Release Readiness For Nooschain Developers

This page is for developers preparing a NOOSChain release candidate. It describes the evidence a codebase should produce before operators use it for production admission.

Operator node admission is a separate concern. Operators use Production Readiness and Production Release Readiness on real nodes with real configuration.

Developer release readiness answers:

Is this release candidate safe enough to hand to operators, with known protocol behavior, migrations, sidecars, tests, docs, and limitations?

Release Principles

A release is not ready just because it builds. A release candidate should prove that deterministic chain behavior, replay, migrations, sidecars, snapshots, operator gates, and docs agree with the code being shipped.

Release evidence should cover:

• TypeScript build and type safety;
• database migrations;
• protocol and replay compatibility;
• consensus and membership boundaries;
• state-root engines and sidecars;
• snapshots, backup, and restore;
• smart-contract runtime and package governance;
• TLS/security assumptions and secret handling;
• operator preflight, monitoring, and alert surfaces;
• performance, soak, and stability evidence;
• documentation and generated reference.

When a release cannot prove a safety boundary, the correct behavior is to fail closed, document the blocker, and keep the candidate out of production use.

Developer Vs Operator Gates

Audience	Owns	Main question
Developers	Builds, migrations, tests, replay evidence, sidecar compatibility, docs, release notes.	Does this release candidate preserve NOOSChain invariants?
Operators	Production .env, TLS, node identity, sidecar deployment, backup drills, admission preflight.	Is this particular node safe to admit right now?

Do not use operator preflight as a substitute for release testing. Do not use release tests as a substitute for operator admission on a real node.

Release Candidate Flow

1. Freeze the candidate commit or tag.
2. Install dependencies and build all release artifacts.
3. Run database migrations against clean and representative databases.
4. Run protocol, chain, and replay verification.
5. Run consensus and membership tests.
6. Run state-root engine, sidecar, activation, proof, and readiness tests.
7. Run snapshot export, verify, import, and restore coverage.
8. Run smart-contract runtime, package, provenance, and release gates when the release includes contract functionality.
9. Run performance, soak, and stability evidence appropriate to the risk.
10. Build docs and generated reference.
11. Write release notes with migration, activation, sidecar, and known-limit information.

For small patch releases, not every broad test is always required, but the evidence should match the blast radius of the change.

Baseline Command Matrix

Build and static checks:

npm run build
npm run typecheck
npm run admin:build
npm run web:build
npm run docs:build

Sidecar builds:

npm run build:raft-go
npm run build:state-root-sidecar-nervos
npm run build:contract-wasmtime-sidecar

Database and core verification:

npm run migrate
npm run verify:protocol
npm run verify:chain
npm run verify:replay
npm run verify:genesis

Consensus:

npm run test:raft
npm run test:raft:http
npm run test:raft:go
npm run test:raft:go:tcp-tls
npm run test:raft:membership
npm run test:raft:snapshot

State root:

npm run test:state-root-v1

Snapshots and restore:

npm run test:snapshots
npm run test:snapshots:large
npm run test:contract-backup-disaster-recovery

Smart contracts:

npm run test:contract-runtime-security
npm run test:contract-runtime-compatibility
npm run test:contract-runtime-governance
npm run test:contract-runtime-activation
npm run test:contract-runtime-rollout-policy
npm run test:contract-runtime-preflight
npm run test:contract-mainnet-launch-gate
npm run test:contract-runtime-provenance
npm run test:contract-release-candidate-gate
npm run test:contract-incident-drill-suite
npm run contracts:rc-gate
npm run contracts:incident-drills
npm run contracts:sidecar:provenance

Broader E2E and soak:

npm run test-e2e:all
npm run test-e2e:hardness-multiple-producers-noosraft
npm run test-e2e:hardness-multiple-producers-hashicorp-go
npm run soak:single-producer
npm run soak:multiple-producers-noosraft
npm run soak:multiple-producers-hashicorp-go

Performance:

npm run benchmark:v1-readiness
npm run benchmark:v1-readiness:check
npm run benchmark:snapshots
npm run benchmark:state-root-engine
npm run benchmark:payload-backfill
npm run benchmark:sync-catchup

