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

Oasis App

General structure

The Application Identifier depends on the app type:

TypeAPP_CLA
Validator0xf5
Consumer0x05

The general structure of commands and responses is as follows:

Commands

FieldTypeContentNote
CLAbyte (1)Application IdentifierAPP_CLA
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
0x6985Conditions not satisfied
0x6986Command not allowed
0x6D00INS not supported
0x6E00CLA not supported
0x6F00Unknown
0x9000Success

Command definition

GET_VERSION

Command

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

GET_ADDR_ED25519

Command

FieldTypeContentExpected
CLAbyte (1)Application IdentifierAPP_CLA
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 Data44
Path[1]byte (4)Derivation Path Data474
Path[2]byte (4)Derivation Path Data?
Path[3]byte (4)Derivation Path Data?
Path[4]byte (4)Derivation Path Data?

First three items in the derivation path will be hardened automatically hardened

Response

FieldTypeContentNote
PKbyte (32)Public Key
ADDRbyte (??)Bech 32 addr
SW1-SW2byte (2)Return codesee list of return codes

SIGN_ED25519

Command

FieldTypeContentExpected
CLAbyte (1)Application IdentifierAPP_CLA
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 should contain message to sign

The chunk size is 250 bytes.

First Packet

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

Data is defined as:

FieldTypeContentExpected
CtxLenbyteContext Length
Contextbytes..ContextCtxLen bytes
Messagebytes..CBOR data to sign

Response

The response depends on app type:

Consumer Response

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

Validator Response

The Validator response has a validation flow that can result in diferente responses:

If Oasis Blob is a Consensus Type:

  1. Vote State is checked and if it is not initialized, a new valid vote is set:
FieldTypeContentNote
SW1-SW2byte (2)Return codesee list of return codes
  1. Vote is initialized and the current vote state is returned alongside the conflicting vote data [vote][vote_state][error]
FieldTypeContentNote
Bufferbyte (1)Vote type
byte (8)Vote height
byte (8)Vote round
byte (1)Vote state type
byte (8)Vote state height
byte (8)Vote state round
SW1-SW2byte (2)Return codesee list of return codes

If Oasis Blob is not a Consensus Type:

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

SIGN_RT_ED25519

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x05
INSbyte (1)Instruction ID0x05
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 should contain message to sign

The chunk size is 250 bytes.

First Packet

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

Data is defined as:

FieldTypeContentExpected
Metabyte..CBOR metadata
Messagebytes..CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

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

GET_ADDR_SECP256K1

Command

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

First three items in the derivation path are hardened

Response

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

SIGN_RT_SECP256K1

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x05
INSbyte (1)Instruction ID0x07
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 should contain message to sign

First Packet

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

Data is defined as:

FieldTypeContentExpected
Metabyte..CBOR metadata
Messagebytes..CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

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

GET_ADDR_SR25519

Command

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

First three items in the derivation path are hardened

Response

FieldTypeContentNote
PKbyte (32)Public Key
ADDRbyte (??)Bech 32 addr
SW1-SW2byte (2)Return codesee list of return codes

SIGN_RT_SR25519

Command

FieldTypeContentExpected
CLAbyte (1)Application Identifier0x05
INSbyte (1)Instruction ID0x06
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 should contain message to sign

First Packet

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

Data is defined as:

FieldTypeContentExpected
Metabyte..CBOR metadata
Messagebytes..CBOR data to sign

Meta contains the following fields:

  • runtime_id: 32-byte runtime ID
  • chain_context: 32-byte chain ID
  • orig_to (optional): 20-byte ethereum destination address

Response

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