disperseCaPay Function

Function Type: external
Function Signature: disperseCaPay((uint256,address)[],address,uint256) Function Selector: 0xa7a096f6

The disperseCaPay function facilitates batch payments initiated by another smart contract (msg.sender). It enables the calling contract to trigger the distribution of a specified token from a designated from address to multiple recipients defined in toData within a single transaction.

This function operates with fewer restrictions compared to user-initiated disperse functions:

Key Features:

• Executor must be a Contract: The msg.sender calling this function must be a smart contract (verified via extcodesize).
• No sMATE Required (but Rewarded): The calling contract (msg.sender) does not need to be an sMATE staker, but if it is a staker, it can receive MATE rewards for successful execution.
• No EVVM Nonce: This function does not utilize the EVVM's user-specific nonce system (sync or async).
• No MNS Signature: Does not require an EIP-191 signature from the msg.sender (the contract) for authorization.
• No Priority Fee: Does not involve a priorityFee mechanism.

Parameters

Parameter	Type	Description
toData	DispersePayMetadata[]	An array detailing each recipient's destination address and the amount they should receive. See struct and warning below.
token	address	The contract address of the ERC20 token being dispersed.
amount	uint256	The total amount of token to be distributed across all recipients. Must equal the sum of individual amounts specified within toData.

DispersePayMetadata Struct

Defines the payment details for a single recipient within the toData array.

struct DispersePayMetadata {
   uint256 amount;    
   address to_address; 
   string to_identity; 
}

Field	Type	Description
amount	uint256	The amount of token to send to this recipient.
to_address	address	The recipient's direct wallet address. Recommended.
to_identity	string	Usage Not Recommended (See Warning).

Use to_address, Not to_identity

For disperseCaPay, it is strongly recommended to only use the to_address field within the DispersePayMetadata struct for each recipient. Providing a non-empty to_identity may lead to unexpected behavior or transaction reverts, as this function might be optimized to bypass identity resolution. Always populate to_address directly.

Workflow

1. CA Verification: Validates that the transaction sender (msg.sender) is indeed a smart contract by checking if its extcodesize is greater than 0. Reverts if msg.sender is an Externally Owned Account (EOA).

2. Balance Check: Verifies that the specified from address has a sufficient internal balance (within this EVVM system) of the token to cover the total amount to be dispersed. Reverts if the balance is insufficient.

3. Debit Sender: Subtracts the total amount of token from the from address's internal balance. This effectively moves the funds into the contract's temporary holding for distribution.

4. Payment Distribution Loop: Iterates through each DispersePayMetadata entry in the toData array:

   a. Initialize accumulatedAmount: A running total (accumulatedAmount) is maintained, starting at zero.

   b. Transfer to Recipient: Transfers the amount specified in the current DispersePayMetadata entry from this contract to the recipient address.

   c. Update Accumulated Amount: Adds the recipient's amount to the accumulatedAmount tracker.

5. Total Amount Verification: After the loop, verifies that the final accumulatedAmount exactly equals the amount parameter initially provided. Reverts if there is a mismatch.

6. Executor Reward (Conditional):

   • Checks if the calling contract (msg.sender) is an sMATE staker using isMateStaker(msg.sender).
   • If msg.sender is a staker, grants 1 MATE token reward to the msg.sender using the _giveMateReward function.