State-Root Activation

This page is for operators activating, validating, and monitoring NOOSChain state-root engine changes.

Use it when starting a new chain with nervos-smt-v2, scheduling an existing iden3-v1 chain to migrate at an activation height, or deciding whether a node is safe to admit near a state-root activation boundary.

Related pages:

Need	Page
General state-root model	State Root
Nervos sidecar origin, build, and protocol	Nervos SMT Sidecar
Frozen sidecar contract	Nervos State-Root Contract
Sidecar repair	Nervos Sidecar Recovery
Planned activation runbook	Nervos Activation Runbook
Developer internals	State-Root Engine Migration

Activation Model

State-root engine selection is consensus-visible.

New chains can start with nervos-smt-v2 from genesis. Existing iden3-v1 chains must move through a governed activation height recorded in consensus state. Flipping local environment variables is not a migration because iden3-v1 and nervos-smt-v2 produce different roots for the same logical state.

After a Nervos activation block is finalized, there is no silent fallback to iden3-v1. A node that cannot execute the required engine must fail closed, stay out of validator traffic, and be repaired.

Operator Responsibilities

Operators own:

• deploying the correct Nervos sidecar binary;
• configuring the sidecar command and protocol version;
• provisioning a durable checkpoint directory;
• running readiness checks before activation;
• monitoring readiness at and after activation;
• backing up checkpoint files with the database;
• keeping validators out of traffic when readiness is red;
• repairing sidecar or checkpoint failures before resolving incidents.

NOOSChain TypeScript still executes transactions and emits ordered state mutations. The sidecar computes the SMT root, handles local checkpoints, and supports proof operations for the selected engine.

Commands

Build the sidecar:

npm run build:state-root-sidecar-nervos

Check readiness:

npm run noos -- state-root readiness --json
npm run noos -- state-root preflight

Run the production gate:

npm run noos -- production preflight --profile validator

Monitor:

npm run noos -- production monitor-report --json

Verify after activation or repair:

npm run noos -- chain verify
npm run noos -- chain replay-verify

Configuration

Core configuration:

NOOS_STATE_ROOT_ENGINE=nervos-smt-v2
NOOS_STATE_ROOT_SIDECAR_COMMAND=C:\path\to\noos-state-root-sidecar-nervos.exe
NOOS_STATE_ROOT_SIDECAR_PROTOCOL_VERSION=1
NOOS_STATE_ROOT_CHECKPOINT_DIR=D:\nooschain\state-root-checkpoints

On Linux/macOS, the command path normally points to:

external/state-root-sidecar-nervos/target/release/noos-state-root-sidecar-nervos

Supervisor configuration:

NOOS_STATE_ROOT_SIDECAR_TIMEOUT_MS=60000
NOOS_STATE_ROOT_SIDECAR_AUTO_RESTART=true
NOOS_STATE_ROOT_SIDECAR_MAX_RESTARTS=3
NOOS_STATE_ROOT_SIDECAR_RESTART_BACKOFF_MS=2000
NOOS_STATE_ROOT_SIDECAR_SUPERVISOR_ENABLED=auto
NOOS_STATE_ROOT_SIDECAR_HEALTH_INTERVAL_MS=10000
NOOS_STATE_ROOT_SIDECAR_PREWARM=false

NOOS_STATE_ROOT_SIDECAR_SUPERVISOR_ENABLED=auto starts the continuous supervisor when Nervos is scheduled or active. Use true to always start it and false only for controlled troubleshooting.

NOOS_STATE_ROOT_SIDECAR_PREWARM=true starts the supervisor before Nervos is scheduled or active so operators can validate the binary early.

Readiness Phases

State-root readiness is reported through node observability and the CLI.

Phase	Meaning	Operator posture
pre_activation	No active Nervos block yet, or a future activation is scheduled.	Red readiness is a launch or activation blocker, but may be fixed before height arrives.
activation_height_reached	The next block is the activation block and must use the scheduled engine.	Red readiness is a hard blocker. Do not produce/admit the activation block.
post_activation	The activation boundary has passed.	Red readiness is a hard blocker. Keep node out of validator traffic.
replay_or_restore	Replay or restore selects engine from stored metadata.	Fix engine/sidecar before trusting replay or restore.