Evidence By System

System	Release evidence
Protocol and replay	verify:protocol, verify:replay, protocol-version tests, docs for any changed semantics.
Database migrations	migrate from empty and representative schemas, migration review, snapshot/restore impact reviewed.
Consensus	Raft tests, HashiCorp Go tests, membership reconciliation tests, multi-producer E2E where ordering can change.
State root	test:state-root-v1, Nervos vectors, activation/readiness/governance tests, sidecar build evidence.
Snapshots and restore	test:snapshots, large snapshot tests, backup disaster recovery, snapshot internals updated for new tables.
Smart contracts	Runtime security/compatibility/governance tests, RC gate, incident drills, provenance evidence.
Security and transport	TLS/mTLS tests, auth tests, operator-token expectations, support-bundle redaction review.
Observability	Production preflight/monitoring code updated for new failure modes.
Performance	Benchmarks and soak evidence appropriate to the release risk.
Documentation	Audience docs and generated reference built from the release candidate.

Database And Migration Readiness

Release candidates must prove that migrations match the code being shipped.

Check:

• migrations apply in order on a clean schema;
• representative upgraded schemas reach the expected migration state;
• no code assumes a migration that is missing from src/db/migrations;
• new consensus tables are included in snapshots, replay, and state roots when applicable;
• rollback/downgrade limitations are documented when a migration is not reversible.

Operator preflight later verifies applied migrations on a real node. Developer release readiness proves the migration set itself is coherent before it reaches operators.

Protocol And Replay Readiness

Any change that can alter deterministic block execution needs protocol review.

Before release:

• old blocks replay with their stored protocol_version;
• new behavior is isolated to the intended protocol version or proven equivalent;
• unsupported versions fail closed;
• sync rejects unsupported or mismatched protocol metadata;
• conflict and verification paths report protocol mismatches clearly;
• docs explain activation or migration behavior.

Use Protocol Versioning for the implementation checklist.

Consensus And Membership Readiness

For production validator clusters, HashiCorp Go Raft is the current production candidate. Noosraft remains important for development, deterministic harnesses, and shared adapter safety.

Release evidence should prove:

• the Raft adapter still orders opaque NOOSChain block entries;
• TypeScript deterministic execution still verifies committed hash/root;
• HashiCorp sidecar lifecycle and restart paths are covered;
• TLS/mTLS coverage exists for Raft TCP when transport behavior changes;
• governance validator state and runtime membership remain separate;
• membership reconciliation refuses unsafe quorum changes.

Use Raft Consensus Adapter Internals, HashiCorp Raft Engine, and Raft Membership Reconciliation.

State-Root Readiness

nervos-smt-v2 is the default state-root engine for new chains. Existing iden3-v1 chains still require a governed activation boundary.

Developer release evidence should prove:

• engine identifiers and migration models are unchanged or explicitly versioned;
• Nervos deterministic vectors still match the frozen contract;
• sidecar protocol, checkpoint format, proof format, and empty-root semantics are pinned;
• activation readiness fails closed when sidecar requirements are not met;
• governed activation through SCHEDULE_STATE_ROOT_ENGINE_ACTIVATION works;
• replay, sync, and snapshots preserve state_root_engine_version.

Deployment configuration belongs in State-Root Activation. Internals live in State-Root Engine Migration.

Snapshot And Restore Readiness

Snapshot changes are release-sensitive because they affect backup, restore, Raft catch-up, and replay-from-checkpoint.

Before release:

• snapshot format and table definitions match current consensus state;
• new consensus tables are exported, verified, imported, and materialized into state leaves;
• snapshotHash remains canonical and stable;
• consensus_state_only and include_local_ciphertext rules are tested;
• import rollback safety is tested;
• post-import replay and chain verification work;
• Raft InstallSnapshot still verifies before import.

Use Snapshot Internals for the developer checklist.

Smart-Contract Release Evidence

When smart contracts are enabled or touched by the release, include runtime, package, and operator evidence.

Expected evidence includes:

• Wasmtime sidecar build and provenance;
• runtime compatibility and security tests;
• runtime activation, rollout policy, and preflight tests;
• mainnet launch-gate report;
• package provenance and registry tests;
• release workflow and migration tests;
• incident drill suite;
• contract backup/restore coverage.

