FPSF-MPC-001 — Reference
Layer: Reference · Audience: developers (daily reference) For normative requirements, see the Formal Specification.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/keys | POST | Create a new disposable key pair |
/api/v1/keys | GET | List all active disposable keys for the account |
/api/v1/keys/{key_id} | GET | Get metadata for a single disposable key |
/api/v1/keys/{key_id}/sign | POST | Sign a message with a disposable key |
/api/v1/keys/{key_id} | DELETE | Destroy a disposable key |
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 400 | Malformed request (invalid JSON, not canonical, missing fields) |
| 401 | Signature verification failed |
| 403 | Root key attempted to sign directly; invalid sub key authorization |
| 404 | Key ID not found or not owned by caller |
| 409 | Key already in DESTROYING or DESTROYED state |
| 429 | Rate limit exceeded |
| 500 | Internal error |
| 503 | Insufficient online nodes to complete operation |
Error Codes
| Code | HTTP | Description |
|---|---|---|
INVALID_JSON | 400 | Request body is not valid JSON |
NOT_CANONICAL | 400 | Envelope JSON is not RFC 8785 canonical |
MISSING_FIELD | 400 | Required envelope field absent |
EXPIRED_TIMESTAMP | 401 | Timestamp outside ±5 minute window |
REPLAYED_NONCE | 401 | Nonce has been seen before |
INVALID_SIGNATURE | 401 | Request signature does not verify |
INVALID_AUTHORIZATION | 401 | Authorization token signature does not verify |
SUB_KEY_MISMATCH | 401 | Request signer does not match token sub_key_pub |
ROOT_KEY_SIGNING | 403 | Request signed by a root key directly |
KEY_NOT_FOUND | 404 | Key ID does not exist or belongs to another account |
KEY_DESTROYED | 409 | Key has already been destroyed |
KEY_BEING_DESTROYED | 409 | Destruction is in progress |
INSUFFICIENT_NODES | 503 | Not enough online nodes |
DKG_FAILED | 503 | Key generation failed after retries |
SIGNING_FAILED | 503 | Threshold signing failed |
COORDINATOR_UNAVAILABLE | 503 | Coordinator temporarily unreachable |
INTERNAL_ERROR | 500 | Unexpected internal error |
Disposable Key States
| State | Terminal | Description |
|---|---|---|
ACTIVE | No | Key is available for signing |
SIGNING | No | A signing job is in progress |
DESTROYING | No | Destruction initiated; shares being wiped |
DESTROYED | Yes | All shares wiped; key metadata retained for audit |
Node States
| State | Description |
|---|---|
CONNECTING | WebSocket handshake in progress |
ONLINE | Fully connected; eligible for group assignment |
DEGRADED | Missed 3–4 heartbeats; not assigned to new groups |
OFFLINE | Missed 5+ heartbeats or connection dropped |
REVOKED | Certificate revoked; permanently excluded |
RECONNECTING | Attempting to re-establish connection |
Key Encoding
| Item | Encoding | Length |
|---|---|---|
| Ed25519 public key | base64url, no padding | 32 bytes → 43 chars |
| Ed25519 signature | base64url, no padding | 64 bytes → 86 chars |
| Key ID | UUID v4 | 36 chars |
| Account ID | lowercase hex SHA-256 | 64 chars |
| Nonce | base64url, no padding | 16 bytes → 22 chars |
Default Threshold Parameters
| Parameter | Default | Minimum | Notes |
|---|---|---|---|
threshold_t | 3 | 2 | Single-node signing disallowed |
threshold_n | 5 | t + 1 | At least one redundant node |
Max n | Coordinator policy | — | Recommended 7–15 |
Glossary
| Term | Definition |
|---|---|
| Root Key | Offline Ed25519 key pair. Signs Authorization Tokens only. Never transmitted. |
| Sub Key | Online Ed25519 key pair. Signs all API requests. Authorized by the root key. |
| Disposable Key | Ed25519 key pair generated by MPC DKG. Private scalar never assembled. |
| Node | MPC network participant holding key shares. |
| Coordinator | Central orchestration server. Manages nodes, groups, and jobs. Never holds key material. |
| Group | A temporary set of n nodes assigned to one disposable key. |
| Threshold | The minimum number t of nodes required to sign. |
| DKG | Distributed Key Generation. |
| FROST | Flexible Round-Optimized Schnorr Threshold Signatures. |
| Share | A node's fragment of a distributed private key scalar. |
| Authorization Token | Root key signature certifying a sub key. Presented in every API request. |
| Key ID | UUID v4 assigned by the Coordinator to identify a disposable key. |
| Account ID | SHA-256 hash of the root key public key, hex-encoded. |
| Canonical JSON | JSON serialized per RFC 8785. Required for deterministic signing. |
| VRF | Verifiable Random Function. Used for anti-collusion group selection. |
FPSF-MPC-001 v1.0.0 · Draft · Fabric Payment Standards Foundation · Apache-2.0