How to Issue and Anchor Assets on Stellar?

One of the core features of Stellar is to issue assets. You can tokenize any asset and then transfer or trade it over the Stellar network. It can be done quickly, economically, and by anyone (from banks, money service businesses, payment processors, local communities, enterprises, and individuals). You can also tune these assets to specific use cases with the help of Stellar’s built-in mechanisms, list them on the Stellar decentralized exchange and use market-making bots to benefit from Stellar’s global reach and ensure the required liquidity. Presently, the tokenization of fiat currency for optimizing processes like cross-border payments is the biggest use case for Stellar.

In this article, we will discuss how you can issue and anchor assets on Stellar. However, before we begin with the processes, it is important to discuss what an asset comprises. So, let’s begin by discussing the anatomy of an asset.

Anatomy of an Asset

The two characteristics of every Stellar asset are:

• The Asset Code
  There are two supported formats for the asset code, i.e., the alphanumeric 4-character maximum and alphanumeric 12-character maximum. It is an identifying code that allows potential token holders to understand what your token represents.
• The Issuer
  Assets on stellar are created with a payment operation. So, the issuer is the account that makes the payment using the asset it is issuing. The payment done by the issuing account creates the asset on the network. The issuing account has the responsibility for the asset and its control.

These characteristics are used to identify an asset on Stellar for interaction. Sometimes, asset codes overlap as more than one organization can issue a credit representing the same underlying asset. So, the combination of the issuer and the asset code allows each asset to be identified uniquely. The credits represented by these stellar tokens can redeem something outside the network, such as bonds, fiat currency, gold, carbon credits, etc. In case of issuing a currency, it should be used with the appropriate ISO 4217 code and in case of issuing a bond or stock, it should be used with the apt ISIN number.

Trustlines

Trustlines are persistent account-level ledger entries created with a change_trust operation. Every account has to establish a trustline before it can hold an asset issued by another account. It specifies both the issuer and the asset code. Some functions of trustlines are:

• Increase an account’s minimum lumen balance by one base reserve (currently 0.5XLM) and track the asset’s balance.
• Limit the asset’s amount held by an account.
• Track liabilities.

Trustlines should always have enough balance to satisfy its selling liabilities and sufficiently below its limit to accommodate its buying liabilities.

Amount Precision

Asset amounts are encoded as signed 64-bit integers in the XDR structures. Stellar uses these structures to encode transactions. To arrive at the native 64-integer representation, the asset amount unit (as seen by end-users) is scaled down by a factor of ten million.

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

The integer encoded value is abstracted away in the client-side and Horizon libraries like js-stellar-sdk. Some programming languages like JavaScript face problems while maintaining precision on a number amount. Several APIs expect the amount in unit value, i.e., the scaled-up amount displayed to the end-users. Hence, we recommend you use a “big number” library that can record arbitrary-precision decimal numbers without losing any precision.

Lumens (XLM)

The native currency of the Stellar network, Lumens (XLM), is the only asset that does not require a trustline or an issuer. All transaction fees are paid in lumens; hence it is required that every account holds a minimum lumen balance. Its smallest unit is a “Stroop,” i.e., one ten-millionth of a lumen.

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",
);

Issue an Asset

Instead of following a dedicated operation, assets on Stellar are created with a payment operation. The issuing account makes the payment via the asset it is issuing and the payment creates an asset on the network. It is a simple process with a requirement of the following four operations:

1. Operation to create an issuing account
2. Operation to create a distribution account
3. Operation to establish a trustline
4. Operation to make a payment

Although you don’t have to issue assets to a dedicated distribution account, it is recommended to issue them to any account with the required trustline.  However, you must know that if you want to create a token on the public network, you need a funded account to provide the necessary XLM for creating, issuing and distributing accounts.

Step 1: Create the Issuing and Distribution Accounts

Issuing Account
The asset’s origin, one that is linked to the asset’s identity forever.

Distribution Account
The asset’s first recipient.

For creating an account, you have to follow the following two steps:

Generate a keypair 

Fund the account using a create_account operation.

It is vital to understand that even though the keypair can be generated for free, an account will not exist on the Stellar ledger if it isn’t funded with the XLM to cover the minimum balance. Also, you must keep the following in mind:

