ERC20 Token Standard

EIPS/eip-20-token-standard.md

@@ -0,0 +1,184 @@
+## Preamble
+
+    EIP: 20
+    Title: ERC-20 Token Standard
+    Author: Fabian Vogelsteller <[email protected]>, Vitalik Buterin <[email protected]>
+    Type: Standard
+    Category: ERC
+    Status: Accepted
+    Created: 2015-11-19
+
+
+## Simple Summary
+
+A standard interface for tokens.
+
+
+## Abstract
+
+The following standard allows for the implementation of a standard API for tokens within smart contracts.
+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.
+
+
+## Motivation
+
+A standard interface allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges.
+
+
+## Specification
+
+## Token
+### Methods
+
+**NOTE**: Callers MUST handle `false` from `returns (bool success)`.  Callers MUST NOT assume that `false` is never returned!
+
+
+#### name
+
+Returns the name of the token - e.g. `"MyToken"`.
+
+OPTIONAL - This method can be used to improve useability,
+but interfaces and other contracts MUST NOT expect these values to be present.
+
+
+``` js
+function name() constant returns (string name)
+```
+
+
+#### symbol
+
+Returns the symbol of the token. E.g. "HIX".
+
+OPTIONAL - This method can be used to improve useability,
+but interfaces and other contracts MUST NOT expect these values to be present.
+
+``` js
+function symbol() constant returns (string symbol)
+```
+
+
+
+#### decimals
+
+Returns the number of decimals the token uses - e.g. `8`, means to divide the token amount by `100000000` to get its user representation.
+
+OPTIONAL - This method can be used to improve useability,
+but interfaces and other contracts MUST NOT expect these values to be present.
+
+``` js
+function decimals() constant returns (uint8 decimals)
+```
+
+
+#### totalSupply
+
+Returns the total token supply.
+
+``` js
+function totalSupply() constant returns (uint256 totalSupply)
+```
+
+
+
+#### balanceOf
+
+Returns the account balance of another account with address `_owner`.
+
+``` js
+function balanceOf(address _owner) constant returns (uint256 balance)
+```
+
+
+
+#### transfer
+
+Transfers `_value` amount of tokens to address `_to`, and MUST fire the `Transfer` event.
+The function SHOULD `throw` if the `_from` account balance does not have enough tokens to spend.
+
+A token contract which creates new tokens SHOULD trigger a Transfer event with the `_from` address set to `0x0` when tokens are created.
+
+*Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event.
+
+``` js
+function transfer(address _to, uint256 _value) returns (bool success)
+```
+
+
+
+#### transferFrom
+
+Transfers `_value` amount of tokens from address `_from` to address `_to`, and MUST fire the `Transfer` event.
+
+The `transferFrom` method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf.
+This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies.
+The function SHOULD `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism.
+
+*Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event.
+
+``` js
+function transferFrom(address _from, address _to, uint256 _value) returns (bool success)
+```
+
+
+
+#### approve
+
+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`.
+
+**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),
+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.
+THOUGH The contract itself shouldn't enforce it, to allow backwards compatilibilty with contracts deployed before
+
+``` js
+function approve(address _spender, uint256 _value) returns (bool success)
+```
+
+
+#### allowance
+
+Returns the amount which `_spender` is still allowed to withdraw from `_owner`.
+
+``` js
+function allowance(address _owner, address _spender) constant returns (uint256 remaining)
+```
+
+
+
+### Events
+
+
+#### Transfer
+
+MUST trigger when tokens are transferred, including zero value transfers.
+
+``` js
+event Transfer(address indexed _from, address indexed _to, uint256 _value)
+```
+
+
+
+#### Approval
+
+MUST trigger on any successful call to `approve(address _spender, uint256 _value)`.
+
+``` js
+event Approval(address indexed _owner, address indexed _spender, uint256 _value)
+```
+
+
+
+## Implementation
+
+There are already plenty of ERC20-compliant tokens deployed on the Ethereum network.
+Different implementations have been written by various teams that have different trade-offs: from gas saving to improved security.
+
+#### Example implementations are available at
+- https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/contracts/token/StandardToken.sol
+- https://github.com/ConsenSys/Tokens/blob/master/Token_Contracts/contracts/StandardToken.sol
+
+#### Implementation of adding the force to 0 before calling "approve" again:
+- https://github.com/Giveth/minime/blob/master/contracts/MiniMeToken.sol
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).