LogoLogo
  • Welcome
  • Where to Start
    • Introduction
    • list of Operations
    • Bantu Stack
  • Tutorials
    • Create Account
    • Send and Receive Payments
    • Follow Received Payments
    • Securing Web-based Projects
  • Issue Assets
    • Overview
    • Anatomy of an Asset
    • Issue an Asset
    • Publish Information About an Asset
    • Control Access to an Asset
  • Building Apps
    • Overview
    • Project Setup
    • Key Management Basics
    • Create a Basic Wallet
    • Make XBN Payments
    • Handle Custom Assets
  • Run a Core Node
    • index
    • running-node
    • network-upgrades
    • tier-1-orgs
    • installation
    • prerequisites
    • configuring
    • publishing history archives
    • commands
    • monitoring
  • Run API Server
    • prerequisites
    • quickstart
    • index
    • installing
    • monitoring
    • Running
    • configuring
  • Software and SDKs
    • index
  • Glossary
    • scp
    • Claimable Balance
    • XDR
    • Assets
    • BUDS
    • Inflation
    • Miscellaneous Core Objects
    • Testnet
    • Accounts
    • Network Passphrase
    • Ledger
    • Versioning
    • Sponsored Reserves
    • Operations
    • Decentralized Exchange
    • Fees
    • XBN Supply
    • Fee Bumps
    • Channels
    • Transactions
    • Minimum Balance
    • Multisig
  • Docs
    • Index
  • API
    • Introduction
      • Index
      • Response Format
      • Streaming
      • Rate Limiting
      • XDR
      • Pagination
        • Index
        • Page Arguments
    • Resources
      • Untitled
      • Overview
      • Ledgers
        • index
        • Object
        • Single
        • Transactions
        • Operations
        • Payments
        • Effects
        • List
      • Transactions
        • Index
        • Object
        • Single
        • Operations
        • Effects
        • List
      • Operations
        • Index
        • Object
          • Index
          • Create Account
          • Payment
          • Path Payment Strict Send
          • Path Payment Strict Receive
          • Sell Offer
          • Buy Offer
          • Passive Sell Offer
          • Set Options
          • Change Trust
          • Allow Trust
          • Account Merge
          • Manage Data
          • Bump Sequence
          • Create Claimable Balance
          • Claim Claimable Balance
          • Begin Sponsoring Future Reserves
          • End Sponsoring Future Reserves
          • Revoke Sponsorship
        • Single
        • Effects
        • List
        • List Payments
      • Effects
        • Index
        • Types
        • List
      • Accounts
        • Index
        • Object
        • Transactions
        • List
        • Single
        • Operations
        • Payments
        • Effects
        • Offers
        • Trades
        • Data
      • Offers
        • Index
        • Object
        • Single
        • List
      • Trades
        • Index
        • Object
        • List
      • Assets
        • Index
        • Object
        • List
      • Claimable Balances
        • Index
        • Object
        • Single
        • List
    • Aggregations
      • Index
      • Order Books
        • Index
        • object
        • Single
      • Paths
        • Index
        • Object
        • Strict Receive
        • Strict Send
      • Trade Aggregations
        • Index
        • Object
        • List
      • Fee Stats
        • Index
        • Object
        • Single
    • Errors
      • Index
      • Response
      • HTTP Status Codes
        • Index
        • Standard
        • Expansion Specific
          • Index
          • Transaction Failed
          • Transaction Malformed
          • Before History
          • Stale History
          • Timeout
      • Result Codes
        • Index
        • Transactions
        • Operations
        • Operation Specific
          • Index
          • Create Account
          • Payment
          • Path Payment Strict Receive
          • Path Payment Strict Send
          • Manage Sell Offer
          • Manage Buy Offer
          • Create Passive Sell Offer
          • Set Options
          • Change Trust
          • Allow Trust
          • Account Merge
          • Manage Data
          • Bump Sequence
Powered by GitBook
On this page
  • Asset Code
  • Issuer
  • Trustlines
  • Representation
  • Amount Precision
  • Relevance in Expansion and Bantu Client Libraries
  • XBN

Was this helpful?

  1. Issue Assets

Anatomy of an Asset

PreviousOverviewNextIssue an Asset

Last updated 4 years ago

Was this helpful?

Each Bantu asset has two characteristics: the asset code and the issuer. When you look up or interact with an asset on Bantu, you always use both to identify it.

Many Bantu tokens represent credits that can be redeemed for something outside the network—often fiat currency, but also bonds, carbon credits, gold, etc.—and since more than one organization can issue a credit representing the same underlying asset, asset codes often overlap. More than one company offers a USD token on Bantu, for instance.

However, the combination of asset code and issuer allows each asset to be uniquely identified: each USD token is offered by, and redeemable with, one specific issuer.

Asset Code

When you issue an asset, the first thing you do is choose an identifying code. Currently, there are two supported formats.

  • 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.

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

Issuer

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

The public key of the issuing account is linked on the ledger to the asset itself. Responsibility for and control over an asset resides with the issuing account, and 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.

Trustlines

Before an account can hold an asset another account issues, it has to establish something called a trustline, which is a persistent account-level ledger entry created with a change_trust operation.

A trustline is an explicit opt-in to hold a particular token, so it specifies both asset code and issuer. Each trustline increases an account’s minimum lumen balance by one — currently 0.5 XLM — and tracks the balance of the asset the account holds. Trustlines can also limit the amount of an asset an account can hold, though more often than not, account holders don’t set that limit: they simply turn the trustline on, which by default allows the maximum.

A trustline also tracks liabilities. Buying liabilities equal the total amount of the asset offered to buy aggregated over all offers owned by an account, and selling liabilities equal the total amount of the asset offered to sell aggregated over all offers owned by an account. A trustline must always have balance sufficiently large to satisfy its selling liabilities, and a balance sufficiently below its limit to accommodate its buying liabilities.

Representation

In Expansion, 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` (XBN), `credit_alphanum4`, or `credit_alphanum12`.
  "asset_type": "credit_alphanum12"
}

In the Bantu SDKs, they’re represented with the Asset class:

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

Amount Precision

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 is 0.0000001 (one ten-millionth) represented as an integer value of one. The largest amount unit possible is ((2^63)-1)/(10^7) (derived from max int64 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 Expansion and Bantu Client Libraries

In Expansion 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 with 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.

XBN

Each asset amount is encoded as a signed 64-bit integer in the that Bantu 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.

XBN are the native currency of the Bantu network, and are the only asset that doesn't require an issuer or a trustline. Every account is required to hold a , and all are paid in XBN. The smallest unit of a XBN is a spirit, which is one ten-millionth of a XBN.

ISO 4217 code
ISIN number
base reserve
XDR structures
minimum XBN balance
transaction fees