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#

  1. Encrypt

    The caller’s device encrypts the input to the enclave’s key.

  2. open
    Open

    The call opens with the hash of the encrypted input.

    price → escrow
  3. Answer

    The enclave runs the model and signs the call, the input hash and the output hash.

    model key
    escrow held
  4. settled
    Settle

    The program checks the signature and writes the receipt.

    escrow → owner, operator, protocol
  5. Verify

    The caller’s device checks the signature, the attestation record and its expiry.

Drawn line: an act by a person or an enclaveCap: what the chain holdsDashed: pending
  1. Choose. The caller picks a live model. The client picks a live, reachable enclave that holds a grant for it.
  2. Encrypt. The input is encrypted on the caller's device to the enclave's encryption key.
  3. 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.
  4. 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.
  5. 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.
  6. 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:

Text
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:

StepValue
Shared secretX25519 between the sender's ephemeral key and the recipient's key
Key derivationHKDF-SHA256, 32 bytes out
Saltsender public key, then recipient public key
Info, inputvoynich/call-input/v1
Info, outputvoynich/call-output/v1
CipherXChaCha20-Poly1305, no associated data

The input is encrypted to the enclave's encryption key. Its plaintext is UTF-8 JSON with two fields:

FieldMeaning
inputThe 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.
outputPublicKeyA 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:

FactMeaning
CallerThe wallet that pays and may refund.
Model, enclaveThe sealed model and the enclave chosen to answer.
Input hashSHA-256 of the input envelope.
EscrowThe model's price at the moment the call opened.
DeadlineThe slot after which the call can be refunded: the opening slot plus the protocol's call deadline, read as callDeadlineSlots from GET /v1/config.
Statusopen, 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:

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

FactMeaning
Call, model, enclaveWhat was called, and which enclave answered.
Input hash, output hashThe two envelope hashes the enclave signed.
SignatureThe enclave's 64-byte Ed25519 signature.
SlotThe slot the call settled in.
PaymentsThe 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.

CheckWhat is comparedWhat it proves
SignatureThe 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 recordThe 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.
ExpiryThe 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 stateMeaning
unavailableThe call settled. There is nothing to refund.
pending-deadlineThe call is open and its deadline has not passed.
refundableThe deadline has passed without a receipt. refund_call returns the escrow.
refundedThe escrow is back with the caller.

Taking a refund is in Refund a call.