enclave

The three enclave commands are the operator's: register attests an enclave and registers it, run runs the enclave runtime, status prints where an enclave stands. This page is the command reference. The operator's path from a machine to earnings is told in Run the enclave runtime and Register and get granted, and what an enclave is in Enclaves and attestation.

The runtime package#

The commands load the enclave runtime from a second package, voynich-enclave, which they find beside the CLI. Install both:

Shell
npm install -g voynich voynich-enclave

The runtime needs Node 22 or later. The package also installs its own binary, voynich-enclave, which starts the runtime without the CLI, as told in Run the enclave runtime. Building it from the repository is told in Run the enclave runtime.

Environment variables#

The three commands take no flags of their own. They are configured through the environment, and through a .env file in the working directory when one exists. A variable set to an empty value counts as unset.

FieldMeaning
SOLANA_RPC_URLURLrequired

The Solana RPC the runtime reads the chain and sends its transactions through.

OPERATOR_KEYPAIRfile path or JSON array

The operator's keypair: a Solana JSON keypair file, or the 64-byte array itself. It pays the runtime's fees and is recorded as the enclave's operator. For register and run the CLI sets it from --keypair, then from this variable, then from the Solana CLI's keypair, as told in Install.

DEV_ATTESTATION_ROOT_KEYPAIRfile path or JSON arrayrequired

The keypair that signs the enclave's hardware type dev attestation report when Config.attestation_program points to attest (used at mainnet launch as well as on local clusters until set_config switches to Solana Confidential Compute). It must match dev_root in attest's config.

DEV_SEALING_KEY64 hex charactersrequired

The 32-byte key the state file is encrypted under.

ENCLAVE_STATE_PATHfile path

The enclave's state file. .local/enclave.sealed.json under the working directory when unset. Each enclave has its own.

ENCLAVE_ENDPOINTURL

The address callers' inputs reach the runtime at. It is recorded on the Enclave account, so set it to the runtime's public URL. http://127.0.0.1:<ENCLAVE_PORT> when unset.

ENCLAVE_HOSThost

The interface run listens on. 127.0.0.1 when unset.

ENCLAVE_PORTinteger

The port run listens on. 9707 when unset.

ENCLAVE_POLL_MSinteger, milliseconds

How often run checks its attestation record, its grants and other enclaves. 5000 when unset.

ENCLAVE_RPC_RPSinteger

The most RPC requests per second the runtime sends. Required when SOLANA_RPC_URL is not a local address.

ENCLAVE_SCAN_INTERVAL_MSinteger, milliseconds

The shortest gap between two scans of the program's accounts. Required when SOLANA_RPC_URL is not a local address.

PROGRAM_IDaddress

The voynich program. The id built into the runtime when unset.

ATTESTATION_PROGRAM_IDaddress

The attestation program. The id built into the runtime when unset.

LOOKUP_TABLEaddress

An address lookup table the runtime's transactions use. None when unset.

The state file#

The first enclave register or enclave run against a state path creates the enclave's two keys, the Ed25519 signing key and the X25519 encryption key, and writes them to the state file, encrypted with AES-256-GCM under DEV_SEALING_KEY. Every later command with the same path and key is the same enclave. enclave status reads the file and never creates or writes it. The file also holds the enclave's grants, the calls it is answering and the transactions it has signed and is still following, so a restart continues where the runtime stopped.

A state file belongs to one chain and one pair of program ids.

voynich enclave register#

Shell
voynich enclave register

Attests and registers the enclave, then exits. It runs no listener.

  1. Follow what was in flight

    Transactions the state file holds as signed and not landed are sent again.

  2. Fund the signing key

    When the enclave's signing key holds less than the rent-exempt minimum, the operator's wallet sends it the difference.

  3. Attest

    A report is submitted to the attestation program when the enclave has no attestation record, when the record expires within a third of a record's lifetime, or when it states another measurement than the runtime's.

  4. Register or refresh

    An enclave that has no Enclave account is registered with register_enclave: its two keys, the operator and the endpoint. One that has an account is refreshed with refresh_enclave when the record's expiry, the endpoint or the measurement has changed.

