call

call sends one input to a sealed model and returns the answer once it has been verified. It chooses the enclave, encrypts the input, opens the call, relays the input, waits for the answer, checks the receipt against the chain and decrypts the output.

TypeScript
import voynich from 'voynich'

const pixels: number[] = new Array(784).fill(0)
const { output, receipt, verified } = await voynich.call('sketch-32', pixels)

Signature#

TypeScript
call(model: string, input: SketchInput | unknown, options?: CallOptions)
FieldMeaning
modelstringrequired

The model's name, such as sketch-32, or its address.

inputSketchInput | unknownrequired

The input, in the form the model's manifest asks for. See Input.

options.onStep(step: CallStep) => void

Called as the call moves through its steps.

options.enclavestring

The enclave that answers, by its address or its signing key. Without it the client takes the first enclave in GET /v1/models/{id}/enclaves that is live and reachable and holds a live grant for the model. That list puts live and reachable enclaves first.

options.signalAbortSignal

Aborts the call. An abort after the price is in escrow leaves a call that settles or becomes refundable.

Input#

For a model whose manifest says inputKind: "sketch", the input is a drawing in any of these forms:

FormShape
Flat array784 numbers, the 28×28 drawing row by row. Also a Float32Array or Float64Array of 784.
Matrix28 rows of 28 numbers.
Strokes{ strokes, width, height }: each stroke is an array of [x, y] points inside a canvas of width by height pixels, at most 4,194,304 pixels in all.

Pixel values run from 0 (background) to 1 (ink). Every form goes through preprocessSketch, which crops the drawing to its ink, scales the longer side to 24 pixels keeping the aspect, and centers it in 28×28, as the manifest of sketch-32 describes. Strokes are drawn 3 pixels wide before that.

For a model whose manifest says inputKind: "tensor", the input is a flat array of numbers in the order of the manifest's inputShape, as many as its dimensions multiply to.

What comes back#

FieldMeaning
outputunknown

The decrypted answer. For a sketch model: { label, scores }, where scores is the five most probable labels as { label, probability }, highest first, and label is the first of them.

receiptReceipt

The call's receipt: its address, the call, the model and its name, the enclave, both hashes, the signature, the slot, the settling transaction and the payments. The fields are in HTTP API: Calls and receipts.

verifiedboolean

True when all three checks passed. call throws instead of returning an answer whose checks failed.

checks{ signature, record, expiry }

The result of each check, as booleans. What each proves is in Calls and receipts.

fixtureboolean

False against a cluster. True only against an API in fixture mode, where verified is false.

Steps#

TypeScript
const result = await voynich.call('sketch-32', drawing, {
  onStep: step => console.log(step),
})
StepWhat has happened
encryptingA live, reachable enclave holding a live grant is chosen, the one in options.enclave when it is given. The client has read the Config, the Model, the Enclave, its attestation record and its Grant from the chain and found the record in force, the measurement allowed and the grant active. Only then is the input encrypted to the enclave's key.
awaiting-signatureThe transaction that opens the call is built and waiting for the wallet.
escrowedThe call is open on chain with the price in escrow.
answeringThe encrypted input is with the enclave.
verifiedThe answer is back, the receipt passed its checks and the output is decrypted.

The wallet signs once, at awaiting-signature.

Failures#

call throws a VoynichError with a code. After the price is in escrow the error also carries the call and its refundState.

CodeWhen
WALLET_REQUIREDThe client has no signer.
ENCLAVE_UNAVAILABLENo live, reachable enclave holds a live grant for the model, or the enclave named in options.enclave is not one.
ENCLAVE_MISMATCHWith options.enclave: the enclave on chain is not the one named.
PROGRAM_MISMATCHThe API names a program other than the one the SDK is built for.
INVALID_CHAIN_ACCOUNTThe Config, the Model or the Enclave is missing on chain or is not owned by the program.
MODEL_MISMATCHThe accounts on chain are not the model and enclave that were asked for.
MODEL_NOT_LIVEThe model is not live.
INVALID_ATTESTATIONThe enclave's record is at the wrong address, has the wrong owner or layout, names another key, is expired, or states a measurement the model does not allow.
GRANT_REQUIREDThe enclave has no active grant for the model on chain.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction that opens the call did not land. Nothing is in escrow.
CALL_FAILED, or the failure's own codeThe call did not settle. refundState says whether it can be refunded yet.
INVALID_ANSWERThe answer is missing its envelope, hash, signature, receipt or transaction.
RECEIPT_MISMATCHThe answer or the receipt belongs to another call, input, model or enclave.
VERIFICATION_FAILEDA check on the receipt failed. The message says which part.
CALL_INTERRUPTED, or an API error codeThe connection or the API failed after escrow. refundState is pending-deadline, or refundable for CALL_DEADLINE_PASSED.

A failure before the wallet signs can also be an ApiClientError with an API error code, such as MODEL_NOT_FOUND, or an Error from preprocessSketch for an input that is not a drawing.

TypeScript
import { createVoynich, VoynichError } from 'voynich'

const voynich = createVoynich({ apiUrl: 'https://<api host>', signer: wallet })

try {
  const { output } = await voynich.call('sketch-32', drawing)
} catch (error) {
  if (error instanceof VoynichError && error.call && error.refundState === 'refundable') {
    await voynich.refund(error.call.address)
  } else throw error
}

What it costs#

The model's price, the transaction fee of open_call and the rent of the Call account. See Fees and the token.