Anchor.toml Configuration

provider (required)

A wallet and cluster that are used for all commands.

Example:

[provider]
cluster = "localnet"                    # The cluster used for all commands.
wallet = "~/.config/solana/id.json"     # The keypair used for all commands.

scripts (required for testing)

Scripts that can be run with anchor run <script>. The test script is executed by anchor test.

Example:

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

features

resolution

This tells the IDL to support account resolution. The default is true.

Example:

[features]
resolution = true

Adds a directory where you want the <idl>.ts file to be copied when running anchor build. This is helpful when you want to keep this file in version control, like when using it on the frontend, which will probably not have access to the target directory generated by anchor.

Example:

[workspace]
types = "app/src/idl/"

members

Sets the paths --relative to the Anchor.toml-- to all programs in the local workspace, i.e., the path to the Cargo.toml manifest associated with each program that can be compiled by the anchor CLI. For programs using the standard Anchor workflow, this can be omitted. For programs not written in Anchor but still want to publish, this should be added.

Example:

[workspace]
members = [
    "programs/*",
    "other_place/my_program"
]

exclude

Opposite of workspace.members.

Example:

[workspace]
exclude = [
    "programs/my_program"
]

programs

Example:

[programs.localnet]
my_program = "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"

The addresses of the programs in the workspace.

programs.localnet is used during testing on localnet where it's possible to load a program at genesis with the --bpf-program option on solana-test-validator.

test

startup_wait

Increases the time anchor waits for the solana-test-validator to start up. This is, for example, useful if you're cloning (see test.validator.clone) many accounts which increases the validator's startup time.

Example:

[test]
startup_wait = 10000

genesis

Makes commands like anchor test start solana-test-validator with a given program already loaded.

Example

[[test.genesis]]
address = "srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX"
program = "dex.so"
 
[[test.genesis]]
address = "22Y43yTVxuUkoRKdm9thyRhQ3SdgQS7c7kB6UNCiaczD"
program = "swap.so"
upgradeable = true

upgradeable

Deploys the program-to-test using --upgradeable-program. This makes it possible to test that certain instructions can only be executed by the program's upgrade authority. The initial upgrade authority will be set to provider.wallet.

If unspecified or explicitly set to false, then the test program will be deployed with --bpf-program, disabling upgrades to it.

Example:

[test]
upgradeable = true

test.validator

These options are passed into the options with the same name in the solana-test-validator cli (see solana-test-validator --help) in commands like anchor test.

[test.validator]
url = "https://api.mainnet-beta.solana.com"     # This is the url of the cluster that accounts are cloned from (See `test.validator.clone`).
warp_slot = 1337                                # Warp the ledger to `warp_slot` after starting the validator.
slots_per_epoch = 5                             # Override the number of slots in an epoch.
rpc_port = 1337                                 # Set JSON RPC on this port, and the next port for the RPC websocket.
limit_ledger_size = 1337                        # Keep this amount of shreds in root slots.
ledger = "test-ledger"                          # Set ledger location.
gossip_port = 1337                              # Gossip port number for the validator.
gossip_host = "127.0.0.1"                       # Gossip DNS name or IP address for the validator to advertise in gossip.
faucet_sol = 1337                               # Give the faucet address this much SOL in genesis.
faucet_port = 1337                              # Enable the faucet on this port.
dynamic_port_range = "1337 - 13337"             # Range to use for dynamically assigned ports.
bind_address = "127.0.0.1"                      # IP address to bind the validator ports.

test.validator.clone

Use this to clone an account from the test.validator.clone.url cluster to the cluster of your test. If address points to a program owned by the "BPF upgradeable loader", anchor (>= 0.23.0) will clone the program data account of the program for you automatically.

Example:

[test.validator]
url = "https://api.mainnet-beta.solana.com"
 
[[test.validator.clone]]
address = "7NL2qWArf2BbEBBH1vTRZCsoNqFATTddH6h8GkVvrLpG"
[[test.validator.clone]]
address = "2RaN5auQwMdg5efgCaVqpETBV8sacWGR8tkK4m9kjo5r"
[[test.validator.clone]]
address = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s" # implicitly also clones PwDiXFxQsGra4sFFTT8r1QWRMd4vfumiWC1jfWNfdYT

test.validator.account

Use this to upload an account from a .json file.

Example:

[[test.validator.account]]
address = "Ev8WSPQsGb4wfjybqff5eZNcS3n6HaMsBkMk9suAiuM"
filename = "some_account.json"
 
[[test.validator.account]]
address = "Ev8WSPQsGb4wfjybqff5eZNcS3n6HaMsBkMk9suAiuM"
filename = "some_other_account.json"

surfpool