It then reads the enclave as voynich enclave status does and prints that object on stdout: enclave (the Enclave account, which owners grant to), signingKey, measurement (the SHA-384 of the runtime's built file, which owners allow with voynich seal --measurement), registered and expiresAtSlot.

voynich enclave run#

Shell
voynich enclave run

Runs the enclave runtime until the process is stopped. It starts with the four steps of register, then listens on ENCLAVE_HOST and ENCLAVE_PORT and repeats this every ENCLAVE_POLL_MS:

  • attest again and refresh the Enclave before the record expires
  • read the enclave's grants; for each new one, read the model's Weights accounts, check the ciphertext's SHA-256 against the Model, unwrap the model key, decrypt the weights and load the model in memory
  • grant each loaded, live model to every other registered enclave whose measurement the model allows, whose record is in force and which has no Grant for it, with grant_by_enclave
  • take up calls that were waiting when the runtime last stopped

A pass that fails writes an enclave.sync.failed line and the next pass runs after ENCLAVE_POLL_MS. The listener keeps answering meanwhile.

A call arrives as an encrypted input. The runtime checks it against the Call on chain, runs the model, encrypts the output to the caller, signs the receipt message and sends settle_call. A call is told from the caller's side in Calls and receipts.

The listener serves three routes:

RouteReturns
GET /healthstatus (ready), enclave, measurement and models, the addresses of the models loaded. The Voynich API reads it to tell whether the enclave is reachable.
POST /v1/calls/{call}/inputTakes { "envelope": "<base64>" }, the encrypted input, and returns call and status (accepted).
GET /v1/calls/{call}/answerstatus (waiting, answered or failed), outputEnvelope, outputHash, signature, settleTransaction, receiptAddress and failure.

It writes one line of JSON per event, all on stderr:

LineWhen
event listening, with host and portThe listener is up.
event http, with method, route, status and msA request to the listener is answered.
event model.loaded, with model and nameA granted model is decrypted and loaded.
event call.failed, with call and errorA call could not be completed.
event enclave.sync.failed, with error and messageA pass of the loop failed.
event rpc, with service, method, status and msEach request to the RPC. register and status write these lines too.

The three commands keep stdout for their result alone: the JSON object of register and status. run writes nothing on stdout.

voynich enclave status#

Shell
voynich enclave status

Reads the state file and the Enclave account. It sends no transaction, creates no keys and writes no file, and it takes no keypair: it reads DEV_SEALING_KEY, ENCLAVE_STATE_PATH, SOLANA_RPC_URL and the two program ids. It prints:

FieldMeaning
enclaveaddress or null

The Enclave account's address, derived from the signing key. null when no state file exists.

signingKeyaddress or null

The enclave's signing key. null when no state file exists.

measurement96 hex characters

The runtime's measurement.

registeredboolean

Whether the Enclave account exists on chain. false when no state file exists.

expiresAtSlotinteger string or null

The slot the enclave's attestation record expires at, as the Enclave account holds it. null when the enclave is not registered.

Failures#

A failing command prints the message to stderr and exits with code 1.

MessageCause
Use enclave register, enclave run, or enclave status.The word after enclave is not one of the three.
SOLANA_RPC_URL is required for the development enclave.A required variable is unset. The message names it.
OPERATOR_KEYPAIR must contain a valid 64-byte Solana keypair.The variable named holds neither a keypair file's path nor a 64-byte array.
DEV_SEALING_KEY must be a 32-byte hexadecimal development sealing key.The sealing key is unset or is not 64 hex characters.
voynich-enclave: set rps and scanIntervalMs. A remote endpoint is a budget shared with every service on its key.ENCLAVE_RPC_RPS or ENCLAVE_SCAN_INTERVAL_MS is unset with a remote SOLANA_RPC_URL.
Unsupported enclave state version.The state file was written in another format.
The sealed enclave state belongs to another chain. Choose a separate ENCLAVE_STATE_PATH.The state file was made against another cluster or other program ids.
DEV_ATTESTATION_ROOT_KEYPAIR does not match the configured development root.The attestation program's config names another root.
The on-chain enclave registration does not match its sealed keys and operator.The Enclave account at this signing key has another operator or encryption key.