@ledgerhq/coin-evm 5.3.4 → 5.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/lib/adapters/etherscan.d.ts.map +1 -1
  3. package/lib/adapters/etherscan.js +2 -1
  4. package/lib/adapters/etherscan.js.map +1 -1
  5. package/lib/config.d.ts +4 -0
  6. package/lib/config.d.ts.map +1 -1
  7. package/lib/config.js.map +1 -1
  8. package/lib/errors.d.ts +6 -0
  9. package/lib/errors.d.ts.map +1 -1
  10. package/lib/errors.js +12 -1
  11. package/lib/errors.js.map +1 -1
  12. package/lib/logic/getBlock.js +2 -2
  13. package/lib/logic/getBlock.js.map +1 -1
  14. package/lib/network/explorer/etherscan.d.ts.map +1 -1
  15. package/lib/network/explorer/etherscan.js +38 -24
  16. package/lib/network/explorer/etherscan.js.map +1 -1
  17. package/lib/network/explorer/ledger.d.ts.map +1 -1
  18. package/lib/network/explorer/ledger.js +6 -4
  19. package/lib/network/explorer/ledger.js.map +1 -1
  20. package/lib/network/node/rpc.common.d.ts.map +1 -1
  21. package/lib/network/node/rpc.common.js +30 -6
  22. package/lib/network/node/rpc.common.js.map +1 -1
  23. package/lib/network/node/types.d.ts +3 -1
  24. package/lib/network/node/types.d.ts.map +1 -1
  25. package/lib/network/node/types.js.map +1 -1
  26. package/lib/network/withRetries.d.ts.map +1 -1
  27. package/lib/network/withRetries.js +13 -0
  28. package/lib/network/withRetries.js.map +1 -1
  29. package/lib/types/etherscan.d.ts +2 -0
  30. package/lib/types/etherscan.d.ts.map +1 -1
  31. package/lib/utils.d.ts +0 -2
  32. package/lib/utils.d.ts.map +1 -1
  33. package/lib/utils.js +0 -30
  34. package/lib/utils.js.map +1 -1
  35. package/lib-es/adapters/etherscan.d.ts.map +1 -1
  36. package/lib-es/adapters/etherscan.js +2 -1
  37. package/lib-es/adapters/etherscan.js.map +1 -1
  38. package/lib-es/config.d.ts +4 -0
  39. package/lib-es/config.d.ts.map +1 -1
  40. package/lib-es/config.js.map +1 -1
  41. package/lib-es/errors.d.ts +6 -0
  42. package/lib-es/errors.d.ts.map +1 -1
  43. package/lib-es/errors.js +10 -0
  44. package/lib-es/errors.js.map +1 -1
  45. package/lib-es/logic/getBlock.js +2 -2
  46. package/lib-es/logic/getBlock.js.map +1 -1
  47. package/lib-es/network/explorer/etherscan.d.ts.map +1 -1
  48. package/lib-es/network/explorer/etherscan.js +39 -25
  49. package/lib-es/network/explorer/etherscan.js.map +1 -1
  50. package/lib-es/network/explorer/ledger.d.ts.map +1 -1
  51. package/lib-es/network/explorer/ledger.js +7 -5
  52. package/lib-es/network/explorer/ledger.js.map +1 -1
  53. package/lib-es/network/node/rpc.common.d.ts.map +1 -1
  54. package/lib-es/network/node/rpc.common.js +30 -6
  55. package/lib-es/network/node/rpc.common.js.map +1 -1
  56. package/lib-es/network/node/types.d.ts +3 -1
  57. package/lib-es/network/node/types.d.ts.map +1 -1
  58. package/lib-es/network/node/types.js.map +1 -1
  59. package/lib-es/network/withRetries.d.ts.map +1 -1
  60. package/lib-es/network/withRetries.js +10 -0
  61. package/lib-es/network/withRetries.js.map +1 -1
  62. package/lib-es/types/etherscan.d.ts +2 -0
  63. package/lib-es/types/etherscan.d.ts.map +1 -1
  64. package/lib-es/utils.d.ts +0 -2
  65. package/lib-es/utils.d.ts.map +1 -1
  66. package/lib-es/utils.js +0 -28
  67. package/lib-es/utils.js.map +1 -1
  68. package/package.json +1 -1
  69. package/src/adapters/etherscan.test.ts +67 -0
  70. package/src/adapters/etherscan.ts +3 -1
  71. package/src/api/getBlock.integ.test.ts +1 -1
  72. package/src/api/index.avalanche_c_chain_fuji.integ.test.ts +1 -1
  73. package/src/api/index.integ.test.ts +7 -12
  74. package/src/api/index.linea.integ.test.ts +1 -1
  75. package/src/api/index.monad_testnet.integ.test.ts +1 -1
  76. package/src/api/index.optimism.integ.test.ts +30 -1
  77. package/src/api/index.rsk.integ.test.ts +1 -1
  78. package/src/api/index.shape.integ.test.ts +1 -1
  79. package/src/api/index.somnia.integ.test.ts +40 -0
  80. package/src/api/index.zksync.integ.test.ts +42 -0
  81. package/src/config.ts +4 -0
  82. package/src/errors.ts +10 -0
  83. package/src/logic/getBlock.test.ts +49 -0
  84. package/src/logic/getBlock.ts +3 -2
  85. package/src/network/explorer/etherscan.test.ts +407 -91
  86. package/src/network/explorer/etherscan.ts +69 -33
  87. package/src/network/explorer/ledger.test.ts +24 -13
  88. package/src/network/explorer/ledger.ts +27 -22
  89. package/src/network/node/rpc.common.ts +35 -6
  90. package/src/network/node/rpc.test.ts +73 -0
  91. package/src/network/node/types.ts +10 -1
  92. package/src/network/withRetries.test.ts +63 -0
  93. package/src/network/withRetries.ts +12 -0
  94. package/src/staking/validators.integ.test.ts +1 -1
  95. package/src/types/etherscan.ts +2 -0
  96. package/src/utils.test.ts +0 -86
  97. package/src/utils.ts +0 -41
@@ -18,7 +18,11 @@ import {
18
18
  serializePagingToken,
19
19
  } from '../../adapters'
20
20
  import { getCoinConfig } from '../../config'
21
- import { EtherscanAPIError, EtherscanLikeExplorerUsedIncorrectly } from '../../errors'
21
+ import {
22
+ EtherscanAPIError,
23
+ EtherscanLikeExplorerUsedIncorrectly,
24
+ RateLimitError,
25
+ } from '../../errors'
22
26
  import { createMockEvmCoinConfig, mkExternalNode } from '../../fixtures/context.fixtures'
23
27
  import {
24
28
  etherscanCoinOperations,
@@ -141,6 +145,33 @@ describe('EVM Family', () => {
141
145
  // it should fail 2 times and succeed on the next try
142
146
  expect(spy).toHaveBeenCalledTimes(3)
143
147
  })
148
+
149
+ it('should surface a 429 HTTP response as RateLimitError without retrying', async () => {
150
+ const rateLimitError = Object.assign(new Error('Request failed with status code 429'), {
151
+ isAxiosError: true,
152
+ response: { status: 429 },
153
+ })
154
+ // axios is fully mocked — restore isAxiosError to its real behaviour for this test
155
+ jest
156
+ .spyOn(axios, 'isAxiosError')
157
+ .mockImplementation(
158
+ (e: unknown): boolean => typeof e === 'object' && e !== null && 'isAxiosError' in e
159
+ )
160
+ const spy = jest.spyOn(axios, 'request').mockRejectedValue(rateLimitError)
161
+
162
+ await expect(
163
+ ETHERSCAN_API.fetchWithRetries({}, ETHERSCAN_API.DEFAULT_RETRIES_API)
164
+ ).rejects.toBeInstanceOf(RateLimitError)
165
+ // must not retry — a rate-limit error is not transient
166
+ expect(spy).toHaveBeenCalledTimes(1)
167
+ })
168
+
169
+ it('should respect retries: 0 from explorer config and not retry on failure', async () => {
170
+ const spy = jest.spyOn(axios, 'request').mockRejectedValue(new Error('upstream error'))
171
+
172
+ await expect(ETHERSCAN_API.fetchWithRetries({}, 0)).rejects.toThrow('upstream error')
173
+ expect(spy).toHaveBeenCalledTimes(1)
174
+ })
144
175
  })
