Concepts
Sealed models
A sealed model is a model whose weights are stored on Solana as ciphertext. It has an address. Anyone can fetch every byte behind that address, and the bytes open only inside an enclave that holds a grant.
A sealed model is two kinds of account:
- one Model account, which holds the facts about the model and the rules for opening it
- one or more Weights accounts, which hold the ciphertext
What the Model holds#
| Fact | Meaning |
|---|---|
| Owner | The wallet that sealed the model. It sets the price, grants enclaves and retires the model. |
| Name | 1 to 32 characters: lowercase letters and digits in groups joined by single hyphens, such as sketch-32. The name gives the Model its address, so a name is taken once. A model is addressed by its name or by its account address. |
| Manifest | What the model takes and returns, up to 4,096 bytes. See The manifest. |
| Weights accounts | The accounts that hold the ciphertext, in order: 1 to 8. |
| Size | The length of the ciphertext in bytes. |
| Ciphertext SHA-256 | The hash of the complete ciphertext. Empty until the model is sealed, fixed from then on. |
| Cipher | The cipher id, the chunk size and the nonce prefix. See The cipher. |
| Allowed measurements | The enclave software that may open the model: 1 to 8 measurements. See Allowed measurements. |
| Price and mint | What one call costs, in base units of the mint the owner chose. No mint means SOL. |
| Operator share | The part of each call's price paid to the operator whose enclave answers, in basis points. The split is told in Fees and the token. |
| Status | uploading, sealed, live or retired. See Statuses. |
| Calls settled | How many calls to the model have settled. |
The exact account layout is in Program: Accounts.
The manifest#
The manifest is stored in the Model in the clear. It tells a caller what to send and an enclave how to run the model.
| Field | Type | Meaning |
|---|---|---|
name | slug | The model's name. |
inputKind | sketch or tensor | sketch takes a drawing. tensor takes numbers as JSON. |
inputShape | positive integers | The shape of the input tensor. |
labels | strings, at least one | What each output index means, in order. |
inputName | string, optional | The name of the ONNX input. |
outputName | string, optional | The name of the ONNX output. |
preprocess | string, optional | How a raw input becomes the tensor. |
The manifest of sketch-32:
{
"name": "sketch-32",
"inputKind": "sketch",
"inputShape": [1, 1, 28, 28],
"inputName": "input",
"outputName": "logits",
"preprocess": "Crop the drawing to its ink, scale the longer side to 24 px keeping aspect, center it in 28x28; float32, background 0, ink 1.",
"labels": [
"airplane", "apple", "banana", "bicycle", "bird", "butterfly", "car", "cat",
"clock", "cloud", "cup", "envelope", "eye", "fish", "flower", "guitar",
"hat", "house", "key", "ladder", "light bulb", "moon", "mountain", "pizza",
"snail", "spider", "star", "sun", "sword", "television", "tree", "umbrella"
]
}The weights file itself is ONNX.
On chain#
The Model stores the manifest as compact UTF-8 JSON of at most 4,096 bytes. A sketch manifest leaves out each of inputShape, inputName, outputName and preprocess whose value is the sketch default, the value shown above. Read back, a sketch manifest carries all four, the defaults filled in, so the API, the SDK and the enclave runtime always see the whole manifest.
The manifest and the allowed measurements travel in the create_model transaction, which is at most 1,104 bytes. POST /v1/models/quote measures that transaction for a model's metadata, and a sealing allocates its Weights accounts once the quote's canCreate is true.
The cipher#
Weights are encrypted on the owner's device, before anything is sent, with cipher id xchacha20poly1305-64k-v1.
| Part | Value |
|---|---|
| Algorithm | XChaCha20-Poly1305 |
| Model key | 32 random bytes, drawn on the owner's device |
| Chunk | 65,536 bytes of plaintext; the last chunk holds the remainder |
| Tag | 16 bytes, one per chunk, stored after the chunk |
| Nonce prefix | 16 random bytes, drawn at every sealing and stored in the Model |
Nonce of chunk i | the nonce prefix, then i as an unsigned 64-bit little-endian integer (24 bytes) |
The ciphertext is the sealed chunks one after another, each with its tag:
ciphertext bytes = plaintext bytes + 16 × ceil(plaintext bytes / 65,536)
sealed chunk i starts at byte i × 65,552Each chunk authenticates on its own, so any range of the model can be opened and checked without the rest: take the complete sealed chunks the range touches, authenticate each one, and cut the range out of the result.
The hash#
The Model's hash is the SHA-256 of the complete ciphertext: every sealed chunk and its tag, in order. Sealing writes it into the Model. From that slot the bytes behind the address cannot change, and anyone who fetches them can check they have the model the owner sealed.
Where the ciphertext sits#
The ciphertext is written into Weights accounts. A Weights account is a 56-byte header followed by ciphertext, and a Solana account holds up to 10 MiB, so one account carries up to 10,485,704 bytes of ciphertext. sketch-32 sits in one. A model has up to 8 Weights accounts, and its ciphertext is theirs in order. The header records which model the account belongs to, its place in the model's list, its size and how much of it has been written.
The bytes are public. Read them from the accounts over any RPC, or as a range through the API:
GET /v1/models/sketch-32/weights?offset=0&length=256offset starts at 0 and length is between 1 and 1,048,576 bytes (256 when omitted). The response carries the range as base64 with the Weights accounts it came from. See HTTP API: Models.
Allowed measurements#
A measurement is the 48-byte fingerprint of the software running inside an enclave, written as 96 lowercase hex characters. The attestation record records it with the enclave's key.
A Model lists 1 to 8 measurements, set when the model is created. A grant is made only to an enclave whose recorded measurement is on that list. The owner chooses which enclave software may ever hold the model's key, and the list is public. See Enclaves and attestation.
Statuses#
| Status | The model is | What can happen |
|---|---|---|
uploading | created, its ciphertext being written | The upload key writes the ciphertext, in any order. The owner seals once every account is written to its end and the hash matches. |
sealed | complete, its hash fixed | Nothing can write to its Weights accounts again. The owner grants a first enclave. |
live | granted to a first enclave | Callers open calls. The owner sets the price, grants further enclaves, revokes grants, retires. Granted enclaves grant further enclaves. |
retired | closed to new calls and new grants | Open calls settle until their deadline and refund after it. |
Sealing a model from the first step to live is in Seal a model in ten minutes. Changing a live model is in Manage a model.