forked from Concordium/concordium-ledger-app
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add documentation for some methods
- Loading branch information
Showing
13 changed files
with
259 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Concordium Ledger Nano S API | ||
|
|
||
| This document contains a brief overview of how to integrate with the Concordium Ledger applications. It should | ||
| be used as a reference when implementing software that integrates with the application. | ||
|
|
||
| ## Communication protocol | ||
|
|
||
| The Ledger device uses APDU (Application Protocol Data Unit) messages for the communication between a computer host and | ||
| the Ledger device. A very brief introduction to the protocol can be | ||
| found [here](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit), but it will help to provide | ||
| an understanding of the Concordium specific command protocols. | ||
|
|
||
| For the specific protocol for a specific function, please refer to the documents prefixed by 'ins'. A document exists | ||
| for each piece of functionality exposed by the Concordium applications. | ||
|
|
||
| ## Key derivation path | ||
|
|
||
| For (almost) all instructions a key derivation path has to be provided. This is always sent as the initial bytes in the first | ||
| command. So any first command for a function on the Ledger starts with: | ||
|
|
||
| `CLA INS P1 P2 Lc path_length path` | ||
|
|
||
| It is necessary to include the path length as it is not static, i.e. some paths are longer than others in our | ||
| setup. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| # Export private key | ||
|
|
||
| As the Ledger Nano S (at the time of writing) does not support the necessary key types, we have implemented an export | ||
| of some special private keys. These keys are not account signing keys, and note that it is not possible to export keys that are used for signatures. | ||
| Signature keys do not leave the device at any point, and the exported keys cannot be used to submit transactions. | ||
|
|
||
| The two key types that can be exported are exactly these: | ||
|
|
||
| 1. PRF-key | ||
| 1. IdCredSec | ||
|
|
||
| If P2 = 0x01, the exported keys are derived using SLIP10 for ed25519. | ||
| These must be used as the key seed for the KeyGen algorithm for generating BLS12-381 private keys. | ||
| This endpoint is deprecated and should not be used. (Available to support legacy accounts from the desktop wallet) | ||
|
|
||
| If P2 = 0x02, the BLS12-381 private keys will be exported instead. (Generated using the corresponding ed25519 key as key seed) | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Single command | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ------------------ | -------------------------------------------------------------------------------------------------------------- | | ||
| | `0x05` | `0x00` | `0x01` | `identity[uint32]` | Export of PRF key seed for the BLS12-381 KeyGen algorithm (Deprecated) | | ||
| | `0x05` | `0x01` | `0x01` | `identity[uint32]` | Export of PRF key seed for the BLS12-381 KeyGen algorithm with alternative display (for recovery) (Deprecated) | | ||
| | `0x05` | `0x02` | `0x01` | `identity[uint32]` | Export of PRF key and IdCredSec seeds for the BLS12-381 KeyGen algorithm (Deprecated) | | ||
| | `0x05` | `0x00` | `0x02` | `identity[uint32]` | Export of PRF key (BLS12-381) | | ||
| | `0x05` | `0x01` | `0x02` | `identity[uint32]` | Export of PRF key with alternative display (for recovery) (BLS12-381) | | ||
| | `0x05` | `0x02` | `0x02` | `identity[uint32]` | Export of PRF key and IdCredSec (BLS12-381) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| # Configure baker | ||
|
|
||
| A transaction to configure a baker. | ||
|
|
||
| All parameters of the payload are optional, and the first part of the payload is a bitmap used to indicate which of the optional parameters that are sent. 8 bits are used: | ||
|
|
||
| - index 0: capital amount | ||
| - index 1: restake earnings | ||
| - index 2: open for delegation | ||
| - index 3: Baker keys | ||
| - index 4: metadata url | ||
| - index 5: transaction fee commission | ||
| - index 6: baking reward commission | ||
| - index 7: finalization reward commission | ||
|
|
||
| The Ledger expects that only necessary parts are sent. i.e. if the 4th bit in the bitmap is not set, there should not be a metadata url, and so the P1 = 2 and P1 = 3 parts should be skipped. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Multiple commands | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `0x18` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] bitmap[uint16] capitalAmount[uint64] restakeEarnings[uint8] openForDelegation[uint8] electionVerifyKey[uint32] electionProof[uint64] signatureVerifyKey[uint32] signatureProof[uint64]` | restakeEarnings should be 0 or 1, openForDelegation should be 0,1 or 2 (representing "open for all", "Closed for new", "Closed for all" respectively) | | ||
| | `0x18` | `0x01` | `0x00` | `aggregationVerifyKey[uint96] aggregationProof[uint64]` | | | ||
| | `0x18` | `0x02` | `0x00` | `metadataUrlLength[uint16]` | | | ||
| | `0x18` | `0x03` | `0x00` | `metadataUrl[1..255 bytes]` | In batches of up to 255 bytes, repeated until the entire URL has been sent. | | ||
| | `0x18` | `0x04` | `0x00` | `transactionFeeCommissionRate[uint32] bakingRewardCommissionRate[uint32] finalizationRewardCommissionRate[uint32]` | | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Configure delegation | ||
|
|
||
| A transaction to configure the delegation of stake. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Single command | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `0x17` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] bitmap[uint16] (optional) capitalAmount[uint64] (optional) restakeEarnings[uint8] (optional) delegationTarget[uint8] (optional) bakerId[uint64]` | The `bitmap` is used to indicate which of the optional parameters that are sent. For example `5 = 0b101`, which translates to the capital and delegation target parameters being sent in the transaction, whereas e.g. `2 = 0b010` means that only the restake earnings parameter is sent. Restake earnings has to be either 0 (do not restake), or 1 (do restake). The delegationTarget has to be either 0 (Passive delegation) or 1 (Specific baker). Note that a bakerId should only be supplied if `delegationTarget = 1`. Note that it is not valid to not supply any of the optional parameters, i.e. at least one of the capital, restake or delegation target must be supplied. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Encrypted amount transfer | ||
|
|
||
| A transaction for transferring an encrypted amount to another account. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Multiple commands. | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | ||
| | `0x11` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] to_address[32 bytes]` | | | ||
| | `0x11` | `0x01` | `0x00` | `remaining_amount` | | | ||
| | `0x11` | `0x02` | `0x00` | `transfer_amount index encrypted_amount_agg_index proofs_size[uint16]` | | | ||
| | `0x11` | `0x03` | `0x00` | `proofs[1..255 bytes]` | In batches of up to 255 bytes, repeated until all proofs have been sent. | | ||
|
|
||
| # Encrypted amount transfer with memo | ||
|
|
||
| A transaction for transferring an encrypted amount to another account, with a memo attached. | ||
| Uses the same INS number, but a different P1 for the initial call, and has a different transaction kind (23); | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Multiple commands | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | ||
| | `0x11` | `0x04` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] to_address[32 bytes] memo_length[uint16]` | | | ||
| | `0x11` | `0x05` | `0x00` | `memo[1...255 bytes]` | The memo is assumed to be CBOR encoded. | | ||
| | `0x11` | `0x01` | `0x00` | `remaining_amount` | | | ||
| | `0x11` | `0x02` | `0x00` | `transfer_amount index encrypted_amount_agg_index proofs_size[uint16]` | | | ||
| | `0x11` | `0x03` | `0x00` | `proofs[1..255 bytes]` | In batches of up to 255 bytes, repeated until all proofs have been sent. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # Public information for identity provider | ||
|
|
||
| When creating an identity some data has to be signed as a part of the protocol for identity creation, which | ||
| is carried out with the identity provider. This function allows for the signing of that data. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Multiple commands | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | ||
| | `0x20` | `0x00` | `0x00` | `path_length path[uint32]x[8] id_cred_pub[48 bytes] cred_id[48 bytes] public_key_count[uint8]` | | | ||
| | `0x20` | `0x01` | `0x00` | `key_index[uint8] key_type[uint8] public_key[32 bytes]` | Instruction is repeated until `public_key_count` keys have been sent. | | ||
| | `0x20` | `0x02` | `0x00` | `threshold[uint8]` | | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Export public key | ||
|
|
||
| Provides the ability to export public-keys for accounts, and also for governance keys. The key to | ||
| be exported is defined by the key derivation path that is provided, which can either be for an | ||
| account or for a governance key. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Single command | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | --------------------- | ------------------------------------------------------ | | ||
| | `0x01` | `0x00` | `0x00` | `path[uint32]x[5..8]` | Export of a public-key with user acceptance. | | ||
| | `0x01` | `0x01` | `0x00` | `path[uint32]x[5..8]` | Export of a public-key without user acceptance. | | ||
| | `0x01` | `0x00` | `0x01` | `path[uint32]x[5..8]` | Export of a signed public-key with user acceptance. | | ||
| | `0x01` | `0x01` | `0x01` | `path[uint32]x[5..8]` | Export of a signed public-key without user acceptance. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| # Register data | ||
|
|
||
| A transaction to register some data on the chain. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Maximum supported data size is 256 bytes. | ||
| - Multiple commands | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `0x35` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] data_length[uint16]` | | | ||
| | `0x35` | `0x01` | `0x00` | `data[1...255 bytes]` | The data is assumed to be CBOR encoded, and should be sent in batches of up to 255 bytes (Either 1 batch, or a 255 byte batch + 1 byte batch) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # Transfer transaction | ||
|
|
||
| A transaction to transfer GTU from one account to another. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Single command | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | ||
| | `0x02` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] recipient_address[32 bytes] amount[uint64]` | The amount is in µGTU. The recipient address has to be base58. | | ||
|
|
||
| # Transfer with memo | ||
|
|
||
| A transaction to transfer GTU from one account to another, with a memo attached. | ||
| Uses the same INS number, but a different P1 for the initial call, and has a different transaction kind (22); | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Multiple commands | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | ||
| | `0x02` | `0x01` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] recipient_address[32 bytes] memo_length[uint16]` | The recipient address has to be base58. | | ||
| | `0x02` | `0x02` | `0x00` | `memo[1...255 bytes]` | The memo is assumed to be CBOR encoded. | | ||
| | `0x02` | `0x03` | `0x00` | `amount[uint64]` | The amount is in µGTU. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| # Transfer to encrypted | ||
|
|
||
| A transaction for transferring an amount to the encrypted balance of the account. | ||
|
|
||
| ## Protocol description | ||
|
|
||
| - Single command | ||
|
|
||
| | INS | P1 | P2 | CDATA | Comment | | ||
| | ------ | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------- | ------- | | ||
| | `0x11` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] amount_to_encrypted[uint64]` | | |
Oops, something went wrong.