Flush Custom Metadata Function

This section details the flushCustomMetadata function within the MNS service. This function allows the current owner (_user) of a registered identity (_identity, typically a username) to remove all custom metadata entries associated with that identity in a single transaction.

To flush all custom metadata, the identity owner must authorize the action with their signature and pay a fee via the EVVM contract. This fee is typically determined by a function like getPriceToFlushCustomMetadata(_identity) (which might be proportional to the number of entries being removed or a flat rate, e.g., a multiple of the base MATE reward per entry or in total). 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: flushCustomMetadata(address,uint256,string,uint256,bytes,uint256,bool,bytes)
Function Selector: 0x3e7899a1

Parameters

Parameter Name	Type	Description
_user	address	The address of the current owner of the _identity who is authorizing the flush.
_nonce	uint256	The owner's (_user) nonce specific to the MNS contract (mateNameServiceNonce) for this flushCustomMetadata action's replay protection.
_identity	string	The registered identity (e.g., username) from which all custom metadata entries will be flushed.
_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 all metadata 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.

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 always required, these EVVM parameters are mandatory.
• The MNS add custom metadata signature (_signature) must be generated by the current owner (_user) and follows the Flush Custom Metadata Signature Structure.

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. 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 Custom Metadata Signature Validation: Verifies the _signature provided by _user (the owner) against the reconstructed message hash using an internal function (e.g., verifyMessageSignedForFlushCustomMetadata). This function should use the appropriate signature structure for flushing. Reverts if the signature is invalid.
5. Payment Execution (EVVM):
   • Calculates the required fee to flush metadata (flushFee) in MATE tokens, typically by calling an internal function like getPriceToFlushCustomMetadata(_identity) (which might account for the number of entries being flushed multiplied by 10 times seeMateReward()).
   • Calls an internal helper function (e.g., makePay) to initiate a payment through the EVVM contract's payMateStaker (or similar) 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. Custom Metadata Removal (Flush): Removes all existing custom metadata entries associated with the _identity.
7. Reward Distribution (to Executor): Calls an internal helper function (e.g., makeCaPay) to distribute rewards in MATE tokens directly to msg.sender (the executor). The rewards typically consist of:
   • A base MATE reward share that might be proportional to the work done (e.g., 5 * seeMateReward() multiplied by the number of custom metadata entries that were removed). (The fee structure in Step 5 and this reward structure must be consistent).
   • 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.