From f9bbccc747dc80800db967712225ba4dc5f4b9ac Mon Sep 17 00:00:00 2001 From: keiff3r Date: Tue, 3 Dec 2024 17:28:32 +0100 Subject: [PATCH] docs: add documentation for some methods --- doc/api.md | 24 +++++++++++++++++++++ doc/export_private_key.md | 29 ++++++++++++++++++++++++++ doc/ins_configure_baker.md | 28 +++++++++++++++++++++++++ doc/ins_configure_delegation.md | 11 ++++++++++ doc/ins_encrypted_amount_transfer.md | 31 ++++++++++++++++++++++++++++ doc/ins_public_info_for_ip.md | 14 +++++++++++++ doc/ins_public_key.md | 16 ++++++++++++++ doc/ins_register_data.md | 13 ++++++++++++ doc/ins_transfer.md | 26 +++++++++++++++++++++++ doc/ins_transfer_to_encrypted.md | 11 ++++++++++ doc/ins_transfer_to_public.md | 12 +++++++++++ doc/ins_transfer_with_schedule.md | 28 +++++++++++++++++++++++++ doc/verify_address.md | 16 ++++++++++++++ 13 files changed, 259 insertions(+) create mode 100644 doc/api.md create mode 100644 doc/export_private_key.md create mode 100644 doc/ins_configure_baker.md create mode 100644 doc/ins_configure_delegation.md create mode 100644 doc/ins_encrypted_amount_transfer.md create mode 100644 doc/ins_public_info_for_ip.md create mode 100644 doc/ins_public_key.md create mode 100644 doc/ins_register_data.md create mode 100644 doc/ins_transfer.md create mode 100644 doc/ins_transfer_to_encrypted.md create mode 100644 doc/ins_transfer_to_public.md create mode 100644 doc/ins_transfer_with_schedule.md create mode 100644 doc/verify_address.md diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 00000000..a510d519 --- /dev/null +++ b/doc/api.md @@ -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. diff --git a/doc/export_private_key.md b/doc/export_private_key.md new file mode 100644 index 00000000..a997cb23 --- /dev/null +++ b/doc/export_private_key.md @@ -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) | diff --git a/doc/ins_configure_baker.md b/doc/ins_configure_baker.md new file mode 100644 index 00000000..db01b622 --- /dev/null +++ b/doc/ins_configure_baker.md @@ -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]` | | diff --git a/doc/ins_configure_delegation.md b/doc/ins_configure_delegation.md new file mode 100644 index 00000000..3e328123 --- /dev/null +++ b/doc/ins_configure_delegation.md @@ -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. | diff --git a/doc/ins_encrypted_amount_transfer.md b/doc/ins_encrypted_amount_transfer.md new file mode 100644 index 00000000..908faea2 --- /dev/null +++ b/doc/ins_encrypted_amount_transfer.md @@ -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. | diff --git a/doc/ins_public_info_for_ip.md b/doc/ins_public_info_for_ip.md new file mode 100644 index 00000000..4b965f87 --- /dev/null +++ b/doc/ins_public_info_for_ip.md @@ -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]` | | diff --git a/doc/ins_public_key.md b/doc/ins_public_key.md new file mode 100644 index 00000000..5a1e5285 --- /dev/null +++ b/doc/ins_public_key.md @@ -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. | diff --git a/doc/ins_register_data.md b/doc/ins_register_data.md new file mode 100644 index 00000000..677a0b93 --- /dev/null +++ b/doc/ins_register_data.md @@ -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) | diff --git a/doc/ins_transfer.md b/doc/ins_transfer.md new file mode 100644 index 00000000..87ab5d40 --- /dev/null +++ b/doc/ins_transfer.md @@ -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. | diff --git a/doc/ins_transfer_to_encrypted.md b/doc/ins_transfer_to_encrypted.md new file mode 100644 index 00000000..2334e8e9 --- /dev/null +++ b/doc/ins_transfer_to_encrypted.md @@ -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]` | | diff --git a/doc/ins_transfer_to_public.md b/doc/ins_transfer_to_public.md new file mode 100644 index 00000000..02b41014 --- /dev/null +++ b/doc/ins_transfer_to_public.md @@ -0,0 +1,12 @@ +# Transfer to public + +A transaction for transferring an encrypted amount to the public balance of the account. + +## Protocol description + +- Multiple commands. + +| INS | P1 | P2 | CDATA | Comment | +| ------ | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| `0x12` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] remaining_encrypted_amount[192 bytes] transfer_amount[uint64] encrypted_amount_agg_index[8 bytes] proofs_size[uint16]` | | +| `0x12` | `0x00` | `0x00` | `proofs[1..255 bytes]` | In batches of up to 255 bytes, repeated until all proofs have been sent. | diff --git a/doc/ins_transfer_with_schedule.md b/doc/ins_transfer_with_schedule.md new file mode 100644 index 00000000..a87107ff --- /dev/null +++ b/doc/ins_transfer_with_schedule.md @@ -0,0 +1,28 @@ +# Transfer with schedule + +A transaction to send GTU from one account to another with a schedule, i.e. each transfer +of a GTU amount can be set to be released at a specific point in time. + +## Protocol description + +- Multiple commands + +| INS | P1 | P2 | CDATA | Comment | +| ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0x03` | `0x00` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] recipient_address[32 bytes] scheduled_amounts_count[uint8]` | Transaction kind must be 19. | +| `0x03` | `0x01` | `0x00` | `(timestamp[uint64] amount[uint64])x[count]` | Up to 15 pairs of timestamp and amount pairs can be sent per packet, and packets can be sent until scheduled_amounts_count pairs have been sent in total. The maximum number of packets that can be sent should be sent, i.e. if there are more than 15 left to send, then 15 should be sent. | + +# Transfer with schedule with memo + +A 'Transfer with schedule', with a memo attached. +Uses the same INS number, but a different P1 for the initial call, and has a different transaction kind (24); + +## Protocol description + +- Multiple commands + +| INS | P1 | P2 | CDATA | Comment | +| ------ | ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0x03` | `0x02` | `0x00` | `path_length path[uint32]x[8] account_transaction_header[60 bytes] transaction_kind[uint8] recipient_address[32 bytes] scheduled_amounts_count[uint8] memo_length[uint16]` | Transaction kind must be 24. | +| `0x03` | `0x03` | `0x00` | `memo[1...255 bytes]` | The memo is assumed to be CBOR encoded. | +| `0x03` | `0x01` | `0x00` | `(timestamp[uint64] amount[uint64])x[count]` | Up to 15 pairs of timestamp and amount pairs can be sent per packet, and packets can be sent until scheduled_amounts_count pairs have been sent in total. The maximum number of packets that can be sent should be sent, i.e. if there are more than 15 left to send, then 15 should be sent. | diff --git a/doc/verify_address.md b/doc/verify_address.md new file mode 100644 index 00000000..c3e49ce3 --- /dev/null +++ b/doc/verify_address.md @@ -0,0 +1,16 @@ +# Verify Address + +Given an identity index and a credential counter/account index this function displays the associated account address. + +Allows the user to approve or reject the address, determining whether the app returns success or rejection. + +For an account address to match the one that is displayed, the account's primary credential must be made using the PRF-key exported by the same Ledger on the same identity index and credential counter. +The address is the credId's sh256 hash, and is displayed in base58. + +## Protocol description + +- Single command + +| INS | P1 | P2 | CDATA | Comment | +| ------ | ------ | ------ | -------------------------------------- | ------- | +| `0x00` | `0x00` | `0x00` | `identity[uint32] credCounter[uint32]` | |