From 452067175ef7b90f9e13bd062b87b4964ff6e786 Mon Sep 17 00:00:00 2001 From: Ekrem Seren Date: Fri, 23 Aug 2024 15:16:45 +0300 Subject: [PATCH] add solidity docgen and generate docs --- contracts/account/CMAccount.sol | 125 +- contracts/account/ChequeManager.sol | 80 +- contracts/account/GasMoneyManager.sol | 14 +- contracts/booking-token/BookingToken.sol | 60 +- .../booking-token/BookingTokenOperator.sol | 2 +- contracts/manager/CMAccountManager.sol | 88 +- docs/index.md | 2887 +++++++++++++++++ hardhat.config.js | 6 + package.json | 2 + yarn.lock | 12 +- 10 files changed, 3106 insertions(+), 170 deletions(-) create mode 100644 docs/index.md diff --git a/contracts/account/CMAccount.sol b/contracts/account/CMAccount.sol index 7e60214..14678dd 100644 --- a/contracts/account/CMAccount.sol +++ b/contracts/account/CMAccount.sol @@ -51,7 +51,7 @@ import "./GasMoneyManager.sol"; * operation pays the price of the Booking Token with the funds on the * {CMAccount} contract. * - * @dev This contract uses UUPS style upgradability. The authorization function + * @dev This contract uses UUPS style upgradeability. The authorization function * `_authorizeUpgrade(address)` can be called by the `UPGRADER_ROLE` and is * restricted to only upgrade to the implementation address registered on the * {CMAccountManager} contract. @@ -74,43 +74,43 @@ contract CMAccount is ***************************************************/ /** - * @dev Upgrader role can upgrade the contract to a new implementation. + * @notice Upgrader role can upgrade the contract to a new implementation. */ bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE"); /** - * @dev Bot admin role can add & remove bots and set gas money withdrawal + * @notice Bot admin role can add & remove bots and set gas money withdrawal * parameters. */ bytes32 public constant BOT_ADMIN_ROLE = keccak256("BOT_ADMIN_ROLE"); /** - * @dev Cheque operator role can issue cheques to be paid by this CMAccount + * @notice Cheque operator role can issue cheques to be paid by this CMAccount * contract. */ bytes32 public constant CHEQUE_OPERATOR_ROLE = keccak256("CHEQUE_OPERATOR_ROLE"); /** - * @dev Gas withdrawer role can withdraw gas money from the contract. This is + * @notice Gas withdrawer role can withdraw gas money from the contract. This is * intended to be used by the bots and is granted when `addMessengerBot` is * called. */ bytes32 public constant GAS_WITHDRAWER_ROLE = keccak256("GAS_WITHDRAWER_ROLE"); /** - * @dev Withdrawer role can withdraw funds from the contract. + * @notice Withdrawer role can withdraw funds from the contract. */ bytes32 public constant WITHDRAWER_ROLE = keccak256("WITHDRAWER_ROLE"); /** - * @dev Booking operator role can mint and buy booking tokens using the + * @notice Booking operator role can mint and buy booking tokens using the * functions on this contract. This is generally used by the bots. The * price for the booking token is paid by this contract. */ bytes32 public constant BOOKING_OPERATOR_ROLE = keccak256("BOOKING_OPERATOR_ROLE"); /** - * @dev Service admin role can add & remove supported & wanted services. + * @notice Service admin role can add & remove supported & wanted services. */ bytes32 public constant SERVICE_ADMIN_ROLE = keccak256("SERVICE_ADMIN_ROLE"); @@ -149,27 +149,27 @@ contract CMAccount is ***************************************************/ /** - * @dev CMAccount upgrade event. Emitted when the CMAccount implementation is upgraded. + * @notice CMAccount upgrade event. Emitted when the CMAccount implementation is upgraded. */ event CMAccountUpgraded(address indexed oldImplementation, address indexed newImplementation); /** - * @dev Deposit event, emitted when there is a new deposit + * @notice Deposit event, emitted when there is a new deposit */ event Deposit(address indexed sender, uint256 amount); /** - * @dev Withdraw event, emitted when there is a new withdrawal + * @notice Withdraw event, emitted when there is a new withdrawal */ event Withdraw(address indexed receiver, uint256 amount); /** - * @dev Messenger bot added + * @notice Messenger bot added */ event MessengerBotAdded(address indexed bot); /** - * @dev Messenger bot removed + * @notice Messenger bot removed */ event MessengerBotRemoved(address indexed bot); @@ -178,32 +178,32 @@ contract CMAccount is ***************************************************/ /** - * @dev CMAccount implementation address does not match the one in the manager + * @notice CMAccount implementation address does not match the one in the manager */ error CMAccountImplementationMismatch(address latestImplementation, address newImplementation); /** - * @dev New implementation is the same as the current implementation, no update needed + * @notice New implementation is the same as the current implementation, no update needed */ error CMAccountNoUpgradeNeeded(address oldImplementation, address newImplementation); /** - * @dev Error to revert with if depositer is not allowed + * @notice Error to revert with if depositer is not allowed */ error DepositorNotAllowed(address sender); /** - * @dev Error to revert zero value deposits + * @notice Error to revert zero value deposits */ error ZeroValueDeposit(address sender); /** - * @dev Error to revert with if the prefund is not spent yet + * @notice Error to revert with if the prefund is not spent yet */ error PrefundNotSpentYet(uint256 withdrawableAmount, uint256 prefundLeft, uint256 amount); /** - * @dev Error to revert if transfer to zero address + * @notice Error to revert if transfer to zero address */ error TransferToZeroAddress(); @@ -251,7 +251,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Returns the CMAccountManager address. + * @notice Returns the CMAccountManager address. * * @return CMAccountManager address */ @@ -261,7 +261,7 @@ contract CMAccount is } /** - * @dev Returns the booking token address. + * @notice Returns the booking token address. * * @return BookingToken address */ @@ -271,7 +271,7 @@ contract CMAccount is } /** - * @dev Returns the prefund amount. + * @notice Returns the prefund amount. * * @return prefund amount */ @@ -285,14 +285,16 @@ contract CMAccount is ***************************************************/ /** - * @dev Authorizes the upgrade of the CMAccount.. + * @notice Authorizes the upgrade of the CMAccount. * * Reverts if the new implementation is the same as the old one. * * Reverts if the new implementation does not match the implementation address * in the manager. Only implementations registered at the manager are allowed. * - * Emits a {CMAccountUpgraded} event. + * @dev Emits a {CMAccountUpgraded} event. + * + * @param newImplementation The new implementation address */ function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) { // Get the implementation address from the manager @@ -313,14 +315,18 @@ contract CMAccount is } /** - * @dev Returns true if an address is authorized to sign cheques + * @notice Returns true if an address is authorized to sign cheques + * + * @param bot The bot's address */ function isBotAllowed(address bot) public view override returns (bool) { return hasRole(CHEQUE_OPERATOR_ROLE, bot); } /** - * @dev Verifies if the amount is withdrawable by checking if prefund is spent + * @notice Verifies if the amount is withdrawable by checking if prefund is spent + * + * @param amount The amount to check if it's withdrawable */ function _checkPrefundSpent(uint256 amount) private view { uint256 prefundAmount = getPrefundAmount(); @@ -344,7 +350,7 @@ contract CMAccount is } /** - * @dev Withdraw CAM from the CMAccount + * @notice Withdraw CAM from the CMAccount * * This function reverts if the amount is bigger then the prefund left to spend. This is to prevent * spam by forcing user to spend the full prefund for cheques, so they can not just create an account @@ -363,7 +369,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Mints booking token. + * @notice Mints booking token. * * @param reservedFor The account to reserve the token for * @param uri The URI of the token @@ -390,7 +396,7 @@ contract CMAccount is } /** - * @dev Buys booking token. + * @notice Buys booking token. * * @param tokenId The token id */ @@ -399,9 +405,9 @@ contract CMAccount is } /** - * @dev See {IERC721Receiver-onERC721Received}. + * @notice Always returns `IERC721Receiver.onERC721Received.selector`. * - * Always returns `IERC721Receiver.onERC721Received.selector`. + * @dev See {IERC721Receiver-onERC721Received}. */ function onERC721Received(address, address, uint256, bytes memory) public virtual returns (bytes4) { return this.onERC721Received.selector; @@ -412,7 +418,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Transfers ERC20 tokens. + * @notice Transfers ERC20 tokens. * * This function reverts if `to` is the zero address. * @@ -428,7 +434,7 @@ contract CMAccount is } /** - * @dev Transfers ERC721 tokens. + * @notice Transfers ERC721 tokens. * * This function reverts if `to` is the zero address. * @@ -448,12 +454,17 @@ contract CMAccount is ***************************************************/ /** - * @dev Add a service to the account + * @notice Adds a service to the account as a supported service. * * `serviceName` is defined as pkg + service name in protobuf. For example: * + * ```text * ┌────────────── pkg ─────────────┐ ┌───── service name ─────┐ * "cmp.services.accommodation.v1alpha.AccommodationSearchService") + * ``` + * + * @dev These services are coming from the Camino Messenger Protocol's protobuf + * definitions. * * @param serviceName Service name to add to the account as a supported service * @param fee Fee of the service in aCAM (wei in ETH terminology) @@ -469,7 +480,7 @@ contract CMAccount is } /** - * @dev Remove a service from the account by its name + * @notice Remove a service from the account by its name */ function removeService(string memory serviceName) public onlyRole(SERVICE_ADMIN_ROLE) { _removeService(getServiceHash(serviceName)); @@ -478,7 +489,7 @@ contract CMAccount is // FEE /** - * @dev Set the fee of a service by name + * @notice Set the fee of a service by name */ function setServiceFee(string memory serviceName, uint256 fee) public onlyRole(SERVICE_ADMIN_ROLE) { _setServiceFee(getServiceHash(serviceName), fee); @@ -487,7 +498,7 @@ contract CMAccount is // RESTRICTED RATE /** - * @dev Set the restricted rate of a service by name + * @notice Set the restricted rate of a service by name */ function setServiceRestrictedRate( string memory serviceName, @@ -499,7 +510,7 @@ contract CMAccount is // ALL CAPABILITIES /** - * @dev Set all capabilities for a service by name + * @notice Set all capabilities for a service by name */ function setServiceCapabilities( string memory serviceName, @@ -511,7 +522,7 @@ contract CMAccount is // SINGLE CAPABILITY /** - * @dev Add a single capability to the service by name + * @notice Add a single capability to the service by name */ function addServiceCapability( string memory serviceName, @@ -521,7 +532,7 @@ contract CMAccount is } /** - * @dev Remove a single capability from the service by name + * @notice Remove a single capability from the service by name */ function removeServiceCapability( string memory serviceName, @@ -531,7 +542,7 @@ contract CMAccount is } /** - * @dev Get service hash by name. Returns the keccak256 hash of the service name + * @notice Get service hash by name. Returns the keccak256 hash of the service name * from the account manager */ function getServiceHash(string memory serviceName) private view returns (bytes32 serviceHash) { @@ -543,7 +554,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Get all supported services. Return a list of service names and a list of service objects. + * @notice Get all supported services. Return a list of service names and a list of service objects. */ function getSupportedServices() public view returns (string[] memory serviceNames, Service[] memory services) { // Get all hashes and create a list with predefined length @@ -560,21 +571,21 @@ contract CMAccount is } /** - * @dev Get service fee by name. Overloading the getServiceFee function. + * @notice Get service fee by name. Overloading the getServiceFee function. */ function getServiceFee(string memory serviceName) public view returns (uint256 fee) { return getServiceFee(getServiceHash(serviceName)); } /** - * @dev Get service restricted rate by name. Overloading the getServiceRestrictedRate function. + * @notice Get service restricted rate by name. Overloading the getServiceRestrictedRate function. */ function getServiceRestrictedRate(string memory serviceName) public view returns (bool restrictedRate) { return getServiceRestrictedRate(getServiceHash(serviceName)); } /** - * @dev Get service capabilities by name. Overloading the getServiceCapabilities function. + * @notice Get service capabilities by name. Overloading the getServiceCapabilities function. */ function getServiceCapabilities(string memory serviceName) public view returns (string[] memory capabilities) { return getServiceCapabilities(getServiceHash(serviceName)); @@ -585,7 +596,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Adds wanted services. + * @notice Adds wanted services. * * @param serviceNames List of service names */ @@ -597,7 +608,7 @@ contract CMAccount is } /** - * @dev Removes wanted services. + * @notice Removes wanted services. * * @param serviceNames List of service names */ @@ -609,7 +620,7 @@ contract CMAccount is } /** - * @dev Get all wanted services. + * @notice Get all wanted services. * * @return serviceNames List of service names */ @@ -632,7 +643,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Sets if off-chain payment is supported. + * @notice Sets if off-chain payment is supported. * * @param _isSupported true if off-chain payment is supported */ @@ -641,7 +652,7 @@ contract CMAccount is } /** - * @dev Adds a supported payment token. + * @notice Adds a supported payment token. * * @param _supportedToken address of the token */ @@ -650,7 +661,7 @@ contract CMAccount is } /** - * @dev Removes a supported payment token. + * @notice Removes a supported payment token. * * @param _supportedToken address of the token */ @@ -663,7 +674,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Add public key with address + * @notice Add public key with address * * These public keys are intended to be used with for off-chain encryption of private booking data. * @@ -675,7 +686,7 @@ contract CMAccount is } /** - * @dev Remove public key by address + * @notice Remove public key by address */ function removePublicKey(address pubKeyAddress) public onlyRole(SERVICE_ADMIN_ROLE) { _removePublicKey(pubKeyAddress); @@ -686,7 +697,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Adds messenger bot with initial gas money. + * @notice Adds messenger bot with initial gas money. */ function addMessengerBot(address bot, uint256 gasMoney) public onlyRole(BOT_ADMIN_ROLE) { // Check if we can spend the gasMoney to send it to the bot @@ -704,7 +715,7 @@ contract CMAccount is } /** - * @dev Removes messenger bot by revoking the roles. + * @notice Removes messenger bot by revoking the roles. */ function removeMessengerBot(address bot) public onlyRole(BOT_ADMIN_ROLE) { _revokeRole(CHEQUE_OPERATOR_ROLE, bot); @@ -719,7 +730,7 @@ contract CMAccount is ***************************************************/ /** - * @dev Withdraw gas money. Requires the `GAS_WITHDRAWER_ROLE`. + * @notice Withdraw gas money. Requires the `GAS_WITHDRAWER_ROLE`. * * @param amount The amount to withdraw in aCAM (wei) */ @@ -729,7 +740,7 @@ contract CMAccount is } /** - * @dev Set gas money withdrawal parameters. Requires the `BOT_ADMIN_ROLE`. + * @notice Set gas money withdrawal parameters. Requires the `BOT_ADMIN_ROLE`. * * @param limit Amount of gas money to withdraw in wei per period * @param period Duration of the withdrawal period in seconds diff --git a/contracts/account/ChequeManager.sol b/contracts/account/ChequeManager.sol index 3e86db5..fe479eb 100644 --- a/contracts/account/ChequeManager.sol +++ b/contracts/account/ChequeManager.sol @@ -12,7 +12,7 @@ import "@openzeppelin/contracts/utils/Address.sol"; import { ICMAccountManager } from "../manager/ICMAccountManager.sol"; /** - * @dev ChequeManager manages, verifies, and cashes in the messenger cheques. + * @notice ChequeManager manages, verifies, and cashes in the messenger cheques. * * EIP712 Domain name & version: * DOMAIN_NAME = "CaminoMessenger" @@ -27,19 +27,23 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Pre-computed hash of the MessengerCheque type + * @notice Pre-computed hash of the MessengerCheque type * + * ``` * keccak256( * "MessengerCheque(address fromCMAccount,address toCMAccount,address toBot,uint256 counter,uint256 amount,uint256 createdAt,uint256 expiresAt)" * ); + * ``` */ bytes32 public constant MESSENGER_CHEQUE_TYPEHASH = 0x87b38f131334165ac2b361f08966c9fcff3a953fa7d9d9c2861b7f0b50445bcb; /** - * @dev Pre-computed hash of the EIP712Domain type + * @notice Pre-computed hash of the EIP712Domain type * + * ``` * keccak256("EIP712Domain(string name,string version,uint256 chainId)"); + * ``` */ bytes32 public constant DOMAIN_TYPEHASH = 0xc2f8787176b8ac6bf7215b4adcc1e069bf4ab82d9ab1df05a57a91d425935b6e; @@ -48,7 +52,7 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Struct representing a Messenger Cheque. + * @notice Struct representing a Messenger Cheque. */ struct MessengerCheque { address fromCMAccount; // CM Account that will pay the amount @@ -61,7 +65,7 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Struct for tracking the counter, amount and timestamps used for the last + * @notice Struct for tracking the counter, amount and timestamps used for the last * cash-in operation. */ struct LastCashIn { @@ -78,15 +82,15 @@ abstract contract ChequeManager is Initializable { /// @custom:storage-location erc7201:camino.messenger.storage.ChequeManager struct ChequeManagerStorage { /** - * @dev Mapping to track the cash-in details for each pair of fromBot and toBot addresses. + * @notice Mapping to track the cash-in details for each pair of fromBot and toBot addresses. */ mapping(address fromBot => mapping(address toBot => LastCashIn)) _lastCashIns; /** - * @dev Total amount of cheques that have been cashed in. + * @notice Total amount of cheques that have been cashed in. */ uint256 _totalChequePayments; /** - * @dev EIP712 Domain Separator used for signature verification. This variable includes + * @notice EIP712 Domain Separator used for signature verification. This variable includes * dynamic chain ID, hence it is not a constant. */ bytes32 _domainSeparator; @@ -107,7 +111,7 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Cheque verified event. Emitted when a cheque is verified. + * @notice Cheque verified event. Emitted when a cheque is verified. */ event ChequeVerified( address indexed fromCMAccount, @@ -120,7 +124,7 @@ abstract contract ChequeManager is Initializable { ); /** - * @dev Cash-in event. Emitted when a cheque is cashed in. + * @notice Cash-in event. Emitted when a cheque is cashed in. */ event ChequeCashedIn( address indexed fromBot, @@ -135,33 +139,33 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Invalid CM Account. Cheque's `fromCMAccount` has to be for `address(this)`. + * @notice Invalid CM Account. Cheque's `fromCMAccount` has to be for `address(this)`. */ error InvalidFromCMAccount(address fromCMAccount); /** - * @dev `toCMAccoun` address is not a registered CMAccount on the manager + * @notice `toCMAccount` address is not a registered CMAccount on the manager. */ error InvalidToCMAccount(address toCMAccount); /** - * @dev The signer is not allowed to sign cheques + * @notice The signer is not allowed to sign cheques */ error NotAllowedToSignCheques(address signer); /** - * @dev Invalid counter for the cheque. The counter on the cheque is not greater then the last + * @notice Invalid counter for the cheque. The counter on the cheque is not greater then the last * recorded counter. */ error InvalidCounter(uint256 chequeCounter, uint256 lastCounter); /** - * @dev Last recorded amount is lower than the cheque's amount. + * @notice Last recorded amount is lower than the cheque's amount. */ error InvalidAmount(uint256 chequeAmount, uint256 lastAmount); /** - * @dev The cheque is expired at the given timestamp + * @notice The cheque is expired at the given timestamp. */ error ChequeExpired(uint256 expiresAt); @@ -170,7 +174,7 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Initializes the contract, setting the domain separator with EIP712 domain type hash and + * @notice Initializes the contract, setting the domain separator with EIP712 domain type hash and * the domain. * * EIP712Domain { @@ -188,7 +192,7 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns the domain separator. + * @notice Returns the domain separator. */ function getDomainSeparator() public view returns (bytes32) { ChequeManagerStorage storage $ = _getChequeManagerStorage(); @@ -196,7 +200,7 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns the hash of the `MessengerCheque` encoded with + * @notice Returns the hash of the `MessengerCheque` encoded with * `MESSENGER_CHEQUE_TYPEHASH`. */ function hashMessengerCheque( @@ -224,7 +228,7 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns the hash of the typed data (cheque) with prefix and domain + * @notice Returns the hash of the typed data (cheque) with prefix and domain * separator. */ function hashTypedDataV4( @@ -247,7 +251,7 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns the signer for the given cheque and signature. Uses {ECDSA} library to + * @notice Returns the signer for the given cheque and signature. Uses {ECDSA} library to * recover the signer. */ function recoverSigner( @@ -266,12 +270,13 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns signer and payment amount if the signature is valid for the + * @notice Returns signer and payment amount if the signature is valid for the * given cheque, the signer is an allowed bot, cheque counter and amounts are * valid according to last cash ins. * * Please be aware that `cheque.amount < paymentAmount` for a valid cheque as - * long as the last amount is lower than the cheque amount. + * long as the last amount is lower than the cheque amount. Only the difference + * between the cheque amount and the last recorded amount is paid. */ function verifyCheque( address fromCMAccount, @@ -337,9 +342,8 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Cash in a cheque by verifying it and paying the difference between the - * cheque amount - * and the last recorded amount for the signer and `toBot` pair. + * @notice Cash in a cheque by verifying it and paying the difference between the + * cheque amount and the last recorded amount for the signer and `toBot` pair. * * A percentage of the amount is also paid to the developer wallet. * @@ -404,12 +408,17 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns last cash-in details for given `fromBot` & `toBot` pair. + * @notice Returns last cash-in details for given `fromBot` & `toBot` pair. * * @param fromBot The address of the bot that sent the cheque. * @param toBot The address of the bot that received the cheque. * * Returns (lastCounter, lastAmount, lastCreatedAt, lastExpiresAt) + * + * @return lastCounter The last counter of the cheque. + * @return lastAmount The last amount of the cheque. + * @return lastCreatedAt The last creation timestamp of the cheque. + * @return lastExpiresAt The last expiration timestamp of the cheque. */ function getLastCashIn( address fromBot, @@ -421,7 +430,14 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Sets last cash-in for given `fromBot`, `toBot` pair. + * @notice Sets last cash-in for given `fromBot`, `toBot` pair. + * + * @param fromBot The address of the bot that sent the cheque. + * @param toBot The address of the bot that received the cheque. + * @param counter The counter of the cheque. + * @param amount The amount of the cheque. + * @param createdAt The creation timestamp of the cheque. + * @param expiresAt The expiration timestamp of the cheque. */ function setLastCashIn( address fromBot, @@ -436,7 +452,9 @@ abstract contract ChequeManager is Initializable { } /** - * @dev Returns total cheque payments. This is the sum of all cashed in cheques. + * @notice Returns total cheque payments. This is the sum of all cashed in cheques. + * + * @return totalChequePayments The total cheque payments made. */ function getTotalChequePayments() public view returns (uint256) { ChequeManagerStorage storage $ = _getChequeManagerStorage(); @@ -448,13 +466,13 @@ abstract contract ChequeManager is Initializable { ***************************************************/ /** - * @dev Abstract function to check if a bot is allowed to sign cheques. This + * @notice Abstract function to check if a bot is allowed to sign cheques. This * must be implemented by the inheriting contract. */ function isBotAllowed(address bot) public view virtual returns (bool); /** - * @dev Abstract function to get the manager address. This must be implemented + * @notice Abstract function to get the manager address. This must be implemented * by the inheriting contract. */ function getManagerAddress() public view virtual returns (address); diff --git a/contracts/account/GasMoneyManager.sol b/contracts/account/GasMoneyManager.sol index 71856a9..ae839dc 100644 --- a/contracts/account/GasMoneyManager.sol +++ b/contracts/account/GasMoneyManager.sol @@ -9,7 +9,7 @@ import "@openzeppelin/contracts/utils/Address.sol"; /** * @title GasMoneyManager - * @dev GasMoneyManager manages gas money withdrawals for a {CMAccount}. + * @notice GasMoneyManager manages gas money withdrawals for a {CMAccount}. * * Gas money withdrawals are restricted to a withdrawal limit and period. */ @@ -43,7 +43,7 @@ abstract contract GasMoneyManager is Initializable { ***************************************************/ /** - * @dev Gas money withdrawal event + * @notice Gas money withdrawal event * * @param withdrawer the address of the withdrawer * @param amount the amount withdrawn @@ -51,7 +51,7 @@ abstract contract GasMoneyManager is Initializable { event GasMoneyWithdrawal(address indexed withdrawer, uint256 amount); /** - * @dev Gas money withdrawal limit and period updated event + * @notice Gas money withdrawal limit and period updated event * * @param limit the withdrawal limit for the period * @param period the withdrawal period in seconds @@ -80,7 +80,7 @@ abstract contract GasMoneyManager is Initializable { ***************************************************/ /** - * @dev Withdraws gas money. + * @notice Withdraws gas money. * * This functions is intended to be called by the bot to withdraw gas money. * Inheriting contract should restrict who can call this with a public @@ -120,7 +120,7 @@ abstract contract GasMoneyManager is Initializable { } /** - * @dev Sets the gas money withdrawal limit and period. + * @notice Sets the gas money withdrawal limit and period. * * @param limit the withdrawal limit for the period * @param period the withdrawal period in seconds @@ -134,7 +134,7 @@ abstract contract GasMoneyManager is Initializable { } /** - * @dev Returns the gas money withdrawal restrictions. + * @notice Returns the gas money withdrawal restrictions. * * @return withdrawalLimit * @return withdrawalPeriod @@ -145,7 +145,7 @@ abstract contract GasMoneyManager is Initializable { } /** - * @dev Returns the gas money withdrawal details for an account. + * @notice Returns the gas money withdrawal details for an account. * * @param account address of the account * @return periodStart timestamp of the withdrawal period start diff --git a/contracts/booking-token/BookingToken.sol b/contracts/booking-token/BookingToken.sol index b3c4677..9ac7714 100644 --- a/contracts/booking-token/BookingToken.sol +++ b/contracts/booking-token/BookingToken.sol @@ -49,12 +49,12 @@ contract BookingToken is ***************************************************/ /** - * @dev Upgrader role can upgrade the contract to a new implementation. + * @notice Upgrader role can upgrade the contract to a new implementation. */ bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE"); /** - * @dev This role can set the mininum allowed expiration timestamp difference. + * @notice This role can set the mininum allowed expiration timestamp difference. */ bytes32 public constant MIN_EXPIRATION_ADMIN_ROLE = keccak256("MIN_EXPIRATION_ADMIN_ROLE"); @@ -98,7 +98,7 @@ contract BookingToken is ***************************************************/ /** - * @dev Event emitted when a token is reserved + * @notice Event emitted when a token is reserved. * * @param tokenId token id * @param reservedFor reserved for address @@ -117,7 +117,7 @@ contract BookingToken is ); /** - * @dev Event emitted when a token is bought + * @notice Event emitted when a token is bought. * * @param tokenId token id * @param buyer buyer address @@ -129,20 +129,20 @@ contract BookingToken is ***************************************************/ /** - * @dev Error for expiration timestamp too soon. It must be at least - * `_minExpirationTimestampDiff` seconds in the future + * @notice Error for expiration timestamp too soon. It must be at least + * `_minExpirationTimestampDiff` seconds in the future. */ error ExpirationTimestampTooSoon(uint256 expirationTimestamp, uint256 minExpirationTimestampDiff); /** - * @dev Address is not a CM Account + * @notice Address is not a CM Account. * * @param account account address */ error NotCMAccount(address account); /** - * @dev ReservedFor and buyer mismatch + * @notice ReservedFor and buyer mismatch. * * @param reservedFor reserved for address * @param buyer buyer address @@ -150,7 +150,7 @@ contract BookingToken is error ReservationMismatch(address reservedFor, address buyer); /** - * @dev Reservation expired + * @notice Reservation expired. * * @param tokenId token id * @param expirationTimestamp expiration timestamp @@ -158,7 +158,7 @@ contract BookingToken is error ReservationExpired(uint256 tokenId, uint256 expirationTimestamp); /** - * @dev Incorrect price + * @notice Incorrect price. * * @param price price of the token * @param reservationPrice reservation price @@ -166,7 +166,7 @@ contract BookingToken is error IncorrectPrice(uint256 price, uint256 reservationPrice); /** - * @dev Supplier is not the owner + * @notice Supplier is not the owner. * * @param tokenId token id * @param supplier supplier address @@ -174,7 +174,7 @@ contract BookingToken is error SupplierIsNotOwner(uint256 tokenId, address supplier); /** - * @dev Token is reserved and can not be transferred + * @notice Token is reserved and can not be transferred. * * @param tokenId token id * @param reservedFor reserved for address @@ -182,7 +182,7 @@ contract BookingToken is error TokenIsReserved(uint256 tokenId, address reservedFor); /** - * @dev Insufficient allowance to transfer the ERC20 token to the supplier + * @notice Insufficient allowance to transfer the ERC20 token to the supplier. * * @param sender msg.sender * @param paymentToken payment token address @@ -196,7 +196,7 @@ contract BookingToken is ***************************************************/ /** - * @dev Only CMAccount modifier + * @notice Only CMAccount modifier. */ modifier onlyCMAccount(address account) { requireCMAccount(account); @@ -223,7 +223,10 @@ contract BookingToken is $._minExpirationTimestampDiff = 60; } - // Function to authorize an upgrade for UUPS proxy + /** + * @notice Function to authorize an upgrade for UUPS proxy. + */ + function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) {} /*************************************************** @@ -231,7 +234,7 @@ contract BookingToken is ***************************************************/ /** - * @dev Mints a new token with a reservation for a specific address. + * @notice Mints a new token with a reservation for a specific address. * * @param reservedFor The CM Account address that can buy the token * @param uri The URI of the token @@ -272,7 +275,7 @@ contract BookingToken is } /** - * @dev Buys a reserved token. The reservation must be for the message sender. + * @notice Buys a reserved token. The reservation must be for the message sender. * * Also the message sender should set allowance for the payment token to this * contract to at least the reservation price. (only for ERC20 tokens) @@ -342,7 +345,7 @@ contract BookingToken is } /** - * @dev Reserve a token for a specific address with an expiration timestamp + * @notice Reserve a token for a specific address with an expiration timestamp */ function _reserve( uint256 tokenId, @@ -357,7 +360,7 @@ contract BookingToken is } /** - * @dev Check if the token is transferable + * @notice Check if the token is transferable */ function checkTransferable(uint256 tokenId) internal { BookingTokenStorage storage $ = _getBookingTokenStorage(); @@ -379,16 +382,17 @@ contract BookingToken is } /** - * @dev Checks if an address is a CM Account. + * @notice Checks if an address is a CM Account. * * @param account The address to check + * @return true if the address is a CM Account */ function isCMAccount(address account) public view returns (bool) { return ICMAccountManager(getManagerAddress()).isCMAccount(account); } /** - * @dev Checks if the address is a CM Account and reverts if not. + * @notice Checks if the address is a CM Account and reverts if not. * * @param account The address to check */ @@ -399,7 +403,7 @@ contract BookingToken is } /** - * @dev Sets for the manager address + * @notice Sets for the manager address. * * @param manager The address of the manager */ @@ -409,7 +413,7 @@ contract BookingToken is } /** - * @dev Returns for the manager address. + * @notice Returns for the manager address. */ function getManagerAddress() public view returns (address) { BookingTokenStorage storage $ = _getBookingTokenStorage(); @@ -417,7 +421,7 @@ contract BookingToken is } /** - * @dev Sets minimum expiration timestamp difference in seconds. + * @notice Sets minimum expiration timestamp difference in seconds. * * @param minExpirationTimestampDiff Minimum expiration timestamp difference in seconds */ @@ -429,7 +433,7 @@ contract BookingToken is } /** - * @dev Returns minimum expiration timestamp difference in seconds + * @notice Returns minimum expiration timestamp difference in seconds. */ function getMinExpirationTimestampDiff() public view returns (uint256) { BookingTokenStorage storage $ = _getBookingTokenStorage(); @@ -437,7 +441,7 @@ contract BookingToken is } /** - * @dev Returns the token reservation price for a specific token. + * @notice Returns the token reservation price for a specific token. * * @param tokenId The token id */ @@ -451,7 +455,7 @@ contract BookingToken is ***************************************************/ /** - * @dev Override transferFrom to check if token is reserved. It reverts if + * @notice Override transferFrom to check if token is reserved. It reverts if * the token is reserved. */ function transferFrom(address from, address to, uint256 tokenId) public override(ERC721Upgradeable, IERC721) { @@ -461,7 +465,7 @@ contract BookingToken is } /** - * @dev Override safeTransferFrom to check if token is reserved. It reverts if + * @notice Override safeTransferFrom to check if token is reserved. It reverts if * the token is reserved. */ function safeTransferFrom( diff --git a/contracts/booking-token/BookingTokenOperator.sol b/contracts/booking-token/BookingTokenOperator.sol index 0c5ae3c..dea54c8 100644 --- a/contracts/booking-token/BookingTokenOperator.sol +++ b/contracts/booking-token/BookingTokenOperator.sol @@ -8,7 +8,7 @@ import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; /** * @title BookingTokenOperator - * @dev Booking token operator contract is used by the {CMAccount} contract to mint + * @notice Booking token operator contract is used by the {CMAccount} contract to mint * and buy booking tokens. * * We made this a library so that we can use it in the {CMAccount} contract without diff --git a/contracts/manager/CMAccountManager.sol b/contracts/manager/CMAccountManager.sol index f406334..2c16aa2 100644 --- a/contracts/manager/CMAccountManager.sol +++ b/contracts/manager/CMAccountManager.sol @@ -58,18 +58,18 @@ contract CMAccountManager is using Address for address payable; /** - * @dev Pauser role can pause the contract. Currently this only affects the + * @notice Pauser role can pause the contract. Currently this only affects the * creation of CM Accounts. When paused, account creation is stopped. */ bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE"); /** - * @dev Upgrader role can upgrade the contract to a new implementation. + * @notice Upgrader role can upgrade the contract to a new implementation. */ bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE"); /** - * @dev Versioner role can set new {CMAccount} implementation address. When a + * @notice Versioner role can set new {CMAccount} implementation address. When a * new implementation address is set, it is used for the new {CMAccount} * creations. * @@ -80,31 +80,31 @@ contract CMAccountManager is bytes32 public constant VERSIONER_ROLE = keccak256("VERSIONER_ROLE"); /** - * @dev Fee admin role can set the developer fee basis points which used for + * @notice Fee admin role can set the developer fee basis points which used for * calculating the developer fee that is cut from the cheque payments. */ bytes32 public constant FEE_ADMIN_ROLE = keccak256("FEE_ADMIN_ROLE"); /** - * @dev Developer wallet admin role can set the developer wallet address + * @notice Developer wallet admin role can set the developer wallet address * which is used to receive the developer fee. */ bytes32 public constant DEVELOPER_WALLET_ADMIN_ROLE = keccak256("DEVELOPER_WALLET_ADMIN_ROLE"); /** - * @dev Prefund admin role can set the mandatory prefund amount for {CMAccount} + * @notice Prefund admin role can set the mandatory prefund amount for {CMAccount} * contracts. */ bytes32 public constant PREFUND_ADMIN_ROLE = keccak256("PREFUND_ADMIN_ROLE"); /** - * @dev Service registry admin role can add and remove services to the service + * @notice Service registry admin role can add and remove services to the service * registry mapping. Implemented by {ServiceRegistry} contract. */ bytes32 public constant SERVICE_REGISTRY_ADMIN_ROLE = keccak256("SERVICE_REGISTRY_ADMIN_ROLE"); /** - * @dev This role is granted to the created CM Accounts. It is used to keep + * @notice This role is granted to the created CM Accounts. It is used to keep * an enumerable list of CM Accounts. */ bytes32 public constant CMACCOUNT_ROLE = keccak256("CMACCOUNT_ROLE"); @@ -114,7 +114,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev CMAccount info struct, to keep track of created CM Accounts and their + * @notice CMAccount info struct, to keep track of created CM Accounts and their * creators. */ struct CMAccountInfo { @@ -125,12 +125,12 @@ contract CMAccountManager is /// @custom:storage-location erc7201:camino.messenger.storage.CMAccountManager struct CMAccountManagerStorage { /** - * @dev CM Account implementation address to be used by the CMAccount contract to resctrict + * @dev CM Account implementation address to be used by the CMAccount contract to restrict * the implementation address for the UUPS proxies. */ address _latestAccountImplementation; /** - * @dev Prefund amount + * @dev Prefund amount. */ uint256 _prefundAmount; /** @@ -138,7 +138,7 @@ contract CMAccountManager is */ address _developerWallet; /** - * @dev Developer fee basis points + * @dev Developer fee basis points. * * A basis point (bp) is one hundredth of 1 percentage point. * @@ -148,11 +148,11 @@ contract CMAccountManager is */ uint256 _developerFeeBp; /** - * @dev BookingToken address + * @dev BookingToken address. */ address _bookingToken; /** - * @dev CMAccount info mapping to track if an address is a CMAccount and initial creators + * @dev CMAccount info mapping to track if an address is a CMAccount and initial creators. */ mapping(address account => CMAccountInfo) _cmAccountInfo; } @@ -172,34 +172,34 @@ contract CMAccountManager is ***************************************************/ /** - * @dev CM Account created + * @notice CM Account created event. * @param account The address of the new CMAccount */ event CMAccountCreated(address indexed account); /** - * @dev CM Account implementation address updated + * @notice CM Account implementation address updated event. * @param oldImplementation The old implementation address * @param newImplementation The new implementation address */ event CMAccountImplementationUpdated(address indexed oldImplementation, address indexed newImplementation); /** - * @dev Developer wallet address updated + * @notice Developer wallet address updated event. * @param oldDeveloperWallet The old developer wallet address * @param newDeveloperWallet The new developer wallet address */ event DeveloperWalletUpdated(address indexed oldDeveloperWallet, address indexed newDeveloperWallet); /** - * @dev Developer fee basis points updated + * @notice Developer fee basis points updated event. * @param oldDeveloperFeeBp The old developer fee basis points * @param newDeveloperFeeBp The new developer fee basis points */ event DeveloperFeeBpUpdated(uint256 indexed oldDeveloperFeeBp, uint256 indexed newDeveloperFeeBp); /** - * @dev Booking token address updated + * @notice Booking token address updated event. * @param oldBookingToken The old booking token address * @param newBookingToken The new booking token address */ @@ -210,31 +210,31 @@ contract CMAccountManager is ***************************************************/ /** - * @dev The implementation of the CMAccount is invalid + * @notice The implementation of the CMAccount is invalid. * @param implementation The implementation address of the CMAccount */ error CMAccountInvalidImplementation(address implementation); /** - * @dev The admin address is invalid + * @notice The admin address is invalid. * @param admin The admin address */ error CMAccountInvalidAdmin(address admin); /** - * @dev Invalid developer address + * @notice Invalid developer address. * @param developerWallet The developer wallet address */ error InvalidDeveloperWallet(address developerWallet); /** - * @dev Invalid booking token address + * @notice Invalid booking token address. * @param bookingToken The booking token address */ error InvalidBookingTokenAddress(address bookingToken); /** - * @dev Incorrect pre fund amount + * @notice Incorrect pre fund amount. * @param expected The expected pre fund amount */ error IncorrectPrefundAmount(uint256 expected, uint256 sended); @@ -275,7 +275,7 @@ contract CMAccountManager is } /** - * @dev Pauses the CMAccountManager contract. Currently this only affects the + * @notice Pauses the CMAccountManager contract. Currently this only affects the * creation of CMAccount. When paused, account creation is stopped. */ function pause() public onlyRole(PAUSER_ROLE) { @@ -283,14 +283,14 @@ contract CMAccountManager is } /** - * @dev Unpauses the CMAccountManager contract. + * @notice Unpauses the CMAccountManager contract. */ function unpause() public onlyRole(PAUSER_ROLE) { _unpause(); } /** - * @dev Authorization for the CMAccountManager contract upgrade. + * @notice Authorization for the CMAccountManager contract upgrade. */ function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) {} @@ -299,7 +299,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Creates CMAccount by deploying a ERC1967Proxy with the CMAccount + * @notice Creates CMAccount by deploying a ERC1967Proxy with the CMAccount * implementation from the manager. * * Because this function is deploying a contract, it reverts if the caller is @@ -307,7 +307,7 @@ contract CMAccountManager is * * Caller must send the pre-fund amount with the transaction. * - * Emits a {CMAccountCreated} event. + * @dev Emits a {CMAccountCreated} event. */ function createCMAccount( address admin, @@ -317,7 +317,7 @@ contract CMAccountManager is } /** - * @dev Private function to create CMAccount + * @notice Private function to create a `CMAccount`. */ function _createCMAccount(address admin, address upgrader) private returns (address) { // Checks @@ -368,7 +368,7 @@ contract CMAccountManager is } /** - * @dev Returns the given account's creator + * @notice Returns the given account's creator. * @param account The account address */ function getCMAccountCreator(address account) public view returns (address) { @@ -377,7 +377,7 @@ contract CMAccountManager is } /** - * @dev Check if an address is CMAccount created by the manager + * @notice Check if an address is CMAccount created by the manager. * @param account The account address to check */ function isCMAccount(address account) public view returns (bool) { @@ -390,7 +390,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Returns the CMAccount implementation address + * @notice Returns the CMAccount implementation address. */ function getAccountImplementation() public view returns (address) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -398,7 +398,7 @@ contract CMAccountManager is } /** - * @dev Set a new CMAccount implementation address + * @notice Set a new CMAccount implementation address. * @param newImplementation The new implementation address */ function setAccountImplementation(address newImplementation) public onlyRole(VERSIONER_ROLE) { @@ -421,7 +421,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Get prefund amount + * @notice Returns the prefund amount. */ function getPrefundAmount() public view returns (uint256) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -429,7 +429,7 @@ contract CMAccountManager is } /** - * @dev Set pre fund amount + * @notice Sets the prefund amount. */ function setPrefundAmount(uint256 newPrefundAmount) public onlyRole(PREFUND_ADMIN_ROLE) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -441,7 +441,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Returns the booking token address. + * @notice Returns the booking token address. */ function getBookingTokenAddress() public view returns (address) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -449,7 +449,7 @@ contract CMAccountManager is } /** - * @dev Sets booking token address. + * @notice Sets booking token address. */ function setBookingTokenAddress(address token) public onlyRole(VERSIONER_ROLE) { if (token.code.length == 0) { @@ -471,7 +471,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Returns developer wallet address. + * @notice Returns developer wallet address. */ function getDeveloperWallet() public view returns (address developerWallet) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -479,7 +479,7 @@ contract CMAccountManager is } /** - * @dev Sets developer wallet address. + * @notice Sets developer wallet address. */ function setDeveloperWallet(address developerWallet) public onlyRole(DEVELOPER_WALLET_ADMIN_ROLE) { if (developerWallet == address(0)) { @@ -497,7 +497,7 @@ contract CMAccountManager is } /** - * @dev Returns developer fee in basis points. + * @notice Returns developer fee in basis points. */ function getDeveloperFeeBp() public view returns (uint256 developerFeeBp) { CMAccountManagerStorage storage $ = _getCMAccountManagerStorage(); @@ -505,7 +505,7 @@ contract CMAccountManager is } /** - * @dev Sets developer fee in basis points. + * @notice Sets developer fee in basis points. * * A basis point (bp) is one hundredth of 1 percentage point. * @@ -529,7 +529,7 @@ contract CMAccountManager is ***************************************************/ /** - * @dev Registers a given service name. CM Accounts can only register services + * @notice Registers a given service name. CM Accounts can only register services * if they are also registered in the service registry on the manager contract. * * @param serviceName Name of the service @@ -539,7 +539,7 @@ contract CMAccountManager is } /** - * @dev Unregisters a given service name. CM Accounts will not be able to register + * @notice Unregisters a given service name. CM Accounts will not be able to register * the service anymore. * * @param serviceName Name of the service diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..fd93fe1 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,2887 @@ +# Solidity API + +## CMAccount + +A CM Account manages funds, minting/buying of booking tokens, provided +or wanted services, and multiple bots for distributors and suppliers on +Camino Messenger ecosystem. + +Registering bots is done by role based access control. Bot's with +`CHEQUE_OPERATOR_ROLE` can issue cheques to paid by the {CMAccount} contract. +Bot can also have `GAS_WITHDRAWER_ROLE` and `BOOKING_OPERATOR_ROLE`. + +`GAS_WITHDRAWER_ROLE` enables a bot to withdraw native coins (CAM) from the +contract to be used as gas money. This restricted with a `limit` +(wei/aCAM) and `period` (seconds) by the `BOT_ADMIN_ROLE`. Default starting +values are 10 CAM per 24 hours. + +`BOOKING_OPERATOR_ROLE` enables a bot to mint and buy Booking Tokens by +calling the corresponding functions on the {BookingToken} contract. The buy +operation pays the price of the Booking Token with the funds on the +{CMAccount} contract. + +_This contract uses UUPS style upgradeability. The authorization function +`_authorizeUpgrade(address)` can be called by the `UPGRADER_ROLE` and is +restricted to only upgrade to the implementation address registered on the +{CMAccountManager} contract._ + +### UPGRADER_ROLE + +```solidity +bytes32 UPGRADER_ROLE +``` + +Upgrader role can upgrade the contract to a new implementation. + +### BOT_ADMIN_ROLE + +```solidity +bytes32 BOT_ADMIN_ROLE +``` + +Bot admin role can add & remove bots and set gas money withdrawal +parameters. + +### CHEQUE_OPERATOR_ROLE + +```solidity +bytes32 CHEQUE_OPERATOR_ROLE +``` + +Cheque operator role can issue cheques to be paid by this CMAccount +contract. + +### GAS_WITHDRAWER_ROLE + +```solidity +bytes32 GAS_WITHDRAWER_ROLE +``` + +Gas withdrawer role can withdraw gas money from the contract. This is +intended to be used by the bots and is granted when `addMessengerBot` is +called. + +### WITHDRAWER_ROLE + +```solidity +bytes32 WITHDRAWER_ROLE +``` + +Withdrawer role can withdraw funds from the contract. + +### BOOKING_OPERATOR_ROLE + +```solidity +bytes32 BOOKING_OPERATOR_ROLE +``` + +Booking operator role can mint and buy booking tokens using the +functions on this contract. This is generally used by the bots. The +price for the booking token is paid by this contract. + +### SERVICE_ADMIN_ROLE + +```solidity +bytes32 SERVICE_ADMIN_ROLE +``` + +Service admin role can add & remove supported & wanted services. + +### CMAccountStorage + +```solidity +struct CMAccountStorage { + address _manager; + address _bookingToken; + uint256 _prefundAmount; +} +``` + +### CMAccountUpgraded + +```solidity +event CMAccountUpgraded(address oldImplementation, address newImplementation) +``` + +CMAccount upgrade event. Emitted when the CMAccount implementation is upgraded. + +### Deposit + +```solidity +event Deposit(address sender, uint256 amount) +``` + +Deposit event, emitted when there is a new deposit + +### Withdraw + +```solidity +event Withdraw(address receiver, uint256 amount) +``` + +Withdraw event, emitted when there is a new withdrawal + +### MessengerBotAdded + +```solidity +event MessengerBotAdded(address bot) +``` + +Messenger bot added + +### MessengerBotRemoved + +```solidity +event MessengerBotRemoved(address bot) +``` + +Messenger bot removed + +### CMAccountImplementationMismatch + +```solidity +error CMAccountImplementationMismatch(address latestImplementation, address newImplementation) +``` + +CMAccount implementation address does not match the one in the manager + +### CMAccountNoUpgradeNeeded + +```solidity +error CMAccountNoUpgradeNeeded(address oldImplementation, address newImplementation) +``` + +New implementation is the same as the current implementation, no update needed + +### DepositorNotAllowed + +```solidity +error DepositorNotAllowed(address sender) +``` + +Error to revert with if depositer is not allowed + +### ZeroValueDeposit + +```solidity +error ZeroValueDeposit(address sender) +``` + +Error to revert zero value deposits + +### PrefundNotSpentYet + +```solidity +error PrefundNotSpentYet(uint256 withdrawableAmount, uint256 prefundLeft, uint256 amount) +``` + +Error to revert with if the prefund is not spent yet + +### TransferToZeroAddress + +```solidity +error TransferToZeroAddress() +``` + +Error to revert if transfer to zero address + +### constructor + +```solidity +constructor() public +``` + +### initialize + +```solidity +function initialize(address manager, address bookingToken, uint256 prefundAmount, address defaultAdmin, address upgrader) public +``` + +### receive + +```solidity +receive() external payable +``` + +### getManagerAddress + +```solidity +function getManagerAddress() public view returns (address) +``` + +Returns the CMAccountManager address. + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | ------------------------ | +| [0] | address | CMAccountManager address | + +### getBookingTokenAddress + +```solidity +function getBookingTokenAddress() public view returns (address) +``` + +Returns the booking token address. + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | -------------------- | +| [0] | address | BookingToken address | + +### getPrefundAmount + +```solidity +function getPrefundAmount() public view returns (uint256) +``` + +Returns the prefund amount. + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | -------------- | +| [0] | uint256 | prefund amount | + +### \_authorizeUpgrade + +```solidity +function _authorizeUpgrade(address newImplementation) internal +``` + +Authorizes the upgrade of the CMAccount. + +Reverts if the new implementation is the same as the old one. + +Reverts if the new implementation does not match the implementation address +in the manager. Only implementations registered at the manager are allowed. + +_Emits a {CMAccountUpgraded} event._ + +#### Parameters + +| Name | Type | Description | +| ----------------- | ------- | ------------------------------ | +| newImplementation | address | The new implementation address | + +### isBotAllowed + +```solidity +function isBotAllowed(address bot) public view returns (bool) +``` + +Returns true if an address is authorized to sign cheques + +#### Parameters + +| Name | Type | Description | +| ---- | ------- | ----------------- | +| bot | address | The bot's address | + +### withdraw + +```solidity +function withdraw(address payable recipient, uint256 amount) external +``` + +Withdraw CAM from the CMAccount + +This function reverts if the amount is bigger then the prefund left to spend. This is to prevent +spam by forcing user to spend the full prefund for cheques, so they can not just create an account +and withdraw the prefund. + +### mintBookingToken + +```solidity +function mintBookingToken(address reservedFor, string uri, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) external +``` + +Mints booking token. + +#### Parameters + +| Name | Type | Description | +| ------------------- | --------------- | -------------------------------------------- | +| reservedFor | address | The account to reserve the token for | +| uri | string | The URI of the token | +| expirationTimestamp | uint256 | The expiration timestamp | +| price | uint256 | The price of the token | +| paymentToken | contract IERC20 | The payment token, if address(0) then native | + +### buyBookingToken + +```solidity +function buyBookingToken(uint256 tokenId) external +``` + +Buys booking token. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------ | +| tokenId | uint256 | The token id | + +### onERC721Received + +```solidity +function onERC721Received(address, address, uint256, bytes) public virtual returns (bytes4) +``` + +Always returns `IERC721Receiver.onERC721Received.selector`. + +_See {IERC721Receiver-onERC721Received}._ + +### transferERC20 + +```solidity +function transferERC20(contract IERC20 token, address to, uint256 amount) external +``` + +Transfers ERC20 tokens. + +This function reverts if `to` is the zero address. + +#### Parameters + +| Name | Type | Description | +| ------ | --------------- | ------------------------------------- | +| token | contract IERC20 | The ERC20 token | +| to | address | The address to transfer the tokens to | +| amount | uint256 | The amount of tokens to transfer | + +### transferERC721 + +```solidity +function transferERC721(contract IERC721 token, address to, uint256 tokenId) external +``` + +Transfers ERC721 tokens. + +This function reverts if `to` is the zero address. + +#### Parameters + +| Name | Type | Description | +| ------- | ---------------- | ------------------------------------- | +| token | contract IERC721 | The ERC721 token | +| to | address | The address to transfer the tokens to | +| tokenId | uint256 | The token id of the token | + +### addService + +```solidity +function addService(string serviceName, uint256 fee, bool restrictedRate, string[] capabilities) public +``` + +Adds a service to the account as a supported service. + +`serviceName` is defined as pkg + service name in protobuf. For example: + +```text + ┌────────────── pkg ─────────────┐ ┌───── service name ─────┐ +"cmp.services.accommodation.v1alpha.AccommodationSearchService") +``` + +_These services are coming from the Camino Messenger Protocol's protobuf +definitions._ + +#### Parameters + +| Name | Type | Description | +| -------------- | -------- | --------------------------------------------------------- | +| serviceName | string | Service name to add to the account as a supported service | +| fee | uint256 | Fee of the service in aCAM (wei in ETH terminology) | +| restrictedRate | bool | | +| capabilities | string[] | Capabilities of the service (if any, optional) | + +### removeService + +```solidity +function removeService(string serviceName) public +``` + +Remove a service from the account by its name + +### setServiceFee + +```solidity +function setServiceFee(string serviceName, uint256 fee) public +``` + +Set the fee of a service by name + +### setServiceRestrictedRate + +```solidity +function setServiceRestrictedRate(string serviceName, bool restrictedRate) public +``` + +Set the restricted rate of a service by name + +### setServiceCapabilities + +```solidity +function setServiceCapabilities(string serviceName, string[] capabilities) public +``` + +Set all capabilities for a service by name + +### addServiceCapability + +```solidity +function addServiceCapability(string serviceName, string capability) public +``` + +Add a single capability to the service by name + +### removeServiceCapability + +```solidity +function removeServiceCapability(string serviceName, string capability) public +``` + +Remove a single capability from the service by name + +### getSupportedServices + +```solidity +function getSupportedServices() public view returns (string[] serviceNames, struct PartnerConfiguration.Service[] services) +``` + +Get all supported services. Return a list of service names and a list of service objects. + +### getServiceFee + +```solidity +function getServiceFee(string serviceName) public view returns (uint256 fee) +``` + +Get service fee by name. Overloading the getServiceFee function. + +### getServiceRestrictedRate + +```solidity +function getServiceRestrictedRate(string serviceName) public view returns (bool restrictedRate) +``` + +Get service restricted rate by name. Overloading the getServiceRestrictedRate function. + +### getServiceCapabilities + +```solidity +function getServiceCapabilities(string serviceName) public view returns (string[] capabilities) +``` + +Get service capabilities by name. Overloading the getServiceCapabilities function. + +### addWantedServices + +```solidity +function addWantedServices(string[] serviceNames) public +``` + +Adds wanted services. + +#### Parameters + +| Name | Type | Description | +| ------------ | -------- | --------------------- | +| serviceNames | string[] | List of service names | + +### removeWantedServices + +```solidity +function removeWantedServices(string[] serviceNames) public +``` + +Removes wanted services. + +#### Parameters + +| Name | Type | Description | +| ------------ | -------- | --------------------- | +| serviceNames | string[] | List of service names | + +### getWantedServices + +```solidity +function getWantedServices() public view returns (string[] serviceNames) +``` + +Get all wanted services. + +#### Return Values + +| Name | Type | Description | +| ------------ | -------- | --------------------- | +| serviceNames | string[] | List of service names | + +### setOffChainPaymentSupported + +```solidity +function setOffChainPaymentSupported(bool _isSupported) public +``` + +Sets if off-chain payment is supported. + +#### Parameters + +| Name | Type | Description | +| ------------- | ---- | -------------------------------------- | +| \_isSupported | bool | true if off-chain payment is supported | + +### addSupportedToken + +```solidity +function addSupportedToken(address _supportedToken) public +``` + +Adds a supported payment token. + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | -------------------- | +| \_supportedToken | address | address of the token | + +### removeSupportedToken + +```solidity +function removeSupportedToken(address _supportedToken) public +``` + +Removes a supported payment token. + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | -------------------- | +| \_supportedToken | address | address of the token | + +### addPublicKey + +```solidity +function addPublicKey(address pubKeyAddress, bytes data) public +``` + +Add public key with address + +These public keys are intended to be used with for off-chain encryption of private booking data. + +#### Parameters + +| Name | Type | Description | +| ------------- | ------- | ------------------------- | +| pubKeyAddress | address | address of the public key | +| data | bytes | public key data | + +### removePublicKey + +```solidity +function removePublicKey(address pubKeyAddress) public +``` + +Remove public key by address + +### addMessengerBot + +```solidity +function addMessengerBot(address bot, uint256 gasMoney) public +``` + +Adds messenger bot with initial gas money. + +### removeMessengerBot + +```solidity +function removeMessengerBot(address bot) public +``` + +Removes messenger bot by revoking the roles. + +### withdrawGasMoney + +```solidity +function withdrawGasMoney(uint256 amount) public +``` + +Withdraw gas money. Requires the `GAS_WITHDRAWER_ROLE`. + +#### Parameters + +| Name | Type | Description | +| ------ | ------- | ------------------------------------ | +| amount | uint256 | The amount to withdraw in aCAM (wei) | + +### setGasMoneyWithdrawal + +```solidity +function setGasMoneyWithdrawal(uint256 limit, uint256 period) public +``` + +Set gas money withdrawal parameters. Requires the `BOT_ADMIN_ROLE`. + +#### Parameters + +| Name | Type | Description | +| ------ | ------- | ------------------------------------------------- | +| limit | uint256 | Amount of gas money to withdraw in wei per period | +| period | uint256 | Duration of the withdrawal period in seconds | + +## ChequeManager + +ChequeManager manages, verifies, and cashes in the messenger cheques. + +EIP712 Domain name & version: +DOMAIN_NAME = "CaminoMessenger" +DOMAIN_VERSION= "1" + +### MESSENGER_CHEQUE_TYPEHASH + +```solidity +bytes32 MESSENGER_CHEQUE_TYPEHASH +``` + +Pre-computed hash of the MessengerCheque type + +``` +keccak256( + "MessengerCheque(address fromCMAccount,address toCMAccount,address toBot,uint256 counter,uint256 amount,uint256 createdAt,uint256 expiresAt)" +); +``` + +### DOMAIN_TYPEHASH + +```solidity +bytes32 DOMAIN_TYPEHASH +``` + +Pre-computed hash of the EIP712Domain type + +``` +keccak256("EIP712Domain(string name,string version,uint256 chainId)"); +``` + +### MessengerCheque + +Struct representing a Messenger Cheque. + +```solidity +struct MessengerCheque { + address fromCMAccount; + address toCMAccount; + address toBot; + uint256 counter; + uint256 amount; + uint256 createdAt; + uint256 expiresAt; +} +``` + +### LastCashIn + +Struct for tracking the counter, amount and timestamps used for the last +cash-in operation. + +```solidity +struct LastCashIn { + uint256 counter; + uint256 amount; + uint256 createdAt; + uint256 expiresAt; +} +``` + +### ChequeManagerStorage + +```solidity +struct ChequeManagerStorage { + mapping(address => mapping(address => struct ChequeManager.LastCashIn)) _lastCashIns; + uint256 _totalChequePayments; + bytes32 _domainSeparator; +} +``` + +### ChequeVerified + +```solidity +event ChequeVerified(address fromCMAccount, address toCMAccount, address fromBot, address toBot, uint256 counter, uint256 amount, uint256 payment) +``` + +Cheque verified event. Emitted when a cheque is verified. + +### ChequeCashedIn + +```solidity +event ChequeCashedIn(address fromBot, address toBot, uint256 counter, uint256 paid, uint256 developerFee) +``` + +Cash-in event. Emitted when a cheque is cashed in. + +### InvalidFromCMAccount + +```solidity +error InvalidFromCMAccount(address fromCMAccount) +``` + +Invalid CM Account. Cheque's `fromCMAccount` has to be for `address(this)`. + +### InvalidToCMAccount + +```solidity +error InvalidToCMAccount(address toCMAccount) +``` + +`toCMAccount` address is not a registered CMAccount on the manager. + +### NotAllowedToSignCheques + +```solidity +error NotAllowedToSignCheques(address signer) +``` + +The signer is not allowed to sign cheques + +### InvalidCounter + +```solidity +error InvalidCounter(uint256 chequeCounter, uint256 lastCounter) +``` + +Invalid counter for the cheque. The counter on the cheque is not greater then the last +recorded counter. + +### InvalidAmount + +```solidity +error InvalidAmount(uint256 chequeAmount, uint256 lastAmount) +``` + +Last recorded amount is lower than the cheque's amount. + +### ChequeExpired + +```solidity +error ChequeExpired(uint256 expiresAt) +``` + +The cheque is expired at the given timestamp. + +### \_\_ChequeManager_init + +```solidity +function __ChequeManager_init() internal +``` + +Initializes the contract, setting the domain separator with EIP712 domain type hash and +the domain. + +EIP712Domain { +string name; +string version; +uint256 chainid; +} + +### getDomainSeparator + +```solidity +function getDomainSeparator() public view returns (bytes32) +``` + +Returns the domain separator. + +### hashMessengerCheque + +```solidity +function hashMessengerCheque(address fromCMAccount, address toCMAccount, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt) public pure returns (bytes32) +``` + +Returns the hash of the `MessengerCheque` encoded with +`MESSENGER_CHEQUE_TYPEHASH`. + +### hashTypedDataV4 + +```solidity +function hashTypedDataV4(address fromCMAccount, address toCMAccount, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt) public view returns (bytes32) +``` + +Returns the hash of the typed data (cheque) with prefix and domain +separator. + +### recoverSigner + +```solidity +function recoverSigner(address fromCMAccount, address toCMAccount, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt, bytes signature) internal view returns (address signer) +``` + +Returns the signer for the given cheque and signature. Uses {ECDSA} library to +recover the signer. + +### verifyCheque + +```solidity +function verifyCheque(address fromCMAccount, address toCMAccount, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt, bytes signature) public returns (address signer, uint256 paymentAmount) +``` + +Returns signer and payment amount if the signature is valid for the +given cheque, the signer is an allowed bot, cheque counter and amounts are +valid according to last cash ins. + +Please be aware that `cheque.amount < paymentAmount` for a valid cheque as +long as the last amount is lower than the cheque amount. Only the difference +between the cheque amount and the last recorded amount is paid. + +### cashInCheque + +```solidity +function cashInCheque(address fromCMAccount, address toCMAccount, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt, bytes signature) public +``` + +Cash in a cheque by verifying it and paying the difference between the +cheque amount and the last recorded amount for the signer and `toBot` pair. + +A percentage of the amount is also paid to the developer wallet. + +#### Parameters + +| Name | Type | Description | +| ------------- | ------- | ----------------------------------------------------------------------------------- | +| fromCMAccount | address | The CM Account that will pay the amount. This contract. | +| toCMAccount | address | The CM Account that will receive the amount. | +| toBot | address | The address of the bot that received the cheque. | +| counter | uint256 | The counter of the cheque. Should be increased with every cheque. | +| amount | uint256 | The amount on the cheque. Should be greater then or equal the last recorded amount. | +| createdAt | uint256 | The creation timestamp of the cheque. | +| expiresAt | uint256 | The expiration timestamp of the cheque. | +| signature | bytes | The signature of the cheque. | + +### getLastCashIn + +```solidity +function getLastCashIn(address fromBot, address toBot) public view returns (uint256 lastCounter, uint256 lastAmount, uint256 lastCreatedAt, uint256 lastExpiresAt) +``` + +Returns last cash-in details for given `fromBot` & `toBot` pair. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ---------------------------------------------------------------------------------------------------------------- | +| fromBot | address | The address of the bot that sent the cheque. | +| toBot | address | The address of the bot that received the cheque. Returns (lastCounter, lastAmount, lastCreatedAt, lastExpiresAt) | + +#### Return Values + +| Name | Type | Description | +| ------------- | ------- | -------------------------------------------- | +| lastCounter | uint256 | The last counter of the cheque. | +| lastAmount | uint256 | The last amount of the cheque. | +| lastCreatedAt | uint256 | The last creation timestamp of the cheque. | +| lastExpiresAt | uint256 | The last expiration timestamp of the cheque. | + +### setLastCashIn + +```solidity +function setLastCashIn(address fromBot, address toBot, uint256 counter, uint256 amount, uint256 createdAt, uint256 expiresAt) internal +``` + +Sets last cash-in for given `fromBot`, `toBot` pair. + +#### Parameters + +| Name | Type | Description | +| --------- | ------- | ------------------------------------------------ | +| fromBot | address | The address of the bot that sent the cheque. | +| toBot | address | The address of the bot that received the cheque. | +| counter | uint256 | The counter of the cheque. | +| amount | uint256 | The amount of the cheque. | +| createdAt | uint256 | The creation timestamp of the cheque. | +| expiresAt | uint256 | The expiration timestamp of the cheque. | + +### getTotalChequePayments + +```solidity +function getTotalChequePayments() public view returns (uint256) +``` + +Returns total cheque payments. This is the sum of all cashed in cheques. + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | --------------------------------------------------- | +| [0] | uint256 | totalChequePayments The total cheque payments made. | + +### isBotAllowed + +```solidity +function isBotAllowed(address bot) public view virtual returns (bool) +``` + +Abstract function to check if a bot is allowed to sign cheques. This +must be implemented by the inheriting contract. + +### getManagerAddress + +```solidity +function getManagerAddress() public view virtual returns (address) +``` + +Abstract function to get the manager address. This must be implemented +by the inheriting contract. + +## GasMoneyManager + +GasMoneyManager manages gas money withdrawals for a {CMAccount}. + +Gas money withdrawals are restricted to a withdrawal limit and period. + +### GasMoneyStorage + +```solidity +struct GasMoneyStorage { + mapping(address => uint256) _withdrawalPeriodStart; + mapping(address => uint256) _withdrawnAmount; + uint256 _withdrawalLimit; + uint256 _withdrawalPeriod; +} +``` + +### GasMoneyWithdrawal + +```solidity +event GasMoneyWithdrawal(address withdrawer, uint256 amount) +``` + +Gas money withdrawal event + +#### Parameters + +| Name | Type | Description | +| ---------- | ------- | ----------------------------- | +| withdrawer | address | the address of the withdrawer | +| amount | uint256 | the amount withdrawn | + +### GasMoneyWithdrawalUpdated + +```solidity +event GasMoneyWithdrawalUpdated(uint256 limit, uint256 period) +``` + +Gas money withdrawal limit and period updated event + +#### Parameters + +| Name | Type | Description | +| ------ | ------- | ----------------------------------- | +| limit | uint256 | the withdrawal limit for the period | +| period | uint256 | the withdrawal period in seconds | + +### WithdrawalLimitExceeded + +```solidity +error WithdrawalLimitExceeded(uint256 limit, uint256 amount) +``` + +### WithdrawalLimitExceededForPeriod + +```solidity +error WithdrawalLimitExceededForPeriod(uint256 limit, uint256 amount) +``` + +### \_\_GasMoneyManager_init + +```solidity +function __GasMoneyManager_init(uint256 withdrawalLimit, uint256 withdrawalPeriod) internal +``` + +### \_withdrawGasMoney + +```solidity +function _withdrawGasMoney(uint256 amount) internal +``` + +Withdraws gas money. + +This functions is intended to be called by the bot to withdraw gas money. +Inheriting contract should restrict who can call this with a public +function. + +### \_setGasMoneyWithdrawal + +```solidity +function _setGasMoneyWithdrawal(uint256 limit, uint256 period) internal +``` + +Sets the gas money withdrawal limit and period. + +#### Parameters + +| Name | Type | Description | +| ------ | ------- | ----------------------------------- | +| limit | uint256 | the withdrawal limit for the period | +| period | uint256 | the withdrawal period in seconds | + +### getGasMoneyWithdrawal + +```solidity +function getGasMoneyWithdrawal() public view returns (uint256 withdrawalLimit, uint256 withdrawalPeriod) +``` + +Returns the gas money withdrawal restrictions. + +#### Return Values + +| Name | Type | Description | +| ---------------- | ------- | ----------- | +| withdrawalLimit | uint256 | | +| withdrawalPeriod | uint256 | | + +### getGasMoneyWithdrawalForAccount + +```solidity +function getGasMoneyWithdrawalForAccount(address account) public view returns (uint256 periodStart, uint256 withdrawnAmount) +``` + +Returns the gas money withdrawal details for an account. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ---------------------- | +| account | address | address of the account | + +#### Return Values + +| Name | Type | Description | +| --------------- | ------- | ---------------------------------------- | +| periodStart | uint256 | timestamp of the withdrawal period start | +| withdrawnAmount | uint256 | amount withdrawn within the period | + +## ICMAccount + +### initialize + +```solidity +function initialize(address manager, address bookingToken, uint256 prefundAmount, address owner, address upgrader) external +``` + +## BookingToken + +Booking Token contract represents a booking done on the Camino Messenger. + +Suppliers can mint Booking Tokens and reserve them for a distributor address to +buy. + +Booking Tokens can have zero price, meaning that the payment will be done +off-chain. + +When a token is minted with a reservation, it can not transferred until the +expiration timestamp is reached or the token is bought. + +### UPGRADER_ROLE + +```solidity +bytes32 UPGRADER_ROLE +``` + +Upgrader role can upgrade the contract to a new implementation. + +### MIN_EXPIRATION_ADMIN_ROLE + +```solidity +bytes32 MIN_EXPIRATION_ADMIN_ROLE +``` + +This role can set the mininum allowed expiration timestamp difference. + +### TokenReservation + +```solidity +struct TokenReservation { + address reservedFor; + address supplier; + uint256 expirationTimestamp; + uint256 price; + contract IERC20 paymentToken; +} +``` + +### BookingTokenStorage + +```solidity +struct BookingTokenStorage { + address _manager; + uint256 _nextTokenId; + uint256 _minExpirationTimestampDiff; + mapping(uint256 => struct BookingToken.TokenReservation) _reservations; +} +``` + +### TokenReserved + +```solidity +event TokenReserved(uint256 tokenId, address reservedFor, address supplier, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) +``` + +Event emitted when a token is reserved. + +#### Parameters + +| Name | Type | Description | +| ------------------- | --------------- | --------------------- | +| tokenId | uint256 | token id | +| reservedFor | address | reserved for address | +| supplier | address | supplier address | +| expirationTimestamp | uint256 | expiration timestamp | +| price | uint256 | price of the token | +| paymentToken | contract IERC20 | payment token address | + +### TokenBought + +```solidity +event TokenBought(uint256 tokenId, address buyer) +``` + +Event emitted when a token is bought. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------- | +| tokenId | uint256 | token id | +| buyer | address | buyer address | + +### ExpirationTimestampTooSoon + +```solidity +error ExpirationTimestampTooSoon(uint256 expirationTimestamp, uint256 minExpirationTimestampDiff) +``` + +Error for expiration timestamp too soon. It must be at least +`_minExpirationTimestampDiff` seconds in the future. + +### NotCMAccount + +```solidity +error NotCMAccount(address account) +``` + +Address is not a CM Account. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | --------------- | +| account | address | account address | + +### ReservationMismatch + +```solidity +error ReservationMismatch(address reservedFor, address buyer) +``` + +ReservedFor and buyer mismatch. + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | -------------------- | +| reservedFor | address | reserved for address | +| buyer | address | buyer address | + +### ReservationExpired + +```solidity +error ReservationExpired(uint256 tokenId, uint256 expirationTimestamp) +``` + +Reservation expired. + +#### Parameters + +| Name | Type | Description | +| ------------------- | ------- | -------------------- | +| tokenId | uint256 | token id | +| expirationTimestamp | uint256 | expiration timestamp | + +### IncorrectPrice + +```solidity +error IncorrectPrice(uint256 price, uint256 reservationPrice) +``` + +Incorrect price. + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | ------------------ | +| price | uint256 | price of the token | +| reservationPrice | uint256 | reservation price | + +### SupplierIsNotOwner + +```solidity +error SupplierIsNotOwner(uint256 tokenId, address supplier) +``` + +Supplier is not the owner. + +#### Parameters + +| Name | Type | Description | +| -------- | ------- | ---------------- | +| tokenId | uint256 | token id | +| supplier | address | supplier address | + +### TokenIsReserved + +```solidity +error TokenIsReserved(uint256 tokenId, address reservedFor) +``` + +Token is reserved and can not be transferred. + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | -------------------- | +| tokenId | uint256 | token id | +| reservedFor | address | reserved for address | + +### InsufficientAllowance + +```solidity +error InsufficientAllowance(address sender, contract IERC20 paymentToken, uint256 price, uint256 allowance) +``` + +Insufficient allowance to transfer the ERC20 token to the supplier. + +#### Parameters + +| Name | Type | Description | +| ------------ | --------------- | --------------------- | +| sender | address | msg.sender | +| paymentToken | contract IERC20 | payment token address | +| price | uint256 | price of the token | +| allowance | uint256 | allowance amount | + +### onlyCMAccount + +```solidity +modifier onlyCMAccount(address account) +``` + +Only CMAccount modifier. + +### initialize + +```solidity +function initialize(address manager, address defaultAdmin, address upgrader) public +``` + +### \_authorizeUpgrade + +```solidity +function _authorizeUpgrade(address newImplementation) internal +``` + +Function to authorize an upgrade for UUPS proxy. + +### safeMintWithReservation + +```solidity +function safeMintWithReservation(address reservedFor, string uri, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) public +``` + +Mints a new token with a reservation for a specific address. + +#### Parameters + +| Name | Type | Description | +| ------------------- | --------------- | --------------------------------------------------------------------- | +| reservedFor | address | The CM Account address that can buy the token | +| uri | string | The URI of the token | +| expirationTimestamp | uint256 | The expiration timestamp | +| price | uint256 | The price of the token | +| paymentToken | contract IERC20 | The token used to pay for the reservation. If address(0) then native. | + +### buyReservedToken + +```solidity +function buyReservedToken(uint256 tokenId) external payable +``` + +Buys a reserved token. The reservation must be for the message sender. + +Also the message sender should set allowance for the payment token to this +contract to at least the reservation price. (only for ERC20 tokens) + +For native coin, the message sender should send the exact amount. + +Only CM Accounts can call this function + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------ | +| tokenId | uint256 | The token id | + +### \_reserve + +```solidity +function _reserve(uint256 tokenId, address reservedFor, address supplier, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) internal +``` + +Reserve a token for a specific address with an expiration timestamp + +### checkTransferable + +```solidity +function checkTransferable(uint256 tokenId) internal +``` + +Check if the token is transferable + +### isCMAccount + +```solidity +function isCMAccount(address account) public view returns (bool) +``` + +Checks if an address is a CM Account. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------- | +| account | address | The address to check | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------------------------------- | +| [0] | bool | true if the address is a CM Account | + +### requireCMAccount + +```solidity +function requireCMAccount(address account) internal view +``` + +Checks if the address is a CM Account and reverts if not. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------- | +| account | address | The address to check | + +### setManagerAddress + +```solidity +function setManagerAddress(address manager) public +``` + +Sets for the manager address. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| manager | address | The address of the manager | + +### getManagerAddress + +```solidity +function getManagerAddress() public view returns (address) +``` + +Returns for the manager address. + +### setMinExpirationTimestampDiff + +```solidity +function setMinExpirationTimestampDiff(uint256 minExpirationTimestampDiff) public +``` + +Sets minimum expiration timestamp difference in seconds. + +#### Parameters + +| Name | Type | Description | +| -------------------------- | ------- | -------------------------------------------------- | +| minExpirationTimestampDiff | uint256 | Minimum expiration timestamp difference in seconds | + +### getMinExpirationTimestampDiff + +```solidity +function getMinExpirationTimestampDiff() public view returns (uint256) +``` + +Returns minimum expiration timestamp difference in seconds. + +### getReservationPrice + +```solidity +function getReservationPrice(uint256 tokenId) public view returns (uint256 price, contract IERC20 paymentToken) +``` + +Returns the token reservation price for a specific token. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------ | +| tokenId | uint256 | The token id | + +### transferFrom + +```solidity +function transferFrom(address from, address to, uint256 tokenId) public +``` + +Override transferFrom to check if token is reserved. It reverts if +the token is reserved. + +### safeTransferFrom + +```solidity +function safeTransferFrom(address from, address to, uint256 tokenId, bytes data) public +``` + +Override safeTransferFrom to check if token is reserved. It reverts if +the token is reserved. + +### \_update + +```solidity +function _update(address to, uint256 tokenId, address auth) internal returns (address) +``` + +### \_increaseBalance + +```solidity +function _increaseBalance(address account, uint128 value) internal +``` + +### tokenURI + +```solidity +function tokenURI(uint256 tokenId) public view returns (string) +``` + +### supportsInterface + +```solidity +function supportsInterface(bytes4 interfaceId) public view returns (bool) +``` + +## BookingTokenOperator + +Booking token operator contract is used by the {CMAccount} contract to mint +and buy booking tokens. + +We made this a library so that we can use it in the {CMAccount} contract without +increasing the size of the contract. + +### TokenApprovalFailed + +```solidity +error TokenApprovalFailed(address token, address spender, uint256 amount) +``` + +_Token approval for the BookingToken address failed._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | --------------------------------------------------- | +| token | address | token address | +| spender | address | spender address (the BookingToken contract address) | +| amount | uint256 | amount of tokens to approve | + +### mintBookingToken + +```solidity +function mintBookingToken(address bookingToken, address reservedFor, string uri, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) public +``` + +_Mints a booking token._ + +#### Parameters + +| Name | Type | Description | +| ------------------- | --------------- | ---------------------------------------------------------------------------- | +| bookingToken | address | booking token contract address | +| reservedFor | address | address of the CM Account that can buy the token (generally the distributor) | +| uri | string | URI of the token | +| expirationTimestamp | uint256 | expiration timestamp of the token in seconds | +| price | uint256 | price of the token | +| paymentToken | contract IERC20 | payment token address | + +### buyBookingToken + +```solidity +function buyBookingToken(address bookingToken, uint256 tokenId) public +``` + +_Buys a booking token with the specified price and payment token in the +reservation._ + +#### Parameters + +| Name | Type | Description | +| ------------ | ------- | ------------------------------ | +| bookingToken | address | booking token contract address | +| tokenId | uint256 | token id | + +## IBookingToken + +### safeMintWithReservation + +```solidity +function safeMintWithReservation(address reservedFor, string uri, uint256 expirationTimestamp, uint256 price, contract IERC20 paymentToken) external +``` + +### buyReservedToken + +```solidity +function buyReservedToken(uint256 tokenId) external payable +``` + +### getReservationPrice + +```solidity +function getReservationPrice(uint256 tokenId) external view returns (uint256 price, contract IERC20 paymentToken) +``` + +## CMAccountManager + +This contract manages the creation of the Camino Messenger accounts by +deploying {ERC1967Proxy} proxies that point to the{CMAccount} implementation +address. + +Create CM Account: Users who want to create an account should call +`createCMAccount(address admin, address upgrader)` function with addresses of +the accounts admin and upgrader roles and also send the pre fund amount, +which is currently set as 100 CAMs. When the manager contract is paused, +account creation is stopped. + +Developer Fee: This contracts also keeps the info about the developer wallet +and fee basis points. Which are used during the cheque cash in to pay for the +developer fee. + +Service Registry: {CMAccountManager} also acts as a registry for the services +that {CMAccount} contracts add as a supported or wanted service. Registry +works by hashing (keccak256) the service name (string) and creating a mapping +as keccak256(serviceName) => serviceName. And provides functions that +{CMAccount} function uses to register services. The {CMAccount} only keeps +the hashes (byte32) of the registered services. + +### PAUSER_ROLE + +```solidity +bytes32 PAUSER_ROLE +``` + +Pauser role can pause the contract. Currently this only affects the +creation of CM Accounts. When paused, account creation is stopped. + +### UPGRADER_ROLE + +```solidity +bytes32 UPGRADER_ROLE +``` + +Upgrader role can upgrade the contract to a new implementation. + +### VERSIONER_ROLE + +```solidity +bytes32 VERSIONER_ROLE +``` + +Versioner role can set new {CMAccount} implementation address. When a +new implementation address is set, it is used for the new {CMAccount} +creations. + +The old {CMAccount} contracts are not affected by this. Owners of those +should do the upgrade manually by calling the `upgradeToAndCall(address)` +function on the account. + +### FEE_ADMIN_ROLE + +```solidity +bytes32 FEE_ADMIN_ROLE +``` + +Fee admin role can set the developer fee basis points which used for +calculating the developer fee that is cut from the cheque payments. + +### DEVELOPER_WALLET_ADMIN_ROLE + +```solidity +bytes32 DEVELOPER_WALLET_ADMIN_ROLE +``` + +Developer wallet admin role can set the developer wallet address +which is used to receive the developer fee. + +### PREFUND_ADMIN_ROLE + +```solidity +bytes32 PREFUND_ADMIN_ROLE +``` + +Prefund admin role can set the mandatory prefund amount for {CMAccount} +contracts. + +### SERVICE_REGISTRY_ADMIN_ROLE + +```solidity +bytes32 SERVICE_REGISTRY_ADMIN_ROLE +``` + +Service registry admin role can add and remove services to the service +registry mapping. Implemented by {ServiceRegistry} contract. + +### CMACCOUNT_ROLE + +```solidity +bytes32 CMACCOUNT_ROLE +``` + +This role is granted to the created CM Accounts. It is used to keep +an enumerable list of CM Accounts. + +### CMAccountInfo + +CMAccount info struct, to keep track of created CM Accounts and their +creators. + +```solidity +struct CMAccountInfo { + bool isCMAccount; + address creator; +} +``` + +### CMAccountManagerStorage + +```solidity +struct CMAccountManagerStorage { + address _latestAccountImplementation; + uint256 _prefundAmount; + address _developerWallet; + uint256 _developerFeeBp; + address _bookingToken; + mapping(address => struct CMAccountManager.CMAccountInfo) _cmAccountInfo; +} +``` + +### CMAccountCreated + +```solidity +event CMAccountCreated(address account) +``` + +CM Account created event. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------------- | +| account | address | The address of the new CMAccount | + +### CMAccountImplementationUpdated + +```solidity +event CMAccountImplementationUpdated(address oldImplementation, address newImplementation) +``` + +CM Account implementation address updated event. + +#### Parameters + +| Name | Type | Description | +| ----------------- | ------- | ------------------------------ | +| oldImplementation | address | The old implementation address | +| newImplementation | address | The new implementation address | + +### DeveloperWalletUpdated + +```solidity +event DeveloperWalletUpdated(address oldDeveloperWallet, address newDeveloperWallet) +``` + +Developer wallet address updated event. + +#### Parameters + +| Name | Type | Description | +| ------------------ | ------- | -------------------------------- | +| oldDeveloperWallet | address | The old developer wallet address | +| newDeveloperWallet | address | The new developer wallet address | + +### DeveloperFeeBpUpdated + +```solidity +event DeveloperFeeBpUpdated(uint256 oldDeveloperFeeBp, uint256 newDeveloperFeeBp) +``` + +Developer fee basis points updated event. + +#### Parameters + +| Name | Type | Description | +| ----------------- | ------- | ---------------------------------- | +| oldDeveloperFeeBp | uint256 | The old developer fee basis points | +| newDeveloperFeeBp | uint256 | The new developer fee basis points | + +### BookingTokenAddressUpdated + +```solidity +event BookingTokenAddressUpdated(address oldBookingToken, address newBookingToken) +``` + +Booking token address updated event. + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | ----------------------------- | +| oldBookingToken | address | The old booking token address | +| newBookingToken | address | The new booking token address | + +### CMAccountInvalidImplementation + +```solidity +error CMAccountInvalidImplementation(address implementation) +``` + +The implementation of the CMAccount is invalid. + +#### Parameters + +| Name | Type | Description | +| -------------- | ------- | ------------------------------------------- | +| implementation | address | The implementation address of the CMAccount | + +### CMAccountInvalidAdmin + +```solidity +error CMAccountInvalidAdmin(address admin) +``` + +The admin address is invalid. + +#### Parameters + +| Name | Type | Description | +| ----- | ------- | ----------------- | +| admin | address | The admin address | + +### InvalidDeveloperWallet + +```solidity +error InvalidDeveloperWallet(address developerWallet) +``` + +Invalid developer address. + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | ---------------------------- | +| developerWallet | address | The developer wallet address | + +### InvalidBookingTokenAddress + +```solidity +error InvalidBookingTokenAddress(address bookingToken) +``` + +Invalid booking token address. + +#### Parameters + +| Name | Type | Description | +| ------------ | ------- | ------------------------- | +| bookingToken | address | The booking token address | + +### IncorrectPrefundAmount + +```solidity +error IncorrectPrefundAmount(uint256 expected, uint256 sended) +``` + +Incorrect pre fund amount. + +#### Parameters + +| Name | Type | Description | +| -------- | ------- | ---------------------------- | +| expected | uint256 | The expected pre fund amount | +| sended | uint256 | | + +### constructor + +```solidity +constructor() public +``` + +### initialize + +```solidity +function initialize(address defaultAdmin, address pauser, address upgrader, address versioner, address developerWallet, uint256 developerFeeBp) public +``` + +### pause + +```solidity +function pause() public +``` + +Pauses the CMAccountManager contract. Currently this only affects the +creation of CMAccount. When paused, account creation is stopped. + +### unpause + +```solidity +function unpause() public +``` + +Unpauses the CMAccountManager contract. + +### \_authorizeUpgrade + +```solidity +function _authorizeUpgrade(address newImplementation) internal +``` + +Authorization for the CMAccountManager contract upgrade. + +### createCMAccount + +```solidity +function createCMAccount(address admin, address upgrader) external payable returns (address) +``` + +Creates CMAccount by deploying a ERC1967Proxy with the CMAccount +implementation from the manager. + +Because this function is deploying a contract, it reverts if the caller is +not KYC or KYB verified. (For EOAs only) + +Caller must send the pre-fund amount with the transaction. + +_Emits a {CMAccountCreated} event._ + +### \_setCMAccountInfo + +```solidity +function _setCMAccountInfo(address account, struct CMAccountManager.CMAccountInfo info) internal +``` + +### getCMAccountCreator + +```solidity +function getCMAccountCreator(address account) public view returns (address) +``` + +Returns the given account's creator. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------------- | +| account | address | The account address | + +### isCMAccount + +```solidity +function isCMAccount(address account) public view returns (bool) +``` + +Check if an address is CMAccount created by the manager. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ---------------------------- | +| account | address | The account address to check | + +### getAccountImplementation + +```solidity +function getAccountImplementation() public view returns (address) +``` + +Returns the CMAccount implementation address. + +### setAccountImplementation + +```solidity +function setAccountImplementation(address newImplementation) public +``` + +Set a new CMAccount implementation address. + +#### Parameters + +| Name | Type | Description | +| ----------------- | ------- | ------------------------------ | +| newImplementation | address | The new implementation address | + +### \_setAccountImplementation + +```solidity +function _setAccountImplementation(address newImplementation) internal +``` + +### getPrefundAmount + +```solidity +function getPrefundAmount() public view returns (uint256) +``` + +Returns the prefund amount. + +### setPrefundAmount + +```solidity +function setPrefundAmount(uint256 newPrefundAmount) public +``` + +Sets the prefund amount. + +### getBookingTokenAddress + +```solidity +function getBookingTokenAddress() public view returns (address) +``` + +Returns the booking token address. + +### setBookingTokenAddress + +```solidity +function setBookingTokenAddress(address token) public +``` + +Sets booking token address. + +### \_setBookingTokenAddress + +```solidity +function _setBookingTokenAddress(address token) internal +``` + +### getDeveloperWallet + +```solidity +function getDeveloperWallet() public view returns (address developerWallet) +``` + +Returns developer wallet address. + +### setDeveloperWallet + +```solidity +function setDeveloperWallet(address developerWallet) public +``` + +Sets developer wallet address. + +### getDeveloperFeeBp + +```solidity +function getDeveloperFeeBp() public view returns (uint256 developerFeeBp) +``` + +Returns developer fee in basis points. + +### setDeveloperFeeBp + +```solidity +function setDeveloperFeeBp(uint256 bp) public +``` + +Sets developer fee in basis points. + +A basis point (bp) is one hundredth of 1 percentage point. + +1 bp = 0.01%, 1/10,000⁠, or 0.0001. +10 bp = 0.1%, 1/1,000⁠, or 0.001. +100 bp = 1%, ⁠1/100⁠, or 0.01. + +### registerService + +```solidity +function registerService(string serviceName) public +``` + +Registers a given service name. CM Accounts can only register services +if they are also registered in the service registry on the manager contract. + +#### Parameters + +| Name | Type | Description | +| ----------- | ------ | ------------------- | +| serviceName | string | Name of the service | + +### unregisterService + +```solidity +function unregisterService(string serviceName) public +``` + +Unregisters a given service name. CM Accounts will not be able to register +the service anymore. + +#### Parameters + +| Name | Type | Description | +| ----------- | ------ | ------------------- | +| serviceName | string | Name of the service | + +## ICMAccountManager + +### getAccountImplementation + +```solidity +function getAccountImplementation() external view returns (address) +``` + +### getDeveloperFeeBp + +```solidity +function getDeveloperFeeBp() external view returns (uint256) +``` + +### getDeveloperWallet + +```solidity +function getDeveloperWallet() external view returns (address) +``` + +### isCMAccount + +```solidity +function isCMAccount(address account) external view returns (bool) +``` + +### getRegisteredServiceHashByName + +```solidity +function getRegisteredServiceHashByName(string serviceName) external view returns (bytes32 serviceHash) +``` + +### getRegisteredServiceNameByHash + +```solidity +function getRegisteredServiceNameByHash(bytes32 serviceHash) external view returns (string serviceName) +``` + +## CMAccountManagerV2 + +### getVersion + +```solidity +function getVersion() public pure returns (string) +``` + +## PartnerConfiguration + +Partner Configuration is used by the {CMAccount} contract to register +supported and wanted services by the partner. + +### Service + +```solidity +struct Service { + uint256 _fee; + bool _restrictedRate; + string[] _capabilities; +} +``` + +### PaymentInfo + +```solidity +struct PaymentInfo { + bool _supportsOffChainPayment; + struct EnumerableSet.AddressSet _supportedTokens; +} +``` + +### PartnerConfigurationStorage + +```solidity +struct PartnerConfigurationStorage { + struct EnumerableSet.Bytes32Set _servicesHashSet; + mapping(bytes32 => struct PartnerConfiguration.Service) _supportedServices; + struct PartnerConfiguration.PaymentInfo _paymentInfo; + struct EnumerableSet.AddressSet _publicKeyAddressesSet; + mapping(address => bytes) _publicKeys; + struct EnumerableSet.Bytes32Set _wantedServicesHashSet; +} +``` + +### ServiceAlreadyExists + +```solidity +error ServiceAlreadyExists(bytes32 serviceHash) +``` + +### ServiceDoesNotExist + +```solidity +error ServiceDoesNotExist(bytes32 serviceHash) +``` + +### WantedServiceAlreadyExists + +```solidity +error WantedServiceAlreadyExists(bytes32 serviceHash) +``` + +### WantedServiceDoesNotExist + +```solidity +error WantedServiceDoesNotExist(bytes32 serviceHash) +``` + +### PaymentTokenAlreadyExists + +```solidity +error PaymentTokenAlreadyExists(address token) +``` + +### PaymentTokenDoesNotExist + +```solidity +error PaymentTokenDoesNotExist(address token) +``` + +### PublicKeyAlreadyExists + +```solidity +error PublicKeyAlreadyExists(address pubKeyAddress) +``` + +### PublicKeyDoesNotExist + +```solidity +error PublicKeyDoesNotExist(address pubKeyAddress) +``` + +### InvalidPublicKeyUseType + +```solidity +error InvalidPublicKeyUseType(uint8 use) +``` + +### ServiceAdded + +```solidity +event ServiceAdded(bytes32 serviceHash) +``` + +### ServiceRemoved + +```solidity +event ServiceRemoved(bytes32 serviceHash) +``` + +### WantedServiceAdded + +```solidity +event WantedServiceAdded(bytes32 serviceHash) +``` + +### WantedServiceRemoved + +```solidity +event WantedServiceRemoved(bytes32 serviceHash) +``` + +### ServiceFeeUpdated + +```solidity +event ServiceFeeUpdated(bytes32 serviceHash, uint256 fee) +``` + +### ServiceRestrictedRateUpdated + +```solidity +event ServiceRestrictedRateUpdated(bytes32 serviceHash, bool restrictedRate) +``` + +### ServiceCapabilitiesUpdated + +```solidity +event ServiceCapabilitiesUpdated(bytes32 serviceHash) +``` + +### ServiceCapabilityAdded + +```solidity +event ServiceCapabilityAdded(bytes32 serviceHash, string capability) +``` + +### ServiceCapabilityRemoved + +```solidity +event ServiceCapabilityRemoved(bytes32 serviceHash, string capability) +``` + +### PaymentTokenAdded + +```solidity +event PaymentTokenAdded(address token) +``` + +### PaymentTokenRemoved + +```solidity +event PaymentTokenRemoved(address token) +``` + +### OffChainPaymentSupportUpdated + +```solidity +event OffChainPaymentSupportUpdated(bool supportsOffChainPayment) +``` + +### PublicKeyAdded + +```solidity +event PublicKeyAdded(address pubKeyAddress) +``` + +### PublicKeyRemoved + +```solidity +event PublicKeyRemoved(address pubKeyAddress) +``` + +### \_\_PartnerConfiguration_init + +```solidity +function __PartnerConfiguration_init() internal +``` + +### \_\_PartnerConfiguration_init_unchained + +```solidity +function __PartnerConfiguration_init_unchained() internal +``` + +### \_addService + +```solidity +function _addService(bytes32 serviceHash, uint256 fee, string[] capabilities, bool restrictedRate) internal virtual +``` + +_Adds a supported Service object for a given hash._ + +### \_removeService + +```solidity +function _removeService(bytes32 serviceHash) internal virtual +``` + +_Removes a supported Service object for a given hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### \_setServiceFee + +```solidity +function _setServiceFee(bytes32 serviceHash, uint256 fee) internal virtual +``` + +_Set the Service fee for a given hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | +| fee | uint256 | Fee | + +### \_setServiceRestrictedRate + +```solidity +function _setServiceRestrictedRate(bytes32 serviceHash, bool restrictedRate) internal virtual +``` + +_Set the Service restricted rate for a given hash._ + +#### Parameters + +| Name | Type | Description | +| -------------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | +| restrictedRate | bool | Restricted rate | + +### \_setServiceCapabilities + +```solidity +function _setServiceCapabilities(bytes32 serviceHash, string[] capabilities) internal virtual +``` + +_Set the Service capabilities for a given hash._ + +#### Parameters + +| Name | Type | Description | +| ------------ | -------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | +| capabilities | string[] | Capabilities | + +### \_addServiceCapability + +```solidity +function _addServiceCapability(bytes32 serviceHash, string capability) internal virtual +``` + +_Add a capability to the service._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | +| capability | string | Capability | + +### \_removeServiceCapability + +```solidity +function _removeServiceCapability(bytes32 serviceHash, string capability) internal virtual +``` + +_Remove a capability from the service._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | +| capability | string | Capability | + +### getAllServiceHashes + +```solidity +function getAllServiceHashes() public view returns (bytes32[] serviceHashes) +``` + +_Returns all supported service hashes_ + +### getService + +```solidity +function getService(bytes32 serviceHash) public view virtual returns (struct PartnerConfiguration.Service service) +``` + +\_Returns the Service object for a given hash. Service object contains fee and capabilities. + +{serviceHash} is keccak256 hash of the pkg + service name as: + + ┌────────────── pkg ─────────────┐ ┌───── service name ─────┐ + +keccak256("cmp.services.accommodation.v1alpha.AccommodationSearchService")\_ + +### getServiceFee + +```solidity +function getServiceFee(bytes32 serviceHash) public view virtual returns (uint256 fee) +``` + +_Returns the fee for a given service hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### getServiceRestrictedRate + +```solidity +function getServiceRestrictedRate(bytes32 serviceHash) public view virtual returns (bool restrictedRate) +``` + +_Returns the restricted rate for a given service hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### getServiceCapabilities + +```solidity +function getServiceCapabilities(bytes32 serviceHash) public view virtual returns (string[] capabilities) +``` + +_Returns the capabilities for a given service hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### \_addWantedService + +```solidity +function _addWantedService(bytes32 serviceHash) internal virtual +``` + +\_Adds a wanted service hash to the wanted services set. + +Reverts if the service already exists.\_ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### \_removeWantedService + +```solidity +function _removeWantedService(bytes32 serviceHash) internal virtual +``` + +\_Removes a wanted service hash from the wanted services set. + +Reverts if the service does not exist.\_ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### getWantedServiceHashes + +```solidity +function getWantedServiceHashes() public view virtual returns (bytes32[] serviceHashes) +``` + +_Returns all wanted service hashes._ + +### \_addSupportedToken + +```solidity +function _addSupportedToken(address _token) internal virtual +``` + +_Adds a supported payment token._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | --------------------------------- | +| \_token | address | Payment token address to be added | + +### \_removeSupportedToken + +```solidity +function _removeSupportedToken(address _token) internal virtual +``` + +_Removes a supported payment token._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ----------------------------------- | +| \_token | address | Payment token address to be removed | + +### getSupportedTokens + +```solidity +function getSupportedTokens() public view virtual returns (address[] tokens) +``` + +_Returns supported token addresses._ + +### \_setOffChainPaymentSupported + +```solidity +function _setOffChainPaymentSupported(bool _supportsOffChainPayment) internal virtual +``` + +_Set the off-chain payment support is supported._ + +### offChainPaymentSupported + +```solidity +function offChainPaymentSupported() public view virtual returns (bool) +``` + +_Return true if off-chain payment is supported for the given service_ + +### \_addPublicKey + +```solidity +function _addPublicKey(address pubKeyAddress, bytes publicKeyData) internal virtual +``` + +\_Adds public key with an address. Reverts if the public key already +exists. + +Beware: This functions does not check if the public key is actually for the +given address.\_ + +### \_removePublicKey + +```solidity +function _removePublicKey(address pubKeyAddress) internal virtual +``` + +\_Removes the public key for a given address + +Reverts if the public key does not exist\_ + +### getPublicKeysAddresses + +```solidity +function getPublicKeysAddresses() public view virtual returns (address[] pubKeyAddresses) +``` + +_Returns the addresses of all public keys. These can then be used to +retrieve the public keys the `getPublicKey(address)` function._ + +### getPublicKey + +```solidity +function getPublicKey(address pubKeyAddress) public view virtual returns (bytes data) +``` + +\_Returns the public key for a given address. + +Reverts if the public key does not exist\_ + +#### Parameters + +| Name | Type | Description | +| ------------- | ------- | ------------------------- | +| pubKeyAddress | address | Address of the public key | + +## ServiceRegistry + +_Service registry is used by the {CMAccountManager} contract to register +services by hashing (keccak256) the service name (string) and creating a mapping +as keccak256(serviceName) => serviceName._ + +### ServiceRegistryStorage + +```solidity +struct ServiceRegistryStorage { + struct EnumerableSet.Bytes32Set _servicesHashSet; + mapping(bytes32 => string) _serviceNameByHash; + mapping(string => bytes32) _hashByServiceName; +} +``` + +### ServiceRegistered + +```solidity +event ServiceRegistered(string serviceName, bytes32 serviceHash) +``` + +### ServiceUnregistered + +```solidity +event ServiceUnregistered(string serviceName, bytes32 serviceHash) +``` + +### ServiceAlreadyRegistered + +```solidity +error ServiceAlreadyRegistered(string serviceName) +``` + +### ServiceNotRegistered + +```solidity +error ServiceNotRegistered() +``` + +### \_\_ServiceRegistry_init + +```solidity +function __ServiceRegistry_init() internal +``` + +### \_\_ServiceRegistry_init_unchained + +```solidity +function __ServiceRegistry_init_unchained() internal +``` + +### \_registerServiceName + +```solidity +function _registerServiceName(string serviceName) internal virtual +``` + +\_Adds a new service by its name. This function calculates the hash of the +service name and adds it to the registry + +{serviceName} is the pkg + service name as: + +┌────────────── pkg ─────────────┐ ┌───── service name ─────┐ +"cmp.services.accommodation.v1alpha.AccommodationSearchService"\_ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------ | ------------------- | +| serviceName | string | Name of the service | + +### \_unregisterServiceName + +```solidity +function _unregisterServiceName(string serviceName) internal virtual +``` + +_Removes a service by its name. This function calculates the hash of the +service name and removes it from the registry._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------ | ------------------- | +| serviceName | string | Name of the service | + +### getRegisteredServiceNameByHash + +```solidity +function getRegisteredServiceNameByHash(bytes32 serviceHash) public view returns (string serviceName) +``` + +_Returns the name of a service by its hash._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ------------------- | +| serviceHash | bytes32 | Hash of the service | + +### getRegisteredServiceHashByName + +```solidity +function getRegisteredServiceHashByName(string serviceName) public view returns (bytes32 serviceHash) +``` + +_Returns the hash of a service by its name._ + +#### Parameters + +| Name | Type | Description | +| ----------- | ------ | ------------------- | +| serviceName | string | Name of the service | + +### getAllRegisteredServiceHashes + +```solidity +function getAllRegisteredServiceHashes() public view returns (bytes32[] services) +``` + +_Returns all registered service hashes._ + +### getAllRegisteredServiceNames + +```solidity +function getAllRegisteredServiceNames() public view returns (string[] services) +``` + +_Returns all registered service names._ + +## Dummy + +### getVersion + +```solidity +function getVersion() public pure returns (string) +``` + +## NullUSD + +### constructor + +```solidity +constructor() public +``` + +## ICaminoAdmin + +### getKycState + +```solidity +function getKycState(address account) external view returns (uint256) +``` + +## KYCUtils + +### ADMIN_ADDR + +```solidity +address ADMIN_ADDR +``` + +Admin contract address + +### KYC_VERIFIED + +```solidity +uint256 KYC_VERIFIED +``` + +Constants for KYC states + +### KYC_EXPIRED + +```solidity +uint256 KYC_EXPIRED +``` + +### KYB_VERIFIED + +```solidity +uint256 KYB_VERIFIED +``` + +### NotKYCVerified + +```solidity +error NotKYCVerified(address account) +``` + +Errors + +### NotKYBVerified + +```solidity +error NotKYBVerified(address account) +``` + +### NotVerified + +```solidity +error NotVerified(address account) +``` + +### getKYCState + +```solidity +function getKYCState(address account) internal view returns (uint256) +``` + +_Returns KYC state from the CaminoAdmin contract_ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### isKYCVerified + +```solidity +function isKYCVerified(address account) internal view returns (bool) +``` + +_Returns true if the address is KYC verified_ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### isKYBVerified + +```solidity +function isKYBVerified(address account) internal view returns (bool) +``` + +_Returns true if the address is KYB verified_ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### isVerified + +```solidity +function isVerified(address account) internal view returns (bool) +``` + +_Returns true if the address is KYC or KYB verified_ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### requireKYCVerified + +```solidity +function requireKYCVerified(address account) internal view +``` + +_Reverts with `NotKYCVerified(account)` if the account is not KYC verified._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### requireKYBVerified + +```solidity +function requireKYBVerified(address account) internal view +``` + +_Reverts with `NotKYBVerified(account)` if the account is not KYB verified._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | + +### requireVerified + +```solidity +function requireVerified(address account) internal view +``` + +_Reverts with `NotVerified(account)` if the account is not KYC or KYB verified._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------- | +| account | address | address to check the state | diff --git a/hardhat.config.js b/hardhat.config.js index 54af56b..3f8b76f 100644 --- a/hardhat.config.js +++ b/hardhat.config.js @@ -1,6 +1,7 @@ require("@nomicfoundation/hardhat-toolbox"); require("@openzeppelin/hardhat-upgrades"); require("hardhat-contract-sizer"); +require("solidity-docgen"); /** @type import('hardhat/config').HardhatUserConfig */ module.exports = { @@ -56,4 +57,9 @@ module.exports = { }, ], }, + docgen: { + path: "./docs", + pages: "single", + runOnCompile: true, + }, }; diff --git a/package.json b/package.json index e89babd..9e92175 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "test": "REPORT_GAS=true yarn hardhat test", "compile": "yarn hardhat compile", "format": "yarn prettier --write .", + "docgen": "yarn hardhat docgen && yarn prettier --write docs/", "lint": "yarn lint:prettier && yarn lint:eslint && yarn lint:solhint", "lint:prettier": "yarn prettier --check .", "lint:eslint": "yarn eslint .", @@ -35,6 +36,7 @@ "prettier": "^3.3.3", "prettier-plugin-solidity": "^1.3.1", "solidity-coverage": "^0.8.0", + "solidity-docgen": "^0.6.0-beta.36", "typechain": "^8.3.0" } } diff --git a/yarn.lock b/yarn.lock index e125bf7..577e11c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2475,7 +2475,7 @@ graceful-fs@^4.1.2, graceful-fs@^4.1.6, graceful-fs@^4.2.0, graceful-fs@^4.2.4: resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3" integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ== -handlebars@^4.0.1: +handlebars@^4.0.1, handlebars@^4.7.7: version "4.7.8" resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.8.tgz#41c42c18b1be2365439188c77c6afae71c0cd9e9" integrity sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ== @@ -3851,7 +3851,7 @@ solc@0.8.26: semver "^5.5.0" tmp "0.0.33" -solidity-ast@^0.4.51: +solidity-ast@^0.4.38, solidity-ast@^0.4.51: version "0.4.56" resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.56.tgz#94fe296f12e8de1a3bed319bc06db8d05a113d7a" integrity sha512-HgmsA/Gfklm/M8GFbCX/J1qkVH0spXHgALCNZ8fA8x5X+MFdn/8CP2gr5OVyXjXw6RZTPC/Sxl2RUDQOXyNMeA== @@ -3888,6 +3888,14 @@ solidity-coverage@^0.8.0: shelljs "^0.8.3" web3-utils "^1.3.6" +solidity-docgen@^0.6.0-beta.36: + version "0.6.0-beta.36" + resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.36.tgz#9c76eda58580fb52e2db318c22fe3154e0c09dd1" + integrity sha512-f/I5G2iJgU1h0XrrjRD0hHMr7C10u276vYvm//rw1TzFcYQ4xTOyAoi9oNAHRU0JU4mY9eTuxdVc2zahdMuhaQ== + dependencies: + handlebars "^4.7.7" + solidity-ast "^0.4.38" + source-map-support@^0.5.13: version "0.5.21" resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.5.21.tgz#04fe7c7f9e1ed2d662233c28cb2b35b9f63f6e4f"