Calls and receipts

Five routes open, read and refund calls and read receipts. The sixth route of a call, the one that carries the encrypted input, is on Relay. What a call is and what its receipt proves are told in Calls and receipts.

Over the API a call is made in this order:

StepRoute
Open the callPOST /v1/calls/build, then POST /v1/transactions/submit
Send the encrypted inputPOST /v1/calls/{id}/input
Read the answerGET /v1/calls/{id}/answer
Read the receiptGET /v1/receipts/{id}
Take the escrow back when no answer camePOST /v1/calls/{id}/refund/build

In the paths of calls, {id} is the Call account's address. The errors every route shares are in Overview.

Call#

FieldMeaning
addressaddressrequired

The Call account.

calleraddressrequired

The wallet that opened the call and paid its price.

modeladdressrequired

The model called.

modelNamestringrequired

The model's name.

enclaveaddressrequired

The Enclave account chosen to answer.

inputHashhashrequired

The SHA-256 of the input envelope, as the caller gave it when the call opened.

priceMoneyrequired

The amount in escrow, as a Money.

openedSlotslotrequired

The slot the call opened in.

deadlineSlotslotrequired

The last slot the call can settle in. After it the call can be refunded.

statusstringrequired

open: in escrow, its deadline ahead. settled: answered, with a receipt. refundable: still open on chain with the current slot past deadlineSlot. refunded: the escrow is back with the caller.

receiptaddress or nullrequired

The Receipt account, once the call has settled.

failureCallFailure or nullrequired

A CallFailure with code CALL_DEADLINE_PASSED while the call is refundable (refundState refundable) and once it is refunded (refundState refunded). null while the call is open or settled.

CallFailure#

FieldMeaning
codestringrequired

One of the error codes.

messagestringrequired

A sentence that can be shown to a person.

refundStatestringrequired

unavailable: the call settled. pending-deadline: the call is open and its deadline has not passed. refundable: the deadline has passed without a receipt. refunded: the escrow is back with the caller. See Refunds.

CallAnswer#

What GET /v1/calls/{id}/answer returns.

FieldMeaning
statusstringrequired

waiting: the enclave has not answered. answered: the enclave answered and sent settle_call. failed: the call did not settle.

callCallrequired

The Call as it is now.

outputEnvelopeenvelope or nullrequired

The output, encrypted to the output key the caller put in the input. See What is encrypted.

outputHashhash or nullrequired

The SHA-256 of the output envelope's bytes.

signaturereceipt signature or nullrequired

The enclave's Ed25519 signature over the call's address, the input hash and the output hash. See What the enclave signs.

settleTransactiontransaction signature or nullrequired

The signature of the settle_call transaction.

receiptAddressaddress or nullrequired

The Receipt account.

failureCallFailure or nullrequired

Why the call failed, as a CallFailure.

Receipt#

FieldMeaning
addressaddressrequired

The Receipt account.

calladdressrequired

The call it settles.

modeladdressrequired

The model that answered.

modelNamestringrequired

The model's name.

enclaveaddressrequired

The Enclave account that answered.

inputHashhashrequired

The SHA-256 of the input envelope.

outputHashhashrequired

The SHA-256 of the output envelope.

signaturereceipt signaturerequired

The enclave's 64-byte Ed25519 signature.

slotslotrequired

The slot the call settled in.

transactionSignaturetransaction signaturerequired

The signature of the settling transaction.

paymentsobjectrequired

The payments made at settlement.

Payments#

FieldMeaning
mintaddress or nullrequired

The mint paid in. null is SOL.

totalamountrequired

The sum of the three payments.

ownerobjectrequired

recipient (address) and amount paid to the model's owner.

operatorobjectrequired

recipient (address) and amount paid to the enclave's operator.

protocolobjectrequired

recipient (address) and amount of the protocol share.

How the price divides is in The split.

POST /v1/calls/build#

Builds open_call: a Call account with the model's price in its escrow and the hash of the encrypted input on record.

Before this call, encrypt the input to the enclave's encryptionKey and take the SHA-256 of the envelope's bytes, as told in What is encrypted.

HTTP
POST /v1/calls/build
Content-Type: application/json

{
  "wallet": "<caller address>",
  "model": "<model name or address>",
  "enclave": "<enclave address>",
  "inputHash": "<sha-256 of the input envelope, 64 hex characters>",
  "nonce": "<unsigned 64-bit integer, decimal>"
}
FieldMeaning
walletaddressrequired

The caller. It pays the price and the fee, and signs.

modeladdress or namerequired

The model to call.

enclaveaddressrequired

The Enclave account that answers. It holds a grant for the model. GET /v1/models/{id}/enclaves lists the candidates, live and reachable ones first.

inputHashhashrequired

The SHA-256 of the complete input envelope.

noncedecimal string, unsigned 64-bit

