Encryption contract
| Element | Contract |
|---|---|
| Key discovery | GET /v2/encryption-key |
| Submission path | POST /v2/request |
| Request payload | Signed request bytes encrypted with operator public key |
| Key material | Per-request secret key and nonce bytes |
Client flow summary
- Serialize the signed request payload to JSON bytes.
- Fetch the operator compressed secp256k1 public key from
GET /v2/encryption-key. - Generate a fresh ephemeral private key and derive the shared secret with ECDH.
- Compute
keccak256(shared_secret)and use the first 16 bytes as the AES-GCM key. - Generate a fresh 12-byte nonce.
- Prefix the plaintext with its 4-byte big-endian length and encrypt with AES-GCM.
- Submit bytes in the order
ciphertext || tag || nonce || client_public_key_compressed.
Wire format
| Segment | Meaning |
|---|---|
ciphertext | AES-GCM encrypted request bytes |
tag | AES-GCM authentication tag |
nonce | 12-byte AES-GCM nonce |
client_public_key_compressed | Ephemeral compressed secp256k1 public key |
Error behavior on submission
| Error reason | Behavior |
|---|---|
InvalidEncryption | Rebuild fresh key material and resubmit |
RateLimit | Retry with backoff when enabled |
SafetyFailure | Return error immediately; fix payload |
ServiceUnavailable | Retry with backoff |
| Other invalid request errors | Return error; do not blind-retry |