1  ---
  2  eip: 20
  3  title: ERC-20 Token Standard
  4  author: Fabian Vogelsteller <fabian@ethereum.org>, Vitalik Buterin <vitalik.buterin@ethereum.org>
  5  type: Standards Track
  6  category: ERC
  7  status: Final
  8  created: 2015-11-19
  9  ---
 10  
 11  ## Simple Summary
 12  
 13  A standard interface for tokens.
 14  
 15  
 16  ## Abstract
 17  
 18  The following standard allows for the implementation of a standard API for tokens within smart contracts.
 19  This standard provides basic functionality to transfer tokens, as well as allow tokens to be approved so they can be spent by another on-chain third party.
 20  
 21  
 22  ## Motivation
 23  
 24  A standard interface allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges.
 25  
 26  
 27  ## Specification
 28  
 29  ## Token
 30  ### Methods
 31  
 32  **NOTES**:
 33   - The following specifications use syntax from Solidity `0.4.17` (or above)
 34   - Callers MUST handle `false` from `returns (bool success)`.  Callers MUST NOT assume that `false` is never returned!
 35  
 36  
 37  #### name
 38  
 39  Returns the name of the token - e.g. `"MyToken"`.
 40  
 41  OPTIONAL - This method can be used to improve usability,
 42  but interfaces and other contracts MUST NOT expect these values to be present.
 43  
 44  
 45  ``` js
 46  function name() public view returns (string)
 47  ```
 48  
 49  
 50  #### symbol
 51  
 52  Returns the symbol of the token. E.g. "HIX".
 53  
 54  OPTIONAL - This method can be used to improve usability,
 55  but interfaces and other contracts MUST NOT expect these values to be present.
 56  
 57  ``` js
 58  function symbol() public view returns (string)
 59  ```
 60  
 61  
 62  
 63  #### decimals
 64  
 65  Returns the number of decimals the token uses - e.g. `8`, means to divide the token amount by `100000000` to get its user representation.
 66  
 67  OPTIONAL - This method can be used to improve usability,
 68  but interfaces and other contracts MUST NOT expect these values to be present.
 69  
 70  ``` js
 71  function decimals() public view returns (uint8)
 72  ```
 73  
 74  
 75  #### totalSupply
 76  
 77  Returns the total token supply.
 78  
 79  ``` js
 80  function totalSupply() public view returns (uint256)
 81  ```
 82  
 83  
 84  
 85  #### balanceOf
 86  
 87  Returns the account balance of another account with address `_owner`.
 88  
 89  ``` js
 90  function balanceOf(address _owner) public view returns (uint256 balance)
 91  ```
 92  
 93  
 94  
 95  #### transfer
 96  
 97  Transfers `_value` amount of tokens to address `_to`, and MUST fire the `Transfer` event.
 98  The function SHOULD `throw` if the message caller's account balance does not have enough tokens to spend.
 99  
100  *Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event.
101  
102  ``` js
103  function transfer(address _to, uint256 _value) public returns (bool success)
104  ```
105  
106  
107  
108  #### transferFrom
109  
110  Transfers `_value` amount of tokens from address `_from` to address `_to`, and MUST fire the `Transfer` event.
111  
112  The `transferFrom` method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf.
113  This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies.
114  The function SHOULD `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism.
115  
116  *Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event.
117  
118  ``` js
119  function transferFrom(address _from, address _to, uint256 _value) public returns (bool success)
120  ```
121  
122  
123  
124  #### approve
125  
126  Allows `_spender` to withdraw from your account multiple times, up to the `_value` amount. If this function is called again it overwrites the current allowance with `_value`.
127  
128  **NOTE**: To prevent attack vectors like the one [described here](https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/) and discussed [here](https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729),
129  clients SHOULD make sure to create user interfaces in such a way that they set the allowance first to `0` before setting it to another value for the same spender.
130  THOUGH The contract itself shouldn't enforce it, to allow backwards compatibility with contracts deployed before
131  
132  ``` js
133  function approve(address _spender, uint256 _value) public returns (bool success)
134  ```
135  
136  
137  #### allowance
138  
139  Returns the amount which `_spender` is still allowed to withdraw from `_owner`.
140  
141  ``` js
142  function allowance(address _owner, address _spender) public view returns (uint256 remaining)
143  ```
144  
145  
146  
147  ### Events
148  
149  
150  #### Transfer
151  
152  MUST trigger when tokens are transferred, including zero value transfers.
153  
154  A token contract which creates new tokens SHOULD trigger a Transfer event with the `_from` address set to `0x0` when tokens are created.
155  
156  ``` js
157  event Transfer(address indexed _from, address indexed _to, uint256 _value)
158  ```
159  
160  
161  
162  #### Approval
163  
164  MUST trigger on any successful call to `approve(address _spender, uint256 _value)`.
165  
166  ``` js
167  event Approval(address indexed _owner, address indexed _spender, uint256 _value)
168  ```
169  
170  
171  
172  ## Implementation
173  
174  There are already plenty of ERC20-compliant tokens deployed on the Ethereum network.
175  Different implementations have been written by various teams that have different trade-offs: from gas saving to improved security.
176  
177  #### Example implementations are available at
178  - [OpenZeppelin implementation](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/9b3710465583284b8c4c5d2245749246bb2e0094/contracts/token/ERC20/ERC20.sol)
179  - [ConsenSys implementation](https://github.com/ConsenSys/Tokens/blob/fdf687c69d998266a95f15216b1955a4965a0a6d/contracts/eip20/EIP20.sol)
180  
181  
182  ## History
183  
184  Historical links related to this standard:
185  
186  - Original proposal from Vitalik Buterin: https://github.com/ethereum/wiki/wiki/Standardized_Contract_APIs/499c882f3ec123537fc2fccd57eaa29e6032fe4a
187  - Reddit discussion: https://www.reddit.com/r/ethereum/comments/3n8fkn/lets_talk_about_the_coin_standard/
188  - Original Issue #20: https://github.com/ethereum/EIPs/issues/20
189  
190  
191  
192  ## Copyright
193  Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).