The following describes standard functions a token contract and contract working with specified token can implement to prevent accidentally sends of tokens to contracts and make token transactions behave like ether transactions.
Motivation
Problems of ERC20 that ERC223 will solve:
Impossibility of handling incoming transactions in receiver contract.
Tokens could be sent to contract that is not designed to work with tokens without handling and potentially could be lost. At least $72000 are lost at the moment. This problem is described here.
Token-transactions should match Ethereum ideology of uniformity. When a user needs to transfer his funds, he must always perform transfer. Doesn't matter is user depositing in contract or sending to an externally owned account.
Those will allow contracts to handle incoming token transactions and prevent accidentally sent tokens from being accepted by contracts.
For example decentralized exchange will no more need to force users to call approve at token contract then call deposit that is calling transferFrom taking allowed tokens. Token transaction will automatically be handled inside the exchange contract.
The most important here is a call of tokenFallback when performing a transaction to a contract.
Specification
Token
Contracts that work with tokens
Methods
NOTE: An important point is that contract developers must implement tokenFallback if they want their contracts to work with the specified tokens.
If the receiver does not implement the tokenFallback function, consider the contract is not designed to work with tokens, then the transaction must fail and no tokens will be transferred. An analogy with an Ether transaction that is failing when trying to send Ether to a contract that did not implement function() payable.
totalSupply
function totalSupply() constant returns (uint256 totalSupply)
Get the total token supply
name
function name() constant returns (string _name)
Get the name of token
symbol
function symbol() constant returns (string _symbol)
Get the symbol of token
decimals
function decimals() constant returns (uint8 _decimals)
Get decimals of token
balanceOf
function balanceOf(address _owner) constant returns (uint256 balance)
Get the account balance of another account with address _owner
transfer(address, uint, bytes)
function transfer(address _to, uint _value, bytes _data) returns (bool success)
function that is always called when someone wants to transfer tokens.
This function must transfer tokens and invoke the function tokenFallback (address, uint256, bytes) in _to, if _to is a contract. If the tokenFallback function is not implemented in _to (receiver contract), then the transaction must fail and the transfer of tokens should not occur.
If _to is an externally owned address, then the transaction must be sent without trying to execute tokenFallback in _to.
_data can be attached to this token transaction and it will stay in blockchain forever (requires more gas). _data can be empty.
NOTE: The recommended way to check whether the _to is a contract or an address is to assemble the code of _to. If there is no code in _to, then this is an externally owned address, otherwise it's a contract.
IMPORTANT: Token fallback function that will be called at receiver contract must be named tokenFallback and take parametersaddress, uint256,bytes. This function must have 0xc0ee0b8asignature.
transfer(address, uint)
function transfer(address _to, uint _value) returns (bool success)
Needed due to backwards compatibility reasons because of ERC20 transfer function doesn't have bytes parameter. This function must transfer tokens and invoke the function tokenFallback(address, uint256, bytes) in _to, if _to is a contract. If the tokenFallback function is not implemented in _to (receiver contract), then the transaction must fail and the transfer of tokens should not occur.
IMPORTANT: Token fallback function that will be called at receiver contract must be named tokenFallback and take parametersaddress, uint256,bytes. This function must have 0xc0ee0b8asignature.
function tokenFallback(address _from, uint _value, bytes _data)
A function to handle token transfers that is called from token contract when token holder is sending tokens. _from is a token sender, _value is amount of incoming tokens and _data is attached data similar to data in Ether transactions. Works like fallback function for Ether transactions and returns nothing.
NOTE: msg.sender will be a token-contract inside the tokenFallback function. It may be important to filter which tokens are sent (by token-contract address). The token sender (the person who initiated the token transaction) will be _from inside thetokenFallback function.
IMPORTANT: This function must be named tokenFallback and take parametersaddress, uint256,bytes to match the function signature0xc0ee0b8a.
ERC: 223 Title: Token standard Author: Dexaran, dexaran820@gmail.com Status: Draft Type: ERC Created: 5-03.2017 Resolution: https://github.com/Dexaran/ERC23-tokens ERC20 compatible example: https://github.com/Dexaran/ERC23-tokens/blob/ERC20_compatible/ERC23_token.sol
Abstract
The following describes standard functions a token contract and contract working with specified token can implement to prevent accidentally sends of tokens to contracts and make token transactions behave like ether transactions.
Motivation
Problems of ERC20 that ERC223 will solve:
transfer
. Doesn't matter is user depositing in contract or sending to an externally owned account.Those will allow contracts to handle incoming token transactions and prevent accidentally sent tokens from being accepted by contracts. For example decentralized exchange will no more need to force users to call
approve
at token contract then calldeposit
that is callingtransferFrom
taking allowed tokens. Token transaction will automatically be handled inside the exchange contract.The most important here is a call of
tokenFallback
when performing a transaction to a contract.Specification
Token Contracts that work with tokens
Methods
NOTE: An important point is that contract developers must implement
tokenFallback
if they want their contracts to work with the specified tokens.If the receiver does not implement the
tokenFallback
function, consider the contract is not designed to work with tokens, then the transaction must fail and no tokens will be transferred. An analogy with an Ether transaction that is failing when trying to send Ether to a contract that did not implementfunction() payable
.totalSupply
Get the total token supply
name
Get the name of token
symbol
Get the symbol of token
decimals
Get decimals of token
balanceOf
Get the account balance of another account with address _owner
transfer(address, uint, bytes)
function that is always called when someone wants to transfer tokens. This function must transfer tokens and invoke the function
tokenFallback (address, uint256, bytes)
in_to
, if _to is a contract. If thetokenFallback
function is not implemented in_to
(receiver contract), then the transaction must fail and the transfer of tokens should not occur. If_to
is an externally owned address, then the transaction must be sent without trying to executetokenFallback
in_to
._data
can be attached to this token transaction and it will stay in blockchain forever (requires more gas)._data
can be empty.NOTE: The recommended way to check whether the
_to
is a contract or an address is to assemble the code of_to
. If there is no code in_to
, then this is an externally owned address, otherwise it's a contract.IMPORTANT: Token fallback function that will be called at receiver contract must be named
tokenFallback
and take parametersaddress
,uint256
,bytes
. This function must have0xc0ee0b8a
signature.transfer(address, uint)
Needed due to backwards compatibility reasons because of ERC20 transfer function doesn't have
bytes
parameter. This function must transfer tokens and invoke the functiontokenFallback(address, uint256, bytes)
in_to
, if _to is a contract. If thetokenFallback
function is not implemented in_to
(receiver contract), then the transaction must fail and the transfer of tokens should not occur.IMPORTANT: Token fallback function that will be called at receiver contract must be named
tokenFallback
and take parametersaddress
,uint256
,bytes
. This function must have0xc0ee0b8a
signature.Events
Transfer
Triggered when tokens are transferred.
Contract to work with tokens
A function to handle token transfers that is called from token contract when token holder is sending tokens.
_from
is a token sender,_value
is amount of incoming tokens and_data
is attached data similar to data in Ether transactions. Works like fallback function for Ether transactions and returns nothing.NOTE:
msg.sender
will be a token-contract inside thetokenFallback
function. It may be important to filter which tokens are sent (by token-contract address). The token sender (the person who initiated the token transaction) will be_from
inside thetokenFallback
function.IMPORTANT: This function must be named
tokenFallback
and take parametersaddress
,uint256
,bytes
to match the function signature0xc0ee0b8a
.Recommended implementation
This is highly recommended implementation of ERC 223 token: https://github.com/Dexaran/ERC23-tokens/tree/Recommended