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.
Before using this method, launch the KomoDeFi API, and plug in your Trezor.
| Parameter | Type | Description |
|---|---|---|
| device_pubkey | string | Optional. 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 |
| Parameter | Type | Description |
|---|---|---|
| task_id | integer | An identifying number which is used to query task status. |
{
"userpass": "testpsw",
"mmrpc": "2.0",
"method": "task::init_trezor::init",
"params": {}
}
{
"userpass": "testpsw",
"mmrpc": "2.0",
"method": "task::init_trezor::init",
"params": {
"device_pubkey": "066deb87b0d0500ec2e9b85f5314870b03a53517"
}
}
After running the task::init_trezor::init method, we can query the status of device initialisation to check its progress.
| 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. |
| Parameter | Type | Description |
|---|---|---|
| status | string | A short indication of how the requested process is progressing. |
| details | object | Depending on the state of process progress, this will contain different information as detailed in the items below. |
| details.type | string | Type of hardware wallet device (e.g. Trezor) |
| details.model | string | The model of the hardware wallet device (e.g. One or T) |
| details.device_name | string | The name of the device as defned by user in Trezor Suite or another wallet application. |
| details.device_id | string (hex) | An unique identifier of the device, set during manufacturing. |
| details.device_pubkey | string (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. |
{
"userpass": "testpsw",
"mmrpc": "2.0",
"method": "task::init_trezor::status",
"params": {
"task_id": 0,
"forget_if_finished": false
}
}
Use the task::init_trezor::cancel method to cancel the initialisation task.
| Parameter | Type | Description |
|---|---|---|
| task_id | integer | The identifying number returned when initiating the initialisation process. |
| Parameter | Type | Description |
|---|---|---|
| result | string | Returns with value success when successful, otherwise returns the error values below |
| error | string | Description of the error |
| 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 |
{
"userpass": "testpsw",
"mmrpc": "2.0",
"method": "task::init_trezor::cancel",
"params": {
"task_id": 0
}
}
When you see the pin grid on your device, or it asks for a passphrase word, use this method.
| 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 | Either TrezorPin or TrezorPassphrase, depending on which is requested by responses from related methods returning "status": "UserActionRequired" |
| 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. |
| user_action.passphrase | string | The 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. |
| Parameter | Type | Description |
|---|---|---|
| result | string | The 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
}
{
"userpass": "testpsw",
"mmrpc": "2.0",
"method": "task::init_trezor::user_action",
"params": {
"task_id": 0,
"user_action": {
"action_type": "TrezorPin",
"pin": "862743"
}
}
}
{
"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
}