Crypto Asset List (CAL)
The Crypto Asset List is designed to address two issues:
- The Exchange application does not know which application to call to handle a given currency.
- The Coin application may not have all the data required to handle a given currency.
These issues are solved by using the CAL to provide trusted information to the Exchange application.
The CAL signature
The CAL data is stored on an HSM alongside its signature.
The signature is checked by the Exchange application upon reception of CAL data to ensure that the data is legitimate.
To allow testing 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 the test framework.
The coin configuration format
A coin configuration for 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.
Its content is application-specific. The byte array will be passed as a pointer to the handlers in the coin application.
For more information about the handlers, please refer to the corresponding section: Coin Application API.
A standard subconfiguration exists, composed of ticker + decimals. This is the one used by most of our applications when handling tokens (for example, Ethereum and Solana).
The Ragger tool provides utilities to craft coin configurations both without and with the standard subconfiguration.
As an example, here is the crafting 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)