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.

FieldMeaning
addressaddressrequired

The Model account.

namestringrequired

The model's name, 1 to 32 characters.

owneraddressrequired

The wallet that created the model.

createdSlotslotrequired

The slot the model was created in.

sealedSlotslot or nullrequired

The slot the model was sealed in. null while it is uploading.

sizeBytesintegerrequired

Bytes of ciphertext.

plaintextSizeBytesintegerrequired

Bytes of the weights before encryption.

ciphertextSha256hash or nullrequired

The SHA-256 of the complete ciphertext. null while the model is uploading.

cipherobjectrequired
allowedMeasurementsarray of measurementsrequired

The enclave measurements that may hold the model's key. At least one.

priceMoneyrequired

The price of one call, as a Money.

operatorShareBpsinteger, 0 to 10000required

The operator's share of the price, in basis points.

protocolShareBpsinteger, 0 to 10000, or nullrequired

The protocol share from the Config, in basis points. The same value as in GET /v1/config.

statusstringrequired

uploading: 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.

manifestobjectrequired
weightsarray of Weightsrequired

The model's Weights accounts, in order.

uploadobject or nullrequired

The upload of the ciphertext. null when the model records no upload key.

enclavesHoldingintegerrequired

Grants for this model that are not revoked and whose enclave's attestation record is unexpired.

callsSettleddecimal stringrequired

Calls to this model that settled.

Cipher header#

FieldMeaning
idstringrequired

Always xchacha20poly1305-64k-v1.

chunkSizeBytesintegerrequired

Always 65536.

noncePrefixbase64 of 16 bytesrequired

The nonce prefix of this model's chunks.

The chunking and the nonce of each chunk are in The cipher.

Manifest#

FieldMeaning
namestringrequired

The model's name.

inputKindstringrequired

sketch or tensor. What a caller sends for each is in What is encrypted.

inputShapearray of positive integersrequired

The shape of the input tensor. At least one dimension.

labelsarray of stringsrequired

The names of the model's outputs, in order. At least one.

inputNamestring

The name of the ONNX input.

outputNamestring

The name of the ONNX output.

preprocessstring

How 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.

FieldMeaning
addressaddressrequired

The Weights account.

modeladdressrequired

The model it belongs to.

indexintegerrequired

Its place in the model's list, from 0.

offsetintegerrequired

Where this account's first ciphertext byte sits in the model's ciphertext.

sizeBytesintegerrequired

Ciphertext bytes this account holds.

writtenRangesarray of byte rangesrequired

The ranges written so far, each { offset, length } counted from the start of this account's ciphertext.

Upload#

FieldMeaning
uploadKeyaddressrequired

The key that signs the writes.

bytesWrittenintegerrequired

Ciphertext bytes written across all Weights accounts.

transactionsWrittenintegerrequired

write_weights transactions that landed for this model.

writtenRangesarray of byte rangesrequired

The 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.

closedbooleanrequired

false while the model is uploading. From sealing on, the model's upload is null.

GET /v1/models#

Lists models, one page at a time.

FieldMeaning
sortstring

calls: most settled calls first. newest: latest created first. price: lowest price amount first. calls when omitted. Models that tie are ordered by address.

cursorstring
limitinteger, 1 to 100

24 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.

CodeWhen
MODEL_NOT_FOUNDNo model has this name or address.
PROGRAM_REFUSEDThe 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.

FieldMeaning
offsetinteger, 0 or more

The first byte of the range, counted from the start of the model's ciphertext. 0 when omitted.

lengthinteger, 1 to 1048576

Bytes to read. 256 when omitted.

Response:

FieldMeaning
modeladdressrequired

The Model account.

offsetintegerrequired

The first byte returned.

lengthintegerrequired

Bytes returned. Less than the length asked for when the range runs past the end of the ciphertext.

totalBytesintegerrequired

The model's sizeBytes.

bytesBase64base64required

The bytes of the range.

accountsarray of Weightsrequired

The Weights accounts the range was read from.

CodeWhen
VALIDATION_ERRORoffset is past the end of the ciphertext, or length is outside 1 to 1,048,576.
UPSTREAM_UNAVAILABLEA 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.

FieldMeaning
itemsarrayrequired

One object per grant: enclave, an Enclave, and grant, a Grant.

asOftimestamprequired

When 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.

HTTP
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>"]
  }
}
FieldMeaning
sizeBytesinteger, 17 to 83885632required

Bytes of ciphertext: the weights' length plus 16 bytes for every 65,536 bytes of it, the last partial chunk included.

createobject

The 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.

FieldMeaning
fixturebooleanrequired

false for a quote read from a cluster.

asOfSlotslotrequired

The slot the rent and the fees were read at.

sizeBytesintegerrequired

The sizeBytes asked for.

writeChunkBytesintegerrequired

Always 512: the ciphertext bytes one write carries.

writeCountintegerrequired

The write_weights transactions the upload takes.

modelAccountBytesintegerrequired

Always 6000: the size of the Model account.

modelRentLamportsamountrequired

The rent-exempt minimum of the Model account.

weightsarrayrequired

One 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).

weightsRentLamportsamountrequired

The rent of all Weights accounts.

uploadKeyMinimumLamportsamountrequired

The rent-exempt minimum of an account with no data, which the upload key holds until sealing.

signaturesPerTransactionobjectrequired

The signatures each kind of transaction carries: allocation, createModel, write and seal.

allocationFeeLamportsamountrequired

The fee of one transaction that creates a Weights account.

allocationFeesLamportsamountrequired

That fee for every Weights account.

createFeeLamportsamountrequired

The fee of the create_model transaction.

writeFeeLamportsamountrequired

The fee of one write_weights transaction.

writeFeesLamportsamountrequired

