Oasis App
General structure
The Application Identifier depends on the app type:
Type | APP_CLA |
---|---|
Validator | 0xf5 |
Consumer | 0x05 |
The general structure of commands and responses is as follows:
Commands
Field | Type | Content | Note |
---|---|---|---|
CLA | byte (1) | Application Identifier | APP_CLA |
INS | byte (1) | Instruction ID | |
P1 | byte (1) | Parameter 1 | |
P2 | byte (1) | Parameter 2 | |
L | byte (1) | Bytes in payload | |
PAYLOAD | byte (L) | Payload |
Response
Field | Type | Content | Note |
---|---|---|---|
ANSWER | byte (?) | Answer | depends on the command |
SW1-SW2 | byte (2) | Return code | see list of return codes |
Return codes
Return code | Description |
---|---|
0x6400 | Execution Error |
0x6982 | Empty buffer |
0x6983 | Output buffer too small |
0x6985 | Conditions not satisfied |
0x6986 | Command not allowed |
0x6D00 | INS not supported |
0x6E00 | CLA not supported |
0x6F00 | Unknown |
0x9000 | Success |
Command definition
GET_VERSION
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | APP_CLA |
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 |
---|---|---|---|
TEST | byte (1) | Test Mode | 0xFF means test mode is enabled |
MAJOR | byte (1) | Version Major | |
MINOR | byte (1) | Version Minor | |
PATCH | byte (1) | Version Patch | |
LOCKED | byte (1) | Device is locked | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
GET_ADDR_ED25519
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | APP_CLA |
INS | byte (1) | Instruction ID | 0x01 |
P1 | byte (1) | Request User confirmation | No = 0 |
P2 | byte (1) | Parameter 2 | ignored |
L | byte (1) | Bytes in payload | (depends) |
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 474 |
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
Field | Type | Content | Note |
---|---|---|---|
PK | byte (32) | Public Key | |
ADDR | byte (??) | Bech 32 addr | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
SIGN_ED25519
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | APP_CLA |
INS | byte (1) | Instruction ID | 0x02 |
P1 | byte (1) | Payload desc | 0 = init |
1 = add | |||
2 = last | |||
P2 | byte (1) | ---- | not used |
L | byte (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
Field | Type | Content | Expected |
---|---|---|---|
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 474 |
Path[2] | byte (4) | Derivation Path Data | ? |
Path[3] | byte (4) | Derivation Path Data | ? |
Path[4] | byte (4) | Derivation Path Data | ? |
Other Chunks/Packets
Field | Type | Content | Expected |
---|---|---|---|
Data | bytes... | Context+Message |
Data is defined as:
Field | Type | Content | Expected |
---|---|---|---|
CtxLen | byte | Context Length | |
Context | bytes.. | Context | CtxLen bytes |
Message | bytes.. | CBOR data to sign |
Response
The response depends on app type:
Consumer Response
Field | Type | Content | Note |
---|---|---|---|
SIG | byte (64) | Signature | |
SW1-SW2 | byte (2) | Return code | see 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:
- Vote State is checked and if it is not initialized, a new valid vote is set:
Field | Type | Content | Note |
---|---|---|---|
SW1-SW2 | byte (2) | Return code | see list of return codes |
- Vote is initialized and the current vote state is returned alongside the conflicting vote data [vote][vote_state][error]
Field | Type | Content | Note |
---|---|---|---|
Buffer | byte (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-SW2 | byte (2) | Return code | see list of return codes |
If Oasis Blob is not a Consensus Type:
Field | Type | Content | Note |
---|---|---|---|
SIG | byte (64) | Signature | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
SIGN_RT_ED25519
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | 0x05 |
INS | byte (1) | Instruction ID | 0x05 |
P1 | byte (1) | Payload desc | 0 = init |
1 = add | |||
2 = last | |||
P2 | byte (1) | ---- | not used |
L | byte (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
Field | Type | Content | Expected |
---|---|---|---|
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 474 |
Path[2] | byte (4) | Derivation Path Data | ? |
Path[3] | byte (4) | Derivation Path Data | ? |
Path[4] | byte (4) | Derivation Path Data | ? |
Other Chunks/Packets
Field | Type | Content | Expected |
---|---|---|---|
Data | bytes... | Context+Message |
Data is defined as:
Field | Type | Content | Expected |
---|---|---|---|
Meta | byte.. | CBOR metadata | |
Message | bytes.. | 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
Field | Type | Content | Note |
---|---|---|---|
SIG | byte (64) | Signature | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
GET_ADDR_SECP256K1
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | 0x05 |
INS | byte (1) | Instruction ID | 0x04 |
P1 | byte (1) | Request User confirmation | No = 0 |
P2 | byte (1) | Parameter 2 | ignored |
L | byte (1) | Bytes in payload | (depends) |
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 60 |
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
Field | Type | Content | Note |
---|---|---|---|
PK | byte (33) | Compressed Public Key | |
ADDR | byte (??) | Hex addr | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
SIGN_RT_SECP256K1
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | 0x05 |
INS | byte (1) | Instruction ID | 0x07 |
P1 | byte (1) | Payload desc | 0 = init |
1 = add | |||
2 = last | |||
P2 | byte (1) | ---- | not used |
L | byte (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
Field | Type | Content | Expected |
---|---|---|---|
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 60 |
Path[2] | byte (4) | Derivation Path Data | ? |
Path[3] | byte (4) | Derivation Path Data | ? |
Path[4] | byte (4) | Derivation Path Data | ? |
Other Chunks/Packets
Field | Type | Content | Expected |
---|---|---|---|
Data | bytes... | Meta+Message |
Data is defined as:
Field | Type | Content | Expected |
---|---|---|---|
Meta | byte.. | CBOR metadata | |
Message | bytes.. | 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
Field | Type | Content | Note |
---|---|---|---|
SIG | byte (64) | Signature | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
GET_ADDR_SR25519
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | 0x05 |
INS | byte (1) | Instruction ID | 0x03 |
P1 | byte (1) | Request User confirmation | No = 0 |
P2 | byte (1) | Parameter 2 | ignored |
L | byte (1) | Bytes in payload | (depends) |
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 474 |
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
Field | Type | Content | Note |
---|---|---|---|
PK | byte (32) | Public Key | |
ADDR | byte (??) | Bech 32 addr | |
SW1-SW2 | byte (2) | Return code | see list of return codes |
SIGN_RT_SR25519
Command
Field | Type | Content | Expected |
---|---|---|---|
CLA | byte (1) | Application Identifier | 0x05 |
INS | byte (1) | Instruction ID | 0x06 |
P1 | byte (1) | Payload desc | 0 = init |
1 = add | |||
2 = last | |||
P2 | byte (1) | ---- | not used |
L | byte (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
Field | Type | Content | Expected |
---|---|---|---|
Path[0] | byte (4) | Derivation Path Data | 44 |
Path[1] | byte (4) | Derivation Path Data | 474 |
Path[2] | byte (4) | Derivation Path Data | ? |
Path[3] | byte (4) | Derivation Path Data | ? |
Path[4] | byte (4) | Derivation Path Data | ? |
Other Chunks/Packets
Field | Type | Content | Expected |
---|---|---|---|
Data | bytes... | Meta+Message |
Data is defined as:
Field | Type | Content | Expected |
---|---|---|---|
Meta | byte.. | CBOR metadata | |
Message | bytes.. | 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
Field | Type | Content | Note |
---|---|---|---|
SIG | byte (64) | Signature | |
SW1-SW2 | byte (2) | Return code | see list of return codes |