Skip to main content

Asset Management

The stellar-cli can be used to issue and administer assets on the Stellar network.

The following guide assumes that the stellar-cli has been configured to use testnet, or a local test network. To use testnet, run the following command.

stellar network use testnet

Asset Issuance​

To create a Stellar Asset using the stellar-cli several steps take place:

  • An issuer account must exist.
  • An asset code selected.
  • Optionally, an admin is configured.

Issuer Creation​

To create an issuer, generate a key and fund it. Funding uses friendbot, the testnet faucet, and is only available on testnet.

stellar keys generate issuer
stellar keys fund issuer

View the public key with:

stellar keys public-key issuer

Configure the issuer key to be used for signing transactions:

stellar keys use issuer

Issuer Config​

Issuer accounts have several configuration flags that can be toggled and affect all assets issued by the issuer.

In this guide the issuer account will be setup with the revocable and clawback-enabled features will be enabled. These features allow the asset admin to revoke authorisation to use an asset, which has the effect of freezing their balance, and to clawback, which has the effect of forcibly burning the asset.

stellar tx new set-options \
  --set-revocable \
  --set-clawback-enabled

For other options, see the manual for the stellar tx new set-options command.

To view the tx before sending, use the --build-only option and pipe the transaction through the tx edit command:

stellar tx new set-options \
  --set-revocable \
  --set-clawback-enabled \
  --build-only \
  | stellar tx edit \
  | stellar sign \
  | stellar send

Choosing the Asset Code​

Choose an asset code 1 to 12 characters long.

The asset code along with the issuer account address will uniquely identify the asset. An issuer can issue multiple assets, distinguished by their asset code.

For the rest of this guide the asset code ABC will be used.

Asset Contract Setup​

A built-in contract exists on network for every asset. It's address is reserved and can be calculated using the following command.

stellar contract asset id --asset ABC:issuer

The contract is not deployed automatically. Anyone can deploy the contract, it is not an action requiring authorisation.

Contract Deployment​

Deploy the built-in asset contract.

The --asset option specifies the name of the asset, which is in the format <asset-code>:<asset-issuer>.

The --alias option stores locally an alias that can be used in subsequent commands to reference the contract address.

stellar contract asset deploy --asset ABC:issuer --alias mycontract

Run the following command to get some read only data from the contract to confirm it's deployed.

stellar contract invoke --id mycontract -- name
Admin Setup​

At this point the issuer is the admin of the contract. Let's create another account that'll be the admin.

stellar keys generate admin
stellar keys public-key admin
stellar keys fund admin

Using the issuer account, invoke the asset contract's set_admin function.

stellar keys use issuer
stellar contract invoke --source issuer --id mycontract -- set_admin --new_admin admin

Actions​

Once the asset contract is deployed and setup, the following actions can take place.

Mint (Admin Only)​

Generate and fund a user account that the minted asset will be transferred to.

stellar keys generate user
stellar keys fund user
stellar keys public-key user

Using the user account, trust the asset so that the user account can hold the asset.

stellar keys use user
stellar tx new change-trust --line ABC:issuer

To mint the asset to the user, use the admin account, invoke the asset contract's mint function.

stellar keys use admin
stellar contract invoke --id mycontract -- mint --to user --amount 25

Check the balance after the mint.

stellar contract invoke --id mycontract -- balance --id user

Transfer​

Generate and fund a second user account that the user account from the previous step can transfer the asset to.

stellar keys generate user2
stellar keys fund user2
stellar keys public-key user2

Using the user2 account, trust the asset so that the new user account can hold the asset.

stellar keys use user2
stellar tx new change-trust --line ABC:issuer

Using the user account, invoke the asset contract's transfer function.

stellar keys use user
stellar contract invoke --id mycontract -- transfer --from user --to user2 --amount 3

Check the balances after the transfer.

stellar contract invoke --id mycontract -- balance --id user
stellar contract invoke --id mycontract -- balance --id user2

Burn​

Using the user account, invoke the asset contract's burn function.

stellar keys use user
stellar contract invoke --id mycontract -- burn --from user --amount 5

Check the balance after the burn.

stellar contract invoke --id mycontract -- balance --id user

Revoke Authorization / Freeze (Admin Only)​

An admin can revoke a user's authorisation to use the asset. The user will continue to hold the balance but will be unable to transfer it or create new payments. Any existing liabilities, such as those created by offers created on Stellar, will continue to exist and could still be executed.

Using the admin, invoke the asset contract's set_authorized function.

stellar keys use admin
stellar contract invoke --id mycontract -- set_authorized --id user --authorize false

Using the user account, invoke the asset contract's transfer function. The invocation will fail because they are no longer authorized to transfer.

stellar keys use user
stellar contract invoke --id mycontract -- transfer --from user --to user2 --amount 3

Clawback (Admin Only)​

An admin can clawback a user's balance. The amount clawed back will be burned.

Using the admin, invoke the asset contract's clawback function.

stellar keys use admin
stellar contract invoke --id mycontract -- clawback --from user --amount 1

Check the balance after the clawback.

stellar contract invoke --id mycontract -- balance --id user

Guides in this category: