View Source DigitalToken (Digital Token v1.0.0)

Functions to validate, search and retrieve digital token data sourced from the DTIF registry.

Summary

Types

A digital token may have zero or more short names associated with it. They are arbitrary strings, usually three or four characters in length. For example "BTC", "ETH" and "DOGE".

short_name_map()

A mapping from a short name to token identifier.

symbol_map()

A mapping of digital token identifiers to a currency symbol for that token.

t()

The structure of data matching that hosted in the DTIF registry/

token_id()

token_id is a random 9-character string defined by the dtif registry that uniquely identifies a digital token.

token_map()

A mapping of digital token identifiers to the registry data for that token.

token_type()

The type of a token

Functions

get_token(id)

Returns the registry data for a given token identifier.

get_token!(id)

Returns the registry data for a given token identifier.

is_digital_token(token_id)

long_name(token_id)

Returns the long name of a digital token.

short_name(token_id)

Returns the short name of a digital token.

short_names()

Returns a mapping of digital token short names to digital token identifiers.

symbol(token_id, style)

Returns a currency symbol used in number formatting.

symbols()

Returns a mapping of digital token identifiers names to a currency symbol.

tokens()

Returns a map of the digital tokens in the dtif registry.

validate_token(id)

Validates a token identifier or short name and returns the token identifier or an error.

Types

short_name()

@type short_name() :: String.t()

A digital token may have zero or more short names associated with it. They are arbitrary strings, usually three or four characters in length. For example "BTC", "ETH" and "DOGE".

short_name_map()

@type short_name_map() :: %{required({token_id(), token_type()}) => token_id()}

A mapping from a short name to token identifier.

symbol_map()

@type symbol_map() :: %{required(token_id()) => String.t()}

A mapping of digital token identifiers to a currency symbol for that token.

t()

@type t() :: %DigitalToken{
  header: map(),
  informative: map(),
  metadata: map(),
  normative: map()
}

The structure of data matching that hosted in the DTIF registry/

token_id()

@type token_id() :: String.t()

token_id is a random 9-character string defined by the dtif registry that uniquely identifies a digital token.

token_map()

@type token_map() :: %{required(token_id()) => t()}

A mapping of digital token identifiers to the registry data for that token.

token_type()

@type token_type() :: :native | :auxiliary | :distributed | :fungible

The type of a token

Functions

get_token(id)

@spec get_token(token_id() | short_name()) :: {:ok, t()} | {:error, {module(), any()}}

Returns the registry data for a given token identifier.

Arguments

id is any token identifier or short name

Returns

{:ok, registry_data} or
{:error, {exception, id}}

Example

DigitalToken.get_token("BTC")
#=> {:ok,
 %DigitalToken{
   header: %{
     dlt_type: :blockchain,
     dti: "4H95J0R2X",
     dti_type: :native,
     template_version: #Version<1.0.0>
   },
   informative: %{
     long_name: "Bitcoin",
     public_distributed_ledger_indication: false,
     short_names: ["BTC", "XBT"],
     unit_multiplier: 100000000,
     url: "https://github.com/bitcoin/bitcoin"
   },
   metadata: %{
     .....

get_token!(id)

@spec get_token!(token_id() | short_name()) :: t() | no_return()

Returns the registry data for a given token identifier.

Arguments

id is any token identifier or short name

Returns

registry_data or
raises an exception

Example

DigitalToken.get_token("BTC")
#=> %DigitalToken{
   header: %{
     dlt_type: :blockchain,
     dti: "4H95J0R2X",
     dti_type: :native,
     template_version: #Version<1.0.0>
   },
   informative: %{
     long_name: "Bitcoin",
     public_distributed_ledger_indication: false,
     short_names: ["BTC", "XBT"],
     unit_multiplier: 100000000,
     url: "https://github.com/bitcoin/bitcoin"
   },
   metadata: %{
     .....

is_digital_token(token_id)

(macro)

long_name(token_id)

@spec long_name(token_id()) :: {:ok, String.t()} | {:error, {module(), String.t()}}

Returns the long name of a digital token.

Arguments

token_id is any valid digital token identifier.

Returns

{:ok, long_name} where long_name is the token's registered name.
{:error, {exception, reason}}

Examples

iex> DigitalToken.long_name "BTC"
{:ok, "Bitcoin"}

iex> DigitalToken.long_name "4H95J0R2X"
{:ok, "Bitcoin"}

iex> DigitalToken.long_name "W0HBX7RC4"
{:ok, "Terra Classic"}

short_name(token_id)

@spec short_name(token_id()) :: {:ok, String.t()} | {:error, {module(), String.t()}}

Returns the short name of a digital token.

Arguments

token_id is any valid digital token identifier.

Returns

{:ok, short_name} where short_name is either the first short name in token.informative.short_names or the token long name if there are no short names.
{:error, {exception, reason}}

Examples

iex> DigitalToken.short_name "BTC"
{:ok, "BTC"}

iex> DigitalToken.short_name "4H95J0R2X"
{:ok, "BTC"}

iex> DigitalToken.short_name "W0HBX7RC4"
{:ok, "Terra Classic"}

short_names()

@spec short_names() :: short_name_map()

Returns a mapping of digital token short names to digital token identifiers.

symbol(token_id, style)

@spec symbol(token_id(), 1..4) :: {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a currency symbol used in number formatting.

Arguments

token_id is any valid digital token identifier.
style is a number in the range 1 to 4 as follows:
- 1 is the token's symbol, if it exists
- 2 is the token's short name as a proxy for a currency code
- 3 is the token's long name
- 4 is the token's symbol as a proxy for a narrow currency symbol

Returns

{:ok, symbol} or
{:error, {exception, reason}}

Examples

iex> DigitalToken.symbol "BTC", 1
{:ok, "₿"}

iex> DigitalToken.symbol "BTC", 2
{:ok, "BTC"}

iex> DigitalToken.symbol "BTC", 3
{:ok, "Bitcoin"}

iex> DigitalToken.symbol "BTC", 4
{:ok, "₿"}

iex> DigitalToken.symbol "ETH", 4
{:ok, "Ξ"}

iex> DigitalToken.symbol "DOGE", 4
{:ok, "Ð"}

iex> DigitalToken.symbol "DODGY", 4
{:error, {DigitalToken.UnknownTokenError, "DODGY"}}

symbols()

@spec symbols() :: symbol_map()

Returns a mapping of digital token identifiers names to a currency symbol.

tokens()

@spec tokens() :: token_map()

Returns a map of the digital tokens in the dtif registry.

validate_token(id)

@spec validate_token(token_id() | short_name()) ::
  {:ok, token_id()} | {:error, {module(), any()}}

Validates a token identifier or short name and returns the token identifier or an error.

Arguments

id is any token identifier or short name

Returns

{:ok, token_id} or
{:error, {exception, id}}

Example

iex> DigitalToken.validate_token("BTC")
{:ok, "4H95J0R2X"}

iex> DigitalToken.validate_token("Bitcoin")
{:ok, "4H95J0R2X"}

iex> DigitalToken.validate_token "4H95J0R2X"
{:ok, "4H95J0R2X"}

iex> DigitalToken.validate_token("Nothing")
{:error, {DigitalToken.UnknownTokenError, "Nothing"}}