That fee for every write.

sealFeeLamportsamountrequired

The fee of the seal_model transaction.

uploadFundingLamportsamountrequired

The uploadFundingLamports to send in POST /v1/models/build: writeFeesLamports plus returnedUploadReserveLamports.

returnedUploadReserveLamportsamountrequired

What the upload key still holds after its last write, which the sealing transaction returns to the owner: uploadKeyMinimumLamports plus sealFeeLamports.

estimatedCostLamportsamountrequired

What the sealing costs: the Model's rent, the Weights accounts' rent and the fees of every allocation, the creation, every write and the sealing.

requiredUpfrontLamportsamountrequired

What the owner's wallet needs before the sealing starts: estimatedCostLamports plus returnedUploadReserveLamports.

createTransactionBytesinteger or nullrequired

The size in bytes of the create_model transaction built from create, its signatures included. null without create.

createTransactionMaxBytesintegerrequired

Always 1104: the largest transaction a build returns, 1,232 bytes less the 128 bytes left for what the wallet adds. See Signing.

manifestBytesinteger or nullrequired

The size of the manifest as the Model stores it. null without create.

canCreateboolean or nullrequired

true when createTransactionBytes is at most createTransactionMaxBytes and manifestBytes is at most 4,096. null without create.

CodeWhen
VALIDATION_ERRORsizeBytes 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_UNAVAILABLEThe 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.

HTTP
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>"
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and signs.

uploadKeyaddressrequired

A fresh key the owner's device holds. It signs this transaction and every write.

weightsarray of 1 to 8 addressesrequired

The Weights accounts, in the order of the ciphertext.

namestringrequired

The model's name, 1 to 32 characters. The same as manifest.name.

manifestobjectrequired
sizeBytesinteger above 0required

Bytes of ciphertext. The ciphertext space of the Weights accounts adds up to it.

plaintextSizeBytesinteger above 0required

Bytes of the weights before encryption.

cipherobjectrequired
priceMoneyrequired

The price of one call. All four fields of Money are sent; the transaction carries amount and mint.

operatorShareBpsinteger, 0 to 10000required

The operator's share of the price, in basis points.

allowedMeasurementsarray of measurementsrequired

At least one. The program takes 1 to 8.

uploadFundingLamportsamountrequired

Lamports 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.

CodeWhen
VALIDATION_ERRORname 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_FUNDSThe owner holds fewer lamports than the Model's rent, uploadFundingLamports and the fee.
SIMULATION_FAILEDThe 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.

HTTP
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>"
}
FieldMeaning
walletaddressrequired

The model's upload key. It pays the fee and is the only signer.

offsetinteger, 0 or morerequired

Where 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 charactersrequired

1 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.

CodeWhen
VALIDATION_ERRORThe bytes are more than 512, or the range offset to offset + bytes does not lie inside one Weights account.
MODEL_NOT_UPLOADINGThe model is sealed.
INSUFFICIENT_FUNDSThe upload key holds fewer lamports than the write's fee.
SIMULATION_FAILEDwallet 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.

HTTP
POST /v1/models/sketch-32/seal/build
Content-Type: application/json

{
  "wallet": "<owner address>",
  "ciphertextSha256": "<sha-256 of the complete ciphertext, 64 hex characters>"
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and signs.

ciphertextSha256hashrequired

The 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.

CodeWhen
MODEL_NOT_UPLOADINGThe model is already sealed.
UPLOAD_INCOMPLETENot every ciphertext byte is written.
CIPHERTEXT_HASH_MISMATCHciphertextSha256 is not the SHA-256 of the bytes on chain.
SIMULATION_FAILEDwallet 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.

HTTP
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>
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and signs.

priceMoneyrequired

The new price. All four fields of Money are sent; the transaction carries amount and mint, with mint: null for SOL.

operatorShareBpsinteger, 0 to 10000required

The operator's share of the price, in basis points.

The Build's action is set_price. Its addresses hold model.

CodeWhen
SIMULATION_FAILEDwallet 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.

HTTP
POST /v1/models/sketch-32/grant/build
Content-Type: application/json

{
  "wallet": "<owner address>",
  "enclave": "<enclave address>",
  "wrappedKey": "<105-byte envelope, base64>"
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and the Grant's rent, and signs.

enclaveaddressrequired

The Enclave account that receives the grant.

wrappedKeywrapped keyrequired

The 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.

CodeWhen
ENCLAVE_NOT_FOUNDNo Enclave account has the address in enclave.
MODEL_NOT_LIVEThe model is uploading or retired.
ENCLAVE_EXPIREDThe enclave's attestation record is invalid or expired.
MEASUREMENT_NOT_ALLOWEDThe enclave's measurement is not in the model's allowedMeasurements.
INSUFFICIENT_FUNDSThe owner holds fewer lamports than the fee and, for a Grant that does not exist yet, its rent.
SIMULATION_FAILEDwallet 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.

HTTP
POST /v1/models/sketch-32/revoke/build
Content-Type: application/json

{
  "wallet": "<owner address>",
  "enclave": "<enclave address>"
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and signs.

enclaveaddressrequired

The Enclave account whose grant is revoked.

The Build's action is revoke_grant. Its addresses hold model.

CodeWhen
GRANT_REQUIREDNo Grant account exists for this model and the address in enclave. Stage build.
SIMULATION_FAILEDwallet 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.

HTTP
POST /v1/models/sketch-32/retire/build
Content-Type: application/json

{
  "wallet": "<owner address>"
}
FieldMeaning
walletaddressrequired

The owner. It pays the fee and signs.

The Build's action is retire_model. Its addresses hold model.

CodeWhen
SIMULATION_FAILEDwallet is not the model's owner (Unauthorized).