Skip to main content

Zcash App

  • Zondax API: New API that provides support for shielded and unshielded transactions

General Structure

The general structure of commands and responses is as follows:

FieldTypeContentNote
CLAbyte (1)Application Identifier0xE0
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
0x6982Empty buffer
0x6983Output buffer too small
0x6986Command not allowed
0x6D00INS not supported
0x6E00CLA not supported
0x6F00Unknown
0x9000Success

New API

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 Mode0xFF means test mode is enabled
MAJORbyte (1)Version Major
MINORbyte (1)Version Minor
PATCHbyte (1)Version Patch
LOCKEDbyte (1)Device is locked
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
PKbyte (65)Public Key
ADDR_RAW_LENbyte (1)ADDR_RAW Length
ADDR_RAWbyte (??)Address as Raw Bytes
ADDR_HUMAN_LENbyte (1)ADDR_HUMAN Len
ADDR_HUMANbyte (??)Address as String
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 payload(depends)
ZIP32-pathbyte (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 payload(depends)
ZIP32-pathbyte (4)Derivation Path Datau32 Little-Endian
DIVbyte (11)Diversifier11-bytes

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_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)Request User confirmationignored (no)
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-pathbyte (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).

Command

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

Response

FieldTypeContentNote
IVK_RAWbyte (32)Raw IVK
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)Request User confirmation1
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-pathbyte (4)Derivation Path Datau32 Little-Endian

Response

FieldTypeContentNote
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)Request User confirmation1
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload(depends)
ZIP32-pathbyte (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_SAPLING

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 * 84 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 Identifier0xE0
INSbyte (1)Instruction ID0xa0
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----not used
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_GET_SPENDINFO

Returns a proof generating key (PGK) and randomness (rcv and alpha) for a sapling spend. This command requires you already called the INS_INITTX_SAPLING. This command requires that it is needed to extract spendinfo.

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x85
INSbyte (1)Instruction ID0xa1
P1byte (1)Request User confirmationNo = 0
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_GET_OUTPUTINFO

Returns randomness (rcv and rseed (after ZIP202) and optional Hash_Seed) for a sapling output. This command requires you already called the INS_INITTX_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)Request User confirmationNo = 0
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_TX_SAPLING

Checks the transaction data and signs if it is correct with the corresponding keys. This command requires you already called the INS_INITTX_SAPLING. This command requires you already called the correct number of INS_GET_SPENDINFO. This command requires you already called the correct number of INS_GET_OUTPUTINFO.

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

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 Identifier0xE0
INSbyte (1)Instruction ID0xa3
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----not used
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

INS_GET_TRANSPARENT_SIGNATURE

Returns a SECP256K1 signature for a sapling transparent input. This command requires that you already called INS_CHECKANDSIGN_SAPLING. 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 confirmationNo = 0
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0 (empty)

Response

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

INS_GET_SPEND_SIGNATURE

Returns a spend signature for a sapling shielded spend input. This command requires that you already called INS_CHECKANDSIGN_SAPLING.

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

INS_SIGN_SECP256K1

OLD COMMAND: NOT SUPPORTED

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0xE0
INSbyte (1)Instruction ID0x02
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----not used
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
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?

Other Chunks/Packets

FieldTypeContentExpected
Databytes...Message

Data is defined as:

FieldTypeContentExpected
Messagebytes..Data to sign

Response

FieldTypeContentNote
secp256k1 Rbyte (32)Signature
secp256k1 Sbyte (32)Signature
secp256k1 Vbyte (1)Signature
SIGbyte (variable)SignatureDER format
SW1-SW2byte (2)Return codesee list of return codes

INS_SIGN_SAPLING

OLD COMMAND: NOT SUPPORTED

FieldTypeContentExpected
CLAbyte (1)Application Identifier0xE0
INSbyte (1)Instruction ID0x12
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----not used
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
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?

Other Chunks/Packets

FieldTypeContentExpected
Databytes...Message

Data is defined as:

FieldTypeContentExpected
Messagebytes..Data to sign

Response

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