Anchor for Solana: where builds and program tests break
An Anchor project that builds only on one engineer's machine is the most common entry point.
For everyone else, the build fails during environment setup: the dependency lock file is not committed, the path to the wallet and build tool is set locally in the project configuration, and the program identifier in the interface description and in the keys diverged after a manual update. There are no logic errors, but the build can no longer be reproduced on a second machine.
Tests behave the same way: locally the validator starts from scratch, and each run begins with a clean state, while on the shared test bench accounts already exist, the balance is different, and some data remains from a previous run.
As a result, the same check passes for the author and fails for a colleague, and the cause is not the program code but a different environment.
Until the dependency set, startup parameters, and initial network state are described explicitly, test failures say nothing about build quality.
Publishing an update becomes a manual operation: build the artifact, verify the update key, upload the buffer, confirm the write, synchronize addresses and the interface description.
Rollback is possible only if someone saved the previous binary, and update rights belong to one person—and this is discovered when a rollback is urgently needed.
We break down how this is addressed: a single project configuration, reproducible tests, predictable program deployment.
What a configured project provides: builds, tests, updates
The first measurement worth making on a project is the time from code change to finished artifact.
Split build profiles and dependency caching cut the cycle many times over: the result appears in minutes instead of tens of minutes of waiting, and checks can run several times before changes are sent. Tests run on a local validator without waiting for the network, so feedback arrives immediately.
Environment repeatability eliminates an entire class of failures. Pinned Anchor versions, pinned dependencies, and identical startup for all engineers remove the "passes locally, fails on deployment" discrepancy.
The build is reproduced on a clean machine with one command—a new person on the team reaches a working cycle on day one instead of spending a week sorting out the environment.
Deploying a program to the network stops being a manual sequence of steps: a script builds the artifact, runs checks, deploys the build, and records the address.
The share of manual operations drops almost to zero, and with it goes the risk that someone skips a step or mixes up the network.
Recovery time after a failure is measured in minutes: configuration and keys are in the repository, and rollback to the previous build is one command. We hand over the project with working checks and a description of how to bring it up from scratch on a new machine.
Run and test modes: comparison of options
The same code behaves differently depending on where it runs: on a local validator, account state is set by the scenario; in a public test cluster, some programs are not always available; and request limits are set externally.
That is why the run mode is chosen for the task, not out of habit—both the speed of changes and the reliability of acceptance depend on it.
| Option | When it fits | Limitations |
|---|---|---|
| Local validator on the developer's machine | Fast iterations when debugging programs and checking instructions | State resets on restart, no external services or real data |
| Public test cluster | Checking integrations with third-party programs, interaction with wallets and external services | Shared resources and external limits, state is not controlled, runs conflict with others |
| Dedicated team test bench | Regression before release, acceptance and load scenarios | Requires node and synchronization support, takes longer to deploy, needs scheduling |
| Customer's own node | Acceptance in a closed environment, customer data and security requirements | Access and updates are on the customer's side, the contractor has limited rights |
We tie environment selection to the stage: local validator for daily debugging, dedicated test bench for regression, customer node for final verification in their environment.
We write tests so that the same suite runs in any mode: discrepancies between runs usually reveal an implicit dependency on the environment—clocks, oracles, or pre-filled state.
Setting up Anchor for Solana: from project scheme to deployment
Setting up Anchor for Solana is not a single initialization command but a sequence of work where each step relies on the previous one.
Losses arise later: environments diverge, the account scheme and signing rights live in the developer's memory, tests pass locally and differ from behavior in the shared network. That is why we run the project in fixed stages, and each has a verifiable result.
- Repository audit. Tool versions, dependencies, build settings—we mark what is reproducible from a clean environment and what relies on manual steps.
- Project and role scheme. Programs, accounts, signing rights, and the relationships between them—the basis for both tests and configuration audit.
- Environment setup. Local validator, test and main network—separate keys and parameters for each environment, without overlap.
- Build configuration. Profiles and option sets for each environment, reproducible artifacts that do not depend on the developer's machine.
- Test coverage. Instructions, account state after transactions, failure scenarios—behavior is verified before and after deployment.
- Pre-deployment checks. A run on the test network, pinned parameters, rollback plan, and update key management procedure.
- Project handover. Documentation, scheme, deployment scripts, and a walkthrough with the customer's team—updates are released without us.
This order removes the main cause of breakdowns—the discrepancy between what is described and what is deployed. The project builds and comes up from the repository on a clean machine.
Configurations, tests, and procedures in the delivery
Development does not end with program deployment—what matters more is what remains in your team's hands.
We hand over the working environment in full so an engineer can release updates independently, without reconstructing logic from change history and without checking with us at every step.
For an Anchor program this is especially noticeable: most maintenance errors arise not in the instruction code but in the environment around it.
- Configuration files by environment—separate parameter sets for the local test bench, test network, and main network: program addresses, provider keys, compute limits. Values are not duplicated in code.
- Variable description—a table with the purpose of each parameter, allowed values, and consequences of changes. A new engineer does not need to read the entire program.
- Access policies—a role matrix: who deploys the program, who manages service accounts, who only reads state. Critical operations require multiple signatures.
- Test suite—unit and integration checks for instructions, negative scenarios, rights checks. Running on the local validator and in the test network catches regressions before deployment.
- Deployment instruction—a step-by-step build and deployment procedure with checks: what to verify before signing, where to look at the log, and how to confirm that the network accepted the update.
- Update procedure—change freeze, test run, test network deployment, result verification, main network deployment, and a pre-described rollback procedure.
- Architecture documentation—account scheme and relationships, initialization order, state storage locations. It allows assessing the consequences of a change before work begins.
Case study: reduced build time and eliminated test failures
What it was
The Anchor project took 12–14 minutes to build: the program and client side were rebuilt from scratch, and dependencies were not cached between runs.
Tests in the main branch failed on average three times a week, and on different suites—the suites shared one local validator and common account state.
Diagnosing one such failure took 30–40 minutes: the engineer restarted the run, got a green result, and could not tell whether it was a race condition or a real regression. Releases stalled, branches were rolled back, confidence in checks fell—they began to be bypassed.
What was changed and what was achieved
We separated test suites into isolated local validator instances with state reset between groups and pinned key generation, time, and initial balances—the source of "flaky" failures disappeared.
Dependencies were moved into a cache, the build was split into incremental and release profiles, and toolchain versions were pinned in a lockfile so local and server builds matched.
The build came down to 3–4 minutes, the share of reruns dropped from a third to zero or one per month, and recovery after a failure fell from half an hour to 5–7 minutes. Over two months of observation, there was not a single release rollback due to a "flaky" test.
The way of working also changed: changes go to the main branch in small batches, not accumulated packages. If a test fails, it is a real defect, and it is visible immediately, not after a restart.
How does a local validator differ from a test bench?
A local validator is a process on the engineer's machine that starts together with the Anchor project: state in one directory, startup in seconds, reset to clean with one command.
A test bench is a permanent environment of several nodes deployed separately from the workstation, with parameters close to the public network. These are not fast and slow versions of the same thing: the environments catch different classes of defects.
On a local validator, the "edit—build—check" cycle takes seconds, so it is used to check instruction logic, account parsing, and edge cases.
The price of speed is environment predictability: one node and one order of events do not reproduce confirmation delay, transaction competition for block space, or block producer switching, so races and synchronization defects do not appear on it.
A test bench is needed where access and updates are checked, not arithmetic: program rights, multisig, role separation, deploying a new build, rolling back to the previous one, and migrating existing accounts.
These scenarios make sense only in an environment with an already deployed program and accumulated state.
Reproducibility is provided not by the tool but by the same environment description: a state snapshot, a fixed set of test accounts, unified startup parameters, and versions from the current branch.
Then a test failure repeats both locally and on the test bench, and a discrepancy in results points to environment influence, not randomness.
Technical concerns: tests, access, updates
Some questions arise not at the start but when the code already builds and passes checks on the test bench.
Below are answers to technical concerns that come up when handing the project over to another team, changing the person responsible for releases, or preparing for the first deployment to the Solana main network.
Can an already deployed project be moved to our configuration?
Yes. Configuration, the set of checks, and deployment scripts are transferred separately from the program logic. We compare the account structure, instruction set, and dependencies, and run checks on a copy of the test network data. If the result matches, the project is ready to work.
Who gets the right to deploy updates?
Release rights are described explicitly: who signs changes, whether multiple participants must confirm, and which operations are prohibited after deployment.
For a running project, we transfer control without stopping: first we add the new participant and verify their rights, then remove the old ones.
Why do check results differ on different machines?
Usually the environment differs, not the logic: toolchain versions, startup order, test account state. We pin the environment, isolate checks from each other, and reset state before a run—discrepancies either disappear or point to a real error.
Why a separate test bench, and how is access arranged?
Checks run on a copy of the main network with the same parameters, so errors do not reach users. Access is granted by role: read, run checks, deploy. Before release—build, run, compare changes, and obtain the responsible person's confirmation.
Let's discuss the task: what is needed for an estimate and work plan
To make the scope estimate based on facts rather than guesses, it is useful to attach several inputs to the task discussion.
A repository link and a short description of what already works are enough: we will look at the structure of the Anchor programs, the configuration file, and the current set of checks, then return with an implementation plan and timeline by stage.
- Repository link and working branch—shows which programs are already built and which are only declared.
- Role description: who signs transactions, which accounts are created, who holds the management keys.
- List of environments—local validator, test and main clusters, and how settings are transferred between them.
- Check requirements: which scenarios must pass before deployment, whether load runs and account size control are needed.
- What is already automated: builds, tests, manual steps that you want to remove.
- Deadline constraints and external dependencies—release dates, audit, integrations on the side of other teams.
This set is enough to break the work into stages: environment preparation, configuration, check coverage, deployment, handover with documentation. Describe the task and attach the listed items—we will return with a scope estimate, implementation plan, and timeline for each stage.