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 and Deploying 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/wasm32-unknown-unknown/release directory.

After building, you're ready to deploy the smart contracts to Futurenet. To do this, open a terminal in the soroban-examples/token directory and execute the following:

soroban contract deploy \
 --wasm target/wasm32-unknown-unknown/release/soroban_token_contract.wasm \
 --source <ADMIN_ACCOUNT_SECRET_KEY> \
 --rpc-url https://rpc-futurenet.stellar.org:443 \
 --network-passphrase 'Test SDF Future Network ; October 2022'

This command deploys the smart contracts to Futurenet using the soroban contract deploy function.

Initializing a Token Contract

With the contracts deployed, it's time to initialize the token contract:

soroban contract invoke \
 --id <TOKEN_CONTRACT_ID> \
 --source-account <ADMIN_ACCOUNT_SECRET_KEY> \
 --rpc-url https://rpc-futurenet.stellar.org:443 \
 --network-passphrase 'Test SDF Future Network ; October 2022' \
 -- initialize \
 --admin <ADMIN_PUBLIC_KEY> \
 --decimal 7 \
 --name '44656d6f20546f6b656e' \
 --symbol '"4454"'

This command requires certain inputs:

• 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 value of 7 specifies that the token can support transactions up to 7 decimal places. This precision level enables flexibility when transferring token amounts.

• Token Name: The token's name, represented as a hex-encoded string. In this case, '44656d6f20546f6b656e' corresponds to "Demo Token".

• Token Symbol: This is the token's symbol, also represented as a hex string. '4454' translates to the symbol "DT".

Minting Tokens

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

soroban contract invoke \
 --id <TOKEN_CONTRACT_ID> \
 --source-account <ADMIN_ACCOUNT_SECRET_KEY> \
 --rpc-url https://rpc-futurenet.stellar.org:443 \
 --network-passphrase 'Test SDF Future Network ; October 2022' \
 -- mint \
 --to <USER_PUBLIC_KEY> \
 --amount 1000000000

This command will mint 100 tokens to the designated user's account.

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 Soroban CLI commands, check out the Soroban 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, wrapping Stellar assets, 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 soroban-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
soroban network add \
  --rpc-url "$SOROBAN_RPC_URL" \
  --network-passphrase "$SOROBAN_NETWORK_PASSPHRASE" "$NETWORK"

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

# TODO: Remove this once we can use `soroban keys` from webpack.
mkdir -p .soroban-example-dapp
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

ARGS="--network $NETWORK --source token-admin"

echo Deploy the Stellar asset contract
TOKEN_ID=$(soroban contract asset deploy $ARGS --asset "EXT:$TOKEN_ADMIN_ADDRESS")
echo "Token deployed successfully with TOKEN_ID: $TOKEN_ID"

# TODO - remove this workaround when
# https://github.com/stellar/soroban-tools/issues/661 is resolved.
TOKEN_ADDRESS="$(node ./address_workaround.js $TOKEN_ID)"
echo "Token Address converted to StrKey contract address format:" $TOKEN_ADDRESS

echo -n "$TOKEN_ID" > .soroban-example-dapp/token_id

echo Build the crowdfund contract
make build

echo Deploy the crowdfund contract
CROWDFUND_ID="$(
  soroban contract deploy $ARGS \
    --wasm target/wasm32-unknown-unknown/release/soroban_crowdfund_contract.wasm
)"
echo "Contract deployed successfully with ID: $CROWDFUND_ID"
echo "$CROWDFUND_ID" > .soroban-example-dapp/crowdfund_id

echo "Initialize the crowdfund contract"
deadline="$(($(date +"%s") + 86400))"
soroban contract invoke \
  $ARGS \
  --id "$CROWDFUND_ID" \
  -- \
  initialize \
  --recipient "$TOKEN_ADMIN_ADDRESS" \
  --deadline "$deadline" \
  --target_amount "1000000000" \
  --token "$TOKEN_ADDRESS"

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 Soroban RPC host URL depending on its execution environment (either inside the soroban-preview Docker container or locally)
• Sets the Soroban 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 to Soroban using soroban network add
• Generates a token-admin identity using soroban 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
• Deploy the Stellar asset contract with soroban contract asset deploy and stores the resulting TOKEN_ID
• Builds the crowdfund contract with make build and deploys it using soroban contract deploy, storing the returned CROWDFUND_ID
• Initializes the crowdfund contract by invoking the initialize function with necessary parameters
• 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.