DEV Community

esteblock
esteblock

Posted on

Token Playground #9 : Read the native token (XLM) using soroban-cli

Token Playground Chapter 9 : Read the native token (XLM) using soroban-cli

1. Introduction

What about when we want to use XLM inside a Soroban smart contract? How do we trigger those transactions? Can we trigger transactions on behalf the user using the require_auth method?

In this chapter we will use our XLM inside Soroban using soroban-cli!

2. The native Stellar Lumens (XLM) contract address

Soroban is great! And in order to use the native XLM tokens, we just need to treat it as another asset that behaves as an Stellar Asset Contract (SAC). It indeed has it's own contract address.

We will call this the native token address

This contract address is unique per network (standalone, futurenet... as well as it will later be with testnet and mainnet), so be sure to call it correctly.

  1. Wrap the native token: In order to get the XLM "contract address" you first need to "wrap" the native asset it into a token inside Soroban. This can be done only once, but you'll be needing to do it each time you open a new Standalone instance.

If you use only Futurenet, you'll probably never need to do this:

TOKEN_ADDRESS=$(soroban lab token wrap $ARGS --asset native)
echo Wrapped with address result: $TOKEN_ADDRESS
Enter fullscreen mode Exit fullscreen mode

This command will return the address, so no need for the next step. If this commands fails, this means that the token has already been wrapped before :)

  1. Get the native token's contracts address: Once the native token has been wrapped, you can also it's address like this: 
soroban lab token id --asset native --network standalone
Enter fullscreen mode Exit fullscreen mode

and you'll get

CDMLFMKMMD7MWZP3FKUBZPVHTUEDLSX4BYGYKH4GCESXYHS3IHQ4EIG4
Enter fullscreen mode Exit fullscreen mode

and for the case of futurenet you'll get:

soroban lab token id --asset native --network futurenet

CB64D3G7SM2RTH6JSGG34DDTFTQ5CFDKVDZJZSODMCX4NJ2HV2KN7OHT
Enter fullscreen mode Exit fullscreen mode

3. Native token and Token Interface

So, can we use this address as if it was any other token that complies with the token interface?

Yes! So let's do it.

Implementing the token intrface means that the contract will have the following functions: (please take a look at the link above)

pub trait Contract {
    // --------------------------------------------------------------------------------
    // Admin interface – privileged functions.
    // --------------------------------------------------------------------------------
    //
    // All the admin functions have to be authorized by the admin with all input
    // arguments, i.e. they have to call `admin.require_auth()`.

    /// Clawback "amount" from "from" account. "amount" is burned.
    /// Emit event with topics = ["clawback", admin: Address, to: Address], data = [amount: i128]
    fn clawback(
        env: soroban_sdk::Env,
        from: Address,
        amount: i128,
    );

    /// Mints "amount" to "to".
    /// Emit event with topics = ["mint", admin: Address, to: Address], data = [amount: i128]
    fn mint(
        env: soroban_sdk::Env,
        to: Address,
        amount: i128,
    );

    /// Sets the administrator to the specified address "new_admin".
    /// Emit event with topics = ["set_admin", admin: Address], data = [new_admin: Address]
    fn set_admin(
        env: soroban_sdk::Env,
        new_admin: Address,
    );

    /// Sets whether the account is authorized to use its balance.
    /// If "authorized" is true, "id" should be able to use its balance.
    /// Emit event with topics = ["set_authorized", id: Address], data = [authorize: bool]
    fn set_authorized(
        env: soroban_sdk::Env,
        id: Address,
        authorized: bool,
    );

    // --------------------------------------------------------------------------------
    // Token interface
    // --------------------------------------------------------------------------------
    //
    // All the functions here have to be authorized by the token spender
    // (usually named `from` here) using all the input arguments, i.e. they have
    // to call `from.require_auth()`.

    /// Set the allowance by "amount" for "spender" to transfer/burn from "from".
    /// "expiration_ledger" is the ledger number where this allowance expires. It cannot
    /// be less than the current ledger number unless the amount is being set to 0.
    /// An expired entry (where "expiration_ledger" < the current ledger number)
    /// should be treated as a 0 amount allowance.
    /// Emit event with topics = ["approve", from: Address, spender: Address], data = [amount: i128, expiration_ledger: u32]
    fn approve(
        env: soroban_sdk::Env,
        from: Address,
        spender: Address,
        amount: i128,
        expiration_ledger: u32,
    );

    /// Transfer "amount" from "from" to "to".
    /// Emit event with topics = ["transfer", from: Address, to: Address], data = [amount: i128]
    fn transfer(
        env: soroban_sdk::Env,
        from: Address,
        to: Address,
        amount: i128,
    );

    /// Transfer "amount" from "from" to "to", consuming the allowance of "spender".
    /// Authorized by spender (`spender.require_auth()`).
    /// Emit event with topics = ["transfer", from: Address, to: Address], data = [amount: i128]
    fn transfer_from(
        env: soroban_sdk::Env,
        spender: Address,
        from: Address,
        to: Address,
        amount: i128,
    );

    /// Burn "amount" from "from".
    /// Emit event with topics = ["burn", from: Address], data = [amount: i128]
    fn burn(
        env: soroban_sdk::Env,
        from: Address,
        amount: i128,
    );

    /// Burn "amount" from "from", consuming the allowance of "spender".
    /// Emit event with topics = ["burn", from: Address], data = [amount: i128]
    fn burn_from(
        env: soroban_sdk::Env,
        spender: Address,
        from: Address,
        amount: i128,
    );

    // --------------------------------------------------------------------------------
    // Read-only Token interface
    // --------------------------------------------------------------------------------
    //
    // The functions here don't need any authorization and don't emit any
    // events.

