Enclaves

Two routes read enclaves. An enclave reaches the chain by registering its attestation record with the program, which is told in Enclaves and attestation and, for operators, in Register and get granted.

The errors every route shares are in Overview.

Enclave#

FieldMeaning
addressaddressrequired

The Enclave account.

signingKeyaddressrequired

The enclave's Ed25519 key. It signs receipts.

encryptionKeybase64 of 32 bytesrequired

The enclave's X25519 key. Inputs and wrapped model keys are encrypted to it.

hardwareTypestringrequired

dev: a standard-server enclave attested through attest (used at mainnet launch until Config.attestation_program switches via set_config, as well as on local clusters). tdx: Intel TDX. sev-snp: AMD SEV-SNP.

measurementmeasurementrequired

The measurement in the enclave's attestation record.

expiresAtSlotslotrequired

The slot the attestation record expires at.

operatoraddressrequired

The wallet that registered the enclave and receives the operator share.

endpointURLrequired

The address the enclave registered for itself.

relayPathstringrequired

/v1/calls/{call}/input, with the call's address in place of {call}: the path, on the API and on the enclave's endpoint alike, that takes a call's encrypted input. See Relay.

statusstringrequired

live: the attestation record expires after the current slot. expired: it does not.

reachablebooleanrequired

Whether the enclave's endpoint answered the API's last health request as this enclave. See Reachability.

lastSeentimestamp or nullrequired

When the endpoint last answered as this enclave. null until it first does.

modelsHeldintegerrequired

Grants to this enclave that are not revoked.

callsSettleddecimal stringrequired

Calls this enclave settled.

attestationobjectrequired

The enclave's attestation record.

Reachability#

The API sends GET /health to every enclave's endpoint every 15 seconds and waits up to 3 seconds for the answer. The enclave is reachable when the answer has HTTP status 200 and a JSON body whose status is ready, whose enclave is this Enclave account's address and whose measurement is the measurement of its attestation record. Any other answer, or none, makes it unreachable. Each answer that makes it reachable sets lastSeen.

When a refresh changes the enclave's endpoint or measurement, reachable reads false until the next health request reaches the new runtime.

The runtime's side of the health request is in Run the enclave runtime.

Attestation record#

The record the chain holds for the enclave's signing key. What it proves and how it is laid out are in The attestation record.

FieldMeaning
addressaddressrequired

The record's account.

signingKeyaddressrequired

The signing key the record names.

encryptionKeybase64 of 32 bytesrequired

The enclave's encryption key.

hardwareTypestringrequired

dev, tdx or sev-snp, as on the Enclave.

measurementmeasurementrequired

The 48-byte software measurement recorded for the enclave.

recordedSlotslotrequired

The slot the record was written in.

expiresAtSlotslotrequired

The slot the record expires at.

layoutVersioninteger above 0required

The record's layout version.

Grant#

One model key wrapped to one enclave. See Grants.

FieldMeaning
addressaddressrequired

The Grant account.

modeladdressrequired

The model.

modelNamestringrequired

The model's name.

enclaveaddressrequired

The Enclave account the key is wrapped to.

wrappedKeywrapped keyrequired

The model key as a 105-byte envelope, readable only inside the enclave.

grantedByaddressrequired

Who wrote the grant: the owner's wallet, or the Enclave account of the enclave that passed the key on.

grantedSlotslotrequired

The slot the grant was written in.

statusstringrequired

revoked: the owner revoked it. expired: it is not revoked and the enclave's attestation record has expired. live: neither.

GET /v1/enclaves#

Lists enclaves, live and expired, in this order: live and reachable, then live, then reachable, then the rest, each group by address. It takes cursor and limit as in Pagination.

Returns a page whose items are Enclave objects.

Next: read one enclave with GET /v1/enclaves/{key}. The enclaves that hold a given model are at GET /v1/models/{id}/enclaves.

GET /v1/enclaves/{key}#

Reads one enclave with its grants, its latest receipts and its earnings. {key} is the Enclave account's address or the enclave's signing key.

FieldMeaning
enclaveEnclaverequired

The Enclave.

grantsarray of Grantrequired

Every Grant made to this enclave, revoked ones included.

receiptsarray of Receiptrequired

The enclave's 20 latest Receipt objects, latest settling slot first.

earningsarray of Moneyrequired

The operator share of the calls this enclave settled, one Money per mint. Calls settled by the operator's other enclaves are not in it; the operator's total is operatorEarnings of GET /v1/accounts/{wallet}.

CodeWhen
VALIDATION_ERROR{key} is not an address.
ENCLAVE_NOT_FOUNDNo enclave has this address or signing key.

Next: an owner grants this enclave a model with POST /v1/models/{id}/grant/build and revokes the grant with POST /v1/models/{id}/revoke/build. A caller names it in POST /v1/calls/build.