Skip to content

docs(proof): add proof system deployment + key registration runbook - #937

Open
agentotto[bot] wants to merge 6 commits into
mainfrom
docs/proof-system-deployment-runbook
Open

docs(proof): add proof system deployment + key registration runbook#937
agentotto[bot] wants to merge 6 commits into
mainfrom
docs/proof-system-deployment-runbook

Conversation

@agentotto

@agentotto agentotto Bot commented Jul 29, 2026 •
edited by cursor Bot
Loading

Copy link
Copy Markdown
Contributor

What

Adds docs/proof/deploy-proof-system.md — a single operational runbook for deploying the Nitro (TEE) proof system to an environment (e.g. alphanet) and registering a running enclave's signing key on-chain.

Why

Today the deployment procedure only exists as inline comments on the just proof-* recipes in the Justfile. There was no consolidated deployment doc under docs/, and — more importantly — the final step, registering the enclave's generated secp256k1 keypair via NitroEnclaveKeyRegistry.registerKey, had no just recipe and no markdown coverage at all. just proof-setup stops at Phase 3b (approve PCRs).

What's in the doc

  • Phase table mapping each just proof-* recipe (0a → 3b) to what it does, plus the combined proof-setup.
  • Prerequisites: tooling, the running nitro-worker pod (alphanet namespace/context/image), env config (scripts/proof-envs/), and the full secret/env-var matrix.
  • Phase-by-phase walkthrough (rollup config hash, PCRs, deploy Nitro stack, deploy proof system, CertManager pre-warm, approve PCR set), grounded in DeployNitro.s.sol, DeployProofSystem.s.sol, and PrewarmCertManager.s.sol.
  • Phase 4 — register the generated keypair: the enclave's ephemeral secp256k1 key (from NSM entropy) → PublicKey-embedding attestation → split TBS/sig → p384-hints attestation → registerKey(bytes,bytes,bytes) → verify with isKeyRegistered. Explicitly flags the current tooling gap (bare get-attestation omits public_key and can't be used to register; no just proof-register-key recipe yet).
  • Re-registration/upgrade flow and a troubleshooting table.

Notes

  • Documentation-only change; no code or contract behavior touched.
  • Complements the existing docs/proof/nitro-worker.md (how-it-works) and docs/proof/proof-cli.md (CLI reference) rather than duplicating them.
  • Suggested follow-up: expose Phase 4 as a just proof-register-key <env> recipe (needs a PublicKey-request CLI path, since the existing get-attestation returns a bare attestation).

Co-authored-by: Otto otto@toolsforhumanity.com

Note

Low Risk
Documentation-only; no runtime, contract, or deployment behavior changes in this PR.

Overview
Adds docs/proof/deploy-proof-system.md, a single operational runbook for deploying the Nitro (TEE) proof stack and registering an enclave signing key on L1.

It maps just proof-* phases 0a–3b (rollup hash, enclave inspection, DeployNitro / DeployProofSystem, CertManager pre-warm, PCR approval) and just proof-setup, with prerequisites (tooling, scripts/proof-envs/, secrets matrix, running nitro-worker pod). just proof-setup stops at Phase 3b; the doc fills the gap with Phase 4: PublicKey-embedding attestation → TBS/sig split → p384-hints → registerKey (not owner-gated; PCR allowlist gates images), plus verification and the bare-get-attestation tooling limitation.

