Wallet Service

Headless, governance-focused wallet service with 2-of-3 MPC threshold signing. Integrates with the Custody Service for key management and supports multi-chain operations across Ethereum, Solana, and Bitcoin.

Service Architecture

ProtocolPortDescription
REST8080External API (Axum)
gRPC50051Internal governance APIs
Metrics9090Prometheus metrics

Authentication

All protected endpoints require:

  • x-tenant-id: Tenant UUID (required)
  • x-user-id: SHA256 hash of user email (for Platform Auth)
  • x-device-id: Device identifier (optional)
  • x-auth-provider: passkey or custom

REST Endpoints

Health

MethodPathDescription
GET/healthBasic health check
GET/health/detailedDetailed health with circuit breaker states

MPC Wallet Operations

MethodPathDescription
GET/api/wallet/meGet or create wallet for authenticated user
GET/api/wallet/public-keyGet wallet's public key for address derivation
POST/api/wallet/signSign transaction using 2-of-3 MPC threshold

Governance Settings

MethodPathDescription
GET/api/wallet/settingsGet wallet governance settings
PUT/api/wallet/settingsUpdate wallet governance settings

Spending Policies

MethodPathDescription
GET/api/wallet/policiesList all spending policies
POST/api/wallet/policiesCreate new spending policy
GET/api/wallet/policies/:policy_idGet specific policy
DELETE/api/wallet/policies/:policy_idDelete policy

Approval Requests

MethodPathDescription
GET/api/wallet/approvalsList approval requests (with status filter)
POST/api/wallet/approvalsCreate new approval request
GET/api/wallet/approvals/:request_idGet approval request details
POST/api/wallet/approvals/:request_id/approveApprove pending request
POST/api/wallet/approvals/:request_id/rejectReject pending request

Address Whitelist

MethodPathDescription
GET/api/wallet/whitelistList whitelisted addresses
POST/api/wallet/whitelistAdd address to whitelist
DELETE/api/wallet/whitelist/:entry_idRemove address from whitelist

Key Holders & Signers

MethodPathDescription
GET/api/wallet/key-holdersList organization's key holders
GET/api/wallet/signersList active signers (2-of-3 MPC info)
GET/api/wallet/signers/:signer_idGet specific signer details

Biometric Authentication

MethodPathDescription
GET/api/wallet/biometric/challengeGet challenge for biometric verification
POST/api/wallet/biometric/verifyVerify biometric signature

WebAuthn Credentials

MethodPathDescription
GET/api/wallet/webauthn/credentialsList user's WebAuthn credentials
POST/api/wallet/webauthn/credentialsStore new WebAuthn credential
GET/api/wallet/webauthn/credentials/:idGet credential details
DELETE/api/wallet/webauthn/credentials/:idDelete WebAuthn credential

Multi-Chain Support

NetworkAddress FormatSDK
Ethereum/EVM0x-prefixed (42 chars)Alloy v1.0
SolanaBase58 encodedSolana SDK 3.x
BitcoinLegacy, SegWit, Bech32bitcoin v0.32

MPC Key Architecture

Wallets use a 2-of-3 threshold MPC scheme with shares distributed across:

ShareLocationPurpose
TEE ShareCustody ServiceHardware-isolated server share
Client SharePasskey/Device PRFUser-controlled biometric share
HSM ShareCloud HSMRecovery backup share

Key Holder Roles

RolePermissions
ownerFull control, all permissions
adminManage settings, policies, whitelist, key holders
approverApprove/reject requests
signerSign transactions
memberView access only

Approval Request Status

StatusDescription
pendingAwaiting approvals
approvedThreshold met
rejectedRequest denied
executedTransaction complete
expired7-day expiry reached

Transaction Types

TypeDescription
transferStandard asset transfer
bridgeCross-chain transfer
contract_callSmart contract interaction

Security Features

  • Biometric challenge expiry: 5 minutes
  • WebAuthn counter verification for replay protection
  • ES256 (P-256 ECDSA) signature verification
  • Privacy-preserving: email hash only, no PII stored
  • Circuit breakers for custody service calls
  • Adaptive rate limiting (GCRA algorithm)