This application describes the APDU messages interface to communicate with the Everscale application.
The application covers the following functionalities :
- Retrieve a public key given an account number
- Retrieve an address given an account number
- Sign Everscale message hash
- Sign Everscale BOC transaction
The application interface can be accessed over HID or BLE
| Field name | Length (bytes) | Description |
|---|---|---|
| CLA | 1 | Instruction class - indicates the type of command |
| INS | 1 | Instruction code - indicates the specific command |
| P1 | 1 | Instruction parameter 1 for the command |
| P2 | 1 | Instruction parameter 2 for the command |
| Lc | 1 | The number of bytes of command data to follow (a value from 0 to 255) |
| CData | variable | Command data with Lc bytes |
No `Le` field in APDU command
This command returns specific application configuration
| CLA | INS | P1 | P2 | Lc | CData |
|---|---|---|---|---|---|
| E0 | 01 | 00 | 00 | 00 | variable |
None
| Description | Length |
|---|---|
| Application major version | 01 |
| Application minor version | 01 |
| Application patch version | 01 |
This command returns a public key for the given account number
| CLA | INS | P1 | P2 | Lc | CData |
|---|---|---|---|---|---|
| E0 | 02 | 00 : return public key 01 : display public key and confirm before returning |
00 | variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| Description | Length |
|---|---|
| Pubkey length | 1 |
| Pubkey | 32 |
This command signs a message
To avoid blindly signing message hash the application adds a 4-byte prefix [0xFF, 0xFF, 0xFF, 0xFF] to the message before signing.
| CLA | INS | P1 | P2 | Lc | CData |
|---|---|---|---|---|---|
| E0 | 03 | 01 | 00 | variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| A bytes to sign | 32 |
| Description | Length |
|---|---|
| Signature length | 1 |
| Signature | 64 |
This command returns an address for the given account number
| CLA | INS | P1 | P2 | Lc | CData |
|---|---|---|---|---|---|
| E0 | 04 | 00 : return address 01 : display address and confirm before returning |
00 | variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| Wallet number to retrieve | 1 |
| Description | Length |
|---|---|
| Address length | 1 |
| Address | 32 |
This command signs a transaction message
| CLA | INS | P1 | P2 | Lc | CData |
|---|---|---|---|---|---|
| E0 | 05 | 01 | 0x01 (last chunk) 0x02 (first chunk) 0x00 (single chunk) 0x03 (intermediate chunk) |
variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| Original wallet number to derive address | 1 |
| Decimals | 1 |
| Ticker length | 1 |
| Ticker | variable |
| Metadata | 1 |
| Current wallet number to parse transaction abi (Optional: metadata b'00000001) | 1 |
| Workchain ID (Optional: metadata b'00000010) | 1 |
| Deploy contract address (Optional: metadata b'00000100) | 32 |
| Chain ID (Optional: metadata b'00001000) | 4 |
| Serialized transaction | variable |
| Description | Length |
|---|---|
| Address length | 1 |
| Signature | 64 |
APDU Command payloads are encoded as follows :
| Description | Length |
|---|---|
| APDU length (big endian) | 2 |
| APDU CLA | 1 |
| APDU INS | 1 |
| APDU P1 | 1 |
| APDU P2 | 1 |
| APDU data length | 1 |
| Optional APDU data | var |
APDU payload is encoded according to the APDU case
| Case Number | Lc | Le | Case description |
|---|---|---|---|
| 1 | 0 | 0 | No data in either direction - L is set to 00 |
| 2 | 0 | !0 | Input Data present, no Output Data - L is set to Lc |
| 3 | !0 | 0 | Output Data present, no Input Data - L is set to Le |
| 4 | !0 | !0 | Both Input and Output Data are present - L is set to Lc |
APDU Response payloads are encoded as follows :
| Description | Length |
|---|---|
| APDU response length (big endian) | 2 |
| APDU response data and Status Word | var |
Messages are exchanged with the dongle over HID endpoints over interrupt transfers, with each chunk being 64 bytes long. The HID Report ID is ignored.
A similar encoding is used over BLE, without the Communication channel ID.
The application acts as a GATT server defining service UUID D973F2E0-B19E-11E2-9E96-0800200C9A66
When using this service, the client sends requests to the characteristic D973F2E2-B19E-11E2-9E96-0800200C9A66, and gets notified on the characteristic D973F2E1-B19E-11E2-9E96-0800200C9A66 after registering for it.
Requests are encoded using the standard BLE 20 bytes MTU size
The following standard Status Words are returned for all APDUs - some specific Status Words can be used for specific commands and are mentioned in the command description.
| SW | Description |
|---|---|
| 6700 | Incorrect length |
| 6982 | Security status not satisfied (Canceled by user) |
| 6B0x | Invalid request |
| 6Fxx | Technical problem (Internal error, please report) |
| 9000 | Normal ending of the command |