For iden3-v1, readiness reports that no external sidecar is required. For nervos-smt-v2, readiness checks sidecar command, startup, version, protocol, checkpoint format, health, deterministic probe root, and checkpoint round-trip.

Decision Table

Situation	What to do
New chain starts with Nervos	Configure Nervos from genesis, run state-root preflight, run production preflight.
Existing iden3 chain migrates	Schedule a governed activation height; deploy and preflight every validator before the height arrives.
Readiness red before activation	Fix sidecar/config before activation height; do not proceed until green.
Readiness red at activation height	Keep affected validators out of traffic; do not finalize activation block from an unready node.
Readiness red after activation	Treat as consensus-safety blocker; repair sidecar and verify replay/sync before rejoin.
Checkpoint file missing	Rebuild from materialized state_leaves only after database integrity is confirmed.
Checkpoint file corrupt	Treat local checkpoint cache as unsafe; restore checkpoint backup or rebuild from verified state.
Snapshot imported after Nervos activation	Ensure sidecar is ready before the first post-import block.

Readiness Failures

Failed check	Meaning	First fix
Sidecar command missing	Configured binary path does not exist or is not executable.	Deploy sidecar binary and correct NOOS_STATE_ROOT_SIDECAR_COMMAND.
Version mismatch	Sidecar reports the wrong engine/protocol/checkpoint format.	Deploy sidecar built from the matching NOOSChain release.
Health check failed	Sidecar starts but does not report healthy state.	Inspect sidecar logs, permissions, data dir, and host pressure.
Probe root mismatch	Deterministic readiness mutation produced the wrong root.	Treat as binary/protocol mismatch; replace sidecar.
Checkpoint round-trip failed	Export/load checkpoint changed root or failed.	Check checkpoint directory, sidecar version, disk, permissions.
Timeout	Sidecar did not answer within configured timeout.	Inspect CPU, memory, disk latency, checkpoint size, and sidecar process state.

Example: New Chain Starts With Nervos

Use this when initializing a new chain that has no historical iden3-v1 blocks.

1. Build and deploy the sidecar:

   npm run build:state-root-sidecar-nervos

2. Configure the node:

   $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"

3. Check readiness:

   npm run noos -- state-root preflight
   npm run noos -- production preflight --profile validator

4. Start production traffic only after readiness and production preflight are green.

Example: Existing iden3 Chain Schedules Nervos Activation

Use this when an existing chain has iden3-v1 history.

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 readiness on every validator:

   npm run noos -- state-root readiness --json
   npm run noos -- state-root preflight

4. Submit the governed activation transaction. Payload shape:

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

5. Confirm the scheduled activation appears on every validator:

   npm run noos -- state-root status --json

6. Re-run production preflight as the activation height approaches:

   npm run noos -- production preflight --profile validator

7. Watch the activation block commit, then verify:

   npm run noos -- chain verify
   npm run noos -- chain replay-verify

For the detailed rollout sequence, use Nervos Activation Runbook.

Example: Prewarm Sidecar Before Activation

Use prewarm when you want process supervision and readiness evidence before the activation is scheduled or reached.

$env:NOOS_STATE_ROOT_SIDECAR_PREWARM="true"
$env:NOOS_STATE_ROOT_SIDECAR_SUPERVISOR_ENABLED="true"
npm run noos -- state-root preflight

Prewarming does not change consensus state. It only proves the configured sidecar can start, answer readiness probes, and perform checkpoint round-trips.

Example: Activation Height Approaching, Readiness Red

Use this when nextActivation exists and readiness fails before the activation height.

1. Keep the validator in service only if local policy permits and the chain is still pre-activation.

2. Fix the failed readiness check:

   • deploy missing binary;
   • correct sidecar command;
   • deploy matching protocol version;
   • fix checkpoint directory permissions;
   • resolve host CPU/memory/disk pressure.

3. Re-run:

   npm run noos -- state-root preflight
   npm run noos -- production preflight --profile validator

4. If readiness cannot be fixed before the activation height, remove the node from validator traffic or delay/cancel activation through the approved governance path if available.

Example: Wrong Sidecar Version Deployed

Symptoms:

• readiness reports sidecar version mismatch;
• monitor report emits a sidecar version alert;
• sidecar reports wrong engine, protocol version, or checkpoint format.

Actions:

npm run noos -- state-root preflight --json
npm run noos -- production monitor-report --json

