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
This command returns specific application configuration
| CLA | INS | P1 | P2 | Lc | Le |
|---|---|---|---|---|---|
| E0 | 01 | 00 | 00 | 00 | 04 |
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 | Le |
|---|---|---|---|---|---|
| E0 | 02 | 00 | 00 | variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| Description | Length |
|---|---|
| Pubkey length | 1 |
| Pubkey | 32 |
This command signs a message
| CLA | INS | P1 | P2 | Lc | Le |
|---|---|---|---|---|---|
| E0 | 03 | 01 | 00 | variable | variable |
| Description | Length |
|---|---|
| An account number to retrieve | 4 |
| Metadata | 1 |
| Chain ID (Optional: metadata b'00000100) | 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 | Le |
|---|---|---|---|---|---|
| E0 | 04 | 00 | 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 | Le |
|---|---|---|---|---|---|
| E0 | 05 | 01 | 00 | 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 |
Ledger APDUs requests and responses are encapsulated using a flexible protocol allowing to fragment large payloads over different underlying transport mechanisms.
The common transport header is defined as follows:
| Description | Length |
|---|---|
| Communication channel ID (big endian) | 2 |
| Command tag | 1 |
| Packet sequence index (big endian) | 2 |
| Payload | var |
The Communication channel ID allows commands multiplexing over the same physical link. It is not used for the time being, and should be set to 0101 to avoid compatibility issues with implementations ignoring a leading 00 byte.
The Command tag describes the message content. Use TAG_APDU (0x05) for standard APDU payloads, or TAG_PING (0x02) for a simple link test.
The Packet sequence index describes the current sequence for fragmented payloads. The first fragment index is 0x00.
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 |