Hardware Call

Hardware Call is the process that a software wallet send requests to Keystone hardware wallet, Keystone then execute the given command and present the result in QR code. You can think it as the API of Keystone hardware wallet.

The Hardware Call supports at the moment

Key Derivation Call (Experimental)

Most wallet do not need this step when getting account information from Keystone.

Keystone hardware wallet needs to provide the account information to the software wallet to generate addresses, sync balances and etc. There are situations that software needs multiple public keys to support different address types or different chains. Key Derivation Call receives paths of public keys and generates corresponding QR codes.

For passing an key derivation call to the Keystone hardware wallet, KeystoneSDK needs the data underneath, then covert it into a QR codes.

schemas: Array(
    path: String // The path of public key that the software wallet want to get from hardware wallet
    curve: Optional(Enum) // The crypto curve for generating the public key, `secp256k1` by default, currently supports `secp256k1` and `ed25519`
    algo: Optional(Enum) // The derivation algorithm, `slip10` by default, currently supports `slip10` and `bip32ed25519`
    chainType:Optional(String) // The chainType specifies the public key of the corresponding chain that the user expects to receive. Currently, ChainType supports extracting more than 40 types of chains. The user must ensure that the value of ChainType appears in the list below, otherwise the cold end will not be able to provide it.
)
origin: Optional(String) // source of the request, wallet name etc
version: Optional(Enum) // The hardware call protocol version , `V0` by default. Currently, we recommend using the V1 version.

Acceptable Combination

curve	derivation algorithm
secp256k1	slip10	✔️
secp256k1	bip32ed25519	Not Supported
ed25519	slip10	✔️
ed25519	bip32ed25519	✔️

After generating the Key Derivation Call QR code with KeystoneSDK, scans the QR code with Keystone hardware wallet to execute it.

Hardware Call Version 0

This is an example of requesting an ada address. In this example, you need to pay attention that In hardwarecall version 0, you can only request addresses from "m/1852'/1815'/0'" to "m/1852'/1815'/23'". Any index exceeding 23 will only return the address for "m/1852'/1815'/0'".Additionally, in version 0, it can only be used to generate ADA addresses. It cannot be used to generate non-ADA addresses such as BTC、ETH、SOLANA and etc.

import { DerivationAlgorithm } from '@keystonehq/keystone-sdk'
import { AnimatedQRCode } from '@keystonehq/animated-qr'
import KeystoneSDK, { Curve } from '@keystonehq/keystone-sdk'
export const Cosmos = () => {
	let schemas = [
		{
			path: "m/1852'/1815'/0'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.bip32ed25519,
			chainType: 'ADA',
		},
        {
			path: "m/1852'/1815'/0'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.bip32ed25519,
			chainType: 'ADA',
		},
	]
	const ur = KeystoneSDK.generateKeyDerivationCall({
		schemas,
		origin: 'XXX Wallet',
	})
	return <AnimatedQRCode type={ur.type} cbor={ur.cbor.toString('hex')} />
}

Hardware Call Version 1

We recommend using HardwareCall Version 1. This version is more powerful as it can handle addresses for over 40 different blockchains.

In the example below, we use the hardware call version 1 to obtain addresses for chains such as ADA, SOL, ETH, BTC, BCH and so on . It's important to note that when retrieving the ADA path, the default return is the ADA standard address.

If you need a ADA ledger/bitbox2 address, please manually switch to it on the keystone cold wallet approve page.

For more supported ChainTypes, please refer to the acceptable chaintype section below.

import { DerivationAlgorithm } from '@keystonehq/keystone-sdk'
import { AnimatedQRCode } from '@keystonehq/animated-qr'
import KeystoneSDK, { Curve } from '@keystonehq/keystone-sdk'
import { QRHardwareCallVersion } from '@keystonehq/keystone-sdk'
export const HardwareCallV1 = () => {
	let schemas = [
		{
			path: "m/1852'/1815'/0'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.bip32ed25519,
			chainType: 'ADA',
		},
		{
			path: "m/1852'/1815'/1'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.bip32ed25519,
			chainType: 'ADA',
		},
		{
			path: "m/44'/501'/0'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.slip10,
			chainType: 'SOL',
		},
		{
			path: "m/44'/501'/1'",
			curve: Curve.ed25519,
			algo: DerivationAlgorithm.slip10,
			chainType: 'SOL',
		},
		{
			path: "m/44'/60'/0'",
			curve: Curve.secp256k1,
			chainType: 'ETH',
		},
        {
            path: "m/44'/60'/0'/0/0",
            curve: Curve.secp256k1,
            chainType: 'ETH',
        },
        {
            path: "m/49'/2'/0'",
			curve: Curve.secp256k1,
			chainType: 'LTC',
        },
        {
            path: "m/44'/5'/0'",
			curve: Curve.secp256k1,
			chainType: 'DASH',
        },
        {
            path: "m/44'/145'/0'",
			curve: Curve.secp256k1,
			chainType: 'BCH',
        },
        {
            path: "m/44'/195'/0'",
			curve: Curve.secp256k1,
			chainType: 'TRX',
        },
        {
            path: "m/44'/0'/0'",
			curve: Curve.secp256k1,
			chainType: 'BTC_LEGACY',
        }
	]
	const ur = KeystoneSDK.generateKeyDerivationCall({
		schemas,
		origin: 'XXX Wallet',
		version: QRHardwareCallVersion.V1,
	})
	return <AnimatedQRCode type={ur.type} cbor={ur.cbor.toString('hex')} />
}

Acceptable ChainType

"BTC"
"BTC_LEGACY"
"BTC_NATIVE_SEGWIT"
"BTC_TAPROOT"
"ETH"
"SOL"
"XRP"
"ADA"
"TRX"
"LTC"
"BCH"
"APT"
"SUI"
"DASH"
"AR"
"XLM"
"TIA"
"ATOM"
"DYM"
"OSMO"
"INJ"
"CRO"
"KAVA"
"LUNC"
"AXL"
"LUNA"
"AKT"
"STRD"
"SCRT"
"BLD"
"CTK"
"EVMOS"
"STARS"
"XPRT"
"SOMM"
"JUNO"
"IRIS"
"DVPN"
"ROWAN"
"REGEN"
"BOOT"
"GRAV"
"IXO"
"NGM"
"IOV"
"UMEE"
"QCK"
"TGD"