Deploy the sidecar built from the same NOOSChain release, restart the supervisor or node, then verify:

npm run noos -- state-root preflight
npm run noos -- production preflight --profile validator

Never allow a wrong-version sidecar to execute post-activation blocks.

Example: Post-Activation Sidecar Failure

Use this when nervos-smt-v2 is active and the sidecar is missing, unresponsive, wrong-version, or unable to load checkpoints.

1. Keep the node out of validator traffic.

2. Collect evidence:

   npm run noos -- state-root status --json
   npm run noos -- state-root preflight --json
   npm run noos -- production monitor-report --json
   npm run noos -- support bundle --output noos-support-bundle.json

3. Repair using Nervos Sidecar Recovery.

4. Verify:

   npm run noos -- state-root preflight
   npm run noos -- chain replay-verify
   npm run noos -- production preflight --profile validator

5. Resolve any incident only after replay/sync and preflight are green.

Example: Snapshot Restore After Nervos Activation

After importing a post-activation snapshot, the imported checkpoint carries nervos-smt-v2 engine metadata. The first post-import block must continue with that engine, regardless of local environment defaults.

After restore:

npm run noos -- snapshots verify --file .\snapshot.noosnap.tar.gz
npm run noos -- state-root preflight
npm run noos -- chain verify
npm run noos -- chain replay-verify

If sidecar readiness is red, fix the sidecar before producing or admitting new blocks. Do not change local env back to iden3-v1 to bypass the problem.

Example: Checkpoint Directory Lost, Database Intact

Local Nervos checkpoint files are operational cache. Losing the directory is recoverable from materialized state_leaves, but slower.

1. Confirm database integrity:

   npm run noos -- chain verify
   npm run noos -- chain replay-verify

2. Recreate the checkpoint directory with correct permissions.

3. Run state-root preflight:

   npm run noos -- state-root preflight

4. Let the next successful Nervos execution export a new verified checkpoint.

If a checkpoint DB row points to a missing or corrupt file, the node should fail closed before execution. Do not mark the incident resolved until the checkpoint path is repaired or rebuilt from verified state.

Example: Delay Or Cancel Before Activation

If readiness cannot be made green before the activation height, delay or cancel only through the approved governance path if the protocol/governance flow supports it.

Do not:

• edit local database rows by hand;
• change local env to hide nextActivation;
• allow some validators to activate while others remain unready;
• finalize an activation block from a node with red readiness.

If governance does not support cancellation in the current deployment, keep unready validators out of traffic and follow the planned activation incident procedure.

Checkpoints And Snapshots

When the continuous supervisor is active, block execution uses the supervised sidecar through an exclusive execution lease. For each block, the node loads the latest verified checkpoint when available, applies ordered mutations, computes the root, exports a checkpoint, and records verified metadata.

NOOS_STATE_ROOT_CHECKPOINT_DIR should be backed up with the node database once Nervos is active. Checkpoint files are local cache, not consensus state. The node trusts only verified checkpoint rows whose file hash and loaded root still match recorded metadata.

Normal snapshots do not bundle local checkpoint files. They preserve consensus-critical engine metadata, block hash, state root, and materialized state_leaves. After importing a Nervos snapshot, a node can hydrate the sidecar from those leaves and export a fresh local checkpoint.

For snapshot operations, see Snapshots and Backup, Restore, And Recovery.

What Not To Do

• Do not change env to iden3-v1 after Nervos blocks exist.
• Do not manually edit block roots, checkpoint rows, or engine-version rows.
• Do not mark a state-root incident resolved before replay/sync is green.
• Do not treat checkpoint files as consensus state.
• Do not ignore sidecar version mismatch.
• Do not increase sidecar timeouts to hide deterministic execution stalls without benchmark evidence.
• Do not finalize an activation block from a node with red readiness.

Validation Commands

Use these for development and release validation, not as a replacement for operator preflight:

npm run test:state-root-engine-version
npm run test:state-root-engine-safety
npm run test:state-root-nervos-vectors
npm run test:state-root-persistent-sidecar
npm run test:state-root-nervos
npm run test:state-root-engine-activation
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

Production operators should still rely on:

npm run noos -- state-root preflight
npm run noos -- production preflight --profile validator
npm run noos -- production monitor-report --json