Skip to main content

Username Functions

Important

This part of the documentation is still under construction.

This section provides information about functions related exclusively to usernames managment in the MNS service.

Those functions can be executed by identitys flagges as username and his registration.

preRegistrationUsername​

Function Type: external
Function Signature: preRegistrationUsername(address,uint256,bytes32,uint256,bytes,uint256,bool,bytes)
Function Selector: 0x393b9c6f

This function is used to pre-register a username to prevent front-running attacks. A user (_user) commits to a hash (_hashUsername) derived from their desired username and a secret number. This function must be executed by an sMATE staker (msg.sender).

Parameters​

ParameterTypeDescription
_useraddressThe address of the end-user initiating the pre-registration.
_nonceuint256The user's nonce specific to this MNS service (mateNameServiceNonce) for replay protection of this pre-registration action.
_hashUsernamebytes32The pre-commitment hash (see Hash Username Structure below)
_priorityFeeForFisheruint256Optional fee (in MATE tokens) paid by _user to the msg.sender (staker executing the transaction) via the EVVM contract
_signaturebytesThe EIP-191 signature from _user authorizing this pre-registration action
_nonce_Evvmuint256Required if _priorityFeeForFisher > 0. _user's nonce for the EVVM payMateStaker function call used to pay the fee.
_priority_EvvmboolRequired if _priorityFeeForFisher > 0. Priority flag (sync/async) for the EVVM payMateStaker function call.
_signature_EvvmbytesRequired if _priorityFeeForFisher > 0. _user's signature authorizing the EVVM payMateStaker call to transfer the fee.
note

Hash Username Structure​

The _hashUsername is calculated off-chain by the user. The hash is calculated using SHA3-256 with the following structure:

keccak256(abi.encodePacked(username, clowNumber));

Where:

  • username (string): The desired username.
  • clowNumber (uint256): A secret number chosen by the user, required later for the registrationUsername function.

Execution Methods​

This function must be executed by an address (msg.sender) that is an sMATE staker.

Fisher Execution​

When the executor is the fisher:

  1. The user sends the payment request to the fishing spot
  2. The fisher captures the transaction and validates all parameters
  3. The fisher submits the transaction to the contract for processing

Direct Execution​

When the executor is the user or a service:

  1. The user/service submits their transaction directly to the contract

Workflow​

Failure at validation steps typically reverts the transaction.

  1. MNS Nonce Verification: Checks if _nonce is unused for _user in mateNameServiceNonce. Reverts if used.

  2. Executor Staker Verification: Verifies msg.sender is an sMATE staker via EVVM's isMateStaker(). Reverts if not.

  3. Pre-registration Signature Verification: Verifies _signature (authorizing this MNS action) using verifyMessageSignedForPreRegistrationUsername. Reverts if invalid.

  4. Priority Fee Processing: If _priorityFeeForFisher > 0:

    • Calls an internal helper (e.g., makePay) to trigger the EVVM payMateStaker function.
    • Uses _nonce_Evvm, _priority_Evvm, _signature_Evvm for the EVVM call authorization.

When processing the priority fee:

  • The fee amount must be assigned to the amount variable
  • The priorityFee variable should be set to 0
  • MATE should be used as the token

  1. Username Pre-Registration: Stores the commitment _hashUsername, associated _user, and timestamp/block number in the identityDetails mapping, keyed by a string like the following:

    string.concat("@", AdvancedStrings.bytes32ToString(_hashUsername))

  2. Nonce Management: The system marks the user's nonce as used in the mateNameServiceNonce mapping.

  3. Reward Distribution (to Executor): Calls an internal helper (e.g., makeCaPay) to send rewards in MATE tokens to msg.sender (the executor). Rewards include:

    • A base MATE reward fetched from EVVM (e.g., via seeMateReward()).
    • The _priorityFeeForFisher (if paid successfully in Step 4).

preRegistrationUsername fisher execution preRegistrationUsername direct execution

registrationUsername​

Function Type: external
Function Signature: registrationUsername(address,uint256,string,uint256,bytes,uint256,uint256,bool,bytes)
Function Selector: 0xd134f8b4

