Querying the Dataset

Overview

The Token Name Service uses ENS, and can be queried anywhere .eth domains are supported

The Token name set is persisted as subdomains of the .tkn.eth domain

For instance, the contract for USDC can be found at usdc.tkn.eth and Wrapped Bitcoin at wbtc.tkn.eth

Descriptive metadata can be found on chain in each token's ENS resolver. Including name, description, avatar, url, dweb, decimals, notice, version, twitter, & github.

The TNS.sol contract exposes additional queries; such as: fetch all metadata, fetch token contracts on all chains, and token balance for address. TNS.sol is hosted at tkn.eth

Get token contract address

Retrieves the address where the token contract resides.

Useful for converting a user supplied token symbol into an actionable contract.

await provider.resolveName("uni.tkn.eth");
// '0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984'

import { useEnsAddress } from 'wagmi'

function App() {
  const { data, isError, isLoading } = useEnsAddress({
    name: 'wbtc.tkn.eth',
  })

  if (isLoading) return <div>Fetching address…</div>
  if (isError) return <div>Error fetching address</div>
  return <div>Address: {data}</div>
}
// Returns data: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599'

pragma solidity ^0.8.4;

contract HelloTKN {
    ITKN tkn;
    constructor() {
        tkn = ITKN(0xc11BA824ab2cEA5E701831AB87ed43eb013902Dd); 
    }
    
    // Get an account's balance from a ticker symbol
    function balanceForAddress(address user, string calldata tickerSymbol) public view returns (uint) {
	// Fetch the token contract address with ticker:
	address contractAddress = tkn.addressFor(tickerSymbol);
        IERC20 tokenContract = IERC20(contractAddress);
        return tokenContract.balanceOf(user);
    }
}
// Required Interfaces
interface ITKN {
    struct TokenInfo {
        address contractAddress;
        string name;
        string url;
        string avatar;
        string description;
        string notice;
        string version;
        string decimals;
        string twitter;
        string github;
        bytes dweb;
    }
    function addressFor(string calldata _name) external view returns (address);
    function infoFor(string calldata _name) external view returns (TokenInfo memory);
    function gasEfficientFetch(bytes32 namehash) external view returns (address);
    function balanceWithTicker(address user, string calldata tickerSymbol) external view returns (uint);
}

interface IERC20 {
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
} 

Get token by contract address

Reverse resolution by token contract address is now available

Query <tokenAddress>.<chain>.tkn.eth to fetch the metadata for that token

Example: 0x78b3C724A2F663D11373C4a1978689271895256f.base.tkn.eth ($TKN on Base) will resolve the data for the $TKN token

Get single datapoint

Get one of the datapoints available for each token.

Pulls a single datapoint, such as a name or description.

To see the available data types visit: https://docs.tkn.xyz/developers/dataset

Get all token info

Retrieve all datapoints for a token, excluding the sidechain contract addresses.

Useful for fetching all token data in a single query.

Get all token info and sidechain contract addresses

Retrieve all token info and it's sidechain contract addresses.

Useful for fetching all known data about a token in a single query.

Decoding non-EVM and dweb responses: Non-EVM contract addresses can be decoded with https://www.npmjs.com/package/@ensdomains/address-encoder addressEncoder.formatsByName['SOL'].encoder(Buffer.from(tokenData.sol_address.substring(2), 'hex')) And the dweb IPFS CID can be decoded with https://github.com/pldespaigne/content-hash#contenthashdecode-contenthash----string

Get all sidechain contract addresses

Retrieve all token sidechain contract addresses.

Useful for a token's contract addresses for all chains in a single query.

Decoding non-EVM contract addresses: Non-EVM contract addresses can be decoded with https://www.npmjs.com/package/@ensdomains/address-encoder addressEncoder.formatsByName['SOL'].encoder(Buffer.from(tokenData.sol_address.substring(2), 'hex'))

Get tokens owned by an address

Lookup how many tokens an address owns, using a token symbol.

Helpful for looking up an ERC20 account balance without having to fetch the token contract address separately.

Get all TKN tokens

There are multiple ways to fetch the complete list of tokens

1. Registry.tkn.eth: a simple JSON array with the symbols for all listed tokens. The current source of truth for TKN listings. Can be fetched with an IPFS dweb resolver, or eth.limo. https://registry.tkn.eth.limo/

2. TheGraph: TKN now has it's very own subgraph. Can conveniently produce all tokens and metadata in a single query.

Use this TKN Subgraph query to fetch all tokens and metadata at once:

And this query can be used to fetch a single token:

1. TokenList: Tokenlists.org formatted list. Published at list.tkn.eth. View at: https://tokenlists.org/token-list?url=list.tkn.eth