locallaunchsc-cloud/solana-dev-skills / anchor-scaffold
solana-anchor-scaffold
FlaggedUse this skill when the user wants to bootstrap a new Solana Anchor program from scratch — install toolchain, scaffold project, write a first instruction, build, test, and deploy.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
| scripts/hello-program.rs | script | 2.0 KB |
| scripts/hello-program.test.ts | script | 2.7 KB |
SKILL.md
View on GitHub---
name: solana-anchor-scaffold
description: Use this skill when the user wants to bootstrap a new Solana Anchor program from scratch — install toolchain, scaffold project, write a first instruction, build, test, and deploy.
---
# 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:
```bash
curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash
```
After it finishes, restart your shell and verify:
```bash
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)
```bash
# 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:
```bash
solana-keygen new --no-bip39-passphrase
solana config set --url localhost
```
## Workflow
### 1. Scaffold the project
```bash
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`
```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:
```bash
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
```bash
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:
```bash
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:
```bash
solana-test-validator # terminal 1
anchor test --skip-local-validator # terminal 2
```
### 7. Deploy to devnet
```bash
solana config set --url devnet
solana airdrop 2 # may need to retry; devnet faucet is rate-limited
solana balance
```
Edit `Anchor.toml`:
```toml
[provider]
cluster = "Devnet"
```
Then deploy:
```bash
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:
```bash
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`).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |