Task: UTXO Activation

API-v2task::enable_utxo::init

task::enable_utxo::init

Use this method for task managed activation of UTXO coins like KMD, LTC, BTC & DOGE. Refer to the task managed activation overview for activation of other coin types.

Arguments

Parameter	Type	Description
ticker	string	The ticker of the coin you want to enable.
activation_params	object	An object containing the actvation parameters below.
.priv_key_policy	object	Optional. A standard PrivKeyPolicy object. Defaults to `{"type": "ContextPrivKey"}`.
.min_addresses_number	integer	How many additional addreesses to generate at a minimum.
.scan_policy	string	Whether or not to scan for new addresses. Select from `do_not_scan`, `scan_if_new_wallet` or `scan`. Note that `scan` will result in multple requests to the Komodo DeFi Framework.
.gap_limit	integer	The max number of empty addresses in a row. If transactions were sent to an address outside the `gap_limit`, they will not be identified when scanning.
.mode	object	An object containing RPC type and data parameters as below.
..rpc	string	UTXO RPC mode. Options: `{ "rpc":"Native" }` if running a native blockchain node, or `"rpc":"Electrum"` to use electrum RPCs. If using electrum, a list of electrum servers is required under `rpc_data.servers`
..rpc_data	object	An object containing electrum server information.
...servers	list	A list of electrum server URLs (https://github.com/KomodoPlatform/coins/tree/master/electrums)
....url	object	The url and port of a coins electrum server
....ws_url	object	Optional. Used to define electrum server url/port for websocket connections.
....protocol	object	Defines electrum server protocol as `TCP` or `SSL`. Defaults to `TCP`
....disable_cert_verification	boolean	Optional. For `SSL` electrum connections, this will allow expired certificates.

Response

Parameter	Type	Description
task_id	integer	An identifying number which is used to query task status.

📌 Examples

Activation in Trezor mode

task::enable_utxo::init

POST

task::enable_utxo::init

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::init",
  "params": {
    "ticker": "KMD",
    "activation_params": {
      "mode": {
        "rpc": "Electrum",
        "rpc_data": {
          "servers": [
            {
              "url": "kmd.electrum3.cipig.net:20001",
              "protocol": "SSL"
            },
            {
              "url": "kmd.electrum3.cipig.net:10001",
              "protocol": "TCP"
            },
            {
              "url": "kmd.electrum2.cipig.net:30001",
              "protocol": "WSS"
            }
          ]
        }
      },
      "scan_policy": "scan_if_new_wallet",
      "priv_key_policy": {
        "type": "Trezor"
      },
      "min_addresses_number": 3,
      "gap_limit": 20
    }
  }
}

Response

{
  "mmrpc": "2.0",
  "result": {
    "task_id": 1
  },
  "id": null
}

API-v2task::enable_utxo::status

task::enable_utxo::status

After running the task::enable_utxo::init method, we can query the status of activation to check its progress. The response will return the following:

Result of the task (success or error)
Progress status (what state the task is in)
Required user action (what user should do before the task can continue)

Arguments

Parameter	Type	Description
task_id	integer	The identifying number returned when initiating the initialisation process.
forget_if_finished	boolean	If `false`, will return final response for completed tasks. Optional, defaults to `true`.

Command

task::enable_utxo::status

POST

task::enable_utxo::status

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::status",
  "params": {
    "task_id": 1,
    "forget_if_finished": false
  }
}

Parameter	Type	Description
status	string	A short indication of how the enabling is progressing.
details	object	Depending on the state of enabling progress, this will contain different information as shown in the responses below.

Possible status values while activation is in progress:

ActivatingCoin: The first step of activation. It does not require any action from the user.
RequestingWalletBalance: The first step of activation, while initial balances info is being requested. It does not require any action from the user.
Finishing: Activation process completed
WaitingForTrezorToConnect: Waiting for the user to plugin a Trezor device
FollowHwDeviceInstructions: Waiting for the user to follow the instructions on the device

Once complete, status will be Ok, and the details object will have the following structure:

Response (ready, successful, HD mode)

Parameter	Type	Description
current_block	integer	Block height of the coin being activated
ticker	string	Ticker of the coin being activated.
wallet_balance	object	A standard WalletBalanceInfo object. Note: the structure may vary based on the `get_balances` parameter value in the activation request.

