Calls and receipts
A call is one input sent to one sealed model, paid for once. A receipt is what the call leaves on chain: which model answered, inside which enclave, to which input, with which output, and who was paid.
The path of a call#
- Encrypt
The caller’s device encrypts the input to the enclave’s key.
- openOpen
The call opens with the hash of the encrypted input.
price → escrow - Answer
The enclave runs the model and signs the call, the input hash and the output hash.
model keyescrow held - settledSettle
The program checks the signature and writes the receipt.
escrow → owner, operator, protocol - Verify
The caller’s device checks the signature, the attestation record and its expiry.
- Choose. The caller picks a live model. The client picks a live, reachable enclave that holds a grant for it.
- Encrypt. The input is encrypted on the caller's device to the enclave's encryption key.
- Open. The caller signs
open_call. The model's price moves into the call's escrow, and the call records the hash of the encrypted input and a deadline. - Answer. The enclave decrypts the input, runs the model, encrypts the output to the caller and signs the call, the input hash and the output hash.
- Settle. The enclave sends
settle_call. The program checks the signature against the enclave's recorded key, writes the receipt and pays out the escrow. - Verify. The client decrypts the output and checks the receipt before it shows the answer.
What is encrypted#
The input and the output each travel as an envelope:
0x01 (1 byte)
ephemeral X25519 public key of the sender (32 bytes)
XChaCha20 nonce (24 bytes)
ciphertext with its Poly1305 tag (16 bytes)An envelope is at least 73 bytes. Its key is derived for that one envelope:
| Step | Value |
|---|---|
| Shared secret | X25519 between the sender's ephemeral key and the recipient's key |
| Key derivation | HKDF-SHA256, 32 bytes out |
| Salt | sender public key, then recipient public key |
| Info, input | voynich/call-input/v1 |
| Info, output | voynich/call-output/v1 |
| Cipher | XChaCha20-Poly1305, no associated data |
The input is encrypted to the enclave's encryption key. Its plaintext is UTF-8 JSON with two fields:
| Field | Meaning |
|---|---|
input | The model's input. For a sketch model: 784 numbers from 0 to 1, the 28×28 drawing row by row, background 0 and ink 1. For a tensor model: a flat array of numbers in the order of the manifest's inputShape, as many as its dimensions multiply to. |
outputPublicKey | A fresh X25519 public key, base64, that the caller made for this call. The enclave encrypts the answer to it. |
Only the enclave reads the input. Only the holder of the fresh key reads the output. The relay that carries both sees envelopes.
The input hash is the SHA-256 of the envelope's bytes: the serialized envelope, not its base64 text and not the JSON inside it. The output hash is taken the same way over the output envelope.
The call on chain#
open_call creates a Call account:
| Fact | Meaning |
|---|---|
| Caller | The wallet that pays and may refund. |
| Model, enclave | The sealed model and the enclave chosen to answer. |
| Input hash | SHA-256 of the input envelope. |
| Escrow | The model's price at the moment the call opened. |
| Deadline | The slot after which the call can be refunded: the opening slot plus the protocol's call deadline, read as callDeadlineSlots from GET /v1/config. |
| Status | open, settled or refunded. |
A call reads as refundable when it is still open and the current slot is past its deadline.
What the enclave signs#
The enclave signs exactly these 114 bytes with its Ed25519 signing key:
UTF-8 "voynich/receipt/v1" (18 bytes)
call address (32 bytes)
SHA-256 of the input envelope (32 bytes)
SHA-256 of the output envelope (32 bytes)There are no separators and no length prefixes. The signing key exists only inside the enclave, and the chain holds its attestation record.
The receipt#
settle_call carries the signature. The program verifies it in the same transaction through the Ed25519 precompile, against the key in the enclave's record, and refuses an enclave whose record has expired. Then, in one instruction, it writes the Receipt and pays the escrow to the owner, the operator and the protocol share. The split is told in Fees and the token.
| Fact | Meaning |
|---|---|
| Call, model, enclave | What was called, and which enclave answered. |
| Input hash, output hash | The two envelope hashes the enclave signed. |
| Signature | The enclave's 64-byte Ed25519 signature. |
| Slot | The slot the call settled in. |
| Payments | The mint, the total, and the amount and recipient for the owner, the operator and the protocol share. |
A receipt is found by its own address, by its call's address, or by the signature of the settling transaction.
What the checks prove#
A client runs three checks before it shows an answer. Anyone can run them later from the receipt alone.
| Check | What is compared | What it proves |
|---|---|---|
| Signature | The receipt's signature over the call address, input hash and output hash, against the enclave's signing key. The caller also hashes the envelopes it sent and received and compares them with the receipt's hashes. | This enclave key answered this input with this output. |
| Attestation record | The signing key against the key in the enclave's attestation record, and the record's measurement against the model's allowed measurements. | The chain recorded that key under the configured attestation program, running software the owner allowed. |
| Expiry | The record's recorded slot ≤ the receipt's slot < the record's expiry slot. | The record was in force when the call settled. A record that expires later leaves the receipt valid. |
Running them by hand is in Verify a receipt.
Refunds#
A call that has no receipt when its deadline passes is refunded with refund_call. The full escrow returns to the caller. The caller can send it, and the protocol's crank sends it for calls nobody collects.
While a call waits or after it fails, its refund state is one of:
| Refund state | Meaning |
|---|---|
unavailable | The call settled. There is nothing to refund. |
pending-deadline | The call is open and its deadline has not passed. |
refundable | The deadline has passed without a receipt. refund_call returns the escrow. |
refunded | The escrow is back with the caller. |
Taking a refund is in Refund a call.