GDK Hardware Wallet Interface

This section details the format of data requests from hardware wallet interaction during resolution of GA_auth_handler processing when GA_auth_handler_get_status returns the status "resolve_code" with a "required_data" element present.

Required Data JSON

Returned as an element "required_data" of Auth handler status JSON when data is required from a registered hardware device.

{
  "action": "",
  "device": {
  },
}

action:: Describes the hardware wallet data requested.
device:: Contains the HW device JSON originally registered with the session.

Additional fields will be present depending on the action requested, as follows:

Hardware Get XPubs Action

When "action" is "get_xpubs", this describes a request to compute one or more xpubs from the wallet’s master key.

{
  "paths": [ [], [ 2147501889 ] ]
}

paths:: An array of unsigned 32-bit integer arrays representing each xpub to fetch. The integer values should be interpreted per BIP32, i.e. the topmost bit may be set to indicate a private derivation in the path. An empty array indicates that the top level xpub should be returned.

Expected response:

{
  "xpubs": [
    "tpubD8G8MPH9RK9uk4EV97RxhzaY8SJPUWXnViHUwji92i8B7vYdht797PPDrJveeathnKxonJe8SbaScAC1YJ8xAzZbH9UvywrzpQTQh5pekkk",
    "tpubD6NzVbkrYhZ4X9jwmpJxg1kjEJTQgkrnHNEWww2e86X1eUfWu1f7hZpgezAyWUk5zRt4fMPHB33CXrvJSYHHAoVMFXrfxpornvJBgbvjvLN"
  ]
}

xpubs:: An array of base58-encoded BIP32 extended public keys, in the same order as the "paths" elements in the request.

Hardware Get Master Blinding Key Action

When "action" is "get_master_blinding_key", this describes a request to return the wallet’s SLIP0077 master blinding key if the user allows this.

Note

This action is only returned when using the Liquid network.

No request data is currently associated with this request.

Expected response:

{
  "master_blinding_key": "512cd6c0b73452a2414e9d86d37cdcc8283b44f0b6dd2b1eec23c59ff12b4f7e5949569b3430220dafce1e0e299a2a6f3fb3e62b2e8c860c82512cdf2d8b2fbc"
}

master_blinding_key:: The 512-bit or 256-bit master blinding key for the wallet, hex-encoded. If a 256-bit key is returned, it should be the lower 256-bits of the SLIP0021 derived node as specified in https://github.com/satoshilabs/slips/blob/master/slip-0077.md.

Note

If the user denies the request to share the key, an empty string should be returned.

Hardware Sign Message Action

When "action" is "sign_message", this describes a request to sign a message using the given path.

{
  "message": "A text message to sign",
  "path": [ 1195487518 ],
  "use_ae_protocol": false,
}

message:: The message to be utf-8 encoded and signed.
path:: The path from the wallet’s master key to the key that the message should be signed with.
use_ae_protocol:: true if the hardware device advertises Anti-Exfil support and it should be used for signing, false otherwise. See Anti-Exfil Request Data / Anti-Exfil Reply Data.

Expected response:

{
  "signature": "304402207c673ef4255873cf095016c98c4982cea9a5133060b66a380f1bf3880e54f6c8022056fd731cbd44cd96366212439717a888470ed481628cba81195c557d5c4fc39c"
}

signature:: The ECDSA signature corresponding to the given message. It must be returned as hex-encoded DER format, without a sighash byte, and must be in low-S form. Additionally, if the HW device JSON for the signer indicates low-R support, and Anti-Exfil is not being used, the signature must also be low-R.

Hardware Get Blinding Public Keys Action

When "action" is "get_blinding_public_keys", this describes a request to compute blinding public keys from wallet scripts.

Note

This action is only returned when using the Liquid network.

{
  "scripts": [ "a91403f650e2434916d5b7f124de8f673442b696282887" ]
}

scripts:: An array of hex-encoded scripts for which a blinding key should be generated.

Expected response:

{
  "public_keys": [ "02045e92b8f68bd066180c05a39969f862a67f4efc8f5d7aeca32c627a463b8f27" ]
}

public_keys:: An array of hex-encoded compressed public keys for blinding the given scripts.

Hardware Get Blinding Nonces Action

When "action" is "get_blinding_nonces", this describes a request to compute blinding nonces and possibly blinding public keys for the given scripts and shared public keys.

Note

This action is only returned when using the Liquid network.

{
  "blinding_keys_required": true
  "scripts": [ "a91403f650e2434916d5b7f124de8f673442b696282887" ],
  "public_keys": [ "035f242d49b88ca17948b156263e1f0c86d2cc9e9ff316b058dbbdb351e34bc9aa" ]
}

blinding_keys_required:: true if the blinding public keys must be returned, false otherwise. Blinding public keys are not requested if the master blinding key has previously been given.
public_keys:: An array of hex-encoded compressed shared public keys for computing the nonces.
scripts:: An array of hex-encoded scripts for which a blinding key should be generated and then the nonce computed using the public key given.

Expected response:

{
  "public_keys": [ "02045e92b8f68bd066180c05a39969f862a67f4efc8f5d7aeca32c627a463b8f27" ]
  "nonces": [ "8d940a5ec4ad122394cd2596ecfbf933a8d8fb0196015cc0a35399e3c326758c" ]
}

public_keys:: An array of hex-encoded compressed public keys for blinding the given scripts. Must be present if "blinding_keys_required" was true in the request, and absent otherwise.
nonces:: An array of hex-encoded 256 bit blinding nonces.

Hardware Get Blinding Factors Action

