Improve documentation.

.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

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<ExternCallResponse, QueryAccountPublicKeysError> {
@@ -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<bool, CheckAccountSignatureError> {
@@ -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 {

concordium-std/src/test_infrastructure.rs

@@ -1563,7 +1563,7 @@ impl<State: Serial + DeserialWithState<TestStateApi> + StateClone<TestStateApi>>
 
     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<State: Serial + DeserialWithState<TestStateApi> + StateClone<TestStateApi>>
         _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."
         )
     }

concordium-std/src/traits.rs

@@ -411,6 +411,14 @@ pub trait HasHost<State>: 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,

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,
 }
 

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.