@ledgerhq/coin-evm 16.2.0 → 16.2.4

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 (51) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/lib/network/explorer/etherscan.d.ts +12 -0
  3. package/lib/network/explorer/etherscan.d.ts.map +1 -1
  4. package/lib/network/explorer/etherscan.js +22 -12
  5. package/lib/network/explorer/etherscan.js.map +1 -1
  6. package/lib/network/gasTracker/ledger.js +2 -2
  7. package/lib/network/gasTracker/ledger.js.map +1 -1
  8. package/lib/network/node/rpc.common.d.ts.map +1 -1
  9. package/lib/network/node/rpc.common.js +31 -6
  10. package/lib/network/node/rpc.common.js.map +1 -1
  11. package/lib-es/network/explorer/etherscan.d.ts +12 -0
  12. package/lib-es/network/explorer/etherscan.d.ts.map +1 -1
  13. package/lib-es/network/explorer/etherscan.js +22 -12
  14. package/lib-es/network/explorer/etherscan.js.map +1 -1
  15. package/lib-es/network/gasTracker/ledger.js +2 -2
  16. package/lib-es/network/gasTracker/ledger.js.map +1 -1
  17. package/lib-es/network/node/rpc.common.d.ts.map +1 -1
  18. package/lib-es/network/node/rpc.common.js +31 -6
  19. package/lib-es/network/node/rpc.common.js.map +1 -1
  20. package/package.json +9 -3
  21. package/src/api/tests/getBlock.integ.test.ts +1 -1
  22. package/src/api/tests/index.monad_testnet.integ.test.ts +20 -20
  23. package/src/api/tests/index.unichain.integ.test.ts +46 -0
  24. package/src/logic/tests/combine.test.ts +1 -1
  25. package/src/logic/tests/getStakes.test.ts +7 -0
  26. package/src/network/explorer/etherscan.ts +25 -13
  27. package/src/network/gasTracker/ledger.ts +2 -2
  28. package/src/network/node/rpc.common.ts +46 -6
  29. package/src/network/tests/explorer/etherscan.test.ts +104 -36
  30. package/src/network/tests/gasTracker/ledger.test.ts +52 -0
  31. package/src/network/tests/node/rpc.test.ts +58 -4
  32. package/.oxlintrc.json +0 -94
  33. package/docs/abis.md +0 -20
  34. package/docs/adapters.md +0 -10
  35. package/docs/evm-family-integration-process/README.md +0 -102
  36. package/docs/getBlock-internal-txs-schema.md +0 -104
  37. package/docs/logic.md +0 -17
  38. package/docs/network/explorer/etherscan.md +0 -35
  39. package/docs/network/explorer/index.md +0 -7
  40. package/docs/network/explorer/ledger.md +0 -22
  41. package/docs/network/gasTracker/index.md +0 -8
  42. package/docs/network/gasTracker/ledger.md +0 -13
  43. package/docs/network/node/index.md +0 -10
  44. package/docs/network/node/ledger.md +0 -47
  45. package/docs/network/node/rpc.md +0 -42
  46. package/docs/types.md +0 -18
  47. package/jest.config.js +0 -15
  48. package/jest.integ.config.js +0 -8
  49. package/knip.json +0 -30
  50. package/tsconfig.build.json +0 -14
  51. package/tsconfig.json +0 -14
