--- title: "Kiến trúc Cosigner" description: "Kiến trúc Cosigner: các thành phần, kênh truyền tải, ranh giới tin cậy và vòng đời phiên MPC." url: https://docs.fystack.io/vi/cosigner/architecture last_updated: 2026-11-13 --- > ## Documentation index > Fetch the complete documentation index at: https://docs.fystack.io/llms.txt > Use it to discover all available pages before exploring further. # Kiến trúc Cosigner Thành phần nào chạy ở đâu, các phần giao tiếp với nhau như thế nào, và một phiên được điều phối ra sao. _Diagram: Tổng quan kiến trúc Cosigner_ ## Các thành phần ### Cosigner runtime Một binary Go duy nhất, được phát hành dưới dạng `ghcr.io/fystack/cosigner` cho `linux/amd64` và `linux/arm64`. Nó tham gia các phiên, nhưng không điều phối chúng. - **MPC engine**: Bản fork của Fystack từ [tss-lib](https://github.com/bnb-chain/tss-lib), giống như MPCium. ECDSA sử dụng GG18 trên secp256k1. EdDSA sử dụng Ed25519 ngưỡng của tss-lib. - **Khóa định danh**: Ed25519, được tạo khi ghép nối. Dùng để xác thực cosigner và ký các message của nó. - **Kho khóa**: Các bản ghi được mã hóa AES-256-GCM trong SQLite (mặc định), Badger hoặc DynamoDB. - **Gateway relay**: Một luồng gRPC hướng ra ngoài. Gửi tín hiệu hiện diện mỗi 5 giây. - **Approval client**: Gọi [approval callback](https://docs.fystack.io/cosigner/approval-callback.md) của bạn trước mỗi phiên. - **Nhật ký kiểm toán**: JSONL được ký và liên kết chuỗi băm. ### Các dịch vụ của bạn - **cosigner-cli**: Cài đặt, xác minh, ghép nối, khởi động và sao lưu runtime. - **Approval callback**: Máy chủ HTTPS của bạn. Trả về `approve` hoặc `reject`. - **Nguồn khóa lưu trữ**: Mật khẩu (profile `manual`) hoặc AWS KMS (profile `unattended`). ### Các dịch vụ của Fystack - **Apex**: Cấp token ghép nối, đăng ký khóa cosigner, xử lý thu hồi, gửi các yêu cầu MPC. - **Gateway**: Tiếp nhận luồng từ cosigner, kiểm tra định danh và trạng thái thu hồi, chuyển tiếp lưu lượng sang NATS. Mỗi cosigner chỉ có một luồng đang hoạt động trên tất cả các replica. - **Orchestrator**: Chạy máy trạng thái của phiên và ký mọi message điều khiển. Không bao giờ chạm vào phần khóa (key share). - **MPCium**: Các node MPC của Fystack. Xem [MPCium](https://docs.fystack.io/mpcium.md). ## Các kênh | Từ → đến | Truyền tải | Xác thực | Nội dung | | --- | --- | --- | --- | | Cosigner → Apex | HTTPS | Token ghép nối dùng một lần | Đăng ký định danh | | Cosigner ↔ Gateway | Luồng gRPC, TLS | EdDSA JWT, thời hạn 60 giây | Toàn bộ lưu lượng của phiên | | Gateway ↔ Orchestrator ↔ MPCium | NATS | Ed25519 cho từng message | Điều phối bên trong Fystack | | Bên tham gia ↔ bên tham gia | Chuyển tiếp | X25519 + ChaCha20-Poly1305 | Các vòng MPC, mã hóa đầu cuối | | Cosigner → Callback | HTTPS | RS256 JWT ở cả hai chiều | Phê duyệt hoặc từ chối | ### Phong bì luồng Mỗi frame mang theo `workspace_id`, `cosigner_id` và `participant_id` đã được xác thực. Gateway loại bỏ các frame không khớp với định danh của luồng. | Loại | Chiều | Subject | | --- | --- | --- | | `CONTROL` | Orchestrator → cosigner | `mpc.v1.peer..control` | | `SESSION_EVENT` | Cosigner → orchestrator | `mpc.v1.session..event` | | `P2P` | Bên tham gia ↔ bên tham gia | `mpc.v1.peer..session..p2p` | | `PRESENCE` | Cosigner → orchestrator | `mpc.v1.peer..presence` | ## Ranh giới tin cậy - **Gateway**: Chuyển tiếp bản mã. Có thể loại bỏ hoặc làm chậm lưu lượng, nhưng không thể đọc hoặc giả mạo message MPC. - **Orchestrator**: Ký mọi message điều khiển bằng một khóa mà cosigner đã ghim (pin) khi ghép nối. Các message không được ký hoặc ký sai sẽ bị loại bỏ. - **Apex**: Không thể bỏ qua callback của bạn. Mọi phiên đều được gửi đến callback của bạn trước. - **Cosigner của bạn**: Không thể ký một mình. Hội đồng ký được cố định từ lúc tạo khóa. Chi tiết trong [Mô hình bảo mật](https://docs.fystack.io/cosigner/security.md). ## Phiên Mỗi lần tạo khóa, ký hoặc chia sẻ lại khóa là một phiên orchestrator với TTL 120 giây. _Diagram: Các trạng thái phiên: created, waiting, key_exchange, active_mpc, completed, cùng với failed và expired_ 1. **Tiếp nhận**: Orchestrator xác minh chữ ký của Apex, kiểm tra hội đồng ký và xác nhận mọi bên tham gia đều đang trực tuyến. Mỗi ví và giao thức chỉ có một phiên tại một thời điểm. 2. **waiting**: Các bên tham gia nhận `session_start` đã được ký, chạy các kiểm tra cục bộ (cosigner gọi callback của bạn) và phản hồi `peer_joined`, `peer_ready`. 3. **key_exchange**: Các bên tham gia trao đổi các khóa X25519 đã được ký. Những ví có người phê duyệt cũng cần phê duyệt đã ký của người đó ở bước này. 4. **active_mpc**: Orchestrator gửi `mpc_begin`. Các bên tham gia chạy trực tiếp các vòng tss-lib. 5. **completed**: Tất cả các bên tham gia báo cáo cùng một mã băm kết quả. Orchestrator ký và công bố kết quả. Một phiên sẽ **thất bại** khi một bên tham gia gặp lỗi, mất kết nối hoặc kết quả không khớp, và sẽ **hết hạn** sau 120 giây. Trong cả hai trường hợp, orchestrator đều phát đi một `session_abort` đã được ký. ### Hội đồng ký Ngưỡng `t` nghĩa là cần `t + 1` bên ký (theo ngữ nghĩa của tss-lib). Hội đồng gồm các node MPCium và cosigner được cố định từ lúc tạo khóa. Mọi phiên sau đó phải sử dụng cùng các khóa của bên tham gia, khóa định danh và vai trò người phê duyệt. ### Kết nối - Mỗi định danh cosigner chỉ có một luồng đang hoạt động. Một instance thứ hai với cùng định danh sẽ bị từ chối. - Mỗi phiên được gắn với luồng đang hoạt động tại thời điểm phiên bắt đầu. Nếu luồng đó bị ngắt, phiên sẽ thất bại với `PARTICIPANT_DISCONNECTED`. - Một cosigner bị thu hồi sẽ nhận `PermissionDenied` và dừng lại.