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

Internet Computer App

General structure

The general structure of commands and responses is as follows:

Commands

FieldTypeContentNote
CLAbyte (1)Application Identifier0x11
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
0x6985Conditions not satisfied
0x6986Command not allowed
0x6987Tx is not initialized
0x6A80Bad key handle
0x6B00P1/P2 are invalid
0x6D00INS not supported
0x6E00CLA not supported
0x6F00Unknown
0x6F01Sign / verify error
0x9000Success
0x9001Busy

Command definition

GET_VERSION

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
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

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
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 Data0x80000000
Path[1]byte (4)Derivation Path Data0x80000000
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_B_LENbyte (1)ADDR_B Length
ADDR_Bbyte (??)Address as Bytes
ADDR_S_LENbyte (1)ADDR_S Len
ADDR_Sbyte (??)Address as String
SW1-SW2byte (2)Return codesee list of return codes

INS_SIGN

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x02
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----is_stake_tx
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

If the transaction blob is from a Neuron-stake transaction, it expects P2 == 1. Otherwise P2 needs to be 0.

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

First Packet

FieldTypeContentExpected
Path[0]byte (4)Derivation Path Data44
Path[1]byte (4)Derivation Path Data461
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..CBOR 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_COMBINED

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x03
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----is_stake_tx
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

If the transaction blob is from a Neuron-stake transaction, it expects P2 == 1. Otherwise P2 needs to be 0.

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

First Packet

FieldTypeContentExpected
Path[0]byte (4)Derivation Path Data44
Path[1]byte (4)Derivation Path Data461
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...Combined Message

Data is defined as:

FieldTypeContentExpected
State Read Lengthbyte (4)Length of state read data
State Read Databytes..State read CBOR data
Request Lengthbyte (4)Length of request data
Request Databytes..Request CBOR data

Response

FieldTypeContentNote
Request Hashbyte (32)Hash of request data
Request Signaturebyte (64)Signature request hash
State Read Hashbyte (32)Hash of state read data
State Read Signaturebyte (64)Signature state read
SW1-SW2byte (2)Return codesee list of return codes

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x04
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----ignored
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

First Packet

FieldTypeContentExpected
Path[0]byte (4)Derivation Path Data44
Path[1]byte (4)Derivation Path Data461
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...Consent Request

Response

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

INS_CANISTER_CALL_TX

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x05
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----ignored
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

First Packet

FieldTypeContentExpected
Path[0]byte (4)Derivation Path Data44
Path[1]byte (4)Derivation Path Data461
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...Canister Call

Response

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

INS_CERTIFICATE_AND_SIGN

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x06
P1byte (1)Payload desc0 = init
1 = add
2 = last
P2byte (1)----ignored
Lbyte (1)Bytes in payload(depends)

The first packet/chunk includes only the derivation path

First Packet

FieldTypeContentExpected
Path[0]byte (4)Derivation Path Data44
Path[1]byte (4)Derivation Path Data461
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...Certificate Data

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_SUPPORTED_TOKENS_LEN

Command

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

Response

FieldTypeContentNote
LENbyte (1)Number of tokensNumber of supported tokens in registry
SW1-SW2byte (2)Return codesee list of return codes

INS_TOKEN_AT_IDX

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x11
INSbyte (1)Instruction ID0x08
P1byte (1)Token Index0-255
P2byte (1)Parameter 2ignored
Lbyte (1)Bytes in payload0

Response

FieldTypeContentNote
TOKEN_INFObyte (?)Token InformationSee TokenInfo structure
SW1-SW2byte (2)Return codesee list of return codes

TokenInfo Structure

The token information is returned as an array of the following structure:

FieldTypeContent
TOKEN_SYMBOLbyte (?)Token symbol string
TOKEN_NAMEbyte (?)Token name string
DECIMALSbyte (1)Number of decimals

The array length is determined by the number of supported tokens, which can be obtained using the INS_SUPPORTED_TOKENS_LEN command.