[Feat] Complete the typed read-only query surface

[al-onyxprotocol]

Summary

Complete the typed read-only query surface so that read-heavy consumers such as ADAMANT Explorer can use typed methods for every node query, without falling back to the generic api.get().

Motivation

These gaps were found while migrating ADAMANT Explorer to adamant-api v3, see Adamant-im/adamant-explorer#11. Closing them gives TypeScript consumers correct types for options the node already supports.

All node behavior below was verified against ADAMANT Node v0.10.0 (endless.adamant.im).

Detailed description

1. Shared CONTROL_PARAMETERS allows chat-only flags on /api/transactions

includeDirectTransfers and withoutDirectTransfers pass through the shared CONTROL_PARAMETERS set in src/api/utils.ts, but they are only valid for /api/chats/get and /api/chatrooms; node v0.10.0 rejects both on /api/transactions with Parameter is not supported. The type level is already scoped (ChatroomsOptions vs TransactionsOptions), but the runtime transformer is shared, so a typed getTransactions() call can produce a request the node rejects. Scope the control parameters per endpoint so /api/transactions requests cannot carry chat-only flags.

2. No typed method for accounts/top

The /api/accounts/top endpoint has no typed method or response DTO. Add getTopAccounts({limit, offset}). Note the endpoint is opt-in: the node registers the route only when started with topAccounts enabled (TOP=TRUE), since it sorts mem_accounts by balance on every request. The SDK method should exist regardless, like any other public API surface that depends on node configuration.

3. Option types miss parameters the node supports

• GetBlocksOptions: no orderBy (the explorer uses height:desc)
• GetDelegatesOptions: no orderBy (rate:asc)
• GetPeersOptions: no orderBy (ip:asc) and no state filter (?state=2 verified working); consider version and broadhash as well

The options pass through at runtime, so plain JavaScript works, but TypeScript consumers get type errors for valid queries.

4. searchDelegates has no limit

The node supports limit on /api/delegates/search (verified), but the method signature accepts only q.

5. Document the condition composition model, with examples

Measurements in this comment show how the node composes mixed and:/or: chains: conditions are concatenated into one flat WHERE string in query-string order, the first condition's prefix is ignored, no parentheses are added, and SQL precedence applies (AND binds tighter than OR). None of this is covered by the querying-transactions guide today.

Consequences that the guide must spell out with worked examples:

• Shapes like (A AND B) OR C are expressible by ordering conditions; A AND (B OR C) is not expressible at all
• With transformTransactionQuery, the wire order of conditions follows the JS object key insertion order, so {and: {…}, or: {…}} and {or: {…}, and: {…}} can return different result sets

A runtime warning when a query mixes both groups would turn a silent wrong-result into a visible hint, at no maintenance cost.

The node-side documentation counterpart for docs.adamant.im is tracked separately in the Adamant-im/docs repository.

6. New block subscriptions (blocked by the node)

WebSocketClient handles only newTrans. Once Adamant-im/adamant#256 adds a newBlock client WebSocket event, expose a block subscription API so explorers and pools can stop polling /api/blocks.

Alternatives

Keep using the generic api.get() for the uncovered queries: works, but bypasses typing, and the gaps stay invisible to TypeScript consumers.

Proposed technical implementation

• Scope control parameters per endpoint so /api/transactions requests cannot carry chat-only flags
• Add getTopAccounts() with a response DTO
• Add orderBy to GetBlocksOptions, GetDelegatesOptions, and GetPeersOptions; add state to GetPeersOptions
• Add limit to searchDelegates
• Document the condition composition model in the querying-transactions guide: flat WHERE string in query-string order, first-condition prefix ignored, SQL precedence, no grouping — with the worked examples from the measurements comment
• Document that the options-object key order defines the wire order of conditions, and therefore the query semantics
• Add a runtime warning when a query mixes and and or groups
• After [Feat] Emit newBlock events over the client WebSocket API adamant#256: add newBlock subscription support to WebSocketClient

Verification: typed calls return responses identical to the equivalent raw queries (equal count values on a v0.10.0 node), tsc passes for the new options, and the documentation site reflects the added parameters.

[al-onyxprotocol]

Removed the original item 1 (noClutter passthrough) after review.

The node's noClutter is an undocumented raw SQL clause (("t_amount" > 0 OR "t_type" < 8) in modules/transactions.js) and turned out to be both replaceable and unsafe:

• It joins the WHERE chain with the endpoint's default or combinator: and:inId=U…&noClutter=1 returns the global feed instead of the address's transactions (verified on v0.10.0). Exposing it in the SDK would bake in this foot-gun.
• The transfer views are expressible with the existing typed surface in a single request: getTransactions({types: [TransactionType.SEND, TransactionType.CHAT_MESSAGE], minAmount: 1, …}) — token transfers plus in-chat transfers, composable with any other and filters.

ADAMANT Explorer dropped noClutter entirely and now uses only typed getTransactions() calls; this also fixed the address transfers view, which previously showed unrelated global transactions.

[al-onyxprotocol]

One more finding worth a documentation note in the querying-transactions guide: how the node actually composes mixed and:/or: chains.

Measured on a v0.10.0 node (/api/transactions, total ≈1.5M rows at the time):

Query string order	Count	Effective SQL
and:inId=U…&and:minAmount=1&or:types=0..7	222,499	(inId AND amount>0) OR types IN (0..7)
or:types=0..7&and:inId=U…&and:minAmount=1	3,187	types IN (0..7) AND inId AND amount>0
or:minAmount=1&and:types=0..7	218,569	amount>0 AND types IN (0..7)
and:types=0..7&or:minAmount=1	227,833	types IN (0..7) OR amount>0

The model this confirms:

1. Conditions are concatenated into one flat WHERE string in query-string order
2. The first condition's prefix is irrelevant (nothing precedes it)
3. No parentheses are ever added; standard SQL precedence applies, so AND binds tighter than OR

Consequences for SDK users:

• Shapes like (A AND B) OR C are expressible by ordering conditions; A AND (B OR C) is not expressible at all
• With transformTransactionQuery, the wire order follows JS object key insertion order, so {and: {…}, or: {…}} and {or: {…}, and: {…}} can return different result sets — worth documenting explicitly, and possibly worth a runtime warning when both groups are present

[adamant-al]

Additional note from the Explorer fix work:

getTopAccounts({ offset, limit }) should not be treated as a pure SDK typing gap. There is also a Node-side request-shape problem on ADAMANT Node v0.10.0.

Verified on https://endless.adamant.im:

curl 'https://endless.adamant.im/api/accounts/top?offset=0&limit=1'

returns:

{"success":false,"error":"Expected type integer but found type string: #/offset"}

because /api/accounts/top sanitizes req.query with integer schema fields, while HTTP query parameters arrive as strings. Calling /api/accounts/top without query parameters works and returns the default first page. Sending a GET JSON body can avoid the schema error, but the public endpoint behavior still does not provide reliable offset/limit pagination through the normal HTTP query surface.

So this issue should add the typed SDK method, but a fully functional getTopAccounts({ offset, limit }) also needs an ADAMANT Node fix, for example coercing numeric query strings before schema validation or accepting numeric strings for GET query parameters. Until then, SDK consumers can only reliably fetch the default first top-accounts page from public nodes.

This affected adamant-explorer: Explorer now pages over the first public top-accounts page locally and documents that deeper pagination depends on a Node-side API fix.