@ledgerhq/coin-evm

EVM family integration process

How to integrate a new EVM family currency in the Ledger Live application.

This document will outline the different steps needed to implement a new EVM family currency in the Ledger Live application. Depending on the specifications, some steps might not be needed for all currencies.

Specifications

Most EVM coin integrations are quite similar. The main specs will be outlined below. But each coin may have its specificities and more information can be found on the specific coin integration Jira Epic created for each integration, based on this template https://ledgerhq.atlassian.net/browse/LIVE-10187

• Integration is done in Ledger Live desktop and Ledger Live mobile
• Supported features:
  • Sending and receiving coins
  • Viewing transaction history
  • Token support, enabling interactions with the blockchain tokens
• Use of public RPC node and explorer (etherscan-like). This should be specified in the corresponding Jira Epic
  • To find a public node, you can use https://chainlist.org/ for example
  • To find a public explorer, you can use https://blockscan.com/ (etherscan-like) for example
• The Ethereum embedded app must handle this new network

Live codebase update

Here is an example PR of an EVM currency integration: https://github.com/LedgerHQ/ledger-live/pull/4008

Main steps

Common steps for all new EVM currency integration

• Add a new config entry for the new currency under libs/ledgerjs/packages/cryptoassets/src/currencies.ts
• Add the new currency ID to the CryptoCurrencyId type under libs/ledgerjs/packages/types-cryptoassets/src/index.ts
• Add an entry for the new currency in the abandonSeedAddresses (using the currency ID as key and EVM_DEAD_ADDRESS as value) under libs/ledgerjs/packages/cryptoassets/src/abandonseed.ts
• Add the new currency ID to the setSupportedCurrencies function param on each relevant project (CLI, LLD, LLM and LLC test environement)
• Add a new feature flag config for this currency:
  • The new feature flag type in the CurrencyFeatures type under libs/ledgerjs/packages/types-live/src/feature.ts
  • The new feature flag definition with default value in the CURRENCY_DEFAULT_FEATURES mapping under libs/ledger-live-common/src/featureFlags/defaultFeatures.ts
  • Use this new feature flag in both LLD and LLM currencies entry points (add account / select crypto flow)
• Update related doc and snapshot files:
  • run pnpm doc under libs/ledgerjs/packages/types-live to update the doc
  • run pnpm test:jest under apps/ledger-live-desktop to update the snapshots
• Add the related currency icon as SVG format under the libs/ui/packages/crypto-icons/src/svg folder within the @ledgerhq/icons-ui package
  • the file name should follow the {currency_ticker}.svg naming convention
  • the SVG icon should follow Ledger Live currency icon guideline (you can use this tool for validation)

Optional steps

Optional / extra steps that might be needed on a case-by-case basis depending on the integration

• If the related currency public explorer is not an etherscan-like, you might need to add a new implementation for this currency explorer
  • If needed, create a new explorer implementation of this explorer API in a new file under the libs/coin-modules/coin-evm/src/network/explorer folder
  • Add the new explorer type to:
    • the getExplorerApi function under libs/coin-modules/coin-evm/src/network/explorer/index.ts
    • the EthereumLikeInfo.explorer.type type under libs/ledgerjs/packages/types-cryptoassets/src/index.ts
    • if the new explorer type follows the etherscan-like API, add it to the isEtherscanLikeExplorerConfig type guard under libs/coin-modules/coin-evm/src/network/explorer/types.ts (this is the case for some custom made explorers that are not blockscan white label implementation, but are still compatible with the blockscan/etherscan API)

Tokens support

Here are the steps to handle the new currencies (ERC20) tokens, if relevant:

• add the new tokens config to the CAL (historically handled by @adrienlacombe-ledger)
• after this update of the CAL, check that the tokens are present on the CDN, replacing {chainId} with the actual currency chain ID, specified under ethereumLikeInfo.chainId in the currency config (under libs/ledgerjs/packages/cryptoassets/src/currencies.ts) which would be 1 for ethereum mainnet for example, using https://cdn.live.ledger.com/cryptoassets/evm/{chainId}/erc20.json

No change should be needed on Ledger Live side since tokens are automatically imported from CAL at the release stage, cf:

• this GitHub Action .github/workflows/test-release-create.yml
• the import:cal-tokens job in the ledger-js package

Counter values support (fiat prices)

To have the associated market (fiat) price supported for the network being added, some config updates are needed on the CAL and countervalue service sides.

The process for this can be found here: https://ledgerhq.atlassian.net/wiki/spaces/WALLETCO/pages/4354769042/Adding+price+support+for+a+currency

Ethereum app firmware update

The new network being added needs to be handled by the nano ethereum app.

Make sure the network being added is present under the network_info_t mapping in src_common/network.c (here for staging and here for prod).

In Ledger Live, make sure the ethereum nano app version requirements match the latest version of the ethereum app handling the network being added:

• appVersion in getAppQuery under libs/coin-modules/coin-evm/src/specs.ts
• Ethereum in appVersionsRequired under libs/ledger-live-common/src/apps/support.ts
• related tests for the ethereum app version under libs/ledger-live-common/src/apps/support.test.ts

Tests

Bot

• Make sure to fund the appropriate bot(s) with coins and tokens of the new network being added (cf. The different bots)
• Make sure to make the bot run multiple times on your PR to make sure everything works fine with the new network
• If the coin related to the network you are adding is somewhat expensive, you can tailor the minimum balance needed to test this coin by updating minBalancePerCurrencyId under libs/coin-modules/coin-evm/src/specs.ts

Manual testing

The bare minimum to test in terms of flows is, on both LLD and LLM:

• Add account
• Send funds (coins) from one account to another
• Add (receive) token (if supported)
• Send token (if supported)

Firebase Feature Flag config

Make sure to add the newly created currency feature flag to the Firebase config