Anchor scaffold

Anchor Scaffold

Overview

Anchor is the de facto Rust framework for Solana programs. It generates the account-validation boilerplate, account discriminators, IDL, and a TypeScript client so you can focus on instruction logic instead of byte layouts. This skill takes a user from zero installed tooling to a deployed counter program on devnet in roughly 10 minutes.

When to use this skill

• "I want to start a new Solana program."
• "How do I scaffold an Anchor project?"
• "Help me write my first on-chain instruction."
• "Deploy a Solana program to devnet."
• The user is on a fresh machine and needs the Solana / Rust / Anchor toolchain installed.

Do not use this skill for SPL-token-only flows, client-only dApp work, or non-Anchor native programs.

Prerequisites

Versions verified May 2026: Anchor 1.0.2, Solana CLI / Agave 3.0.10 (stable) or 4.0.0 (just released, fine for dev), Rust 1.91+, Node 20+, Yarn.

One-line installer (recommended)

The Solana Foundation maintains a script that installs Rust, Solana CLI, Anchor, and surfpool:

curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash

After it finishes, restart your shell and verify:

rustc --version        # rustc 1.91.1 or newer
solana --version       # solana-cli 3.0.10 (or 4.x)
anchor --version       # anchor-cli 1.0.2
node --version         # v20+
yarn --version

Manual install (if the one-liner fails)

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Solana CLI (Agave)
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

# avm (Anchor Version Manager) + Anchor CLI
cargo install --git https://github.com/solana-foundation/anchor avm --force
avm install 1.0.2
avm use 1.0.2

Create a local wallet

Anchor needs a default keypair at ~/.config/solana/id.json. If solana address errors, create one:

solana-keygen new --no-bip39-passphrase
solana config set --url localhost

Workflow

1. Scaffold the project

anchor init hello-program
cd hello-program

This generates:

hello-program/
├── Anchor.toml              # cluster, wallet, program IDs, test runner
├── Cargo.toml               # workspace
├── programs/hello-program/
│   ├── Cargo.toml
│   └── src/lib.rs           # your program
├── tests/hello-program.ts   # default TS test
├── migrations/deploy.ts
├── tsconfig.json
└── package.json

2. Understand Anchor.toml

[toolchain]
anchor_version = "1.0.2"

[features]
resolution = true
skip-lint = false

[programs.localnet]
hello_program = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"

[programs.devnet]
hello_program = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"

[provider]
cluster = "Localnet"           # change to "Devnet" before `anchor deploy`
wallet = "~/.config/solana/id.json"

[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

The programs.<cluster> table maps program name → on-chain program ID. Anchor reads this so the TS client knows where to send instructions.

3. Write the instruction

Replace programs/hello-program/src/lib.rs with the counter program in scripts/hello-program.rs. Key macros to know:

• declare_id!(...) — the program's on-chain address. Must match target/deploy/hello_program-keypair.json.
• #[program] — module containing instruction handlers. Each pub fn becomes a callable instruction.
• #[derive(Accounts)] — declares the accounts each instruction touches and enforces constraints (init, mut, has_one, signer, etc.) at runtime.
• #[account] — marks a struct as a program-owned account. Combine with #[derive(InitSpace)] so Anchor computes the byte size for you (then add 8 for the discriminator).
• #[error_code] — custom errors that surface cleanly in the client.

4. Sync the program ID

The keypair Anchor generates locally won't match the placeholder declare_id! value. Sync them once:

anchor keys sync

This rewrites declare_id! in lib.rs and the [programs.*] entries in Anchor.toml to match target/deploy/hello_program-keypair.json.

5. Build

anchor build

Expected output ends with:

   Compiling hello-program v0.1.0 ...
    Finished `release` profile [optimized] target(s) in 42.13s

Build artifacts:

• target/deploy/hello_program.so — the BPF binary
• target/idl/hello_program.json — IDL used by the TS client
• target/types/hello_program.ts — TypeScript types

6. Test on localnet

Drop scripts/hello-program.test.ts into tests/ (overwrite the default), then:

anchor test

This spins up solana-test-validator, deploys, runs the test file, and tears the validator down. Expected output:

  hello-program
    ✔ initializes the counter to 0 (412ms)
    ✔ increments the counter (407ms)
    ✔ increments again (402ms)
    ✔ rejects increment from a non-authority signer

  4 passing (2s)

If you want a long-running validator for repeated runs:

solana-test-validator       # terminal 1
anchor test --skip-local-validator  # terminal 2

7. Deploy to devnet

solana config set --url devnet
solana airdrop 2                       # may need to retry; devnet faucet is rate-limited
solana balance

Edit Anchor.toml:

[provider]
cluster = "Devnet"

Then deploy:

anchor deploy

Expected output:

Deploying cluster: https://api.devnet.solana.com
Upgrade authority: ~/.config/solana/id.json
Deploying program "hello_program"...
Program path: target/deploy/hello_program.so...
Program Id: Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS

Deploy success

Verify on-chain:

solana program show <PROGRAM_ID> --url devnet

Common pitfalls

1. Anchor / Solana version skew. Anchor 1.0.x expects Solana CLI 2.x or 3.x. If anchor build fails with error[E0658] or unresolved import 'solana_program', you almost certainly have an old toolchain. Run avm use 1.0.2 and agave-install update.

2. declare_id! doesn't match the deploy keypair. After the first anchor build, always run anchor keys sync. Otherwise anchor test fails with DeclaredProgramIdMismatch (Anchor error 4100).

3. No local wallet. solana-keygen new must have been run at least once, or anchor test dies with Error: No such file or directory (os error 2) reading id.json.

4. Insufficient SOL for deploy. A small program costs ~1.5 SOL of rent on devnet. The devnet faucet caps at 2 SOL per request and rate-limits hard. If airdrop fails, use https://faucet.solana.com or wait 8 hours.

5. Forgot the 8-byte discriminator in space. Anchor prepends an 8-byte discriminator to every account. space = 8 + Counter::INIT_SPACE is the safe pattern; bare space = 40 will silently truncate the next field you add.

6. Test file imports the wrong workspace key. anchor.workspace.HelloProgram is the camelCase of your Cargo.toml name. If you renamed the program, update the import and the workspace lookup or you'll get Cannot read properties of undefined.

References

• Anchor docs: https://www.anchor-lang.com/docs
• Anchor source: https://github.com/solana-foundation/anchor
• Solana CLI install: https://docs.anza.xyz/cli/install
• Solana program docs: https://solana.com/docs/programs/anchor
• Devnet faucet: https://faucet.solana.com
• Solana cookbook: https://solana.com/developers/cookbook

Example program

See scripts/hello-program.rs for the working counter program shown in the workflow. Run with scripts/hello-program.test.ts (copy into tests/ after anchor init).