ERC-2009 Token Compliance Check Service (Compliance Service)
Stagnant · Tokens · created 2019-05-09
A compliance service standard that requires regulated tokens to automatically check and record on-chain compliance requirements such as KYC and AML before executing transfers, mints, or burns.
Why it is needed
Handling legally required compliance checks such as KYC or AML off-chain makes token transfers dependent on confirmation from a specific institution, which centralizes them. Also, because checking and approval are split into separate steps, a transfer does not complete in a single transaction and must wait for a second confirmation step, which takes a long time. ERC-1462 proposed a basic set of functions to check whether transfer, mint, and burn are permitted, but it did not define how those checks should actually be implemented. As a result, implementation methods differ from token to token, and there was no standardized way for third-party developers to check whether a given account's token movement is permitted.
What to implement
function checkTransferAllowed(bytes32 tokenId, address from, address to, uint256 value) external view returns (byte);: Checks whether the transfer function can be executed with the given parameters.function checkTransferFromAllowed(bytes32 tokenId, address sender, address from, address to, uint256 value) external view returns (byte);: Checks whether the transferFrom function can be executed with the given parameters.function checkMintAllowed(bytes32 tokenId, address to, uint256 value) external view returns (byte);: Checks whether the mint function can be executed with the given parameters.function checkBurnAllowed(bytes32 tokenId, address from, uint256 value) external view returns (byte);: Checks whether the burn function can be executed with the given parameters.function updateTransferAccumulated(bytes32 tokenId, address from, address to, uint256 value) external;: Must be called within the same transaction as transfer or transferFrom, and reverts if a compliance rule is violated.function updateMintAccumulated(bytes32 tokenId, address to, uint256 value) external;: Must be called within the same transaction as mint, and reverts if a rule is violated.function updateBurnAccumulated(bytes32 tokenId, address from, uint256 value) external;: Must be called within the same transaction as burn, and reverts if a rule is violated.function addToken(bytes32 tokenId, address token) external;: Registers a token with the service so its accumulation-update functions can be called. Reverts if the tokenId is already in use.function replaceToken(bytes32 tokenId, address token) external;: Replaces the address of a registered token with another address.function removeToken(bytes32 tokenId) external;: Removes a token from the service so its accumulation-update functions can no longer be called.function isToken(address token) external view returns (bool);: Returns whether the given address is a token registered with the service.function getTokenId(address token) external view returns (bytes32);: Returns the token's tokenId. Returns 0 if not registered.function authorizeAccumulatedOperator(address operator) external returns (bool);: Authorizes an operator to update accumulation on behalf of msg.sender's tokenId.function revokeAccumulatedOperator(address operator) external returns (bool);: Revokes an operator's authorization to update accumulation on behalf of msg.sender's tokenId.function isAccumulatedOperatorFor(address operator, bytes32 tokenId) external view returns (bool);: Returns whether a given operator has permission to update accumulation on behalf of the given tokenId.event TokenAdded(bytes32 indexed tokenId, address indexed token);: Emitted after a token is added to the service.event TokenReplaced(bytes32 indexed tokenId, address indexed previousAddress, address indexed newAddress);: Emitted after a token's address is replaced.event TokenRemoved(bytes32 indexed tokenId);: Emitted after a token is removed from the service.event AuthorizedAccumulatedOperator(address indexed operator, bytes32 indexed tokenId);: Emitted when an operator is authorized to update accumulation on behalf of a token.event RevokedAccumulatedOperator(address indexed operator, bytes32 indexed tokenId);: Emitted when an operator's authorization to update accumulation on behalf of a token is revoked.
In depth
Status Codes and Mandatory Checks
If permitted, the function must return 0x11 (Allowed) or an equivalent but more specific issuer-defined code. If not permitted, it must return 0x10 (Disallowed) or a corresponding issuer-defined code. These codes follow ERC-1066. If a check function does not return Allowed, the corresponding action (transfer, transferFrom, mint, burn) must fail (revert), and the check must be performed together with that action.
Four Check Functions
checkTransferAllowed(tokenId, from, to, value) checks whether transfer can be executed, checkTransferFromAllowed(tokenId, sender, from, to, value) checks whether transferFrom can be executed, checkMintAllowed(tokenId, to, value) checks whether mint can be executed, and checkBurnAllowed(tokenId, from, value) checks whether burn can be executed. All are view functions that only query a status code without changing state.
Accumulation-Update Functions
updateTransferAccumulated, updateMintAccumulated, and updateBurnAccumulated must each be called within the same transaction as transfer/transferFrom, mint, and burn respectively. If the update violates a compliance rule, it must revert, and the specific logic to execute is left to the implementer. No separate event is emitted for the update itself, since the associated transfer, mint, or burn already emits its own event.
Token Registration Management and tokenId
A token must be registered via addToken(tokenId, token) before that address can call the accumulation-update functions, and it reverts if the tokenId is already in use. replaceToken(tokenId, token) can replace the address of a registered token, and at minimum the token itself must be able to replace its own address. Once removeToken(tokenId) deregisters a token, its accumulation-update functions can no longer be called. isToken and getTokenId are read-only functions for querying registration status and tokenId; getTokenId returns 0 for an unregistered token. The reason for using tokenId instead of an address is to preserve accumulated data across address changes without requiring migration.
Accumulation-Update Operators
authorizeAccumulatedOperator(operator) authorizes an operator to update accumulation on behalf of msg.sender's tokenId, and revokeAccumulatedOperator(operator) revokes that authorization. isAccumulatedOperatorFor(operator, tokenId) queries whether the given operator has authorization on behalf of that tokenId. The names of these three functions are not mandatory but follow ERC-777's operator naming convention.
A Shared Service Spanning Multiple Tokens
The compliance service is designed to support one or more tokens, allowing a legislative body to manage compliance rules for regulated tokens within its jurisdiction in a single smart contract that all tokens in that jurisdiction can share. Because the check functions are standardized, third-party developers can also query whether a given account's token movement is permitted and act accordingly.
Localization, Compatibility, and Reference Standards
Localization of status code messages is out of scope for this proposal, but it can be implemented by combining ERC-1066 and ERC-1444. The names of the check* functions are not mandatory but follow ERC-1462's naming. This proposal specifies ERC-1066 via requires but does not extend the functionality of that existing proposal itself, so there are no backward-compatibility concerns to consider.
Proposal status
This proposal is registered as Stagnant, meaning discussion has stopped and is no longer moving forward. The content may change or may never be adopted.