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:
npm install -g voynich voynich-enclaveThe 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.
SOLANA_RPC_URLURLrequiredThe Solana RPC the runtime reads the chain and sends its transactions through.
OPERATOR_KEYPAIRfile path or JSON arrayThe 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 arrayrequiredThe 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 charactersrequiredThe 32-byte key the state file is encrypted under.
ENCLAVE_STATE_PATHfile pathThe enclave's state file. .local/enclave.sealed.json under the working directory when unset. Each enclave has its own.
ENCLAVE_ENDPOINTURLThe 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_HOSThostThe interface run listens on. 127.0.0.1 when unset.
ENCLAVE_PORTintegerThe port run listens on. 9707 when unset.
ENCLAVE_POLL_MSinteger, millisecondsHow often run checks its attestation record, its grants and other enclaves. 5000 when unset.
ENCLAVE_RPC_RPSintegerThe most RPC requests per second the runtime sends. Required when SOLANA_RPC_URL is not a local address.
ENCLAVE_SCAN_INTERVAL_MSinteger, millisecondsThe shortest gap between two scans of the program's accounts. Required when SOLANA_RPC_URL is not a local address.
PROGRAM_IDaddressThe voynich program. The id built into the runtime when unset.
ATTESTATION_PROGRAM_IDaddressThe attestation program. The id built into the runtime when unset.
LOOKUP_TABLEaddressAn 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#
voynich enclave registerAttests and registers the enclave, then exits. It runs no listener.
- Follow what was in flight
Transactions the state file holds as signed and not landed are sent again.
- 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.
- 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.
- 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 withrefresh_enclavewhen 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#
voynich enclave runRuns 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:
| Route | Returns |
|---|---|
GET /health | status (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}/input | Takes { "envelope": "<base64>" }, the encrypted input, and returns call and status (accepted). |
GET /v1/calls/{call}/answer | status (waiting, answered or failed), outputEnvelope, outputHash, signature, settleTransaction, receiptAddress and failure. |
It writes one line of JSON per event, all on stderr:
| Line | When |
|---|---|
event listening, with host and port | The listener is up. |
event http, with method, route, status and ms | A request to the listener is answered. |
event model.loaded, with model and name | A granted model is decrypted and loaded. |
event call.failed, with call and error | A call could not be completed. |
event enclave.sync.failed, with error and message | A pass of the loop failed. |
event rpc, with service, method, status and ms | Each 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#
voynich enclave statusReads 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:
enclaveaddress or nullThe Enclave account's address, derived from the signing key. null when no state file exists.
signingKeyaddress or nullThe enclave's signing key. null when no state file exists.
measurement96 hex charactersThe runtime's measurement.
registeredbooleanWhether the Enclave account exists on chain. false when no state file exists.
expiresAtSlotinteger string or nullThe 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.
| Message | Cause |
|---|---|
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. |