Blockchains, Networks & Currency

Throughout the API you will find several endpoints that accept parameters blockchain, network, and currencyID. This document outlines their differences and explains how to use them. These three parameters can be a source of confusion especially for EVM-compatible blockchains, or cases where a token is deployed on multiple blockchains (for example, USDT).

🚧

Deprecated: currency

You may come across a parameter, currency, which is being deprecated and being replaced with currencyId. Avoid using currency and instead use by the newer blockchain, network, and currencyId parameters. If you come across an endpoint that only accepts currency, we advise to use currencyId as the parameter value unless explicitly requested.

Using these parameters

Our API generally uses three parameters or filters to identify digital assets.

🚧

Important: Multi-chain tokens

Multi-chain tokens are tokens that exist on multiple chains but have the same symbol. For example, USDT is available on Ethereum, Avalanche, Cosmos, Solana, etc... These are separate deployments of USDT accessed via separate contract addresses. This is why symbol alone is not specific enough to isolate a specific token.

Each deployment of USDT does have retain a unique currencyId which is why this is the recommended parameter to use. Whenever currencyId is omitted, both blockchain and network are required to identify a token.

Examples

Below are a few examples highlighting the differences between Symbol, Blockchain and Network. Note that this is not an exhaustive list and if you are unclear about which values to use in your protect instance, you should query the currencies to identify the respective values for coins enabled in your instance of PROTECT.

Implications for Developers

• When working with EVM based blockchains, the blockchain parameter should be set toETH.
• For any of the endpoints below you must provide either a valid currencyId or both blockchain and network parameters. Supplying only one of these (blockchain or network) is not sufficient to uniquely identify a currency.
• To find the correct currencyId for your query, use the List currencies endpoint. Prefer using currencyId to identify the specific coin or token on each chain. This ID is explicit and unique across blockchains, networks and assets. CurrencyId is also unique to your instance of protect.
• Set blockchain to ETH for all EVM-compatible blockchains.
• Currency information about an address will also be returned in the currencyInfo field. This structure will include the symbol, blockchain and network.

Endpoints that use blockchain, network, currencyId.

There are several endpoints that accept these parameters:

• Get blockchain entities
• Get the total balances for the tenant, for each nft collection
• List fee payers)
• Get the balance of the address
• Get the daily transactions of the address
• Get the proof of reserve of an address
• Get auto-transfer event handlers
• Export transactions
• Export addresses
• List Addresses
• List Wallets
• List Transactions
• List Fee Payers
• List Shared Assets (Taurus Network)
• List Whitelisted Addresses
• List whitelisted addresses for approval
• List Whitelisted Contracts
• Create a wallet
• Create a whitelisted address
• Create whitelisted contracts

chain_id for EVM-based blockchains

There is special configuration for EVM based tokens, which prevents replay attacks for transactions between different EVM-compatible chains. If you manage your PROTECT configuration yourself on-premise, when enabling a new coin in PROTECT, you must specify a chain_idfor ETH blockchains.

For example, in the tg-validatord configuration, to enable XDC you must specify a chain_id since XDC is an EVM compatible blockchain. The correct chain_id value can be found online for public blockchains, or can be specified in the genesis configuration of a permissionless chain.

...
eth/xdc:
	enabled: true
	network: xdc
  native_symbol: XDC
	chain_id: 50  
	...