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.
import voynich from 'voynich'
const pixels: number[] = new Array(784).fill(0)
const { output, receipt, verified } = await voynich.call('sketch-32', pixels)Signature#
call(model: string, input: SketchInput | unknown, options?: CallOptions)modelstringrequiredThe model's name, such as sketch-32, or its address.
inputSketchInput | unknownrequiredThe input, in the form the model's manifest asks for. See Input.
options.onStep(step: CallStep) => voidCalled as the call moves through its steps.
options.enclavestringThe 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.signalAbortSignalAborts 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:
| Form | Shape |
|---|---|
| Flat array | 784 numbers, the 28×28 drawing row by row. Also a Float32Array or Float64Array of 784. |
| Matrix | 28 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#
outputunknownThe 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.
receiptReceiptThe 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.
verifiedbooleanTrue 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.
fixturebooleanFalse against a cluster. True only against an API in fixture mode, where verified is false.
Steps#
const result = await voynich.call('sketch-32', drawing, {
onStep: step => console.log(step),
})| Step | What has happened |
|---|---|
encrypting | A 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-signature | The transaction that opens the call is built and waiting for the wallet. |
escrowed | The call is open on chain with the price in escrow. |
answering | The encrypted input is with the enclave. |
verified | The 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.
| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
ENCLAVE_UNAVAILABLE | No live, reachable enclave holds a live grant for the model, or the enclave named in options.enclave is not one. |
ENCLAVE_MISMATCH | With options.enclave: the enclave on chain is not the one named. |
PROGRAM_MISMATCH | The API names a program other than the one the SDK is built for. |
INVALID_CHAIN_ACCOUNT | The Config, the Model or the Enclave is missing on chain or is not owned by the program. |
MODEL_MISMATCH | The accounts on chain are not the model and enclave that were asked for. |
MODEL_NOT_LIVE | The model is not live. |
INVALID_ATTESTATION | The 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_REQUIRED | The enclave has no active grant for the model on chain. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The transaction that opens the call did not land. Nothing is in escrow. |
CALL_FAILED, or the failure's own code | The call did not settle. refundState says whether it can be refunded yet. |
INVALID_ANSWER | The answer is missing its envelope, hash, signature, receipt or transaction. |
RECEIPT_MISMATCH | The answer or the receipt belongs to another call, input, model or enclave. |
VERIFICATION_FAILED | A check on the receipt failed. The message says which part. |
CALL_INTERRUPTED, or an API error code | The 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.
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.