seal

seal takes a model's weights and its manifest and leaves a sealed model on chain. The weights are encrypted on the device that calls it. The model key never leaves that device except wrapped to an enclave.

TypeScript
const price = { amount: '100000', mint: null, decimals: 9, symbol: 'SOL' }

const { model, resume } = await voynich.seal({
  weights: onnxBytes,
  manifest,
  price,
  operatorShareBps: 2500,
  allowedMeasurements: [measurement],
  uploadFundingLamports: '5000000',
  grantEnclave: enclave,
  onPrepared: state => save(state),
  onProgress: progress => console.log(progress.step, progress.bytesWritten, progress.totalBytes),
})

Options#

FieldMeaning
weightsUint8Array

The ONNX file's bytes. Required for a new sealing, left out when resuming.

manifestManifestrequired

The model's manifest. Its fields are in Sealed models.

namestring

The model's name. The manifest's name by default. 1 to 32 characters: lowercase letters and digits in groups joined by single hyphens.

priceMoneyrequired

The price of one call: amount in base units as a decimal string, mint (an SPL Token mint address, or null for SOL), and the mint's decimals and symbol.

operatorShareBpsnumberrequired

The operator's share of the price, in basis points, 0 to 10,000. With the protocol share it is at most 10,000.

allowedMeasurementsstring[]required

1 to 8 measurements, each 96 hex characters: the enclave software that may open the model.

uploadFundingLamportsstringrequired

Lamports moved from the owner to the upload key when the model is created. It pays the fees of the upload's transactions: one per 512 bytes of ciphertext. voynich.api.quoteModel({ sizeBytes }) returns the amount as uploadFundingLamports, for a ciphertext of sizeBytes bytes.

grantEnclavestring

An enclave's address or signing key. When given, the sealed model is granted to it and becomes live.

resumeSealResume

The state of a sealing that was interrupted. See Resuming.

onPrepared(resume: SealResume) => void | Promise<void>

Called with the sealing's state before anything is written to chain, and again once the model's address is known. Save the state here.

onProgress(progress: SealProgress) => void

Called as the sealing moves on.

signalAbortSignal

Aborts the sealing. It can be resumed.

What it does#

StepWhat happensSigned by
EncryptA random model key is drawn and the weights are encrypted in 64 KiB chunks. Nothing is sent.nobody
QuotePOST /v1/models/quote with the model's create metadata and the addresses the Weights accounts will have. Unless canCreate is true, the sealing stops with CREATE_MODEL_TOO_LARGE and no account is allocated.nobody
AllocateThe Weights accounts are created: one for every 10,485,704 bytes of ciphertext, at most 8. One transaction each.the owner, once per account
Createcreate_model: the Model exists in uploading and the upload key is funded.the owner
UploadThe ciphertext is written up to 512 bytes per transaction, four transactions at a time.the upload key, with no wallet prompt
Sealseal_model: the hash is fixed and the model is sealed. The upload key's remaining lamports return to the owner in the same transaction.the owner and the upload key
GrantWith grantEnclave: the model key is wrapped to the enclave and grant_by_owner makes the model live.the owner

Before wrapping the key for the grant, the client checks the enclave on chain the way grant does.

Progress#

onProgress receives:

FieldMeaning
step'create' | 'upload' | 'seal' | 'grant' | 'done'

Where the sealing is. upload is reported after every write.

bytesWrittennumber

Ciphertext bytes on chain so far.

totalBytesnumber

The length of the ciphertext.

transactionsWrittennumber

Upload transactions that have landed for the model.

What comes back#

FieldMeaning
modelModel

The model as the API reads it after the last step: sealed, or live when a grant was made. The fields are in HTTP API: Models.

resumeSealResume

The sealing's state, including the model key. Keep it: the model key is what every later grant by the owner wraps.

Resuming#

A SealResume holds everything the device needs to carry a sealing on, or to grant the model later:

FieldMeaning
modelstring

The model's address.

ciphertextUint8Array

The complete ciphertext.

modelKeyUint8Array

The 32-byte model key.

uploadKeyKeypair

The one-time key that writes the ciphertext.

plaintextSizeBytesnumber

The length of the weights before encryption.

noncePrefixUint8Array

The 16-byte nonce prefix of the weights cipher.

weightsKeysKeypair[], optional

The keys of the Weights accounts.

To resume, pass the saved state as resume with the same manifest and settings, and no weights:

TypeScript
const resumed = await voynich.seal({
  manifest,
  price,
  operatorShareBps: 2500,
  allowedMeasurements: [measurement],
  uploadFundingLamports: '5000000',
  grantEnclave: enclave,
  resume: saved,
})

A resumed sealing reads the model from chain, skips the Weights accounts that exist and the byte ranges already written, writes the rest, seals, and grants when asked. A sealing interrupted at any step picks up at that step.

Failures#

Code or errorWhen
WALLET_REQUIREDThe client has no signer.
Error, Weights are required for a new sealingNeither weights nor resume was given.
MODEL_TOO_LARGEThe ciphertext needs more than 8 Weights accounts.
CREATE_MODEL_TOO_LARGEThe quote's canCreate is not true: the create_model transaction is larger than 1,104 bytes or the stored manifest larger than 4,096. The message gives the transaction's size. Fewer measurements or a shorter manifest make it smaller.
CONFIGURATION_REQUIREDThe API does not name the program.
ALLOCATION_FAILEDA transaction creating a Weights account failed.
TRANSACTION_EXPIREDA transaction creating a Weights account expired before it landed. Resume with the saved state.
INVALID_WEIGHTSOn resume: a Weights account exists with another owner or size, or the model's accounts do not cover a byte range.
RESUME_MISMATCHOn resume: the model on chain has another owner, another size or another upload key.
TRANSACTION_FAILEDA create, write, seal or grant transaction was refused. The message carries the reason.
ApiClientErrorThe API refused the quote or a build, with an API error code. An invalid name, or one that differs from the manifest's, is refused at the quote. A build its signer cannot pay is refused with INSUFFICIENT_FUNDS. A name that is taken by another model fails with RESUME_MISMATCH.

The grant step can also fail with the codes of grant.

What it costs#

The rent of the Model account and of the Weights accounts, the fees of the owner's transactions, and the fees of the upload's transactions, paid from the upload funding. The sealing transaction returns what is left of the upload funding to the owner. voynich.api.quoteModel({ sizeBytes }) computes each part before anything is sent: see POST /v1/models/quote.

The whole task, with the site and the CLI beside the SDK, is in Seal a model in ten minutes.