Add Hardware wallet docs

[sergeyboyko0791]

I tried to describe the API in as much detail as possible for the integration into GUI.
https://github.com/KomodoPlatform/air_dex/issues/502

But there are still not documented RPCs, and the final API refactoring PR hasn't been merged yet, so this task is more to remember to write documentation when the PR is merged.

[sergeyboyko0791]

@smk762 corresponding PR has been merged, we can now update the docs.
I prepared changes in Postman collection, hope it will help you. Also there are comprehensive comments in https://github.com/KomodoPlatform/air_dex/issues/502

[smk762]

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\""task::init_trezor::init"\",\"mmrpc\":\"2.0\",\"params\":{}}"

curl --url "http://127.0.0.1:7783" --data "{\"userpass\":\"$userpass\",\"method\":\""task::init_trezor::status"\",\"mmrpc\":\"2.0\",\"params\":{\"task_id\":$1}}"


curl --url "http://127.0.0.1:7783" --data '{
    "userpass": "'$userpass'",
    "method": "task::init_trezor::user_action",
    "mmrpc": "2.0",
    "params": {
        "task_id": '${1}',
        "user_action": {
            "action_type": "TrezorPin",
            "pin": "'${2}'"
        }
    }
}'


curl --url "http://127.0.0.1:7783" --data '{
    "userpass": "'$userpass'",
    "method": "task::init_trezor::user_action",
    "mmrpc": "2.0",
    "params": {
        "task_id": '${1}',
        "user_action": {
            "action_type": "TrezorPassphrase",
            "passphrase": "'${2}'"
        }
    }
}'

[smk762]

@smk762 corresponding PR has been merged, we can now update the docs. I prepared changes in Postman collection, hope it will help you. Also there are comprehensive comments in KomodoPlatform/WebDEX#502

Thanks for the detailed notes! I've managed to test auth & activation so far, and added a top section of the doc as a draft which will link to the related methods.

[smk762]

@sergeyboyko0791 While testing the task::init_trezor::user_action method, I seem to get a success response regardless of input, even when I enter the wrong PIN or an empty string. Is this because any input is accepted but leads to different hidden addresses? How do I trigger error states?
I'm using 2.1.8796_mm2-hd-account_27b0928d5_Linux_Release - please let me know if a different branch would be better.

[sergeyboyko0791]

@smk762 Do you mean TrezorPassphrase?

{
    "userpass": "...",
    "mmrpc": "2.0",
    "method": "task::init_trezor::user_action",
    "params": {
        "task_id": 0,
        "user_action": {
            "action_type": "TrezorPassphrase",
            "passphrase": "PASSPHRASE HERE"
        }
    }
}

Yes, "" (i.e. an emoty passphrase) means a default account. This default account is the same if you disable the passphrase feature.
Any other passphrases lead to the creation/use of hidden accounts.

But if you mean TrezorPin action type, then it's weird behaviour. Trezor should not allow to login to the wallet if the pin is incorrect.

[smk762]

Yeah it was definitely TrezorPIN