Key pages:

• Smart Contract Runtime Operations
• Runtime Reproducible Builds
• Security Review Checklist
• Threat Model
• Audit Package
• Packages And Provenance
• Contract Registry

Security And Transport Readiness

Release candidates should preserve the production security posture:

• HTTPS support for TypeScript node APIs;
• mTLS support for operator, node-to-node, and Raft HTTP paths where used;
• TLS/mTLS support for HashiCorp Raft TCP transport;
• non-development operator-token behavior;
• no private keys, DEKs, operator tokens, plaintext payloads, or encrypted payload bytes in logs or support bundles;
• auth, clock skew, TLS, and node-auth tests passing.

Relevant commands:

npm run test:auth
npm run test:auth-clock
npm run test:tls
npm run test:pem-normalization
npm run test:raft:go:tcp-tls

Observability And Operator Gates

When a release adds a new safety failure mode, it should also add operator visibility.

Review whether the change needs updates to:

• production report;
• production preflight;
• production monitor-report;
• node health;
• support bundle evidence;
• incident diagnostics;
• Admin GUI surfaces;
• docs and runbooks.

Operators should be able to see enough detail to decide whether to admit, hold, repair, or roll back a node. A hidden failure mode is not release-ready.

Performance And Soak

Production preflight does not prove performance, and benchmarks do not prove correctness.

Before launch, keep explicit acceptance thresholds for:

• block commit p95;
• observer catch-up time;
• payload backfill throughput;
• snapshot export/import duration;
• replay verification duration;
• state-root sidecar restart recovery time;
• smart-contract call throughput and failure rate when contracts are enabled.

Use benchmark:v1-readiness and benchmark:v1-readiness:check for the draft v1 budget matrix. Use soak and hardness tests for long-running cluster behavior.

See Performance Benchmarks and V1 Performance Targets.

Release Artifact Boundary

Version these artifacts together:

• TypeScript node package;
• CLI;
• Admin GUI;
• Web GUI when included;
• HashiCorp Raft sidecar binary;
• Nervos state-root sidecar binary;
• Wasmtime contract sidecar binary;
• database migration set;
• generated API/reference docs;
• operator and developer docs.

Current compatibility gates verify node package version, CLI package version, database migrations, and supported snapshot archive format. Future hardening should add explicit version stamping for external sidecar binaries as those components expose stable release identifiers.

Release Notes Checklist

Before tagging or publishing, release notes should include:

• protocol-version changes or confirmation that none were made;
• database migration summary;
• state-root engine or sidecar changes;
• consensus/HashiCorp Raft changes;
• snapshot format or restore behavior changes;
• smart-contract runtime/package governance changes;
• operator preflight or monitor-report changes;
• required environment/configuration changes;
• known limitations and follow-up risks;
• exact command evidence retained for the candidate.

Review Checklist

Before handing a release candidate to operators, confirm:

• build, typecheck, sidecar builds, and docs build pass;
• migrations apply and are reviewed;
• protocol and replay evidence match the change;
• state-root and snapshot implications are covered;
• consensus and membership tests match the release risk;
• smart-contract gates pass when contracts are affected;
• operator preflight/monitoring surfaces expose new failures;
• generated reference and audience docs are current;
• performance/soak evidence is available where needed;
• release notes describe activation, migration, sidecar, and limitation details.

Anti-Patterns

Avoid these:

• treating production preflight as the whole release test plan;
• shipping protocol changes without replay evidence;
• shipping sidecar changes without vectors, provenance, and fail-closed tests;
• adding migrations without snapshot/restore consideration;
• adding consensus tables without state-root and snapshot updates;
• ignoring docs or generated reference drift;
• treating benchmarks as correctness tests;
• hiding known limitations from release notes;
• relying on local development database compatibility hacks.

Related Pages

• Nooschain Developers Overview
• Protocol Versioning
• Raft Consensus Adapter Internals
• State-Root Engine Migration
• Snapshot Internals
• Performance Benchmarks
• Production Readiness
• Production Release Readiness