You can fund your account by getting free XLM from Friendbot if you’re issuing an asset on testnet.

You’ll need to use an existing account in case you’re issuing an asset in production so that it can send you enough live XLM to cover the transaction fees, a trustline and the minimum balance.

If you move too close to the minimum network balance, you may not have enough XLM to fulfill your requirements.

Why Having Separate Accounts for Issuing and Distribution is Important?

The main reasons behind using a distribution account are security and auditing.

Many people agree that functionally, a distribution account isn’t necessary and one can even create a market from the issuing account directly and issue via trading. However, it is also a known fact that the account one uses to distribute their asset becomes a ‘hot’ account and some web services may have direct access to sign its transactions.

So, if the distribution and the issuing accounts are the same, the asset can be compromised in case of malicious activity as the actor can issue as much of the asset as they want.  As a result, potential off-chain liabilities can be increased. If the malicious actor uses the anchor service to redeem these newly issued tokens, the anchor may not have enough liquidity to support the transactions.

On the other hand, if one has separate issuing and distribution accounts, the risk is lower. In case of malicious activities, the issuer can effectively freeze the account’s asset balance and a new distribution account can be started without changing the issuing account.

Regarding auditability or bookkeeping, a standing inventory of one’s asset in a separate account is easier to track, as an issuing account cannot hold the balance of its asset.

Also, with the help of distribution accounts, the ecosystem’s standards are decoupled from issuance. Participants get the freedom to come up with innovative and interesting concepts without changing the protocols.

Step 2: Create a Trustline

In this step, the distribution account submits a change_trust operation to create a trustline, which Stellar needs the account to explicitly opt-in to hold an asset. The trustline goes from the distribution account to the issuing account.

In the change_trust operation, the distribution account specifies the issuer’s public key and asset code. It is the first time asset code appears on the ledger, so it implies that the asset is named by the distribution account instead of the issuing account.

Step 3: Make a Payment

In this step, the issuing account makes a payment via the newly named asset to the distribution account. As long as it remains unlocked, the issuing account can create new tokens by making payments to the distribution account or any other account with the required trustline.

Your next step should be to complete a stellar.toml file so that you can provide the required information about your asset to exchanges, wallets, potential token holders and market listing services. It will help them to understand what your asset represents.

Publish Information About an Asset

It is vital to provide clear information about your asset and what it represents after issuing it. This can be done by linking a home domain to your issuing account and publishing a complete and accurate stellar.toml file on it. Asset issuers should give exchanges, potential buyers and wallets a lot of information in the stellar.toml file. There are several benefits of doing so, such as:

• You will gain the trust of potential buyers.
• Your asset will get more exposure.
• Your asset will be listed on several exchanges.
• Your project’s chances of success will increase, etc.

The stellar.toml files are used by several entities to include assets and populate their listings, such as:

• The Stellar ticker (it is a market data source for sites like CoinMarketCap)
• Trading interfaces like Stellarport, StellarX, StellarTerm
• Wallets like Lobstr, Solar

Ecosystem integrations enabling interoperability also rely on information in the stellar.toml file that details your Stellar setup. It is written in TOML (a configuration format readable by both humans and machines). You can link the domain by hosting it to your Stellar account and using a set_options operation. SEP-1 specifies everything that you can include in a stellar.toml file. The four major categories of required information are:

General Information
A field required for all token issuers; this category requires information like:

• Accounts
  The list of public keys for Stellar accounts that are associated with your asset.

You can find several fields where you can list information about your Stellar integration to help in discoverability.

Ensure to include the location of your resources if you support other SEPs or host a public Horizon instance.

Organization Documentation
This category includes basic information about your organization to inform your buyers and exchanges about your business to build trust, such as:

• Your organization’s official website link.
• Your organization’s legal name.
• The official URL to your company’s logo.
• Your organization’s physical address.
• Your organization’s email address.

Although not a necessity, you can also include information like:

• Your organization’s official twitter handle.
• Your organization’s official GitHub account.
• A description of your company.
• The official Keybase account of your organization.

