Komodo DeFi SDK Common Structures
The objects are in the request or response of multiple Komodo DeFi SDK methods have been grouped into the following sections:
Structures which are used in more than one section are listed below:
| Structure | Type | Description |
|---|---|---|
| format | string (enum) | address format to which the input address should be converted. Possible values: mixedcase for ETH/ERC20 coins; cashaddress or standard for UTXO coins; contract or wallet for QTUM/QRC20 |
| network | string (enum) | Optional, only used for UTXO coins. Network prefix for cashaddress format. Possible values: bitcoincash for BCH mainnet; bchtest for BCH testnet; bchreg for BCH regtest |
The AddressInfo object includes the following items for a given address:
| Parameter | Type | Description |
|---|---|---|
| balances | object | A standard balanceInfos object. Not included in responses where get_balances is false |
| derivation_method | object | A standard DerivationMethod object |
| pubkey | string | The public key associated with the seed used to launch Komodo DeFi Framework |
| tickers | array | A list of tokens which were successfully activated. Only included in responses where get_balances is false |
The balanceInfos object includes the following items for a given coin or token:
| Parameter | Type | Description |
|---|---|---|
| spendable | string (numeric) | The available amount of a coin or token which is ready to be traded or withdrawn. |
| unspendable | string (numeric) | The amount of a coin or token which is awaiting confirmation on the block chain for an incoming or outgoing transaction. |
The DerivationMethod object includes the following items for a given coin or token:
| Parameter | Type | Description |
|---|---|---|
| type | string | Defines how keypairs will be generated. Possible values: Iguana or HDWallet |
Using the same seed or private key to generate keypairs using different derivation methods will result in a different address and private key for each method.
Where the value indicates:
Iguana: The coin or token is was activated using Iguana derivation (default).HDWallet: The coin or token is was activated using a Heirarchical Deterministic (HD) Wallet derivation path.
The EventStreamConfig object defines which events will be streamed to the client:
| Parameter | Type | Description |
|---|---|---|
| access_control_allow_origin | string | Defines CORS whitelist. Use "*" to allow fromi any origin. |
| active_events | object | Events to be streamed to the client, along with configuration defineing frequency etc. |
| worker_path | string | WASM only. Path to a custom worker.js file. |
Active events are defined as follows:
- NETWORK: Network status changes. Requires
stream_interval_secondsconfiguration. - HEARTBEAT: Allows clients to easily determine whether channels are functioning. Requires
stream_interval_secondsconfiguration. - COIN_BALANCE: Balance changes. Does not require
stream_interval_secondsconfiguration, as the event is triggered by the balance change.
The COIN_BALANCE event may not be available for all coins or tokens.
An example of the event stream output can then be viewed in https://github.com/KomodoPlatform/komodo-defi-framework/blob/main/examples/sse/index.html
The NumericFormatsValue returns a price or amount in three different formats: fraction, rational, and decimal.
| Parameter | Type | Description |
|---|---|---|
| decimal | numeric string | A decimal number as a string. |
| rational | object | A standard RationalValue object. |
| fraction | object | A standard FractionalValue object. |
The FeeInfo response object includes the following items for withdraw (v2) requests:
| Parameter | Type | Description |
|---|---|---|
| type | string | Type of transaction fee; possible values: UtxoFixed, UtxoPerKbyte, EthGas, Qrc20Gas, CosmosGas |
| amount | string (numeric) | Fee amount in coin units, used only when type is UtxoFixed (fixed amount not depending on tx size) or UtxoPerKbyte (amount per Kbyte) |
| gas_price | string (numeric) | Used only when fee type is Qrc20Gas or EthGas; sets the gas price in gwei units. |
| gas_price | number (double) | Used only when fee type is CosmosGas; sets the gas price. |
| gas | number (integer) | Used only when fee type is EthGas; sets the gas limit for transaction |
| gas_limit | number (integer) | Used only when fee type is Qrc20Gas or CosmosGas; sets the gas limit for transaction |
| Structure | Type | Description |
|---|---|---|
| coin | string | the fee is paid from the user's balance of this coin. This coin name may differ from the base or rel coins. For example, ERC20 fees are paid by ETH (gas) |
| amount | string (numeric) | fee amount (in decimal representation) |
| amount_rat | rational | fee amount (in rational representation) |
| amount_fraction | fraction | fee amount (in fraction representation) |
| amount_fraction | fraction | fee amount (in fraction representation) |
| paid_from_trading_vol | bool | whether the fee is paid from trading volume and not use actual coin balance |
| Structure | Type | Description |
|---|---|---|
| coin | string | the fee is paid from the user's balance of this coin. This coin name may differ from the base or rel coins. For example, ERC20 fees are paid by ETH (gas) |
| amount | string (numeric) | fee amount (in decimal representation) |
| amount_rat | rational | fee amount (in rational representation) |
| amount_fraction | fraction | fee amount (in fraction representation) |
| required_balance | string (numeric) | the required coin balance to pay the fee |
| required_balance_rat | rational | required_balance in rational representation |
| required_balance_fraction | fraction | required_balance in fraction representation |
The FractionalValue object includes a numerator and denominator values for a given price or amount:
| Parameter | Type | Description |
|---|---|---|
| numer | string (numeric) | The numerator of the fractional value. |
| denom | string (numeric) | The denominator of the fractional value. |
For requests which return many results, pagination offsets may be applied. ** Use either value, not both. **
| Parameter | Type | Description |
|---|---|---|
| PageNumber | integer | Optional, defaults to 1. Offset for paginated results |
| FromId | integer | Optional. Ignores any results prior to this UUID |
The Komodo DeFi SDK now offers the num-rational crate feature which allows for higher precision numeric values to represent order volumes and prices in a unique format as explained below:
[
[1, [0, 1]],
[1, [1]]
]
In the above unique format, the first item [1,[0,1]] is the numerator and the second item [1,[1]] is the denominator.
The numerator and denominator are BigInteger numbers represented as a sign and a uint32 array (where numbers are 32-bit parts of big integer in little-endian order).
[1,[0,1]] represents +0000000000000000000000000000000010000000000000000000000000000000 = 4294967296
[-1,[1,1]] represents -1000000000000000000000000000000010000000000000000000000000000000 = -4294967297
| Parameter | Type | Description |
|---|---|---|
| state | string | current state of sync; possible values: NotEnabled, NotStarted, InProgress, Error, Finished |
| additional_info | object | A standard SyncStatusExtended object. Additional info that helps to track the progress; present for InProgress and Error states only. |
| Parameter | Type | Description |
|---|---|---|
| blocks_left | number | present for ETH/ERC20 coins only; displays the number of blocks left to be processed for InProgress state |
| transactions_left | number | present for UTXO coins only; displays the number of transactions left to be processed for InProgress state |
| code | number | displays the error code for Error state |
| message | number | displays the error message for Error state |
The WithdrawFee object varies depending on the coin or token type. Refer to the examples to view the object structure for each type.
| Parameter | Type | Description |
|---|---|---|
| type | string | The fee type. Either Utxo, Tendermint, Qrc20 or Eth. |
| amount | numeric string | Utxo or Tendermint type only. The fee amount. |
| coin | string | The coin which will be used to pay the transaction fee. |
| gas | integer | Eth type only. The amount of gas to be used for the transaction. |
| gas_price | numeric string | Eth or Qrc20 type only. Price per unit of gas to be used for the transaction. |
| gas_limit | numeric string | Tendermint or Qrc20 type only. Maximum gas to be used for the transaction. |
| miner_fee | numeric string | Tendermint type only. Fee to mine the transaction. |
| total_fee | numeric string | Eth type only. Gas price multiplied by gas amount. |
| total_gas_fee | numeric string | Qrc20 type only. Gas price multiplied by gas amount. |
The 'FilterCriteria' object allows you to filter the results based on specific parameters.
| Parameter | Type | Description |
|---|---|---|
| status | string | Status of the transactions (e.g., "completed") |
| date_from | string | `Start date in ISO 8601 format |
| date_to | string | End date in ISO 8601 format |
| my_coin | string | Coin being used by you for the swap/trade. |
| other_coin | string | Coin you are trading against |
| from_timestamp | number | Start timestamp in UNIX format |
| to_timestamp | number | End timestamp in UNIX format |
The PagingOptions object includes options of page selection to consult when looking for recent swaps:
| Parameter | Type | Description |
|---|---|---|
| from_uuid | string (or null) | Skips records until this UUID, excluding the record with this UUID. Convenient for infinite scrolling implementations. |
| limit | number | Limits the number of returned swaps. |
| page_number | number | Returns limit swaps from the selected page. This parameter is ignored if from_uuid is set. |