Crypto Asset List (CAL)
The Crypto Asset List is there to tackle two issues:
- The Exchange application does not know which application to call to handle a given currency.
- The Coin application may not have all data on hand to handle a given currency.
We solve these issues by using the CAL to give trusted information to the Exchange application.
The CAL signature
The data of the CAL is stored on a HSM alongside its signature.
The signature is checked by the Exchange application upon reception of CAL data to ensure that the data is legitimate.
In order to be able to test with dynamic data, the Exchange application can be compiled with the TEST_PUBLIC_KEY=1 flag to accept a false Ledger HSM key.
The resulting application will not work in production but is useful in our test framework.
The coin configuration format
A coin configuration of a currency contains the following elements:
| Bytes | Description |
|---|---|
| 1 byte | Coin configuration length of the FROM coin. The coin configuration is made of the ticker, appname, and subconf |
| 1 byte | Ticker name length N |
| N bytes | Ticker name of this the coin configuration. The ticker has to be the same as the FROM ticker |
| 1 byte | Application name length M |
| M bytes | Name of the application that can handle this currency |
| 1 byte | Sub coin configuration length R |
| R bytes | Sub coin configuration, used for tokens to specify an app the subticker and the decimals |
| S bytes | Signature of the coin configuration by the Ledger key in DER format, curve secp256k1 hashfunc sha256 |
| 1 byte | Packed derivation path length T |
| T bytes | Packed derivation path used for the FROM coin |
The subconfiguration
The subconfiguration part is optional and is often used only when handling tokens.
It's content is application specific, the bytes array will be given as pointer to the handles in the coin application, for more information about the handles please refer to the corresponding section Coin Application API
A standard subconfiguration exists, it is composed of ticker + decimals, it is the one used by most of our applications when handling tokens (Ethereum and Solana for example).
The Ragger tool provides utilities to craft coin configurations both without and with standard subconfiguration.
As an example, here is the craft of the coin configuration for Solana in our tests:
test/python/apps/solana_utils.py
from ragger.utils import create_currency_config
from ragger.bip import pack_derivation_path
### Proposed Solana derivation paths for tests ###
SOL_PACKED_DERIVATION_PATH = pack_derivation_path("m/44'/501'/12345'")
SOL_PACKED_DERIVATION_PATH_2 = pack_derivation_path("m/44'/501'/0'/0'")
### Package this currency configuration in exchange format ###
# Simple native currency configuration: Ticker + Appname
SOL_CONF = create_currency_config("SOL", "Solana")
# Standard coin configuration for a token: Ticker + Appname + (Ticker + decimal)
JUP_CONF = create_currency_config("JUP", "Solana", ("JUP", 6))
JUP_PACKED_DERIVATION_PATH = SOL_PACKED_DERIVATION_PATH
SOL_USDC_CONF = create_currency_config("USDC", "Solana", ("USDC", 6))
SOL_USDC_PACKED_DERIVATION_PATH = SOL_PACKED_DERIVATION_PATH
# Solana and Solana tokens
SOL_CURRENCY_CONFIGURATION = CurrencyConfiguration(ticker="SOL", conf=SOL_CONF, packed_derivation_path=SOL_PACKED_DERIVATION_PATH)
JUP_CURRENCY_CONFIGURATION = CurrencyConfiguration(ticker="JUP", conf=JUP_CONF, packed_derivation_path=JUP_PACKED_DERIVATION_PATH)
SOL_USDC_CURRENCY_CONFIGURATION = CurrencyConfiguration(ticker="USDC", conf=SOL_USDC_CONF, packed_derivation_path=SOL_USDC_PACKED_DERIVATION_PATH)