Local Program Development

Summary #

• To develop onchain programs locally, you need the Solana CLI, Rust, and (optional, but recommended) Anchor.
• You can use anchor init to create a new blank Anchor project.
• anchor test runs your tests and also builds your code.

Lesson #

This lesson is a guide to installing the tools required for developing onchain programs. Let's install Solana CLI tools, the Rust SDK, and Anchor, and create a test program to ensure that our setup works.

Lab #

Extra steps for Windows users #

Firstly, make sure you have Windows Terminal installed, otherwise you can install Windows Terminal from the Microsoft store.

Then, install Windows Subsystem for Linux (WSL). WSL provides a Linux environment that launches instantly when needed without slowing down your computer.

Open Windows Terminal, start an 'Ubuntu' session and proceed with the rest of these steps.

Download Rust #

First, install Rust by following the instructions:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Download the Solana CLI tools #

Next, download the Solana CLI tools:

sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

After installation, solana -V should display solana-cli 1.18.x (where x can be any number).

Running the Solana Test Validator #

The Solana Test Validator is a local emulator for the Solana blockchain. It provides developers with a private and controlled environment to build and test Solana programs without needing to connect to a public testnet or mainnet.

To start the Solana Test Validator, run the following command:

solana-test-validator

When running solana-test-validator, you should see output indicating that the validator is working correctly. Below is an example of what the output should look like:

$ solana-test-validator
--faucet-sol argument ignored, ledger already exists
Ledger location: test-ledger
Log: test-ledger/validator.log
⠴ Initializing...
Waiting for fees to stabilize 1...
Identity: J8yKZJa5NtcmCQqmBRC6Fe8X6AECo8Vc3d7L3dF9JPiM
Genesis Hash: FTPnCMDzTEthZxE6DvHbsWWv83F2hFe1GFvpVFBMUoys
Version: 1.18.22
Shred Version: 49491
Gossip Address: 127.0.0.1:1024
TPU Address: 127.0.0.1:1027
JSON RPC URL: http://127.0.0.1:8899
WebSocket PubSub URL: ws://127.0.0.1:8900
⠄ 00:00:25 | Processed Slot: 114 | Confirmed Slot: 114 | Finalized Slot: 82 | Full Snapshot Slot: - | Incremental Snapshot Slot: - | Transactions: 111 | ◎499.999445000

If you see this output, it means the Solana test validator is running correctly. You should cancel the process by pressing CTRL + C, as you'll need to run the anchor test command next.

For more detailed information, you can refer to the Solana Test Validator guide.

Download Anchor #

Finally, download Anchor:

cargo install --git https://github.com/coral-xyz/anchor avm --locked --force

you may need to install additional dependencies in Linux (or WSL):

sudo apt-get update && \
sudo apt-get upgrade && \
sudo apt-get install -y pkg-config build-essential libudev-dev libssl-dev

proceed...

avm install latest
avm use latest

After installation, anchor -V should display anchor-cli 0.30.1. For more detailed information on Anchor, refer to The Anchor Book.

Verify your Anchor Installation #

Create a temporary project with the default contents using Anchor and ensure it compiles and runs:

anchor init temp-project
cd temp-project
anchor test

The anchor test command should complete with no errors or warnings.

However you may encounter issues, and we'll fix them below:

package solana-program #

v1.18.12 cannot be built because it requires rustc 1.75.0 or newer error

This error is due to incompatible versions of solana-program and solana-cli. Run cargo add solana-program@"=1.18.x", where x matches your version of solana-cli. Then re-run anchor test.

Error: Unable to read keypair file #

Add a keypair to .config/solana/id.json. You can either copy a keypair from an .env file (just the array of numbers) into a file or use the command solana-keygen new --no-bip39-passphrase to create a new keypair file. Then re-run anchor test.

error: no such command: build-sbf #

If you see this message, this error typically occurs because the relevant binaries are not in your shell's PATH variable.

Run this command to add this folder to your shell, and also add this to your ~/.zshrc or ~/.bashrc file to make the change permanent.

export PATH=~"/.local/share/solana/install/active_release/bin:$PATH"

Unable to get latest blockhash. Test validator does not look started. #

There's multiple versions of the 'tar' (tape archiver) command Solana used for archiving. macOS comes with BSD tar, but Solana CLI wants the GNU version installed.

• Install Homebrew and use it to install GNU tar:

  # Install Homebrew; you can skip this step if you already have Homebrew installed
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  # Install GNU tar
  brew install gnu-tar
  

• Add this to your ~/.zshrc or ~/.bashrc file to make the change permanent.

  export PATH=/opt/homebrew/opt/gnu-tar/libexec/gnubin:$PATH
  

Error: Your configured rpc port: 8899 is already in use #

If you are running solana-test-validator, you may encounter the error Error: Your configured rpc port: 8899 is already in use when running anchor test. To resolve this, stop the solana-test-validator before running anchor test.

All done? #

Ensure anchor test completes successfully - with no warnings and no errors - before continuing.