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 chuncks 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: 1.1 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 1.2 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 |
