Custos
Hiểu điều bạn sắp ký.
SDK phân tích giao dịch trước khi ký cho ví và dApp Solana.
Thấy thay đổi tài sản. Hiểu quyền được trao. Kiểm tra bằng chứng.
Mở demo · Thử như người dùng: SolBonus · Trang Tích hợp · SDK · Tài liệu
Số dư chưa đổi. Quyền kiểm soát có thể đã khác.
Một giao dịch không cần chuyển token ngay để tạo ra rủi ro. Trong ca đổi chủ nhóm dựng trên Devnet, tài khoản vẫn có 490 token, nhưng mô phỏng cho thấy quyền chủ tài khoản sẽ chuyển sang địa chỉ khác nếu giao dịch được thực thi.
Custos đưa những thay đổi đó đến trước bước ký. Ví hoặc dApp gọi SDK; người dùng nhận được thay đổi tài sản, thay đổi quyền, lý do cảnh báo và phạm vi đã phân tích. Dữ kiện có thể mở để kiểm tra thêm.
Bản thử nghiệm Devnet. Kết quả mô phỏng phụ thuộc dữ kiện, trạng thái chain và phạm vi hỗ trợ. Không có cờ đỏ không phải bảo đảm an toàn.
Thử trong 2 phút — không cần cài, không cần khoá
Custos nằm trong ví, không phải trang quét link. Một dApp bất kỳ xin chữ ký qua chuẩn Wallet Standard. Ví đã tích hợp Custos mô phỏng đúng giao dịch đó, giải thích hậu quả và để người dùng quyết định trước khi ví ký (ADR-0004).
- Mở SolBonus → Kết nối ví. Cửa sổ Ví Custos bật lên; bấm Cho kết nối và giữ cửa sổ đó mở.
- Ở SolBonus, bấm Tìm token DEMO trên Devnet, rồi Nhận 1.000 SOLB. Cửa sổ ký của Ví Custos mô phỏng đúng giao dịch SolBonus gửi và hiện Nguy hiểm: một nửa token rời đi, và chủ tài khoản token đổi sang địa chỉ khác.
- Bấm Chặn giao dịch — SolBonus không nhận được chữ ký nào.
- Mở Phòng phân tích để so các tình huống bên dưới, và Inspector để xem 10 giao dịch mainnet thật.
Danh sách tình huống đầy đủ nằm trong registry kịch bản.
| Tình huống | Điều cần quan sát |
|---|
| Đổi chủ tài khoản token | Quyền thay đổi dù token chưa rời tài khoản |
| Approve 1.010 token, số dư 490 | Luật vượt số dư kích hoạt |
| Approve 250 token, số dư 490 | Ca đối chứng không kích hoạt luật vượt số dư; vẫn cần xét ý định người ký |
| Thiếu dữ kiện hoặc RPC lỗi | Hiển thị trạng thái không kiểm tra đủ; bên tích hợp không được tự chuyển sang ký |
Mọi bề mặt của sản phẩm
Bản phụ trên GitHub Pages: neitln.github.io/Custos-Solana. Địa chỉ cũ custos-solana.vercel.app và solbonus-custos.vercel.app/tan-cong/ vẫn chạy song song.
Bản công khai không nhúng khóa ký. Tình trạng AI phụ thuộc cấu hình backend của từng bản triển khai: lượt AI thật trong bản ghi local không đồng nghĩa mọi demo public đều đã bật AI. Giao diện phân biệt nguồn diễn giải; khi không dùng mô hình, có câu tất định dự phòng.
Custos làm gì?
- Phân tích hậu quả: đọc thay đổi số dư, owner, delegate và các dữ kiện hỗ trợ từ mô phỏng.
- Cảnh báo có lý do: engine luật trả mức cảnh báo, mã lý do và bằng chứng liên quan.
- Nói rõ phần chưa hiểu: trả coverage và giới hạn phân tích để người dùng biết phạm vi kết quả.
- Diễn giải bằng tiếng Việt: dùng câu tất định hoặc mô hình ngôn ngữ tùy chọn qua adapter.
- Tích hợp trước bước ký: SDK phục vụ đội ví/dApp; người hưởng lợi là người ký giao dịch.
- Nằm trong luồng ký của ví: connector Wallet Standard (
packages/connector) đưa yêu cầu signTransaction của mọi dApp vào cửa sổ ví. Ở đó Custos kiểm trước, người dùng quyết định, và ví đối chiếu kết quả thật với dự báo sau khi giao dịch chạy.
Kiến trúc: quan sát → đánh giá → diễn giải
flowchart LR
TX["Giao dịch chưa ký"] --> L1["L1 · Mô phỏng và đọc trạng thái"]
RPC["Solana Devnet RPC"] --> L1
L1 --> F["Facts · thay đổi và phạm vi"]
F --> L2["L2 · Engine luật"]
L2 --> V["Verdict · reason codes · evidence"]
F --> L3["L3 · Diễn giải"]
L2 --> L3
AI["Mô hình tùy chọn"] -.-> L3
V --> UI["Giao diện review"]
L3 --> UI
UI --> C["Ứng dụng tích hợp · chính sách và consent"]
C --> S["Signer của ví"]
| Thành phần | Trách nhiệm |
|---|
| Core / L1 | Mô phỏng qua RPC, bóc tách dữ kiện trong phạm vi hỗ trợ |
| Core / L2 | Áp luật để sinh level, lý do và bằng chứng |
| AI / L3 | Diễn giải facts; có câu tất định khi không dùng mô hình |
| Ứng dụng tích hợp | Hiển thị, áp chính sách, lấy xác nhận và kiểm nội dung trước khi gọi signer |
AI không tạo hoặc sửa level. Ranh giới được thể hiện trong hợp đồng dữ liệu, cách ghép kết quả và các kiểm tra đầu ra; không chỉ dựa vào prompt. Phần diễn giải vẫn có thể sai và cần được đánh giá riêng.
Vì sao Solana? Custos cần hiểu account, instruction và quyền SPL Token mà giao dịch tác động tới. Solana cung cấp trạng thái và môi trường thực thi; Custos dùng RPC simulation để quan sát trước khi broadcast. Phân tích chạy off-chain, hiện không có smart contract Custos riêng.
Điểm kỹ thuật đáng xem
Mỗi dòng trỏ tới chỗ trong mã để tự kiểm, không cần tin lời mô tả.
| Điểm | Ở đâu trong mã | Kiểm bằng |
|---|
Verdict tất định. level chỉ do engine luật L2 sinh ra; kiểu dữ liệu L3 trả về không có trường level | l2/rules.ts · inspect.ts | npm run check |
Fail-safe. Mô phỏng hỏng, account không đo được, hoặc lệnh không đọc hiểu chạm tài sản người ký thì tối thiểu Cần xem kỹ, không bao giờ safe | l2/evaluate.ts | failsafe.test.ts |
| AI có rào. Câu diễn giải qua bộ kiểm đầu ra; AI không đổi được mức cảnh báo, có câu tất định khi không dùng mô hình | packages/ai/src/moHinh.ts | Đánh giá AI |
Kiểm đúng giao dịch dApp gửi. Connector Wallet Standard đưa signTransaction vào cửa sổ ví; ví mô phỏng chính giao dịch đó trước khi người dùng quyết định | packages/connector · ket-noi.tsx | Luồng SolBonus ở trên |
| Dự báo ↔ thực tế. Sau khi ký trên Devnet, ví đối chiếu thay đổi thật trên chain với điều Custos đã dự báo |
Chạy tại máy
Dùng Node 24.12.x và npm 11.6.2 theo .nvmrc và package.json. Trên Windows, có thể chọn Node bằng trình quản lý phiên bản bạn đang dùng; nvm use 24.12.0 nếu dùng nvm-windows.
git clone https://github.com/NeitLN/Custos-Solana.git
cd Custos-Solana
npx [email protected] ci
npx [email protected] run check # typecheck + 1397 test
npm run vi
Mở http://localhost:5188. Trong terminal thứ hai, chạy trang dApp minh họa:
npm run tan-cong
Mở http://localhost:5189. Địa chỉ hiện trường Devnet có sẵn trong hien-truong.json; không cần khóa API mô hình để chạy luồng diễn giải tất định.
| Lệnh | Mục đích | Cần mạng? |
|---|
npm run check | Typecheck và bộ test | Có với một số ca CLI gọi RPC; các ca còn lại chạy cục bộ |
npm run replay-rpc | Kiểm L1 bằng phản hồi RPC đã lưu | Không |
npm run doi-khang | Các probe đối kháng | Không |
npm run thu-tich-hop:deterministic | Kiểm consumer với fixture | Không |
npm run mo-phong-kichban | Mô phỏng các kịch bản trên Devnet | Có, RPC |
npm run thu-tich-hop:devnet | Kiểm lượt tích hợp live | Có, RPC |
npm run thu-goi | Đóng gói và cài SDK từ ngoài monorepo | Có, npm registry |
RPC công cộng có thể chậm hoặc giới hạn yêu cầu. Một lượt live lỗi mạng không tự chứng minh engine phát hiện sai; kiểm nguyên nhân và đối chiếu với replay offline.
Tích hợp SDK
Bắt đầu từ hướng dẫn Core và consumer mẫu. Đoạn dưới minh họa lời gọi phân tích, không phải luồng ký hoàn chỉnh:
import { inspect } from "@custos-solana/core";
import { boiThoiHan, dienGiaiKhongAI } from "@custos-solana/ai";
// connection: kết nối Devnet; transaction: giao dịch chưa ký.
// Lấy địa chỉ người dùng từ ví, không tin giá trị dApp tự khai.
const result = await inspect(
{ connection, interpret: boiThoiHan(dienGiaiKhongAI) },
transaction,
{ locale: "vi", nguoiDung: walletPublicKey.toBase58() },
);
Trước khi nối với signer, ứng dụng phải xử lý timeout/lỗi, mức cảnh báo, aiAdvisory, coverage và việc giao dịch có thay đổi sau khi kiểm hay không. Không tự động ký chỉ vì result.level === "safe". Xem hợp đồng ký trong consumer và threat model.
Bằng chứng kỹ thuật
Các số sau là snapshot đã lưu, không phải cam kết hiệu năng hay độ chính xác trên mọi giao dịch. Nguồn: so-lieu.json, báo cáo kiểm chứng và quy cách dataset.
| Phạm vi | Kết quả đã lưu |
|---|
| Luật đã chạy | 14 — 12 theo đặc tả, cộng 2 luật sinh từ audit bảo mật |
| Test | 1397, chạy trong npm run check |
| Mẫu trong bộ dữ liệu | 38 — cả 14 luật đều có mẫu kích hoạt; cả 14 luật đều có thêm ca đối chứng gần giống, chỉ khác đúng điều kiện quyết định |
| Giao dịch mainnet thật, phát lại | 10 giao dịch SPL Token thành công liên tiếp, ghi 06/10/2026 vài giây sau khi thực thi, không chọn theo kết quả: 4 Bình thường (không cờ trong phần đọc được) · 6 Cần xem kỹ (4 vì mô phỏng lại hỏng — fail-safe, không bao giờ trả safe) · 0 Nguy hiểm. Dữ liệu · cách ghi |
| Bằng chứng | Chứng minh trong phạm vi nào? | Chưa chứng minh |
|---|
| 1397 test tự động | Các hành vi và bất biến trong bộ kiểm | Chất lượng phát hiện trên traffic thực tế |
| 38 mẫu đã gắn nhãn | Ca kích hoạt và đối chứng của luật | Khả năng khái quát sang tập độc lập |
| Cohort công khai lưu offline | Hành vi trên response đã lưu | Precision/recall; cohort chưa có ground truth |
| 10 giao dịch mainnet phát lại | Engine đọc message mainnet thật; thiếu trạng thái thì báo, không đoán | Luồng ký hay bảo vệ tài sản trên mainnet; tỉ lệ phát hiện — 10 mẫu, chưa có nhãn |
| Ví dụ tích hợp | Consumer do nhóm dựng dùng SDK ngoài monorepo | Adoption hoặc nhu cầu bên thứ ba |
| Đánh giá AI — 13/13 bẫy bị chặn, 3/3 câu đúng đi qua | Bộ guard qua các ca đối kháng đã lưu; có đánh giá với mô hình thật | Mọi câu diễn giải đều đúng hoặc dễ hiểu hơn template |
Bảng đối chiếu rubric theo ADR-0001; trọng số là cách tài liệu đó tổ chức bằng chứng, không phải điểm BGK đã chấm.
| Nhóm tiêu chí | Bằng chứng và nguồn |
|---|
| 30 % độ khó và chiều sâu | 14 luật L2 · 1397 test trong bộ kiểm, một số ca CLI cần RPC · ma trận hành vi |
| 25 % kiến trúc on-chain/off-chain | L1/L2/L3; engine giữ verdict, ứng dụng tích hợp giữ trách nhiệm ký; chưa có contract riêng |
| 25 % Solana stack · hiệu năng | inspect() 639 ms trong phép đo tích hợp đã lưu; ngân sách RPC |
| 20 % demo và trình bày | FCP 88 ms · bấm→thẻ n=30, trung vị 890 ms, p95 quan sát 6005 ms · môi trường và cách đo |
Số giao diện được đo trên Chromium headless; không suy rộng sang thiết bị thật hoặc mọi trình duyệt.
| Đo trên Devnet, 25/09/2026 — lượt pass gần nhất | |
|---|
| Cài đặt → kết quả đầu tiên | 8,4 giây — trung vị 10 lượt trên 9 bản dựng, dải 6,6–13,2 |
| Dòng mã tích hợp | 31 |
| Một lượt kiểm tra | 639 ms — trung vị 10 lượt trên 9 bản dựng |
Consumer này do nhóm dựng; kết quả đo ma sát tích hợp không chứng minh có khách hàng hay đối tác.
Measured, not estimated: 1397 tests and 38 labelled samples in the stored snapshot. These are scoped engineering checks, not an accuracy benchmark.
Giới hạn hiện tại
- Devnet-only: runtime/demo hiện dành cho thử nghiệm; không tuyên bố sẵn sàng bảo vệ tài sản mainnet. Mục mainnet trong Inspector là dữ liệu đã ghi, phát lại offline — ví không mở kết nối mainnet nào.
- Phạm vi đọc hiểu chưa đầy đủ: decoder và Token-2022 còn giới hạn. Coverage là phạm vi phân tích, không phải xác suất giao dịch an toàn.
- Mô phỏng có giới hạn: chỉ phản ánh dữ kiện quan sát được; trạng thái chain có thể thay đổi trước khi gửi giao dịch.
- Tích hợp quyết định hiệu lực: SDK không thể cưỡng chế một consumer cố ý bỏ qua kết quả hoặc ký nội dung khác.
- AI là tùy chọn: có đường tất định dự phòng; chưa có dữ liệu được nhóm xác nhận để kết luận AI cải thiện mức hiểu của người dùng.
- Chưa có validation thị trường được xác nhận: README không sử dụng số phỏng vấn trong tài liệu lịch sử làm traction. Chưa có bên thứ ba tích hợp được xác nhận.
Phụ thuộc và an toàn
npm audit ngày 09/10/2026: 19 lỗ hổng — 19 high · 0 moderate · 0 critical trong snapshot đã lưu (critical duy nhất, shell-quote, đã vá cùng ngày). Phần lớn đi vào qua dApp spike apps/thu-ket-noi, không nằm trong bản deploy — đường đi từng nhóm ở xử trí phụ thuộc.
Xem artifact kiểm phụ thuộc để biết gói và thời điểm đo; đây không phải kết quả audit mới. Chạy node scripts/do-lo-hong.mjs để cập nhật phép đo. Xem tài liệu bảo mật để hiểu các giới hạn trước khi tích hợp. Không đưa khóa ký hoặc khóa API vào frontend, ảnh chụp hay issue công khai.
Bước tiếp theo
- Đánh giá trên tập giao dịch độc lập có nhãn; đo riêng ca bỏ sót và cảnh báo không cần thiết.
- Củng cố endpoint, xử lý lỗi và khả năng quan sát khi chạy live.
- Mở rộng khả năng phân tích theo các ca còn thiếu bằng chứng.
- Tìm đội ví/dApp thử tích hợp và kiểm chứng cách người ký hiểu cảnh báo.
Đây là kế hoạch phát triển, chưa phải cam kết pilot hoặc partnership.
Bản đồ repository
apps/
demo-wallet/ Ví Custos (ví tham chiếu) và cửa sổ ký, Inspector, website, trang số liệu
trang-tan-cong/ SolBonus — dApp độc hại mô phỏng, xin chữ ký qua Wallet Standard
packages/
core/ Mô phỏng, facts, engine luật và API inspect
connector/ Connector Wallet Standard: đưa yêu cầu ký của dApp vào cửa sổ Ví Custos
ai/ Diễn giải tất định, adapter mô hình và kiểm đầu ra
types/ Hợp đồng dữ liệu dùng chung
vi-du-tich-hop/ Consumer kiểm tích hợp ngoài monorepo
scripts/ Kiểm thử, replay, benchmark và đóng gói
data/ Dataset và bằng chứng kỹ thuật
docs/ Đặc tả, threat model, báo cáo và tài liệu pitch
Tài liệu theo nhu cầu
Khi báo lỗi, kèm bước tái hiện, commit, kịch bản, môi trường và kết quả mong đợi/thực tế. Không đính kèm khóa, token truy cập hoặc dữ liệu ví riêng tư.
Custos phát triển cho UniHackfest 2026 · Best Technical Build, theo lựa chọn đã được chủ dự án xác nhận. Track đăng ký trên form lịch sử ngày 24/08 là Best Product & Business; giữ thông tin này để người đọc phân biệt hồ sơ cũ với hướng trình bày hiện tại. Xem ADR đổi hướng và thông tin vòng thi để đối chiếu hồ sơ, không suy tình trạng cập nhật biểu mẫu từ README.
English overview
Custos is a pre-signing transaction-intelligence SDK for Solana wallets and dApps. It simulates transactions, surfaces asset and permission changes, and returns rule-based findings with supporting evidence and analysis coverage.
A Wallet Standard connector puts Custos inside the signing flow: any dApp's signTransaction request opens the Custos Wallet window, which simulates that exact transaction before the user decides. Inspector also replays 10 real mainnet transactions recorded seconds after execution (offline, recorded data — not a mainnet signing flow).
The deterministic engine owns the verdict. An optional language model explains structured facts; a deterministic explanation path remains available. The integrating application handles policy, consent and signing. Current runtime and demo scope is Solana Devnet, with no Custos smart contract and no claim of complete threat detection or confirmed third-party adoption.
We are building Custos for Solana wallet users so they can understand asset and permission changes before signing.
Built by Team Too Hard · MIT License
