docs: add nat-spec doc comments (#255)

* docs: add nat-spec doc comments

* fix: more errors cleanup

* chore: extend cspell dict

* docs: weird -> unusual

* feat: update timestamp asserter locator with mainnet address

* chore: update webauthn docs

Provide some extra information that's less obvious from reading the code
unless you are already familiar with webauthn

---------

Co-authored-by: Colin <[email protected]>

cspell-config/cspell-misc.txt

@@ -11,6 +11,7 @@ testid
 vueuse
 dockerized
 ethereum
+sepolia
 
 // examples/bank-demo
 ctap

src/SsoBeacon.sol

@@ -6,6 +6,9 @@ import { UpgradeableBeacon } from "@openzeppelin/contracts/proxy/beacon/Upgradea
 /// @title SsoBeacon
 /// @author Matter Labs
 /// @custom:security-contact [email protected]
+/// @dev This beacon stores the implementation address of SsoAccount contract,
+/// which every SSO account delegates to. This beacon's address is immutably stored
+/// in AAFactory contract, as it is required for deploying new SSO accounts.
 contract SsoBeacon is UpgradeableBeacon {
   constructor(address _implementation) UpgradeableBeacon(_implementation) {}
 }

src/helpers/TimestampAsserterLocator.sol

@@ -3,16 +3,24 @@ pragma solidity ^0.8.24;
 
 import { ITimestampAsserter } from "../interfaces/ITimestampAsserter.sol";
 
+/// @title Timestamp asserter locator
+/// @author Matter Labs
+/// @custom:security-contact [email protected]
+/// @notice This library is used to locate the TimestampAsserter contract on different networks.
+/// @dev Might be removed in the future, when TimestampAsserter is deployed via create2 to the same address on all networks.
 library TimestampAsserterLocator {
   function locate() internal view returns (ITimestampAsserter) {
+    // anvil-zksync (era-test-node)
     if (block.chainid == 260) {
-      return ITimestampAsserter(address(0x00000000000000000000000000000000808012));
+      return ITimestampAsserter(address(0x0000000000000000000000000000000000808012));
     }
+    // era sepolia testnet
     if (block.chainid == 300) {
       return ITimestampAsserter(address(0xa64EC71Ee812ac62923c85cf0796aA58573c4Cf3));
     }
+    // era mainnet
     if (block.chainid == 324) {
-      revert("Timestamp asserter is not deployed on ZKsync mainnet yet");
+      return ITimestampAsserter(address(0x958F70e4Fd676c9CeAaFe5c48cB78CDD08b4880d));
     }
     revert("Timestamp asserter is not deployed on this network");
   }

src/helpers/TokenCallbackHandler.sol

@@ -6,8 +6,9 @@ import { IERC721Receiver } from "@openzeppelin/contracts/token/ERC721/IERC721Rec
 import { IERC1155Receiver } from "@openzeppelin/contracts/token/ERC1155/IERC1155Receiver.sol";
 
 /**
- * Token callback handler.
- *   Handles supported tokens' callbacks, allowing account receiving these tokens.
+ * @title Token callback handler
+ * @notice Contract to handle ERC721 and ERC1155 token callbacks
+ * @author https://getclave.io
  */
 contract TokenCallbackHandler is IERC721Receiver, IERC1155Receiver {
   function onERC721Received(address, address, uint256, bytes calldata) external pure override returns (bytes4) {

src/interfaces/IHook.sol

@@ -5,15 +5,26 @@ import { Transaction } from "@matterlabs/zksync-contracts/l2/system-contracts/li
 import { IERC165 } from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import { IModule } from "./IModule.sol";
 
-// Validation hooks are a non-standard way to always perform validation,
-// They can't expect any specific transaction data or signature, but can be used to enforce
-// additional restrictions on the account during the validation phase
+/// @title Validation hook interface for native AA
+/// @author getclave.io
+/// @notice Validation hooks trigger before each transaction,
+/// can be used to enforce additional restrictions on the account and/or transaction during the validation phase.
 interface IValidationHook is IModule, IERC165 {
+  /// @notice Hook that triggers before each transaction during the validation phase.
+  /// @param signedHash Hash of the transaction that is being validated.
+  /// @param transaction Transaction that is being validated.
+  /// @dev If reverts, the transaction is rejected from the mempool and not included in the block.
   function validationHook(bytes32 signedHash, Transaction calldata transaction) external;
 }
 
+/// @title Execution hook interface for native AA
+/// @author getclave.io
+/// @notice Execution hooks trigger before and after each transaction, during the execution phase.
 interface IExecutionHook is IModule, IERC165 {
-  function preExecutionHook(Transaction calldata transaction) external returns (bytes memory context);
+  /// @notice Hook that triggers before each transaction during the execution phase.
+  /// @param transaction Transaction that is being executed.
+  function preExecutionHook(Transaction calldata transaction) external;
 
+  /// @notice Hook that triggers after each transaction during the execution phase.
   function postExecutionHook() external;
 }

src/interfaces/IModule.sol

@@ -1,3 +1,7 @@
+/**
+ * @title Module interface
+ * @dev Interface for a module that can be added to SSO account (e.g. hook or validator).
+ */
 interface IModule {
   /**
    * @dev This function is called by the smart account during installation of the module

src/interfaces/IModuleValidator.sol

@@ -7,16 +7,28 @@ import { IModule } from "./IModule.sol";
 
 /**
  * @title Modular validator interface for native AA
- * @dev Add signature to module or validate existing signatures for acccount
+ * @notice Validators are used for custom validation of transactions and/or message signatures
  */
 interface IModuleValidator is IModule, IERC165 {
+  /**
+   * @notice Validate transaction for account
+   * @param signedHash Hash of the transaction
+   * @param signature Signature for the transaction
+   * @param transaction Transaction to validate
+   * @return bool True if transaction is valid
+   */
   function validateTransaction(
     bytes32 signedHash,
-    bytes memory signature,
+    bytes calldata signature,
     Transaction calldata transaction
   ) external returns (bool);
 
-  function validateSignature(bytes32 signedHash, bytes memory signature) external view returns (bool);
-
-  function addValidationKey(bytes memory key) external returns (bool);
+  /**
+   * @notice Validate signature for account (including via EIP-1271)
+   * @dev If module is not supposed to validate signatures, it MUST return false
+   * @param signedHash Hash of the message
+   * @param signature Signature of the message
+   * @return bool True if signature is valid
+   */
+  function validateSignature(bytes32 signedHash, bytes calldata signature) external view returns (bool);
 }

src/interfaces/ITimestampAsserter.sol

@@ -1,6 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.24;
 
+/// @title Timestamp asserter interface
+/// @author Matter Labs
+/// @custom:security-contact [email protected]
+/// @notice Used to assert that the current timestamp is within a given range in AA validation context.
 interface ITimestampAsserter {
   function assertTimestampInRange(uint256 start, uint256 end) external view;
 }

src/libraries/Errors.sol

@@ -1,56 +1,25 @@
 // SPDX-License-Identifier: GPL-3.0
 pragma solidity ^0.8.24;
 
+/// @title Errors
+/// @notice Errors used by ZKsync SSO and its components
+/// @author getclave.io
 library Errors {
-  /*//////////////////////////////////////////////////////////////
-                               ACCOUNT
-    //////////////////////////////////////////////////////////////*/
-
+  // Account errors
   error INSUFFICIENT_FUNDS(uint256 required, uint256 available);
   error FEE_PAYMENT_FAILED();
   error METHOD_NOT_IMPLEMENTED();
 
-  /*//////////////////////////////////////////////////////////////
-                               LINKED LIST
-    //////////////////////////////////////////////////////////////*/
-
-  error INVALID_PREV_BYTES(bytes prevValue, bytes oldValue);
-  error INVALID_PREV_ADDR(address prevValue, address oldValue);
-  // Bytes
-  error INVALID_BYTES(uint256 length);
-  error BYTES_ALREADY_EXISTS(bytes length);
-  error BYTES_NOT_EXISTS(bytes lookup);
-  // Address
-  error INVALID_ADDRESS(address valid);
-  error ADDRESS_ALREADY_EXISTS(address exists);
-  error ADDRESS_NOT_EXISTS(address notExists);
-
-  /*//////////////////////////////////////////////////////////////
-                             VALIDATOR MANAGER
-    //////////////////////////////////////////////////////////////*/
-
+  // ERC165 module errors
   error VALIDATOR_ERC165_FAIL(address validator);
-
-  /*//////////////////////////////////////////////////////////////
-                              HOOK MANAGER
-    //////////////////////////////////////////////////////////////*/
-
-  error EMPTY_HOOK_ADDRESS(uint256 hookAndDataLength);
   error HOOK_ERC165_FAIL(address hookAddress, bool isValidation);
-  error INVALID_KEY(bytes32 key);
-
-  /*//////////////////////////////////////////////////////////////
-                              AUTH
-    //////////////////////////////////////////////////////////////*/
 
+  // Auth errors
   error NOT_FROM_BOOTLOADER(address notBootloader);
   error NOT_FROM_HOOK(address notHook);
   error NOT_FROM_SELF(address notSelf);
 
-  /*//////////////////////////////////////////////////////////////
-                            BatchCaller
-    //////////////////////////////////////////////////////////////*/
-
+  // Batch caller errors
   error CALL_FAILED(uint256 batchCallIndex);
   error MSG_VALUE_MISMATCH(uint256 actualValue, uint256 expectedValue);
 }