Skip to main content
Zondax Github LinkZondax Github Link
Theme SwitchTheme Switch

Zcash App

General structure

The general structure of commands and responses is as follows:

Commands

FieldTypeContentNote
CLAbyte (1)Application Identifier0x59
INSbyte (1)Instruction ID
P1byte (1)Parameter 1
P2byte (1)Parameter 2
Lbyte (1)Bytes in payload
PAYLOADbyte (L)Payload

Response

FieldTypeContentNote
ANSWERbyte (?)Answerdepends on the command
SW1-SW2byte (2)Return codesee list of return codes

Return codes

Return codeDescription
0x6400Execution Error
0x6700Wrong buffer length
0x6982Empty buffer
0x6983Output buffer too small
0x6984Data is invalid
0x6986Command not allowed
0x6987Tx is not initialized
0x6B00P1/P2 are invalid
0x6D00INS not supported
0x6E00CLA not supported
0x6F00Unknown
0x6F01Sign / verify error
0x9000Success

New API

GET_DEVICE_INFO

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0xE0
INSbyte (1)Instruction ID0x01
P1byte (1)Parameter 10x00
P2byte (1)Parameter 20x00
Lbyte (1)Bytes in payload0x00

Response

FieldTypeContentNote
TARGET_IDbyte (4)Target Id
OS_LENbyte (1)OS version length0..64
OSbyte (?)OS versionNon terminated string
FLAGS_LENbyte (1)Flags length0
MCU_LENbyte (1)MCU version length0..64
MCUbyte (?)MCU versionNon terminated string
SW1-SW2byte (2)Return codesee list of return codes

GET_VERSION

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0x00
P1byte (1)Parameter 1ignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0

Response

FieldTypeContentNote
TESTbyte (1)Test Mode0x01 means test mode is enabled
MAJORbyte (2)Version Major0..65535
MINORbyte (2)Version Minor0..65535
PATCHbyte (2)Version Patch0..65535
LOCKEDbyte (1)Device is lockedIt'll always be 0
TARGET_IDbyte (4)Target Id
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_ADDR_SECP256K1

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0x01
P1byte (1)Request User confirmationNo = 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
Path[0]byte (4)Derivation Path Data0x8000002c
Path[1]byte (4)Derivation Path Data0x80000085
Path[2]byte (4)Derivation Path Data?
Path[3]byte (4)Derivation Path Data?
Path[4]byte (4)Derivation Path Data?

Response

FieldTypeContentNote
Compressed PKbyte (33)Public Key
ADDRbyte (??)address
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_ADDR_SAPLING

Returns or shows a shielded address with default diversifier (z-address)

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0x11
P1byte (1)Request User confirmationNo = 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payloadalways 4
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian

Response

FieldTypeContentNote
ADDR_RAWbyte (43)Raw address
ADDR_BECH32byte (variable)Bech32 encoding of address
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_ADDR_SAPLING_DIV

Returns a shielded address using a specific diversifier

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0x10
P1byte (1)Request User confirmationNo = 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payloadalways 15
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian
DIVbyte (11)Diversifier11-bytes

Response

FieldTypeContentNote
ADDR_RAWbyte (43)Diversifier (11) + pubkeyDiv(32)
ADDR_BECH32byte (43)Bech32 encoding of raw address
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_DIV_LIST

On input of a 11-byte starting index, get all valid diversifiers in the 20 indexes after (including starting index). If a diversifier was not valid, zero-bytes are returned (so always 220 bytes are returned).

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0x09
P1byte (1)Parameter 1ignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian
DIVbyte (11)Starting index search11-bytes

Response

FieldTypeContentNote
DIV_LIST_RAWbyte (220)List of raw diversifiers11-bytes each
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_IVK_SAPLING

Returns a sapling incoming viewing key. Forced user confirmation (So P1 needs to be 0x01). Also returns the default diversifier (starting from index 0).

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xf0
P1byte (1)Ignoredignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian

Response

