On this page

latest contributor to this doc

Last Edit:

@smk762

Prerequisites for a coin to be compatible with Komodo DeFi Framework

Before a coin can be listed in Komodo DeFi Framework, it needs to be confirmed for compatibility, and present within the Komodo Platform coins repository.

The information below details the requirements for creating a working coins configuration file and submitting a successful pull request to the coins repository. Please contact our support team in the #dev-support channel on the Komodo Platorm Discord if you have any questions or need assistance with performing a test swap.

Different platforms & protocols vary slightly in what data is required. Review the parameter descriptions and examples below to understand what information is needed to list your coin.

ParameterTypeDescription
coinstringTicker of the coin/token. If the coin is a token, please use COIN-PROTOCOL as ticker, eg USDC-BEP20.
namestringThis is the value which is expected to be default data directory name for that coin - e.g. if coin's name is litecoin then it's expected data directory on ~/.litecoin/ on Linux, ~/Library/Applications Support/Litecoin/ on Mac, %AppData%\Litecoin on Windows. Please keep this key's value in small letters only.
fnamestringThe full name of the coin/token.
mm2integerIndicates trading compatibility with Komodo DeFi Framework API. 1 is compatible, 0 is not compatible. Non-compatible coins may still be listed as wallet only in Komodo DeFi Framework apps.
required_confirmationsintegerDefaults to 1. The number of confirmations Komodo DeFi Framework will wait for during the swap. WARNING, this setting affects the security of the atomic swap. 51% attacks (double spending) are a threat and have been succesfully conducted in the past. You can find a collection of coins and the theoretical cost of a 51% attack here. Please be aware that some of the coins supported by Komodo DeFi Framework may be vulnerable to such attacks, so consider using higher confirmation values for them, especially when dealing with large amounts.
requires_notarizationbooleanDefaults to false. For coins protected by dPoW can be set to true wait for a notarization when sending transactions during a swap. If true, "required_confirmations" must be set to 2 or higher.
decimalsintegerDefines the number of digits after the decimal point that should be used to display the orderbook amounts, balance, and the value of inputs to be used in the case of order creation or a withdraw transaction. The default value used for a UTXO type coin (Bitcoin Protocol) is 8 and the default value used for a ERC20 Token is 18. It is very important for this value to be set correctly. For example, if this value was set as 9 for BTC, a command to withdraw 1 BTC tries to withdraw 10^9 satoshis of Bitcoin, i.e., 10 BTC
protocolstringContains the coin protocol "type" (UTXO, ETH, etc.) and specific protocol configuration - "protocol_data" object that can have arbitrary format.
orderbook_tickerstringIf set, coins with the same value will share the same orderbook. For example, if BTC-Segwit and BTC-BEP20 are set with "orderbook_ticker":"BTC" the same orderbook is returned for KMD/BTC, KMD/BTC-BEP20 and KMD/BTC-Segwit pairs.
sign_message_prefixstringOptional, required to allow for message signing in Komodo DeFi Framework API. Can normally be found within a projects github repository [example] and follows a standard format like "Komodo Signed Message:\n"

The following rpc methods should be available.

