Relay

One route carries a call's input to the enclave that answers it. The input travels as an envelope encrypted to the enclave's key on the caller's device, and the answer returns as an envelope encrypted to a key only the caller holds. The byte layout of both is in What is encrypted.

POST /v1/calls/{id}/input#

Sends the encrypted input of an open call to the call's enclave. {id} is the Call account's address, the addresses.call of the Build from POST /v1/calls/build. Send it once the open_call transaction is confirmed.

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

{
  "envelope": "<input envelope, base64>"
}
FieldMeaning
envelopeenveloperequired

The complete input envelope as padded base64: at least 73 bytes, the first byte 1. Its SHA-256 is the inputHash the call was opened with.

Response:

FieldMeaning
calladdressrequired

The call the enclave took the input for.

statusstringrequired

Always accepted: the enclave holds the input and is answering.

Sending the same envelope again while the enclave is answering, or after it answered, returns accepted again and starts nothing new.

CodeStageWhen
VALIDATION_ERRORvalidation{id} is not an address, or envelope is not a version 1 envelope in padded base64.
CALL_NOT_FOUNDreadNo call has this address. A call opened a moment ago reads this way until the API has indexed its transaction: send again.
INPUT_HASH_MISMATCHuploadThe SHA-256 of the envelope's bytes is not the call's inputHash.
ENCLAVE_NOT_FOUNDreadThe API holds no enclave for the call's enclave.
INVALID_ENVELOPEuploadThe enclave that received the input is not the one the call names.
CALL_NOT_OPENuploadThe call already settled or was refunded.
CALL_DEADLINE_PASSEDuploadThe current slot is past the call's deadlineSlot.
UPSTREAM_UNAVAILABLEreadThe enclave did not answer within 60 seconds, or did not accept the call. Retryable. Check the call's deadline before sending again.

The errors every POST route shares are in Overview.

Next: read the answer at GET /v1/calls/{id}/answer.

The path of the envelope#

  1. The caller encrypts

    On the caller's device the input and a fresh output public key are encrypted to the enclave's encryptionKey, read from GET /v1/models/{id}/enclaves. The SHA-256 of the envelope goes on chain in open_call.

  2. The API checks the hash

    The API reads the call, hashes the envelope it received and compares the hash with the call's inputHash. An envelope that differs is refused with INPUT_HASH_MISMATCH and goes no further.

  3. The API forwards

    The API posts the same body to the call's enclave, at the enclave's endpoint followed by its relayPath with the call's address in it.

  4. The enclave checks the call

    The enclave reads the Call account from the chain and takes the input when the call names this enclave, the envelope hashes to the call's input hash, the call is open and its deadline is ahead. Then it answers accepted.

  5. The enclave answers

    Inside the enclave the input is decrypted and the model runs. The output is encrypted to the caller's output key, the enclave signs the call's address with both hashes, and it sends settle_call, which writes the receipt and pays out the escrow.

  6. The answer returns

    GET /v1/calls/{id}/answer asks the enclave for what it holds for the call and returns it with the call's state: the output envelope, its hash, the enclave's signature, the settling transaction and the receipt's address.

What the relay sees#

The relay
seesThe call's address, the input envelope and the output envelope as ciphertext, both hashes, the enclave's signature, and what the chain shows of the call: caller, model, enclave, price.
cannot readThe input, the output key inside the input envelope, and the output. The input opens only with the enclave's encryption key, the output only with the secret half of the caller's output key.
cannot changeThe input: the API and the enclave each compare the envelope with the hash the caller escrowed on chain. The output: its hash is in the message the enclave signs and in the receipt, and the caller compares the envelope it received with it.

The caller's checks on the answer are in What the checks prove.