A number the caller has not used before. With the caller it gives the Call its address. The API draws a random one when it is omitted.

Returns a Build. Its action is open_call and its addresses hold model and call, the address of the Call the transaction creates. For a price in a mint, the price leaves the caller's associated token account for that mint.

CodeWhen
MODEL_NOT_FOUNDNo model has this name or address.
ENCLAVE_NOT_FOUNDNo Enclave account has the address in enclave.
MODEL_NOT_LIVEThe model is not live.
GRANT_REQUIREDThe enclave's grant for the model is revoked.
ENCLAVE_EXPIREDThe enclave's attestation record is invalid or expired.
MEASUREMENT_NOT_ALLOWEDThe enclave's measurement is not in the model's allowedMeasurements.
INSUFFICIENT_FUNDSFor a price in SOL: the caller holds fewer lamports than the price, the Call's rent and the fee. For a price in a mint: the caller's associated token account holds less than the price, with funding.mint the mint, or the caller holds fewer lamports than the Call's rent, the rent of a new escrow token account and the fee.
SIMULATION_FAILEDThe transaction failed in simulation for another reason. programError names a program error when there is one.

The codes every build shares are in Errors from a build.

Next: sign and submit the Build, then send the envelope to POST /v1/calls/{id}/input with addresses.call as {id}.

GET /v1/calls/{id}#

Reads one call.

Returns a Call.

CodeWhen
VALIDATION_ERROR{id} is not an address.
CALL_NOT_FOUNDNo call has this address.

A wallet's calls are listed at GET /v1/accounts/{wallet}.

GET /v1/calls/{id}/answer#

Reads the call's answer. Poll it after the input is sent until status leaves waiting, or follow GET /v1/calls/{id}/events.

Returns a CallAnswer.

statusThe response holds
waitingThe output fields as null. The enclave holds no answer for this call.
answeredoutputEnvelope, outputHash, signature, settleTransaction and receiptAddress.
failedfailure. The output fields are null.

The answer is the enclave's: for a call that is open or settled the API asks the call's enclave and returns what it holds, with the call read by the API. For a call that is refundable or refunded the API answers failed itself. Its failure is the call's own: code CALL_DEADLINE_PASSED, with refundState refundable or refunded.

In a failed answer from the enclave, failure.code is ENCLAVE_EXPIRED when the enclave's attestation record expired before it answered, and PROGRAM_REFUSED when the enclave could not complete the call. failure.refundState says where the escrow stands at the moment of the read.

CodeWhen
VALIDATION_ERROR{id} is not an address.
CALL_NOT_FOUNDNo call has this address.
ENCLAVE_NOT_FOUNDThe API holds no enclave for the call's enclave.
UPSTREAM_UNAVAILABLEThe enclave did not answer within 60 seconds, or answered with something that is not an answer. Retryable.

The plaintext of outputEnvelope is UTF-8 JSON with two fields: label, the name of the highest output, and scores, up to five { label, probability } objects, highest first.

Next: decrypt outputEnvelope with the secret half of the output key, then read the receipt and check it. The checks are in Verify a receipt.

POST /v1/calls/{id}/refund/build#

Builds refund_call for a call that passed its deadline without settling. The whole escrow returns to the caller, whoever sends the transaction.

HTTP
POST /v1/calls/<call address>/refund/build
Content-Type: application/json

{
  "wallet": "<address that signs and pays the fee>"
}
FieldMeaning
walletaddressrequired

The wallet that sends the refund. It pays the fee and signs. It can be any wallet; the escrow goes to the call's caller.

Returns a Build. Its action is refund_call and its addresses hold model and call.

CodeWhen
VALIDATION_ERROR{id} is not an address.
CALL_NOT_FOUNDNo Call account has this address.
CALL_NOT_OPENThe call already settled or was refunded.
CALL_NOT_REFUNDABLEThe current slot is not past the call's deadlineSlot.

Next: sign and submit the Build. GET /v1/calls/{id} then reads refunded. The whole task is in Refund a call.

GET /v1/receipts/{id}#

Reads one receipt with what a client needs to check it. {id} is any of three things: the Receipt account's address, the address of its call, or the signature of the settling transaction.

FieldMeaning
receiptReceiptrequired

The Receipt.

enclaveSigningKeyaddressrequired

The signing key in the enclave's attestation record. The receipt's signature verifies against it.

attestationRecordobjectrequired

The enclave's attestation record.

attestationProgramIdaddressrequired

The program that owns the record.

recordLayoutVersioninteger above 0required

The record's layout version.

CodeWhen
VALIDATION_ERROR{id} is neither an address nor a transaction signature.
RECEIPT_NOT_FOUNDNo receipt matches this receipt address, call address or transaction signature.

Next: run the three checks of What the checks prove. A model's receipts are listed at GET /v1/models/{id}/receipts.