Calling from an agent
An autonomous agent can call any live sealed model on Voynich with its own funded Solana keypair, verify the returned on-chain Receipt before trusting the model's answer, and pass the receipt id downstream so any other service or human can verify the exact inference independently.
The worked Node.js example lives at backend/sdk/examples/agent-caller.mjs (with a quick reference in backend/sdk/examples/README.md).
Running the example#
Fund a 64-byte Solana JSON keypair with SOL for call fees and Call account rent, then run the script from the backend/ workspace:
VOYNICH_KEYPAIR=./agent.json \
VOYNICH_MODEL=sketch-32 \
VOYNICH_ANSWER_MODE=open \
node sdk/examples/agent-caller.mjsOn PowerShell:
$env:VOYNICH_KEYPAIR = ".\agent.json"
$env:VOYNICH_MODEL = "sketch-32"
$env:VOYNICH_ANSWER_MODE = "open"
node sdk/examples/agent-caller.mjsEnvironment variables#
| Variable | Required | Default | Meaning |
|---|---|---|---|
VOYNICH_KEYPAIR | yes | Path to a 64-byte Solana JSON keypair file funded for call fees and rent. | |
VOYNICH_API_URL | no | https://api.voynich.dev | Voynich HTTP API base URL. |
VOYNICH_SITE_URL | no | https://voynich.dev | Web base URL used when formatting receiptUrl and accountUrl. |
VOYNICH_MODEL | no | sketch-32 | Live model slug or address to call. |
VOYNICH_ANSWER_MODE | no | open | open (stores plaintext answer bytes in the on-chain Receipt) or sealed (encrypted to the caller). |
REPORT_WEBHOOK_URL | no | Optional HTTP(S) endpoint that receives the verified JSON report via POST. |
Call, verify, then act#
agent-caller.mjs builds a voynich client from the keypair, runs client.call, and runs an independent on-chain client.verify pass before producing a report or touching REPORT_WEBHOOK_URL:
import { readFile } from 'node:fs/promises'
import { resolve } from 'node:path'
import { Keypair } from '@solana/web3.js'
import { createVoynich } from 'voynich'
const secret = JSON.parse(await readFile(resolve(process.env.VOYNICH_KEYPAIR), 'utf8'))
const signer = Keypair.fromSecretKey(Uint8Array.from(secret))
const client = createVoynich({
apiUrl: process.env.VOYNICH_API_URL || 'https://api.voynich.dev',
signer,
})
const result = await client.call('sketch-32', drawing, { answerMode: 'open' })
const verification = await client.verify(result.receipt.address)
if (verification.verified !== true) {
throw new Error(`Receipt verification failed: ${verification.reason || 'checks did not pass'}`)
}Pass a custom Solana Connection to createVoynich({ apiUrl, signer, connection }) when your agent should read the Receipt and attestation accounts through its own RPC node independently of the API.
Enforcing all four checks#
Never act on result.output or forward a webhook unless verification.verified === true. That flag requires all four checks in verification to pass:
| Check | What it proves |
|---|---|
signature | The enclave's Ed25519 key signed the 114-byte voynich/receipt/v1 message binding the Call address, input_hash, and output_hash. |
record | That signing key sits in an on-chain attestation record owned by the configured attestation program, with a measurement the model allows. |
expiry | The settling slot sits inside the attestation record's valid slot window (recordedSlot <= slot < expiresAtSlot). |
answer | For an open receipt, the raw on-chain Receipt.open_answer bytes hash (SHA-256) to output_hash. For a sealed receipt, no open bytes are stored and the check passes. |
In agent-caller.mjs, any failed check throws before stdout output or REPORT_WEBHOOK_URL delivery and exits with status 1.
Forwarding the receipt downstream#
Once all four checks pass, agent-caller.mjs prints a JSON report to stdout and, when REPORT_WEBHOOK_URL is set, POSTs the same JSON body with content-type: application/json:
{
"agent": "<agent-wallet-pubkey>",
"model": "sketch-32",
"answerMode": "open",
"output": {
"label": "clock",
"probability": 0.97
},
"receiptAddress": "<receipt-pda>",
"receiptUrl": "https://voynich.dev/receipts/<receipt-pda>",
"accountUrl": "https://voynich.dev/account?wallet=<agent-wallet-pubkey>",
"slot": "419284102",
"transactionSignature": "<settle-tx-signature>",
"verified": true,
"checks": {
"signature": true,
"record": true,
"expiry": true,
"answer": true
}
}agentaddressrequiredBase58 public key of the agent keypair that paid for and opened the call.
modelstringrequiredModel slug returned on the verified Receipt.
answerMode'open' | 'sealed'requiredAnswer mode recorded on the Receipt.
outputunknownrequiredModel output returned by client.call.
receiptAddressaddressrequiredCanonical Receipt PDA on Solana. Downstream services pass this id to client.verify(receiptAddress) or GET /v1/receipts/{id} without needing the agent's keypair.
receiptUrlstringrequiredDirect link to the receipt verification page at /receipts/<receiptAddress>.
accountUrlstringrequiredDirect link to the agent wallet's account view at /account?wallet=<agent>.
slotdecimal stringrequiredSolana slot the call settled in.
transactionSignaturesignaturerequiredSolana transaction signature of settle_call.
verifiedtruerequiredAlways true in an emitted report; any failure aborts non-zero before emitting.
checks{ signature, record, expiry, answer }requiredBoolean outcome of each of the four verification checks.
A downstream consumer does not need to trust the agent's report body on its own: passing report.receiptAddress to verify(report.receiptAddress) (SDK, CLI, or /receipts/<receiptAddress>) re-runs all four checks directly against Solana and, for open calls, reads the signed answer bytes straight from the on-chain Receipt.
Inspecting an agent's calls and receipts#
Every call opened by the agent's keypair appears under its public key in two places:
- Web: open
https://voynich.dev/account?wallet=<agent-wallet-pubkey>(or /account) to see the agent's calls, settled receipts, and any refundable expired calls. - HTTP API: call
GET /v1/accounts/{wallet}(orclient.account(agentPubkey)in the SDK) to fetch the agent wallet'scallsarray, each carrying itsstatus,receiptaddress,answerMode, andrefundState.
Read next#
Every option, input shape, step callback and error code for calling a sealed model.
SDK: verifyRe-verify any receipt address or transaction signature from a downstream service.
HTTP API: Accounts and statsRead an agent wallet's calls and receipts programmatically via GET /v1/accounts/{wallet}.