Completes the second phase (reveal phase) of username registration. The user reveals the _username and _clowNumber to prove ownership of a prior pre-registration commit. This function handles the registration payment and finalizes the username association.

Requirements:

  • A valid pre-registration for the _username hash must exist, associated with the _user.
  • A minimum time period (e.g., 30 minutes) must have passed since pre-registration.
  • The _user must pay a registration fee (e.g., 100 times the base MATE reward) via the EVVM contract.

Parameters​

ParameterTypeDescription
_useraddressThe address of the end-user registering the username (must match pre-registration).
_nonceuint256The user's MNS nonce (mateNameServiceNonce) for this registration action.
_usernamestringThe desired username being registered (must match the pre-registered hash when combined with _clowNumber).
_clowNumberuint256The secret number used during pre-registration hash calculation. Reveals the pre-image.
_signaturebytesThe EIP-191 signature from _user authorizing this registration action (signing _username, _clowNumber, _nonce).
_priorityFeeForFisheruint256Optional fee (in MATE) paid by _user to msg.sender for processing this transaction, paid via EVVM alongside the registration fee.
_nonce_Evvmuint256_user's nonce for the EVVM payMateStaker function call used to pay the total amount (registration fee + priority fee).
_priority_EvvmboolPriority flag (sync/async) for the EVVM function call.
_signature_Evvmbytes_user's signature authorizing the EVVM call to transfer the total payment.
note

Execution Methods​

Can be executed by any address (msg.sender). Rewards are only distributed if the executor is an sMATE staker.

Fisher Execution​

When the executor is the fisher:

  1. The user sends the payment request to the fishing spot
  2. The fisher captures the transaction and validates all parameters
  3. The fisher submits the transaction to the contract for processing

Direct Execution​

When the executor is the user or a service:

  1. The user/service submits their transaction directly to the contract

Workflow​

Failure at validation steps typically reverts the transaction.

  1. MNS Nonce Verification: Checks if _nonce is unused for _user using verifyIfNonceIsAvailable modifier. Reverts if used.
  2. Username Validation: Unless msg.sender is an admin, calls isValidUsername to check character set and length constraints for _username. Reverts if invalid.
  3. Username Availability Check: Calls isUsernameAvailable to ensure _username is not already registered. Reverts if unavailable.
  4. Registration Signature Verification: Verifies _signature (authorizing this MNS action) using verifyMessageSignedForRegistrationUsername. Reverts if invalid.
  5. Registration Payment:
    • Calculates the required registration fee (100 * seeMateReward() from EVVM).
    • Calculates the total payment amount = Registration Fee + _priorityFeeForFisher.
    • Calls an internal helper (makePay) to trigger the EVVM payMateStaker function.
    • Uses _nonce_Evvm, _priority_Evvm, _signature_Evvm for EVVM authorization.
    • Transfers the total payment amount in MATE tokens from _user to the service via the EVVM contract. Reverts if the EVVM payment fails.
  6. Pre-Registration Check & Validation:
    • Reconstructs the hash: expectedHash = keccak256(abi.encodePacked(_username, _clowNumber)).
    • Retrieves the pre-registration data stored under "@<expectedHash_string>".
    • Verifies that the pre-registration exists, belongs to _user, and that the required waiting period (e.g., 30 minutes) has passed since its timestamp. Reverts on any mismatch or if the waiting period is not met.
  7. Username Registration: The function registers the username and basic metadata in the identityDetails mapping.
  8. MNS Nonce Update: Marks _nonce as used for _user in mateNameServiceNonce.
  9. Reward Distribution (Conditional):
    • Checks if msg.sender is an sMATE staker via EVVM's isMateStaker().
    • If msg.sender is a staker, calls an internal helper (e.g., makeCaPay) to send rewards in MATE tokens to msg.sender. Rewards typically include:
      • A portion of the registration fee 50 * seeMateReward().
      • The _priorityFeeForFisher (if any was specified and paid in Step 5).
  10. Pre-Registration Cleanup: Deletes the original pre-registration data (entry keyed by "@<hash_string>").

registrationUsername fisher execution

registrationUsername direct execution

makeOffer​