@@ -1,104 +0,0 @@
1
- # Internal transactions retrieval in getBlock
2
-
3
- This document describes how internal transactions are fetched and merged when calling `getBlock(currency, height)`.
4
-
5
- ## Flow overview
6
-
7
- ```mermaid
8
- flowchart TB
9
- subgraph entry["getBlock(currency, height)"]
10
- A[getNodeApi] --> B["createInternalTransactionsFetcher(config, nodeApi, sources, logger)"]
11
- B --> C[fetchInternalTxs]
12
- end
13
-
14
- subgraph parallel["Promise.all (parallel)"]
15
- D["nodeApi.getBlockByHeight(height, true)"]
16
- E["fetchInternalTxs(height)"]
17
- end
18
-
19
- A --> parallel
20
- C --> E
21
-
22
- subgraph sources["Ordered source list (default or getBlockInternalTxsSources)"]
23
- F["explorer → getInternalTransactionsByBlock"]
24
- G["trace_block → nodeApi.traceBlockErigon"]
25
- H["debug_traceBlockByNumber → nodeApi.traceBlockGeth"]
26
- I["empty → resolve Map()"]
27
- end
28
-
29
- E -.-> sources
30
-
31
- subgraph compose["composeInternalTxsFetcher loop"]
32
- J{source resolves?}
33
- J -->|yes| K["Map(txHash → BlockOperation[])"]
34
- J -->|SourceUnavailableError| L[skip to next source]
35
- J -->|real runtime error| M[remember errors, next source]
36
- L --> N{next source}
37
- M --> N
38
- N -->|empty, no real error| O[resolve empty Map]
39
- N -->|empty, real errors remembered| P[throw collected real errors]
40
- N -->|list exhausted| P
41
- end
42
-
43
- sources -.-> compose
44
-
45
- subgraph after["after parallel"]
46
- Q[result, internalTxs]
47
- R[getTransactionsFromNode]
48
- S[mergeInternalTransactions]
49
- T[return Block]
50
- end
51
-
52
- parallel --> Q
53
- Q --> R
54
- R --> S
55
- S --> T
56
- ```
57
-
58
- ## Default source list
59
-
60
- When `getBlockInternalTxsSources` is absent, the default is:
61
-
62
- `["explorer", "trace_block", "debug_traceBlockByNumber", "empty"]`
63
-
64
- Built via `internalTxSourcesFromList(["explorer", "trace_block", "debug_traceBlockByNumber", "empty"])` in `internalTxSources.ts`.
65
-
66
- ## Source semantics
67
-
68
- | Source | When unavailable (skipped) | When available but fails at runtime |
69
- |--------|---------------------------|-------------------------------------|
70
- | `explorer` | Explorer config is not etherscan-like | Best-effort: wrapped as `SourceUnavailableError`, fall through to node traces |
71
- | `trace_block` | `nodeApi.traceBlockErigon` is undefined | Remember error, try next source; rethrow collected errors when `empty` is reached or the list is exhausted without a later success (e.g. erigon error → geth fallback) |
72
- | `debug_traceBlockByNumber` | `nodeApi.traceBlockGeth` is undefined | Same as `trace_block`: remember and continue; rethrow collected errors only when no later source succeeds |
73
- | `empty` | N/A (terminal) | Resolves empty Map only if no real runtime errors were remembered; otherwise re-throws all collected real errors |
74
-
75
- **Behaviour-preserving rule:** structurally unsupported sources are skipped (`SourceUnavailableError`). Explorer failures are always best-effort (fall through). Runtime trace failures are remembered and the loop continues to later sources (erigon → geth); collected real errors are rethrown only when `empty` is reached with remembered errors or the list ends without a success (single error rethrown as-is, multiple as `AggregateError`). A trailing `empty` resolves only when every prior source was unavailable, not when a trace call failed at runtime.
76
-
77
- ## Paths summary
78
-
79
- | Explorer config | Primary source | Fallback |
80
- |-----------------|----------------|----------|
81
- | Etherscan-like (etherscan, blockscout, teloscan, klaytnfinder, corescan) | `getInternalTransactionsByBlock` → `txlistinternal` | `traceBlockErigon` → `traceBlockGeth` → empty (if traces unavailable) or propagate (if traces error) |
82
- | Other (ledger, none, …) | `traceBlockErigon` → `traceBlockGeth` | empty (if traces unavailable) or propagate (if traces error) |
83
-
84
- ## Data flow
85
-
86
- 1. **Explorer path**
87
- `getInternalTransactionsByBlock` → `EtherscanInternalTransaction[]` → `internalTxsToOperationsByHash` → `Map<string, BlockOperation[]>`.
88
-
89
- 2. **Node trace paths**
90
- `traceBlockErigon` / `traceBlockGeth` → RPC `trace_block` / `debug_traceBlockByNumber` → `TraceBlockItem[]` → `traceBlockItemsToOperationsByHash` → `Map<string, BlockOperation[]>`.
91
-
92
- 3. **Merge**
93
- `mergeInternalTransactions(transactions, internalTxs)` adds each `internalTxs.get(tx.hash)` as extra `operations` on the corresponding `BlockTransaction`.
94
-
95
- ## Files
96
-
97
- - **Fetcher wiring:** `libs/coin-modules/coin-evm/src/logic/internalTransactionsFetcher.ts`
98
- - **getBlock:** `libs/coin-modules/coin-evm/src/logic/getBlock.ts`
99
- - **Source list builder:** `libs/coin-modules/coin-evm/src/internalTxSources.ts`
100
- - **Config field:** `libs/coin-modules/coin-evm/src/config.ts` (`getBlockInternalTxsSources`)
101
- - **Explorer internal txs:** `libs/coin-modules/coin-evm/src/network/explorer/etherscan.ts`
102
- - **Explorer → operations:** `libs/coin-modules/coin-evm/src/adapters/etherscan.ts`
103
- - **RPC traces:** `libs/coin-modules/coin-evm/src/network/node/rpc.common.ts` (`traceBlockErigon`, `traceBlockGeth`)
104
- - **Trace → operations:** `libs/coin-modules/coin-evm/src/adapters/blockOperations.ts`
package/docs/logic.md DELETED
@@ -1,17 +0,0 @@
1
- # `logic.ts`
2
- Set of helpers for the whole coin-evm module.
3
-
4
- ## Methods
5
-
6
- #### getGasLimit
7
- Helper return the gas limit of a transaction, either customized by the user or the default one.
8
-
9
- #### getEstimatedFees
10
- Combines the gas limit and the gas price of a transaction to return the estimated maximum fee payed for its execution.
11
-
12
- #### getAdditionalLayer2Fees
13
- Some Layer 2 require additional fee in order to execute a transaction, not limiting the spending to its `gasLimit`. As of today, it's only the case for Layer 2 implementing the [OP Stack](https://stack.optimism.io/) standard and therefore behaving like Optimism.
14
- This method is responsible for providing that additional fee in an agnostic manner.
15
-
16
- #### padHexString
17
- Add necessary "0" in a hexadecimal string in order to make its character an even number, which can be necessary to some implementations. (e.g. 0x123 => 0x0123)
@@ -1,35 +0,0 @@
1
- # `etherscan.ts`
2
- Set of functions designed to retrieve transactions associated with an account through explorers that utilize the [etherscan API](https://docs.etherscan.io/api-endpoints/accounts).
3
-
4
- ### Constants
5
-
6
- #### ETHERSCAN_TIMEOUT
7
- Minimum time between two requests, allowing for retries after a failure.
8
-
9
- #### DEFAULT_RETRIES_API
10
- Number of retries when a request fails.
11
-
12
- ### Methods
13
- #### fetchWithRetries
14
- This helper function wraps the basic axios request method, incorporating handling for retries upon failure. This is particularly relevant due to a rate limit on etherscan requests without an API key, allowing only one request every 5 seconds.
15
-
16
- #### getLastCoinOperations
17
- Uses `fetchWithRetries` to retrieve coin transactions for a given address. This method does not consider any outcomes resulting from that transaction, such as internal transactions or events.
18
-
19
- #### getLastTokenOperations
20
- Uses `fetchWithRetries` to retrieve ERC20 transfer events for a specified address. These transfer events are often treated as "transactions" for simplicity, but they are essentially side effects of a coin transaction interacting with a smart contract, indicating that a particular smart contract has completed an action.
21
-
22
- #### getLastERC721Operations
23
- Uses `fetchWithRetries` to retrieve ERC721 (NFT) transfer events for a specified address. Similar to ERC20 transfer events, these are often regarded as "transactions" for simplicity, though they are actually side effects of a coin transaction interacting with a smart contract, signifying the completion of a specific smart contract transfer action.
24
-
25
- #### getLastERC1155Operations
26
- Uses `fetchWithRetries` to retrieve ERC1155 (NFT) transfer events for a specified address. Similar to ERC20 transfer events, these are often regarded as "transactions" for simplicity, though they are actually side effects of a coin transaction interacting with a smart contract, signifying the completion of a specific smart contract transfer
27
-
28
- #### getLastNftOperations
29
- A wrapper around the two NFT fetching operations.
30
-
31
- #### getLastInternalOperations
32
- Uses `fetchWithRetries` to fetch internal transactions for a specified address. These transactions are a byproduct of a coin transaction interacting with a smart contract, causing that smart contract to create transactions itself.
33
-
34
- #### getLastOperations
35
- Responsible for triggering all the other methods to fetch every type of transaction possible and return each type separately.
@@ -1,7 +0,0 @@
1
- # `index.ts`
2
-
3
- ## Methods
4
-
5
- #### getExplorerApi
6
-
7
- This method is used to determine the explorer designated for a particular currency. While some explorers may share the same API, mainly owing to compatibility with the [Etherscan API](https://docs.etherscan.io/api-endpoints/accounts), any explorer with the capability to provide the complete transaction history of an account can be included as an option.
@@ -1,22 +0,0 @@
1
- # `ledger.ts`
2
- Set of functions designed to retrieve transactions associated with an account through the [Ledger explorers](https://explorers.api.live.ledger.com/blockchain/v4/eth/docs/).
3
-
4
- ### Constants
5
-
6
- #### BATCH_SIZE
7
- Maximum number of transactions returned by a single explorer request.
8
-
9
-
10
- #### LEDGER_TIMEOUT
11
- Minimum time between two requests for retry after a failure.
12
-
13
- #### DEFAULT_RETRIES_API
14
- Number of retries when a request fails.
15
-
16
- ### Methods
17
-
18
- #### fetchPaginatedOpsWithRetries
19
- This is a general request method responsible for fetching all transactions of all types for a given address. It manages retries and pagination for a complete retrieval.
20
-
21
- #### getLastOperations
22
- This method utilizes `fetchPaginatedOpsWithRetries` to retrieve all transactions, sort them by type, and return each type separately.
@@ -1,8 +0,0 @@
1
- # `index.ts`
2
-
3
-
4
- ## Methods
5
-
6
- #### getGasTracker
7
-
8
- Method used to select the gasTracker optionnaly defined for a specific currency.
@@ -1,13 +0,0 @@
1
- # `ledger.ts`
2
-
3
- This module consists of functions responsible for retrieving data related to gas pricing using the [Ledger explorers](https://explorers.api.live.ledger.com/blockchain/v4/eth/docs/#/default/getBlockchainV4EthGastrackerBarometer).
4
-
5
- ### Constants
6
-
7
- #### explorerIdGasTrackerMap
8
- This map is utilized to associate an explorer ID/currency with a set of properties of the gas tracker linked to it, such as its compatibility with [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) or not.
9
-
10
- ### Methods
11
-
12
- #### getGasOptions
13
- This method is responsible for providing three options for gas pricing: slow, medium, and fast.
@@ -1,10 +0,0 @@
1
- # `index.ts`
2
-
3
-
4
- ## Methods
5
-
6
- #### getNodeApi
7
-
8
- Method used to select the node defined for a specific currency. The node can be an RPC node or a simple REST API as long as it's capable of providing a given set of functionalities.
9
-
10
- Signature: `getNodeApi(config, logger)`. The `logger` (usually `context.logger`) is required; it is captured when the `NodeApi` for a given config is first built and memoized, and is used for all its logs.
@@ -1,47 +0,0 @@
1
- # `ledger.ts`
2
- Set of functions specific to Ledger nodes functionalities through the [explorers API](https://explorers.api.live.ledger.com/blockchain/v4/eth/docs/).
3
-
4
- ### Constants
5
-
6
- #### LEDGER_TIMEOUT
7
- Maximum time before a request is deemed timed out and should result in failure.
8
-
9
- #### LEDGER_TIME_BETWEEN_TRIES
10
- Minimum time between two requests for retry after a failure.
11
-
12
- #### DEFAULT_RETRIES_API
13
- Number of retries when a request fails.
14
-
15
- ### Methods
16
- #### fetchWithRetries
17
- A helper function encapsulating the basic axios request method and incorporating retry handling in case of failure.
18
-
19
- #### getTransaction
20
- Retrieves a transaction by hash and returns its block and nonce.
21
-
22
- #### getCoinBalance
23
- Provides the amount of coin for a given address in wei.
24
-
25
- #### getBatchTokenBalances
26
- Batches multiple requests for token balances into a single one.
27
-
28
- #### getTokenBalance
29
- Returns the amount of tokens for a given address based on the balanceOf method of the [ERC20 standard](https://eips.ethereum.org/EIPS/eip-20). This request will be batched with other requests made in the same synchronization.
30
-
31
- #### getTransactionCount
32
- Returns the number of transaction made by an account. This will be then used as nonce for a future transaction crafting.
33
-
34
- #### getGasEstimation
35
- Simulates a transaction to estimate the amount of gas consumed in executing the transaction on the blockchain. If the transaction is impossible (e.g. sending more than the account owns), the simulation will fail and no estimation will be returned.
36
-
37
- #### getFeeData
38
- In charge of finding the different elements for the gas pricing depending on the chain ability to use [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) or not. If the chain supports EIP-1559, it should return a `maxPriorityFeePerGas`, a `maxFeePerGas` & a `nextBaseFee`, otherwise it should simply return a `gasPrice` value.
39
-
40
- #### broadcastTransaction
41
- Broadcasts an RLP serialized signed transaction and returns its hash to poll a node using the `getTransaction` method, determining when it has been added to a block.
42
-
43
- #### getBlockByHeight
44
- Fetches basic information from a block by its height, primarily used to obtain its creation timestamp.
45
-
46
- #### getOptimismAdditionalFees
47
- Requests an oracle smart contract to estimate the L1 fee that an account will need to pay for an optimism transaction to be included in a block. This fee is related to data availability. For more information, refer to: https://docs.optimism.io/builders/dapp-developers/transactions/estimates
@@ -1,42 +0,0 @@
1
- # `rpc.ts`
2
- Set of functions specific to interacting with an EVM RPC Node. The JSON-RPC API is documented [here](https://ethereum.org/developers/docs/apis/json-rpc).
3
-
4
- ### Constants
5
-
6
- #### RPC_TIMEOUT
7
- Minimum time between two requests for retry after a failure.
8
-
9
- #### DEFAULT_RETRIES_RPC_METHODS
10
- Number of retries when a request fails.
11
-
12
- ### Methods
13
- #### withApi
14
- A helper function encapsulating the `StaticJsonRpcProvider` object and incorporating retry handling in case of failure.
15
-
16
- #### getTransaction
17
- Retrieves a transaction by hash and returns its block and nonce.
18
-
19
- #### getCoinBalance
20
- Provides the amount of coin for a given address in wei.
21
-
22
-
23
- #### getTokenBalance
24
- Returns the amount of tokens for a given address based on the balanceOf method of the [ERC20 standard](https://eips.ethereum.org/EIPS/eip-20). This request will be batched with other requests made in the same synchronization.
25
-
26
- #### getTransactionCount
27
- Returns the number of transaction made by an account. This will be then used as nonce for a future transaction crafting.
28
-
29
- #### getGasEstimation
30
- Simulates a transaction to estimate the amount of gas consumed in executing the transaction on the blockchain. If the transaction is impossible (e.g. sending more than the account owns), the simulation will fail and no estimation will be returned.
31
-
32
- #### getFeeData
33
- In charge of finding the different elements for the gas pricing depending on the chain ability to use [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) or not. If the chain supports EIP-1559, it should return a `maxPriorityFeePerGas`, a `maxFeePerGas` & a `nextBaseFee`, otherwise it should simply return a `gasPrice` value.
34
-
35
- #### broadcastTransaction
36
- Broadcasts an RLP serialized signed transaction and returns its hash to poll a node using the `getTransaction` method, determining when it has been added to a block.
37
-
38
- #### getBlockByHeight
39
- Fetches basic information from a block by its height, primarily used to obtain its creation timestamp.
40
-
41
- #### getOptimismAdditionalFees
42
- Requests an oracle smart contract to estimate the L1 fee that an account will need to pay for an optimism transaction to be included in a block. This fee is related to data availability. For more information, refer to: https://docs.optimism.io/builders/dapp-developers/transactions/estimates
package/docs/types.md DELETED
@@ -1,18 +0,0 @@
1
- # `types`
2
-
3
- ## Files
4
-
5
- #### editTransaction
6
- Set of types proper to the functionality of the replace by fee mechanism.
7
-
8
- #### etherscan
9
- Set of types proper to etherscan explorers. Mostly containing their own transaction format, received from their API. Also used for Blockscout explorers and any other explorer having a compatiblity layer with Etherscan.
10
-
11
- #### ledger
12
- Set of types proper to ledger explorers. Mostly containing their own transaction format, received from their API.
13
-
14
- #### signer
15
- Set of types for the abstraction added to remove the dependency of the `coin-evm` module with the `@ledgerhq/hw-app-eth` module (as a dependency, not devDependency which is necessary for some types). Mostly used in the bridge definition with the `buildSignOperation` & `makeAccountBridgeReceive` methods.
16
-
17
- #### transaction
18
- Set of types representing the `evm` family transactions, specific to Ledger Live and/or the `@ledgerhq/ledger-wallet-framework`
package/jest.config.js DELETED
@@ -1,15 +0,0 @@
1
- // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
- // SPDX-License-Identifier: Apache-2.0
3
-
4
- const base = require("../jest.config.base");
5
-
6
- module.exports = {
7
- ...base,
8
- passWithNoTests: true,
9
- setupFilesAfterEnv: ["jest-expect-message", "dotenv/config"],
10
- // Imported from ledger-live with a pre-existing handle leak: some suites leave
11
- // sockets/timers behind, so jest never returns on its own in CI (the Unit Tests job
12
- // ran 36 min without finishing). forceExit ends the run once tests are done.
13
- forceExit: true,
14
- maxWorkers: 2,
15
- };
@@ -1,8 +0,0 @@
1
- // SPDX-FileCopyrightText: © 2024 LEDGER SAS
2
- // SPDX-License-Identifier: Apache-2.0
3
-
4
- /** @type {import('jest').Config} */
5
- module.exports = {
6
- ...require("../jest.integ.config.base"),
7
- testTimeout: 90_000,
8
- };
package/knip.json DELETED
@@ -1,30 +0,0 @@
1
- {
2
- "$schema": "https://unpkg.com/knip@5.34.1/schema.json",
3
- "entry": [
4
- "src/abis/index.ts",
5
- "src/api/index.ts",
6
- "src/config.ts",
7
- "src/errors.ts",
8
- "src/logic.ts",
9
- "src/logic/combine.ts",
10
- "src/logic/craftTransaction.ts",
11
- "src/logic/getErc20Data.ts",
12
- "src/logic/index.ts",
13
- "src/logic/validateAddress.ts",
14
- "src/network/gasTracker/index.ts",
15
- "src/network/gasTracker/types.ts",
16
- "src/network/index.ts",
17
- "src/network/node/index.ts",
18
- "src/network/node/rpc.common.ts",
19
- "src/network/node/rpc.native.ts",
20
- "src/network/node/types.ts",
21
- "src/staking/index.ts",
22
- "src/staking/redelegations.ts",
23
- "src/supportedFeatures.ts",
24
- "src/types/editTransaction.ts",
25
- "src/types/index.ts",
26
- "src/types/staking.ts"
27
- ],
28
- "project": ["src/**/*.ts"],
29
- "ignoreDependencies": ["@ledgerhq/coin-module-framework"]
30
- }
@@ -1,14 +0,0 @@
1
- {
2
- "extends": ["./tsconfig.json", "../tsconfig.build.base.json"],
3
- "exclude": [
4
- "**/*.test.ts",
5
- "**/*.spec.ts",
6
- "**/__tests__/**/*",
7
- "**/tests/**/*",
8
- "**/__mocks__/**/*",
9
- "**/*.test.js",
10
- "**/*.spec.js",
11
- "**/fixtures/**/*",
12
- "**/*.fixtures.ts"
13
- ]
14
- }
package/tsconfig.json DELETED
@@ -1,14 +0,0 @@
1
- {
2
- "extends": "../tsconfig.coin.json",
3
- "compilerOptions": {
4
- "outDir": "lib",
5
- "rootDir": "src",
6
- "lib": ["es2022", "dom"]
7
- },
8
- "files": [
9
- "node_modules/jest-expect-message/types/index.d.ts"
10
- ],
11
- "include": [
12
- "src/**/*"
13
- ]
14
- }