Also documents boot-time self-registration (PR #938 entry points, REGISTER_PRIVATE_KEY), alphanet Kubernetes behavior (production enclave mode, launcher/probe lifecycle, secret provisioning), re-registration/upgrades, and a troubleshooting table. Links to nitro-worker.md and proof-cli.md instead of duplicating architecture/CLI detail.

Reviewed by Cursor Bugbot for commit 0fb84de. Bugbot is set up for automated code reviews on this repo. Configure here.

@piohei Otto
docs(proof): add proof system deployment + key registration runbook
575c107 
Consolidates the Nitro proof-system deployment procedure (previously only
documented inline in the Justfile) into a single docs/ runbook, and fills the
gap around Phase 4 — registering the enclave's generated secp256k1 keypair
on-chain via NitroEnclaveKeyRegistry.registerKey, which had no just recipe or
markdown coverage.

Co-authored-by: Otto <otto@toolsforhumanity.com>
@piohei Otto
docs(proof): clarify registerKey is not owner-gated + note self-regis…
9057b20 
…tration gap

- registerKey is permissionless-by-attestation: any funded L1 key can call it;
  authorization is the owner-approved PCR allowlist + attestation verification,
  not an onlyOwner modifier. Use PRIVATE_KEY (not OWNER_KEY) in the example.
- Add a 'Known gap / follow-up' section: worker self-registration on boot is
  compatible with the trust model but not implemented (get_public_key_async has
  no callers; no CLI/just/startup hook).

Co-authored-by: Otto <otto@toolsforhumanity.com>
@agentotto agentotto Bot mentioned this pull request Jul 29, 2026
Merged
piohei and others added 4 commits August 4, 2026 06:28
@piohei Otto
docs(proof): document automated self-registration + K8s deployment
639c6a5 
The 'known gap' section is now implemented (PR #938); replace it with an
'Automated self-registration' section (register CLI / --auto-register /
just proof-register-key) and a 'Kubernetes deployment (alphanet auto-register)'
section that captures the rationale trimmed out of the crypto-apps values:
production-mode enclave, probe-based keep-alive (jq + trap + sleep infinity),
the funding-key provisioning chain (infra Terraform -> kube-ops -> application
secret -> /etc/secrets), and PCR verification.

Co-authored-by: Otto <otto@toolsforhumanity.com>
@piohei Otto
docs(proof): select the launched enclave, not describe-enclaves[0]
28223d5 
Update the K8s deployment section: read EnclaveID/EnclaveCID from run-enclave's
own JSON output (not describe-enclaves .[0], which lists all node enclaves);
probes filter by our specific enclave ID via /tmp/enclave-id; note the
defensive startup termination of leaked node-level enclaves.

Co-authored-by: Otto <otto@toolsforhumanity.com>
@piohei Otto
docs(proof): drop startup terminate-all; fail loud on capacity
5d3c556 
Correct the K8s deployment section: the launcher terminates only its own
captured enclave ID (never others on the node), and on a run-enclave capacity
failure it fails loudly + logs describe-enclaves for Kubernetes to retry, rather
than force-terminating other enclaves.

Co-authored-by: Otto <otto@toolsforhumanity.com>
@piohei Otto
docs(proof): note bg-sleep + wait so SIGTERM runs the cleanup trap
0fb84de 
A foreground sleep infinity blocks the shell in waitpid(), deferring the
TERM/EXIT trap until the grace period + SIGKILL (leaking the enclave); the
backgrounded sleep + wait pattern lets the trap fire promptly on rollout /
eviction / liveness restart.

Co-authored-by: Otto <otto@toolsforhumanity.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@0xOsiris 0xOsiris 0xOsiris approved these changes
@Kemperino Kemperino Kemperino approved these changes
@0xForerunner 0xForerunner Awaiting requested review from 0xForerunner 0xForerunner is a code owner
@Dzejkop Dzejkop Awaiting requested review from Dzejkop Dzejkop is a code owner
@karankurbur karankurbur Awaiting requested review from karankurbur karankurbur is a code owner
@murph murph Awaiting requested review from murph murph is a code owner
@kilianglas kilianglas Awaiting requested review from kilianglas kilianglas is a code owner
@alessandromazza98 alessandromazza98 Awaiting requested review from alessandromazza98 alessandromazza98 is a code owner
@piohei piohei Awaiting requested review from piohei piohei is a code owner
@cichaczem cichaczem Awaiting requested review from cichaczem cichaczem is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@0xOsiris @Kemperino @piohei