ERC-2018 Clearable token
Stagnant · Tokens · created 2019-04-30
A standard for regulated tokens in which a transfer is not settled immediately. Instead, the amount is first ordered and held, and a clearing agent performs an off-chain check before executing or rejecting it.
Why it is needed
Regulated tokens must comply with legal requirements such as KYC and AML, and these checks are often difficult to perform directly on-chain. With the conventional transfer mechanism, the request and the settlement happen at the same time, leaving no room to insert an off-chain check in between. If funds move before the check is complete, or get double-spent across transfers, this can cause accidents, while holding the transfer entirely until the check is done increases uncertainty because the funds cannot be used for anything else in the meantime. Without this standard, there was no standardized way for tokens requiring regulation to combine the single-step settlement of ERC-20 transfers with an off-chain approval process.
What to implement
function orderTransfer(string calldata operationId, address to, uint256 value) external returns (bool);: Orders a clearable transfer to be sent to `to` on behalf of `msg.sender`. Reverts if the `operationId` has already been used.function orderTransferFrom(string calldata operationId, address from, address to, uint256 value) external returns (bool);: An approved operator orders a clearable transfer to be sent to `to` on behalf of `from`. Reverts if the `operationId` has already been used.function cancelTransfer(string calldata operationId) external returns (bool);: Cancels a clearable transfer order. Only the orderer can do this, and it cannot be cancelled once it reaches the InProcess state.function processClearableTransfer(string calldata operationId) external returns (bool);: Changes a clearable transfer to the InProcess state. Only the clearing agent can execute this.function executeClearableTransfer(string calldata operationId) external returns (bool);: Executes a clearable transfer, moving tokens from the payer to the payee. Only the clearing agent can execute this.function rejectClearableTransfer(string calldata operationId, string calldata reason) external returns (bool);: Rejects a clearable transfer, releasing the held amount so the payer can use it again. Only the clearing agent can execute this.function retrieveClearableTransferData(string calldata operationId) external view returns (address from, address to, uint256 value, ClearableTransferStatusCode status);: Looks up the payer, payee, amount, and status information of a specific clearable transfer.function authorizeClearableTransferOperator(address operator) external returns (bool);: Authorizes an operator to order transfers on behalf of `msg.sender`.function revokeClearableTransferOperator(address operator) external returns (bool);: Revokes an operator's authorization to order transfers on behalf of `msg.sender`.function isClearableTransferOperatorFor(address operator, address from) external view returns (bool);: Checks whether a specific operator is authorized to order transfers on behalf of `from`.event ClearableTransferOrdered(address indexed orderer, string operationId, address indexed from, address indexed to, uint256 value);: Emitted when a clearable transfer is ordered.event ClearableTransferInProcess(address indexed orderer, string operationId);: Emitted when a clearable transfer enters the InProcess state.event ClearableTransferExecuted(address indexed orderer, string operationId);: Emitted when a clearable transfer is executed.event ClearableTransferRejected(address indexed orderer, string operationId, string reason);: Emitted, along with the reason, when a clearable transfer is rejected.event ClearableTransferCancelled(address indexed orderer, string operationId);: Emitted when the orderer cancels a clearable transfer.event AuthorizedClearableTransferOperator(address indexed operator, address indexed account);: Emitted when an operator is authorized to order transfers on behalf of another account.event RevokedClearableTransferOperator(address indexed operator, address indexed account);: Emitted when an operator's transfer-ordering authorization is revoked.
In depth
Transfer state machine
ClearableTransferStatusCode consists of six stages: Nonexistent, Ordered, InProcess, Executed, Rejected, and Cancelled. A transfer becomes Ordered once it is ordered, and changes to InProcess when the clearing agent calls `processClearableTransfer`. From there it becomes Executed via `executeClearableTransfer` or Rejected via `rejectClearableTransfer`, and the orderer can set it to Cancelled via `cancelTransfer` as long as it has not yet become InProcess. The current status can be looked up with `retrieveClearableTransferData`.
orderTransfer and orderTransferFrom
`orderTransfer` is used when `msg.sender` orders a transfer of their own tokens, while `orderTransferFrom` is used when an approved operator orders a transfer of another account's (`from`) tokens on their behalf. Both functions take an `operationId`, a payee (`to`), and an amount (`value`), and `value` must be less than or equal to the payer's balance. Calling either function again with an already-used `operationId` must revert. The ordered amount is not deducted from the payer's balance right away, but it is held so it cannot be used in other transfers.
cancelTransfer and processClearableTransfer
`cancelTransfer` can only be called by the orderer, and fails once the transfer has already reached the InProcess state. `processClearableTransfer` is an optional step that moves the transfer to InProcess, and only the clearing agent can execute it. Skipping this step means the orderer can cancel the transfer at any time, so the InProcess state serves to block the orderer's cancellation right.
executeClearableTransfer and rejectClearableTransfer
`executeClearableTransfer` is the function the clearing agent uses to actually move tokens from the payer to the payee for a transfer that has passed the check. `rejectClearableTransfer` is used for a transfer that failed the check, releasing the held amount so the payer can use it again and recording the rejection reason in a reason string. Only the clearing agent can call either function.
Operator authorization structure
With `authorizeClearableTransferOperator` and `revokeClearableTransferOperator`, an account owner can authorize or revoke another address's ability to order clearable transfers on their behalf. `isClearableTransferOperatorFor` can be used to check whether a specific address is an operator for a specific account. The naming of these three functions follows the ERC-777 naming convention.
operationId and the ERC-1996 dependency
`operationId` is defined as a string type, prioritizing traceability and human-readable identifiers over gas efficiency. Implementers can decide whether to store the full string on-chain or only its hash. Since `operationId` is a contested resource, it is recommended, though not required, to use an issuer-specific prefix to avoid collisions. This standard uses the hold feature of ERC-1996 to lock up ordered amounts, extending ERC-1996's functionality in a backward-compatible way.
Relationship to existing transfer/transferFrom
This standard leaves it to the implementer to decide whether to always revert ERC-20's `transfer` and `transferFrom` functions or allow them under certain conditions, rather than specifying it. In other words, whether a clearable token fully blocks or partially allows ordinary, immediately-settled transfers can differ from token to token.
Proposal status
This proposal is in Stagnant status, meaning it is stalled without active discussion. A reference implementation is published in io.builders' repository, but the standard itself has not been finalized.