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.

Tổng quan kiến trúc Cosigner
Click to open the full-size diagram

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, 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 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.

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.<participant_id>.control
SESSION_EVENT Cosigner → orchestrator mpc.v1.session.<session_id>.event
P2P Bên tham gia ↔ bên tham gia mpc.v1.peer.<to>.session.<session_id>.p2p
PRESENCE Cosigner → orchestrator mpc.v1.peer.<participant_id>.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.

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.

Các trạng thái phiên: created, waiting, key_exchange, active_mpc, completed, cùng với failed và expired
Click to open the full-size diagram
  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.