eip-2009.md
1 --- 2 eip: 2009 3 title: Compliance Service 4 author: Daniel Lehrner <daniel@io.builders> 5 discussions-to: https://github.com/ethereum/EIPs/issues/2022 6 status: Draft 7 type: Standards Track 8 category: ERC 9 created: 2019-05-09 10 requires: 1066 11 --- 12 13 ## Simple Summary 14 15 This EIP proposes a service for decentralized compliance checks for regulated tokens. 16 17 ## Actors 18 19 #### Operator 20 An account which has been approved by a token to update the tokens accumulated. 21 22 #### Token 23 An account, normally a smart contract, which uses the `Compliance Service` to check if the an action can be executed or not. 24 25 #### Token holder 26 An account which is in possession of tokens and on for which the checks are made. 27 28 ## Abstract 29 30 A regulated token needs to comply with several legal requirements, especially [KYC][KYC-Wikipedia] and [AML][AML-Wikipedia]. If the necessary checks have to be made off-chain the token transfer becomes centralized. Further the transfer in this case takes longer to complete as it can not be done in one transaction, but requires a second confirmation step. The goal of this proposal is to make this second step unnecessary by providing a service for compliance checks. 31 32 ## Motivation 33 34 Currently there is no proposal on how to accomplish decentralized compliance checks. [ERC-1462][ERC-1462] proposes a basic set of functions to check if `transfer`, `mint` and `burn` are allowed for a user, but not how those checks should be implemented. This EIP proposes a way to implement them fully on-chain while being generic enough to leave the actual implementation of the checks up to the implementers, as these may vary a lot between different tokens. 35 36 The proposed `Compliance Service` supports more than one token. Therefore it could be used by law-makers to maintain the compliance rules of regulated tokens in one smart contract. This smart contract could be used by all of the tokens that fall under this jurisdiction and ensure compliance with the current laws. 37 38 By having a standard for compliance checks third-party developers can use them to verify if token movements for a specific account are allowed and act accordingly. 39 40 ## Specification 41 42 ```solidity 43 interface CompliantService { 44 function checkTransferAllowed(bytes32 tokenId, address from, address to, uint256 value) external view returns (byte); 45 function checkTransferFromAllowed(bytes32 tokenId, address sender, address from, address to, uint256 value) external view returns (byte); 46 function checkMintAllowed(bytes32 tokenId, address to, uint256 value) external view returns (byte); 47 function checkBurnAllowed(bytes32 tokenId, address from, uint256 value) external view returns (byte); 48 49 function updateTransferAccumulated(bytes32 tokenId, address from, address to, uint256 value) external; 50 function updateMintAccumulated(bytes32 tokenId, address to, uint256 value) external; 51 function updateBurnAccumulated(bytes32 tokenId, address from, uint256 value) external; 52 53 function addToken(bytes32 tokenId, address token) external; 54 function replaceToken(bytes32 tokenId, address token) external; 55 function removeToken(bytes32 tokenId) external; 56 function isToken(address token) external view returns (bool); 57 function getTokenId(address token) external view returns (bytes32); 58 59 function authorizeAccumulatedOperator(address operator) external returns (bool); 60 function revokeAccumulatedOperator(address operator) external returns (bool); 61 function isAccumulatedOperatorFor(address operator, bytes32 tokenId) external view returns (bool); 62 63 event TokenAdded(bytes32 indexed tokenId, address indexed token); 64 event TokenReplaced(bytes32 indexed tokenId, address indexed previousAddress, address indexed newAddress); 65 event TokenRemoved(bytes32 indexed tokenId); 66 event AuthorizedAccumulatedOperator(address indexed operator, bytes32 indexed tokenId); 67 event RevokedAccumulatedOperator(address indexed operator, bytes32 indexed tokenId); 68 } 69 ``` 70 71 ### Mandatory checks 72 73 The checks must be verified in their corresponding actions. The action must only be successful if the check return an `Allowed` status code. In any other case the functions must revert. 74 75 ### Status codes 76 77 If an action is allowed `0x11` (Allowed) or an issuer-specific code with equivalent but more precise meaning must be returned. If the action is not allowed the status must be `0x10` (Disallowed) or an issuer-specific code with equivalent but more precise meaning. 78 79 ### Functions 80 81 #### checkTransferAllowed 82 83 Checks if the `transfer` function is allowed to be executed with the given parameters. 84 85 | Parameter | Description | 86 | ---------|-------------| 87 | tokenId | The unique ID which identifies a token | 88 | from | The address of the payer, from whom the tokens are to be taken if executed | 89 | to | The address of the payee, to whom the tokens are to be transferred if executed | 90 | value | The amount to be transferred | 91 92 #### checkTransferFromAllowed 93 94 Checks if the `transferFrom` function is allowed to be executed with the given parameters. 95 96 | Parameter | Description | 97 | ---------|-------------| 98 | tokenId | The unique ID which identifies a token | 99 | sender | The address of the sender, who initiated the transaction | 100 | from | The address of the payer, from whom the tokens are to be taken if executed | 101 | to | The address of the payee, to whom the tokens are to be transferred if executed | 102 | value | The amount to be transferred | 103 104 #### checkMintAllowed 105 106 Checks if the `mint` function is allowed to be executed with the given parameters. 107 108 | Parameter | Description | 109 | ---------|-------------| 110 | tokenId | The unique ID which identifies a token | 111 | to | The address of the payee, to whom the tokens are to be given if executed | 112 | value | The amount to be minted | 113 114 #### checkBurnAllowed 115 116 Checks if the `burn` function is allowed to be executed with the given parameters. 117 118 | Parameter | Description | 119 | ---------|-------------| 120 | tokenId | The unique ID which identifies a token | 121 | from | The address of the payer, from whom the tokens are to be taken if executed | 122 | value | The amount to be burned | 123 124 #### updateTransferAccumulated 125 126 Must be called in the same transaction as `transfer` or `transferFrom`. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function. 127 128 | Parameter | Description | 129 | ---------|-------------| 130 | tokenId | The unique ID which identifies a token | 131 | from | The address of the payer, from whom the tokens are to be taken if executed | 132 | to | The address of the payee, to whom the tokens are to be transferred if executed | 133 | value | The amount to be transferred | 134 135 #### updateMintAccumulated 136 137 Must be called in the same transaction as `mint`. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function. 138 139 | Parameter | Description | 140 | ---------|-------------| 141 | tokenId | The unique ID which identifies a token | 142 | to | The address of the payee, to whom the tokens are to be given if executed | 143 | value | The amount to be minted | 144 145 #### updateBurnAccumulated 146 147 Must be called in the same transaction as `burn`. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function. 148 149 | Parameter | Description | 150 | ---------|-------------| 151 | tokenId | The unique ID which identifies a token | 152 | from | The address of the payer, from whom the tokens are to be taken if executed | 153 | value | The amount to be minted | 154 155 #### addToken 156 157 Adds a token to the service, which allows the token to call the functions to update the accumulated. If an existing token id is used the function must revert. It is up to the implementer if adding a token should be restricted or not. 158 159 | Parameter | Description | 160 | ---------|-------------| 161 | tokenId | The unique ID which identifies a token | 162 | token | The address from which the update functions will be called | 163 164 #### replaceToken 165 166 Replaces the address of a added token with another one. It is up to the implementer if replacing a token should be restricted or not, but a token should be able to replace its own address. 167 168 | Parameter | Description | 169 | ---------|-------------| 170 | tokenId | The unique ID which identifies a token | 171 | token | The address from which the update functions will be called | 172 173 #### removeToken 174 175 Removes a token from the service, which disallows the token to call the functions to update the accumulated. It is up to the implementer if removing a token should be restricted or not. 176 177 | Parameter | Description | 178 | ---------|-------------| 179 | tokenId | The unique ID which identifies a token | 180 181 #### isToken 182 183 Returns `true` if the address has been added to the service, `false` if not. 184 185 | Parameter | Description | 186 | ---------|-------------| 187 | token | The address which should be checked | 188 189 #### getTokenId 190 191 Returns the token id of a token. If the token has not been added to the service, '0' must be returned. 192 193 | Parameter | Description | 194 | ---------|-------------| 195 | token | The address which token id should be returned | 196 197 #### authorizeAccumulatedOperator 198 199 Approves an operator to update accumulated on behalf of the token id of msg.sender. 200 201 | Parameter | Description | 202 | ---------|-------------| 203 | operator | The address to be approved as operator of accumulated updates | 204 205 #### revokeAccumulatedOperator 206 207 Revokes the approval to update accumulated on behalf the token id the token id ofof msg.sender. 208 209 | Parameter | Description | 210 | ---------|-------------| 211 | operator | The address to be revoked as operator of accumulated updates | 212 213 #### isAccumulatedOperatorFor 214 215 Retrieves if an operator is approved to create holds on behalf of `tokenId`. 216 217 | Parameter | Description | 218 | ---------|-------------| 219 | operator | The address which is operator of updating the accumulated | 220 | tokenId | The unique ID which identifies a token | 221 222 ### Events 223 224 #### TokenAdded 225 226 Must be emitted after a token has been added. 227 228 | Parameter | Description | 229 | ---------|-------------| 230 | tokenId | The unique ID which identifies a token | 231 | token | The address from which the update functions will be called | 232 233 #### TokenReplaced 234 235 Must be emitted after the address of a token has been replaced. 236 237 | Parameter | Description | 238 | ---------|-------------| 239 | tokenId | The unique ID which identifies a token | 240 | previousAddress | The previous address which was used before | 241 | newAddress | The address which will be used from now on | 242 243 #### TokenRemoved 244 245 Must be emitted after the a token has been removed. 246 247 | Parameter | Description | 248 | ---------|-------------| 249 | tokenId | The unique ID which identifies a token | 250 251 #### AuthorizedAccumulatedOperator 252 253 Emitted when an operator has been approved to update the accumulated on behalf of a token. 254 255 | Parameter | Description | 256 | ---------|-------------| 257 | operator | The address which is operator of updating the accumulated | 258 | tokenId | Token id on which behalf updates of the accumulated will potentially be made | 259 260 #### RevokedHoldOperator 261 262 Emitted when an operator has been revoked from updating the accumulated on behalf of a token. 263 264 | Parameter | Description | 265 | ---------|-------------| 266 | operator | The address which was operator of updating the accumulated | 267 | tokenId | Token id on which behalf updates of the accumulated could be made | 268 269 ## Rationale 270 271 The usage of a token id instead of the address has been chosen to give tokens the possibility to update their smart contracts and keeping all their associated accumulated. If the address would be used, a migration process would needed to be done after a smart contract update. 272 273 No event is emitted after updating the accumulated as those are always associated with a `transfer`, `mint` or `burn` of a token which already emits an event of itself. 274 275 While not requiring it, the naming of the functions `checkTransferAllowed`, `checkTransferFromAllowed`, `checkMintAllowed` and `checkBurnAllowed` was adopted from [ERC-1462][ERC-1462]. 276 277 While not requiring it, the naming of the functions `authorizeAccumulatedOperator`, `revokeAccumulatedOperator` and `isAccumulatedOperatorFor` follows the naming convention of [ERC-777][ERC-777]. 278 279 Localization is not part of this EIP, but [ERC-1066][ERC-1066] and [ERC-1444][ERC-1444] can be used together to achieve it. 280 281 ## Backwards Compatibility 282 283 As the EIP is not using any existing EIP there are no backwards compatibilities to take into consideration. 284 285 ## Implementation 286 287 The GitHub repository [IoBuilders/compliance-service](https://github.com/IoBuilders/compliance-service) contains the work in progress implementation. 288 289 ## Contributors 290 This proposal has been collaboratively implemented by [adhara.io](https://adhara.io/) and [io.builders](https://io.builders/). 291 292 ## Copyright 293 Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). 294 295 [KYC-Wikipedia]: https://en.wikipedia.org/wiki/Know_your_customer 296 [AML-Wikipedia]: https://en.wikipedia.org/wiki/Money_laundering#Anti-money_laundering 297 [ERC-777]: http://eips.ethereum.org/EIPS/eip-777 298 [ERC-1066]: http://eips.ethereum.org/EIPS/eip-1066 299 [ERC-1444]: http://eips.ethereum.org/EIPS/eip-1444 300 [ERC-1462]: http://eips.ethereum.org/EIPS/eip-1462