Initialize a dapp using scripts - Stellar Developer Docs

When setting up an example Soroban Dapp, correct initialization is crucial. This process entails several steps, including cloning, building and deploying smart contracts, and invoking functions to configure them. This guide walks you through the steps to build and deploy these smart contracts, ensuring a seamless setup for your Soroban Dapp.

Building the Soroban Token Smart Contract

In a dapp, the Soroban Token smart contract can represent the tokenized asset that users send and receive. Here is an example of how to build and deploy the Soroban Token smart contract: Start by cloning the Soroban examples repository:

git clone https://github.com/stellar/soroban-examples.git

Then, navigate to the token directory:

cd soroban-examples/token

At this point you can build the smart contract:

make

This action will compile the smart contracts and place them in the token/target/wasm32v1-none/release directory. After building, you’re ready to deploy the smart contracts to Testnet.

Deploying and Initializing the Soroban Token Smart Contract

The smart contract can be initialized at deploy-time by utilizing the __constructor function. This function will be called at deploy-time and can be declared with parameters you can pass to the function with the deploy command. The __constructor function is added to the contract entry point, in this token smart contract it is found in the contract.rs file.

contract.rs

#[contractimpl]
impl Token {
  pub fn __constructor(e: Env, admin: Address, decimal: u32, name: String, symbol: String) {
      if decimal > 18 {
          panic!("Decimal must not be greater than 18");
      }
      write_administrator(&e, &admin);
      write_metadata(
          &e,
          TokenMetadata {
              decimal,
              name,
              symbol,
          },
      )
  }
  ...
}

The __constructor function in this example project takes the following parameters:

Administrator Account: This is the public key of the administrator account. The administrator has control and authority over the token contract, enabling management of various contract functionalities. Learn more about the administrator’s role from the Soroban Token Interface.
Decimal Precision: The decimal precision specifies the maximum number of decimal places the token can support transactions up to. This precision level enables flexibility when transferring token amounts.
Token Name: The token’s name.
Token Symbol: This is the token’s symbol.

The commands below use two identities: alice deploys the contract and is its admin, and bob receives the minted tokens. Create and fund both on Testnet first. Skip this step if you already have them:

stellar keys generate alice --network testnet --fund
stellar keys generate bob --network testnet --fund

To deploy the smart contract in this example, open a terminal in the soroban-examples/token directory and execute the following:

stellar contract deploy \
 --wasm target/wasm32v1-none/release/soroban_token_contract.wasm \
 --source-account alice \
 --network testnet \
 --alias token \
 -- \
 --admin alice \
 --decimal 7 \
 --name 'Demo Token' \
 --symbol 'DT'

This command deploys the smart contract to Testnet using the stellar contract deploy command. Everything after -- goes to the __constructor function, so the contract is initialized with these values. The --alias token option saves the new contract ID under the name token, so later commands can use --id token.

Minting Tokens

Lastly, you need to mint some tokens to the sender’s account:

stellar contract invoke \
 --id token \
 --source-account alice \
 --network testnet \
 -- \
 mint \
 --to bob \
 --amount 1000000000

This command mints 100 tokens to the designated user’s account, in this case bob. The token has 7 decimals, so an --amount of 1000000000 is 100 tokens. By following these steps, you ensure that the Soroban token smart contracts are correctly deployed and initialized, setting the stage for the Dapp to effectively interact with the token. For a deeper dive into Stellar CLI commands, check out the Stellar CLI repo.

Automating Initialization with Scripts

To streamline the initialization process, you can use a script. This script automates tasks such as generating and funding a deployer identity, building and deploying the contract, and initializing it with the necessary parameters. Here’s an example initializer script. Save it in the soroban-examples/token directory and run it from there, for example bash initialize.sh testnet alice 7 'Demo Token' DT:

initialize.sh

#!/bin/bash

set -e

USAGE="Usage: $0 testnet|futurenet|local <admin> <decimal> <name> <symbol>"

if [[ $# -ne 5 ]]; then
  echo "$USAGE"
  exit 1
fi

NETWORK="$1"
ADMIN="$2"
DECIMAL="$3"
NAME="$4"
SYMBOL="$5"

case "$NETWORK" in
testnet | futurenet | local)
  echo "Using the $NETWORK network"
  ;;
*)
  echo "$USAGE"
  exit 1
  ;;
esac

# The CLI keeps the key in its own config.
# The script never reads the secret key or writes it to a file.
if ! stellar keys address deployer >/dev/null 2>&1; then
  echo "Create and fund the deployer identity"
  stellar keys generate deployer --network "$NETWORK" --fund
fi

echo "Build the contract"
make build

echo "Deploy the contract"
CONTRACT_ID="$(
  stellar contract deploy \
    --wasm target/wasm32v1-none/release/soroban_token_contract.wasm \
    --network "$NETWORK" \
    --source-account deployer \
    --alias token \
    -- \
    --admin "$ADMIN" \
    --decimal "$DECIMAL" \
    --name "$NAME" \
    --symbol "$SYMBOL"
)"
echo "Contract deployed with ID: $CONTRACT_ID"

echo "Done"

Here’s a summary of what the initialize.sh script does:

Checks the arguments and picks one of the networks the Stellar CLI knows by default: testnet, futurenet or local
Generates a deployer identity with stellar keys generate and funds it with Friendbot, only if the identity does not exist yet
Builds the contract with make build
Deploys the contract with stellar contract deploy, passes the constructor arguments after --, and saves the contract ID under the alias token
Prints the contract ID and “Done”

The deployer identity only pays for the deployment. The <admin> argument sets the token’s admin, so pass the identity or address that should manage the token. The deployer’s secret key stays in the Stellar CLI’s config, and the script never prints it or writes it to a file. You can run the script again: it reuses the deployer identity, deploys a new contract, and points the token alias at it. By leveraging automated initialization, you can streamline the setup process for your Soroban Dapp, ensuring it is correctly deployed and initialized.

​Building the Soroban Token Smart Contract

​Deploying and Initializing the Soroban Token Smart Contract

​Minting Tokens

​Automating Initialization with Scripts

Building the Soroban Token Smart Contract

Deploying and Initializing the Soroban Token Smart Contract

Minting Tokens

Automating Initialization with Scripts