Initialize a dapp using scripts

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

Building the Soroban Token Smart Contract

In dapps like the Example Payment Dapp, the Soroban Token smart contracts are used to represent the tokenized asset that users can send and receive. Here is an example of how to build and deploy the Soroban Token smart contracts:

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.

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 \
 --rpc-url https://soroban-testnet.stellar.org \
 --network-passphrase 'Test SDF Network ; September 2015'
 -- \
 --admin alice \
 --decimal 10 \
 --name 'Demo Token' \
 --symbol 'DT'

This command deploys the smart contracts to Testnet using the stellar contract deploy function. The smart contract will be deployed with the mandatory parameters, and the smart contract will be initialized with these values.

Minting Tokens

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

stellar contract invoke \
 --id <TOKEN_CONTRACT_ID> \
 --source-account alice \
 --rpc-url https://soroban-testnet.stellar.org \
 --network-passphrase 'Test SDF Network ; September 2015'
 -- mint \
 --to bob \
 --amount 1000000000

This command will mint 100 tokens to the designated user's account, in this case bob.

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 should automate various tasks such as setting up the network, generating token-admin identities, funding the token-admin account, building and deploying the contracts, and initializing them with necessary parameters.

Here's an example initializer script:

initialize.sh

#!/bin/bash

set -e

NETWORK="$1"

# If stellar-cli is called inside the soroban-preview docker container,
# it can call the stellar standalone container just using its name "stellar"
if [[ "$IS_USING_DOCKER" == "true" ]]; then
  SOROBAN_RPC_HOST="http://stellar:8000"
else
  SOROBAN_RPC_HOST="http://localhost:8000"
fi

case "$1" in
standalone)
  echo "Using standalone network"
  SOROBAN_NETWORK_PASSPHRASE="Standalone Network ; February 2017"
  FRIENDBOT_URL="$SOROBAN_RPC_HOST/friendbot"
  SOROBAN_RPC_URL="$SOROBAN_RPC_HOST/soroban/rpc"
  ;;
futurenet)
  echo "Using Futurenet network"
  SOROBAN_NETWORK_PASSPHRASE="Test SDF Future Network ; October 2022"
  FRIENDBOT_URL="https://friendbot-futurenet.stellar.org/"
  SOROBAN_RPC_URL="https://rpc-futurenet.stellar.org"
  ;;
testnet)
  echo "Using Testnet network"
  SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
  FRIENDBOT_URL="https://friendbot.stellar.org/"
  SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
  ;;
*)
  echo "Usage: $0 standalone|futurenet|testnet"
  exit 1
  ;;
esac

echo Add the $NETWORK network to cli client
stellar network add \
  --rpc-url "$SOROBAN_RPC_URL" \
  --network-passphrase "$SOROBAN_NETWORK_PASSPHRASE" "$NETWORK"

if !(stellar keys ls | grep token-admin 2>&1 >/dev/null); then
  echo Create the token-admin identity
  stellar keys generate token-admin
fi
TOKEN_ADMIN_SECRET="$(stellar keys show token-admin)"
TOKEN_ADMIN_ADDRESS="$(stellar keys address token-admin)"

echo "$TOKEN_ADMIN_SECRET" > .soroban-example-dapp/token_admin_secret
echo "$TOKEN_ADMIN_ADDRESS" > .soroban-example-dapp/token_admin_address

# This will fail if the account already exists, but it'll still be fine.
echo Fund token-admin account from friendbot
curl --silent -X POST "$FRIENDBOT_URL?addr=$TOKEN_ADMIN_ADDRESS" >/dev/null

echo Build the contract
make build

echo Deploy the contract
ARGS="--network $NETWORK --source-account token-admin -- --admin $2 --decimal $3 --name $4 --symbol $5"
CROWDFUND_ID="$(
  stellar contract deploy $ARGS \
    --wasm target/wasm32v1-none/release/soroban_token_contract.wasm
)"
echo "Contract deployed successfully with ID: $CROWDFUND_ID"
echo "$CROWDFUND_ID" > .soroban-example-dapp/crowdfund_id

echo "Done"

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

• Identifies the network (standalone or futurenet) based on user input
• Determines the Stellar RPC host URL depending on its execution environment (either inside the soroban-preview Docker container or locally)
• Sets the Stellar RPC URL based on the previously determined host URL
• Sets the Soroban network passphrase and Friendbot URL depending on the chosen network
• Adds the network configuration using stellar network add
• Generates a token-admin identity using stellar keys generate
• Fetches the TOKEN_ADMIN_SECRET and TOKEN_ADMIN_ADDRESS from the newly generated identity
• Saves the TOKEN_ADMIN_SECRET and TOKEN_ADMIN_ADDRESS in the .soroban directory
• Funds the token-admin account using Friendbot
• Builds the contract with make build and deploys it using stellar contract deploy, storing the returned CROWDFUND_ID
• Prints "Done" to signify the end of the initialization process

By leveraging automated initialization, you can streamline the setup process for your Soroban Dapp, ensuring it is correctly deployed and initialized.