Client WebSocket events for blocks and balances in ADAMANT Node

[massivedev0]

Summary

We implemented two related client WebSocket capabilities for ADAMANT Node:

• opt-in newBlock events for successfully applied and saved blocks;
• opt-in balances/change events for confirmed balance and unconfirmedBalance updates.

The implementation is available in Adamant-im/adamant#264, with synchronized documentation in Adamant-im/docs#35 and an OpenAPI 3.2 companion contract in Adamant-im/adamant-schema#48.

This work addresses Node issue #256 and Node issue #217.

Client subscription contract

The client API uses Socket.IO rather than a bare WebSocket connection. Subscriptions are scoped to one socket and must be restored after reconnecting.

New block events

Clients explicitly enable block notifications:

connection.emit('blocks', true);

connection.on('newBlock', (block) => {
  console.log('Applied block:', block);
});

newBlock contains a compact public header: block ID, height, timestamp, generator public key, transaction count, total amount, total fee, and reward. It intentionally omits the transaction list, signatures, and payload hash; clients can request the full block through REST when needed.

The node emits this event only after the complete block application pipeline succeeds and the block is saved. Historical replay and memory-table rebuilds do not produce live-looking block events.

Balance change events

Balance delivery requires both an address subscription and an explicit field subscription:

connection.emit('address', ['U1234567890123456']);
connection.emit('balances', ['balance', 'unconfirmedBalance']);

connection.on('balances/change', (account) => {
  console.log('Balance changed:', account);
});

Example payload:

{
  "address": "U1234567890123456",
  "balance": "100000000",
  "unconfirmedBalance": "99900000"
}

The payload includes only subscribed fields that changed. Values are decimal strings in 1/10^8 ADM units and currently use the same numeric account representation as the REST API.

balance represents confirmed blockchain state. unconfirmedBalance also reflects the node's current unconfirmed pool and may change when transactions are accepted, confirmed, expired, rolled back, or revalidated.

Delivery and performance design

The main implementation goal was to add useful events without turning every account mutation into a scan of every connected socket or an unnecessary database read.

• Dedicated block and per-address balance indexes select only interested sockets.
• The node skips account reads when no subscriber needs the changed address and field.
• Block application and rollback batch internal balance mutations and perform one final account read per changed address.
• Nested batch suppression is latched until the outer batch closes, preventing partial publication after an inner failure.
• Failed block application, failed rollback, replay, rebuild, and completed snapshot truncation suppress non-durable balance notifications.
• Socket matching, account lookup, and individual socket emission failures are isolated from block, round, and account processing.
• Round reward changes publish only after a completed durable round operation.

The changes do not modify consensus rules, block or transaction serialization, signatures, IDs, database schemas, rewards, fees, or peer protocol behavior.

Best-effort event semantics

These events are low-latency notifications, not a durable event log:

• clients can miss events during a disconnect and must reconcile important state through REST;
• balance subscriptions do not send an initial snapshot;
• asynchronous balance reads can complete out of order during rapid independent updates;
• duplicate transaction and block IDs are suppressed for at least 60 seconds, with periodic cleanup extending the effective window to approximately two minutes;
• if a block is rolled back and the same ID is re-applied inside that window, the second notification can be suppressed;
• the current balance string representation intentionally matches REST behavior; exact values beyond JavaScript's safe-integer range require a coordinated API-wide change rather than a WebSocket-only divergence.

We did not introduce an arbitrary silent per-socket subscription ceiling in this change. The current API has no acknowledgement mechanism for partial rejection, so a resource limit should be a separate configurable and documented contract with explicit client feedback.

Validation

Validation included:

• 226 passing feature-targeted Node tests covering WebSocket, account, transaction, block, and round paths;
• focused follow-up regression tests for snapshot suppression and nested batch discard;
• 940 passing tests in the current fast unit suite;
• full repository ESLint;
• a production VitePress documentation build;
• OpenAPI formatting and bundle validation;
• real Socket.IO integration coverage for block and balance delivery.

The longest unrelated test suites were intentionally skipped because this feature does not change consensus validation, serialization, SQL, peer transport, or REST endpoints.

References

• Feature implementation: Adamant-im/adamant#264
• newBlock issue: Adamant-im/adamant#256
• Balance subscriptions issue: Adamant-im/adamant#217
• Client WebSocket documentation: Adamant-im/docs#35
• OpenAPI/WebSocket schemas: Adamant-im/adamant-schema#48
• Node implementation source: modules/clientWs.js
• Documentation source: api/websocket.md
• Schema source: x-client-websocket

[adamantmm]

Well done!