You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
export const title = "Komodo DeFi SDK RPC Protocol v2.0";
export const description = "Starting with version beta-2.1.3434, the Komodo DeFi SDK supports the standardized protocol format called mmrpc 2.0.";
Komodo DeFi SDK RPC Protocol v2.0
Starting with version beta-2.1.3434, the Komodo DeFi SDK supports the standardized protocol format called mmrpc 2.0.
It includes a uniform request, successful and error response formats. At the moment, only a few RPC methods support the mmrpc 2.0 protocol.
Request
Structure
Type
Description
mmrpc
string
the string specifying the version of the Komodo DeFi SDK RPC protocol. Must be exactly "2.0"
userpass
string (optional)
your password for protected RPC methods. Skip this field if the specified method is public
method
string
the name of the method to be invoked
params
object (optional)
a structured value that holds the parameter values to be used during the invocation of the method. This field may be omitted if the method doesn't take arguments
id
number (optional)
the identifier is established by the client. Komodo DeFi SDK will reply with the same value in the Response object if the id field is included and not NULL
Response (Success)
Structure
Type
Description
mmrpc
string
the string specifying the version of the Komodo DeFi SDK RPC protocol
result
object
the value of this field is determined by the method invoked on Komodo DeFi SDK
id
number (optional)
the identifier established by the client. The same value as in the Request if it was passed
Response (Error)
Structure
Type
Description
mmrpc
string
the string specifying the version of the Komodo DeFi API RPC protocol
error
string
the common error description
error_path
string
the error path consisting of file names separated by a dot similar to JSON path notation
error_trace
string
the error path consisting of file and line number pairs separated by ']'
error_type
string
the string error identifier used to determine the cause of the error
error_data
object
an object containing the error data of the corresponding error_type
id
number (optional)
the identifier established by the client. The same value as in the Request if it was passed
{
"mmrpc": "2.0",
"error": "The amount 0.000005 is too small",
"error_path": "utxo_common",
"error_trace": "utxo_common:1379] utxo_common:301]",
"error_type": "AmountIsTooSmall",
"error_data": {
"amount": "0.000005"
},
"id": 0
}
Common Komodo DeFi SDK Request / Response Objects
The folowing objects are used in the request or response of multiple Komodo DeFi SDK methods.
ActivationParams
The ActivationParams object defines additional parameters used for activation. These params may vary depending on the coin type.
Parameter
Type
Description
required_confirmations
integer
Optional. Confirmations to wait for steps in swap. Defaults to value in the coins file if not set.
requires_notarization
boolean
Optional, defaults to false. For dPoW protected coins, a true value will wait for transactions to be notarised when doing swaps. Overrides value if set in coins file.
mode
object
QTUM, UTXO & ZHTLC coins only. A standard ActivationMode object.
zcash_params_path
string
ZHTLC coins only. Path to folder containing Zcash parameters. Optional, defaults to standard location as defined in this guide
scan_blocks_per_iteration
integer
ZHTLC coins only. Sets the number of scanned blocks per iteration during BuildingWalletDb state. Optional, default value is 1000.
scan_interval_ms
integer
ZHTLC coins only. Sets the interval in milliseconds between iterations of BuildingWalletDb state. Optional, default value is 0.
tx_history
boolean
Optional. Enable transaction history scanning. When active, the Komodo DeFi Framework API will collect transaction history data for local storage, and allow use of the my_tx_history (v2) method.
min_addresses_number
integer
Optional, HD wallets only. Number of addresses to generate. If not specified, addresses will be generated up to path_to_address::address_index.
scan_policy
string
Optional, HD wallets only. Whether or not to scan for new addresses. Select from do_not_scan, scan_if_new_wallet or scan. Defaults to scan_if_new_wallet. Note that scan will result in multple requests to the Komodo DeFi API and may take some time to complete.
gap_limit
integer
Optional, HD wallets only. The max number of empty addresses in a row. Transactions sent to an address outside the gap_limit, will not be identified when scanning. Defaults to 20.
Optional, defaults to true. If false, coin and token balances will not be returned in the response, and the response will be returned more quickly.
Is priv\_key\_policy still a thing?
Defaults to `ContextPrivKey`. Set as `Trezor` to activate in Trezor mode.
For ZHTLC coins, older wallets need to set the `sync_params` field to a date before its
first transaction to see all balance and history. This may take a long time on the first
activation, but subsequent activations will be much faster.
Using a smaller `scan_blocks_per_iteration` and larger `scan_interval_ms`,
will reduce the average CPU load during ZHTLC coin activation (at the cost of a
longer activation time). These optional fields are recommended when developing
for iOS, where a high CPU load may kill the activation process. Android &
desktop operating systems do not appear to have any problems with high CPU
load during ZHTLC coin activation.
ActivationMode
Defines the activation mode for QTUM, BCH, UTXO & ZHTLC coins.
Parameter
Type
Description
rpc
string
Native if running a native blockchain node, Electrum if using electrum servers or Light for ZHTLC coins.
QTUM, BCH & UTXO coins only. A list of standard ActivationServers objects.
sync_params
integer or string
ZHTLC coins only. Optional, defaults to two days ago. Defines where to start scanning blockchain data upon initial activation. Options: "earliest" (the coin's sapling_activation_height), height (a specific block height) or date (a unix timestamp).
ActivationServers
Contains information electrum servers for coins being used in Electrum or Light mode.
Parameter
Type
Description
url
string
The URL and port for an electrum server.
ws_url
string
Optional, for WSS only. The URL and port for an electrum server's WSS port.
protocol
string
Optional, defaults to TCP. Transport protocol used to connect to the server. Options: TCP or SSL
disable_cert_verification
boolean
Optional, defaults to false. If true, this disables server SSL/TLS certificate verification (e.g. for self-signed certificates). Use at your own risk!
The AddressDerivationPath object defines the account / change / address_index of the derivation path used for your wallet. Using different values for account_id or address_id parameters will result in a different address and private key for each combination. The chain parameter is used to specify if the change from a transaction. Set to External for addresses that are intended to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used to return the leftover change from a transaction.
Parameter
Type
Description
account_id
integer
Optional, defaults to 0. Used as a layer of separation or hierarchy.
chain
string
Optional. Accepted values are External (0) and Internal (1). Defaults to External.
address_id
integer
Optional, defaults to 0. Used as a layer of separation or hierarchy.
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 Hierarchical Deterministic (HD) Wallet derivation path.
```json
{
"type": "Iguana"
}
```
EvmNode
The EvmNode object includes the following items for a given coin or token:
Parameter
Type
Description
url
string
URL of an RPC node
gui_auth
boolean
Optional, defaults to false. Must be set to true to access RPC nodes run officially by the Komodo Platform team
This object represents the number of blocks required for an on-chain lightning-related transaction to be confirmed.
It is used for estimating the transaction fee rate (feerate) for different transaction types in the context of permissionless transactions performed by the node. Different target types are background, normal, and high_priority.
Parameter
Type
Description
background
integer
Used for transactions that can tolerate slower confirmation times when the transaction fee rate decreases. These transactions are not time-sensitive and can afford to wait longer for confirmation. The recommended range is 12 to 144 blocks to ensure a low feerate.
normal
integer
Used for transactions that we want to confirm promptly, without significant delay (e.g, transactions for opening payment channels). These transactions are important but not critical. Suggested value is 6 blocks to ensure a moderate feerate.
high_priority
integer
Used for transactions that require quick confirmation to prevent potential loss of funds (e.g. redeeming a Hashed Time Lock Contract (HTLC) on the blockchain before it times out). These transactions are time-critical and must be confirmed promptly to ensure the security of funds. Recommended value for high_priority is 1-2 blocks to ensure a high feerate.
Using the recommended values in the above table with a coin that has a block time of 10 minutes, the equivalent time in minutes is:
background: 120 minutes to 1440 minutes (2 hours to 1 day).
normal: 60 minutes (one hour).
high_priority: 10 to 20 minutes.
CounterpartyChannelConfig
Parameter
Type
Description
allow_outbound_0conf
boolean
Optional, defaults to true. When setting an outbound channel, it can be used straight away without waiting for any on-chain confirmations.
force_announced_channel_preference
boolean
Optional, defaults to true. Set to force an incoming channel to match our announced channel preference in ChannelOptions announced_channel.
outbound_channels_confirmations
integer
Optional, defaults to 144. Confirmations we will wait for before considering an inbound channel locked in.
our_locktime_limit
boolean
Optional, defaults to 2016. Set to the amount of blocks we're willing to wait to claim money back to us.
min_funding_sats
boolean
Optional, defaults to 0. Minimum allowed satoshis when an inbound channel is funded.
max_funding_sats
boolean
Optional, defaults to 16777215. Maximum allowed satoshis when an inbound channel is funded.
max_htlc_minimum_msat
boolean
Optional, defaults to 18446744073709551615. The remote node sets a limit on the minimum size of HTLCs we can send to them. This allows us to limit the maximum minimum-size they can require.
min_max_htlc_value_in_flight_msat
boolean
Optional, defaults to 0. The remote node sets a limit on the maximum value of pending HTLCs to them at any given time to limit their funds exposure to HTLCs. This allows us to set a minimum such value.
max_channel_reserve_sats
boolean
Optional, defaults to 18446744073709551615. The remote node will require us to keep a certain amount in direct payment to ourselves at all time, ensuring that we are able to be punished if we broadcast an old state. This allows us to limit the amount which we will have to keep to ourselves (and cannot use for HTLCs).
min_max_accepted_htlcs
boolean
Optional, defaults to 0. The remote node sets a limit on the maximum number of pending HTLCs to them at any given time. This allows us to set a minimum such value.
FeeInfo
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
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 EthGas; sets the gas price in gwei units
gas
number (integer)
Used only when fee type is EthGas; sets the gas limit for transaction
Optional, defaults to 9735. The port that this node listens for incoming connections on.
color
string
Optional, defaults to 2b6680. A hexidecimal color string which will be used in network graphs on lightning explorers
payment_retries
integer
Optional, defaults to 5. Number of times a payment will be retried if it fails.
backup_path
string
Optional. The backup path for channel backups, preferably on an external drive.
LightningChannelAmount
Parameter
Type
Description
type
string
Exact for a specific amount or Max for whole balance.
value
object
Only required if type is Exact. The amount in BTC you want to open the channel with.
LightningChannelConfig
The values in this object are only used if the channel is being opened by the user. If the channel is being opened by the counterparty, the values in this object are ignored.
If not specified when using the [open\_channel](/komodo-defi-framework/api/v20-dev/lightning/channels/#open-channel) or [update\_channel](/komodo-defi-framework/api/v20-dev/lightning/channels/#update-channel) methods, the values in this object will default to the values set in the `coins` configuration file.
Parameter
Type
Description
inbound_channels_confirmations
string
Optional, defaults to 6. Should be set in coins file, and applies to all channels. Confirmations we will wait for before considering an inbound channel locked in.
max_inbound_in_flight_htlc_percent
integer
Optional, defaults to 10. Should be set in coins file, and applies to all channels. Sets the percentage of the channel value we will cap the total value of outstanding inbound HTLCs to.
our_htlc_minimum_msat
integer
Optional, defaults to 1. The smallest value HTLC we will accept to process. The channel gets closed any time our counterparty misbehaves by sending us an HTLC with a value smaller than this.
announced_channel
boolean
Optional, defaults to false. Set to announce the channel publicly and notify all nodes that they can route via this channel. GUIs and wallet apps should be set to false.
commit_upfront_shutdown_pubkey
boolean
Optional, defaults to true. When true (and the counterparty agrees), the user must use the same key for cooperative closing. This prevents a user from changing the destination address in a cooperative close, which slightly increases security (however, this option is not required if the counterparty does not support it and a channel can be accepted regardless). Note that the key for forced closing is always fixed when opening a channel and is different from shutdown_pubkey.
counterparty_locktime
integer
Optional, defaults to 144. The number of blocks we require our counterparty to wait to claim their money on chainif they broadcast a revoked transaction. We have to be online at least once during this time to punish our counterparty for broadcasting a revoked transaction. We have to account also for the time to broadcast and confirm our transaction, possibly with time in between to RBF (Replace-By-Fee) the spending transaction.
negotiate_scid_privacy
integer
Optional, defaults to false. If true, we attempt to negotiate the scid_privacy (referred to as scid_alias in the BOLTs) option for outbound private channels. This provides better privacy by not including our real on-chain channel UTXO in each invoice and requiring that our counterparty only relay HTLCs to us using the channel's SCID alias.
their_channel_reserve_sats
boolean
Optional, defaults to 10000 or 1% of channel value. The minimum balance that the other node has to maintain on their side, at all times. This ensures that if our counterparty broadcasts a revoked state, we can punish them by claiming at least this value on chain.
For GUIs and wallet apps, it is recommended to set `announced_channel` to `false` (the default value), as the node is not expected to be reliably online.
LightningChannelOptions
Parameter
Type
Description
proportional_fee_in_millionths_sats
integer
Optional, defaults to 0. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats.
base_fee_msat
integer
Optional, defaults to 1000. Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in excess of proportional_fee_in_millionths_sats.
Optional. Unique string identifying a channel by its ID.
counterparty_node_id
string
Optional. A hexidecimal string identifying a counterparty node.
funding_tx
string
Optional. A transaction ID which added funds.
from_funding_value_sats
integer
Optional. The minimum value of channel funding in satoshis.
to_funding_value_sats
integer
Optional. The maximum value of channel funding in satoshis.
is_outbound
boolean
Optional. If true, limits the response to outbound channels only.
from_balance_msat
integer
Optional. The minimum channel balance in millisatoshis.
to_balance_msat
integer
Optional. The maximum channel balance in millisatoshis.
from_outbound_capacity_msat
integer
Optional. The minimum outbound capacity of the channel balance in millisatoshis.
to_outbound_capacity_msat
integer
Optional. The maximum outbound capacity of the channel balance in millisatoshis.
from_inbound_capacity_msat
integer
Optional. The minimum inbound capacity of the channel balance in millisatoshis.
to_inbound_capacity_msat
integer
Optional. The maximum inbound capacity of the channel balance in millisatoshis.
confirmed
boolean
Optional. If true, only channels with channel opening transactions that passed the number of confirmations required for the channel to be usable will be returned.
is_usable
boolean
Optional. If true, only channels that are confirmed and the counterparty is online, meaning that these channels can be used for payments will be returned.
is_public
boolean
Optional. If true, only channels that our node announces to the lightning network, these channels are visible on lightning explorers will be returned.
LightningPayment
Parameter
Type
Description
type
string
The payment type. Accepted values are invoice or keysend.
invoice
string
Only used if type is invoice. An identifying string which represents the invoice.
destination
string
Only used if type is keysend. A node_pubkey (which is also the node address in lightning context). Not to be confused with an onchain address.
amount_in_msat
string
Only used if type is keysend. Amount to be paid, in millisatoshis (A thousandth of a satoshi; the same as 0.00000000001 bitcoin).
expiry
string
Only used if type is keysend. Optional, defaults to 3600. Seconds until the payment expires.
LightningPaymentFilter
Parameter
Type
Description
payment_type
object
A standard LightningPaymentType object.
description
string
Optional. A note to indicate the purpose of the invoice.
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
#### Example
{
"PageNumber": 1
}
{
"FromId": 4
}
HistoryTarget
Used to specify a HD wallet account_id or address_id for [my_tx_history (v2)] requests.
Parameter
Type
Description
type
string
Filters results by account_id or address_id part of the derivation path.
account_id
integer
ACCOUNT_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path.
address_id
integer
Only required when type is address_id. ADDRESS_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path.
chain
string
Only required when type is address_id. Internal, or External. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change.
The WithdrawFromInfo response object includes the following items for HD Wallet withdraw (v2) requests.
You can use either the derivation_path on its own, or the account_id, chain and address_id together.
ACCOUNT_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path. Please don't confuse with the global account.
address_id
integer
ADDRESS_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path.
chain
string
Internal, or External. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change.
FeeInfo
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
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 EthGas; sets the gas price in gwei units
gas
number (integer)
Used only when fee type is EthGas; sets the gas limit for transaction
ScanAddressesInfo
The ScanAddressesInfo response object includes the following items for request in HD mode:
Parameter
Type
Description
account_index
integer
ACCOUNT_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path. Please don't confuse with the global account.
Internal, or External. External is used for addresses that are meant to be visible outside of the wallet (e.g. for receiving payments). Internal is used for addresses which are not meant to be visible outside of the wallet and is used for return transaction change.
WalletAccountInfo
The WalletAccountInfo object includes the following items in the activation response for a coin in HD mode:
Parameter
Type
Description
account_index
integer
ACCOUNT_ID child in the m/44'/COIN'/ACCOUNT_ID'/CHAIN/ADDRESS_ID BIP44 derivation path. Please don't confuse with the global account.
derivation_path
string
Derivation path up to the COIN child. E.g. "m/44'/141'/0'"
{
"mmrpc": "2.0",
"error": "Storage is not initialized for TTT-SLP",
"error_path": "my_tx_history_v2",
"error_trace": "my_tx_history_v2:343]",
"error_type": "StorageIsNotInitialized",
"error_data": "Storage is not initialized for TTT-SLP",
"id": null
}
There are some common objects that are used in the Komodo DeFi SDK RPC protocol. These standard objects have been collected and grouped into the following sections: