3. Deploy to Testnet

You've built two simple contracts and run them locally in Sandbox. Now you can deploy them to a network.

Soroban has a test network called Testnet that you can use to deploy and test your contracts. It's a live network, but it's not the same as the Stellar public network. It's a separate network that is used for development and testing, so you can't use it for production apps. But it's a great place to test your contracts before you deploy them to the public network.

Configure Testnet in your CLI

The first step toward deploying to testnet is to configure your CLI to use it. You can do this by running the following command:

soroban config network add --global testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

Note the --global. This creates a file in your home folder's /.config/soroban/network/testnet.toml with the settings you specified. This means that you can use the --network testnet flag in any Soroban CLI command to use this network.

If you want project-specific network configurations, you can omit the --global flag, and the networks will be added to your working directory's .soroban/network folder instead.

Configure an Identity

So far when using Sandbox, you haven't needed to consider who is sending the transactions. But when you deploy to a network, you need to specify an identity that will be used to sign the transactions.

Let's configure an identity called alice. You can use any name you want, but it might be nice to have some named identities that you can use for testing, such as alice, bob, and carol.

soroban config identity generate --global alice

You can see the public key of alice with:

soroban config identity address alice

Like the Network configs, the --global means that the identity gets stored in ~/.config/soroban/identity/alice.toml. You can omit the --global flag to store the identity in your project's .soroban/identity folder instead.

All this did so far is generate a public/private keypair on your local machine. No network requests were made, and alice has no funds on Testnet. This means that you can't make any transactions with alice yet.

To get alice some Testnet tokens, you'll need to use Friendbot. All Stellar and Soroban test networks have a Friendbot that you can use to get some test tokens. The public Friendbot instance for Testnet lives at https://friendbot.stellar.org. Use it:

 curl "https://friendbot.stellar.org/?addr=$(soroban config identity address alice)"

Command Expansion $(…)

This uses command expansion, which only works with bash-compatible shells. If you are using Windows or some other shell, you will need to copy the output of soroban config… and paste it into the curl command, or figure out how command expansion works in your shell.

Deploy

Now you can deploy your Hello World contract:

soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/hello_soroban.wasm \
  --source alice \
  --network testnet

This returns the ID of the contract, starting with a C. Let's put it somewhere semi-permanent so we can use it later. Copy that value and:

echo "C…" > .soroban/hello-id

You may need to create the .soroban folder first with mkdir .soroban.

Interact

This should look a lot like interacting with the contract in the Sandbox, as you did in 1. Hello World. Only now the contract lives on the Testnet network, and the CLI is making RPC calls in the background. Let's try it:

soroban contract invoke \
  --id $(cat .soroban/hello-id) \
  --source alice \
  --network testnet \
  -- \
  --help

This again makes use of command expansion $(…); see the note about that above.

This looks a lot like interacting with the contract back in 1. Hello World, but rather than using a --wasm flag to point to a local wasm file, you now specify the --network and the --source. That's it! You can try calling hello as before:

soroban contract invoke \
  --id $(cat .soroban/hello-id) \
  --source alice \
  --network testnet \
  -- \
  hello \
  --to RPC

Two-step deployment

It's worth knowing that deploy is actually a two-step process.

1. Upload the contract bytes to the network. Soroban currently refers to this as installing the contract—from the perspective of the blockchain itself, this is a reasonable metaphor. This uploads the bytes of the contract to the network, indexing it by its hash. This contract code can now be referenced by multiple contracts, which means they would have the exact same behavior but separate storage state.

2. Instantiate the contract. This actually creates what you probably think of as a Smart Contract. It makes a new contract ID, and associates it with the contract bytes that were uploaded in the previous step.

You can run these two steps separately. Let's try it with the Incrementor contract:

soroban contract install \
  --network testnet \
  --source alice \
  --wasm target/wasm32-unknown-unknown/release/incrementor.wasm

This returns the hash of the Wasm bytes. Now you can use --wasm-hash with deploy rather than --wasm. Let's also automatically pipe the returned contract ID into a file in the .soroban directory, so that when you search your command history and reuse the deploy command in the future, you don't forget that step (you might want to go back and do something similar with the Hello World deploy, too):

soroban contract deploy \
  --wasm-hash [paste the output from the last command] \
  --source alice \
  --network testnet \
  > .soroban/incrementor-id

You can check that it saved the contract ID correctly:

cat .soroban/incrementor-id

Now you can interact with it over RPC like you did with the Hello World contract:

soroban contract invoke \
  --id $(cat .soroban/incrementor-id) \
  --source alice \
  --network testnet \
  -- \
  increment

Run your own network/node

Sometimes you'll need to run your own node:

• Production apps! It's a bad idea to rely on the public, Stellar-maintained Soroban RPC endpoint. Instead, you should run your own node, and point your app at that.
• When you need a network that differs from the version deployed to Testnet.

The Soroban team maintains Docker containers that makes this as straightforward as possible. See the RPC reference for details.

Summary

In this lesson, we learned how to:

• configure networks and identities using Soroban CLI
• fund accounts on test networks using Friendbot
• deploy contracts to a test network
• interact with deployed contracts

You shouldn't have any changes to commit to git, because we didn't change any code in this lesson!

Up next, we'll use the deployed contracts to build a simple web app.