Setting up your Local Smart Contract Development Environment for XION
A properly configured local development environment is essential for building and testing smart contracts on XION. This guide covers the necessary tools, dependencies, and configurations needed to get started.
The following tools will be installed:
Rust & Cargo – The programming language and package manager used for writing and compiling smart contracts.
cargo-generate – A tool for quickly setting up new Rust projects from templates.
Go – Required for interacting with blockchain tooling and dependencies.
Docker – Used for optimizing Rust smart contracts via the Rust Optimizer.
xiond – The XION blockchain daemon for running a local node, deploying smart contracts, and interacting with the blockchain.
Each section provides step-by-step installation instructions for macOS, Debian-based Linux, Red Hat-based Linux and Arch Linux.
Once these dependencies are installed, you will have everything needed to start developing on XION.
Prerequisites
A Unix-like operating system (Linux, macOS, or Windows Subsystem for Linux). If you're using Windows, refer to this guide for installing Windows Subsystem for Linux (WSL).
Rust
Rust is the programming language for developing smart contracts on XION. Known for its performance, security, and memory safety, Rust is well-suited for blockchain development. To build, test, and deploy smart contracts, developers need a properly configured Rust toolchain.
The recommended way to install Rust is through rustup, the official Rust toolchain installer.
Install Rust using Homebrew:
brew install rustup
rustup-init
Follow the on-screen instructions, then restart your terminal or run:
source $HOME/.cargo/env
Verifying Installation
After installation, verify Rust is correctly installed:
rustc --version
You should see output similar to the following::
rustc 1.82.0-nightly (c1a6199e9 2024-07-24)
Cargo
Cargo is Rust's package manager and build system, essential for compiling and managing dependencies in XION smart contract development. When installing Rust using rustup which we did earlier, Cargo is automatically included. However, if Cargo is missing or needs to be installed separately, follow the steps below.
Check if Cargo is Installed
Run the following command to check if Cargo is already installed:
cargo --version
If Cargo is installed, you should see an output similar to:
cargo 1.82.0-nightly (5f6b9a922 2024-07-19)
If Cargo is missing, follow the installation steps below.
If Rust is installed via rustup, install Cargo with:
rustup component add cargo
Cargo Generate
cargo-generate is a Rust tool that simplifies the creation of new Rust projects from pre-existing templates. It is particularly useful for setting up smart contract projects on XION by automating the scaffolding process.
Execute the following command to install cargo-generate:
cargo install cargo-generate
Verifying Installation
After installation, confirm that cargo-generate
is working correctly:
cargo generate --version
If cargo-generate is installed, you should see an output similar to:
cargo generate-generate 0.17.3
Go
Go is required for certain blockchain development tasks, including working with XION’s tooling and dependencies for example xiond
. Follow the installation steps below for your operating system:
brew install go
Alternatively, download and install Go manually from the official website.
Verifying Installation
After installation, verify that Go is correctly installed:
go version
If go is installed, you should see an output similar to:
go version go1.22.3 darwin/arm64
To ensure Go modules work correctly, set up the Go environment:
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc
source ~/.bashrc
If you are using a different shell, replace ~/.bashrc
with the corresponding configuration file for your shell. For example, if you're using Zsh, replace ~/.bashrc
with ~/.zshrc
.
After setting up your environment, restart your terminal to apply the changes.
Docker
Docker is required for optimizing Rust smart contracts using the Rust Optimizer, which ensures that contracts are compiled efficiently for deployment on XION. It can also be used to run xiond
. You can install Docker for your operating system here.
For Linux users, it's recommended to run the Docker daemon in Rootless Mode.
xiond
xiond
is the core command-line tool for running and interacting with the XION blockchain. It serves as the blockchain daemon, enabling developers and node operators to manage network operations, deploy smart contracts, and interact with the XION ecosystem.
To install xiond
, you can either use an installer, download a pre-built binary, build it from source or utilize a docker build. Ensure that you use the release corresponding to the version of xiond
being used on the network where you will be interacting with.
Installers
We recommend installing xiond with one of the following installers for your respective operating system:
Tap the burnt-labs/xion repository
brew tap burnt-labs/xion
Install xiond
brew install xiond
Verify Installation
xiond version
Use Pre-built Binary
You will need to download the appropriate binary for your system architecture https://github.com/burnt-labs/xion/releases/tag/v18.0.0:
Download the linux binary.
For x86_64 architecture it would be:
wget https://github.com/burnt-labs/xion/releases/download/v18.0.0/xiond_18.0.0_linux_amd64.tgz
For ARM64 architecture:
wget https://github.com/burnt-labs/xion/releases/download/v18.0.0/xiond_18.0.0_linux_arm64.tgz
Verify the Integrity of the Binary
Generate the SHA256 hash of the downloaded file:
sha256sum <downloaded_file_name>
The sha256sum
command should generate a hash string (e.g., d41d8cd98f00b204e9800998ecf8427e
).
Download the official checksum file:
wget https://github.com/burnt-labs/xion/releases/download/v18.0.0/xiond-18.0.0-checksums.txt
Compare the two hash strings to ensure they match. This confirms that the downloaded file is authentic and unaltered.
Extract the Binary
Extract the .tgz
file:
tar -xvzf <downloaded_file_name>
Add Executable Permissions
Make the binary executable:
chmod +x <binary_file_name>
Move the Binary to a System Directory
Move the binary to a directory in your PATH
(e.g., /usr/local/bin
) and rename it to xiond
:
sudo mv <binary_file_name> /usr/local/bin/xiond
After this, xiond
should be available for use.
Run xiond with Docker
Instead of installing xiond
manually, you can run it using Docker.
Download the Image from Docker Hub
We publish Docker images to Docker Hub on every commit to the main
branch. The images are tagged with their respective Git SHA.
docker pull burntnetwork/xion:latest
For the latest available tags, check out the Docker Hub page for this image.
Obtain a Shell in the Docker Container
Once the image is pulled, you can invoke the xiond
binary inside a Docker container:
docker run -ti burntnetwork/xion:latest /bin/bash
From within the container, you can interact with xiond
:
xiond version
xiond version --long
xiond --help
Using Docker ensures a clean and isolated environment for running xiond
, eliminating the need for manual installation and dependency management.
Optional: Persist Keys and Configuration
By default, any keys or configuration you create inside a Docker container will be lost once the container is closed. If you want to persist account data and configuration across container sessions, you can mount a local volume.
First create a dedicated directory on your host:
mkdir -p $HOME/.xion_docker
Then run the following command to start the xiond
container session:
docker run -ti \
-v $HOME/xiond_data:/root/.xiond \
burntnetwork/xion:latest /bin/bash
This mounts your host's $HOME/xiond_data
directory to the location inside the container where xiond
stores its data (/root/.xiond
). Any accounts or configurations created inside the container will now persist even after the container is stopped or removed.
To verify persistence:
Run the container and create a key:
xiond keys add myaccount
Exit the container and re-run it with the same volume:
docker run -ti -v $HOME/xiond_data:/root/.xiond burntnetwork/xion:latest /bin/bash xiond keys list
You should still see myaccount
listed.
Build from Source
If downloading the pre-built binary or utilizing the installer is not an option, you can install xiond
from source. Ensure that Go, Git, and Make are installed.
Clone the Repository and Build xiond
xiond
git clone https://github.com/burnt-labs/xion.git
cd xion
git checkout main
make install
This will install the xiond
binary to your GOPATH
.
Verify Installation
You might need to restart your terminal. Check that xiond
is properly installed:
xiond version
If a version number is returned, xiond
is now ready for use.
Last updated
Was this helpful?