Models
Five routes read models, one quotes the cost of sealing, and seven build the transactions that create and change a model. What a sealed model is on chain is told in Sealed models.
In every path, {id} is the model's account address or its name, such as sketch-32. The errors every route shares are in Overview.
Model#
The object the read routes return for one model.
addressaddressrequiredThe Model account.
namestringrequiredThe model's name, 1 to 32 characters.
owneraddressrequiredThe wallet that created the model.
createdSlotslotrequiredThe slot the model was created in.
sealedSlotslot or nullrequiredThe slot the model was sealed in. null while it is uploading.
sizeBytesintegerrequiredBytes of ciphertext.
plaintextSizeBytesintegerrequiredBytes of the weights before encryption.
ciphertextSha256hash or nullrequiredThe SHA-256 of the complete ciphertext. null while the model is uploading.
cipherobjectrequiredThe cipher header.
allowedMeasurementsarray of measurementsrequiredThe enclave measurements that may hold the model's key. At least one.
priceMoneyrequiredThe price of one call, as a Money.
operatorShareBpsinteger, 0 to 10000requiredThe operator's share of the price, in basis points.
protocolShareBpsinteger, 0 to 10000, or nullrequiredThe protocol share from the Config, in basis points. The same value as in GET /v1/config.
statusstringrequireduploading: created, its ciphertext being written. sealed: complete, its hash fixed. live: granted to a first enclave, taking calls. retired: closed to new calls and new grants. What changes each is in Statuses.
manifestobjectrequiredThe manifest.
weightsarray of WeightsrequiredThe model's Weights accounts, in order.
uploadobject or nullrequiredThe upload of the ciphertext. null when the model records no upload key.
enclavesHoldingintegerrequiredGrants for this model that are not revoked and whose enclave's attestation record is unexpired.
callsSettleddecimal stringrequiredCalls to this model that settled.
Cipher header#
idstringrequiredAlways xchacha20poly1305-64k-v1.
chunkSizeBytesintegerrequiredAlways 65536.
noncePrefixbase64 of 16 bytesrequiredThe nonce prefix of this model's chunks.
The chunking and the nonce of each chunk are in The cipher.
Manifest#
namestringrequiredThe model's name.
inputKindstringrequiredsketch or tensor. What a caller sends for each is in What is encrypted.
inputShapearray of positive integersrequiredThe shape of the input tensor. At least one dimension.
labelsarray of stringsrequiredThe names of the model's outputs, in order. At least one.
inputNamestringThe name of the ONNX input.
outputNamestringThe name of the ONNX output.
preprocessstringHow a raw input becomes the tensor.
The API returns the manifest whole. The fields a sketch manifest leaves out on chain are filled in with the sketch defaults, as told in The manifest on chain.
Weights#
One account that holds a part of the ciphertext.
addressaddressrequiredThe Weights account.
modeladdressrequiredThe model it belongs to.
indexintegerrequiredIts place in the model's list, from 0.
offsetintegerrequiredWhere this account's first ciphertext byte sits in the model's ciphertext.
sizeBytesintegerrequiredCiphertext bytes this account holds.
writtenRangesarray of byte rangesrequiredThe ranges written so far, each { offset, length } counted from the start of this account's ciphertext.
Upload#
uploadKeyaddressrequiredThe key that signs the writes.
bytesWrittenintegerrequiredCiphertext bytes written across all Weights accounts.
transactionsWrittenintegerrequiredwrite_weights transactions that landed for this model.
writtenRangesarray of byte rangesrequiredThe ranges written so far, each { offset, length } counted from the start of the model's ciphertext. An upload resumes at the first byte outside them.
closedbooleanrequiredfalse while the model is uploading. From sealing on, the model's upload is null.
GET /v1/models#
Lists models, one page at a time.
sortstringcalls: most settled calls first. newest: latest created first. price: lowest price amount first. calls when omitted. Models that tie are ordered by address.
cursorstringSee Pagination.
limitinteger, 1 to 10024 when omitted.
Returns a page whose items are Model objects.
Next: read one model with GET /v1/models/{id}, or its enclaves with GET /v1/models/{id}/enclaves.
GET /v1/models/{id}#
Reads one model with its manifest, its Weights accounts and the progress of its upload.
Returns a Model.
| Code | When |
|---|---|
MODEL_NOT_FOUND | No model has this name or address. |
PROGRAM_REFUSED | The Model account holds a manifest that is not a valid manifest, or a price mint that is not an SPL Token mint. message says which. |
The three routes below that read under /v1/models/{id} return the same two codes.
GET /v1/models/{id}/weights#
Reads a range of the model's ciphertext, as it sits on chain.
offsetinteger, 0 or moreThe first byte of the range, counted from the start of the model's ciphertext. 0 when omitted.
lengthinteger, 1 to 1048576Bytes to read. 256 when omitted.
Response:
modeladdressrequiredThe Model account.
offsetintegerrequiredThe first byte returned.
lengthintegerrequiredBytes returned. Less than the length asked for when the range runs past the end of the ciphertext.
totalBytesintegerrequiredThe model's sizeBytes.
bytesBase64base64requiredThe bytes of the range.
accountsarray of WeightsrequiredThe Weights accounts the range was read from.
| Code | When |
|---|---|
VALIDATION_ERROR | offset is past the end of the ciphertext, or length is outside 1 to 1,048,576. |
UPSTREAM_UNAVAILABLE | A Weights account could not be read from the cluster. Retryable. |
Next: read the following range with offset raised by length, until offset reaches totalBytes. The SHA-256 of all of it equals the model's ciphertextSha256.
GET /v1/models/{id}/enclaves#
Lists every grant for the model with the enclave it was made to. Revoked grants and enclaves whose record has expired are included. The items are in the order of GET /v1/enclaves: live and reachable enclaves first.
asOftimestamprequiredWhen the API assembled the response.
The list is whole, without pages.
Next: to open a call, pick an item whose enclave.status is live, whose enclave.reachable is true and whose grant.status is live, and pass enclave.address to POST /v1/calls/build.
GET /v1/models/{id}/receipts#
Lists the model's receipts, latest settling slot first. It takes cursor and limit as in Pagination.
Returns a page whose items are Receipt objects.
Next: read one with its attestation record at GET /v1/receipts/{id}.
POST /v1/models/quote#
Computes what sealing a model of a given ciphertext size costs, from the cluster's rent and the fees of the transactions a sealing sends. With the model's create metadata in create, it also measures the create_model transaction and says whether it fits. It builds nothing, signs nothing and needs no Weights account to exist.
POST /v1/models/quote
Content-Type: application/json
{
"sizeBytes": <ciphertext bytes>,
"create": {
"wallet": "<owner address>",
"uploadKey": "<upload key address>",
"weights": ["<Weights account address>"],
"name": "<model name>",
"manifest": { "name": "<model name>", "inputKind": "<sketch or tensor>", "inputShape": [<dimension>], "labels": ["<label>"] },
"plaintextSizeBytes": <plaintext bytes>,
"cipher": { "id": "xchacha20poly1305-64k-v1", "chunkSizeBytes": 65536, "noncePrefix": "<16 bytes, base64>" },
"price": { "amount": "<base units>", "mint": null, "decimals": 9, "symbol": "SOL" },
"operatorShareBps": <0 to 10000>,
"allowedMeasurements": ["<96 hex characters>"]
}
}sizeBytesinteger, 17 to 83885632requiredBytes of ciphertext: the weights' length plus 16 bytes for every 65,536 bytes of it, the last partial chunk included.
createobjectThe body of POST /v1/models/build without sizeBytes and uploadFundingLamports. weights holds 1 to 8 addresses, the ones the Weights accounts will have, and name equals manifest.name. The quote measures the transaction with its own uploadFundingLamports.
Response. Every amount is in lamports.
fixturebooleanrequiredfalse for a quote read from a cluster.
asOfSlotslotrequiredThe slot the rent and the fees were read at.
sizeBytesintegerrequiredThe sizeBytes asked for.
writeChunkBytesintegerrequiredAlways 512: the ciphertext bytes one write carries.
writeCountintegerrequiredThe write_weights transactions the upload takes.
modelAccountBytesintegerrequiredAlways 6000: the size of the Model account.
modelRentLamportsamountrequiredThe rent-exempt minimum of the Model account.
weightsarrayrequiredOne object per Weights account, in order: index, payloadBytes (the ciphertext bytes it holds), accountBytes (payloadBytes plus the 56-byte header), rentLamports (its rent-exempt minimum) and writeCount (the writes that fill it).
weightsRentLamportsamountrequiredThe rent of all Weights accounts.
uploadKeyMinimumLamportsamountrequiredThe rent-exempt minimum of an account with no data, which the upload key holds until sealing.
signaturesPerTransactionobjectrequiredThe signatures each kind of transaction carries: allocation, createModel, write and seal.
allocationFeeLamportsamountrequiredThe fee of one transaction that creates a Weights account.
allocationFeesLamportsamountrequiredThat fee for every Weights account.
createFeeLamportsamountrequiredThe fee of the create_model transaction.
writeFeeLamportsamountrequiredThe fee of one write_weights transaction.
writeFeesLamportsamountrequiredThat fee for every write.
sealFeeLamportsamountrequiredThe fee of the seal_model transaction.
uploadFundingLamportsamountrequiredThe uploadFundingLamports to send in POST /v1/models/build: writeFeesLamports plus returnedUploadReserveLamports.
returnedUploadReserveLamportsamountrequiredWhat the upload key still holds after its last write, which the sealing transaction returns to the owner: uploadKeyMinimumLamports plus sealFeeLamports.
estimatedCostLamportsamountrequiredWhat the sealing costs: the Model's rent, the Weights accounts' rent and the fees of every allocation, the creation, every write and the sealing.
requiredUpfrontLamportsamountrequiredWhat the owner's wallet needs before the sealing starts: estimatedCostLamports plus returnedUploadReserveLamports.
createTransactionBytesinteger or nullrequiredThe size in bytes of the create_model transaction built from create, its signatures included. null without create.
createTransactionMaxBytesintegerrequiredAlways 1104: the largest transaction a build returns, 1,232 bytes less the 128 bytes left for what the wallet adds. See Signing.
manifestBytesinteger or nullrequiredThe size of the manifest as the Model stores it. null without create.
canCreateboolean or nullrequiredtrue when createTransactionBytes is at most createTransactionMaxBytes and manifestBytes is at most 4,096. null without create.
| Code | When |
|---|---|
VALIDATION_ERROR | sizeBytes is outside 17 to 83,885,632, or a field of create does not match its schema, create.name differing from create.manifest.name among them. |
UPSTREAM_UNAVAILABLE | The cluster's RPC returned no rent or no fee. Retryable. |
Next: when canCreate is true, create the Weights accounts at the addresses in create.weights, then build the model with POST /v1/models/build.
Builds#
The seven routes below each return a Build: an unsigned transaction and the addresses it creates. Sign it and send it through POST /v1/transactions/submit. Signing, the order of signatures and the errors every build shares are in Transactions.
Each build route can return MODEL_NOT_FOUND (except POST /v1/models/build), INSUFFICIENT_FUNDS, SIMULATION_FAILED and PROGRAM_REFUSED as told in Errors from a build. The tables below list what each adds.
POST /v1/models/build#
Builds create_model: the Model in uploading, its Weights accounts bound to it, and the upload funding moved to the upload key.
The Weights accounts exist before this call: each is owned by the voynich program and holds 56 bytes of header plus its share of the ciphertext. See Where the ciphertext sits.
POST /v1/models/build
Content-Type: application/json
{
"wallet": "<owner address>",
"uploadKey": "<upload key address>",
"weights": ["<Weights account address>"],
"name": "<model name>",
"manifest": {
"name": "<model name>",
"inputKind": "<sketch or tensor>",
"inputShape": [<dimension>, <dimension>],
"labels": ["<label>", "<label>"]
},
"sizeBytes": <ciphertext bytes>,
"plaintextSizeBytes": <plaintext bytes>,
"cipher": {
"id": "xchacha20poly1305-64k-v1",
"chunkSizeBytes": 65536,
"noncePrefix": "<16 bytes, base64>"
},
"price": { "amount": "<base units>", "mint": null, "decimals": 9, "symbol": "SOL" },
"operatorShareBps": <0 to 10000>,
"allowedMeasurements": ["<96 hex characters>"],
"uploadFundingLamports": "<lamports>"
}walletaddressrequiredThe owner. It pays the fee and signs.
uploadKeyaddressrequiredA fresh key the owner's device holds. It signs this transaction and every write.
weightsarray of 1 to 8 addressesrequiredThe Weights accounts, in the order of the ciphertext.
namestringrequiredThe model's name, 1 to 32 characters. The same as manifest.name.
manifestobjectrequiredThe manifest.
sizeBytesinteger above 0requiredBytes of ciphertext. The ciphertext space of the Weights accounts adds up to it.
plaintextSizeBytesinteger above 0requiredBytes of the weights before encryption.
cipherobjectrequiredThe cipher header.
priceMoneyrequiredThe price of one call. All four fields of Money are sent; the transaction carries amount and mint.
operatorShareBpsinteger, 0 to 10000requiredThe operator's share of the price, in basis points.
allowedMeasurementsarray of measurementsrequiredAt least one. The program takes 1 to 8.
uploadFundingLamportsamountrequiredLamports moved from the owner to the upload key, which pays the fee of every write from them. POST /v1/models/quote returns the amount for a ciphertext size.
The Build's action is create_model. Its addresses hold model, weights and uploadKey. Its requiredSigners are the owner and the upload key.
| Code | When |
|---|---|
VALIDATION_ERROR | name differs from manifest.name; weights is missing or empty (fieldErrors.weights); a Weights account does not exist or is not owned by the program; the accounts' ciphertext space does not add up to sizeBytes. |
INSUFFICIENT_FUNDS | The owner holds fewer lamports than the Model's rent, uploadFundingLamports and the fee. |
SIMULATION_FAILED | The program refused the model or its Weights accounts (InvalidModel, InvalidWeights), or the name is taken. programError names the error. |
Next: submit, then write the ciphertext with POST /v1/models/{id}/write/build.
POST /v1/models/{id}/write/build#
Builds write_weights: one piece of ciphertext into the model's Weights accounts.
POST /v1/models/sketch-32/write/build
Content-Type: application/json
{
"wallet": "<upload key address>",
"offset": <byte offset in the model's ciphertext>,
"bytesBase64": "<up to 512 bytes, base64>"
}walletaddressrequiredThe model's upload key. It pays the fee and is the only signer.
offsetinteger, 0 or morerequiredWhere the bytes go, counted from the start of the model's ciphertext. The API turns it into the offset inside the Weights account that holds it.
bytesBase64base64, 4 to 684 charactersrequired1 to 512 bytes of ciphertext. The whole write lies inside one Weights account.
The Build's action is write_weights. Its addresses hold model, weights (the one account written) and uploadKey.
| Code | When |
|---|---|
VALIDATION_ERROR | The bytes are more than 512, or the range offset to offset + bytes does not lie inside one Weights account. |
MODEL_NOT_UPLOADING | The model is sealed. |
INSUFFICIENT_FUNDS | The upload key holds fewer lamports than the write's fee. |
SIMULATION_FAILED | wallet is not the model's upload key (Unauthorized), or the write is empty or ends past the account's size (InvalidWrite). |
Next: submit, and write the following range. upload.writtenRanges of GET /v1/models/{id} shows what has landed. When every byte is written, seal.
POST /v1/models/{id}/seal/build#
Builds seal_model, which fixes the ciphertext hash, followed by a transfer of the upload key's remaining lamports back to the owner.
POST /v1/models/sketch-32/seal/build
Content-Type: application/json
{
"wallet": "<owner address>",
"ciphertextSha256": "<sha-256 of the complete ciphertext, 64 hex characters>"
}walletaddressrequiredThe owner. It pays the fee and signs.
ciphertextSha256hashrequiredThe SHA-256 of the complete ciphertext, as the owner's device computed it.
The Build's action is seal_model. Its addresses hold model and uploadKey. Its requiredSigners are the owner and the upload key, which signs the transfer.
| Code | When |
|---|---|
MODEL_NOT_UPLOADING | The model is already sealed. |
UPLOAD_INCOMPLETE | Not every ciphertext byte is written. |
CIPHERTEXT_HASH_MISMATCH | ciphertextSha256 is not the SHA-256 of the bytes on chain. |
SIMULATION_FAILED | wallet is not the model's owner (Unauthorized). |
Next: submit, then grant a first enclave with POST /v1/models/{id}/grant/build.
POST /v1/models/{id}/price/build#
Builds set_price: the price, its mint and the operator share. New calls open at the new values.
POST /v1/models/sketch-32/price/build
Content-Type: application/json
{
"wallet": "<owner address>",
"price": { "amount": "<base units>", "mint": null, "decimals": 9, "symbol": "SOL" },
"operatorShareBps": <0 to 10000>
}walletaddressrequiredThe owner. It pays the fee and signs.
priceMoneyrequiredThe new price. All four fields of Money are sent; the transaction carries amount and mint, with mint: null for SOL.
operatorShareBpsinteger, 0 to 10000requiredThe operator's share of the price, in basis points.
The Build's action is set_price. Its addresses hold model.
| Code | When |
|---|---|
SIMULATION_FAILED | wallet is not the model's owner (Unauthorized), or the operator share plus the protocol share is above 10,000 (InvalidModel). |
POST /v1/models/{id}/grant/build#
Builds grant_by_owner: a Grant that carries the model key wrapped to one enclave. Wrapping is told in Grants.
POST /v1/models/sketch-32/grant/build
Content-Type: application/json
{
"wallet": "<owner address>",
"enclave": "<enclave address>",
"wrappedKey": "<105-byte envelope, base64>"
}walletaddressrequiredThe owner. It pays the fee and the Grant's rent, and signs.
enclaveaddressrequiredThe Enclave account that receives the grant.
wrappedKeywrapped keyrequiredThe model key wrapped on the owner's device to the enclave's encryptionKey: an envelope of 105 bytes.
The Build's action is grant_by_owner. Its addresses hold model.
| Code | When |
|---|---|
ENCLAVE_NOT_FOUND | No Enclave account has the address in enclave. |
MODEL_NOT_LIVE | The model is uploading or retired. |
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 | The owner holds fewer lamports than the fee and, for a Grant that does not exist yet, its rent. |
SIMULATION_FAILED | wallet is not the model's owner (Unauthorized), or the record no longer matches the Enclave account (InvalidEnclave). |
Next: submit. The first grant makes the model live, and GET /v1/models/{id}/enclaves lists the grant.
POST /v1/models/{id}/revoke/build#
Builds revoke_grant, which marks the Grant of one enclave revoked. What a revoked grant stops is told in Grants.
POST /v1/models/sketch-32/revoke/build
Content-Type: application/json
{
"wallet": "<owner address>",
"enclave": "<enclave address>"
}walletaddressrequiredThe owner. It pays the fee and signs.
enclaveaddressrequiredThe Enclave account whose grant is revoked.
The Build's action is revoke_grant. Its addresses hold model.
| Code | When |
|---|---|
GRANT_REQUIRED | No Grant account exists for this model and the address in enclave. Stage build. |
SIMULATION_FAILED | wallet is not the model's owner (Unauthorized). |
Next: submit. GET /v1/models/{id}/enclaves then lists the grant with status revoked.
POST /v1/models/{id}/retire/build#
Builds retire_model, which closes the model to new calls and new grants.
POST /v1/models/sketch-32/retire/build
Content-Type: application/json
{
"wallet": "<owner address>"
}walletaddressrequiredThe owner. It pays the fee and signs.
The Build's action is retire_model. Its addresses hold model.
| Code | When |
|---|---|
SIMULATION_FAILED | wallet is not the model's owner (Unauthorized). |