smk762@pig:~/mm2_777$ ./init_trezor.sh
{"mmrpc":"2.0","result":{"task_id":0},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_status.sh 0
{"mmrpc":"2.0","result":{"status":"UserActionRequired","details":"EnterTrezorPin"},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_useraction_pin.sh 0 "234521"
{"mmrpc":"2.0","result":"success","id":null}

# Restarted mm2

smk762@pig:~/mm2_777$ ./init_trezor.sh
{"mmrpc":"2.0","result":{"task_id":0},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_status.sh 0
{"mmrpc":"2.0","result":{"status":"UserActionRequired","details":"EnterTrezorPin"},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_useraction_pin.sh 0 "23452332412452345234523451"
{"mmrpc":"2.0","result":"success","id":null}

# Restarted mm2

smk762@pig:~/mm2_777$ ./init_trezor.sh
{"mmrpc":"2.0","result":{"task_id":0},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_status.sh 0
{"mmrpc":"2.0","result":{"status":"UserActionRequired","details":"EnterTrezorPin"},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_useraction_pin.sh 0 ""
{"mmrpc":"2.0","result":"success","id":null}

smk762@pig:~/mm2_777$ ./version.sh
{"result":"2.1.8796_mm2-hd-account_27b0928d5_Linux_Release","datetime":"2022-11-15T23:40:49+01:00"}

smk762@pig:~/mm2_777$ cat ./init_trezor_useraction_pin.sh
#!/bin/bash
source userpass
curl --url "http://127.0.0.1:7783" --data '{
    "userpass": "'$userpass'",
    "method": "task::init_trezor::user_action",
    "mmrpc": "2.0",
    "params": {
        "task_id": '${1}',
        "user_action": {
            "action_type": "TrezorPin",
            "pin": "'${2}'"
        }
    }
}'
echo

The RPC returns "success" - though not yet tested if trezor will allow an action like withdraw from this yet - will check today to see if it is just RPC response implying success but it wasnt really.

[smk762]

I can confirm - though the status RPC return "success" after an incorrect PIN input, attempts to use subsequent methods appear to be blocked:

# After using wrong pin
{"mmrpc":"2.0","result":{"status":"Error","details":{"error":"Error on platform coin QTUM creation: Hardware Wallet context is not initialized","error_path":"lib.init_qtum_activation.utxo_coin_builder","error_trace":"lib:103] init_qtum_activation:71] utxo_coin_builder:317]","error_type":"CoinCreationError","error_data":{"ticker":"QTUM","error":"Hardware Wallet context is not initialized"}}},"id":null}

Are we able to detect Hardware Wallet context is not initialized once PIN has been input but before returning the success response?

[sergeyboyko0791]

I think that I figured it out . If you send a task::*::user_action, it will fail in only three cases:

1. There is no such method.
2. An error occurred while deserialization the request (i.e. incorrect payload).
3. There is no such RPC task (rpc_task field).

In any other case the task::*::user_action will succeed, and the error can be fetched on task::*::status.
So,

smk762@pig:~/mm2_777$ ./init_trezor.sh
{"mmrpc":"2.0","result":{"task_id":0},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_status.sh 0
{"mmrpc":"2.0","result":{"status":"UserActionRequired","details":"EnterTrezorPin"},"id":null}

smk762@pig:~/mm2_777$ ./init_trezor_useraction_pin.sh 0 "234521"
{"mmrpc":"2.0","result":"success","id":null}

smk762@pig:~/mm2_777$ ./init_trezor_status.sh 0
{"mmrpc":"2.0","error":"Invalid PIN","error_trace":"TRACE",...}

[smk762]

@sergeyboyko0791 I was just testing the task::init_trezor::cancel method, and I see it returns success but in logs there is
20 08:50:09, rpc_task:manager:160] WARN Finished task '0' was not ongoing and the pin grid is still visible in trezor.

After cancelling, attempting to enter pin returns {"mmrpc":"2.0","error":"Internal error: RPC '1' task is in unexpected status. Actual: 'Finished', expected: 'AwaitingUserAction'","error_path":"init_hw.manager","error_trace":"init_hw:196] manager:253]","error_type":"Internal","error_data":"RPC '1' task is in unexpected status. Actual: 'Finished', expected: 'AwaitingUserAction'","id":null}

If I run init again and enter pin for the next task id, it responds as expected. Is it possible to to have the task cancellation also cancel the device request for pin?

[sergeyboyko0791]

Thank you for the issue! I've checked, and this happens if the RPC task is in awaiting status (waiting for the user action like PIN or PASSPHRASE).
I'm thinking about how to fix this.

[sergeyboyko0791]

I've fixed task::*::cancel issue at KomodoPlatform/komodo-defi-framework#1582

20 08:50:09, rpc_task:manager:160] WARN Finished task '0' was not ongoing and the pin grid is still visible in trezor.

This is definitely possible, but I couldn't implement a quick and simple solution.
I created the issue: KomodoPlatform/komodo-defi-framework#1586

Is it possible to to have the task cancellation also cancel the device request for pin?