Skip to main content

Assets

Accounts on the Stellar network can be used to track, hold, and transfer any type of asset. Assets can represent many things: cryptocurrencies (such as bitcoin or ether), fiat currencies (such as dollars or pesos), other tokens of value (such as NFTs), pool shares, or even bonds and equity.

Assets on Stellar have two identifying characteristics: the asset code and the issuer. Since more than one organization can issue a credit representing the same asset, asset codes often overlap (for example, multiple companies offer a USD token on Stellar). Assets are uniquely identified by the combination of their asset code and issuer.

Asset components

Asset code

An asset’s identifying code. There are three different formats: Alphanumeric 4, Alphanumeric 12, and liquidity pool shares. Learn about liquidity pool shares in the Liquidity Pool Encyclopedia Entry.

  • Alphanumeric 4-character maximum: Any characters from the set [a-z][a-z][0-9] are allowed. The code can be shorter than 4 characters, but the trailing characters must all be empty.
  • Alphanumeric 12-character maximum: Any characters from the set [a-z][a-z][0-9] are allowed. The code can be any number of characters from 5 to 12, but the trailing characters must all be empty.

The pool share asset is defined by the liquidity pool identifier (PoolID), which in turn is defined by the two assets its reserves are composed of.

Provided it falls into one of these buckets, you can choose any asset code you like. That said, if you’re issuing a currency, you should use the appropriate ISO 4217 code, and if you’re issuing a stock or bond, the appropriate ISIN number. Doing so makes it easier for Stellar interfaces to properly display and sort your token in their listings and allows potential token holders to understand what your token represents.

Issuer

There is no dedicated operation to create an asset on Stellar. Instead, assets are created with a payment operation: an issuing account makes a payment using the asset it’s issuing, and that payment creates the asset on the network.

The public key of the issuing account is linked on the ledger to the asset. Responsibility for and control over an asset resides with the issuing account. Since settings are stored at the account level on the ledger, the issuing account is where you use set_options operations to link to meta-information about an asset and set authorization flags.

Representation

In Horizon, assets are represented in a JSON object:

{  asset_code: "AstroDollar",  asset_issuer: "GC2BKLYOOYPDEFJKLKY6FNNRQMGFLVHJKQRGNSSRRGSMPGF32LHCQVGF",  // `asset_type` is used to determine how asset data is stored.  // It can be `native` (lumens), `credit_alphanum4`, or `credit_alphanum12`.  asset_type: "credit_alphanum12",}

In the Stellar SDKs, they’re represented with the asset class:

var astroDollar = new StellarSdk.Asset(  "AstroDollar",  "GC2BKLYOOYPDEFJKLKY6FNNRQMGFLVHJKQRGNSSRRGSMPGF32LHCQVGF",);

Amount precision

Each asset amount is encoded as a signed 64-bit integer in the XDR structures that Stellar uses to encode transactions. The asset amount unit seen by end-users is scaled down by a factor of ten million (10,000,000) to arrive at the native 64-bit integer representation.

For example, the integer amount value 25,123,456 equals 2.5123456 units of the asset. This scaling allows for seven decimal places of precision in human-friendly amount units.

The smallest non-zero amount unit, also known as a stroop, is 0.0000001 (one ten-millionth) represented as an integer value of one. The largest amount unit possible is 2631107\frac{2^{63}-1}{10^7} (derived from the maximum 64-bit integer, scaled down) which is 922,337,203,685.4775807.

The numbers are represented as int64s. Amount values are stored as only signed integers to avoid bugs that arise from mixing signed and unsigned integers.

Relevance in Horizon and Stellar Client Libraries

In Horizon and client-side libraries such as js-stellar-sdk, the integer encoded value is abstracted away. Many APIs expect an amount in unit value (the scaled-up amount displayed to end-users). Some programming languages (such as JavaScript) have problems maintaining precision on a number amount. It is recommended to use “big number” libraries that can record arbitrary-precision decimal numbers without a loss of precision.

Deleting or burning assets

To delete, or "burn", an asset, you must send it back to the account that issued it.