{
  "mmrpc": "2.0",
  "result": {
      "status": "Ok",
      "details": {
          "ticker": "KMD",
          "current_block": 4230457,
          "wallet_balance": {
              "wallet_type": "HD",
              "accounts": [
                  {
                      "account_index": 0,
                      "derivation_path": "m/44'/141'/0'",
                      "total_balance": {
                          "KMD": {
                              "spendable": "20",
                              "unspendable": "0"
                          }
                      },
                      "addresses": [
                          {
                              "address": "RMC1cWXngQf2117apEKoLh3x27NoG88yzd",
                              "derivation_path": "m/44'/141'/0'/0/0",
                              "chain": "External",
                              "balance": {
                                  "KMD": {
                                      "spendable": "20",
                                      "unspendable": "0"
                                  }
                              }
                          }
                      ]
                  }
              ]
          }
      }
  },
  "id": null
}

{
  "mmrpc": "2.0",
  "result": {
      "status": "Ok",
      "details": {
          "ticker": "KMD",
          "current_block": 4230467,
          "wallet_balance": {
              "wallet_type": "Iguana",
              "address": "RUYJYSTuCKm9gouWzQN1LirHFEYThwzA2d",
              "balance": {
                  "KMD": {
                      "spendable": "1718.15606485",
                      "unspendable": "0"
                  }
              }
          }
      }
  },
  "id": null
}

Response (in progress)

{
  "mmrpc": "2.0",
  "result": {
    "status": "InProgress",
    "details": "RequestingWalletBalance"
  },
  "id": null
}

Response (ready, error)

Parameter	Type	Description
status	string	A short indication of how the requested process is progressing.
details.result	object	Depending on the state of process progress, this will contain different information as detailed in the items below.
.error	string	The ticker of the coin being activated
.error_path	string	Used for debugging. A reference to the function in code base which returned the error
.error_trace	string	Used for debugging. A trace of lines of code which led to the returned error
.error_type	string	An enumerated error identifier to indicate the category of error
.error_data	string	Additonal context for the error type

Possible Error Cases:

TaskTimedOut - Timed out waiting for coin activation, connecting to the device trezor or for user to confirm pubkey)
CoinCreationError - Error during activation. E.g. incorrect or inactive electrum servers.
HwError - This is the most important error type. Unlike other error types, HwError requires the GUI / User to check the details in error_data field to know which action is required. View the HwError error type details for more info.

API-v2task::enable_utxo::user_action

task::enable_utxo::user_action

If the task::enable_utxo::status returns UserActionRequired, we need to use the task::enable_utxo::user_action method to enter our PIN

Arguments

Parameter	Type	Description
task_id	integer	The identifying number returned when initiating the initialisation process.
user_action	object	Object containing the params below
user_action.action_type	string	Will be `TrezorPin` for this method
user_action.pin	string (number)	When the Trezor device is displaying a grid of numbers for PIN entry, this param will contain your Trezor pin, as mapped through your keyboard numpad. See the image below for more information.

Response

Parameter	Type	Description
result	string	The outcome of the request.

📌 Examples

Command

task::enable_utxo::user_action

POST

task::enable_utxo::user_action

{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_utxo::user_action",
  "params": {
    "task_id": 1,
    "user_action": {
      "action_type": "TrezorPin",
      "pin": "862743"
    }
  }
}

Response (success)

{
  "mmrpc": "2.0",
  "result": "success",
  "id": null
}

API-v2task::enable_utxo::cancel

task::enable_utxo::cancel

If you want to cancel the enabling process before it has completed, you can use this method.

Arguments

Structure	Type	Description
task_id	integer	The identifying number returned when initiating the enabling process.

Response

Structure	Type	Description
result	string	Indicates task cancellation was succesful.
error	string	An error message to explain what went wrong.
error_path	string	An indicator of the class or function which reurned the error.
error_trace	string	An indicator of where in the source code the error was thrown.
error_type	string	An enumerated value for the returned error.
error_data	string	The input task ID which resulted in the error.

task::enable_utxo::cancel

POST

task::enable_utxo::cancel

{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_utxo::cancel",
  "mmrpc": "2.0",
  "params": {
    "task_id": 1
  }
}

Response (success)

{
  "mmrpc": "2.0",
  "result": "success",
  "id": null
}

Response (success - already finished)

{
  "mmrpc": "2.0",
  "error": "Task is finished already",
  "error_path": "init_standalone_coin.manager",
  "error_trace": "init_standalone_coin:144] manager:101]",
  "error_type": "TaskFinished",
  "error_data": 0,
  "id": null
}

Response (error - no such task)

{
  "mmrpc": "2.0",
  "error": "No such task '3'",
  "error_path": "init_standalone_coin",
  "error_trace": "init_standalone_coin:119]",
  "error_type": "NoSuchTask",
  "error_data": 3,
  "id": null
}

On this page

Task: UTXO Activation

task::enable_utxo::init

task::enable_utxo::status

task::enable_utxo::user_action

task::enable_utxo::cancel