Function Type: external
Function Signature: makeOffer(address,uint256,string,uint256,uint256,uint256,bytes,uint256,bool,bytes) Function Selector: 0x52649c2e

This function is used to make an offer for a username. A user (_user) makes an offer for a username (_username) with an amount of MATE (_amount) and an expiration date (_expireDate).

Parameters​

ParameterTypeDescription
_useraddressThe address of the end-user making the offer (offeror).
_nonceuint256The offeror's nonce specific to this MNS contract (mateNameServiceNonce) for replay protection of this makeOffer action.
_usernamestringThe target username for which the offer is being made.
_amountuint256The total gross amount of MATE tokens the offeror commits. This includes the actual offer value plus a 0.5% service fee.
_expireDateuint256The Unix timestamp (seconds since epoch) when this offer automatically expires if not accepted or withdrawn.
_priorityFeeForFisheruint256Optional fee (in MATE) paid by _user to the msg.sender (staker executing the transaction) via the EVVM contract for prioritized processing.
_signaturebytesThe EIP-191 signature from _user authorizing this make offer action.
_nonce_Evvmuint256_user's nonce for the EVVM payMateStaker function call used to transfer the total payment.
_priority_EvvmboolPriority flag (sync/async) for the EVVM payMateStaker function call.
_signature_Evvmbytes_user's signature authorizing the EVVM payMateStaker call to transfer the total payment.
Signature Links & EVVM Payment
  • The EVVM payment signature (_signature_Evvm) covers the total amount (_amount + _priorityFeeForFisher) and uses the Single Payment Signature Structure.
  • The MNS make offer signature (_signature) follows the Make Offer Signature Structure.
  • The EVVM parameters facilitate the transfer of the offer funds and any optional priority fee from the offeror (_user).

Execution Methods​

This function must be executed by an address (msg.sender) that is an sMATE staker.

Fisher Execution​

When the executor is the fisher:

  1. The user sends the payment request to the fishing spot
  2. The fisher captures the transaction and validates all parameters
  3. The fisher submits the transaction to the contract for processing

Direct Execution​

When the executor is the user or a service:

  1. The user/service submits their transaction directly to the contract

Workflow​

Failure at validation steps typically reverts the transaction.

  1. MNS Nonce Verification: Checks if _nonce is unused for _user using the verifyIfNonceIsAvailable modifier. Reverts if used.
  2. Executor Staker Verification: Verifies msg.sender is an sMATE staker via EVVM's isMateStaker(). Reverts if not.
  3. Username Validation: Checks that _username exists and represents a registered username (e.g., identityDetails[_username].flagNotAUsername indicates it's a valid username type) using internal checks like verifyIfIdentityExists. Reverts if the username doesn't exist or isn't eligible for offers.
  4. Amount Validation: Checks if the gross _amount provided is greater than zero. Reverts if not.
  5. Make Offer Signature Validation: Verifies the _signature from _user (authorizing this MNS action) using verifyMessageSignedForMakeOffer. Reverts if invalid.
  6. Payment execution: Calls makePay to transfer the _amount and _priorityFee of MATE tokens from _user to the service via the EVVM contract. Reverts if the payment fails.
  7. Offer ID Search: Finds the next available sequential ID for an offer associated with the _username. Loops through existing offer slots until an empty one (address(0) offerer) is found.
  8. Offer Creation: Creates and stores the offer details in the usernameOffers mapping using the found offer ID. The stored data includes:
    • offerer: _user (address making the offer).
    • expireDate: _expireDate (Unix timestamp).
    • amount: The net offer amount (99.5% of the input _amount, representing the value available to the seller after the 0.5% fee).
  9. Reward Distribution (to Executor): Calls an internal helper (e.g., makeCaPay) to send rewards in MATE tokens to msg.sender (the executor). Rewards include:
    • A base MATE reward (e.g., 1 * seeMateReward() from EVVM).
    • The _priorityFeeForFisher (if any was specified and paid in Step 7).
    • A small percentage of the offer amount (e.g., 0.125% of the gross _amount).
  10. Username offers max slot check: Checks if the username offers max slot is reached after creating the offer. If reached, add one or if not skip this step.
  11. Nonce Management: The system marks the user's nonce as used in the mateNameServiceNonce mapping.