Flush Username Function

This section details the flushUsername function within the MNS service. This function allows the current owner (_user) of a registered identity (_identity, typically a username) to permanently delete the username registration and all of its associated data. This is an irreversible action that makes the username available for registration again by others.

To flush a username, the owner must authorize the action with their signature and pay a fee via the EVVM contract (determined by a function like getPriceToFlushUsername(_identity)). An optional priority fee can also be paid to the executor. This function must be executed by an sMATE staker (msg.sender).

Function Type: external
Function Signature: flushUsername(address,string,uint256,uint256,bytes,uint256,bool,bytes)
Function Selector: 0xd22c816c

Parameters

Parameter Name	Type	Description
_user	address	The address of the current owner of the _identity who is authorizing the permanent deletion.
_nonce	uint256	The owner's (_user) nonce specific to the MNS contract (mateNameServiceNonce) for this flushUsername action's replay protection.
_identity	string	The registered identity (e.g., username) to be permanently flushed from the system.
_priorityFeeForFisher	uint256	Optional fee (in MATE) paid by the owner (_user) to the msg.sender (staker executor) via the EVVM contract for prioritized processing of this transaction.
_signature	bytes	The EIP-191 signature from the owner (_user) authorizing this flush username action (typically signing _identity and _nonce).
_nonce_Evvm	uint256	Required. The owner's (_user) nonce for the EVVM payMateStaker call used to pay the total calculated Flush Fee + Priority Fee.
_priority_Evvm	bool	Required. Priority flag (sync/async) for the EVVM payMateStaker call paying the fees.
_signature_Evvm	bytes	Required. The owner's (_user) signature authorizing the EVVM payMateStaker call to transfer the total calculated Flush Fee + Priority Fee.

note

• The EVVM payment signature (_signature_Evvm) covers the total amount (calculated Flush Fee + _priorityFeeForFisher) and is paid by the identity owner (_user). It uses the Single Payment Signature Structure. Since a flush fee is required, these EVVM parameters are mandatory.
• The MNS flush username signature (_signature) must be generated by the current owner (_user) and follows the Flush Username Signature Structure.
• The EVVM parameters facilitate the transfer of the required flush fee and any optional priority fee from the owner (_user).

Execution Methods

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. The steps execute in the specified order.

1. Identity Ownership Verification: Checks if the provided _user address is the registered owner of the _identity. Reverts if _user is not the owner.
2. MNS Nonce Verification: Checks if the provided _nonce is unused for the _user (the owner) using the verifyIfNonceIsAvailable modifier. Reverts if the nonce is already used.
3. Executor Staker Verification: Verifies that the msg.sender (the executor submitting the transaction) is an sMATE staker by calling isMateStaker() on the associated EVVM contract. Reverts if msg.sender is not a staker.
4. Flush Username Signature Validation: Verifies the _signature provided by _user (the owner) against the reconstructed message hash using an internal function (e.g., verifyMessageSignedForFlushUsername). Reverts if the signature is invalid according to the Flush Username Signature Structure.
5. Payment Execution (EVVM):
   • Calculates the required fee to flush the username (flushFee) in MATE tokens, typically by calling an internal function like getPriceToFlushUsername(_identity).
   • Calculates the totalPayment = flushFee + _priorityFeeForFisher.
   • Calls an internal helper function (e.g., makePay) to initiate a payment through the EVVM contract's payMateStaker function.
   • Uses the provided _nonce_Evvm, _priority_Evvm, and _signature_Evvm (signed by _user) for EVVM authorization.
   • This action attempts to transfer the totalPayment amount of MATE tokens from the _user address via the EVVM contract. The _priorityFeeForFisher portion is directed towards msg.sender, while the flushFee portion is typically routed to the MNS treasury/fee address.
   • Reverts if this EVVM payment process fails.
6. Username Deletion (Flush): Permanently removes the username registration and all associated data. This involves deleting the main identityDetails[_identity] entry and any associated identityCustomMetadata for the _identity. This makes the username available for registration again.
7. Reward Distribution (to Executor): Checks if the executor (msg.sender) is an sMATE staker. If msg.sender is a staker:
   • Calls an internal helper function (e.g., makeCaPay) to distribute rewards in MATE tokens directly to msg.sender.
   • The rewards typically consist of:
     • A portion of the flushFee paid in Step 5 (e.g., 50% of the flushFee).
     • The full _priorityFeeForFisher, if it was greater than zero and successfully paid in Step 5.
8. Nonce Management: Marks the MNS _nonce (provided as an input parameter for this transaction) as used for the _user address within the mateNameServiceNonce mapping.