Setup
Stellar smart contracts are small programs written in the Rust programming language.
To build and develop contracts you need only a couple prerequisites:
- A Rust toolchain
- An editor that supports Rust
- Stellar CLI
Install Rust
- macOS/Linux
- Windows
- Other
If you use macOS, Linux, or another Unix-like OS, the simplest method to install a Rust toolchain is to install rustup
. Install rustup
with the following command.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
On Windows, download and run rustup-init.exe. You can continue with the default settings by pressing Enter.
The Stellar CLI uses emojis in its output. To properly render them on Windows, it is recommended to use the Windows Terminal. See how to install Windows Terminal on Microsoft Learn. If the CLI is used in the built in Windows Command Prompt or Windows PowerShell the CLI will function as expected but the emojis will appear as question marks.
If you're already using WSL, you can also follow the instructions for Linux.
For other methods of installing Rust, see: https://www.rust-lang.org/tools/install
Install the target
Install the wasm32-unknown-unknown
target.
rustup target add wasm32-unknown-unknown
Configure an Editor
Many editors have support for Rust. Visit the following link to find out how to configure your editor: https://www.rust-lang.org/tools
A popular editor is Visual Studio Code:
- Visual Studio Code editor.
- Rust Analyzer for Rust language support.
- CodeLLDB for step-through-debugging.
Install the Stellar CLI
The Stellar CLI can execute smart contracts on futurenet, testnet, mainnet, as well as in a local sandbox.
The latest stable release is v22.0.1.
Install
There are a few ways to install the latest release of Stellar CLI.
- macOS/Linux
- Windows
Install with Homebrew (macOS, Linux):
brew install stellar-cli
Install with cargo from source:
cargo install --locked [email protected] --features opt
Using the installer:
- Download the installer from the latest release.
- Go to your Downloads folder, double click the installer and follow the wizard instructions.
- Restart your terminal to use the
stellar
command.
Using winget:
winget install --id Stellar.StellarCLI --version 22.0.1
Install with cargo from source:
cargo install --locked [email protected] --features opt
Report issues and share feedback about the Stellar CLI here.
Documentation
The auto-generated comprehensive reference documentation is available here.
Autocompletion
You can use stellar completion
to generate shell completion for different shells. You should absolutely try it out. It will feel like a super power!
- Bash
- ZSH
- fish
- PowerShell
- Elvish
To enable autocomplete on the current shell session:
source <(stellar completion --shell bash)
To enable autocomplete permanently, run the following command, then restart your terminal:
echo "source <(stellar completion --shell bash)" >> ~/.bashrc
To enable autocomplete on the current shell session:
source <(stellar completion --shell zsh)
To enable autocomplete permanently, run the following commands, then restart your terminal:
echo "source <(stellar completion --shell zsh)" >> ~/.zshrc
To enable autocomplete on the current shell session:
stellar completion --shell fish | source
To enable autocomplete permanently, run the following command, then restart your terminal:
echo "stellar completion --shell fish | source" >> ~/.config/fish/config.fish
To enable autocomplete on the current shell session:
stellar completion --shell powershell | Out-String | Invoke-Expression
To enable autocomplete permanently, run the following commands, then restart your terminal:
New-Item -ItemType Directory -Path $(Split-Path $PROFILE) -Force
if (-Not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE | Out-Null }
Add-Content $PROFILE 'Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete'
Add-Content $PROFILE 'stellar completion --shell powershell | Out-String | Invoke-Expression'
If you get an error like cannot be loaded because running scripts is disabled on this system
, you may need to change your Execution Policy with Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser
. Before running this command, be sure you understand the implications of doing so.
To enable autocomplete on the current shell session:
source (stellar completion --shell elvish)
To enable autocomplete permanently, run the following commands, then restart your terminal:
echo "source (stellar completion --shell elvish)" >> ~/.elvish/rc.elv
Configuring the CLI for Testnet
Configure an Identity
When you deploy a smart contract 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
. Notice that the account will be funded using Friendbot.
stellar keys generate --global alice --network testnet --fund
You can see the public key of alice
with:
stellar keys address alice
Like the Network configs, the --global
means that the identity gets stored in ~/.config/stellar/identity/alice.toml
. You can omit the --global
flag to store the identity in your project's .stellar/identity
folder instead.
We previously used ~/.config/soroban
(global) and .soroban
(local) as the configuration directories. These directories are still supported, but the preferred name is now ~/.config/stellar
and .stellar
moving forward.