payMateStaking Functions

The payMateStaking functions facilitate single payments where the transaction executor (msg.sender) is required to be an sMATE token holder (staker). These functions are provided in synchronous and asynchronous variants, differing primarily in their nonce handling.

For detailed information on nonce types, please refer to the Nonce Types in EVVM section. The signature structure for these payments is detailed in the Payment Signature Structure section.

payMateStaking_sync

Function Type: external
Function Signature: payMateStaking_sync(address,address,string,address,uint256,uint256,address,bytes)
Function Selector: 0x4faa1fa2

Executes a single, synchronous payment where the transaction executor (msg.sender) must hold sMATE tokens. Synchronous execution relies on an implicitly managed, ordered nonce. The executor receives the specified priorityFee in the token defined by the token parameter and standard MATE rewards for successful execution.

Parameters

Field	Type	Description
from	address	The address whose funds are being sent and whose signature/nonce are validated for this payment.
to_address	address	he recipient's direct address. Used if to_identity is empty.
to_identity	string	An alternative identifier for the recipient. If provided, the contract will attempt to resolve it to an address.
token	address	The specific token address for this individual transfer.
amount	uint256	The quantity of token to transfer from from to the recipient.
priorityFee	uint256	An additional fee, paid in token from the from address to the msg.sender (executor).
executor	address	The address authorized to submit this transaction to the contract. Can be address(0) for unrestricted execution.
signature	bytes	A cryptographic signature (EIP-191) from the from address, authorizing this specific payment's details.

note

There is no explicit nonce parameter; the synchronous nonce is validated as part of the signature verification process

Execution Methods

The function can be executed in two ways:

Fisher Execution

1. A user signs the payment details and sends the request (parameters + signature) to a fishing spot.
2. The fisher (who must hold sMATE) captures the transaction and validates the request.
3. The fisher submits the transaction to the function for processing.

Direct Execution

When the executor is the user or a service:

1. The user/service (who must hold sMATE) directly calls the payMateStaking_sync function.

tip

If using a service as the direct executor, we recommend adding the service's address as the executor parameter.

Workflow

1. Signature & Sync Nonce Verification: Validates the signature against the from address and other parameters using verifyMessageSignedForPay. This step also implicitly checks if the synchronous nonce derived from the signature matches the expected next synchronous nonce for the from address. Reverts on failure.
2. Executor Validation: Checks if the executor parameter matches the transaction sender (msg.sender). If executor is address(0), this check is bypassed, allowing anyone to submit the transaction (provided the signature is valid). Reverts if executor is non-zero and doesn't match msg.sender.
3. sMATE Holder Check: Verifies that the msg.sender (the executor) holds sMATE tokens using the isMateStaker function. Reverts if msg.sender is not an staker.
4. Resolve Recipient Address: Determines the final recipient address:
   • If to_identity is provided (not empty), it attempts to resolve the identity to an owner address using verifyStrictAndGetOwnerOfIdentity from the MateNameService contract.
   • If to_identity is empty, it uses the provided to_address.
5. Balance Check and Update: Executes the main payment transfer using the _updateBalance function sending amount of token from the from address to the resolved recipient address. Reverts on transfer failure.
6. Priority Fee Transfer: If priorityFee > 0, transfers priorityFee amount of token from the from address to the msg.sender (executor) using the _updateBalance function. Reverts on transfer failure.
7. Executor Reward: Grants 1 MATE token reward to the msg.sender (executor) using the _giveMateReward function.
8. Nonce Update: Increments the synchronous nonce counter for the from address, marking this nonce as used.

info

For more information about the signature structure, refer to the Payment Signature Structure section.

---

payMateStaking_async

Function Type: external
Function Signature: payMateStaking_async(address,address,string,address,uint256,uint256,uint256,address,bytes)
Function Selector: 0xf4e1895b

Executes a single, asynchronous payment where the transaction executor (msg.sender) must hold sMATE tokens. Asynchronous execution uses an explicit nonce parameter, allowing for out-of-order processing relative to other async transactions from the same sender.

Parameters

Field	Type	Description
from	address	The address whose funds are being sent and whose signature/nonce are validated for this payment.
to_address	address	he recipient's direct address. Used if to_identity is empty.
to_identity	string	An alternative identifier for the recipient. If provided, the contract will attempt to resolve it to an address.
token	address	The specific token address for this individual transfer.
amount	uint256	The quantity of token to transfer from from to the recipient.
priorityFee	uint256	An additional fee, paid in token from the from address to the msg.sender (executor).
nonce	uint256	The specific asynchronous nonce value provided by the from user for this transaction's replay protection.
executor	address	The address authorized to submit this transaction to the contract. Can be address(0) for unrestricted execution.
signature	bytes	A cryptographic signature (EIP-191) from the from address, authorizing this specific payment's details.

Execution Methods

The function can be executed in two ways:

Fisher Execution

1. A user signs the payment details and sends the request (parameters + signature) to a fishing spot.
2. The fisher (who must hold sMATE) captures the transaction and validates the request.
3. The fisher submits the transaction to the function for processing.

Direct Execution

When the executor is the user or a service:

1. The user/service (who must hold sMATE) directly calls the payMateStaking_sync function.

tip

If using a service as the direct executor, we recommend adding the service's address as the executor parameter.

Workflow

1. Signature Verification: Validates the signature against the from address and other parameters using verifyMessageSignedForPay. Reverts on failure.
2. Executor Validation: Checks if the executor parameter matches the transaction sender (msg.sender). If executor is address(0), this check is bypassed, allowing anyone to submit the transaction (provided the signature is valid). Reverts if executor is non-zero and doesn't match msg.sender.
3. sMATE Holder Check: Verifies that the msg.sender (the executor) holds sMATE tokens using the isMateStaker function. Reverts if msg.sender is not an staker.
4. Async Nonce Verification: Checks if the provided nonce has already been used for the from address by consulting the asyncUsedNonce mapping. Reverts if the nonce is invalid or already used.
5. Resolve Recipient Address: Determines the final recipient address:
   • If to_identity is provided (not empty), it attempts to resolve the identity to an owner address using verifyStrictAndGetOwnerOfIdentity from the MateNameService contract.
   • If to_identity is empty, it uses the provided to_address.
6. Balance Check and Update: Executes the main payment transfer using the _updateBalance function sending amount of token from the from address to the resolved recipient address. Reverts on transfer failure.
7. Priority Fee Transfer: If priorityFee > 0, transfers priorityFee amount of token from the from address to the msg.sender (executor) using the _updateBalance function. Reverts on transfer failure.
8. Executor Reward: Grants 1 MATE token reward to the msg.sender (executor) using the _giveMateReward function.
9. Nonce Update: Marks the specific asynchronous nonce provided in the parameters as used (true) for the from address in the asyncUsedNonce mapping.

info

If you want to know more about the signature structure, refer to the Payment Signature Structure section.

---