ADAMANT Node v0.10.2: safer recovery, richer APIs, and faster queries

[al-onyxprotocol]

ADAMANT Node v0.10.2 is now available:

Release: https://github.com/Adamant-im/adamant/releases/tag/v0.10.2

This release focuses on node liveness, faster recovery, safer database failure handling, richer observation APIs, and more efficient client subscriptions. It is intended for node operators, delegates, explorers, messengers, monitoring systems, and other services that integrate directly with ADAMANT nodes.

Upgrade policy: upgrading is recommended, but it is not mandatory for network compatibility. v0.10.2 contains no consensus fork and does not change block or transaction serialization, signatures, delegate ordering, rewards, fees, activation heights, slot timing, or deterministic replay.

1. Synchronization can recover instead of remaining wedged

A callback or database failure in the synchronization pipeline could previously leave a node permanently reporting that it was syncing while making no progress. In that state it rejected live blocks, never started another sync, and required a manual restart.

v0.10.2 addresses both the recovery path and a probable root cause:

• A progress-based watchdog detects a sync run that has applied no new block for five minutes.
• The stalled run is aborted using a run-scoped stop signal.
• No new state mutation may begin after the abort signal.
• In-flight block/account work drains before the loader releases its syncing state.
• Rejected PostgreSQL queries now propagate through block verification, block loading, and startup memory-table updates instead of silently parking callback chains.

These are liveness and error-propagation changes. They do not alter which blocks are valid.

References: sync watchdog PR #249, DB rejection handling PR #251.

2. Persisted checkpoints reduce recovery work after interrupted shutdowns

ADAMANT keeps consensus-derived state in mem_* tables. If a process is interrupted while those mirrors are being updated, the node must rebuild them from canonical blocks.

v0.10.2 adds three rotating checkpoint slots for derived memory state:

• Each checkpoint records the block height/ID, round, nethash, schema version, status, and canonical SHA-256 digest.
• Startup accepts only checkpoints whose metadata, digest, chain reference, network, and state invariants pass validation.
• A valid checkpoint is restored and only later blocks are replayed.
• Any validation or partial-replay failure falls back to the existing full deterministic rebuild.
• Unconfirmed junction tables are not checkpointed; they are rebuilt from confirmed state.

Canonical blocks and deterministic replay remain the source of truth. A checkpoint is only a local recovery cache and cannot redefine chain state.

Reference: checkpoint recovery PR #261.

3. REST APIs expose more useful state with fewer workarounds

Top accounts

GET /api/accounts/top is now available consistently on every node. It provides deterministic balance DESC, address ASC ordering, pagination, an isDelegate filter, count metadata, and limit=0 count-only requests.

• Node PR #260
• Documentation PR #29
• OpenAPI PR #44

Delegate correctness

The release fixes three important observation/API problems:

• GET /api/delegates/get again reports the delegate's real rank/rate and correct outsider productivity.
• GET /api/delegates/voters can no longer lose its address filter and return all accounts.
• GET /api/delegates/getNextForgers uses the next block height at round boundaries and reports a stable loading error before a chain tip exists.

References: delegate rank PR #253, delegate voters PR #255, status/delegate PR #266.

Consensus and reward visibility

Status and delegate APIs now expose:

• the active consensusCodeName;
• the effective consensus activation schedule after defaults and runtime overrides;
• the complete block reward milestone schedule;
• each delegate's lifetime forged amount as a base-10 integer string.

This makes explorer, monitoring, and client behavior less dependent on duplicated hard-coded schedules. It exposes the node's effective configuration without changing consensus behavior.

• Node PR #266
• Documentation PR #37
• OpenAPI PR #51

Blocks query performance and correctness

GET /api/blocks now honors numberOfTransactions=0. A new composite B-tree index on (text_generatorPublicKey, height DESC) also prevents the expensive full-table filtering path for an unknown generator combined with the default ordering.

The response contract is unchanged. On a large database, operators should allow time and disk space for the index migration during the first startup.

• Node PR #263
• Documentation PR #33
• OpenAPI PR #46

4. Client Socket.IO adds opt-in block and balance events

Services can now subscribe to:

• compact newBlock events;
• balances/change for balance, unconfirmedBalance, or both.

The node maintains dedicated subscription indexes so unrelated sockets are not scanned. Balance reads are batched around block apply/rollback, and event-publication failures are isolated from state mutation.

These events are best-effort and non-durable. Clients should restore subscriptions after reconnecting and use REST reconciliation for critical state.

• Node PR #264
• Documentation PR #35
• OpenAPI PR #48

5. Dependency and audit maintenance

Runtime and development dependencies were updated within their current major versions. The unused direct npm runtime dependency and its bundled subtree were removed, and a narrow compatible Grunt/js-yaml override was added.

The verified audit baseline changed from 4 moderate and 1 high finding to 0 moderate, high, or critical findings. No cryptographic protocol, signature, mnemonic, peer-handshake, or transaction-validation behavior changed.

Reference: dependency maintenance PR #262.

Operator notes

1. Continue using Node.js 22.13.0 or newer.
2. Back up the database using the normal operator procedure.
3. Stop the node gracefully and wait for Cleaned up successfully.
4. Allow the first v0.10.2 startup to finish migrations and checkpoint/index creation.
5. Plan additional disk space for three rotating derived-state checkpoint slots.
6. Verify /api/node/status, synchronization progress, live block processing, and the REST/Socket.IO capabilities used by your services.

Release references

• GitHub Release v0.10.2
• Release PR #269
• Release task #268
• Full comparison from v0.10.0
• ADAMANT Node documentation
• ADAMANT API schema

Questions and operator feedback are welcome below, especially around checkpoint storage, first-start migration time on large databases, sync recovery, and client event integration.