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

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.

Original ERC · ← ERCs