latest contributor to this doc

Last Edit: @gcharang ,

Trezor Initialisation

The methods below prepare your Trezor device for use within the KomoDeFi API. Once completed, you can authenticate using your PIN or phrase with task::init_trezor::user_action.

Methods with a task:: prefix will be linked to a numeric task_id value which can be used to query the status or outcome of a task.

API-v2task::init_trezor::init

Before using this method, launch the KomoDeFi API, and plug in your Trezor.

ParameterTypeDescription
device_pubkeystringOptional. If known, you can specify the device pubkey. If not known, this will be part of the task::init_trezor::status response which you can save for future use

ParameterTypeDescription
task_idintegerAn identifying number which is used to query task status.

POST
task::init_trezor::init
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::init",
  "params": {}
}

POST
task::init_trezor::init
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::init",
  "params": {
    "device_pubkey": "066deb87b0d0500ec2e9b85f5314870b03a53517"
  }
}
API-v2task::init_trezor::status

After running the task::init_trezor::init method, we can query the status of device initialisation to check its progress.

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.
forget_if_finishedbooleanIf false, will return final response for completed tasks. Optional, defaults to true.

ParameterTypeDescription
statusstringA short indication of how the requested process is progressing.
detailsobjectDepending on the state of process progress, this will contain different information as detailed in the items below.
details.typestringType of hardware wallet device (e.g. Trezor)
details.modelstringThe model of the hardware wallet device (e.g. One or T)
details.device_namestringThe name of the device as defned by user in Trezor Suite or another wallet application.
details.device_idstring (hex)An unique identifier of the device, set during manufacturing.
details.device_pubkeystring (hex)The hardware wallet device's pubkey. If included in the task::init_trezor::init request, it wll be the same as input. If not, it should be stored for future use.

POST
task::init_trezor::status
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::status",
  "params": {
    "task_id": 0,
    "forget_if_finished": false
  }
}
API-v2task::init_trezor::cancel

Use the task::init_trezor::cancel method to cancel the initialisation task.

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.

ParameterTypeDescription
resultstringReturns with value success when successful, otherwise returns the error values below
errorstringDescription of the error
error_pathstringUsed for debugging. A reference to the function in code base which returned the error
error_tracestringUsed for debugging. A trace of lines of code which led to the returned error
error_typestringAn enumerated error identifier to indicate the category of error
error_datastringAdditonal context for the error type

POST
task::init_trezor::cancel
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::cancel",
  "params": {
    "task_id": 0
  }
}
API-v2task::init_trezor::user_action

When you see the pin grid on your device, or it asks for a passphrase word, use this method.

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.
user_actionobjectObject containing the params below
user_action.action_typestringEither TrezorPin or TrezorPassphrase, depending on which is requested by responses from related methods returning "status": "UserActionRequired"
user_action.pinstring (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.
user_action.passphrasestringThe passphrase functions like an extra word added to your recovery seed, and it used to access hidden wallets. To access the default wallet, input an empty string here.
Trezor Pin

ParameterTypeDescription
resultstringThe outcome of the request.

Even an incorrect PIN will return success. This doesn't mean the PIN was accepted, just that it was communicated without errors. If the PIN was incorrect, you will see an error like below in the next response for a method that requires authentication.

{
  "mmrpc": "2.0",
  "result": {
    "status": "Error",
    "details": {
      "error": "Error on platform coin KMD creation: Hardware Wallet context is not initialized",
      "error_path": "lib.init_utxo_standard_activation.utxo_coin_builder",
      "error_trace": "lib:103] init_utxo_standard_activation:79] utxo_coin_builder:317]",
      "error_type": "CoinCreationError",
      "error_data": {
        "ticker": "KMD",
        "error": "Hardware Wallet context is not initialized"
      }
    }
  },
  "id": null
}

POST
task::init_trezor::user_action
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::user_action",
  "params": {
    "task_id": 0,
    "user_action": {
      "action_type": "TrezorPin",
      "pin": "862743"
    }
  }
}

POST
task::init_trezor::user_action
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "task::init_trezor::user_action",
  "params": {
    "task_id": 0,
    "user_action": {
      "action_type": "TrezorPassphrase",
      "passphrase": "breakfast"
    }
  }
}

When requesting the status of a task, if an error_type of HwError is returned, the GUI / User should check the details in error_data field to know which action is required (as detailed below).

The connected Trezor device has a different pubkey value than what was specified in the device_pubkey parameter

{
  "mmrpc": "2.0",
  "result": {
    "status": "Error",
    "details": {
      "error": "Found unexpected device. Please re-initialize Hardware wallet",
      "error_path": "lib.common_impl.coin_balance.utxo_common.hd_pubkey.hw_ctx",
      "error_trace": "lib:93] common_impl:46] coin_balance:304] utxo_common:163] hd_pubkey:176] hw_ctx:149]",
      "error_type": "HwError",
      "error_data": "FoundUnexpectedDevice"
    }
  },
  "id": null
}

Multiple Trezor devices are plugged in. Remove the additional devices, and keep the one you want to use plugged in.

{
  "mmrpc": "2.0",
  "result": {
    "status": "Error",
    "details": {
      "error": "Found multiple devices. Please unplug unused devices",
      "error_path": "init_hw.crypto_ctx.hw_client",
      "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_client:152] hw_client:126]",
      "error_type": "HwError",
      "error_data": "FoundMultipleDevices"
    }
  },
  "id": null
}

No Trezor device detected by the KomoDeFi API. Make sure it is plugged in, or try a different USB cable / port.

{
  "mmrpc": "2.0",
  "result": {
    "status": "Error",
    "details": {
      "error": "No Trezor device available",
      "error_path": "init_hw.crypto_ctx.hw_ctx.response.usb.libusb",
      "error_trace": "init_hw:151] crypto_ctx:248] crypto_ctx:354] hw_ctx:120] response:136] usb:46] libusb:195]",
      "error_type": "HwError",
      "error_data": "NoTrezorDeviceAvailable"
    }
  },
  "id": null
}