Add Custom Metadata Function

This section details the addCustomMetadata function within the MNS service. This function allows the current owner (_user) of a registered identity (_identity, typically a username) to associate a custom string value (_value) with their identity.

To add custom metadata, the identity owner must authorize the action with a signature and pay a fee (typically 10 times the base MATE reward, determined by getPriceToAddCustomMetadata()) via the EVVM contract. 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: addCustomMetadata(address,uint256,string,string,uint256,bytes,uint256,bool,bytes)
Function Selector: 0xe6efeffa

Parameters

Parameter Name	Type	Description
_user	address	The address of the current owner of the _identity who is adding the metadata.
_nonce	uint256	The owner's (_user) nonce specific to the MNS contract (mateNameServiceNonce) for this addCustomMetadata action's replay protection.
_identity	string	The registered identity (e.g., username) to which the custom metadata will be added/associated.
_value	string	The custom metadata value (as a string) to be stored. Must not be empty. See "Recommended Metadata Value Format" below for suggested structure.
_priorityFeeForFisher	uint256	Optional fee (in MATE) paid by the owner (_user) to the msg.sender (staker executor) via the EVVM contract for prioritized processing.
_signature	bytes	The EIP-191 signature from the owner (_user) authorizing this add metadata action
_nonce_Evvm	uint256	Required. The owner's (_user) nonce for the EVVM payMateStaker call used to pay the Metadata 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 paying the Metadata Fee + Priority Fee.

note

• The EVVM payment signature (_signature_Evvm) covers the total amount (calculated Metadata Fee + _priorityFeeForFisher) and is paid by the identity owner (_user). It uses the Single Payment Signature Structure. Since a metadata 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 Add Custom Metadata Signature Structure.

Metadata Storage Mechanism

Custom metadata is stored associated with an identity. The system allows flexibility in the format of the _value string. However, a recommended structure exists to promote interoperability and standardized parsing.

Recommended Metadata Value Format

While not enforced on-chain, adhering to this format for the _value string is highly recommended:

[schema]:[subschema]>[value]

• Separators:
  • : separates the schema and subschema.
  • > separates the schema/subschema prefix from the actual value data.
• Schema: A category identifier, preferably based on standard vocabularies like Schema.org (e.g., email, memberOf, url).
• Subschema: Provides additional context within the main schema (optional, e.g., dev, work, personal).
• Padding: If schema or subschema has fewer than 5 characters, it should be right-padded with spaces to exactly 5 characters. This aids off-chain parsing.
• Social Media: Use schema = "socialMedia" (padded: "socialMedia") and subschema = <network_name> (e.g., x , linkedin, github - padded if needed). The value is the username/handle on that network.

Examples:

• memberOf: >EVVM (Schema: memberOf, Value: EVVM)
• socialMedia:x >jistro (Schema: socialMedia, Subschema: x, Value: jistro)
• email :dev >jistro@evvm.org (Schema: email, Subschema: dev, Value: jistro@evvm.org)
• email :callme>contact@jistro.xyz (Schema: email, Subschema: callme, Value: contact@jistro.xyz)
• url :blog >https://blog.example.com (Schema: url, Subschema: blog, Value: https://blog.example.com)

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 _identity is owned by the _user. Reverts if not.
2. MNS Nonce Verification: Checks if the provided _nonce is unused for the _user (offeror) using the verifyIfNonceIsAvailable modifier. Reverts if used.
3. Executor Staker Verification: Verifies msg.sender is an sMATE staker via EVVM's isMateStaker(). Reverts if not.
4. Add Custom Metadata Signature Validation: Verifies the _signature provided by _user (authorizing this MNS action) using verifyMessageSignedForAddCustomMetadata. Reverts if invalid according to the Add Custom Metadata Signature Structure.
5. Custom Metadata Length Validation: Checks that the provided _value string has a length greater than 0. Reverts if the value is empty.
6. Payment execution: Calls makePay to transfer the payment of 10 times of the mate reward using the getPriceToAddCustomMetadata function and _priorityFee of MATE tokens from _user to the service via the EVVM contract. Reverts if the payment fails.
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 derived from the metadata fee ( 5 * seeMateReward()). (Note: This implies 50% of the standard 10x fee goes to the executor as reward, verify exact distribution).
   • The full _priorityFeeForFisher, if it was greater than zero and successfully paid in Step 6.
8. Custom Metadata Storage: Stores the provided _value string associated with the _identity. This is typically done by adding the _value to a list or mapping for that identity (identityCustomMetadata[_identity][slot] = _value) and incrementing a counter (identityDetails[_identity].customMetadataMaxSlots) that tracks the number of metadata entries for that identity.
9. Nonce Management: Marks the MNS _nonce (provided as an input parameter for this transaction) as used for the _user address within the mateNameServiceNonce mapping.