From 103d474daac5494b2a2eeff2d1774fc46d316ccb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1=20Bizjak?= Date: Sat, 15 Jul 2023 13:02:46 +0200 Subject: [PATCH] Improve documentation. --- .github/workflows/linter.yml | 1 + concordium-std/src/impls.rs | 12 ++++++++---- concordium-std/src/test_infrastructure.rs | 4 ++-- concordium-std/src/traits.rs | 8 ++++++++ concordium-std/src/types.rs | 7 +++++++ examples/README.md | 2 ++ 6 files changed, 28 insertions(+), 6 deletions(-) diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml index 016d979f..86aa3814 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/linter.yml @@ -49,6 +49,7 @@ jobs: - examples/offchain-transfers/Cargo.toml - examples/credential-registry-storage-contract/Cargo.toml - examples/account-signature-checks/Cargo.toml + steps: - name: Checkout sources uses: actions/checkout@v2 diff --git a/concordium-std/src/impls.rs b/concordium-std/src/impls.rs index 9c824ac2..5e41e850 100644 --- a/concordium-std/src/impls.rs +++ b/concordium-std/src/impls.rs @@ -1992,7 +1992,7 @@ fn parse_query_contract_balance_response_code( /// - the first 3 bytes encodes the return value index. /// - In case of failure the 4th byte is used, and encodes the enviroment /// failure where: -/// - '0x02' encodes missing contract. +/// - '0x02' encodes missing account. fn parse_query_account_public_keys_response_code( code: u64, ) -> Result { @@ -2009,13 +2009,15 @@ fn parse_query_account_public_keys_response_code( } } -/// Decode the account public keys query response code. +/// Decode the response from checking account signatures. /// /// - Success if the last 5 bytes are all zero: -/// - the first 3 bytes encodes the return value index. /// - In case of failure the 4th byte is used, and encodes the enviroment /// failure where: -/// - '0x02' encodes missing contract. +/// - '0x02' encodes missing account. +/// - '0x0a' encodes malformed data, i.e., the call was made with incorrect +/// data. +/// - '0x0b' encodes that signature validation failed. fn parse_check_account_signature_response_code( code: u64, ) -> Result { @@ -2122,6 +2124,8 @@ fn query_exchange_rates_worker() -> ExchangeRates { ExchangeRates::deserial(&mut response).unwrap_abort() } +/// Helper factoring out the common behaviour of `account_public_keys` for the +/// two extern hosts below. fn query_account_public_keys_worker(address: AccountAddress) -> QueryAccountPublicKeysResult { let data: &[u8] = address.as_ref(); let response = unsafe { diff --git a/concordium-std/src/test_infrastructure.rs b/concordium-std/src/test_infrastructure.rs index 43719f8d..2b55fd81 100644 --- a/concordium-std/src/test_infrastructure.rs +++ b/concordium-std/src/test_infrastructure.rs @@ -1563,7 +1563,7 @@ impl + StateClone> fn account_public_keys(&self, _address: AccountAddress) -> QueryAccountPublicKeysResult { unimplemented!( - "The test infrastructure will be deprecaated and so does not implement new \ + "The test infrastructure will be deprecated and so does not implement new \ functionality." ) } @@ -1575,7 +1575,7 @@ impl + StateClone> _data: &[u8], ) -> CheckAccountSignatureResult { unimplemented!( - "The test infrastructure will be deprecaated and so does not implement new \ + "The test infrastructure will be deprecated and so does not implement new \ functionality." ) } diff --git a/concordium-std/src/traits.rs b/concordium-std/src/traits.rs index 1f76c648..766ef12c 100644 --- a/concordium-std/src/traits.rs +++ b/concordium-std/src/traits.rs @@ -411,6 +411,14 @@ pub trait HasHost: Sized { fn account_public_keys(&self, address: AccountAddress) -> QueryAccountPublicKeysResult; /// Verify the signature with account's public keys. + /// + /// - `address` is the address of the account + /// - `signatures` is the [`AccountSignatures`] that are to be checked + /// - `data` is the data that the signatures are on. + /// + /// The response is an error if the account is missing, and if the + /// signatures were correctly parsed then it is a boolean indicating + /// whether the check succeeded or failed. fn check_account_signature( &self, address: AccountAddress, diff --git a/concordium-std/src/types.rs b/concordium-std/src/types.rs index 54958cad..a4b685f6 100644 --- a/concordium-std/src/types.rs +++ b/concordium-std/src/types.rs @@ -654,7 +654,14 @@ pub struct QueryAccountPublicKeysError; /// Error for checking an account signature. #[derive(Debug, Copy, Clone, PartialEq, Eq)] pub enum CheckAccountSignatureError { + /// The account does not exist in the state. MissingAccount, + /// The signature data could not be parsed, i.e., + /// we could not deserialize the signature map and the data to check the + /// signature against. This should typically not happen since the + /// `concordium-std` library prevents calls that could trigger it, but + /// is here for completeness since it is a possible error returned from + /// the node. MalformedData, } diff --git a/examples/README.md b/examples/README.md index 8c5a26c5..127c2fab 100644 --- a/examples/README.md +++ b/examples/README.md @@ -8,6 +8,8 @@ the logic of the contract is reasonable, or safe. **Do not use these contracts as-is for anything other then experimenting.** The list of contracts is as follows +- [account-signature-checks](./account-signature-checks) A simple contract that + demonstrates how account signature checks can be performed in smart contracts. - [two-step-transfer](./two-step-transfer) A contract that acts like an account (can send, store and accept CCD), but requires n > 1 ordained accounts to agree to the sending of CCD before it is accepted. - [auction](./auction) A contract implementing an simple auction.