145
176
 
146
177
  describe.each([
@@ -1903,26 +1934,84 @@ describe('EVM Family', () => {
1903
1934
  jest.clearAllMocks()
1904
1935
  })
1905
1936
 
1937
+ // getOperations wraps everything its outer catch sees into InvalidExplorerResponse. A rate
1938
+ // limit must escape that wrapping, otherwise the caller loses the 429 status.
1939
+ it('propagates a RateLimitError instead of wrapping it in InvalidExplorerResponse', async () => {
1940
+ mockGetConfig.mockImplementation(() =>
1941
+ createMockEvmCoinConfig({
1942
+ chainId: 1,
1943
+ node: mkExternalNode({ uri: 'mock' }),
1944
+ explorer: { type: 'etherscan', uri: 'https://api.etherscan.io', retries: 0 },
1945
+ })
1946
+ )
1947
+ const rateLimitError = Object.assign(new Error('Request failed with status code 429'), {
1948
+ isAxiosError: true,
1949
+ response: { status: 429 },
1950
+ })
1951
+ // axios is fully mocked - restore isAxiosError to its real behaviour for this test
1952
+ jest
1953
+ .spyOn(axios, 'isAxiosError')
1954
+ .mockImplementation(
1955
+ (e: unknown): boolean => typeof e === 'object' && e !== null && 'isAxiosError' in e
1956
+ )
1957
+ jest.spyOn(axios, 'request').mockRejectedValue(rateLimitError)
1958
+
1959
+ await expect(
1960
+ ETHERSCAN_API.getOperations.force(
1961
+ getCoinConfig(currencyId).info,
1962
+ currencyId,
1963
+ address,
1964
+ 0,
1965
+ undefined,
1966
+ undefined,
1967
+ 1,
1968
+ 'asc'
1969
+ )
1970
+ ).rejects.toBeInstanceOf(RateLimitError)
1971
+ })
1972
+
1973
+ // An operation plus a stable identity: its position in the scenario's op list. The identity
1974
+ // is encoded in the tx hash so it survives the adapters and can be checked on the way out.
1975
+ // Indexing per response page instead would make the same operation change hash from page to
1976
+ // page, and would leave two ops of the same type at the same block indistinguishable — a
1977
+ // duplicate of one masking the omission of the other would then pass an exactly-once check.
1978
+ type IndexedOp = { type: OpType; block: number; uid: number }
1979
+ const opHash = (op: IndexedOp): string => `0x${op.type}${op.uid}`
1980
+
1906
1981
  // Helpers to create mock Etherscan responses with specific block heights for each operation type
1907
- const createMockCoinTxResponse = (blockNumbers: number[]) =>
1908
- blockNumbers.map((blockNumber, i) => ({
1982
+ const createMockCoinTxResponse = (ops: IndexedOp[]) =>
1983
+ ops.map((op) => ({
1909
1984
  ...etherscanCoinOperations[0],
1910
- blockNumber: String(blockNumber),
1911
- hash: `0xcoin${blockNumber}${i}`,
1985
+ blockNumber: String(op.block),
1986
+ hash: opHash(op),
1912
1987
  }))
1913
1988
 
1914
- const createMockInternalTxResponse = (blockNumbers: number[]) =>
1915
- blockNumbers.map((blockNumber, i) => ({
1989
+ const createMockInternalTxResponse = (ops: IndexedOp[]) =>
1990
+ ops.map((op) => ({
1916
1991
  ...etherscanInternalOperations[0],
1917
- blockNumber: String(blockNumber),
1918
- hash: `0xinternal${blockNumber}${i}`,
1992
+ blockNumber: String(op.block),
1993
+ hash: opHash(op),
1919
1994
  }))
1920
1995
 
1921
- const createMockTokenTxResponse = (blockNumbers: number[]) =>
1922
- blockNumbers.map((blockNumber, i) => ({
1996
+ const createMockTokenTxResponse = (ops: IndexedOp[]) =>
1997
+ ops.map((op) => ({
1923
1998
  ...etherscanTokenOperations[0],
1924
- blockNumber: String(blockNumber),
1925
- hash: `0xtoken${blockNumber}${i}`,
1999
+ blockNumber: String(op.block),
2000
+ hash: opHash(op),
2001
+ }))
2002
+
2003
+ const createMockERC721TxResponse = (ops: IndexedOp[]) =>
2004
+ ops.map((op) => ({
2005
+ ...etherscanERC721Operations[0],
2006
+ blockNumber: String(op.block),
2007
+ hash: opHash(op),
2008
+ }))
2009
+
2010
+ const createMockERC1155TxResponse = (ops: IndexedOp[]) =>
2011
+ ops.map((op) => ({
2012
+ ...etherscanERC1155Operations[0],
2013
+ blockNumber: String(op.block),
2014
+ hash: opHash(op),
1926
2015
  }))
1927
2016
 
1928
2017
  // Helper to identify endpoint type from URL - order matters due to substring matching
@@ -1935,16 +2024,28 @@ describe('EVM Family', () => {
1935
2024
  return 'unknown'
1936
2025
  }
1937
2026
 
1938
- // Type for blockchain operation representation in test scenarios
1939
- type BlockchainOp = { type: 'C' | 'I' | 'T'; block: number; toString: () => string }
2027
+ // Type for blockchain operation representation in test scenarios.
2028
+ // N = ERC-721 (tokennfttx), M = ERC-1155 (token1155tx); both are served by the same
2029
+ // NFT endpoint, which merges them into a single result.
2030
+ type OpType = 'C' | 'I' | 'T' | 'N' | 'M'
2031
+ type BlockchainOp = { type: OpType; block: number; toString: () => string }
1940
2032
 
1941
2033
  // Factory to create operation constants
1942
- const makeOp = (type: 'C' | 'I' | 'T', block: number): BlockchainOp => ({
2034
+ const makeOp = (type: OpType, block: number): BlockchainOp => ({
1943
2035
  type,
1944
2036
  block,
1945
2037
  toString: () => `${type}${block}`,
1946
2038
  })
1947
2039
 
2040
+ // Pins each op in a scenario to a stable identity. Op constants are shared singletons and a
2041
+ // scenario may list the same one twice, so identity has to come from the position in the
2042
+ // list rather than from the constant itself.
2043
+ const identify = (allOps: BlockchainOp[]): IndexedOp[] =>
2044
+ allOps.map((op, uid) => ({ type: op.type, block: op.block, uid }))
2045
+
2046
+ // How an op is labelled in exactly-once assertions: type, block and identity.
2047
+ const opLabel = (op: IndexedOp): string => `${op.type}${op.block}#${opHash(op)}`
2048
+
1948
2049
  // Operation constants for clean test syntax: C0, C1, ..., I0, I1, ..., T0, T1, ...
1949
2050
  const [C0, C1, C2, C3, C4, C5, C6, C7, C8, C9] = Array.from({ length: 10 }, (_, i) =>
1950
2051
  makeOp('C', i)
@@ -1955,6 +2056,12 @@ describe('EVM Family', () => {
1955
2056
  const [_T0, T1, T2, T3, T4, T5, T6, T7, T8, T9] = Array.from({ length: 10 }, (_, i) =>
1956
2057
  makeOp('T', i)
1957
2058
  )
2059
+ const [_N0, N1, N2, N3, N4, _N5, _N6, N7, N8, N9] = Array.from({ length: 10 }, (_, i) =>
2060
+ makeOp('N', i)
2061
+ )
2062
+ const [_M0, M1, M2, M3, M4, _M5, _M6, M7, M8, M9] = Array.from({ length: 10 }, (_, i) =>
2063
+ makeOp('M', i)
2064
+ )
1958
2065
 
1959
2066
  // Helper to convert ops to string array for assertions: ops(I6, I6, I6) => ["I6", "I6", "I6"]
1960
2067
  const ops = (...items: BlockchainOp[]) => items.map(String)
@@ -1962,6 +2069,7 @@ describe('EVM Family', () => {
1962
2069
  // Create intelligent mock that simulates blockchain based on given operations
1963
2070
  const createBlockchainMock = (allOps: BlockchainOp[], limit: number, order: 'asc' | 'desc') => {
1964
2071
  const pageCounts: Record<string, number> = {}
2072
+ const indexedOps = identify(allOps)
1965
2073
 
1966
2074
  return async (config: AxiosRequestConfig) => {
1967
2075
  const url: string = config.url ?? ''
@@ -1977,15 +2085,17 @@ describe('EVM Family', () => {
1977
2085
  const currentPage = pageCounts[key]
1978
2086
 
1979
2087
  // Filter ops by type and range
1980
- const typeMap: Record<string, 'C' | 'I' | 'T'> = {
2088
+ const typeMap: Record<string, OpType> = {
1981
2089
  coin: 'C',
1982
2090
  internal: 'I',
1983
2091
  token: 'T',
2092
+ erc721: 'N',
2093
+ erc1155: 'M',
1984
2094
  }
1985
2095
  const opType = typeMap[endpointType]
1986
2096
  if (!opType) return { data: { result: [] } }
1987
2097
 
1988
- const filteredOps = allOps
2098
+ const filteredOps = indexedOps
1989
2099
  .filter((op) => op.type === opType && op.block >= startBlock && op.block <= endBlock)
1990
2100
  .sort((a, b) => (order === 'desc' ? b.block - a.block : a.block - b.block))
1991
2101
 
@@ -1995,11 +2105,15 @@ describe('EVM Family', () => {
1995
2105
 
1996
2106
  // Convert to Etherscan response format
1997
2107
  if (opType === 'C') {
1998
- return { data: { result: createMockCoinTxResponse(pageOps.map((op) => op.block)) } }
2108
+ return { data: { result: createMockCoinTxResponse(pageOps) } }
1999
2109
  } else if (opType === 'I') {
2000
- return { data: { result: createMockInternalTxResponse(pageOps.map((op) => op.block)) } }
2110
+ return { data: { result: createMockInternalTxResponse(pageOps) } }
2111
+ } else if (opType === 'N') {
2112
+ return { data: { result: createMockERC721TxResponse(pageOps) } }
2113
+ } else if (opType === 'M') {
2114
+ return { data: { result: createMockERC1155TxResponse(pageOps) } }
2001
2115
  } else {
2002
- return { data: { result: createMockTokenTxResponse(pageOps.map((op) => op.block)) } }
2116
+ return { data: { result: createMockTokenTxResponse(pageOps) } }
2003
2117
  }
2004
2118
  }
2005
2119
  }
@@ -2045,9 +2159,14 @@ describe('EVM Family', () => {
2045
2159
  ...result.lastCoinOperations.map((op) => ({ type: 'C', block: op.tx.block.height })),
2046
2160
  ...result.lastInternalOperations.map((op) => ({ type: 'I', block: op.tx.block.height })),
2047
2161
  ...result.lastTokenOperations.map((op) => ({ type: 'T', block: op.tx.block.height })),
2162
+ // The NFT endpoint merges ERC-721 and ERC-1155; tell them apart by asset type
2163
+ ...result.lastNftOperations.map((op) => ({
2164
+ type: op.asset.type === 'erc1155' ? 'M' : 'N',
2165
+ block: op.tx.block.height,
2166
+ })),
2048
2167
  ]
2049
- // Secondary sort order: C < I < T (coin first at same block)
2050
- const typeOrder: Record<string, number> = { C: 0, I: 1, T: 2 }
2168
+ // Secondary sort order: C < I < T < N < M (coin first at same block)
2169
+ const typeOrder: Record<string, number> = { C: 0, I: 1, T: 2, N: 3, M: 4 }
2051
2170
  const ops = tagged
2052
2171
  .filter((op): op is { type: string; block: number } => op.block !== undefined)
2053
2172
  .sort((a, b) => b.block - a.block || typeOrder[a.type] - typeOrder[b.type])
@@ -2056,16 +2175,45 @@ describe('EVM Family', () => {
2056
2175
  return { ops, pagingState }
2057
2176
  }
2058
2177
 
2059
- // Helper to create expected paging state (nft is always true/done in tests)
2178
+ // Same ordering as summarize, but each op keeps the identity the mock gave it. Exactly-once
2179
+ // assertions need this: type + block alone cannot tell two ops in the same block apart.
2180
+ const summarizeIdentified = (result: {
2181
+ lastCoinOperations: Array<Operation<MemoNotSupported>>
2182
+ lastTokenOperations: Array<Operation<MemoNotSupported>>
2183
+ lastInternalOperations: Array<Operation<MemoNotSupported>>
2184
+ lastNftOperations: Array<Operation<MemoNotSupported>>
2185
+ }): string[] => {
2186
+ const tagged = [
2187
+ ...result.lastCoinOperations.map((op) => ({ type: 'C', op })),
2188
+ ...result.lastInternalOperations.map((op) => ({ type: 'I', op })),
2189
+ ...result.lastTokenOperations.map((op) => ({ type: 'T', op })),
2190
+ ...result.lastNftOperations.map((op) => ({
2191
+ type: op.asset.type === 'erc1155' ? 'M' : 'N',
2192
+ op,
2193
+ })),
2194
+ ]
2195
+ const typeOrder: Record<string, number> = { C: 0, I: 1, T: 2, N: 3, M: 4 }
2196
+ return tagged
2197
+ .filter((entry) => entry.op.tx.block.height !== undefined)
2198
+ .sort(
2199
+ (a, b) =>
2200
+ (b.op.tx.block.height ?? 0) - (a.op.tx.block.height ?? 0) ||
2201
+ typeOrder[a.type] - typeOrder[b.type]
2202
+ )
2203
+ .map((entry) => `${entry.type}${entry.op.tx.block.height}#${entry.op.tx.hash}`)
2204
+ }
2205
+
2206
+ // Helper to create expected paging state. Every flag is spelled out: nft varies like the
2207
+ // others now that the endpoint is gated only by supportedTokens, and a default would hide it.
2060
2208
  const paging = (
2061
2209
  boundBlock: number,
2062
- flags: { coin: boolean; internal: boolean; token: boolean }
2210
+ flags: { coin: boolean; internal: boolean; token: boolean; nft: boolean }
2063
2211
  ): PagingState => ({
2064
2212
  boundBlock,
2065
2213
  coinIsDone: flags.coin,
2066
2214
  internalIsDone: flags.internal,
2067
2215
  tokenIsDone: flags.token,
2068
- nftIsDone: true,
2216
+ nftIsDone: flags.nft,
2069
2217
  })
2070
2218
 
2071
2219
  describe('desc mode', () => {
@@ -2074,11 +2222,11 @@ describe('EVM Family', () => {
2074
2222
  const result = await callGetOperations('desc')([I6, I6, I6, I5, T5, C4, C3, C2])
2075
2223
  // - coin([Ø, Ø]) [C4 C3 C2] boundBlock=2, isPageFull=true, hasMorePage=true (full page)
2076
2224
  // - internal([2, Ø]) [I6 I6 I6] boundBlock=6, isPageFull=true, hasMorePage=true (full page, higher boundBlock)
2077
- // - token([6, Ø]) [] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded, T5 excluded)
2225
+ // - token([6, Ø]) [] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T5 at block 5 not yet reached)
2078
2226
  // Result: only I6s kept, coin ops dropped (below boundBlock=6)
2079
2227
  expect(summarize(result)).toEqual({
2080
2228
  ops: ops(I6, I6, I6),
2081
- pagingState: paging(5, { coin: false, internal: false, token: true }),
2229
+ pagingState: paging(5, { coin: false, internal: false, token: false, nft: false }),
2082
2230
  })
2083
2231
  })
2084
2232
 
@@ -2086,11 +2234,11 @@ describe('EVM Family', () => {
2086
2234
  const result = await callGetOperations('desc')([T7, I6, I6, I6, T5, C4, C3, C2, I2])
2087
2235
  // - coin([Ø, Ø]) [C4 C3 C2] boundBlock=2, isPageFull=true, hasMorePage=true (full page)
2088
2236
  // - internal([2, Ø]) [I6 I6 I6] boundBlock=6, isPageFull=true, hasMorePage=true (full page, higher boundBlock)
2089
- // - token([6, Ø]) [T7] boundBlock=Ø, isPageFull=false, hasMorePage=false (T7 >= 6)
2237
+ // - token([6, Ø]) [T7] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T5 at block 5 not yet reached)
2090
2238
  // Result: T7 + I6s kept, coin ops dropped (below boundBlock=6)
2091
2239
  expect(summarize(result)).toEqual({
2092
2240
  ops: ops(T7, I6, I6, I6),
2093
- pagingState: paging(5, { coin: false, internal: false, token: true }),
2241
+ pagingState: paging(5, { coin: false, internal: false, token: false, nft: false }),
2094
2242
  })
2095
2243
  })
2096
2244
 
@@ -2110,11 +2258,11 @@ describe('EVM Family', () => {
2110
2258
  ])
2111
2259
  // - coin([Ø, Ø]) [C3 C2 C1] boundBlock=1, isPageFull=true, hasMorePage=true (full page)
2112
2260
  // - internal([1, Ø]) [I6 I5 I4] boundBlock=4, isPageFull=true, hasMorePage=true (full page)
2113
- // - token([4, Ø]) [T9 T8 T7] boundBlock=7, isPageFull=true, hasMorePage=true (full page, highest boundBlock)
2261
+ // - token([4, Ø]) [T9 T8 T7] boundBlock=7, isPageFull=true, hasMorePage=true (constrained by internal's bound, T1 at block 1 not yet reached)
2114
2262
  // Result: only T9/T8/T7 kept, coin+internal ops dropped (below boundBlock=7)
2115
2263
  expect(summarize(result)).toEqual({
2116
2264
  ops: ops(T9, T8, T7),
2117
- pagingState: paging(6, { coin: false, internal: false, token: true }),
2265
+ pagingState: paging(6, { coin: false, internal: false, token: false, nft: false }),
2118
2266
  })
2119
2267
  })
2120
2268
 
@@ -2139,7 +2287,7 @@ describe('EVM Family', () => {
2139
2287
  // Result: ops >= 7 kept, lower ops dropped (below boundBlock=7)
2140
2288
  expect(summarize(result)).toEqual({
2141
2289
  ops: ops(T9, I8, T8, C7, I7, T7),
2142
- pagingState: paging(6, { coin: false, internal: false, token: false }),
2290
+ pagingState: paging(6, { coin: false, internal: false, token: false, nft: false }),
2143
2291
  })
2144
2292
  })
2145
2293
  })
@@ -2148,12 +2296,12 @@ describe('EVM Family', () => {
2148
2296
  it('keeps all when subsequent pages are not full', async () => {
2149
2297
  const result = await callGetOperations('desc')([I6, I6, T5, C4, C3, C2, C1, T1])
2150
2298
  // - coin([Ø, Ø]) [C4 C3 C2] boundBlock=1, isPageFull=true, hasMorePage=true (full page)
2151
- // - internal([1, Ø]) [I6 I6] boundBlock=1, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2152
- // - token([1, Ø]) [T5] boundBlock=1, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2299
+ // - internal([1, Ø]) [I6 I6] boundBlock=1, isPageFull=false, hasMorePage=true (constrained by coins's bound, C1/T1 not yet reached)
2300
+ // - token([1, Ø]) [T5] boundBlock=1, isPageFull=false, hasMorePage=true (constrained by coins's bound, T1 not yet reached)
2153
2301
  // Result: all ops kept, boundBlock stays at 1 because subsequent pages not full
2154
2302
  expect(summarize(result)).toEqual({
2155
2303
  ops: ops(I6, I6, T5, C4, C3, C2),
2156
- pagingState: paging(1, { coin: false, internal: true, token: true }),
2304
+ pagingState: paging(1, { coin: false, internal: false, token: false, nft: false }),
2157
2305
  })
2158
2306
  })
2159
2307
 
@@ -2169,12 +2317,12 @@ describe('EVM Family', () => {
2169
2317
  it('keeps all when only coin has ops', async () => {
2170
2318
  const result = await callGetOperations('desc')([C4, C3, C2, C1])
2171
2319
  // - coin([Ø, Ø]) [C4 C3 C2] boundBlock=1, isPageFull=true, hasMorePage=true (full page)
2172
- // - internal([1, Ø]) [] boundBlock=1, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2173
- // - token([1, Ø]) [] boundBlock=1, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2320
+ // - internal([1, Ø]) [] boundBlock=1, isPageFull=false, hasMorePage=true (constrained by coins's bound, C1 not yet reached)
2321
+ // - token([1, Ø]) [] boundBlock=1, isPageFull=false, hasMorePage=true (constrained by coins's bound)
2174
2322
  // Result: coin ops kept, nextPagingToken=1 for remaining C1
2175
2323
  expect(summarize(result)).toEqual({
2176
2324
  ops: ops(C4, C3, C2),
2177
- pagingState: paging(1, { coin: false, internal: true, token: true }),
2325
+ pagingState: paging(1, { coin: false, internal: false, token: false, nft: false }),
2178
2326
  })
2179
2327
  })
2180
2328
 
@@ -2186,19 +2334,19 @@ describe('EVM Family', () => {
2186
2334
  // Result: token ops kept, nextPagingToken=1 for remaining T1
2187
2335
  expect(summarize(result)).toEqual({
2188
2336
  ops: ops(T4, T3, T2),
2189
- pagingState: paging(1, { coin: true, internal: true, token: false }),
2337
+ pagingState: paging(1, { coin: true, internal: true, token: false, nft: false }),
2190
2338
  })
2191
2339
  })
2192
2340
 
2193
2341
  it('cascades without dropping when blocks interleave nicely', async () => {
2194
2342
  const result = await callGetOperations('desc')([T6, C5, I5, C4, I4, C3, I2, I1, C1, T1])
2195
2343
  // - coin([Ø, Ø]) [C5 C4 C3] boundBlock=3, isPageFull=true, hasMorePage=true (full page)
2196
- // - internal([3, Ø]) [I5 I4] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2197
- // - token([3, Ø]) [T6] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2344
+ // - internal([3, Ø]) [I5 I4] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound, I2/I1 not yet reached)
2345
+ // - token([3, Ø]) [T6] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound, T1 not yet reached)
2198
2346
  // Result: all ops >= 3 kept, interleaved blocks don't cause drops
2199
2347
  expect(summarize(result)).toEqual({
2200
2348
  ops: ops(T6, C5, I5, C4, I4, C3),
2201
- pagingState: paging(2, { coin: false, internal: true, token: true }),
2349
+ pagingState: paging(2, { coin: false, internal: false, token: false, nft: false }),
2202
2350
  })
2203
2351
  })
2204
2352
 
@@ -2206,11 +2354,11 @@ describe('EVM Family', () => {
2206
2354
  const result = await callGetOperations('desc')([T6, I6, C5, C4, I4, I3, I2, I1, T1])
2207
2355
  // - coin([Ø, Ø]) [C5 C4] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2208
2356
  // - internal([Ø, Ø]) [I6 I4 I3] boundBlock=3, isPageFull=true, hasMorePage=true (full page)
2209
- // - token([3, Ø]) [T6] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2357
+ // - token([3, Ø]) [T6] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T1 not yet reached)
2210
2358
  // Result: all ops >= 3 kept, boundBlock from internal applies
2211
2359
  expect(summarize(result)).toEqual({
2212
2360
  ops: ops(I6, T6, C5, C4, I4, I3),
2213
- pagingState: paging(2, { coin: true, internal: false, token: true }),
2361
+ pagingState: paging(2, { coin: true, internal: false, token: false, nft: false }),
2214
2362
  })
2215
2363
  })
2216
2364
 
@@ -2218,11 +2366,11 @@ describe('EVM Family', () => {
2218
2366
  const result = await callGetOperations('desc')([I6, C5, C4, I4, I3, I2, I1, T1])
2219
2367
  // - coin([Ø, Ø]) [C5 C4] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2220
2368
  // - internal([Ø, Ø]) [I6 I4 I3] boundBlock=3, isPageFull=true, hasMorePage=true (full page)
2221
- // - token([3, Ø]) [] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded, T1 excluded)
2369
+ // - token([3, Ø]) [] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T1 not yet reached)
2222
2370
  // Result: coin + internal ops kept
2223
2371
  expect(summarize(result)).toEqual({
2224
2372
  ops: ops(I6, C5, C4, I4, I3),
2225
- pagingState: paging(2, { coin: true, internal: false, token: true }),
2373
+ pagingState: paging(2, { coin: true, internal: false, token: false, nft: false }),
2226
2374
  })
2227
2375
  })
2228
2376
 
@@ -2242,12 +2390,12 @@ describe('EVM Family', () => {
2242
2390
  I1,
2243
2391
  ])
2244
2392
  // - coin([Ø, Ø]) [C4 C4 C4] boundBlock=4, isPageFull=true, hasMorePage=true (full page)
2245
- // - internal([4, Ø]) [I4 I4 I4] boundBlock=4, isPageFull=true, hasMorePage=true (full page, same boundBlock)
2246
- // - token([4, Ø]) [T4 T4 T4] boundBlock=4, isPageFull=true, hasMorePage=true (full page, same boundBlock)
2393
+ // - internal([4, Ø]) [I4 I4 I4] boundBlock=4, isPageFull=true, hasMorePage=true (constrained by coins's bound, I1 not yet reached)
2394
+ // - token([4, Ø]) [T4 T4 T4] boundBlock=4, isPageFull=true, hasMorePage=true (constrained by coins's bound, T1 not yet reached)
2247
2395
  // Result: all 9 ops at block 4 kept, all at boundBlock=4
2248
2396
  expect(summarize(result)).toEqual({
2249
2397
  ops: ops(C4, C4, C4, I4, I4, I4, T4, T4, T4),
2250
- pagingState: paging(3, { coin: false, internal: true, token: true }),
2398
+ pagingState: paging(3, { coin: false, internal: false, token: false, nft: false }),
2251
2399
  })
2252
2400
  })
2253
2401
 
@@ -2264,7 +2412,7 @@ describe('EVM Family', () => {
2264
2412
  describe('with pagination token', () => {
2265
2413
  it('skips coin endpoint when it is done', async () => {
2266
2414
  const result = await callGetOperations('desc')([C1], {
2267
- pagingState: paging(5, { coin: true, internal: false, token: false }),
2415
+ pagingState: paging(5, { coin: true, internal: false, token: false, nft: true }),
2268
2416
  })
2269
2417
  expect(summarize(result)).toEqual({
2270
2418
  ops: ops(),
@@ -2274,7 +2422,7 @@ describe('EVM Family', () => {
2274
2422
 
2275
2423
  it('skips internal endpoint when it is done', async () => {
2276
2424
  const result = await callGetOperations('desc')([I1], {
2277
- pagingState: paging(5, { coin: false, internal: true, token: false }),
2425
+ pagingState: paging(5, { coin: false, internal: true, token: false, nft: true }),
2278
2426
  })
2279
2427
  expect(summarize(result)).toEqual({
2280
2428
  ops: ops(),
@@ -2284,7 +2432,7 @@ describe('EVM Family', () => {
2284
2432
 
2285
2433
  it('skips token endpoint when it is done', async () => {
2286
2434
  const result = await callGetOperations('desc')([T1], {
2287
- pagingState: paging(5, { coin: false, internal: false, token: true }),
2435
+ pagingState: paging(5, { coin: false, internal: false, token: true, nft: true }),
2288
2436
  })
2289
2437
  expect(summarize(result)).toEqual({
2290
2438
  ops: ops(),
@@ -2296,17 +2444,19 @@ describe('EVM Family', () => {
2296
2444
  const result = await callGetOperations('desc')(
2297
2445
  [T6, I6, C6, C5, I5, C4, I4, C3, I2, I1, C1, T1],
2298
2446
  {
2299
- pagingState: paging(5, { coin: false, internal: false, token: false }),
2447
+ pagingState: paging(5, { coin: false, internal: false, token: false, nft: true }),
2300
2448
  }
2301
2449
  )
2302
2450
  // pagingState.boundBlock=5 acts as toBlock for all endpoints
2303
2451
  // - coin([Ø, 5]) [C5 C4 C3] boundBlock=3, isPageFull=true, hasMorePage=true (full page)
2304
- // - internal([3, 5]) [I5 I4] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2305
- // - token([3, 5]) [] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded)
2452
+ // - internal([3, 5]) [I5 I4] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound, I2/I1 not yet reached)
2453
+ // - token([3, 5]) [] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound, T1 not yet reached)
2306
2454
  // Result: C5/C4/C3 + I5/I4 kept, T6/I6/C6 excluded by pagingToken
2307
2455
  expect(summarize(result)).toEqual({
2308
2456
  ops: ops(C5, I5, C4, I4, C3),
2309
- pagingState: paging(2, { coin: false, internal: true, token: true }),
2457
+ // nft stays done: the incoming cursor already marked it done, so the endpoint is
2458
+ // short-circuited rather than re-queried, and a short-circuit is never "constrained".
2459
+ pagingState: paging(2, { coin: false, internal: false, token: false, nft: true }),
2310
2460
  })
2311
2461
  })
2312
2462
  })
@@ -2322,12 +2472,12 @@ describe('EVM Family', () => {
2322
2472
  )
2323
2473
  // fromBlock=2, toBlock=6 restricts all endpoints
2324
2474
  // - coin([2, 6]) [C5 C4 C3] boundBlock=3, isPageFull=true, hasMorePage=true (full page)
2325
- // - internal([3, 6]) [I5 I4] boundBlock=3, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2326
- // - token([3, 6]) [] boundBlock=3, isPageFull=false, hasMorePage=true (bounded by boundBlock > fromBlock)
2475
+ // - internal([3, 6]) [I5 I4] boundBlock=3, isPageFull=false, hasMorePage=true (constrained by coins's bound: 3 > fromBlock=2)
2476
+ // - token([3, 6]) [] boundBlock=3, isPageFull=false, hasMorePage=true (constrained by coins's bound: 3 > fromBlock=2)
2327
2477
  // Result: ops in [3, 6] kept, T7/I7/C7 excluded by toBlock
2328
2478
  expect(summarize(result)).toEqual({
2329
2479
  ops: ops(C5, I5, C4, I4, C3),
2330
- pagingState: paging(2, { coin: false, internal: true, token: true }),
2480
+ pagingState: paging(2, { coin: false, internal: false, token: false, nft: false }),
2331
2481
  })
2332
2482
  })
2333
2483
 
@@ -2359,11 +2509,11 @@ describe('EVM Family', () => {
2359
2509
  const result = await callGetOperations('asc')([C5, C6, C7, C8, T4, I2, I2, I3, I4])
2360
2510
  // - coin([Ø, Ø]) [C5 C6 C7]+[C8] boundBlock=7, isPageFull=true, hasMorePage=true (full page + more)
2361
2511
  // - internal([Ø, 7]) [I2 I2 I3]+[I4] boundBlock=3, isPageFull=true, hasMorePage=true (full page + more, lower boundBlock)
2362
- // - token([Ø, 3]) [] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded)
2512
+ // - token([Ø, 3]) [] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T4 at block 4 not yet reached)
2363
2513
  // Result: only I2s and I3 kept, coin ops dropped (above boundBlock=3)
2364
2514
  expect(summarize(result)).toEqual({
2365
2515
  ops: ops(I3, I2, I2),
2366
- pagingState: paging(4, { coin: false, internal: false, token: true }),
2516
+ pagingState: paging(4, { coin: false, internal: false, token: false, nft: false }),
2367
2517
  })
2368
2518
  })
2369
2519
 
@@ -2372,11 +2522,11 @@ describe('EVM Family', () => {
2372
2522
  const result = await callGetOperations('asc')([T1, I2, I2, I3, I4, T4, C5, C6, C7, C8])
2373
2523
  // - coin([Ø, Ø]) [C5 C6 C7]+[C8] boundBlock=7, isPageFull=true, hasMorePage=true (full page + more)
2374
2524
  // - internal([Ø, 7]) [I2 I2 I3]+[I4] boundBlock=3, isPageFull=true, hasMorePage=true (full page + more, lower boundBlock)
2375
- // - token([Ø, 3]) [T1] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded)
2525
+ // - token([Ø, 3]) [T1] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by internal's bound, T4 at block 4 not yet reached)
2376
2526
  // Result: T1 + I2s + I3 kept, coin ops dropped (above boundBlock=3)
2377
2527
  expect(summarize(result)).toEqual({
2378
2528
  ops: ops(I3, I2, I2, T1),
2379
- pagingState: paging(4, { coin: false, internal: false, token: true }),
2529
+ pagingState: paging(4, { coin: false, internal: false, token: false, nft: false }),
2380
2530
  })
2381
2531
  })
2382
2532
 
@@ -2396,11 +2546,11 @@ describe('EVM Family', () => {
2396
2546
  ])
2397
2547
  // - coin([Ø, Ø]) [C7 C8 C9] boundBlock=Ø, isPageFull=true, hasMorePage=true (full page)
2398
2548
  // - internal([Ø, Ø]) [I4 I5 I6] boundBlock=7, isPageFull=true, hasMorePage=true (full page)
2399
- // - token([Ø, 7]) [T1 T2 T3] boundBlock=4, isPageFull=true, hasMorePage=true (full page, lowest boundBlock)
2549
+ // - token([Ø, 7]) [T1 T2 T3] boundBlock=4, isPageFull=true, hasMorePage=true (constrained by internal's bound, T9 at block 9 not yet reached)
2400
2550
  // Result: only T1/T2/T3 kept, coin+internal ops dropped (above boundBlock=4)
2401
2551
  expect(summarize(result)).toEqual({
2402
2552
  ops: ops(T3, T2, T1),
2403
- pagingState: paging(4, { coin: false, internal: false, token: true }),
2553
+ pagingState: paging(4, { coin: false, internal: false, token: false, nft: false }),
2404
2554
  })
2405
2555
  })
2406
2556
 
@@ -2425,7 +2575,7 @@ describe('EVM Family', () => {
2425
2575
  // Result: ops <= 3 kept, higher ops dropped (above boundBlock=4)
2426
2576
  expect(summarize(result)).toEqual({
2427
2577
  ops: ops(C3, I3, T3, I2, T2, T1),
2428
- pagingState: paging(4, { coin: false, internal: false, token: false }),
2578
+ pagingState: paging(4, { coin: false, internal: false, token: false, nft: false }),
2429
2579
  })
2430
2580
  })
2431
2581
  })
@@ -2434,12 +2584,12 @@ describe('EVM Family', () => {
2434
2584
  it('keeps all when subsequent pages are not full', async () => {
2435
2585
  const result = await callGetOperations('asc')([I2, I2, T4, C5, C6, C7, C8, T8])
2436
2586
  // - coin([Ø, Ø]) [C5 C6 C7] boundBlock=8, isPageFull=true, hasMorePage=true (full page)
2437
- // - internal([Ø, 8]) [I2 I2] boundBlock=8, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2438
- // - token([Ø, 8]) [T4] boundBlock=8, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2587
+ // - internal([Ø, 8]) [I2 I2] boundBlock=8, isPageFull=false, hasMorePage=true (constrained by coins's bound, T8 not yet reached)
2588
+ // - token([Ø, 8]) [T4] boundBlock=8, isPageFull=false, hasMorePage=true (constrained by coins's bound, T8 not yet reached)
2439
2589
  // Result: all ops kept, boundBlock stays at 8 because subsequent pages not full
2440
2590
  expect(summarize(result)).toEqual({
2441
2591
  ops: ops(C7, C6, C5, T4, I2, I2),
2442
- pagingState: paging(8, { coin: false, internal: true, token: true }),
2592
+ pagingState: paging(8, { coin: false, internal: false, token: false, nft: false }),
2443
2593
  })
2444
2594
  })
2445
2595
 
@@ -2455,12 +2605,12 @@ describe('EVM Family', () => {
2455
2605
  it('keeps all when only coin has ops', async () => {
2456
2606
  const result = await callGetOperations('asc')([C5, C6, C7, C8])
2457
2607
  // - coin([Ø, Ø]) [C5 C6 C7] boundBlock=8, isPageFull=true, hasMorePage=true (full page)
2458
- // - internal([Ø, 8]) [] boundBlock=8, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2459
- // - token([Ø, 8]) [] boundBlock=8, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2608
+ // - internal([Ø, 8]) [] boundBlock=8, isPageFull=false, hasMorePage=true (constrained by coins's bound, C8 not yet reached)
2609
+ // - token([Ø, 8]) [] boundBlock=8, isPageFull=false, hasMorePage=true (constrained by coins's bound)
2460
2610
  // Result: coin ops kept, nextPagingToken=8 for remaining C8
2461
2611
  expect(summarize(result)).toEqual({
2462
2612
  ops: ops(C7, C6, C5),
2463
- pagingState: paging(8, { coin: false, internal: true, token: true }),
2613
+ pagingState: paging(8, { coin: false, internal: false, token: false, nft: false }),
2464
2614
  })
2465
2615
  })
2466
2616
 
@@ -2472,19 +2622,19 @@ describe('EVM Family', () => {
2472
2622
  // Result: token ops kept, nextPagingToken=8 for remaining T8
2473
2623
  expect(summarize(result)).toEqual({
2474
2624
  ops: ops(T7, T6, T5),
2475
- pagingState: paging(8, { coin: true, internal: true, token: false }),
2625
+ pagingState: paging(8, { coin: true, internal: true, token: false, nft: false }),
2476
2626
  })
2477
2627
  })
2478
2628
 
2479
2629
  it('cascades without dropping when blocks interleave nicely', async () => {
2480
2630
  const result = await callGetOperations('asc')([T2, C4, I4, C5, I5, C6, I7, I8, C8, T8])
2481
2631
  // - coin([Ø, Ø]) [C4 C5 C6] boundBlock=7, isPageFull=true, hasMorePage=true (full page)
2482
- // - internal([Ø, 7]) [I4 I5] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2483
- // - token([Ø, 7]) [T2] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2632
+ // - internal([Ø, 7]) [I4 I5] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by coins's bound, I7/I8 not yet reached)
2633
+ // - token([Ø, 7]) [T2] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by coins's bound, T8 not yet reached)
2484
2634
  // Result: all ops <= 6 kept, interleaved blocks don't cause drops
2485
2635
  expect(summarize(result)).toEqual({
2486
2636
  ops: ops(C6, C5, I5, C4, I4, T2),
2487
- pagingState: paging(7, { coin: false, internal: true, token: true }),
2637
+ pagingState: paging(7, { coin: false, internal: false, token: false, nft: false }),
2488
2638
  })
2489
2639
  })
2490
2640
 
@@ -2492,11 +2642,11 @@ describe('EVM Family', () => {
2492
2642
  const result = await callGetOperations('asc')([T2, I2, C4, C5, I5, I6, I7, I8, T8])
2493
2643
  // - coin([Ø, Ø]) [C4 C5] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2494
2644
  // - internal([Ø, Ø]) [I2 I5 I6] boundBlock=7, isPageFull=true, hasMorePage=true (full page)
2495
- // - token([Ø, 7]) [T2] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2645
+ // - token([Ø, 7]) [T2] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by internal's bound, T8 not yet reached)
2496
2646
  // Result: all ops <= 6 kept, boundBlock from internal applies
2497
2647
  expect(summarize(result)).toEqual({
2498
2648
  ops: ops(I6, C5, I5, C4, I2, T2),
2499
- pagingState: paging(7, { coin: true, internal: false, token: true }),
2649
+ pagingState: paging(7, { coin: true, internal: false, token: false, nft: false }),
2500
2650
  })
2501
2651
  })
2502
2652
 
@@ -2504,11 +2654,11 @@ describe('EVM Family', () => {
2504
2654
  const result = await callGetOperations('asc')([I2, C4, C5, I5, I6, I7, I8, T8])
2505
2655
  // - coin([Ø, Ø]) [C4 C5] boundBlock=Ø, isPageFull=false, hasMorePage=false (not full)
2506
2656
  // - internal([Ø, Ø]) [I2 I5 I6] boundBlock=7, isPageFull=true, hasMorePage=true (full page)
2507
- // - token([Ø, 7]) [] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2657
+ // - token([Ø, 7]) [] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by internal's bound, T8 not yet reached)
2508
2658
  // Result: coin + internal ops kept
2509
2659
  expect(summarize(result)).toEqual({
2510
2660
  ops: ops(I6, C5, I5, C4, I2),
2511
- pagingState: paging(7, { coin: true, internal: false, token: true }),
2661
+ pagingState: paging(7, { coin: true, internal: false, token: false, nft: false }),
2512
2662
  })
2513
2663
  })
2514
2664
 
@@ -2528,12 +2678,12 @@ describe('EVM Family', () => {
2528
2678
  I8,
2529
2679
  ])
2530
2680
  // - coin([Ø, Ø]) [C5 C5 C5] boundBlock=6, isPageFull=true, hasMorePage=true (full page)
2531
- // - internal([Ø, 6]) [I5 I5 I5] boundBlock=6, isPageFull=true, hasMorePage=true (full page, same boundBlock)
2532
- // - token([Ø, 6]) [T5 T5 T5] boundBlock=6, isPageFull=true, hasMorePage=true (full page, same boundBlock)
2681
+ // - internal([Ø, 6]) [I5 I5 I5] boundBlock=6, isPageFull=true, hasMorePage=true (constrained by coins's bound, I8 not yet reached)
2682
+ // - token([Ø, 6]) [T5 T5 T5] boundBlock=6, isPageFull=true, hasMorePage=true (constrained by coins's bound, T8 not yet reached)
2533
2683
  // Result: all 9 ops at block 5 kept, all below boundBlock=6
2534
2684
  expect(summarize(result)).toEqual({
2535
2685
  ops: ops(C5, C5, C5, I5, I5, I5, T5, T5, T5),
2536
- pagingState: paging(6, { coin: false, internal: true, token: true }),
2686
+ pagingState: paging(6, { coin: false, internal: false, token: false, nft: false }),
2537
2687
  })
2538
2688
  })
2539
2689
 
@@ -2552,17 +2702,19 @@ describe('EVM Family', () => {
2552
2702
  const result = await callGetOperations('asc')(
2553
2703
  [T2, I2, C2, C4, I4, C5, I5, C6, I7, I8, C8, T8],
2554
2704
  {
2555
- pagingState: paging(4, { coin: false, internal: false, token: false }),
2705
+ pagingState: paging(4, { coin: false, internal: false, token: false, nft: true }),
2556
2706
  }
2557
2707
  )
2558
2708
  // pagingState.boundBlock=4 acts as fromBlock for all endpoints
2559
2709
  // - coin([4, Ø]) [C4 C5 C6] boundBlock=7, isPageFull=true, hasMorePage=true (full page)
2560
- // - internal([4, 7]) [I4 I5] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2561
- // - token([4, 7]) [] boundBlock=7, isPageFull=false, hasMorePage=true (bounded by boundBlock < toBlock)
2710
+ // - internal([4, 7]) [I4 I5] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by coins's bound, I7/I8 not yet reached)
2711
+ // - token([4, 7]) [] boundBlock=7, isPageFull=false, hasMorePage=true (constrained by coins's bound, T8 not yet reached)
2562
2712
  // Result: C4/C5/C6 + I4/I5 kept, T2/I2/C2 excluded by pagingToken
2563
2713
  expect(summarize(result)).toEqual({
2564
2714
  ops: ops(C6, C5, I5, C4, I4),
2565
- pagingState: paging(7, { coin: false, internal: true, token: true }),
2715
+ // nft stays done: the incoming cursor already marked it done, so the endpoint is
2716
+ // short-circuited rather than re-queried, and a short-circuit is never "constrained".
2717
+ pagingState: paging(7, { coin: false, internal: false, token: false, nft: true }),
2566
2718
  })
2567
2719
  })
2568
2720
  })
@@ -2579,12 +2731,12 @@ describe('EVM Family', () => {
2579
2731
  )
2580
2732
  // fromBlock=3, toBlock=7 restricts all endpoints
2581
2733
  // - coin([3, 7]) [C4 C5 C6]+[C7] boundBlock=6, isPageFull=true, hasMorePage=true (full page + more)
2582
- // - internal([3, 6]) [I4 I5] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded)
2583
- // - token([3, 6]) [] boundBlock=Ø, isPageFull=false, hasMorePage=false (bounded)
2734
+ // - internal([3, 6]) [I4 I5] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound: 6 < toBlock=7)
2735
+ // - token([3, 6]) [] boundBlock=Ø, isPageFull=false, hasMorePage=true (constrained by coins's bound: 6 < toBlock=7)
2584
2736
  // Result: ops in [3, 6] kept, C7/I7/T1/I1/C1 excluded
2585
2737
  expect(summarize(result)).toEqual({
2586
2738
  ops: ops(C6, C5, I5, C4, I4),
2587
- pagingState: paging(7, { coin: false, internal: true, token: true }),
2739
+ pagingState: paging(7, { coin: false, internal: false, token: false, nft: false }),
2588
2740
  })
2589
2741
  })
2590
2742
 
@@ -2608,6 +2760,170 @@ describe('EVM Family', () => {
2608
2760
  })
2609
2761
  })
2610
2762
  })
2763
+
2764
+ describe('multi-page completeness', () => {
2765
+ const MAX_PAGES = 50
2766
+
2767
+ // Drives getOperations page by page, feeding each nextPagingToken back in, until
2768
+ // the cursor is exhausted. Returns every page so tests can assert on the union.
2769
+ const paginateToExhaustion = async (
2770
+ order: 'asc' | 'desc',
2771
+ allOps: BlockchainOp[],
2772
+ opts: { fromBlock?: number; toBlock?: number; limit?: number } = {}
2773
+ ): Promise<string[][]> => {
2774
+ const pages: string[][] = []
2775
+ let pagingState: PagingState | undefined
2776
+ for (let page = 0; page < MAX_PAGES; page++) {
2777
+ const result = await callGetOperations(order)(allOps, {
2778
+ ...opts,
2779
+ ...(pagingState !== undefined && { pagingState }),
2780
+ })
2781
+ pages.push(summarizeIdentified(result))
2782
+ const { pagingState: next } = summarize(result)
2783
+ if (!next) return pages
2784
+ pagingState = next
2785
+ }
2786
+ throw new Error(`pagination did not terminate within ${MAX_PAGES} pages`)
2787
+ }
2788
+
2789
+ // The scenario's ops as the labels a complete pagination must produce, one per op.
2790
+ const expected = (allOps: BlockchainOp[]): string[] => identify(allOps).map(opLabel)
2791
+
2792
+ // Canonical ordering so a union of pages can be compared regardless of page order.
2793
+ // Keeps duplicates, so an op returned on two pages fails the comparison too.
2794
+ const blockOf = (label: string): number => Number(label.replace(/^[A-Z]/, '').split('#')[0])
2795
+ const canonical = (items: string[]): string[] =>
2796
+ [...items].sort((a, b) => blockOf(b) - blockOf(a) || a.localeCompare(b))
2797
+
2798
+ // Guards the guard. If the labels ever lose operation identity, one op returned twice
2799
+ // while another at the same type and block is dropped would stop being detected, and
2800
+ // every exactly-once assertion below would quietly weaken without any of them failing.
2801
+ it('exactly-once comparison tells apart operations sharing a type and block', () => {
2802
+ const labels = expected([C4, C4, C4])
2803
+ const duplicatedAndDropped = [labels[0], labels[1], labels[1]]
2804
+
2805
+ // Type and block alone cannot tell these two multisets apart...
2806
+ const withoutIdentity = (items: string[]): string[] =>
2807
+ items.map((label) => label.split('#')[0]).sort()
2808
+ expect(withoutIdentity(duplicatedAndDropped)).toEqual(withoutIdentity(labels))
2809
+
2810
+ // ...but the labels the assertions actually compare do.
2811
+ expect(canonical(duplicatedAndDropped)).not.toEqual(canonical(labels))
2812
+ })
2813
+
2814
+ // Scanning from genesis used to silently drop every token transfer once the first page
2815
+ // of native txs filled up.
2816
+ //
2817
+ // Cause: coin returns a full page, which cascades a bound block onto the token endpoint.
2818
+ // Token then finds nothing *inside that narrowed window* and reports isDone=true. The
2819
+ // cursor used to record that as "token globally done", so page 2 skipped the endpoint
2820
+ // entirely and the transfers below the bound were never fetched by any page.
2821
+ it('does not lose token transfers that sit below the first page bound block', async () => {
2822
+ // Native txs occupy the newest blocks; the token transfers are all older.
2823
+ const allOps = [C9, C8, C7, C6, T3, T2, T1]
2824
+ const labels = expected(allOps)
2825
+ const pages = await paginateToExhaustion('desc', allOps, { fromBlock: 0 })
2826
+
2827
+ // Page 1 is native-only: the token endpoint was constrained to the coin bound and
2828
+ // legitimately found nothing there. The bug was in what the cursor recorded next.
2829
+ expect(pages[0]).toEqual(labels.slice(0, 3))
2830
+
2831
+ // The whole point: the token transfers still show up on a later page.
2832
+ expect(canonical(pages.flat())).toEqual(canonical(labels))
2833
+ })
2834
+
2835
+ it('re-queries an internal endpoint that was only locally done', async () => {
2836
+ const allOps = [C9, C8, C7, C6, I3, I2]
2837
+ const pages = await paginateToExhaustion('desc', allOps, { fromBlock: 0 })
2838
+
2839
+ expect(canonical(pages.flat())).toEqual(canonical(expected(allOps)))
2840
+ })
2841
+
2842
+ // The scenarios below are the ones whose single-page cursor expectations changed with the
2843
+ // fix. Walking each to exhaustion checks the new cursor values against an invariant that
2844
+ // does not depend on those expectations: every op is returned exactly once.
2845
+ const scenarios: Array<{ name: string; ops: BlockchainOp[] }> = [
2846
+ { name: 'internal above a full coin page', ops: [I6, I6, I6, I5, T5, C4, C3, C2] },
2847
+ { name: 'token above a full coin page', ops: [T9, T8, T7, I6, I5, C4, C3, C2, T1] },
2848
+ { name: 'interleaved blocks', ops: [T6, C5, I5, C4, I4, C3, I2, I1, T1] },
2849
+ {
2850
+ name: 'all endpoints stacked on one block',
2851
+ ops: [C4, C4, C4, I4, I4, I4, T4, T4, T4, C1, I1, T1],
2852
+ },
2853
+ { name: 'only coin has ops', ops: [C4, C3, C2, C1] },
2854
+ { name: 'only token has ops', ops: [T4, T3, T2, T1] },
2855
+ // One of each direction: ops stranded below the bound only fall outside the window
2856
+ // when paging desc, and above it only when paging asc.
2857
+ { name: 'sparse tail below the bound', ops: [C9, C8, C7, C6, I3, T2, T1] },
2858
+ { name: 'sparse head above the bound', ops: [C1, C2, C3, C4, I7, T8, T9] },
2859
+ ]
2860
+
2861
+ it.each(scenarios)('desc: returns every op exactly once - $name', async ({ ops: allOps }) => {
2862
+ const pages = await paginateToExhaustion('desc', allOps, { fromBlock: 0 })
2863
+ expect(canonical(pages.flat())).toEqual(canonical(expected(allOps)))
2864
+ })
2865
+
2866
+ it.each(scenarios)('asc: returns every op exactly once - $name', async ({ ops: allOps }) => {
2867
+ const pages = await paginateToExhaustion('asc', allOps, { fromBlock: 0 })
2868
+ expect(canonical(pages.flat())).toEqual(canonical(expected(allOps)))
2869
+ })
2870
+
2871
+ // The NFT endpoint is the last in the cascade, so it is handed the most narrowed window
2872
+ // and is the most exposed to being marked done too early. The scenarios above carry no
2873
+ // NFT operations, so they only ever exercise it as an empty endpoint.
2874
+ describe('nft endpoints (ERC-721 + ERC-1155)', () => {
2875
+ // desc pages from the highest block down, so the first coin page sets a floor and the
2876
+ // nft ops have to sit below it to fall outside the narrowed window. asc is the mirror
2877
+ // image: the first coin page sets a ceiling, so they have to sit above it. Using the
2878
+ // same block layout for both directions would leave one of them never exercising the
2879
+ // constrained path at all.
2880
+ const descScenarios: Array<{ name: string; ops: BlockchainOp[] }> = [
2881
+ { name: 'erc721 below a full coin page', ops: [C9, C8, C7, C6, N3, N2, N1] },
2882
+ { name: 'erc1155 below a full coin page', ops: [C9, C8, C7, C6, M3, M2, M1] },
2883
+ { name: 'erc721 and erc1155 interleaved', ops: [C9, C8, C7, C6, N3, M2, N1, M1] },
2884
+ { name: 'nft behind coin, internal and token', ops: [C9, C8, C7, C6, I5, T4, N3, M2] },
2885
+ { name: 'erc721 and erc1155 on the same block', ops: [C9, C8, C7, C6, N2, M2] },
2886
+ { name: 'nft only', ops: [N4, N3, M2, M1] },
2887
+ ]
2888
+
2889
+ const ascScenarios: Array<{ name: string; ops: BlockchainOp[] }> = [
2890
+ { name: 'erc721 above a full coin page', ops: [C1, C2, C3, C4, N7, N8, N9] },
2891
+ { name: 'erc1155 above a full coin page', ops: [C1, C2, C3, C4, M7, M8, M9] },
2892
+ { name: 'erc721 and erc1155 interleaved', ops: [C1, C2, C3, C4, N7, M8, N9, M9] },
2893
+ { name: 'nft behind coin, internal and token', ops: [C1, C2, C3, C4, I5, T6, N7, M8] },
2894
+ { name: 'erc721 and erc1155 on the same block', ops: [C1, C2, C3, C4, N8, M8] },
2895
+ { name: 'nft only', ops: [N1, N2, M3, M4] },
2896
+ ]
2897
+
2898
+ it.each(descScenarios)(
2899
+ 'desc: returns every nft op exactly once - $name',
2900
+ async ({ ops: allOps }) => {
2901
+ const pages = await paginateToExhaustion('desc', allOps, { fromBlock: 0 })
2902
+ expect(canonical(pages.flat())).toEqual(canonical(expected(allOps)))
2903
+ }
2904
+ )
2905
+
2906
+ it.each(ascScenarios)(
2907
+ 'asc: returns every nft op exactly once - $name',
2908
+ async ({ ops: allOps }) => {
2909
+ const pages = await paginateToExhaustion('asc', allOps, { fromBlock: 0 })
2910
+ expect(canonical(pages.flat())).toEqual(canonical(expected(allOps)))
2911
+ }
2912
+ )
2913
+
2914
+ // Same shape as the coin/token regression above, but for the last endpoint in the
2915
+ // cascade: the first coin page narrows the NFT window to nothing, and the NFT
2916
+ // transfers all sit below that bound.
2917
+ it('does not lose nft transfers that sit below the first page bound block', async () => {
2918
+ const allOps = [C9, C8, C7, C6, N3, M2, N1]
2919
+ const labels = expected(allOps)
2920
+ const pages = await paginateToExhaustion('desc', allOps, { fromBlock: 0 })
2921
+
2922
+ expect(pages[0]).toEqual(labels.slice(0, 3))
2923
+ expect(canonical(pages.flat())).toEqual(canonical(labels))
2924
+ })
2925
+ })
2926
+ })
2611
2927
  })
2612
2928
 
2613
2929
  describe('exhaustEndpoint', () => {