Point of Contact Documentation
This category includes information about your organization’s primary contact points, such as:

• The name and official email address of the primary contact.
• The primary contact’s personal GitHub account.
• The primary contact’s personal twitter and Keybase account.

Currency Documentation
This category includes information about the assets issued by you, such as:

• The asset code.
• The issuing account’s Stellar public key.
• Information about the token in terms of anchor – is it anchored or native?
• The type of asset represented by your token.
• The anchor’s name.
• Instructions for token redemption for the underlying asset.
• Your token’s description and what it represents.
• Conditions placed by you for the token redemption process, if any.
• The URL of your token’s image in PNG or GIF, if any.

Step 4: Publish your stellar.toml

To publish your stellar.toml file, you should:

• Post the complete file here on https://YOUR_DOMAIN/.well-known/stellar.toml where YOUR_DOMAIN is the domain that user will use. It could be localhost or anything. To see what stellar.toml does please follow the link – https://stellar.org/.well-known/stellar.toml
• Enable CORS (which can be added as an extension on the browser) to access this file from other sites, and set Access-Control-Allow-Origin: * as the header for an HTTP response for a /.well-known/stellar.toml file request.
• Set a text/plain content type so that instead of prompting for a download, browsers render the contents. To set the home domain on your issuing account, you should use the set_options operation.

Step 5: Control Access to an Asset

By default, anyone can hold your asset after you issue it on Stellar. It facilitates easy access, which brings in better liquidity. Issuers that have KYC requirements can handle those when an asset moves off of or onto the network. However, this does not imply that you cannot control access to your asset.

One can easily control access to an asset by enabling flags on their issuing account.

Set Up Flags

By using the set_options operation, flags are created on an account level and can be set at any time in an asset’s lifecycle. It can be done with the help of the following four operations:

Authorization Required
With this flag enabled, the issuers get to approve an account before holding their assets. The user creates a trustline and is approved when the issuer changes the AUTHORIZE flag with the allow_trust operation.. An issuer can grant two levels of authorization by granting this operation:

AUTHORIZED
It signifies the complete authorization and allows an account to make transactions with the asset freely to make payments, receive them and place orders.

AUTHORIZED_TO_MAINTAIN_LIABILITIES is a flag that denotes limited authorization by allowing an account to maintain current orders without transacting with the asset otherwise.

Authorization Revocable
With this flag enabled, an existing trustline’s authorization can be revoked by the issuer, which will lead to the asset held by an account being frozen. It also allows the issuer to reduce the authorization capabilities of an account from complete to limited so that the account can continue managing its open orders but cannot transact with the asset otherwise. However, in case the authorization is revoked, the open orders get canceled as well. The allow_trust operation is used to perform all changes to the asset authorization.

Authorization Immutable
This flag is set to inform potential token holders that the issuing account and its assets will be on the ledger in an accessible and open state. Hence, no other flags can be set and the issuing account cannot be merged if this setting is set up.

Clawback Enabled
By setting up this flag, all subsequent trustlines established with the account will have clawbacks enabled. These clawbacks can be controlled selectively on a per-trustline basis. However, it is noteworthy that this flag requires the authorization revocable flag to be set up.

Example Flow

This section will see how an issuer of a regulated asset can use the AUTHORIZED_TO_MAINTAIN_LIABILITIES flag.  The account can be left in the AUTHORIZED_TO_MAINTAIN_LIABILITIES state if the issuer wishes to approve transactions on a case-by-case basis while allowing them to maintain offers.

The holding account requests the issuer to approve and sign a transaction to initiate a new operation. Once the operation is inspected and approved by the issuer, it is sandwiched between a set of operations by first granting the authorization and then reducing it.

Let’s take the example of payment from Alice to Andrew. Here’s how the payment will be sandwiched between set_trust_line_flags operations:

• Operation 1: The issuer will use the SetTrustLineFlags operation to authorize Alice’s account, asset X, fully.
• Operation 2: The issuer will use the SetTrustLineFlags operation to authorize Andrew’s account, asset X fully.
• Operation 3: Payment from Alice to Andrew.
• Operation 4: The issuer will use the SetTrustLineFlags operation to set Andrew’s account, asset X to the AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG state.
• Operation 5: The issuer will use the SetTrustLineFlags operation to set Alice’s account, asset X, to AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG state.

