Nooschain Developer Documentation
Use this section when you are changing NOOSChain itself. This is the place for protocol behavior, consensus adapters, state-root engines, replay, snapshots, runtime integration, test strategy, benchmarks, and release gates.
If you are running a node, start with Operators. If you are writing a smart contract, start with Smart Contract Developers. If you are trying to understand the product and architecture, start with General.
What Nooschain Developers Change
NOOSChain developers work on the code paths that decide whether every node in a network reaches the same block, state root, replay result, and operational signal.
The main areas are:
| Area | What changes here | Why it is risky |
|---|---|---|
| Protocol and transactions | Transaction schemas, validation, block effects, protocol versions. | A small behavior change can make old blocks replay differently. |
| Consensus adapters | Single-node, NoosRaft, HashiCorp Raft, membership reconciliation. | Nodes must agree on ordering and validator/runtime membership behavior. |
| State root and replay | State-root engines, sidecars, verification, deterministic replay. | Root mismatches can split the network or invalidate restore evidence. |
| Snapshots and restore | Snapshot contents, import/export, checkpoint metadata, replay after restore. | Restored nodes must rejoin without rewriting history. |
| Smart-contract runtime integration | Runtime requirements, sidecar handshake, host APIs, execution limits. | Contract execution is consensus-significant and must remain deterministic. |
| Observability and operator gates | Preflight, monitor reports, alerts, launch gates, readiness checks. | Operators need reliable signals before admitting traffic or validators. |
| Tests and release readiness | Unit, integration, E2E, soak, chaos, benchmarks, generated reference. | Release confidence depends on repeatable evidence, not only local success. |
Where To Start
| Task | Start here |
|---|---|
| Change protocol behavior or transaction semantics | Protocol Versioning |
| Add or change a consensus adapter | Raft Consensus Adapter Internals |
| Work on HashiCorp Raft behavior | HashiCorp Raft Engine |
| Change validator/runtime membership reconciliation | Raft Membership Reconciliation |
| Change state-root engine selection or activation | State-Root Engine Migration |
| Work on Nervos SMT benchmarking | Nervos SMT Benchmark Utility |
| Change snapshots, imports, exports, or restore assumptions | Snapshot Internals |
| Change replay verification or periodic verification | Periodic Chain Verification |
| Add or repair E2E coverage | E2E Testing |
| Stress multi-validator production paths | Multi-Validator Hardness E2E |
| Run long-lived stability checks | Stability Testing |
| Compare throughput or latency | Performance Benchmarks |
| Evaluate SMT implementations | SMT Candidate Evaluation |
| Prepare a release | Release Readiness |
| Review known cleanup work | Pre-v1 Tech Debt |
| Inspect generated APIs and internals | Generated Code Reference |
Engineering Invariants
Before changing internals, identify which invariants your change touches.
Replay must be deterministic. Replaying finalized blocks on a fresh node should produce the same transactions, effects, state roots, contract results, and verification evidence.
Protocol-visible behavior needs version discipline. If a change affects how a block is interpreted, how a transaction is validated, how state roots are computed, or how contract runtime requirements are enforced, treat it as a protocol change and update the protocol-versioning story.
Consensus results cannot depend on hidden local state. Local sidecars, payload availability, readiness caches, process health, operator tokens, and filesystem paths can affect whether a node is safe to serve traffic, but they must not silently change finalized block results.
State-root engines must fail closed. A node that cannot execute the active state-root engine or load a required sidecar must stop before producing unverifiable roots.
Snapshots must preserve verifiability. Import/export changes should keep enough metadata to verify the restored head, replay forward, and rebuild local caches such as sidecar checkpoints.
Operator signals must match real safety. If code adds a new failure mode, the relevant preflight, monitor report, alert, or readiness surface should expose it clearly enough for operators to act.
Development Workflow
- Identify the affected layer and read the nearest deep page.
- Decide whether the change is consensus-visible, operator-local, or both.
- Check protocol-versioning requirements before changing block, transaction, state-root, snapshot, or runtime behavior.
- Add focused tests around the smallest changed component.
- Add replay, sync, snapshot, or multi-node tests when behavior crosses module boundaries.
- Update operator, smart-contract developer, or general docs when user-visible behavior changes.
- Run the relevant release-readiness checks and keep evidence for review.
For behavior that spans layers, write down the boundary explicitly. For example, a smart-contract runtime preflight failure is local operator state; a runtime activation transaction is consensus state. The implementation and the docs should keep that difference visible.
Core Protocol
- Protocol Versioning explains when a behavior change needs a protocol-version story and how general/operator-facing protocol concepts relate to internal migration work.
- Release Readiness describes evidence expected before a release is treated as ready.
- Pre-v1 Tech Debt tracks cleanup and hardening work that should not be confused with shipped protocol guarantees.
Consensus
- Raft Consensus Adapter Internals explains the adapter boundary used by NOOSChain consensus backends.
- HashiCorp Raft Engine covers the Go HashiCorp Raft integration and runtime behavior.
- Raft Membership Reconciliation explains the boundary between governance validator state and runtime Raft membership.
When changing consensus code, test ordering, replay, membership, node restart, and operator observability. Consensus changes usually need both unit coverage and multi-node E2E coverage.
State, Replay, And Snapshots
- State-Root Engine Migration covers internal state-root engine activation and migration behavior.
- Snapshot Internals explains what snapshots contain, what they deliberately exclude, and how restore preserves verifiability.
- Periodic Chain Verification covers recurring verification and replay-oriented safety checks.
- Nervos SMT Benchmark Utility supports evaluation and comparison of SMT behavior.
Changes here should be reviewed with restore, replay, and state-root mismatch scenarios in mind. A successful happy-path block is not enough evidence when a change affects roots or snapshots.
Smart-Contract Runtime Integration
The smart-contract author docs explain manifests, packages, ABI, provenance, and SDK usage. NOOSChain developers usually touch the lower-level runtime integration:
- protocol-pinned runtime requirements;
- Wasmtime sidecar handshake and capabilities;
- host import surface;
- fuel and execution limits;
- deterministic call results, events, and state writes;
- operator preflight and readiness surfaces.
Start with the operator-facing Smart Contract Runtime Operations page for the operational contract, then use the generated reference for the implementation details.
Testing And Benchmarks
Use the narrowest test that proves the changed behavior, then add broader tests when the change crosses a consensus, replay, snapshot, sidecar, or operator boundary.
| Test class | Use it for |
|---|---|
| E2E Testing | End-to-end block production, transaction processing, sync, and replay flows. |
| Multi-Validator Hardness E2E | Multi-producer and multi-validator safety pressure. |
| E2E Hardness Testing | Hardening scenarios that combine production-like settings. |
| Failure Stress Testing | Failure injection and recovery behavior. |
| Size Stress Testing | Large payload, state, or chain-size pressure. |
| Stability Testing | Long-running confidence checks. |
| Performance Benchmarks | Throughput, latency, and regression comparisons. |
| Raft Chaos Testing | Raft-specific failure and churn scenarios. |
| HashiCorp Raft Chaos Testing | HashiCorp Raft sidecar/engine chaos scenarios. |
| Smart-Contract Fuzz And Soak | Contract runtime, host API, and workload pressure. |
Soak scenarios:
Review Checklist
Before merging a NOOSChain internals change, confirm:
- the consensus-visible surface is understood and documented;
- protocol-version impact is either ruled out or handled;
- deterministic replay has relevant coverage;
- state-root and snapshot implications are considered;
- sidecar/runtime compatibility is explicit when sidecars are involved;
- operator preflight, monitoring, readiness, or alerting is updated for new failure modes;
- docs are updated in the correct audience section;
- generated reference is rebuilt when exported APIs or JSDoc change;
- release-readiness evidence includes the tests that match the risk.
When in doubt, prefer a smaller protocol change with clearer migration and verification evidence over a broad change that is hard to replay, restore, or operate.