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.
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#
weightsUint8ArrayThe ONNX file's bytes. Required for a new sealing, left out when resuming.
manifestManifestrequiredThe model's manifest. Its fields are in Sealed models.
namestringThe model's name. The manifest's name by default. 1 to 32 characters: lowercase letters and digits in groups joined by single hyphens.
priceMoneyrequiredThe 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.
operatorShareBpsnumberrequiredThe operator's share of the price, in basis points, 0 to 10,000. With the protocol share it is at most 10,000.
allowedMeasurementsstring[]required1 to 8 measurements, each 96 hex characters: the enclave software that may open the model.
uploadFundingLamportsstringrequiredLamports 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.
grantEnclavestringAn enclave's address or signing key. When given, the sealed model is granted to it and becomes live.
resumeSealResumeThe 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) => voidCalled as the sealing moves on.
signalAbortSignalAborts the sealing. It can be resumed.
What it does#
| Step | What happens | Signed by |
|---|---|---|
| Encrypt | A random model key is drawn and the weights are encrypted in 64 KiB chunks. Nothing is sent. | nobody |
| Quote | POST /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 |
| Allocate | The Weights accounts are created: one for every 10,485,704 bytes of ciphertext, at most 8. One transaction each. | the owner, once per account |
| Create | create_model: the Model exists in uploading and the upload key is funded. | the owner |
| Upload | The ciphertext is written up to 512 bytes per transaction, four transactions at a time. | the upload key, with no wallet prompt |
| Seal | seal_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 |
| Grant | With 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:
step'create' | 'upload' | 'seal' | 'grant' | 'done'Where the sealing is. upload is reported after every write.
bytesWrittennumberCiphertext bytes on chain so far.
totalBytesnumberThe length of the ciphertext.
transactionsWrittennumberUpload transactions that have landed for the model.
What comes back#
modelModelThe 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.
resumeSealResumeThe 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:
modelstringThe model's address.
ciphertextUint8ArrayThe complete ciphertext.
modelKeyUint8ArrayThe 32-byte model key.
uploadKeyKeypairThe one-time key that writes the ciphertext.
plaintextSizeBytesnumberThe length of the weights before encryption.
noncePrefixUint8ArrayThe 16-byte nonce prefix of the weights cipher.
weightsKeysKeypair[], optionalThe keys of the Weights accounts.
To resume, pass the saved state as resume with the same manifest and settings, and no weights:
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 error | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
Error, Weights are required for a new sealing | Neither weights nor resume was given. |
MODEL_TOO_LARGE | The ciphertext needs more than 8 Weights accounts. |
CREATE_MODEL_TOO_LARGE | The 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_REQUIRED | The API does not name the program. |
ALLOCATION_FAILED | A transaction creating a Weights account failed. |
TRANSACTION_EXPIRED | A transaction creating a Weights account expired before it landed. Resume with the saved state. |
INVALID_WEIGHTS | On resume: a Weights account exists with another owner or size, or the model's accounts do not cover a byte range. |
RESUME_MISMATCH | On resume: the model on chain has another owner, another size or another upload key. |
TRANSACTION_FAILED | A create, write, seal or grant transaction was refused. The message carries the reason. |
ApiClientError | The 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.