NOOSChain Docs

Appearance

iden3 State Root ​

iden3-v1 is NOOSChain's legacy JavaScript state-root engine. It uses the @iden3/js-merkletree sparse Merkle tree implementation through a NOOSChain adapter that converts canonical SHA-256 state keys and value hashes into iden3 field elements.

iden3-v1 is still implemented and recognized by the codebase. It is no longer the default for new chains; nervos-smt-v2 is the current default.

Where It Comes From ​

The iden3 engine is implemented in TypeScript and runs inside the Node.js process. The main adapter lives in:

text
src/chain/smt-state-store.ts

Persistent PostgreSQL SMT backing storage lives in:

text
src/chain/iden3-postgres-smt-db.ts

The adapter imports @iden3/js-merkletree, uses iden3's finite-field sparse Merkle tree, and exposes the same SmtStateStore interface used by the rest of NOOSChain state-root execution.

Why It Still Exists ​

iden3-v1 remains enabled because state-root engine metadata is part of chain history. A node must be able to verify the engine that actually produced an old block or snapshot.

It is used for:

  • legacy blocks whose state_root_engine_version is iden3-v1;
  • replay of pre-Nervos histories;
  • snapshot verification and import when the snapshot records iden3-v1;
  • activation-boundary flows where pre-activation blocks stay on iden3;
  • tests that prove iden3-to-Nervos migration does not happen silently;
  • benchmarks comparing iden3 and Nervos behavior.

For new chains, the default engine is nervos-smt-v2.

Runtime Boundary ​

Unlike the Nervos engine, iden3 does not require an external sidecar. It runs inside the TypeScript process and uses either in-memory iden3 storage or the NOOSChain PostgreSQL SMT backing adapter.

NOOSChain state keys and value hashes remain canonical SHA-256 hex strings. They are converted to iden3 field elements only inside the adapter boundary. That conversion is part of the iden3-v1 root scheme and must not be changed for old blocks.

Proof Boundary ​

The iden3 engine can generate and verify iden3 proof JSON through the @iden3/js-merkletree proof API. The current generic proof helper can still verify iden3 proof semantics when the requested engine is iden3-v1.

Nervos proofs use a different proof document and compiled proof encoding. Do not apply iden3 proof semantics to a nervos-smt-v2 root.

Migration Status ​

iden3-v1 has migration model same_root_scheme. That means another engine could theoretically replace it only if it produced byte-identical roots for the same state namespaces and mutation streams.

nervos-smt-v2 does not share that root scheme. Existing iden3 histories must cross an explicit activation height before producing Nervos blocks. Operators must not continue an existing iden3 chain by changing only NOOS_STATE_ROOT_ENGINE.

Audience-first NOOSChain documentation.

NOOSChain