[Design] Token API

[justgigio]

• Feature Name: token_api
• Start Date: 2021-07-24
• RFC PR: (leave this empty)
• Hathor Issue: (leave this empty)
• Author: Giovane Costa gigio.coder@gmail.com

Summary

Token API will provide token information stored on wallet-service database.

Motivation

We need to retrieve token data without requesting the full node. Wallet service holds those data, so, it's perfect to be used for now.

Guide-level explanation

• Single token data will be retrieved by joining tokens, transactions and tx_outputs tables.
• List of transactions of a token will be retrieve by filtering its tx_outputs

Reference-level explanation

Endpoints:

GET /token/:id return 200 | 404

We retrieve a token by its ID joining transactions and tx_outputs table.

can_melt and can_mint will be decided checking respective tx_outputs authorities.

token-handler return the token data

{
    id: str,
    name: str,
    symbol: str,
    timestamp: int,
    total_supply: int,
    can_mint: boolean,
    can_melt: boolean
}

GET /token/:id/transactions?page=:page&size=:size return 200 | 404

We retrieve the list of transactions of a token by querying tx_outputs table by token_id column. Pagination will be done using offset and limit. total can be calculated with a select count(*) ...

token-handler return paginated transactions of given token

{
    total: int,
    transactions: [
        {
            id: str,
            timestamp: int
        }
    ]
}

GET /tokens?page=:page&size=:size&order=:order&name=:name return 200

We retrieve list of tokens b querying the tokens table. Pagination will be done using offset and limit. name will filter by name and can filter symbol too.

token-handler return list of token currently in the network

{
    total: int,
    tokens: [
        {
             id: str,
             name: str,
             symbol: str,
             timestamp: int
        }
    ]
}

Drawbacks

None.

Unresolved questions

None.

Future possibilities

We will probably have a new service for data that will be consumed by external services.

[andreabadesso]

Mint and melt

How are you planning to get this information? Are you going to query the tx_output table to find if a authority still exists? I think this should be clearer on the design

Pagination

How are you planning to paginate the token transactions? We might receive new transactions with older timestamps than now(), this might be an issue when paginating because we could skip transactions when paginating

[pedroferreira1]

I think you should describe in the 3 APIs how are you getting the information on the wallet service. @andreabadesso has written some questions but I feel all of them are still unclear to me. Some APIs will use more than one table? How are you going to query them?

Besides that, the last API /tokens?page=:page&size=:size&order=:order must have a parameter to query by token name/symbol as well.

[justgigio]

@andreabadesso about the tx_output table, i'm saying here:

Single token data will be retrieved by joining tokens, transactions and txoutputs tables.

But i agree that the way that mint and melt will be calculated mus be described as well.

About pagination, i'm intending to do something as simple as select ... order by timestamp desc offset {(page - 1) * page_size} limit {page_size}

I know that some strange little things can happen, like an older wild transaction suddenly appears but i think we can deal with it in the future. Actually, i can't even think in a good way to make it smooth in the UX by now. It's the default behavior for any place that paginate things that comes from a database

[justgigio]

@pedroferreira1 i've added some more explanation

[pedroferreira1]

We retrieve the list of transactions of a token by querying tx_outputs table by token_id column.

The list of transactions is sorted by timestamp. The tx_outputs table has the transaction timestamp? Besides that, you might get lots of duplicated transactions for the same token, because it's only row for each output.

I think for each API you can write the query (in SQL) you are planning on using, it will be great for everyone to understand the design better and you will use them when you start implementing.

GET /tokens?page=:page&size=:size&order=:order&name=:name return 200

What are the possible values for order? Is it possible to order by timestamp? Name? Symbol?

You said you are going to use the tokens table, and sorting by timestamp is important. Do we have the timestamp of each token creation in the tokens table?

Again I think if you write the query you are planning on using would be better for understanding it.