    /// Get the balance of "id".
    fn balance(env: soroban_sdk::Env, id: Address) -> i128;

    /// Get the spendable balance of "id". This will return the same value as balance()
    /// unless this is called on the Stellar Asset Contract, in which case this can
    /// be less due to reserves/liabilities.
    fn spendable_balance(env: soroban_sdk::Env id: Address) -> i128;

    // Returns true if "id" is authorized to use its balance.
    fn authorized(env: soroban_sdk::Env, id: Address) -> bool;

    /// Get the allowance for "spender" to transfer from "from".
    fn allowance(
        env: soroban_sdk::Env,
        from: Address,
        spender: Address,
    ) -> i128;

    // --------------------------------------------------------------------------------
    // Descriptive Interface
    // --------------------------------------------------------------------------------

    // Get the number of decimals used to represent amounts of this token.
    fn decimals(env: soroban_sdk::Env) -> u32;

    // Get the name for this token.
    fn name(env: soroban_sdk::Env) -> soroban_sdk::Bytes;

    // Get the symbol for this token.
    fn symbol(env: soroban_sdk::Env) -> soroban_sdk::Bytes;
}
Enter fullscreen mode Exit fullscreen mode

In order to call a function of the native asset smart contract inside soroban-cli, we need to provide the WASM. This will tell soroban-cli what are the name of the functions, name and number of variables and what does the function returns.

This is why that in order to interact with the native contract address, we need first a WASM of a token that implements the token interface.

4. Get the WASM of a token contract.

Now we will use the stellar token's contract address found in section 2, together with the token WASM after compiling the a token contract that implements the token interface.

In this case we'll use the token contract available in https://github.com/stellar/soroban-examples/

  1. Get the token contract. Clone https://github.com/stellar/soroban-examples/ and compile the token contract. In this repository you'll find already the token contract of the release 0.9.2 (complying with preview 10) 
cd src/contracts/token
Enter fullscreen mode Exit fullscreen mode
  1. Compile the token 
make build
Enter fullscreen mode Exit fullscreen mode

This will create the compiled wasm in /workspace/src/contracts/token/target/wasm32-unknown-unknown/release/soroban_token_contract.wasm

5. Check your balance using soroban-cli and the native token's contract address.

We have the native token's address and the WASM of a token contract that implements the token interface. We just need to call it!

0.- Set your environment.
Here we suppose that you are using the soroban-preview:10 image as it was explained in previous chapters:

TOKEN_WASM="/workspace/src/contracts/token/target/wasm32-unknown-unknown/release/soroban_token_contract.wasm"

TOKEN_ADDRESS="$(soroban lab token id --asset native --network standalone)"

NETWORK="standalone"
SOROBAN_RPC_HOST="http://stellar:8000"
SOROBAN_RPC_URL="$SOROBAN_RPC_HOST/soroban/rpc"
FRIENDBOT_URL="$SOROBAN_RPC_HOST/friendbot"
SOROBAN_NETWORK_PASSPHRASE="Standalone Network ; February 2017"
soroban config network add "$NETWORK" \
  --rpc-url "$SOROBAN_RPC_URL" \
  --network-passphrase "$SOROBAN_NETWORK_PASSPHRASE"
ARGS="--network standalone --source-account my-account"
Enter fullscreen mode Exit fullscreen mode

1.- Create a soroban-cli identity

soroban config identity generate my-account
MY_ACCOUNT_ADDRESS="$(soroban config identity address my-account)"
Enter fullscreen mode Exit fullscreen mode

2.- Fund this identity with the friendbot

curl  -X POST "$FRIENDBOT_URL?addr=$MY_ACCOUNT_ADDRESS"
Enter fullscreen mode Exit fullscreen mode

3.- Ask your balance to the native token's contract:

MY_BALANCE=$(soroban contract invoke \
  $ARGS \
  --wasm $TOKEN_WASM \
  --id "$TOKEN_ADDRESS" \
  -- \
  balance \
  --id $MY_ACCOUNT_ADDRESS)
echo my-account XLM balance: $MY_BALANCE
Enter fullscreen mode Exit fullscreen mode

You should have an answer like this one:

Asking the native tokens contract what is my-account balance:
my-account XLM balance: "99999952867"
Enter fullscreen mode Exit fullscreen mode

6. Asking other things: 

soroban contract invoke \
  $ARGS \
  --wasm $TOKEN_WASM \
  --id "$TOKEN_ADDRESS" \
  -- \
  name
Enter fullscreen mode Exit fullscreen mode 
"native"
Enter fullscreen mode Exit fullscreen mode

7. Use our code

If you want to use our code in the Token Playground's Repo, you can just call our script with the soroban-preview-10 docker containter

You can run it by:

bash src/chapter9/native_XLM_soroban_read.sh
Enter fullscreen mode Exit fullscreen mode

Check all the code in the repo!

What is next?

In this chapter we wrapped the native token, read it's address, generated a token WASM and interacted with these using soroban-cli in order to read some information about the native asset (balance, name)!

In the next chapter we'll use this contract address in order to send some XLM!

Are you ready?

This Playground chapter has been written by @esteblock

Top comments (0)

Read next

tejasq profile image

Vector Search is Eating the Web

Tejas Kumar -

doriansabitov profile image

Shopify Plus to Salesforce Migration Guide

Dorian Sabitov -

mathieularose profile image

Building a Simple and Secure GitOps CI/CD Pipeline with GitHub Actions (SOC 2)

Mathieu Larose -

jdboris profile image

Practical Code Architecture 🛠️ for Beginners (in JavaScript)

Joe Boris -