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:
| Step | Route |
|---|---|
| Open the call | POST /v1/calls/build, then POST /v1/transactions/submit |
| Send the encrypted input | POST /v1/calls/{id}/input |
| Read the answer | GET /v1/calls/{id}/answer |
| Read the receipt | GET /v1/receipts/{id} |
| Take the escrow back when no answer came | POST /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#
addressaddressrequiredThe Call account.
calleraddressrequiredThe wallet that opened the call and paid its price.
modeladdressrequiredThe model called.
modelNamestringrequiredThe model's name.
enclaveaddressrequiredThe Enclave account chosen to answer.
inputHashhashrequiredThe SHA-256 of the input envelope, as the caller gave it when the call opened.
priceMoneyrequiredThe amount in escrow, as a Money.
openedSlotslotrequiredThe slot the call opened in.
deadlineSlotslotrequiredThe last slot the call can settle in. After it the call can be refunded.
statusstringrequiredopen: 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 nullrequiredThe Receipt account, once the call has settled.
failureCallFailure or nullrequiredA 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#
codestringrequiredOne of the error codes.
messagestringrequiredA sentence that can be shown to a person.
refundStatestringrequiredunavailable: 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.
statusstringrequiredwaiting: the enclave has not answered. answered: the enclave answered and sent settle_call. failed: the call did not settle.
callCallrequiredThe Call as it is now.
outputEnvelopeenvelope or nullrequiredThe output, encrypted to the output key the caller put in the input. See What is encrypted.
outputHashhash or nullrequiredThe SHA-256 of the output envelope's bytes.
signaturereceipt signature or nullrequiredThe enclave's Ed25519 signature over the call's address, the input hash and the output hash. See What the enclave signs.
settleTransactiontransaction signature or nullrequiredThe signature of the settle_call transaction.
receiptAddressaddress or nullrequiredThe Receipt account.
failureCallFailure or nullrequiredWhy the call failed, as a CallFailure.
Receipt#
addressaddressrequiredThe Receipt account.
calladdressrequiredThe call it settles.
modeladdressrequiredThe model that answered.
modelNamestringrequiredThe model's name.
enclaveaddressrequiredThe Enclave account that answered.
inputHashhashrequiredThe SHA-256 of the input envelope.
outputHashhashrequiredThe SHA-256 of the output envelope.
signaturereceipt signaturerequiredThe enclave's 64-byte Ed25519 signature.
slotslotrequiredThe slot the call settled in.
transactionSignaturetransaction signaturerequiredThe signature of the settling transaction.
paymentsobjectrequiredThe payments made at settlement.
Payments#
mintaddress or nullrequiredThe mint paid in. null is SOL.
totalamountrequiredThe sum of the three payments.
ownerobjectrequiredrecipient (address) and amount paid to the model's owner.
operatorobjectrequiredrecipient (address) and amount paid to the enclave's operator.
protocolobjectrequiredrecipient (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.
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>"
}walletaddressrequiredThe caller. It pays the price and the fee, and signs.
modeladdress or namerequiredThe model to call.
enclaveaddressrequiredThe Enclave account that answers. It holds a grant for the model. GET /v1/models/{id}/enclaves lists the candidates, live and reachable ones first.
inputHashhashrequiredThe SHA-256 of the complete input envelope.
noncedecimal string, unsigned 64-bitA 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.
| Code | When |
|---|---|
MODEL_NOT_FOUND | No model has this name or address. |
ENCLAVE_NOT_FOUND | No Enclave account has the address in enclave. |
MODEL_NOT_LIVE | The model is not live. |
GRANT_REQUIRED | The enclave's grant for the model is revoked. |
ENCLAVE_EXPIRED | The enclave's attestation record is invalid or expired. |
MEASUREMENT_NOT_ALLOWED | The enclave's measurement is not in the model's allowedMeasurements. |
INSUFFICIENT_FUNDS | For 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_FAILED | The 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.
| Code | When |
|---|---|
VALIDATION_ERROR | {id} is not an address. |
CALL_NOT_FOUND | No 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.
status | The response holds |
|---|---|
waiting | The output fields as null. The enclave holds no answer for this call. |
answered | outputEnvelope, outputHash, signature, settleTransaction and receiptAddress. |
failed | failure. 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.
| Code | When |
|---|---|
VALIDATION_ERROR | {id} is not an address. |
CALL_NOT_FOUND | No call has this address. |
ENCLAVE_NOT_FOUND | The API holds no enclave for the call's enclave. |
UPSTREAM_UNAVAILABLE | The 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.
POST /v1/calls/<call address>/refund/build
Content-Type: application/json
{
"wallet": "<address that signs and pays the fee>"
}walletaddressrequiredThe 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.
| Code | When |
|---|---|
VALIDATION_ERROR | {id} is not an address. |
CALL_NOT_FOUND | No Call account has this address. |
CALL_NOT_OPEN | The call already settled or was refunded. |
CALL_NOT_REFUNDABLE | The 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.
receiptReceiptrequiredThe Receipt.
enclaveSigningKeyaddressrequiredThe signing key in the enclave's attestation record. The receipt's signature verifies against it.
attestationRecordobjectrequiredThe enclave's attestation record.
attestationProgramIdaddressrequiredThe program that owns the record.
recordLayoutVersioninteger above 0requiredThe record's layout version.
| Code | When |
|---|---|
VALIDATION_ERROR | {id} is neither an address nor a transaction signature. |
RECEIPT_NOT_FOUND | No 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.