payStaker Functions

The payStaker functions process single payments where the transaction executor (msg.sender) must be a token staker. These functions provide enhanced benefits including priority fee rewards and principal token rewards for stakers who process transactions.

Staker benefits include receiving priority fees as rewards for transaction processing and earning principal token rewards upon successful execution. These functions support both direct addresses and identity-based payments through the NameService.

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.

payStaker_sync

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

Processes synchronous payments for principal token stakers with enhanced benefits and rewards. This function provides staker benefits including priority fee rewards and principal token rewards, while using automatic nonce increment for sequential transaction ordering.

Parameters

Field	Type	Description
from	address	The address of the payment sender whose funds are being transferred and whose signature/nonce are validated.
to_address	address	Direct recipient address. Used when to_identity is empty.
to_identity	string	Username/identity of the recipient. If provided, the contract resolves it to an address via the NameService.
token	address	The token address for the transfer.
amount	uint256	The quantity of tokens to transfer from from to the recipient.
priorityFee	uint256	Fee amount distributed to stakers as reward for processing the transaction.
executor	address	Address authorized to execute this transaction (must be a staker). Use address(0) to allow any staker to execute.
signature	bytes	Cryptographic signature (EIP-191) from the from address authorizing this payment.

note

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

Execution Methods

This function can only be executed by principal token stakers:

Fisher Execution

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

Direct Execution

When the executor is a staker user or service:

1. The staker user/service directly calls the payStaker_sync function.
2. The executor receives priority fee rewards and principal token rewards for processing.

tip

When using a service as the executor, we recommend specifying the service's address in the executor parameter for additional security.

Workflow

1. Signature Verification: Validates the signature against the from address and other parameters using verifyMessageSignedForPay. This includes checking that the synchronous nonce matches the expected next nonce for the from address. Reverts with InvalidSignature on failure.
2. Executor Validation: If executor is not address(0), checks that msg.sender matches the executor address. Reverts with SenderIsNotTheExecutor if they don't match.
3. Staker Verification: Verifies that the msg.sender (executor) is a registered staker using the isAddressStaker function. Reverts with NotAnStaker if msg.sender is not a staker.
4. Resolve Recipient Address: Determines the final recipient address:
   • If to_identity is provided (not empty), resolves the identity to an owner address using verifyStrictAndGetOwnerOfIdentity from the NameService contract.
   • If to_identity is empty, uses the provided to_address.
5. Balance Update: Executes the main payment transfer using the _updateBalance function, sending amount of token from the from address to the resolved recipient address. Reverts with UpdateBalanceFailed on transfer failure.
6. Priority Fee Distribution: If priorityFee > 0, transfers the priorityFee amount of token from the from address to the msg.sender (executor) as a staker reward. Reverts with UpdateBalanceFailed on transfer failure.
7. Principal Token Reward: Grants 1 principal token reward to the msg.sender (executor) using the _giveMateReward function.
8. Nonce Increment: Increments the synchronous nonce counter for the from address to prevent replay attacks.

info

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

---

payStaker_async

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

Processes asynchronous payments for principal token stakers with enhanced benefits and custom nonce management. This function provides staker benefits including priority fee rewards and principal token rewards, while using custom nonces for flexible transaction ordering and replay protection.

Parameters

Field	Type	Description
from	address	The address of the payment sender whose funds are being transferred and whose signature/nonce are validated.
to_address	address	Direct recipient address. Used when to_identity is empty.
to_identity	string	Username/identity of the recipient. If provided, the contract resolves it to an address via the NameService.
token	address	The token contract address for the transfer.
amount	uint256	The quantity of tokens to transfer from from to the recipient.
priorityFee	uint256	Fee amount distributed to stakers as reward for processing the transaction.
nonce	uint256	Custom nonce value for transaction ordering and replay protection.
executor	address	Address authorized to execute this transaction (must be a staker). Use address(0) to allow any staker to execute.
signature	bytes	Cryptographic signature (EIP-191) from the from address authorizing this payment.

Execution Methods

This function can only be executed by principal token stakers:

Fisher Execution

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

Direct Execution

When the executor is a staker user or service:

1. The staker user/service directly calls the payStaker_async function.
2. The executor receives priority fee rewards and principal token rewards for processing.

tip

When using a service as the executor, we recommend specifying the service's address in the executor parameter for additional security.

Workflow

1. Signature Verification: Validates the signature against the from address and other parameters using verifyMessageSignedForPay. Reverts with InvalidSignature on failure.
2. Executor Validation: If executor is not address(0), checks that msg.sender matches the executor address. Reverts with SenderIsNotTheExecutor if they don't match.
3. Staker Verification: Verifies that the msg.sender (executor) is a registered staker using the isAddressStaker function. Reverts with NotAnStaker if msg.sender is not a staker.
4. Async Nonce Verification: Checks if the provided nonce has already been used for the from address by consulting the asyncUsedNonce mapping. Reverts with InvalidAsyncNonce if the nonce has already been used.
5. Resolve Recipient Address: Determines the final recipient address:
   • If to_identity is provided (not empty), resolves the identity to an owner address using verifyStrictAndGetOwnerOfIdentity from the NameService contract.
   • If to_identity is empty, uses the provided to_address.
6. Balance Update: Executes the main payment transfer using the _updateBalance function, sending amount of token from the from address to the resolved recipient address. Reverts with UpdateBalanceFailed on transfer failure.
7. Priority Fee Distribution: If priorityFee > 0, transfers the priorityFee amount of token from the from address to the msg.sender (executor) as a staker reward. Reverts with UpdateBalanceFailed on transfer failure.
8. Principal token Reward: Grants 1 principal token reward to the msg.sender (executor) using the _giveMateReward function. Reverts with UpdateBalanceFailed on failure.
9. Nonce Marking: Marks the specific asynchronous nonce as used (true) for the from address in the asyncUsedNonce mapping to prevent replay attacks.

info

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

---