@evvm/testnet-contracts 2.2.2 → 2.3.0

package/contracts/nameService/lib/ErrorsLib.sol

@@ -3,19 +3,153 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title ErrorsLib
+ * @author Mate labs
+ * @notice Library containing custom error definitions exclusively for the NameService.sol contract
+ * @dev This library defines all custom errors used by the NameService.sol contract.
+ *      Custom errors are more gas-efficient than require statements with strings
+ *      and provide better error handling in client applications.
+ *
+ * Error Categories:
+ * - Access Control: Errors related to ownership and admin permissions
+ * - Validation: Errors for invalid usernames, signatures, and input validation
+ * - Registration: Errors specific to username registration and pre-registration
+ * - Marketplace: Errors for offer management and username trading
+ * - Metadata: Errors for custom metadata operations
+ * - Time-Lock: Errors for governance and renewal timing
+ *
+ * @custom:scope Exclusive to the NameService.sol contract
+ * @custom:security All errors provide clear failure reasons without exposing sensitive data
+ */
 library ErrorsLib {
+    //█ Access Control Errors ███████████████████████████████████████████████████
+
+    /**
+     * @notice Thrown when a function restricted to admin is called by a non-admin address
+     * @dev Used in functions with the `onlyAdmin` modifier
+     */
     error SenderIsNotAdmin();
+
+    /**
+     * @notice Thrown when an operation is attempted by someone other than the username owner
+     * @dev Used in functions that modify username data or accept offers
+     */
     error UserIsNotOwnerOfIdentity();
-    error NonceAlreadyUsed();
+
+    /**
+     * @notice Thrown when an operation is attempted by someone other than the offer creator
+     * @dev Used in withdrawOffer to ensure only the offerer can withdraw their own offer
+     */
+    error UserIsNotOwnerOfOffer();
+
+    /**
+     * @notice Thrown when the proposed admin tries to accept before meeting requirements
+     * @dev Part of the time-delayed admin transfer mechanism
+     */
+    error SenderIsNotProposedAdmin();
+
+    //█ Validation Errors ███████████████████████████████████████████████████████
+
+    /**
+     * @notice Thrown when the provided EIP-191 signature is invalid or doesn't match the signer
+     * @dev Used in all operations requiring signature verification
+     */
     error InvalidSignatureOnNameService();
+
+    /**
+     * @notice Thrown when a username doesn't meet format requirements
+     * @dev Username must be 4+ characters, start with letter, contain only alphanumeric
+     */
     error InvalidUsername();
+
+    /**
+     * @notice Thrown when an amount parameter is zero but should be positive
+     * @dev Used in makeOffer to ensure offers have value
+     */
+    error AmountMustBeGreaterThanZero();
+
+    /**
+     * @notice Thrown when a custom metadata key is invalid
+     * @dev Used when trying to remove metadata with a key that doesn't exist
+     */
+    error InvalidKey();
+
+    /**
+     * @notice Thrown when attempting to add empty custom metadata
+     * @dev Custom metadata value cannot be an empty string
+     */
+    error EmptyCustomMetadata();
+
+    /**
+     * @notice Thrown when a proposed address or configuration is invalid
+     * @dev Used in admin proposal functions
+     */
+    error InvalidAdminProposal();
+
+    /**
+     * @notice Thrown when the EVVM address being proposed is invalid
+     * @dev Used when updating the EVVM contract integration address
+     */
+    error InvalidEvvmAddress();
+
+    /**
+     * @notice Thrown when the withdrawal amount is invalid or exceeds available balance
+     * @dev Used in token withdrawal functions
+     */
+    error InvalidWithdrawAmount();
+
+    //█ Registration and Time-Based Errors █████████████████████████████████████
+
+    /**
+     * @notice Thrown when attempting to register a username that is already taken
+     * @dev Usernames are unique and cannot be registered twice
+     */
     error UsernameAlreadyRegistered();
+
+    /**
+     * @notice Thrown when the pre-registration doesn't exist or has expired
+     * @dev Pre-registration must be completed within 30 minutes and by the same user
+     */
     error PreRegistrationNotValid();
-    error MakeOfferVerificationFailed();
-    error UserIsNotOwnerOfOffer();
-    error AcceptOfferVerificationFailed();
-    error RenewUsernameVerificationFailed();
-    error EmptyCustomMetadata();
-    error InvalidKey();
-    error FlushUsernameVerificationFailed();
+
+    /**
+     * @notice Thrown when a timestamp/date is set to before the current time
+     * @dev Used for offer expiration dates and other future-dated operations
+     */
+    error CannotBeBeforeCurrentTime();
+
+    /**
+     * @notice Thrown when attempting operations on an expired username
+     * @dev Username ownership expires after the expireDate timestamp
+     */
+    error OwnershipExpired();
+
+    /**
+     * @notice Thrown when trying to renew a username beyond the maximum allowed period
+     * @dev Usernames can only be renewed up to 100 years in advance
+     */
+    error RenewalTimeLimitExceeded();
+
+    /**
+     * @notice Thrown when attempting to execute a time-locked action prematurely
+     * @dev Used in governance functions with time-delay requirements
+     */
+    error LockTimeNotExpired();
+
+    //█ Marketplace and Offer Errors ███████████████████████████████████████████
+
+    /**
+     * @notice Thrown when trying to accept or interact with an expired or non-existent offer
+     * @dev Offers expire at their expireDate timestamp or when offerer is address(0)
+     */
+    error OfferInactive();
+
+    //█ Identity Type Errors ██████████████████████████████████████████████████
+
+    /**
+     * @notice Thrown when an operation requiring a fully registered username is attempted on a pre-registration
+     * @dev Pre-registrations have flagNotAUsername = 0x01, full usernames have 0x00
+     */
+    error IdentityIsNotAUsername();
 }

