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

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.

Original ERC · ← ERCs