Complete typed read-only access to ADAMANT Node APIs

[dev-adamant-im]

adamant-api now provides a complete typed surface for the read-heavy ADAMANT Node APIs used by explorers, monitoring services, wallets, bots, and other integrations. Consumers no longer need generic api.get() calls or local response casts for the main account, block, delegate, peer, pool, and network-status queries introduced or expanded in ADAMANT Node v0.10.2.

What is now covered

Top accounts

The SDK exposes getTopAccounts() with typed pagination and delegate filtering:

const topDelegates = await api.getTopAccounts({
  limit: 50,
  offset: 0,
  isDelegate: 1,
});

const countOnly = await api.getTopAccounts({limit: 0});

The response includes the Node's deterministic balance ordering and pagination metadata. limit: 0 requests count-only metadata without returning account rows.

Blocks, delegates, peers, and pooled transactions

Public option types now cover the Node-supported filters and pagination controls for:

• block lists and block lookup;
• delegate lists, single-delegate lookup, username search, forging statistics, voters, and next-forger projections;
• connected peer lists and exact peer lookup;
• pooled transaction lists and lookups;
• inclusive transaction-time ranges.

This makes the SDK usable as the typed boundary for read-only services rather than only as a signing and broadcast helper.

Network and delegate state

The generated contracts now expose:

• consensusCodeName;
• the effective consensusSchedule;
• the complete block reward milestoneSchedule;
• delegate lifetime forged values as base-10 integer strings;
• the runtime producedblocks property instead of the previous generated producedlocks typo.

For example, a service can retrieve the public chain projection without locally redefining the response:

const [network, node] = await Promise.all([
  api.getStatus(),
  api.getNodeStatus(),
]);

console.log(network.consensusCodeName);
console.log(node.consensusSchedule, node.milestoneSchedule);

Endpoint-aware query semantics

The Node transaction query language is flat rather than a nested Boolean expression tree. It serializes conditions into one SQL expression in query-string order, with normal SQL precedence and no parentheses added for and: {} or or: {} objects.

The SDK therefore:

• combines ordinary top-level filters with and by default;
• preserves JavaScript object insertion order during serialization;
• warns when mixed and / or conditions make wire order semantically significant;
• scopes controls such as includeDirectTransfers, returnAsset, and userId to compatible endpoints;
• removes known unsupported controls before sending the request;
• permits amount filters only on /api/transactions, where the Node actually applies them.

This is intentionally stricter than forwarding every shared option to every endpoint. A typed call should represent behavior the selected Node route actually implements.

Schema provenance

src/api/generated.ts is reproducibly generated from:

Adamant-im/adamant-schema@f35b8ddb5597a8f1a80a3a670bedb003af65ef90

The repository verifies the generated file with npm run api-types:check, while package-consumer tests compile the exported declarations and exercise the built ESM and CommonJS entry points.

The producedlocks to producedblocks correction is a compile-time compatibility change. Consumers that construct delegate or status fixtures manually may also need to add the newly required fields. Runtime response handling remains pass-through: older Node responses are not transformed or rejected by the SDK.

Live state alongside snapshot reads

The same Node v0.10.2 alignment adds opt-in WebSocket handlers for compact newBlock events and confirmed or unconfirmed balances/change events. Subscriptions are restored after reconnecting, and balance values are absolute replacements rather than deltas.

These events complement the typed REST reads but do not replace them:

• there is no replay or initial balance snapshot;
• a balance payload can contain only the fields that changed;
• events delivered while disconnected are not backfilled;
• critical clients should reconcile blocks and balances through REST after reconnecting.

Compatibility boundaries

• New top-account, network-status, delegate, block, and balance-event capabilities require ADAMANT Node v0.10.2.
• Existing transaction construction, byte layout, hashing, IDs, signatures, encryption, retries, failover, and active-node selection are unchanged.
• The package root remains ADM-focused; external-coin helpers continue to use explicit subpath exports.
• The SDK requires Node.js 22.12.0 or newer. ADAMANT Node v0.10.2 operators should follow the Node's 22.13.0-or-newer requirement.

References

JavaScript SDK

• Typed read-only API implementation: Feat: Complete the typed read-only query surface adamant-api-jsclient#88
• Status and delegate contract synchronization: Feat: Sync JS API with Node status and delegate updates adamant-api-jsclient#90
• Complete integration diff: Release: adamant-api v3.1.0 adamant-api-jsclient#96
• API documentation: https://js.docs.adamant.im/api/
• Query semantics guide: https://js.docs.adamant.im/guide/querying-transactions
• WebSocket guide: https://js.docs.adamant.im/guide/websocket

Node, schema, and protocol documentation

• ADAMANT Node top accounts API: Feat: Add top accounts API adamant#260
• ADAMANT Node client WebSocket events: Feat: Add client WebSocket block and balance events adamant#264
• ADAMANT Node consensus schedules and delegate forged amounts: Feat: Expose consensus schedules and delegate forged amounts adamant#266
• OpenAPI top accounts contract: Feat: Add top accounts endpoint schema adamant-schema#44
• OpenAPI client WebSocket contracts: Feat: Define client WebSocket subscription and event schemas adamant-schema#48
• OpenAPI network and delegate contracts: Feat: Complete Node API status and query coverage adamant-schema#51
• Top accounts documentation: Docs: Add top accounts API reference docs#29
• Client WebSocket documentation: Docs: Document client WebSocket block and balance events docs#35
• Consensus and delegate documentation: Docs: Document status schedules and delegate API enhancements docs#37
• ADAMANT Node v0.10.2 technical notes: https://github.com/Adamant-im/adamant/releases/tag/v0.10.2