When "action" is "get_blinding_factors", this describes a request to compute asset (ABF) and value (VBF) blinding factors for the given transaction outputs.

Note

This action is only returned when using the Liquid network.

{
  "is_partial": false,
  "transaction_outputs": [],
  "transaction_inputs": [
    {
      "txhash": "797c40d53c4a5372303f765281bb107c40ed9618646c46851514ff0483bee894"
      "pt_idx": 2,
    },
    {
      "txhash": "9c7cffca5711968a22b8a03cc6d17224d0d85d884a4d2f638371b6fd6d59afdb"
      "pt_idx": 1,
    }
  ]
}

is_partial:: true if transaction is incomplete, e.g. one half of a swap transaction.
transaction_outputs:: The transaction output details for the outputs to be blinded, in the format returned by GA_create_transaction. Any output with a "blinding_key" key present requires blinding factors to be returned. When "is_partial" is false, the final vbf need not be returned. An empty string should be returned for blinding factors that are not required. It is not an error to provide blinding factors that are not required; they will be ignored.
transaction_inputs:: An array of prevout txids and their indices, supplied so the request handler can compute hashPrevouts for deterministic blinding.

Expected response:

{
  "amountblinders": [
    "ce8259bd2e7fa7d6695ade7cf8481919612df28e164a9f89cd96aace69a78bb9",
    ""
  ],
  "assetblinders": [
    "5ca806862967cde0d51950dd4e9add68e7cae8cda928750037fca1fb9cfc9e58",
    "5748810a8d2c4d87ea8c3038fb71369d8d9c85f09cfa4f6412359910fce93616"
  ]
}

amountblinders:: An array of hex-encoded, display format value blinding factors (VBFs) to blind the transaction output values. Any non-required values should be returned as empty strings.
assetblinders:: An array of hex-encoded, display format asset blinding factors (ABFs) to blind the transaction output assets. Any non-required values should be returned as empty strings.

Hardware Sign Transaction Action

When "action" is "sign_tx", this describes a request to sign one or more inputs of a transaction.

{
  "transaction": "0200000000010135d2bb82963e54a9060567b101760530797590d2b4a636606c4f1e6ac62bed4300000000230000000000000000000000000000000000000000000000000000000000000000000000fdffffff02f8ae00000000000017a9149aaba80ae1e733f8fb4034abcb6bd835608a5c9e87881300000000000017a9148b7f781fc9425ffaeafcd4973d3ae1dc9a09d02b87040048000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000480000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004e210375d1b5be6c3f60759fd594b27a05459095ce0f371372d2f0297691c39357a60aad2102129801c6d879b59f27472ba1ac3e8b20dd1693885ad0e9640827a4bd475dfeafac73640380ca00b268c9000000"
  "transaction_inputs": [],
  "transaction_outputs": [],
  "use_ae_protocol": false,
  "is_partial": false
}

transaction:: The hex-encoded transaction to sign.
transaction_inputs:: Contains details of each of the inputs in the transaction, in the format returned by GA_create_transaction. Any input without a "skip_signing" key present and set to true requires a signature to be returned. An empty string should be returned for signatures that are not required.
transaction_outputs:: The transaction output details for the outputs to be signed, in the format returned by GA_create_transaction.
use_ae_protocol:: true if the hardware device advertises Anti-Exfil support and it should be used for signing, false otherwise. See Anti-Exfil Request Data / Anti-Exfil Reply Data.
is_partial:: true if transaction is incomplete, e.g. one half of a swap transaction.

Expected response:

{
  "signatures": [ "30440220580c7ef934d5d8f31c1c592fbf0e5bc3267b76995206f0eb61616eb2f8f6e1c4022022e3feaf88469328bdaff3990a6069bda4e320e46e0531ba1e403cd50a9252e901" ]
}

signatures:: The ECDSA signatures corresponding to each input in the request, or an empty string if "skip_signing" is true for the input. Signatures must be returned as hex-encoded DER format, with the sighash byte, and must be in low-S form. Additionally, if the HW device JSON for the signer indicates low-R support, and Anti-Exfil is not being used, the signatures must also be low-R.

Anti-Exfil Request Data

Signing devices that advertize support for the Anti-Exfil signing protocol will be passed "use_ae_protocol" as true in signing requests. When this occurs, the following additional data will be present in the request:

{
  "ae_host_entropy": "b18270b26905d7d76d8abac3fb0382af07239f1aeaec8daf8294a79b58e7877f",
  "ae_host_commitment": "61aafe4ca62cc8960687849089ae1a4b7698dcfb28842533a4417c870099167b"
}

ae_host_entropy:: 32 bytes of host-provided entropy to include in the devices signature nonce, hex encoded.
ae_host_commitment:: The Anti-Exfil commitment to ae_host_entropy, hex encoded.

For transaction signing, the above elements will be present in each element in the "transaction_inputs" array of inputs to be signed.

Anti-Exfil Reply Data

When signing messages using the Anti-Exfil protocol, signing devices must return the following along with the signature:

{
  "signer_commitment": "b18270b26905d7d76d8abac3fb0382af07239f1aeaec8daf8294a79b58e7877f"
}

signer_commitment:: The 32 byte signer commitment to the nonce entropy for validation, hex encoded.

For transaction signing, a commitment for each input that was signed must be returned in an array as follows:

{
  "signer_commitments": [ "b18270b26905d7d76d8abac3fb0382af07239f1aeaec8daf8294a79b58e7877f" ]
}

Inputs that were not signed should have an empty string as their commitment array element.