tip-0005.md

TIP: 0005
Title: TIP-5 Single Token Registry Standard
Authors: Stephen Craig Branscom
Status: Draft
Type: Protocol
Created: 2018-08-01
Adopted: 2018-10-30 Voting - Yes: 39, No: 0, Abstain: 0

Abstract

This proposal outlines a plan to standardize Token Registries across the Telos Network, as well as define a common interface for use by third parties.

Motivation

As the Telos Network grows, standardized communication interfaces will become necessary in order to allow complex token transactions. Declaring a network-wide standard will allow any tokens developed on Telos to be reused by other applications and services.

Rationale

In the Telos Network, a token or groups of tokens are collectively tracked and managed by a single contract, which will henceforth be known as a Token Registry. Due to the free nature of the network, anyone can write their own Token Registry, which will likely result in a multitude of different interfaces across the network.

Specification

The TIP-5 Single Token Registry Standard defines an interface that allows third-party support for token contracts that implement a single token. The interface is defined as follows:

Tables

The following tables store information such as token balances, allotments, and global token settings.

• typedef multi_index< N(balances), balance> balances_table

  The balances table will hold all accounts and their respective token balances. The table is indexed by account_name.

• typedef multi_index< N(allotments), allotment> allotments_table

  The allotments table holds all approved account allotments, indexed by the token owner's account_name.

• typedef eosio::singleton<N(singleton), setting> settings_singleton

  The settings singleton holds all token related information such as max supply, circulating supply, and a human-readable name.

Structs

The following structs and their members are stored in tables and referenced by their primary keys.

• setting

  Issuer refers to the account authorized to mint new tokens.

  Max Supply holds the maximum supply of tokens to be allowed in circulation.

  Supply stores the total tokens currently in circulation.

  Name holds the human-readable name of the token.

• balance

  Owner refers to the account that owns the tokens.

  Tokens holds the balance of tokens owned by the owner.

• allotment

  Recipient refers to the account that has the authority to withdraw from the tokens field.

  Sender refers to the account that sent the tokens that have been allotted.

  Tokens holds the allotment to be withdrawn by the recipient.

ABI Actions

The following function signatures define how users can interact with the token contract.

• void mint(account_name recipient, asset tokens)

  Mints new tokens into the circulating supply and sends them to the recipient. Only the account publishing the contract has the authority to mint new tokens.

• void transfer(account_name sender, account_name recipient, asset tokens)

  Transfers tokens from the sender account to the recipient account.

• void allot(account_name sender, account_name recipient, asset tokens)

  Allows recipient to withdraw from the sender account, multiple times, up to the value of tokens. Subsequent allotments called by the same owner to the same recipient are added together.

• void unallot(account_name sender, account_name recipient, asset tokens)

  Reverses an allotment of tokens back into the sender's balance, up to the amount of tokens still remaining in the allotment.

• void claim(account_name sender, account_name recipient, asset tokens)

  Claims tokens from an allotment to the recipient account, up to the amount alloted by the sender.

• void createwallet(account_name recipient)

  Creates a zero balance entry in the balances table for the recipient. Users should call this action first to create a balance entry for holding their future tokens. This will consume a small amount of RAM, which can be reclaimed should the user ever choose to delete their balance entry.

• void deletewallet(account_name recipient)

  Deletes an entry in the balances table for the recipient. Ensure the entry has a balance of zero, otherwise tokens will be deleted.

Discussion

• Q: Why do users need to call the createwallet() action before receiving tokens?

  A: In short, it has to do with ram consumption. In order to store a balance of tokens, a certain amount of ram must be allocated to save that information. By calling createwallet(), a user is reserving this storage space up front for their own use. This ram will be reclaimed later when the user chooses to delete their wallet.

• Q: Does this interface only work for single token contracts?

  A: Yes. A forthcoming Multi Token Registry Standard will declare an interface for interacting with contracts that implement more than one token on a single contract.

• Q: What's the purpose of an allotment?

  A: Allotments can be thought of as a deferred payment. Any user can make an allotment to any other user, even if the recipient doesn't have an existing wallet on that contract (they will, however,need a wallet when they go to claim the allotment). The recipient can then claim their allotment whenever they want, even a few tokens at a time, until either the account that made the allotment unallots the remaining tokens, or the allotment is fully claimed by the recipient. Only the intended recipient can withdraw from an allotment, and unclaimed tokens can be reclaimed by the allotter at any time.

• Q: Why can't a user delete their wallet until it has zero tokens?

  A: Deleting a wallet that still retains a token balance would effectively burn those tokens from circulation.

Summary for Shareholders

The changes suggested in this TIP will declare a standard for developing token contracts. This will pave the way for contract integration with exchanges and other third-party developers.

Copyright

Open Source under MIT License.