Configuration for the Surfpool validator, which is the default local validator used by anchor test. Surfpool provides a lightweight Solana simulator with features like automatic account cloning and runbook execution. All fields are optional and have sensible defaults.

Example:

[surfpool]
startup_wait = 5000                                       # Time (ms) to wait for Surfpool to start. Default: 5000.
shutdown_wait = 2000                                      # Time (ms) to wait for Surfpool to shut down. Default: 2000.
rpc_port = 8899                                           # JSON RPC port. Default: 8899.
ws_port = 8900                                            # WebSocket port. If not set, derived automatically.
host = "127.0.0.1"                                        # IP address to bind to. Default: "127.0.0.1".
online = true                                             # Enable online mode (clone accounts from a remote cluster).
datasource_rpc_url = "https://api.mainnet.solana.com" # RPC URL to use as the data source when online mode is enabled.
airdrop_addresses = ["addr1...", "addr2..."]               # Addresses to airdrop SOL to at startup.
manifest_file_path = "./Cargo.toml"                       # Path to the Cargo.toml manifest file.
runbooks = ["./runbooks/setup.json"]                       # Paths to runbook files to execute on startup.
slot_time = 400                                            # Simulated slot time in milliseconds.
log_level = "info"                                         # Log level for Surfpool. Default: "none".
block_production_mode = "clock"                            # Block production mode. Default: "transaction".

startup_wait

Time in milliseconds to wait for Surfpool to start up. This is useful when loading many accounts or running runbooks at startup. Default: 5000.

shutdown_wait

Time in milliseconds to wait for Surfpool to shut down gracefully. Default: 2000.

rpc_port

The port on which Surfpool exposes its JSON RPC endpoint. Default: 8899.

ws_port

The port for the WebSocket endpoint. If not specified, it is derived automatically.

host

The IP address to bind the Surfpool validator ports to. Default: "127.0.0.1".

online

When set to true, Surfpool operates in online mode, allowing it to clone accounts from a remote cluster specified by datasource_rpc_url. Default: false (offline mode).

datasource_rpc_url

The RPC URL of the remote cluster used as a data source when online is enabled.

Example:

[surfpool]
online = true
datasource_rpc_url = "https://api.mainnet.solana.com"

airdrop_addresses

A list of base58-encoded addresses that will receive an airdrop of SOL when Surfpool starts.

Example:

[surfpool]
airdrop_addresses = [
    "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
    "7NL2qWArf2BbEBBH1vTRZCsoNqFATTddH6h8GkVvrLpG"
]

manifest_file_path

Path to the Cargo.toml manifest file for the workspace. Typically not needed since Anchor resolves this automatically.

runbooks

A list of file paths to runbooks that Surfpool will execute on startup. Runbooks allow you to set up initial state (deploy programs, create accounts, etc.) before tests run.

Example:

[surfpool]
runbooks = [
    "./runbooks/setup.json"
]

slot_time

The simulated slot time in milliseconds. Controls how fast slots advance in the Surfpool simulator.

log_level

Sets the log verbosity level for the Surfpool process. Common values include "none", "info", "debug", "warn", and "error". Default: "none".

block_production_mode

Controls how Surfpool produces blocks. Default: "transaction". Known values include:

"clock" -- Produces blocks at regular time intervals based on slot_time.
"transaction" -- Produces a new block for each incoming transaction.

Example:

[surfpool]
block_production_mode = "clock"

toolchain

Override toolchain data in the workspace similar to rust-toolchain.toml.

[toolchain]
anchor_version = "1.0.2"    # `anchor-cli` version to use(requires `avm`)
solana_version = "3.1.10"     # Solana version to use(applies to all Solana tools)
package_manager = "yarn"     # JS package manager to use

package_manager

The package_manager field indicates which package manager Anchor should use for all of its client and workspace commands. Valid values include npm, yarn, pnpm, and bun.

Anchor will default to yarn, if a value is not specified. Note values should be in lowercase, since values are deserialized with serde(rename_all = "lowercase").

Example:

[toolchain]
package_manager = "pnpm"

hooks

The hooks table allows you to configure commands that may be run at specific stages of the build/test/deploy pipeline.

Example:

[hooks]
# Accepts kebab-case names...
pre-build = "echo foo"
# ...and snake-case names
post_build = "echo bar"
# Accepts a list of commands, run in series
pre-test = ["echo 1", "echo 2"]
# Non-zero exit codes will abort the CLI
post-test = "exit 1"
# Unused hooks may be omitted
# pre-deploy = []
# post-deploy = []

registry (removed)

The [registry] section is no longer supported and has been removed in 1.0.0. If your Anchor.toml contains this section, remove it:

- [registry]
- url = "https://anchor.projectserum.com"

Anchor.toml Configuration

On this page