This authorization sandwich allows the specific payment to be inspected by the issuer and enables him to grant authorization for this specific payment only. As the operations are simultaneously bundled in a transaction, Alice and Andrew receive the authorization for this specific pre-approved payment operation.

Sample Code

This section offers a sample code that sets authorization to be both revocable and required. Although proper error checking has been omitted here for brevity, you should always validate your results to avoid the several ways the requests can fail.

var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Server("https://horizon-testnet.stellar.org");
// Keys for issuing account
var issuingKeys = StellarSdk.Keypair.fromSecret(
  "SCZANGBA5YHTNYVVV4C3U252E2B6P6F5T3U6MM63WBSBZATAQI3EBTQ4",
);
server
  .loadAccount(issuingKeys.publicKey())
  .then(function (issuer) {
    var transaction = new StellarSdk.TransactionBuilder(issuer, {
      fee: 100,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      .addOperation(
        StellarSdk.Operation.setOptions({
          setFlags: StellarSdk.AuthRevocableFlag | StellarSdk.AuthRequiredFlag,
        }),
      )
      // setTimeout is required for a transaction
      .setTimeout(100)
      .build();
    transaction.sign(issuingKeys);
    return server.submitTransaction(transaction);
  })
  .then(console.log)
  .catch(function (error) {
    console.error("Error!", error);
  });

Anchor Assets

The Stellar anchors are the on/off ramps of the Stellar network. They accept the deposits of fiat currencies through existing banking rails and send the equivalent digital tokens to the user. These tokens represent those deposits on the Stellar network. Stellar anchors also allow token holders to redeem them for the assets represented by those tokens.

Stellar anchors have the capability of issuing their own assets, and they can also honor the assets that exist on the network already. Anchors can provide services for:

• Cross-border payments via Stellar
• Deposits and Withdrawals on and off Stellar

Interoperability and Stellar Ecosystem Proposals

Being a completely open network, the organizations that provide services on Stellar must be built to allow quick integration of new products with these existing services. The Stellar Development Foundation makes sure that by defining the standards to be implemented by the network participants, this purpose is fulfilled.

These standards are specified in the Stellar Ecosystem Proposals (SEPs) in a GitHub repository and cover several use cases.
These use cases range from regulated assets (SEP-8) to federated user identification (SEP – 2). They define how different institutions like wallets, exchanges, asset issuers must interact and interoperate.

Implementing SEP-24 and/or SEP-31

To implement the backend services described in these protocols, the following three-phase process can be used:

• Build the service from scratch on Stellar’s Testnet network
• Deploy the same service on Stellar’s Mainnet network and connect the anchor’s existing off-chain rails
• Integrate with the existing wallets or anchors on Stellar and launch the product

Step 1: Enable Cross Border Payments via Stellar

Cooperation between a sending anchor (SA) and receiving anchor (RA) is required to support cross-border payments of an asset via the Stellar network. To learn more about cross-border payments on Stellar, please click here.

Step 2: Enable Deposits and Withdrawals on and off Stellar

To support deposits and withdrawals of an asset on and off the Stellar network, cooperation between wallet (client) and anchor (server) applications is required. To learn more about deposits and withdrawals on and off Stellar, please click here.

Wrapping Up

Stellar is a highly functional blockchain platform that offers multiple profitable opportunities to its users. The ability to anchor assets and set them up for cross-border payments and deposits and withdrawals on and off the Stellar network are examples of such advantageous opportunities. However, expert supervision and assistance are required for seamless proceedings of its simple yet highly technical processes.

Hence, if the requirements exceed your expertise, you must seek help by partnering with a capable Stellar development firm.

LeewayHertz is a software engineering leader in the blockchain space. Our suite of Stellar Blockchain Solutions and Services, StellarPlus, aims to assist our clients in leveraging the Stellar blockchain platform’s potential and transform their business ecosystem. If you are looking for a capable Stellar blockchain development partner, please feel free to contact our skilled Stellar blockchain developers and team for expert guidance.