estimatefee
getblock
getblockhash
getinfo
getrawtransaction
gettxout
importaddress
listunspent
listreceivedbyaddress
listtransactions
sendrawtransaction
ParameterTypeDescription
namestringThis is the value which is expected to be default data directory name for that coin - e.g. if coin's name is litecoin then it's expected data directory on ~/.litecoin/ on Linux, ~/Library/Applications Support/Litecoin/ on Mac, %AppData%\Litecoin on Windows. Please keep this key's value in small letters only.
rpcportintegerThe coin's default RPC port. It is expected that it doesn't conflict with any existing coin in the coins db.
pubtypeintegerThis information can be found in source code of a coin project in files like src/init.cpp, src/base58.h, and src/chainparamsbase.h if the project is following the bitcoin source code directory/files structure. If unsure, then please have these confirmed by that coin/project's developers to ensure it is correct.
p2shtypeintegerThis information can be found in source code of a coin project in files like src/init.cpp, src/base58.h, and src/chainparamsbase.h if the project is following the bitcoin source code directory/files structure. If unsure, then please have these confirmed by that coin/project's developers to ensure it is correct.
wiftypeintegerThis information can be found in source code of a coin project in files like src/init.cpp, src/base58.h, and src/chainparamsbase.h if the project is following the bitcoin source code directory/files structure. If unsure, then please have these confirmed by that coin/project's developers to ensure it is correct.
txfeeintegerThe default transaction fee (in satoshi). Komodo DeFi Framework uses this as the default transaction fee value when making atomic swap transactions. If set to 0, Komodo DeFi Framework will use a dynamic fee based on output from estimatesmartfee.
overwinteredintegerMust be 1 if Overwinter upgrade was activated for the coin. Defaults to 0.
taddrintegerOptional. Is only relevant for coins that forked the Zcash protocol and have both transparent addresses and z-addresses. The value to be set for this key can be found from the file src/chainparams.cpp of the coin's source code and it is the first value present in both base58Prefixes[PUBKEY_ADDRESS] and base58Prefixes[SCRIPT_ADDRESS]. But it has to be converted to decimal from HEX. So if base58Prefixes[PUBKEY_ADDRESS] = {0x1C,0xB8} , the taddr is 0x1C coverted to decimal. As 0x1C in HEX = 28 in decimal, the entry in the json would be "taddr" : 28
force_min_relay_feebooleanIf true for coins with dynamic fees, when a new transaction is generated, Komodo DeFi Framework will check whether the total fee set (sat * tx size) is lower than relay fee and will use the relay fee instead. Defaults to false
mtp_block_countintegerOptional. Number of blocks to be used for the calculation of median time past. Must be greater than 0. Default value is 11. While this parameter is applicable only in the case of KMD reward calculation for now, it will be used for calculating locktimes to be set for the atomic swap refund transactions.
estimate_fee_modestringSets the fee mode for the estimatesmartfee call. Supported values are: ECONOMICAL,CONSERVATIVE, UNSET. Please note that some coins may not support some of these modes. Makes no effect for coins that do not have the estimatesmartfee RPC.
address_formatobjectOptional. Overwrites the address format from coins file, if set. A standard AddressFormat object.
isPoSintegerOptional, defaults to 0. A value of 1 indicates the coin uses proof of stake, so transactions created will have the nTime field.
segwitBooleanIf true, Komodo DeFi Framework will use to P2SH segwit addresses.
version_group_idintegerOptional, used by Zcash (and its forks') transactions.
consensus_branch_idintegerOptional, used in Zcash (and its forks') transactions' signature hash calculation.
mature_confirmationsintegerNumber of blockchain confirmations required for coinbase output to be considered mature (spendable).

The token's contract must have approve and transferFrom methods. Additionally, the transfer and transferFrom methods must return a boolean value (true/false) indicating whether a transfer was successful. This requirement is actually a part of the ERC20 standard, but many tokens seem to not follow it.

  • chain_id - ID of the chain, see Chainlist
  • Protocol "type" field: "ETH" or "ERC20"
  • Protocol "protocol_data" field (ERC20 only): "platform" - "ETH", "ETC" or other Ethereum forks. "contract_address" - ERC20 token checksummed smart contract address.
ParameterTypeDescription
chain_idintegerTo find the EVM chain ID, see Chainlist
gas_limitobjectOptional, required for tokens only. Defines more precise gas prices for swap or transaction operations. Some tokens are called over proxy contracts which often require more gas, though users may be able to choose higher/lower values than the default where required. See the Gas Limit Options table below for more information.
protocol.typestringPlatform / protocol - e.g ETH for Ethereum, ERC20 for ERC20 tokens on the Ethereum network
protocol.protocol_dataobjectRequired for tokens only.
protocol.protocol_data.platformstringThe parent coin of the token's platform - e.g MATIC for PLG20 tokens
protocol.protocol_data.contract_addressstringMust be mixed case The identifying hex string for the token's contract. Can be found on sites like EthScan, BscScan & PolygonScan

ParameterTypeDescription
eth_send_coinsintegerGas limit for sending coins.
eth_send_erc20integerGas limit for sending ERC20 tokens.
eth_paymentintegerGas limit for swap payment tx with coins.
erc20_paymentintegerGas limit for swap payment tx with ERC20 tokens.
eth_receiver_spendintegerGas limit for swap receiver spend tx with coins.
erc20_receiver_spendintegerGas limit for swap receiver spend tx with ERC20 tokens.
eth_sender_refundintegerGas limit for swap refund tx with coins.
erc20_sender_refundintegerGas limit for swap refund tx with with ERC20 tokens.
eth_max_trade_gasintegerGas limit for other operations.

QTUM & QRC20 tokens are a special case which also support all fields of UTXO specific config.

  • The icon file is required.
  • Icon must be a .png format file.
  • Dimensions of icon file is at least 128x128 pixels.
  • Icon file name MUST be the coin/token ticker in small letters without protocl suffix - e.g. for KMD or KMD-BEP20, use kmd.png.
  • Icon file location is icons_original folder.

  • Tokens do not need this data, they will use the values for their parent coin.
  • Explorer file name must be coin's ticker name in all capital letters.
  • Explorer file name must not have any file extension. It is a file without any . extension.
  • It must have a valid JSON array with at least one Explorer URL in it. Multiple explorer URLs are recommended - e.g. ["https://komodod.com/","https://kmd.explorer.dexstats.info/"]
  • Add the path suffixes for the explorer's address and transaction URLs in explorer_paths.json

  • Electrum file name must be coin's ticker name in all capital letters.
  • Electrum file name must not have any file extension. It is a file without any . extension.
  • It must be a valid JSON format as shown in the following example:
  • Details of at least 2 Electrum servers must be provided.
  • The address and port of electrum server are required. The address of electrum server can either be a DNS or an IP address.
  • Protocol can be "SSL" or "TCP". For WebDEX (wasm) listings, SSL is required.
  • Contact information must be provided in case the server admin needs to be contacted in emergency situations. Failing servers will result in an automatic delisting of your coin upon the next release of the Komodo DeFi Framework apps.
  • The status of currently listed ElectrumX servers is monitored via a public API and Dashboard. For help setting up Telegram or Discord alerts for your servers, join the #dev-support channel in the Komodo Platform Discord.

The disable_cert_verification field is optional and defaults to false. If set to true, the SSL certificate verification will be disabled. This can be used when the server has a self-signed certificate, but it is not recommended for production use. To avoid SSL certificate validation issues, it is highly recommended to use EFF's Certbot to generate SSL certificates for ElectrumX servers.

  • Ethereum file name must be coin's ticker name in all capital letters.
  • Ethereum file name must not have any file extension. It is a file without any . extension.
  • Swap contract address must be the address of etomic swap smart contract deployed to ETH network, example.
  • At least minimum 2 or more URLs of RPC nodes must be provided.
  • Contact information must be provided in case the server admin needs to be contacted in urgent cases. It can be any contact information out of the examples provided.
  • The RPC node URL can either be a DNS or an IP address with port.
  • It must be a valid JSON format as shown in the following example:

The API IDs are stored in json files within the /api_ids folder, and used to source price and chart date in Komodo DeFi Framework apps.

For CoinGecko it is conveniently displayed on the right had side of a coins page as below -

Gecko

For CoinPaprika it is the same as displayed in a coin's URL -

Paprika

For For Forex the API ID is the same as the ISO 4217 currency code.

Add these IDs to their respective json file within the /api_ids folder in the format "TICKER": "API_ID"

The BIP44 derivation path is now required to ensure Hierarchical deterministic wallet functionality. The best source for this data is via Satoshi Labs SLP-044

For Trezor compatibility, this field is required. You can find this value at https://trezor.io/coins. Not all coins are listed on this page by default, but if compatible can be found by searching the supported coins. The value is the name of the coin in larger black text (not the grey text in brackets). E.g. for the image below, the Trezor coin name would be Qtum.

Qtum

The coin must have participated in a successful Atomic Swap using Komodo DeFi Framework

When submitting your coin addition request, please submit the URLs of the 5 transactions (takerfee sent, maker payment, taker payment and taker payment spent, maker payment spent) produced by successful swap in a new file inside the swaps directory- here's an example for KMD-ETH. This means that, before going through the further steps and submitting the information to this coins database repo, you would have performed a successful atomic swap. The further steps explain the expected files/values to be submitted.

You can learn about performing an atomic swap from our documentation at this link

Activating a coin at this link

Walkthrough at this link

If you have any questions, please ask in the #support channel in our Discord server or you can get help from the team at [email protected] or [email protected] .