Nervos Activation Runbook

Use this runbook when a chain will run or migrate to nervos-smt-v2.

New chains can start with Nervos from genesis. Existing iden3-v1 chains must activate Nervos only at a protocol-visible height boundary recorded in consensus state.

Preconditions

Before activation:

• all validators run a binary that supports both iden3-v1 and nervos-smt-v2;
• the Nervos sidecar binary is built and deployed on every validator;
• NOOS_STATE_ROOT_SIDECAR_COMMAND points to that binary;
• NOOS_STATE_ROOT_SIDECAR_PROTOCOL_VERSION=1;
• NOOS_STATE_ROOT_CHECKPOINT_DIR points to durable local storage;
• TLS/operator auth production preflight requirements pass.

Build the sidecar:

npm run build:state-root-sidecar-nervos

Linux shell:

npm run build:state-root-sidecar-nervos

New Chain Startup

For a new chain that starts with Nervos:

$env:NOOS_STATE_ROOT_ENGINE="nervos-smt-v2"
$env:NOOS_STATE_ROOT_SIDECAR_COMMAND="C:\path\to\noos-state-root-sidecar-nervos.exe"
$env:NOOS_STATE_ROOT_SIDECAR_PROTOCOL_VERSION="1"
$env:NOOS_STATE_ROOT_CHECKPOINT_DIR="D:\nooschain\state-root-checkpoints"
npm run noos -- state-root preflight
npm run noos -- production preflight --profile validator

The default engine is Nervos for new chains, but setting the env explicitly in deployment files makes the operator intent clear.

Existing Chain Activation

For an existing iden3 chain, schedule activation through governance. The exact transaction can be built with the generic noos tx command group. The payload shape is:

{
  "engineVersion": "nervos-smt-v2",
  "activationHeight": "12345",
  "reason": "planned state-root migration",
  "metadata": {
    "runbook": "nervos-activation"
  }
}

Operational sequence:

1. Choose an activation height far enough in the future for every validator to deploy and preflight.
2. Deploy the matching sidecar binary to every validator.
3. Run state-root preflight on every validator.
4. Submit the signed activation governance transaction.
5. Confirm /node/observability/consensus.stateRootEngine.nextActivation appears on every validator.
6. Re-run state-root preflight as the activation height approaches.
7. Run production preflight on every validator.
8. Watch the activation block commit.
9. Verify that post-activation blocks store state_root_engine_version = nervos-smt-v2.
10. Run chain/replay verification after activation.

Commands:

npm run noos -- state-root readiness --json
npm run noos -- state-root preflight
npm run noos -- production preflight --profile validator
npm run noos -- production monitor-report --json
npm run noos -- chain verify
npm run noos -- chain replay-verify

What To Watch

Before activation, readiness should show:

• targetEngine = nervos-smt-v2;
• ready = true;
• sidecar binary exists;
• sidecar version/protocol/checkpoint format match;
• deterministic probe root passes;
• checkpoint round trip passes.

At activation height, any red readiness check is a hard blocker. The node must not produce a block with a fallback engine.

After activation, monitor:

• stateRootEngine.current;
• stateRootEngine.readiness.phase;
• stateRootEngine.supervisor.state;
• stateRootEngine.supervisor.version;
• stateRootEngine.supervisor.health;
• stateRootEngine.checkpoint.latestVerified;
• production monitor-report alerts.

Rollback Limitations

There is no silent rollback after a Nervos block is finalized.

Do not:

• change local env to iden3-v1 after Nervos blocks exist;
• rewrite finalized block state roots;
• mark a state-root incident resolved before replay/sync is green;
• hide a failed activation by changing a local process default.

Rollback options are intentionally limited:

• before activation: cancel or supersede the planned governance process before the activation height, if the protocol/governance flow supports that path;
• at activation height before finalization: keep affected validators out of traffic until sidecars are fixed;
• after finalized Nervos blocks: recover the sidecar, replay/resync, or restore from a backup before the activation boundary and follow a deliberate recovery plan.

The safe default is to fix the sidecar and replay/resync, not to roll back the engine.

Validation Commands

npm run test:state-root-nervos-vectors
npm run test:state-root-persistent-sidecar
npm run test:state-root-activation-readiness
npm run test:state-root-engine-governance
npm run test-e2e:hardness-multiple-producers-noosraft
npm run test-e2e:hardness-multiple-producers-hashicorp-go

Use the multi-validator tests before a production activation rehearsal because they cover missing sidecar readiness, activation-block failure, post-activation readiness, snapshot/replay, and observer catch-up.