ERC-2021 Payoutable tokens (Payoutable Token)
Stagnant · Tokens · created 2019-05-10
An extension standard that lets ERC-20 token wallet owners request a payout (the process of returning tokens in exchange for payment) directly on the blockchain, and have the issuer process it and burn the tokens.
Why it is needed
Previously, for a token holder to receive a payout, they first had to communicate separately with the issuer in a centralized manner to determine the destination for the funds, and only then could the token-burning transaction be processed. Because this request and negotiation process took place off the blockchain, when the request was made and what state it was currently in was not recorded on-chain, making it hard to track. While the issuance and transfer of tokens were handled in a decentralized flow, the payout stage alone relied on a centralized, prearranged process, leaving part of the overall lifecycle opaque.
What to implement
enum PayoutStatusCode { Nonexistent, Ordered, InProcess, FundsInSuspense, Executed, Rejected, Cancelled }: Defines the seven states a payout request passes through.function authorizePayoutOperator(address orderer) external returns (bool);: The wallet owner approves a specific address as their payout order agent.function revokePayoutOperator(address orderer) external returns (bool);: Revokes the authorization of a previously approved payout order agent.function orderPayout(string calldata operationId, uint256 value, string calldata instructions) external returns (bool);: The wallet owner themselves creates a payout request with an amount and payment instructions.function orderPayoutFrom(string calldata operationId, address walletToBePaidOut, uint256 value, string calldata instructions) external returns (bool);: An approved agent creates a payout request on behalf of another wallet owner.function cancelPayout(string calldata operationId) external returns (bool);: Cancels a payout request that is still in a pre-processing state.function processPayout(string calldata operationId) external returns (bool);: Transitions a request into the InProcess state, after which it can no longer be cancelled.function putFundsInSuspenseInPayout(string calldata operationId) external returns (bool);: Moves the held funds to the suspense wallet and changes the status to FundsInSuspense.function executePayout(string calldata operationId) external returns (bool);: Burns the tokens in the suspense wallet and closes the request in the Executed state.function rejectPayout(string calldata operationId, string calldata reason) external returns (bool);: Rejects the request with a stated reason and returns the held funds.function isPayoutOperatorFor(address walletToDebit, address orderer) external view returns (bool);: Checks whether a specific address has payout ordering authority for a given wallet.function retrievePayoutData(string calldata operationId) external view returns (address walletToDebit, uint256 value, string memory instructions, PayoutStatusCode status);: Retrieves the wallet, amount, payment instructions, and status information for a specific request.event PayoutOrdered(address indexed orderer, string indexed operationId, address indexed walletToDebit, uint256 value, string instructions);: Fired when a payout request is created.event PayoutInProcess(address indexed orderer, string indexed operationId);: Fired when the operator moves a request into the in-process state.event PayoutFundsInSuspense(address indexed orderer, string indexed operationId);: Fired when the operator moves funds into the suspense wallet.event PayoutExecuted(address indexed orderer, string indexed operationId);: Fired when the operator burns tokens to complete execution of a request.event PayoutRejected(address indexed orderer, string indexed operationId, string reason);: Fired when the operator rejects a request, citing a reason.event PayoutCancelled(address indexed orderer, string indexed operationId);: Fired when the holder or orderer cancels a request before it is processed.event PayoutOperatorAuthorized(address indexed walletToBePaidOut, address indexed orderer);: Fired when the wallet owner approves a new payout agent.event PayoutOperatorRevoked(address indexed walletToBePaidOut, address indexed orderer);: Fired when an existing payout agent's authorization is revoked.
In depth
Seven-stage state machine
PayoutStatusCode defines seven states: Nonexistent, Ordered, InProcess, FundsInSuspense, Executed, Rejected, and Cancelled. When a request is created, funds are held and it becomes Ordered; once the operator begins processing, it changes to InProcess, after which the orderer can no longer cancel it. When the operator executes the hold, funds move to the suspense wallet and the status becomes FundsInSuspense, and once tokens are burned after off-chain payment, it ends as Executed. The operator can reject the request as Rejected and return the funds at any point before or after InProcess, and the orderer can cancel it as Cancelled while it is still Ordered and before it becomes InProcess.
Order functions orderPayout / orderPayoutFrom
orderPayout lets the wallet owner themselves create a request by passing operationId, value, and instructions. orderPayoutFrom lets an approved agent create the same kind of request on behalf of someone else by specifying walletToBePaidOut. Both functions must revert if the operationId has already been used.
Delegating operator authority
authorizePayoutOperator is the function by which a wallet owner approves a specific address as their payout order agent (orderer), and revokePayoutOperator revokes that approval. isPayoutOperatorFor is a query function that checks whether a given address has ordering authority for a specific wallet.
Cancellation and rejection
cancelPayout can only be called by the token holder or the payout orderer, and can include a reason using EIP-1066 codes. rejectPayout is a function by which the operator rejects a request with a stated reason, which can likewise use EIP-1066 codes. Cancellation is only possible before the operator transitions the request to InProcess.
Processing and execution
processPayout marks a request as InProcess, after which it can no longer be cancelled. putFundsInSuspenseInPayout can only be called while the request is InProcess, and it executes the hold, moving the funds to the suspense wallet. executePayout burns the token amount in the suspense wallet and finalizes the request as Executed.
Data retrieval authority
retrievePayoutData returns the walletToDebit, value, instructions, and status for a given operationId. Per the specification, this data can only be retrieved by the operator, the token holder, and the orderer of that request.
operationId design and the EIP-1996 hold model
operationId was defined as a string rather than a gas-efficient format in order to favor a human-readable identifier for better traceability. Implementers can decide whether to store the full string on-chain or just its hash, since the hash alone is sufficient for identifying the hold. Because operationId is a contested resource, it is recommended, though not required, for each issuer to use a unique prefix. This standard operates on top of ERC-20 and EIP-1996: when a request comes in, funds are locked via an EIP-1996 hold, and the token contract owner or an agent, acting in a predetermined notary role, decides whether to execute it. The implementation of the hold itself is out of scope for this proposal.
Security recommendations for payment instructions and standard status
The specification recommends against writing concrete payment instructions, such as the payout destination, verbatim onto the blockchain, and instead advises using off-chain means such as private channels or encrypted storage. It notes that if it must be written on-chain, entering the instructions field in encrypted form is a less preferred but possible alternative. This proposal is currently in Stagnant status, meaning it is no longer actively discussed and has stalled.