seal
voynich seal takes a weights file and a manifest to a sealed model on chain. It encrypts the weights on this machine, writes the ciphertext into the model's Weights accounts, fixes its hash and, with --enclave, grants a first enclave so the model is live. What a sealed model is on chain is told in Sealed models. The same from code is seal.
voynich seal model.onnx \
--manifest manifest.json \
--state owner.enc.json \
--price 100000 \
--operator-share-bps 2500 \
--measurement <measurement> \
--upload-funding <lamports> \
--enclave <enclave>Arguments and flags#
weights filefile path, first argumentrequiredThe model's weights, an ONNX file. Left out with --resume, where the ciphertext comes from the owner key file.
--manifestfile pathrequiredThe model's manifest as JSON. Its name is the model's name, and the model's address is derived from it. The manifest's fields are told in Sealed models. A sketch manifest may leave out the fields that take the sketch defaults.
--statefile pathrequiredWhere the owner key file is written, and where --resume reads it from.
--priceinteger stringrequiredThe price of one call, in base units of the price's unit: lamports for SOL, the mint's smallest unit for a mint.
--mintSOL or addressThe unit of the price: SOL, in any case, or the address of the SPL Token mint the price is in. Without it the price is in SOL.
--decimalsintegerThe decimals of the price's unit. Required with a mint address. 9 for SOL.
--symbolstringThe label shown beside the price. SOL for SOL, the mint's address for a mint.
--operator-share-bpsinteger, 0 to 10000requiredThe operator's share of each settled call, in basis points. The split is told in Fees and the token.
--measurement96 hex characters, repeatablerequiredA measurement the model allows: enclaves whose attestation record states it can be granted the key. Give the flag once per measurement, 1 to 8 times.
--upload-fundinginteger string, lamportsrequiredWhat moves from the owner's wallet to the upload key when the model is created. The upload key pays the fee of every write from it. The amount for a model is told in Upload funding.
--enclaveenclave address or signing keyThe enclave to grant when the model is sealed. With it the command ends on a live model, without it on a sealed one.
--resumeflagContinue a sealing from the owner key file. See Resuming.
The global flags --api-url and --keypair are in Install. The wallet the command signs with becomes the model's owner.
Pricing#
A price in SOL needs --price alone:
--price 100000--mint SOL gives the same price. A price in an SPL Token mint names the mint and its decimals:
--price 100000 --mint <mint address> --decimals <decimals> --symbol <symbol>The price and the operator share are recorded on the Model when it is created.
Measurements#
--measurement is repeatable. Each value is the 48-byte measurement of an enclave build, as 96 lowercase hex characters:
--measurement <measurement of one build> --measurement <measurement of another>An operator reads the measurement of a runtime with voynich enclave status, and every registered enclave's measurement is in voynich enclaves. What a measurement is is told in Enclaves and attestation.
Upload funding#
Writes are signed by a one-time upload key, made for this sealing, so the owner's wallet signs nothing while the ciphertext goes up. --upload-funding is the lamports that key receives in the creating transaction. Each write carries up to 512 bytes of ciphertext in one transaction, and a write stops at the end of a Weights account, so a model of n ciphertext bytes takes about n / 512 writes.
POST /v1/models/quote computes the amount for a ciphertext size: its uploadFundingLamports is the value to pass, and its requiredUpfrontLamports is what the owner's wallet needs for the whole sealing.
seal asks the same route for a quote with the model's create metadata before it allocates anything. Unless the quote's canCreate is true, the command stops with CREATE_MODEL_TOO_LARGE, and nothing is sent.
The owner key file#
The file at --state holds everything the sealing needs to finish and the key the owner grants with later:
- the model's address
- the ciphertext
- the model key
- the upload key's secret
- the secrets of the Weights accounts' keys
- the plaintext size and the cipher's nonce prefix
It is written before the first transaction is sent, and again once the creating transaction is built.
The file is encrypted under one password. The key is derived with scrypt (N 131072, r 8, p 1) over a random 16-byte salt, and the contents are encrypted with XChaCha20-Poly1305 under a random 24-byte nonce. On disk it is one line of JSON with version, kdf, salt, nonce and ciphertext. Each write goes to <file>.tmp with mode 0600 and is then renamed over the file.
The password#
seal asks for the password once, on stderr, before it reads anything else:
Owner key file password: The typing is not shown. Enter ends it, Backspace removes a character, Ctrl+C cancels.
Where no terminal is attached, set VOYNICH_PASSWORD:
VOYNICH_PASSWORD=<password> voynich seal model.onnx --manifest manifest.json --state owner.enc.json ...What the wallet signs#
After the quote, the owner's wallet signs these transactions, in order:
| Transaction | How many |
|---|---|
| Allocate a Weights account | One per Weights account. An account holds up to 10 MiB less a 56-byte header, and a model has 1 to 8. |
create_model | One. It creates the Model in uploading, binds the Weights accounts and funds the upload key. |
seal_model | One. It fixes the ciphertext's SHA-256. |
grant_by_owner | One, with --enclave. |
A model whose ciphertext fits one Weights account takes three signatures, four with --enclave. Every write between create_model and seal_model is signed by the upload key. The instructions are told in Instructions.
Progress#
Progress is written to stderr, one line per step and one per upload write:
<step>: <bytes written>/<total bytes> bytes, <writes> upload transactions| Step | Written |
|---|---|
create | Before the Weights accounts are allocated and the model is created. |
upload | After each write, with the bytes written so far and the write transactions that have landed for the model. |
seal | When every byte is written, before seal_model. |
grant | Before the grant, with --enclave. |
done | When the model has reached its final status. |
What it prints#
The Model, as JSON on stdout, with the status it reached: live with --enclave, sealed without. Its fields are listed in Model fields. The model key and the upload key are never printed.
Resuming#
A sealing that stopped continues from its owner key file:
voynich seal --resume \
--manifest manifest.json \
--state owner.enc.json \
--price 100000 \
--operator-share-bps 2500 \
--measurement <measurement> \
--upload-funding <lamports> \
--enclave <enclave>Pass the flags of the first run and the same password. --resume reads the ciphertext, the model key, the upload key and the Weights accounts' keys from the file, so it takes no weights file and encrypts nothing. It then skips whatever the chain already holds:
| Already on chain | Skipped |
|---|---|
| A Weights account | Its allocation. The account has to be owned by the program and have the expected size. |
| The Model | create_model. |
| A range of ciphertext bytes | The writes for that range. Only the missing ranges are written. |
A status of sealed or live | Every write and seal_model. |
A status of live | The grant. |
The wallet has to be the model's owner, and the file's ciphertext size and upload key have to match the Model.
Failures#
The command prints one line to stderr, <code>: <message>, or the message alone where the tables show no code, and exits with code 1. The code is the one the SDK raises for the same failure.
Before anything is sent#
| Message | Cause |
|---|---|
Supply --state. | A required flag or the weights file is missing. The message names it: --manifest, --price, --operator-share-bps, --upload-funding, weights file. |
Supply --decimals for an SPL mint. | --mint with a mint address, without --decimals. |
Set VOYNICH_PASSWORD when no interactive terminal is available | No terminal to prompt on and no VOYNICH_PASSWORD. |
The password cannot be empty | Enter on an empty password. |
Cancelled | Ctrl+C at the prompt. |
Unsupported owner key file format | With --resume: the file at --state has another version or kdf. |
| A list of fields, as JSON | The manifest does not have the manifest's shape. Each entry names the field in path and what is wrong in message. |
While sealing#
| Code | Message | Cause |
|---|---|---|
MODEL_TOO_LARGE | A model can use at most eight weights accounts. | The ciphertext needs more than eight Weights accounts. |
CREATE_MODEL_TOO_LARGE | The create_model transaction is <bytes> bytes; the wallet-safe maximum is 1104. Reduce the manifest or measurements before allocating accounts. | The quote's canCreate is not true. Nothing was sent. |
CONFIGURATION_REQUIRED | The Voynich program is not configured. | The API names no program. |
INVALID_WEIGHTS | A resumed weights allocation does not match this model. | A Weights account of the file exists with another owner or size. |
ALLOCATION_FAILED | The weights allocation transaction failed. | The transaction that allocates a Weights account failed on chain. |
TRANSACTION_EXPIRED | The weights allocation expired. Resume using the saved sealing state. | An allocation did not land before its blockhash expired. Run again with --resume. |
RESUME_MISMATCH | The sealing state does not match the on-chain model. | The Model has another owner, another ciphertext size or another upload key than this run. A model of this name already exists, or --resume was left out. |
INVALID_WEIGHTS | The model weights accounts do not cover this byte range. | The Model's Weights accounts do not span the ciphertext. |
INSUFFICIENT_FUNDS | The API's message, with the amounts | The owner's wallet cannot pay create_model or seal_model, or the upload key cannot pay a write. The amounts are in Funding. |
TRANSACTION_FAILED | The failure's own message, or The transaction did not land. | A transaction was refused. A refusal by the program carries one of its errors. |
TRANSACTION_EXPIRED | The failure's own message, or The transaction did not land. | A transaction did not land before its blockhash expired. Run again with --resume. |
With --enclave, the failures of grant apply to the last step. A refusal by the API prints the API's code and message; the codes are in the HTTP API overview.