FieldTypeContentNote
IVK_RAWbyte (32)Raw IVK
DIVbyte (11)Default diversifier
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_OVK_SAPLING

Returns a sapling outgoing viewing key. Forced user confirmation (So P1 needs to be 0x01).

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xf1
P1byte (1)Ignoredignored
P2byte (1)Ignoredignored
Lbyte (1)Bytes in payload(depends)
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian

Response

FieldTypeContentNote
OVK_RAWbyte (32)Raw OVK
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_FVK_SAPLING

Returns a sapling full viewing key fvk = (ak, nk, ovk). Forced user confirmation (So P1 needs to be 0x01).

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xf3
P1byte (1)Request User confirmationalways 1 or error
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian

Response

FieldTypeContentNote
AK_RAWbyte (32)Raw AK
NK_RAWbyte (32)Raw NK
OVK_RAWbyte (32)Raw OVK
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_NF_SAPLING

Returns a sapling nullifier. TODO: Forced user confirmation (So P1 needs to be 0x01).

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xf2
P1byte (1)Ignoredignored
P2byte (1)Ignoredignored
Lbyte (1)Bytes in payload(depends)
ZIP32-accountbyte (4)Derivation Path Datau32 Little-Endian
POSITIONbyte (8)Note positionuint64
CMbyte(32)Note commitment Data32-bytes

Response

FieldTypeContentNote
NF_RAWbyte (32)Raw NF
SW1-SW2byte (2)Return codesee list of return codes

INS_INIT_TX

Initiates a transaction for sapling. The init_message should have the following format:

TypeContentExpected
byte (1)t_in_len: number of transparent inputs0x00 - 0x05
byte (1)t_out_len: number of transparent outputs0x00 - 0x05
byte (1)s_in_len: number of shielded spends0x00 - 0x05
byte (1)s_out_len: number of shielded outputs0x00 - 0x05
byte (variable)transparent input data = [t_in]t_in_len * 54 bytes
byte (variable)transparent output data = [t_out]t_out_len * 34 bytes
byte (variable)shielded spend data = [s_spend]s_in_len * 55 bytes
byte (variable)shielded output data = [s_out]s_out_len * 85 bytes

where

t_in :

TypeContentExpected
byte (20)Derivation path data5 times 4 bytes
byte (26)Script of transparent input
byte (8)transparent input valueu64

t_out :

TypeContentExpected
byte (26)Script of transparent output
byte (8)transparent output valueu64

s_spend:

TypeContentExpected
byte (4)ZIP32-path (hardened only)u32
byte (43)Shielded spend address
byte (8)Shielded spend valueu64

s_output:

TypeContentExpected
byte (43)Shielded output address
byte (8)Shielded output valueu64
byte (1)Shielded output memo type0xf6 for default memo
byte (32)Shielded output OVK32 zero-bytes for non-OVK

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa0
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)TxVersion4 = Sapling
5 = NU5
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

All other packets/chunks contain data chunks that are described below

First Packet

FieldTypeContentExpected

Other Chunks/Packets

FieldTypeContentExpected
Databytes...Message

Data is defined as:

FieldTypeContentExpected
Messagebytes..init_message bytes as defined above

Response

FieldTypeContentNote
hashbyte (32)Hash of init_messageSHA256-hash
SW1-SW2byte (2)Return codesee list of return codes

INS_EXTRACT_SPEND

Returns a proof generating key (PGK) and randomness (rcv and alpha) for a sapling spend.

  • This command requires you already called the INS_INIT_TX_SAPLING.
  • This command requires that it is needed to extract spendinfo.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa1
P1byte (1)Parameter 1ignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0 (empty)

Response

FieldTypeContentNote
PGK_RAWbyte (64)Raw PGK32 byte representations for ak, nsk
rcv_RAWbyte (32)Raw rcv
alpha_RAWbyte (32)Raw alpha
SW1-SW2byte (2)Return codesee list of return codes

INS_EXTRACT_OUTPUT