package/contracts/nameService/lib/IdentityValidation.sol

@@ -3,6 +3,27 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title IdentityValidation
+ * @author Mate labs
+ * @notice Library for validating usernames, emails, and phone numbers in the NameService system
+ * @dev Provides pure validation functions for identity-related strings used in NameService.sol.
+ *      All validations are performed at the byte level for gas efficiency and precision.
+ *
+ * Validation Types:
+ * - Username: Alphanumeric identifiers with specific length and format requirements
+ * - Email: Standard email format validation with prefix, domain, and TLD checks
+ * - Phone Number: Numeric phone numbers with length constraints
+ *
+ * Character Validation:
+ * - Uses ASCII byte ranges for precise character classification
+ * - Supports letters (A-Z, a-z), digits (0-9), and specific symbols
+ * - All checks performed without external dependencies for security
+ *
+ * @custom:scope Exclusive to NameService.sol contract
+ * @custom:security All functions are pure with no external calls
+ * @custom:gas-optimization Byte-level operations for maximum efficiency
+ */
 library IdentityValidation{
     /**
      * @notice Validates username format according to system rules

package/contracts/nameService/lib/NameServiceStructs.sol

@@ -3,12 +3,37 @@
 
 pragma solidity ^0.8.0;
 
+/**
+ * @title NameServiceStructs
+ * @author Mate labs
+ * @notice Library of data structures used exclusively by the NameService.sol contract
+ * @dev This contract defines the type system for the NameService.sol contract,
+ *      providing structured data types for identity management, marketplace operations,
+ *      and governance proposals. These structures are not shared with external services.
+ *
+ * Structure Categories:
+ * - Identity Structures: IdentityBaseMetadata for username registration data
+ * - Marketplace Structures: OfferMetadata for username trading
+ * - Governance Structures: AddressTypeProposal, UintTypeProposal, BoolTypeProposal for time-delayed changes
+ *
+ * @custom:inheritance This contract is inherited by NameService.sol
+ * @custom:scope Exclusive to the NameService.sol contract
+ */
 abstract contract NameServiceStructs {
+    //░▒▓█ Governance Proposal Structures ███████████████████████████████████████████████▓▒░
+
     /**
-     * @dev Struct for managing address change proposals with time delay
-     * @param current Currently active address
-     * @param proposal Proposed new address waiting for approval
-     * @param timeToAccept Timestamp when the proposal can be accepted
+     * @notice Time-delayed proposal structure for address-type governance changes
+     * @dev Used for admin changes and EVVM contract address updates with 1-day delay
+     *
+     * Governance Flow:
+     * 1. Admin proposes new address -> sets proposal and timeToAccept
+     * 2. Time delay passes (1 day)
+     * 3. Proposed address calls accept -> current is updated, proposal is cleared
+     *
+     * @param current Currently active address with the role/privilege
+     * @param proposal Proposed new address awaiting acceptance after time delay
+     * @param timeToAccept Timestamp after which the proposal can be accepted
      */
     struct AddressTypeProposal {
         address current;
@@ -17,10 +42,13 @@ abstract contract NameServiceStructs {
     }
 
     /**
-     * @dev Struct for managing uint256 value proposals with time delay
-     * @param current Currently active value
-     * @param proposal Proposed new value waiting for approval
-     * @param timeToAccept Timestamp when the proposal can be accepted
+     * @notice Time-delayed proposal structure for uint-type governance changes
+     * @dev Used for token withdrawal amount changes with time-delayed governance
+     *      Follows the same pattern as AddressTypeProposal for consistency
+     *
+     * @param current Currently active value for the parameter
+     * @param proposal Proposed new value awaiting acceptance after time delay
+     * @param timeToAccept Timestamp after which the proposal can be accepted
      */
     struct UintTypeProposal {
         uint256 current;
@@ -29,8 +57,10 @@ abstract contract NameServiceStructs {
     }
 
     /**
-     * @dev Struct for managing boolean flag changes with time delay
-     * @param flag Current boolean state
+     * @notice Time-delayed proposal structure for boolean flag changes
+     * @dev Used for feature toggles and system state changes requiring governance
+     *
+     * @param flag Current boolean state of the feature/setting
      * @param timeToAcceptChange Timestamp when the flag change can be executed
      */
     struct BoolTypeProposal {
@@ -38,13 +68,26 @@ abstract contract NameServiceStructs {
         uint256 timeToAcceptChange;
     }
 
+    //░▒▓█ Identity Management Structures ███████████████████████████████████████████████▓▒░
+
     /**
-     * @dev Core metadata for each registered identity/username
-     * @param owner Address that owns this identity
-     * @param expireDate Timestamp when the registration expires
-     * @param customMetadataMaxSlots Number of custom metadata entries stored
-     * @param offerMaxSlots Maximum number of offers that have been made
-     * @param flagNotAUsername Flag indicating if this is a pre-registration (0x01) or actual username (0x00)
+     * @notice Core metadata for each registered identity/username
+     * @dev Stores essential registration information and ownership details
+     *
+     * Registration States:
+     * - flagNotAUsername = 0x01: Pre-registration (temporary reservation)
+     * - flagNotAUsername = 0x00: Full username registration (active identity)
+     *
+     * Ownership Model:
+     * - Owner has full control over the username
+     * - Ownership expires at expireDate (renewable up to 100 years)
+     * - Can be transferred through marketplace offers
+     *
+     * @param owner Address that owns this identity/username
+     * @param expireDate Timestamp when the registration expires (renewable)
+     * @param customMetadataMaxSlots Number of custom metadata entries stored for this identity
+     * @param offerMaxSlots Highest offer ID that has been created for this username
+     * @param flagNotAUsername 0x01 for pre-registration, 0x00 for full username
      */
     struct IdentityBaseMetadata {
         address owner;
@@ -54,11 +97,24 @@ abstract contract NameServiceStructs {
         bytes1 flagNotAUsername;
     }
 
+    //░▒▓█ Marketplace Structures ███████████████████████████████████████████████████████▓▒░
 
     /**
-     * @dev Metadata for marketplace offers on usernames
-     * @param offerer Address making the offer
-     * @param expireDate Timestamp when the offer expires
+     * @notice Metadata for marketplace offers on usernames
+     * @dev Represents a locked offer to purchase a username at a specific price
+     *
+     * Offer Lifecycle:
+     * 1. Created: Tokens are locked in contract (after 0.5% marketplace fee deduction)
+     * 2. Active: Can be accepted by owner or withdrawn by offerer before expiration
+     * 3. Expired/Completed: offerer set to address(0), tokens released
+     *
+     * Fee Structure:
+     * - 0.5% marketplace fee deducted from offer amount
+     * - Remaining 99.5% locked for potential acceptance
+     * - Additional fees for stakers processing the transaction
+     *
+     * @param offerer Address that created and can withdraw this offer
+     * @param expireDate Timestamp when the offer expires and can no longer be accepted
      * @param amount Amount offered in Principal Tokens (after 0.5% marketplace fee deduction)
      */
     struct OfferMetadata {