nep-17.mediawiki

<pre>
  NEP: 17
  Title: Token Standard
  Author: Erik Zhang <erik@neo.org>
  Type: Standard
  Status: Final
  Created: 2020-11-12
  Replaces: 5
</pre>

==Abstract==

This proposal outlines a token standard for the NEO blockchain that will provide systems with a generalized interaction mechanism for tokenized Smart Contracts.  This mechanic, along with the justification for each feature are defined.  A template and examples are also provided to enable the development community.

==Motivation==

As the NEO blockchain scales, Smart Contract deployment and invocation will become increasingly important.  Without a standard interaction method, systems will be required to maintain a unique API for each contract, regardless of their similarity to other contracts.  Tokenized contracts present themselves as a prime example of this need because their basic operating mechanism is the same.  A standard method for interacting with these tokens relieves the entire ecosystem from maintaining a definition for basic operations that are required by every Smart Contract that employs a token.

==Specification==

In the method definitions below, we provide both the definitions of the functions as they are defined in the contract as well as the invoke parameters.

===Methods===

====symbol====

<pre>
{
  "name": "symbol",
  "safe": true,
  "parameters": [],
  "returntype": "String"
}
</pre>

Returns a short string representing symbol of the token managed in this contract. e.g. <code>"MYT"</code>. This string MUST be valid ASCII, MUST NOT contain whitespace or control characters, SHOULD be limited to uppercase Latin alphabet (i.e. the 26 letters used in English) and SHOULD be short (3-8 characters is recommended).

This method MUST always return the same value every time it is invoked.

====decimals====

<pre>
{
  "name": "decimals",
  "safe": true,
  "parameters": [],
  "returntype": "Integer"
}
</pre>

Returns the number of decimals used by the token - e.g. <code>8</code>, means to divide the token amount by <code>100,000,000</code> to get its user representation.

This method MUST always return the same value every time it is invoked.

====totalSupply====

<pre>
{
  "name": "totalSupply",
  "safe": true,
  "parameters": [],
  "returntype": "Integer"
}
</pre>

Returns the total token supply deployed in the system.

====balanceOf====

<pre>
{
  "name": "balanceOf",
  "safe": true,
  "parameters": [
    {
      "name": "account",
      "type": "Hash160"
    }
  ],
  "returntype": "Integer"
}
</pre>

Returns the token balance of the <code>account</code>.

The parameter <code>account</code> MUST be a 20-byte address. If not, this method SHOULD <code>throw</code> an exception.

If the <code>account</code> is an unused address, this method MUST return <code>0</code>.

====transfer====

<pre>
{
  "name": "transfer",
  "safe": false,
  "parameters": [
    {
      "name": "from",
      "type": "Hash160"
    },
    {
      "name": "to",
      "type": "Hash160"
    },
    {
      "name": "amount",
      "type": "Integer"
    },
    {
      "name": "data",
      "type": "Any"
    }
  ],
  "returntype": "Boolean"
}
</pre>

Transfers an <code>amount</code> of tokens from the <code>from</code> account to the <code>to</code> account.

The parameters <code>from</code> and <code>to</code> MUST be 20-byte addresses. If not, this method SHOULD <code>throw</code> an exception.

The parameter <code>amount</code> MUST be greater than or equal to <code>0</code>. If not, this method SHOULD <code>throw</code> an exception.

The function MUST return <code>false</code> if the <code>from</code> account balance does not have enough tokens to spend.

If the method succeeds, it MUST fire the <code>Transfer</code> event, and MUST return <code>true</code>, even if the <code>amount</code> is <code>0</code>, or <code>from</code> and <code>to</code> are the same address.

The function SHOULD check whether the <code>from</code> address equals the caller contract hash. If so, the transfer SHOULD be processed; If not, the function SHOULD use the SYSCALL <code>Neo.Runtime.CheckWitness</code> to verify the transfer.

If the transfer is not processed, the function MUST return <code>false</code>.

If the receiver is a deployed contract, the function MUST call <code>onNEP17Payment</code> method on receiver contract with the <code>data</code> parameter from <code>transfer</code> AFTER firing the <code>Transfer</code> event. If the receiver doesn't want to receive this transfer it MUST call <code>ABORT</code>.

<pre>
{
  "name": "onNEP17Payment",
  "parameters": [
    {
      "name": "from",
      "type": "Hash160"
    },
    {
      "name": "amount",
      "type": "Integer"
    },
    {
      "name": "data",
      "type": "Any"
    }
  ],
  "returntype": "Void"
}
</pre>

===Events===

====Transfer====

<pre>
{
  "name": "Transfer",
  "parameters": [
    {
      "name": "from",
      "type": "Hash160"
    },
    {
      "name": "to",
      "type": "Hash160"
    },
    {
      "name": "amount",
      "type": "Integer"
    }
  ]
}
</pre>

MUST trigger when tokens are transferred, including zero value transfers and self-transfers.

A token contract which creates new tokens MUST trigger a <code>Transfer</code> event with the <code>from</code> address set to <code>null</code> when tokens are created.

A token contract which burns tokens MUST trigger a <code>Transfer</code> event with the <code>to</code> address set to <code>null</code> when tokens are burned.

==Implementation==

C#: https://github.com/neo-project/neo-devpack-dotnet/blob/master/src/Neo.SmartContract.Framework/Nep17Token.cs

Python: https://github.com/CityOfZion/neo3-boa/blob/development/boa3_test/examples/nep17.py