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#

FactMeaning
OwnerThe wallet that sealed the model. It sets the price, grants enclaves and retires the model.
Name1 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.
ManifestWhat the model takes and returns, up to 4,096 bytes. See The manifest.
Weights accountsThe accounts that hold the ciphertext, in order: 1 to 8.
SizeThe length of the ciphertext in bytes.
Ciphertext SHA-256The hash of the complete ciphertext. Empty until the model is sealed, fixed from then on.
CipherThe cipher id, the chunk size and the nonce prefix. See The cipher.
Allowed measurementsThe enclave software that may open the model: 1 to 8 measurements. See Allowed measurements.
Price and mintWhat one call costs, in base units of the mint the owner chose. No mint means SOL.
Operator shareThe 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.
Statusuploading, sealed, live or retired. See Statuses.
Calls settledHow 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.

FieldTypeMeaning
nameslugThe model's name.
inputKindsketch or tensorsketch takes a drawing. tensor takes numbers as JSON.
inputShapepositive integersThe shape of the input tensor.
labelsstrings, at least oneWhat each output index means, in order.
inputNamestring, optionalThe name of the ONNX input.
outputNamestring, optionalThe name of the ONNX output.
preprocessstring, optionalHow a raw input becomes the tensor.

The manifest of sketch-32:

JSON
{
  "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.

PartValue
AlgorithmXChaCha20-Poly1305
Model key32 random bytes, drawn on the owner's device
Chunk65,536 bytes of plaintext; the last chunk holds the remainder
Tag16 bytes, one per chunk, stored after the chunk
Nonce prefix16 random bytes, drawn at every sealing and stored in the Model
Nonce of chunk ithe 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:

Text
ciphertext bytes = plaintext bytes + 16 × ceil(plaintext bytes / 65,536)
sealed chunk i starts at byte i × 65,552

Each 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:

Text
GET /v1/models/sketch-32/weights?offset=0&length=256

offset 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#

StatusThe model isWhat can happen
uploadingcreated, its ciphertext being writtenThe upload key writes the ciphertext, in any order. The owner seals once every account is written to its end and the hash matches.
sealedcomplete, its hash fixedNothing can write to its Weights accounts again. The owner grants a first enclave.
livegranted to a first enclaveCallers open calls. The owner sets the price, grants further enclaves, revokes grants, retires. Granted enclaves grant further enclaves.
retiredclosed to new calls and new grantsOpen 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.