Returns randomness (rcv and rseed (after ZIP202) and optional Hash_Seed) for a sapling output.

  • This command requires you already called the INS_INIT_TX_SAPLING.
  • This command requires you already called the correct number of INS_GET_SPENDINFO.
  • This command requires that it is needed to extract outputinfo.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa2
P1byte (1)Parameter 1ignored
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0 (empty)

Response

FieldTypeContentNote
rcv_RAWbyte (32)Raw rcv
rseed_RAWbyte (32)Raw rseed
hash_seedbyte (32)Raw hash_seedOnly returned if OVK=None for this output
SW1-SW2byte (2)Return codesee list of return codes

INS_CHECKANDSIGN

Checks the transaction data and signs if it is correct with the corresponding keys.

  • This command requires you already called the INS_INIT_TX
  • This command requires you already called the correct number of INS_EXTRACT_SPEND.
  • This command requires you already called the correct number of INS_EXTRACT_OUTPUT.
  • Due to the complexity of this command, if an error is detected throughout the entire verification process, the response will consist only of the return code.

The transaction_blob should have the following format:

TypeContentExpected
byte (variable)transparent data to checkt_in_len * 74 bytes
byte (variable)previous spend data to checks_in_len* 40 bytes
byte (variable)new spend data to checks_in_len * 320 bytes
byte (variable)shielded output data to checks_out_len * 948 bytes
byte (220)sighash220 bytes

where

transparent data to check : (Some of the below data is already sent in the inittx command, but sending it again is easier for checking purposes)

TypeContentExpected
byte (36)Prevout point
byte (26)Script
byte (8)Valueu64
byte (4)Sequence number

previous spend data to check :

TypeContentExpected
byte (32)Rseed of the spent note
byte (8)Note position of spent noteu64

new spend data to check: NOTE: the values below should have used randomness from INS_GET_SPENDINFO if applicable

TypeContentExpected
byte (32)spend cvshould have used rcv from ledger
byte (32)Anchor
byte (32)Nullifiershould have used old note Rseed and note position
byte (32)Rkshould have used alpha from ledger
byte (192)zkproof

shielded output data to check:

TypeContentExpected
byte (32)output cvshould have used rcv from ledger
byte (32)note commitmentshould have used rseed from ledger
byte (32)ephemeral keyshould have used rseed from ledger
byte (580)enc_ciphertextledger checks correct memo-type too
byte (80)out_ciphertext
byte (192)zkproof

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa3
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)TxVersion4 = Sapling
5 = NU5
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

All other packets/chunks contain data chunks that are described below

First Packet

FieldTypeContentExpected

Other Chunks/Packets

FieldTypeContentExpected
Databytes...Message

Data is defined as:

FieldTypeContentExpected
Messagebytes..transaction_blob bytes as defined above

Response

FieldTypeContentNote
hashbyte (32)Hash of transaction_blobSHA256
SW1-SW2byte (2)Return codesee list of return codes

Error Response

FieldTypeContentNote
SW1-SW2byte (2)Return codesee list of return codes

INS_GET_EXTRACT_TRANSSSIG

Returns a SECP256K1 signature for a sapling transparent input if available. Othrewise, it returns only an error code.

  • This command requires that you already called INS_CHECKANDSIGN.

It gives the signatures in order of the transaction. Returns error if all signatures are retrieved.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa5
P1byte (1)Request User confirmationalways 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload!= 0

Response

FieldTypeContentNote
SECP256K1byte (64)R/S signature
SW1-SW2byte (2)Return codesee list of return codes

Error Response

FieldTypeContentNote
SW1-SW2byte (2)Return codesee list of return codes

INS_EXTRACT_SPENDSIG

Returns a spend signature for a sapling shielded spend input if available. Othrewise, it returns only an error code.

  • This command requires that you already called INS_CHECKANDSIGN.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa4
P1byte (1)Request User confirmationNo = 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0 (empty)

Response

FieldTypeContentNote
RedJubjub signaturebyte (64)R/S signature
SW1-SW2byte (2)Return codesee list of return codes

Error Response

FieldTypeContentNote
SW1-SW2byte (2)Return codesee list of return codes