From 80fa7db762d6db400372e756a81d22c26d13a311 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Mon, 24 Apr 2017 15:37:03 +0200 Subject: [PATCH 01/13] added erc20 --- EIPS/eip-token-standard.md | 113 +++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 EIPS/eip-token-standard.md diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md new file mode 100644 index 0000000000000..a7ffa494422c0 --- /dev/null +++ b/EIPS/eip-token-standard.md @@ -0,0 +1,113 @@ +This is the suggested template for new EIPs. + +Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`. + +## Preamble + + EIP: (I Suggest 20) + Title: + Author: Fabian Vogelsteller , Vitalik Buterin + Type: Informational + Category ERC + Status: Draft + Created: 2015-11-19 + + +## Simple Summary + +Token standard interface. + + +## Abstract + +The following standard allows for people to implement a token standard API withing their smart contracts. + +This standard provides basic functionality for sending and approving tokens to be spend by a third party. + + +## Motivation + +Following the same standard interface allows those tokens to be used in many wallets and exchanges. + + +## Specification + +## Token +### Methods + +**NOTE**: An important point is that callers should handle `false` from `returns (bool success)`. Callers should not assume that `false` is never returned! + +#### totalSupply + +``` js +function totalSupply() constant returns (uint256 totalSupply) +``` + +Get the total token supply +#### balanceOf + +``` js +function balanceOf(address _owner) constant returns (uint256 balance) +``` + +Get the account balance of another account with address `_owner` +#### transfer + +``` js +function transfer(address _to, uint256 _value) returns (bool success) +``` + +Send `_value` amount of tokens to address `_to` +#### transferFrom + +``` js +function transferFrom(address _from, address _to, uint256 _value) returns (bool success) +``` + +Send `_value` amount of tokens from address `_from` to address `_to` + +The `transferFrom` method is used for a withdraw workflow, allowing contracts to send tokens on your behalf, for example to "deposit" to a contract address and/or to charge fees in sub-currencies; the command should fail unless the `_from` account has deliberately authorized the sender of the message via some mechanism; we propose these standardized APIs for approval: +#### approve + +``` js +function approve(address _spender, uint256 _value) returns (bool success) +``` + +Allow _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. +To prevent attack vectors like described here: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ +make sure to set the allowance to 0 before setting it to another value for the same spender. +#### allowance + +``` js +function allowance(address _owner, address _spender) constant returns (uint256 remaining) +``` + +Returns the amount which `_spender` is still allowed to withdraw from `_owner` +### Events +#### Transfer + +``` js +event Transfer(address indexed _from, address indexed _to, uint256 _value) +``` + +Triggered when tokens are transferred. +#### Approval + +``` js +event Approval(address indexed _owner, address indexed _spender, uint256 _value) +``` + +Triggered whenever `approve(address _spender, uint256 _value)` is called. + + +## Implementation + +Different 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 + +Implentation adding the force 0 before calling approve again: +- https://github.com/Giveth/minime/blob/master/MiniMeToken.sol + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 4f987982792430e3f31cea845fd6e01e111c2c33 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Mon, 24 Apr 2017 15:42:04 +0200 Subject: [PATCH 02/13] reformatted --- EIPS/eip-token-standard.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index a7ffa494422c0..59806a7677bae 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -44,6 +44,8 @@ function totalSupply() constant returns (uint256 totalSupply) ``` Get the total token supply + + #### balanceOf ``` js @@ -51,6 +53,8 @@ function balanceOf(address _owner) constant returns (uint256 balance) ``` Get the account balance of another account with address `_owner` + + #### transfer ``` js @@ -58,6 +62,8 @@ function transfer(address _to, uint256 _value) returns (bool success) ``` Send `_value` amount of tokens to address `_to` + + #### transferFrom ``` js @@ -67,6 +73,8 @@ function transferFrom(address _from, address _to, uint256 _value) returns (bool Send `_value` amount of tokens from address `_from` to address `_to` The `transferFrom` method is used for a withdraw workflow, allowing contracts to send tokens on your behalf, for example to "deposit" to a contract address and/or to charge fees in sub-currencies; the command should fail unless the `_from` account has deliberately authorized the sender of the message via some mechanism; we propose these standardized APIs for approval: + + #### approve ``` js @@ -76,6 +84,8 @@ function approve(address _spender, uint256 _value) returns (bool success) Allow _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. To prevent attack vectors like described here: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ make sure to set the allowance to 0 before setting it to another value for the same spender. + + #### allowance ``` js @@ -83,7 +93,11 @@ function allowance(address _owner, address _spender) constant returns (uint256 r ``` Returns the amount which `_spender` is still allowed to withdraw from `_owner` + + ### Events + + #### Transfer ``` js @@ -91,6 +105,8 @@ event Transfer(address indexed _from, address indexed _to, uint256 _value) ``` Triggered when tokens are transferred. + + #### Approval ``` js From d540a40118b09731e9681f10cb3dcc4a2a9cfe79 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 3 May 2017 15:38:54 +0200 Subject: [PATCH 03/13] fixed spelling suggestions --- EIPS/eip-token-standard.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index 59806a7677bae..e5fabc9711b2b 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -1,33 +1,27 @@ -This is the suggested template for new EIPs. - -Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`. - ## Preamble EIP: (I Suggest 20) Title: Author: Fabian Vogelsteller , Vitalik Buterin Type: Informational - Category ERC Status: Draft Created: 2015-11-19 ## Simple Summary -Token standard interface. +A standard interface for tokens. ## Abstract -The following standard allows for people to implement a token standard API withing their smart contracts. - -This standard provides basic functionality for sending and approving tokens to be spend by a third party. +The following standard allows for the implementation of a standard API for tokens within their smart contracts: +it primarily provides basic functionality to transfer tokens and allow them to be approved to be spend by another on-chain third party. ## Motivation -Following the same standard interface allows those tokens to be used in many wallets and exchanges. +A standard interface allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges. ## Specification @@ -61,7 +55,7 @@ Get the account balance of another account with address `_owner` function transfer(address _to, uint256 _value) returns (bool success) ``` -Send `_value` amount of tokens to address `_to` +Transfer `_value` amount of tokens to address `_to` #### transferFrom @@ -82,7 +76,7 @@ function approve(address _spender, uint256 _value) returns (bool success) ``` Allow _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. -To prevent attack vectors like described here: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ +To prevent attack vectors like the one described here: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ make sure to set the allowance to 0 before setting it to another value for the same spender. @@ -118,11 +112,14 @@ Triggered whenever `approve(address _spender, uint256 _value)` is called. ## Implementation -Different implementations are available at +There are already plenty of ERC20-compliant tokens deployed on the Ethereum network and is the most widely used standard. +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 -Implentation adding the force 0 before calling approve again: +#### Implementation adding the force 0 before calling approve again: - https://github.com/Giveth/minime/blob/master/MiniMeToken.sol ## Copyright From c96876e0b94835b7af7dd877b229749d8fa6dfb4 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 3 May 2017 15:45:15 +0200 Subject: [PATCH 04/13] added name, symbol, decimals --- EIPS/eip-token-standard.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index e5fabc9711b2b..c3152b9991054 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -31,6 +31,33 @@ A standard interface allows any tokens on Ethereum to be re-used by other applic **NOTE**: An important point is that callers should handle `false` from `returns (bool success)`. Callers should not assume that `false` is never returned! +#### name + +``` js +function name() constant returns (string name) +``` + +Returns the name of the token. E.g. "MyToken" + + +#### symbol + +``` js +function symbol() constant returns (string symbol) +``` + +Returns the symbol of the token. E.g. "MYT" + + +#### decimals + +``` js +function decimals() constant returns (uint8 decimals) +``` + +Returns the number of decimals the token uses. E.g. 8, which would mean to divide the token amount by 100000000 to get its user representation. + + #### totalSupply ``` js From 2af51d6c80f3264199e3c77200928323ca231cf9 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 17 May 2017 10:51:09 +0200 Subject: [PATCH 05/13] added changes and moved method description above the func declaration --- EIPS/eip-token-standard.md | 68 +++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index c3152b9991054..40f65ed1022ac 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -1,10 +1,11 @@ ## Preamble - EIP: (I Suggest 20) - Title: + EIP: 20 + Title: ERC-20 Token Standard Author: Fabian Vogelsteller , Vitalik Buterin - Type: Informational - Status: Draft + Type: Standard + Category: ERC + Status: Accepted Created: 2015-11-19 @@ -15,8 +16,8 @@ A standard interface for tokens. ## Abstract -The following standard allows for the implementation of a standard API for tokens within their smart contracts: -it primarily provides basic functionality to transfer tokens and allow them to be approved to be spend by another on-chain third party. +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 @@ -29,91 +30,102 @@ A standard interface allows any tokens on Ethereum to be re-used by other applic ## Token ### Methods -**NOTE**: An important point is that callers should handle `false` from `returns (bool success)`. Callers should not assume that `false` is never returned! +**NOTE**: Callers should handle `false` from `returns (bool success)`. Callers should not assume that `false` is never returned! #### name +Returns the name of the token - e.g. `"MyToken"` + ``` js function name() constant returns (string name) ``` -Returns the name of the token. E.g. "MyToken" - #### symbol +Returns the symbol of the token. E.g. "MYT" + ``` js function symbol() constant returns (string symbol) ``` -Returns the symbol of the token. E.g. "MYT" #### 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. + ``` js function decimals() constant returns (uint8 decimals) ``` -Returns the number of decimals the token uses. E.g. 8, which would mean to divide the token amount by 100000000 to get its user representation. - #### totalSupply +Returns the total token supply. + ``` js function totalSupply() constant returns (uint256 totalSupply) ``` -Get the total token supply #### balanceOf +Returns the account balance of another account with address `_owner`. + ``` js function balanceOf(address _owner) constant returns (uint256 balance) ``` -Get the account balance of another account with address `_owner` #### transfer +Transfers `_value` amount of tokens to address `_to`. +The command should `throw` if the `_from` account balance has not enough tokens to spend. + + ``` js function transfer(address _to, uint256 _value) returns (bool success) ``` -Transfer `_value` amount of tokens to address `_to` #### transferFrom +Transfers `_value` amount of tokens from address `_from` to address `_to`. + +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 command should `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism. + ``` js function transferFrom(address _from, address _to, uint256 _value) returns (bool success) ``` -Send `_value` amount of tokens from address `_from` to address `_to` - -The `transferFrom` method is used for a withdraw workflow, allowing contracts to send tokens on your behalf, for example to "deposit" to a contract address and/or to charge fees in sub-currencies; the command should fail unless the `_from` account has deliberately authorized the sender of the message via some mechanism; we propose these standardized APIs for approval: #### 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), +make sure to force users set the allowance to `0` before setting it to another value for the same spender. + ``` js function approve(address _spender, uint256 _value) returns (bool success) ``` -Allow _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. -To prevent attack vectors like the one described here: https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/ -make sure to set the allowance to 0 before setting it to another value for the same spender. - #### allowance +Returns the amount which `_spender` is still allowed to withdraw from `_owner`. + ``` js function allowance(address _owner, address _spender) constant returns (uint256 remaining) ``` -Returns the amount which `_spender` is still allowed to withdraw from `_owner` ### Events @@ -121,32 +133,34 @@ Returns the amount which `_spender` is still allowed to withdraw from `_owner` #### Transfer +Triggered when tokens are transferred. + ``` js event Transfer(address indexed _from, address indexed _to, uint256 _value) ``` -Triggered when tokens are transferred. #### Approval +Triggered when `approve(address _spender, uint256 _value)` is called. + ``` js event Approval(address indexed _owner, address indexed _spender, uint256 _value) ``` -Triggered whenever `approve(address _spender, uint256 _value)` is called. ## Implementation -There are already plenty of ERC20-compliant tokens deployed on the Ethereum network and is the most widely used standard. +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 adding the force 0 before calling approve again: +#### Implementation of adding the force to 0 before calling "approve" again: - https://github.com/Giveth/minime/blob/master/MiniMeToken.sol ## Copyright From b5902d3ffb7da5ee5eff991119cb87386f88cc72 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Mon, 12 Jun 2017 12:34:00 +0200 Subject: [PATCH 06/13] changed example address --- EIPS/eip-token-standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index 40f65ed1022ac..d2d4622a27672 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -161,7 +161,7 @@ Different implementations have been written by various teams that have different - 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/MiniMeToken.sol +- 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/). From a447ded6aeb70fcae41bcff41243123f93d3f0a4 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 21 Jun 2017 08:39:20 +0200 Subject: [PATCH 07/13] added transfer 0 clearification --- EIPS/eip-token-standard.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index d2d4622a27672..f3341c07c2744 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -82,9 +82,10 @@ function balanceOf(address _owner) constant returns (uint256 balance) #### transfer -Transfers `_value` amount of tokens to address `_to`. -The command should `throw` if the `_from` account balance has not enough tokens to spend. +Transfers `_value` amount of tokens to address `_to`, and should fire the `Transfer` event. +The function should `throw` if the `_from` account balance has not enough tokens to spend. +*Note* Transfers of 0 values should be treated as normal transfers and fire the `Transfer` event. ``` js function transfer(address _to, uint256 _value) returns (bool success) @@ -94,11 +95,13 @@ function transfer(address _to, uint256 _value) returns (bool success) #### transferFrom -Transfers `_value` amount of tokens from address `_from` to address `_to`. +Transfers `_value` amount of tokens from address `_from` to address `_to`, and should 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 command should `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism. +The function should `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism. + +*Note* Transfers of 0 values should be treated as normal transfers and fire the `Transfer` event. ``` js function transferFrom(address _from, address _to, uint256 _value) returns (bool success) From ed1c87a72d72d8c2722ae4f47aa9588ef210f909 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 21 Jun 2017 11:04:15 +0200 Subject: [PATCH 08/13] addressed RFC2119 --- EIPS/eip-token-standard.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md index f3341c07c2744..7f838cd32c683 100644 --- a/EIPS/eip-token-standard.md +++ b/EIPS/eip-token-standard.md @@ -30,7 +30,8 @@ A standard interface allows any tokens on Ethereum to be re-used by other applic ## Token ### Methods -**NOTE**: Callers should handle `false` from `returns (bool success)`. Callers should not assume that `false` is never returned! +**NOTE**: Callers MUST handle `false` from `returns (bool success)`. Callers MUST NOT assume that `false` is never returned! + #### name @@ -82,10 +83,10 @@ function balanceOf(address _owner) constant returns (uint256 balance) #### transfer -Transfers `_value` amount of tokens to address `_to`, and should fire the `Transfer` event. -The function should `throw` if the `_from` account balance has not enough tokens to spend. +Transfers `_value` amount of tokens to address `_to`, and MUST fire the `Transfer` event. +The function SHOULD `throw` if the `_from` account balance has not enough tokens to spend. -*Note* Transfers of 0 values should be treated as normal transfers and fire the `Transfer` event. +*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) @@ -95,13 +96,13 @@ function transfer(address _to, uint256 _value) returns (bool success) #### transferFrom -Transfers `_value` amount of tokens from address `_from` to address `_to`, and should fire the `Transfer` event. +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. +The function SHOULD `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism. -*Note* Transfers of 0 values should be treated as normal transfers and fire the `Transfer` event. +*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) @@ -114,7 +115,7 @@ function transferFrom(address _from, address _to, uint256 _value) returns (bool 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), -make sure to force users set the allowance to `0` before setting it to another value for the same spender. +make sure to force users to set the allowance to `0` before setting it to another value for the same spender. ``` js function approve(address _spender, uint256 _value) returns (bool success) @@ -136,7 +137,7 @@ function allowance(address _owner, address _spender) constant returns (uint256 r #### Transfer -Triggered when tokens are transferred. +MUST trigger when tokens are transferred. ``` js event Transfer(address indexed _from, address indexed _to, uint256 _value) @@ -146,7 +147,7 @@ event Transfer(address indexed _from, address indexed _to, uint256 _value) #### Approval -Triggered when `approve(address _spender, uint256 _value)` is called. +MUST trigger when `approve(address _spender, uint256 _value)` is called. ``` js event Approval(address indexed _owner, address indexed _spender, uint256 _value) From efa1fc7f597b9f088d806e7e230bf322be04dfcb Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Thu, 13 Jul 2017 13:58:18 +0200 Subject: [PATCH 09/13] renamed file and add small spelling changes --- EIPS/eip-token-standard.md | 171 ------------------------------------- 1 file changed, 171 deletions(-) delete mode 100644 EIPS/eip-token-standard.md diff --git a/EIPS/eip-token-standard.md b/EIPS/eip-token-standard.md deleted file mode 100644 index 7f838cd32c683..0000000000000 --- a/EIPS/eip-token-standard.md +++ /dev/null @@ -1,171 +0,0 @@ -## Preamble - - EIP: 20 - Title: ERC-20 Token Standard - Author: Fabian Vogelsteller , Vitalik Buterin - 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"` - -``` js -function name() constant returns (string name) -``` - - -#### symbol - -Returns the symbol of the token. E.g. "MYT" - -``` 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. - -``` 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 has not enough tokens to spend. - -*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), -make sure to force users to set the allowance to `0` before setting it to another value for the same spender. - -``` 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. - -``` js -event Transfer(address indexed _from, address indexed _to, uint256 _value) -``` - - - -#### Approval - -MUST trigger when `approve(address _spender, uint256 _value)` is called. - -``` 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/). From dd7e548653011b8b66f17ed39a97c46ebcb50f3a Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Thu, 13 Jul 2017 14:17:43 +0200 Subject: [PATCH 10/13] changed name --- EIPS/eip-20-token-standard.md | 183 ++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 EIPS/eip-20-token-standard.md diff --git a/EIPS/eip-20-token-standard.md b/EIPS/eip-20-token-standard.md new file mode 100644 index 0000000000000..ddda6e75cce94 --- /dev/null +++ b/EIPS/eip-20-token-standard.md @@ -0,0 +1,183 @@ +## Preamble + + EIP: 20 + Title: ERC-20 Token Standard + Author: Fabian Vogelsteller , Vitalik Buterin + 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 has not enough tokens to spend. + +An 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), +make sure to force users to set the allowance to `0` before setting it to another value for the same spender. + +``` 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/). From 94bc4311e889c2c58c561c074be1483f48ac9374 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Mon, 24 Jul 2017 19:59:21 +0200 Subject: [PATCH 11/13] small corrections --- EIPS/eip-20-token-standard.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-20-token-standard.md b/EIPS/eip-20-token-standard.md index ddda6e75cce94..a81787851fe27 100644 --- a/EIPS/eip-20-token-standard.md +++ b/EIPS/eip-20-token-standard.md @@ -96,7 +96,7 @@ function balanceOf(address _owner) constant returns (uint256 balance) Transfers `_value` amount of tokens to address `_to`, and MUST fire the `Transfer` event. The function SHOULD `throw` if the `_from` account balance has not enough tokens to spend. -An token contract which creates new tokens SHOULD trigger a Transfer event with the `_from` address set to `0x0` when tokens are created. +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. @@ -127,7 +127,8 @@ function transferFrom(address _from, address _to, uint256 _value) returns (bool 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), -make sure to force users to set the allowance to `0` before setting it to another value for the same spender. +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) From e0cc8c2609d8f77e343c952b055d306dd16cb016 Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Wed, 9 Aug 2017 11:28:38 +0200 Subject: [PATCH 12/13] small spelling --- EIPS/eip-20-token-standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-20-token-standard.md b/EIPS/eip-20-token-standard.md index a81787851fe27..2952404f446c1 100644 --- a/EIPS/eip-20-token-standard.md +++ b/EIPS/eip-20-token-standard.md @@ -94,7 +94,7 @@ 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 has not enough tokens to spend. +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. From 3a45fb19bab41481aee0cf5d3f70fbff4c1d4f9e Mon Sep 17 00:00:00 2001 From: Fabian Vogelsteller Date: Fri, 8 Sep 2017 13:38:14 +0200 Subject: [PATCH 13/13] fix spelling --- EIPS/eip-20-token-standard.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-20-token-standard.md b/EIPS/eip-20-token-standard.md index 2952404f446c1..c5facc53a4a76 100644 --- a/EIPS/eip-20-token-standard.md +++ b/EIPS/eip-20-token-standard.md @@ -37,7 +37,7 @@ A standard interface allows any tokens on Ethereum to be re-used by other applic Returns the name of the token - e.g. `"MyToken"`. -OPTIONAL - This method can be used to improve useability, +OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. @@ -50,7 +50,7 @@ function name() constant returns (string name) Returns the symbol of the token. E.g. "HIX". -OPTIONAL - This method can be used to improve useability, +OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ``` js @@ -63,7 +63,7 @@ function symbol() constant returns (string symbol) 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, +OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ``` js