Registering a Nautilus Enclave

Enclave registration is a one-time operation. It verifies the enclave's Nitro attestation document on-chain and records the enclave's Ed25519 public key. All subsequent score submissions use cheap Ed25519 signature verification against this key.

Prerequisites

  • Built enclave EIF (./scripts/build-enclave.sh complete)
  • Validator registered with sufficient stake
  • Running EC2 instance with Nitro Enclave support

Step 1: Start the Enclave

nitro-cli run-enclave \
  --eif-path vram-nautilus.eif \
  --memory 4096 \
  --cpu-count 2 \
  --enclave-cid 16

Verify the enclave is running:

nitro-cli describe-enclaves

The enclave exposes an HTTP server via vsock-proxy on port 3000. Start the proxy:

vsock-proxy 3000 localhost 3000 &

Step 2: Verify the Enclave Is Responding

curl http://localhost:3000/health
# {"status":"ok","pubkey":"<hex>"}

curl http://localhost:3000/get_attestation
# {"attestation_document":"<hex>","public_key":"<hex>"}

The attestation_document is a COSE_Sign1 CBOR structure containing the enclave's PCR values and ephemeral public key, signed by the AWS Nitro root certificate.

Step 3: Register On-Chain

source .env
cargo run --release --bin vramhub-cli -- register-enclave \
  --enclave-url http://localhost:3000 \
  --validator-uid $VRAMHUB_VALIDATOR_UID

This command:

  1. Fetches the attestation document from the enclave
  2. Extracts PCR0, PCR1, PCR2 from the CBOR payload
  3. Verifies each PCR is exactly 48 bytes (SHA-384)
  4. Submits register_enclave on-chain

The register_enclave Move function:

  • Verifies the full COSE_Sign1 attestation document
  • Checks PCR0/PCR1/PCR2 match the values stored in hparams.move
  • Records the enclave public key in enclave_registry.move

Expected output:

INFO vramhub_cli::commands::register: Fetching attestation document enclave_url=http://localhost:3000 validator_uid=0
INFO vramhub_cli::commands::register: Extracted PCR values, submitting on-chain pubkey=<hex> pcr0=<hex> pcr1=<hex> pcr2=<hex>
INFO vramhub_cli::commands::register: Enclave registered successfully

Step 4: Verify Registration

cargo run --release --bin vramhub-cli -- status --validator-uid $VRAMHUB_VALIDATOR_UID

You should see the enclave listed as registered with its public key.

PCR Mismatch Errors

If registration fails with a PCR mismatch, the PCR values in hparams.move do not match your enclave build. This can happen if:

  1. You built the enclave with a different version of the code
  2. The governance has updated the expected PCRs on-chain
  3. The build environment is not reproducible

To check expected PCRs:

cargo run --release --bin vramhub-cli -- hparams
# Shows current on-chain hyperparameters including expected PCR values

To rebuild the enclave and get new PCRs:

./scripts/build-enclave.sh
# Note the new PCR values and compare with on-chain values

Enclave Restart

If the enclave restarts (e.g., after an EC2 reboot), it generates a new ephemeral Ed25519 keypair. You must re-register:

cargo run --release --bin vramhub-cli -- register-enclave \
  --enclave-url http://localhost:3000 \
  --validator-uid $VRAMHUB_VALIDATOR_UID

This updates the stored public key in enclave_registry.move. The PCR values remain the same as long as the binary hasn't changed.

Security Note

The enclave's ephemeral private key never leaves the enclave. It is generated inside the Nitro Secure Module (NSM) and used only to sign score payloads. Even the operator running the enclave cannot extract it. This is the root of VRAM HUB's score integrity guarantee.