diff --git a/docs/APDUSPEC.md b/docs/APDUSPEC.md index aef5f60..272c146 100644 --- a/docs/APDUSPEC.md +++ b/docs/APDUSPEC.md @@ -39,6 +39,7 @@ The general structure of commands and responses is as follows: | 0x6F00 | Unknown | | 0x6F01 | Sign / verify error | | 0x9000 | Success | +| 0xE001 | Legacy parser error | --- @@ -46,7 +47,7 @@ The general structure of commands and responses is as follows: Some commands contain two different possible INS values. Such implementation is to allow for backwards compatibility with the original Kadena App. -Everything that regards to such original app is referred to as "Legacy" below. +See [Legacy Command definition](#legacy-command-definition) for more details. ### GET_VERSION @@ -55,7 +56,7 @@ Everything that regards to such original app is referred to as "Legacy" below. | Field | Type | Content | Expected | | ----- | -------- | ---------------------- | -------------------------- | | CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x20 (New) / 0x00 (Legacy) | +| INS | byte (1) | Instruction ID | 0x20 | | P1 | byte (1) | Parameter 1 | ignored | | P2 | byte (1) | Parameter 2 | ignored | | L | byte (1) | Bytes in payload | 0 | @@ -81,7 +82,7 @@ Everything that regards to such original app is referred to as "Legacy" below. | Field | Type | Content | Expected | | ------- | -------- | ------------------------- | -------------------------- | | CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x21 (New) | +| INS | byte (1) | Instruction ID | 0x21 | | P1 | byte (1) | Request User confirmation | No = 0 / Yes = 1 | | P2 | byte (1) | Parameter 2 | ignored | | L | byte (1) | Bytes in payload | 25 | @@ -100,84 +101,64 @@ Everything that regards to such original app is referred to as "Legacy" below. --- -### INS_GET_ADDR (Legacy only) +### INS_SIGN_JSON #### Command -| Field | Type | Content | Expected | -| ------- | -------- | ------------------------- | -------------------------- | -| CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x02 (Legacy) | -| P1 | byte (1) | Parameter 1 | ignored | -| P2 | byte (1) | Parameter 2 | ignored | -| L | byte (1) | Bytes in payload | 25 | -| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | -| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | -| Path[2] | byte (4) | Derivation Path Data | ? | -| Path[3] | byte (4) | Derivation Path Data | ? | -| Path[4] | byte (4) | Derivation Path Data | ? | - -#### Response - -| Field | Type | Content | Note | -| ------- | --------- | ----------- | ------------------------ | -| PK | byte (32) | Public Key | | -| SW1-SW2 | byte (2) | Return code | see list of return codes | - ---- +| Field | Type | Content | Expected | +| ----- | -------- | ---------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x22 | +| P1 | byte (1) | ---- | not used | +| P2 | byte (1) | ---- | not used | +| L | byte (1) | Bytes in payload | (depends) | -### INS_VERIFY_ADDR (Legacy only) +For the new app, the first packet/chunk includes only the derivation path. -Same as [GET_ADDR](#ins_get_addr) but requires user confirmation. +All other packets/chunks contain data chunks that are described below. -#### Command +##### First Packet (New) -| Field | Type | Content | Expected | -| ------- | -------- | ------------------------- | -------------------------- | -| CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x01 (Legacy) | -| P1 | byte (1) | Parameter 1 | ignored | -| P2 | byte (1) | Parameter 2 | ignored | -| L | byte (1) | Bytes in payload | 25 | -| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | -| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | -| Path[2] | byte (4) | Derivation Path Data | ? | -| Path[3] | byte (4) | Derivation Path Data | ? | -| Path[4] | byte (4) | Derivation Path Data | ? | +| Field | Type | Content | Expected | +| ------- | -------- | -------------------- | ----------------- | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| Path[3] | byte (4) | Derivation Path Data | ? | +| Path[4] | byte (4) | Derivation Path Data | ? | -#### Response +##### Other Chunks/Packets -| Field | Type | Content | Note | -| ------- | --------- | ----------- | ------------------------ | -| PK | byte (32) | Public Key | | -| SW1-SW2 | byte (2) | Return code | see list of return codes | +| Field | Type | Content | Expected | +| ------- | -------- | --------------- | ------------------------- | +| Message | byte (?) | Message to Sign | hexadecimal string (utf8) | #### Response | Field | Type | Content | Note | | ------- | --------- | ----------- | ------------------------ | -| PK | byte (32) | Public Key | | +| SIG | byte (64) | Signature | | | SW1-SW2 | byte (2) | Return code | see list of return codes | --- -### INS_SIGN_JSON +### INS_SIGN_HASH #### Command | Field | Type | Content | Expected | | ----- | -------- | ---------------------- | -------------------------- | | CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x22 (New) / 0x03 (Legacy) | +| INS | byte (1) | Instruction ID | 0x23 | | P1 | byte (1) | ---- | not used | | P2 | byte (1) | ---- | not used | | L | byte (1) | Bytes in payload | (depends) | -For the new app, the first packet/chunk includes only the derivation path. +For the new app, the first packet/chunk includes only the derivation path -All other packets/chunks contain data chunks that are described below. +All other packets/chunks contain data chunks that are described below -##### First Packet (New) +##### First Packet | Field | Type | Content | Expected | | ------- | -------- | -------------------- | ----------------- | @@ -187,39 +168,29 @@ All other packets/chunks contain data chunks that are described below. | Path[3] | byte (4) | Derivation Path Data | ? | | Path[4] | byte (4) | Derivation Path Data | ? | -##### Other Chunks/Packets (New) - -| Field | Type | Content | Expected | -| ------- | -------- | --------------- | -------- | -| Message | JSON | Message to Sign | | - -For the legacy behavior, this is inverted. The first chunks/packets contain the message to sign, and the last chunk/packet contains the derivation path : - -##### First Chunks/Packets (Legacy) - -Same as [Other Chunks/Packets (New)](#other-chunkspackets-new) +##### Other Chunks/Packets -##### Last Packet (Legacy) - -Same as [First Packet (New)](#first-packet-new) +| Field | Type | Content | Expected | +| ------- | --------- | --------------- | -------- | +| Hash | byte (32) | Tx Hash to Sign | | #### Response | Field | Type | Content | Note | | ------- | --------- | ----------- | ------------------------ | -| SIG | byte (65) | Signature | | +| SIG | byte (64) | Signature | | | SW1-SW2 | byte (2) | Return code | see list of return codes | --- -### INS_SIGN_HASH +### INS_SING_TRANSFER #### Command | Field | Type | Content | Expected | | ----- | -------- | ---------------------- | -------------------------- | | CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x23 (New) / 0x04 (Legacy) | +| INS | byte (1) | Instruction ID | 0x24 | | P1 | byte (1) | ---- | not used | | P2 | byte (1) | ---- | not used | | L | byte (1) | Bytes in payload | (depends) | @@ -228,7 +199,8 @@ For the new app, the first packet/chunk includes only the derivation path All other packets/chunks contain data chunks that are described below -##### First Packet (New) + +##### First Packet | Field | Type | Content | Expected | | ------- | -------- | -------------------- | ----------------- | @@ -238,101 +210,263 @@ All other packets/chunks contain data chunks that are described below | Path[3] | byte (4) | Derivation Path Data | ? | | Path[4] | byte (4) | Derivation Path Data | ? | -##### Other Chunks/Packets (New) +##### Other Chunks/Packets + +| Field | Type | Content | Expected | +|---------------------|---------------------------- |---------------------------- |-------------------- | +| tx_type | byte (1) | Transaction Type | see list of Tx type | +| recipient_len | byte (1) | Recipient Length | | +| recipient | byte (recipient_len) | Recipient Pubkey | should be 64 bytes | +| recipient_chain_len | byte (1) | Recipient Chain Length | | +| recipient_chain | byte (recipient_chain_len) | Recipient Chain | (0..2) | +| network_len | byte (1) | Network Length | | +| network | byte (network_len) | Network | (0..20) | +| amount_len | byte (1) | Amount Length | | +| amount | byte (amount_len) | Amount | (0..32) | +| namespace_len | byte (1) | Namespace Length | | +| namespace | byte (namespace_len) | Namespace | (0..16) | +| module_len | byte (1) | Module Length | | +| module | byte (module_len) | Module | (0..32) | +| gas_price_len | byte (1) | Gas Price Length | | +| gas_price | byte (gas_price_len) | Gas Price | (0..20) | +| gas_limit_len | byte (1) | Gas Limit Length | | +| gas_limit | byte (gas_limit_len) | Gas Limit | (0..10) | +| creation_time_len | byte (1) | Creation Time Length | | +| creation_time | byte (creation_time_len) | Creation Time | (0..12) | +| chain_id_len | byte (1) | Chain Id Length | | +| chain_id | byte (chain_id_len) | Chain Id | (0..2) | +| nonce_len | byte (1) | Nonce Length | | +| nonce | byte (nonce_len) | Nonce | (0..32) | +| ttl_len | byte (1) | TTL Length | | +| ttl | byte (ttl_len) | TTL | (0..20) | + +#### Tx type + +| Tx type | Description | +| ----------- | --------------------- | +| 0 | Transfer | +| 1 | Transfer Create | +| 2 | Cross-Chain Transfer | -| Field | Type | Content | Expected | -| ------- | -------- | --------------- | -------- | -| Message | Tx Hash | Tx Hash to Sign | | +#### Response -For the legacy behavior, this is inverted. The first chunks/packets contain the message to sign, and the last chunk/packet contains the derivation path : +| Field | Type | Content | Note | +| ------- | --------- | ----------- | ------------------------ | +| SIG | byte (64) | Signature | | +| SW1-SW2 | byte (2) | Return code | see list of return codes | -##### First Chunks/Packets (Legacy) -Same as [Other Chunks/Packets (New)](#other-chunkspackets-new-1) +## Legacy Command definition -##### Last Packet (Legacy) +### BCOMP_GET_VERSION -Same as [First Packet (New)](#first-packet-new-1) +#### Command + +| Field | Type | Content | Expected | +| ----- | -------- | ---------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x00 | +| P1 | byte (1) | Parameter 1 | ignored | +| P2 | byte (1) | Parameter 2 | ignored | +| L | byte (1) | Bytes in payload | 0 | + +#### Response + +| Field | Type | Content | Note | +| ---------- | -------- | ---------------- | ------------------------------- | +| MAJOR | byte (2) | Version Major | 0..65535 | +| MINOR | byte (2) | Version Minor | 0..65535 | +| PATCH | byte (2) | Version Patch | 0..65535 | +| SW1-SW2 | byte (2) | Return code | see list of return codes | + +--- + +### BCOMP_VERIFY_ADDRESS + +Same as [BCOMP_GET_PUBKEY](#bcomp_get_pubkey) but requires user confirmation. + +#### Command + +| Field | Type | Content | Expected | +| --------- | -------- | ------------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x01 | +| P1 | byte (1) | Parameter 1 | ignored | +| P2 | byte (1) | Parameter 2 | ignored | +| N | byte (1) | Number of derivation steps | (depends) | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| ....... | ....... | ..................... | ? | +| Path[N-1] | byte (4) | Derivation Path Data | ? | #### Response | Field | Type | Content | Note | | ------- | --------- | ----------- | ------------------------ | -| SIG | byte (65) | Signature | | +| PK | byte (32) | Public Key | | | SW1-SW2 | byte (2) | Return code | see list of return codes | --- -### INS_MAKE_TRANSACTION +### BCOMP_GET_PUBKEY + +#### Command + +| Field | Type | Content | Expected | +| --------- | -------- | ------------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x02 | +| P1 | byte (1) | Parameter 1 | ignored | +| P2 | byte (1) | Parameter 2 | ignored | +| N | byte (1) | Number of derivation steps | (depends) | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| ....... | ....... | ..................... | ? | +| Path[N-1] | byte (4) | Derivation Path Data | ? | + +#### Response + +| Field | Type | Content | Note | +| ------- | --------- | ----------- | ------------------------ | +| PK | byte (32) | Public Key | | +| SW1-SW2 | byte (2) | Return code | see list of return codes | + +--- + +### BCOMP_SIGN_JSON_TX + +Sign a Transaction in JSON format encoded in hexadecimal string (utf8), using the key for the given derivation path #### Command | Field | Type | Content | Expected | | ----- | -------- | ---------------------- | -------------------------- | | CLA | byte (1) | Application Identifier | 0x00 | -| INS | byte (1) | Instruction ID | 0x24 (New) / 0x10 (Legacy) | +| INS | byte (1) | Instruction ID | 0x03 | | P1 | byte (1) | ---- | not used | | P2 | byte (1) | ---- | not used | | L | byte (1) | Bytes in payload | (depends) | -For the new app, the first packet/chunk includes only the derivation path +##### Input data -All other packets/chunks contain data chunks that are described below +| Field | Type | Content | Expected | +| --------- | ------------- | --------------------------------- | ----------------- | +| tx_size | byte (4) | Size of transaction | u32 | +| tx | byte(tx_size) | Transaction in hexadecimal string | ? | +| N | byte (1) | Number of derivation steps | (depends) | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| ....... | .......... | ........................ | ? | +| Path[N-1] | byte (4) | Derivation Path Data | ? | +#### Response -##### First Packet (New) +| Field | Type | Content | Note | +| ------- | --------- | ----------- | ------------------------ | +| SIG | byte (64) | Signature | | +| SW1-SW2 | byte (2) | Return code | see list of return codes | -| Field | Type | Content | Expected | -| ------- | -------- | -------------------- | ----------------- | -| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | -| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | -| Path[2] | byte (4) | Derivation Path Data | ? | -| Path[3] | byte (4) | Derivation Path Data | ? | -| Path[4] | byte (4) | Derivation Path Data | ? | +--- + +### BCOMP_SIGN_TX_HASH + +Sign a transaction hash using the key for the specified derivation path. Expert Mode must be enabled on the Ledger app. + +#### Command + +| Field | Type | Content | Expected | +| ----- | -------- | ---------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x04 | +| P1 | byte (1) | ---- | not used | +| P2 | byte (1) | ---- | not used | -##### Other Chunks/Packets (New) - -| Field | Type | Content | Expected | -|---------------------|----------|-----------------------------------|-----------------| -| tx_type | byte (1) | Transaction Type | | -| recipient_len | byte (1) | Recipient Length | | -| recipient | byte (64)| Recipient Pubkey | | -| recipient_chain_len | byte (1) | Recipient Chain Length (0..2) | | -| recipient_chain | byte (2) | Recipient Chain | | -| network_len | byte (1) | Network Length (0..20) | | -| network | byte (20)| Network | | -| amount_len | byte (1) | Amount Length (0..32) | | -| amount | byte (32)| Amount | | -| namespace_len | byte (1) | Namespace Length (0..16) | | -| namespace | byte (16)| Namespace | | -| module_len | byte (1) | Module Length (0..32) | | -| module | byte (32)| Module | | -| gas_price_len | byte (1) | Gas Price Length (0..20) | | -| gas_price | byte (20)| Gas Price | | -| gas_limit_len | byte (1) | Gas Limit Length (0..10) | | -| gas_limit | byte (10)| Gas Limit | | -| creation_time_len | byte (1) | Creation Time Length (0..12) | | -| creation_time | byte (12)| Creation Time | | -| chain_id_len | byte (1) | Chain Id Length (0..2) | | -| chain_id | byte (2) | Chain Id | | -| nonce_len | byte (1) | Nonce Length (0..32) | | -| nonce | byte (32)| Nonce | | -| ttl_len | byte (1) | TTL Length (0..20) | | -| ttl | byte (20)| TTL | | - -For the legacy behavior, this is inverted. The first chunks/packets contain the message to sign, and the last chunk/packet contains the derivation path : - -##### First Chunks/Packets (Legacy) - -Same as [Other Chunks/Packets (New)](#other-chunkspackets-new-2) - -##### Last Packet (Legacy) - -Same as [First Packet (New)](#first-packet-new-2) +##### Input data + +| Field | Type | Content | Expected | +| --------- | ------------- | --------------------------------- | ----------------- | +| tx_hash | byte (32) | Transaction hash | ? | +| N | byte (1) | Number of derivation steps | (depends) | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| ....... | .......... | ........................ | ? | +| Path[N-1] | byte (4) | Derivation Path Data | ? | #### Response | Field | Type | Content | Note | | ------- | --------- | ----------- | ------------------------ | -| SIG | byte (65) | Signature | | -| SW1-SW2 | byte (2) | Return code | see list of return codes | \ No newline at end of file +| SIG | byte (64) | Signature | | +| SW1-SW2 | byte (2) | Return code | see list of return codes | + +--- + +### BCOMP_MAKE_TRANSFER_TX + +Builds a transfer transaction using the input data, and provides a signature for it. + +#### Command + +| Field | Type | Content | Expected | +| ----- | -------- | ---------------------- | -------------------------- | +| CLA | byte (1) | Application Identifier | 0x00 | +| INS | byte (1) | Instruction ID | 0x10 | +| P1 | byte (1) | ---- | not used | +| P2 | byte (1) | ---- | not used | + +##### Input data + +| Field | Type | Content | Expected | +| ------------------- | --------------------------- | --------------------------- | ------------------- | +| N | byte (1) | Number of derivation steps | (depends) | +| Path[0] | byte (4) | Derivation Path Data | 0x80000000 \| 44 | +| Path[1] | byte (4) | Derivation Path Data | 0x80000000 \| 626 | +| Path[2] | byte (4) | Derivation Path Data | ? | +| ................. | ........................... | ........................ | ? | +| Path[N-1] | byte (4) | Derivation Path Data | ? | +| tx_type | byte (1) | Transaction Type | see list of Tx type | +| recipient_len | byte (1) | Recipient Length | | +| recipient | byte (recipient_len) | Recipient Pubkey | should be 64 bytes | +| recipient_chain_len | byte (1) | Recipient Chain Length | | +| recipient_chain | byte (recipient_chain_len) | Recipient Chain | (0..2) | +| network_len | byte (1) | Network Length | | +| network | byte (network_len) | Network | (0..20) | +| amount_len | byte (1) | Amount Length | | +| amount | byte (amount_len) | Amount | (0..32) | +| namespace_len | byte (1) | Namespace Length | | +| namespace | byte (namespace_len) | Namespace | (0..16) | +| module_len | byte (1) | Module Length | | +| module | byte (module_len) | Module | (0..32) | +| gas_price_len | byte (1) | Gas Price Length | | +| gas_price | byte (gas_price_len) | Gas Price | (0..20) | +| gas_limit_len | byte (1) | Gas Limit Length | | +| gas_limit | byte (gas_limit_len) | Gas Limit | (0..10) | +| creation_time_len | byte (1) | Creation Time Length | | +| creation_time | byte (creation_time_len) | Creation Time | (0..12) | +| chain_id_len | byte (1) | Chain Id Length | | +| chain_id | byte (chain_id_len) | Chain Id | (0..2) | +| nonce_len | byte (1) | Nonce Length | | +| nonce | byte (nonce_len) | Nonce | (0..32) | +| ttl_len | byte (1) | TTL Length | | +| ttl | byte (ttl_len) | TTL | (0..20) | + +#### Tx type + +| Tx type | Description | +| ----------- | --------------------- | +| 0 | Transfer | +| 1 | Transfer Create | +| 2 | Cross-Chain Transfer | + +#### Response + +| Field | Type | Content | Note | +| ------- | --------- | --------------------------- | ------------------------ | +| SIG | byte (64) | Signature | | +| PK | byte (32) | Public key used for signing | | +| SW1-SW2 | byte (2) | Return code | see list of return codes | +