Skip to content

api: a token cache that follows every token standard, in any build - #128

Merged
EnzinoBB merged 3 commits into
masterfrom
fix/api-token-tracking
Oct 30, 2026
Merged

EnzinoBB merged 3 commits into
masterfrom
fix/api-token-tracking

Conversation

@EnzinoBB

Copy link
Copy Markdown
Collaborator

Summary

The token methods of the Thrift API (TokensListGet, TokenInfoGet, TokenBalancesGet, TokenHoldersGet, TokenTransfersGet, TokenWalletTransfersGet, TokenTransfersListGet, TokenTransferGet, TokenTransactionsGet) answer from a cache the node keeps next to the chain. It affects the API only, never consensus. Built on #126 and #127 (merge those first).

Availability

  • [api] tokens_cache=true turns the cache on in any build (off by default: the default behaviour does not change). RelMonitor/RelWallet builds keep it always on. Before, it existed only in those builds and every other node answered "This node doesn't provide such info".

Tokens the cache missed or got wrong

  • v1/v2 tokens (the current standard, BigDecimal amounts): transfer/transferFrom were transfers only with string amounts, so transfers were not counted, receivers never became holders and their balances were missing. Standards 3 and 4 are known (register() of standard 4 was ignored).
  • Only successful calls, and only the contract called, update the cache: failed calls counted transfers and added holders; the state of a contract reached through invokeExternalContract was booked with the caller's method; a deploy seen again reset a token.
  • Holders: the initiator and every argument that is a wallet address (also mint, airdrops, ...). Balances are always the contract's own (balanceOf), for the wallets a call involves (every holder of a token with up to 50), 50 per executor request. Before: all holders in one request with a 100 ms budget, so large tokens stopped updating.
  • approve() without arguments read params[0] out of bounds (crash risk on monitor/wallet nodes).
  • Amounts in BigDecimal.toString() exponent form (1E+3) were read as 0; 256 zeros overflowed a uint8_t.
  • A getter that fails keeps the known name/symbol/supply; the holders count is recounted instead of incremented and decremented.

Lists

  • TokensListGet filters before paging (count and pages ignored the filters) and with a correct filter logic; the token and holder lists sort with strict weak orderings (desc ^ (a < b) is not one: UB in std::multiset) and without std::stod exceptions.
  • TokenTransfersListGet: the signer is the sender (it was the token contract), only calls to tokens are listed, chain reads happen outside the cache lock.

Start

  • The balances are read again when the node runs, in the background, one token at a time under the lock (before: all under one lock in the reading thread, and never after a quick start at the last block).
  • A checkpoint without tokens (saved with the cache off) is rebuilt from the deployed contracts and their successful calls.

Docs: docs/tokens.md (standards, argument types, the cache, the tests), differences.md, CHANGES.md, README index.

Test plan

  • NODES=5 CONTRACTS=1 TOKENS=1 RESTART_NODES=5 RESTART_AT=100 TOKENS_VIA=5: 0 failures; through the restarted node: TokensListGet (standards 4 and 2, names, symbols), TokenBalancesGet (Alice 909.5 / 5.5, Bob 98.5 / 5, Carol 20), TokenInfoGet (4 holders, 3 transfers, supply 9999000), TokenTransfersGet (3), TokenHoldersGet; same states and balances on every node
  • Rebuild: a copy of a node run once with tokens_cache=false (checkpoint at block 1020 with no tokens), then started with true: API: token cache is empty, looking for tokens among 6 contracts, 2 tokens found, holders and balances equal to the contracts'
  • CI

🤖 Generated with Claude Code

The token methods of the API (TokensListGet, TokenBalancesGet, TokenHoldersGet, ...) answer
from a cache the node keeps next to the chain; it affects the API only, never consensus.

- [api] tokens_cache=true turns it on in any build (RelMonitor/RelWallet: always on); off,
  the methods answer "This node doesn't provide such info" as before.
- v1/v2 tokens: transfer/transferFrom with a BigDecimal amount are transfers (only string
  amounts were), standards 3 and 4 are known (register() of standard 4 was ignored).
- Only successful calls, and only the contract called, update it: a failed call counted
  transfers and added holders, the state of a contract reached by invokeExternalContract was
  booked with the caller's method, and a deploy seen twice reset a token.
- Holders: the initiator and every argument that is a wallet address (mint, airdrop, ...);
  balances are read from the contract for the wallets a call involves (every holder of a
  token with up to 50), 50 per executor request instead of all at once with a 100 ms budget.
  A getter that fails keeps the known name/symbol/supply; the holders count is recounted.
- approve() without arguments read params[0] out of bounds (crash on monitor/wallet nodes).
- Amounts in BigDecimal.toString() exponent form were read as 0; 256 zeros overflowed.
- TokensListGet filters before paging (count and pages ignored the filters) with fixed filter
  logic; the lists sort with strict weak orderings and without std::stod exceptions.
- TokenTransfersListGet: the signer is the sender (it was the token contract), and only
  calls to tokens are listed; chain reads happen outside the cache lock.
- At start the balances are read again in the background, a token at a time under the lock;
  a checkpoint without tokens (saved with the cache off) is rebuilt from the deployed
  contracts and their successful calls.
@EnzinoBB
EnzinoBB merged commit b92f821 into master Oct 30, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant