1---
2title: Anchor v0.32 → v1 Migration Guide
3description: Step-by-step checklist for upgrading an Anchor program workspace from v0.32.x to v1. Covers dependency bumps, CPI context changes, duplicate mutable account errors, legacy IDL account closure, declare_program! renames, interface-instructions removal, CLI commands, and new v1 features.
4---
5 
6# Anchor v0.32 → v1 Migration
7 
8Full upgrade checklist for an Anchor workspace from v0.32.x to v1. Triage which items apply, then work through them in order.
9 
10Items marked **[COMPILE]** will prevent the program from building if not addressed. Items marked **[TS]** affect TypeScript clients. Items marked **[CLI]** affect developer workflow. Items marked **[DEPLOY]** must happen in the right order relative to deployment. Items marked **[CLIENT]** affect the Rust `anchor-client` crate.
11 
12---
13 
14## Applying the Migration (order matters)
15 
16IDL housekeeping and the program code upgrade are **independent tracks** that can be done in parallel, but have one hard constraint: legacy IDL accounts must be closed with the **v0.32 CLI before deploying v1**.
17 
18### Before deploying v1 (old program still live)
19 
20A1. **Re-publish IDL to the new v1 location** *(v1 CLI)* — `anchor idl init` / `anchor idl upgrade`, or use `program-metadata` CLI directly (see §5).
21A2. **Update and publish clients** — update any clients that fetch the on-chain IDL to read from the new v1 location, then deploy them.
22A3. **Close legacy IDL accounts** *(v0.32 CLI)* on every cluster (see §5). Deploying the v1 binary or upgrading the CLI first makes this impossible.
23> **Client notice:** for minimal downtime, follow this order — new IDL first, then clients, then close legacy accounts. Clients depending on the old location will continue to work until A3.
24 
25### Program code upgrade (requires v1 CLI)
26 
270. **Update toolchain** — bring Anchor CLI, AVM, and Solana CLI to the required versions first (see §0).
281. **Audit** — run `cargo check` with bumped deps and collect all errors before fixing anything.
292. **Fix compile errors in order** — deps → CPI context → duplicate accounts → `declare_program!` renames → multiple `#[error_code]` blocks → `Context` lifetime annotations.
303. **`anchor build`** — confirms Rust is clean.
314. **Update TS** — rename package imports, rerun `yarn install` / `npm install`.
325. **Run tests** — `anchor test` (surfpool) or `anchor test -- --features some-feature`.
336. **Deploy** — `anchor deploy`.
34 
35---
36 
37## 0. Check and update toolchain [CLI]
38 
39Verify your current versions before touching any code:
40 
41```bash
42anchor --version   # target: 1.0.0
43avm --version
44solana --version   # recommended: 3.1.10
45rustc --version    # must support edition 2021; 1.75+ recommended
46```
47 
48**Update AVM and Anchor CLI:**
49 
50If your current `avm` supports `self-update`:
51```bash
52avm self-update
53avm install 1.0.0
54avm use 1.0.0
55```
56 
57Otherwise bootstrap via `cargo`:
58```bash
59cargo install avm --git https://github.com/solana-foundation/anchor --tag v1.0.0 --locked
60avm install 1.0.0
61avm use 1.0.0
62```
63 
64**Without AVM** — install `anchor-cli` directly:
65```bash
66cargo install --git https://github.com/solana-foundation/anchor --tag v1.0.0 anchor-cli --locked
67```
68 
69**Update Solana CLI** (if below 3.x):
70```bash
71sh -c "$(curl -sSfL https://release.anza.xyz/v3.1.10/install)"
72solana --version   # confirm 3.1.10
73```
74 
75---
76 
77## 1. Update dependencies [COMPILE]
78 
79**`Cargo.toml` (workspace root and program crate):**
80 
81```toml
82# Before
83anchor-lang = "0.32.1"
84anchor-spl  = "0.32.1"
85solana-program = "2"
86 
87# After
88anchor-lang = "1.0.0"
89anchor-spl  = "1.0.0"
90solana-program = "^3"   # and any other solana-* crate that appears directly
91```
92 
93- All `solana-*` crates that appear in `[dependencies]` must be `^3` or higher.
94 
95**Add `resolver = "2"` to the workspace root `Cargo.toml`:**
96 
97```toml
98[workspace]
99members = ["programs/*"]
100resolver = "2"          # required for edition 2021 members
101```
102 
103Without `resolver = "2"`, Cargo uses the v1 feature resolver, which unifies features across all targets. This causes spurious dependency conflicts and unexpected feature activation when mixing Solana/Anchor crates — manifesting as duplicate type errors or missing trait implementations that disappear once the resolver is set correctly. Any workspace containing at least one `edition = "2021"` crate should have this set.
104- The `cargo update` workarounds for 0.32 (`base64ct --precise 1.6.0`, `constant_time_eq --precise 0.4.1`, `blake3 --precise 1.5.5`) are no longer needed — remove them.
105- If you transitively depended on `solana-sdk` for signing, use `solana-signer` directly.
106 
107See [compatibility-matrix.md](../compatibility-matrix.md) for the full Anchor v1 ↔ Solana CLI version table.
108 
109**Dev dependencies — `litesvm` / `anchor-litesvm`:**
110 
111When you bump `solana-*` crates to `^3`, also bump `litesvm` in `[dev-dependencies]`. The correct version depends on which minor series of the granular `solana-*` crates your workspace resolves to:
112 
113| litesvm | Solana granular crates era | Key markers |
114|---------|---------------------------|-------------|
115| `0.8.2` | `~3.0` | `solana-hash ~3.0`, `solana-vote-interface 4.0`, `solana-system-interface 2.0` |
116| `0.9.1` | `~3.1`–`~3.3` | `solana-hash 4.0`, `solana-vote-interface 5.0`, `solana-system-interface 3.0` |
117| `>0.10.0` | `3.3+` | follow latest releases when on cutting-edge solana-* deps |
118 
119```toml
120# [dev-dependencies] — pick the row that matches your solana-* versions
121litesvm = "0.8.2"   # solana-* ~3.0
122# litesvm = "0.9.1"  # solana-* ~3.1–3.3 (solana-hash 4.0, solana-vote-interface 5.0)
123 
124# If using the Anchor wrapper:
125anchor-litesvm = "0.3"   # requires anchor-lang ^1.0.0 and litesvm ^0.8.2
126```
127 
128> **Tip:** run `cargo tree -d` after bumping — a duplicate `solana-*` in the dependency tree at two incompatible minor versions is the most common sign you've picked the wrong `litesvm` version.
129 
130**`package.json` [TS] — full package rename table:**
131 
132| Before (`@coral-xyz/…`) | After (`@anchor-lang/…`) |
133|-------------------------|--------------------------|
134| `@coral-xyz/anchor` | `@anchor-lang/core` |
135| `@coral-xyz/spl-token` | `@anchor-lang/spl-token` |
136| `@coral-xyz/anchor-errors` | `@anchor-lang/errors` |
137| `@coral-xyz/borsh` | `@anchor-lang/borsh` |
138| `@coral-xyz/anchor-cli` | `@anchor-lang/cli` |
139 
140```json
141// Before
142{
143  "@coral-xyz/anchor": "^0.32.1",
144  "@coral-xyz/spl-token": "^0.32.1"
145}
146 
147// After
148{
149  "@anchor-lang/core": "^1.0.0",
150  "@anchor-lang/spl-token": "^1.0.0"
151}
152```
153 
154```typescript
155// Before
156import * as anchor from "@coral-xyz/anchor";
157import { Program, AnchorProvider, BN } from "@coral-xyz/anchor";
158import { Idl } from "@coral-xyz/anchor/dist/cjs/idl";  // deep import
159 
160// After
161import * as anchor from "@anchor-lang/core";
162import { Program, AnchorProvider, BN } from "@anchor-lang/core";
163import { Idl } from "@anchor-lang/core";  // IDL types live at root now
164```
165 
166Find all occurrences:
167```bash
168grep -r "@coral-xyz" --include="*.ts" --include="*.js" --include="package.json" .
169grep -r "dist/cjs/idl" --include="*.ts" --include="*.js" .
170```
171 
172---
173 
174## 2. Fix CPI context construction [COMPILE]
175 
176`CpiContext::new` and `CpiContext::new_with_signer` no longer accept a program `AccountInfo` as the first argument. Pass the program's **`Pubkey`** (program ID) directly instead. Remove the program account from the accounts struct.
177 
178```rust
179// Before (v0.32)
180#[derive(Accounts)]
181pub struct TransferTokens<'info> {
182    #[account(mut)]
183    pub from: Account<'info, TokenAccount>,
184    #[account(mut)]
185    pub to: Account<'info, TokenAccount>,
186    pub authority: Signer<'info>,
187    pub token_program: Program<'info, Token>,  // <-- needed to pass AccountInfo
188}
189 
190pub fn transfer_tokens(ctx: Context<TransferTokens>, amount: u64) -> Result<()> {
191    let cpi_accounts = Transfer {
192        from: ctx.accounts.from.to_account_info(),
193        to: ctx.accounts.to.to_account_info(),
194        authority: ctx.accounts.authority.to_account_info(),
195    };
196    let cpi_ctx = CpiContext::new(ctx.accounts.token_program.to_account_info(), cpi_accounts);
197    token::transfer(cpi_ctx, amount)
198}
199 
200// After (v1) — program ID as first argument; program field removed from struct
201#[derive(Accounts)]
202pub struct TransferTokens<'info> {
203    #[account(mut)]
204    pub from: Account<'info, TokenAccount>,
205    #[account(mut)]
206    pub to: Account<'info, TokenAccount>,
207    pub authority: Signer<'info>,
208    // token_program no longer needed for CPI
209}
210 
211pub fn transfer_tokens(ctx: Context<TransferTokens>, amount: u64) -> Result<()> {
212    let cpi_accounts = Transfer {
213        from: ctx.accounts.from.to_account_info(),
214        to: ctx.accounts.to.to_account_info(),
215        authority: ctx.accounts.authority.to_account_info(),
216    };
217    let cpi_ctx = CpiContext::new(Token::id(), cpi_accounts);
218    token::transfer(cpi_ctx, amount)
219}
220 
221// PDA-signed CPI
222// Before
223let cpi_ctx = CpiContext::new_with_signer(ctx.accounts.token_program.to_account_info(), cpi_accounts, signer_seeds);
224// After
225let cpi_ctx = CpiContext::new_with_signer(Token::id(), cpi_accounts, signer_seeds);
226```
227 
228Well-known IDs: `Token::id()`, `System::id()`, `system_program::ID`. For external programs declared with `declare_program!`, use `my_program::ID`.
229 
230---
231 
232## 3. Resolve duplicate mutable account errors [COMPILE]
233 
234Anchor now rejects instructions where the same account appears more than once as mutable.
235 
236```
237error: duplicate mutable account `vault` — use `dup` constraint if intentional
238```
239 
240**Option A — prevent aliasing with a constraint (accidental duplication):**
241```rust
242#[account(
243    mut,
244    constraint = token_b.key() != token_a.key() @ MyError::SameAccount
245)]
246pub token_b: Account<'info, TokenAccount>,
247```
248 
249**Option B — allow intentional duplication:**
250```rust
251#[account(mut, dup)]
252pub destination: Account<'info, TokenAccount>,
253```
254 
255Checked types: `Account`, `LazyAccount`, `InterfaceAccount`, `Migration`. Read-only types and `UncheckedAccount` are not checked. Accounts under `init_if_needed` are now included in the check.
256 
257---
258 
259## 4. Update `declare_program!` usages [COMPILE]
260 
261**Rename `utils` module to `parsers`:**
262```rust
263// Before
264use my_external_program::utils::*;
265use my_external_program::utils::parse_instruction;
266 
267// After
268use my_external_program::parsers::*;
269use my_external_program::parsers::parse_instruction;
270```
271 
272```bash
273grep -r "::utils::" --include="*.rs" .
274```
275 
276**Remove `interface-instructions` feature and `#[interface]` attribute:**
277 
278The feature and attribute are gone. Use `#[instruction(discriminator = <const>)]` instead.
279 
280```toml
281# Before (Cargo.toml)
282anchor-lang = { version = "0.32.1", features = ["interface-instructions"] }
283 
284# After — feature removed entirely
285anchor-lang = "1.0.0"
286```
287 
288```rust
289// Before
290#[interface(spl_transfer_hook_interface::execute)]
291pub fn transfer_hook(ctx: Context<TransferHook>, amount: u64) -> Result<()> { Ok(()) }
292 
293// After — use the interface crate's discriminator constant directly
294#[instruction(discriminator = spl_transfer_hook_interface::instruction::ExecuteInstruction::SPL_DISCRIMINATOR)]
295pub fn transfer_hook(ctx: Context<TransferHook>, amount: u64) -> Result<()> { Ok(()) }
296```
297 
298---
299 
300## 5. Close legacy IDL accounts and re-publish [DEPLOY]
301 
302> **⚠️ Do this just before deploying the v1 binary.** Once a v1 binary is live, the legacy IDL instructions are gone — rent in those accounts becomes permanently inaccessible.
303 
304**Step 1 — close the legacy IDL account on every cluster:**
305 
306> This must be run with the **Anchor CLI v0.32** while the **v0.32 binary is still deployed**. The v1 CLI's `idl` commands target the Program Metadata program and cannot interact with legacy IDL accounts. Upgrading the CLI before closing means you lose the ability to recover that rent.
307 
308```bash
309# with anchor-cli 0.32.x still installed
310anchor idl close --provider.cluster devnet <PROGRAM_ID>
311anchor idl close --provider.cluster mainnet-beta <PROGRAM_ID>
312```
313 
314**Step 2** — deploy the v1 binary: `anchor deploy`.
315 
316**Step 3 — re-publish the IDL via Program Metadata.**
317 
318Two options — pick one:
319 
320**Option A: Anchor CLI** (resolved from workspace, no program ID needed):
321```bash
322anchor idl init --filepath target/idl/my_program.json      # first publish
323anchor idl upgrade --filepath target/idl/my_program.json   # subsequent updates
324```
325 
326**Option B: `program-metadata` CLI** (usable immediately after closing, independent of the Anchor CLI and deploy cycle):
327```bash
328npm install -g @solana-program/program-metadata
329program-metadata upload idl target/idl/my_program.json --program-id <PROGRAM_ID>
330```
331 
332Option B is useful when you want to push an updated IDL without going through a full `anchor deploy`, or when working outside an Anchor workspace. See the [program-metadata README](https://github.com/solana-program/program-metadata) for the full command reference and options.
333 
334**What changes in v1:** programs have no `idl_create_buffer`, `idl_write`, `idl_set_buffer` entrypoints. IDL lives in a Program Metadata account managed by a separate on-chain program. Already-deployed v0.32 programs that were not closed retain their legacy IDL account; v1 tooling can read them but cannot manage them.
335 
336---
337 
338## 6. Update `AccountInfo` usage [WARNING]
339 
340Using raw `AccountInfo<'info>` in `#[derive(Accounts)]` now emits a compile-time warning. These are warnings, not errors — migration can be incremental.
341 
342| Old | New |
343|-----|-----|
344| `AccountInfo<'info>` (unknown data) | `UncheckedAccount<'info>` + `/// CHECK:` comment |
345| `AccountInfo<'info>` (token account) | `InterfaceAccount<'info, TokenAccount>` |
346| `AccountInfo<'info>` (executable program) | `Program<'info, MyProgram>` or `Interface<'info, T>` |
347 
348### `UncheckedAccount::clone()` vs `.to_account_info()`
349 
350In anchor v1, `.clone()` on `UncheckedAccount<'info>` returns `UncheckedAccount<'info>`, not `AccountInfo<'info>`. Any function or CPI account struct that expects `AccountInfo<'info>` will now fail:
351 
352```rust
353// Error: mismatched types — expected AccountInfo<'_>, found UncheckedAccount<'_>
354let ctx_accounts = MyCpiAccounts {
355    some_account: ctx.accounts.some_unchecked.clone(),
356    ..
357};
358 
359// Fix: use .to_account_info() explicitly
360let ctx_accounts = MyCpiAccounts {
361    some_account: ctx.accounts.some_unchecked.to_account_info(),
362    ..
363};
364```
365 
366This commonly surfaces when constructing CPI account structs or calling helper functions that accept `AccountInfo<'info>` directly. Find occurrences:
367 
368```bash
369grep -rn "\.clone()" --include="*.rs" . | grep "UncheckedAccount\|merkle_tree\|tree_authority"
370```
371 
372---
373 
374## 7. Suppress `unexpected_cfgs` warnings from macros [WARNING]
375 
376Anchor and Solana derive macros emit code gated on cfg flags (`anchor-debug`, `custom-heap`, `custom-panic`) that Rust's `unexpected_cfgs` lint doesn't know about. This produces a wall of warnings after a clean build.
377 
378**Option A — declare them as features in each program's `[features]`** (more targeted, recommended):
379 
380```toml
381# programs/my_program/Cargo.toml
382[features]
383anchor-debug = []
384custom-heap = []
385custom-panic = []
386# keep your existing features — add these alongside them
387```
388 
389Declaring them as features tells Cargo they are valid cfg values, so the compiler stops warning about them without blanket-suppressing the entire `unexpected_cfgs` lint.
390 
391**Option B — suppress workspace-wide via lints** (blunter, but simpler for large workspaces):
392 
393```toml
394# Cargo.toml (workspace root)
395[workspace.lints.rust]
396unexpected_cfgs = { level = "allow" }
397```
398 
399Then opt every program crate into the workspace lints:
400 
401```toml
402# programs/my_program/Cargo.toml
403[lints]
404workspace = true
405```
406 
407> **Note on Option B:** Do not use the `check-cfg` list form (`check-cfg = ['cfg(anchor-debug)', ...]`) — cfg names containing hyphens are rejected by the compiler with `invalid '--check-cfg' argument`. Use `level = "allow"` without the list.
408 
409```bash
410# find all program Cargo.toml files that still need updating
411grep -rL "workspace = true" programs/*/Cargo.toml
412```
413 
414---
415 
416## 8. Handle IDL external account exclusion [IDL]
417 
418External account types (e.g. SPL Token `Mint`, `TokenAccount`) are no longer inlined in the generated IDL. Clients that relied on your IDL to deserialize third-party accounts must now use those programs' own clients.
419 
420```typescript
421// Before — type came from your program's IDL automatically
422const mintAccount = await program.account.mint.fetch(mintAddress);
423 
424// After — use the token program's own client
425import { getMint } from "@solana/spl-token";
426const mintAccount = await getMint(connection, mintAddress);
427```
428 
429---
430 
431## 9. Switch the test runner [CLI]
432 
433`anchor test` and `anchor localnet` now use **surfpool** by default.
434 
435```toml
436# Anchor.toml — opt out to standard validator
437[tooling]
438validator = "solana"
439 
440# Or configure surfpool
441[surfpool]
442startup_wait = 5000
443log_level = "info" # default is "none"
444block_production_mode = "clock"        # or "transaction"
445datasource_rpc_url = "https://api.mainnet-beta.solana.com"  # optional fork
446```
447 
448Add to `.gitignore`:
449```
450.surfpool/
451```
452 
453CI — surfpool must be installed explicitly:
454```yaml
455- name: Install surfpool
456  run: curl -sL https://run.surfpool.run/ | bash
457```
458 
459---
460 
461## 10. Remove external `solana` CLI dependency [CLI]
462 
463Anchor no longer shells out to `solana`. Update CI pipelines and scripts.
464 
465| Before | After |
466|--------|-------|
467| `solana address` | `anchor address` |
468| `solana balance` | `anchor balance` |
469| `solana airdrop` | `anchor airdrop` |
470| `solana program deploy` | `anchor deploy` |
471| `solana logs` | `anchor logs` |
472 
473Keep the `solana` CLI install step only if you use it directly (keypair generation, cluster switching, etc.).
474 
475---
476 
477## 11. Clean up `Anchor.toml` and removed CLI commands [CLI]
478 
479**Remove `[registry]` from `Anchor.toml`:**
480```toml
481# Before — remove this entire section
482[registry]
483url = "https://anchor.projectserum.com"
484```
485 
486**Remove `arch` build options from `Anchor.toml`** (if present — `arch = "sbf"` etc. are no longer recognised):
487```bash
488grep -n "arch" Anchor.toml
489```
490 
491**`anchor login` is removed.** Remove it from CI scripts and `Makefile` targets; the `[registry]` section it served is gone.
492 
493---
494 
495## 12. Disallow multiple `#[error_code]` blocks [COMPILE]
496 
497Having more than one `#[error_code]` block in a single program is now a compile-time error. Merge all error enums into one.
498 
499```rust
500// Before — two separate blocks compiled fine
501#[error_code]
502pub enum InitError {
503    AlreadyInitialized,
504}
505 
506#[error_code]
507pub enum UpdateError {
508    InvalidAmount,
509}
510 
511// After — single merged enum
512#[error_code]
513pub enum MyProgramError {
514    AlreadyInitialized,
515    InvalidAmount,
516}
517```
518 
519If you used `offset = N` to avoid code collisions between separate enums, that attribute continues to work on the merged single enum.
520 
521```bash
522grep -r "#\[error_code\]" --include="*.rs" .
523```
524 
525---
526 
527## 13. Update `Context` lifetime annotations [COMPILE]
528 
529`Context` was simplified from four lifetime parameters (`'a, 'b, 'c, 'info`) to one (`'info`). Most programs use `Context<MyAccounts>` without explicit lifetimes and are unaffected. If you annotated the lifetimes explicitly, remove the extra three.
530 
531```rust
532// Before (v0.32)
533pub fn my_handler<'a, 'b, 'c, 'info>(
534    ctx: Context<'a, 'b, 'c, 'info, MyAccounts<'info>>,
535) -> Result<()> { ... }
536 
537// After (v1)
538pub fn my_handler<'info>(ctx: Context<'info, MyAccounts<'info>>) -> Result<()> { ... }
539// or simply (when the lifetime is inferred)
540pub fn my_handler(ctx: Context<MyAccounts<'_>>) -> Result<()> { ... }
541```
542 
543```bash
544grep -rn "Context<'" --include="*.rs" .
545```
546 
547---
548 
549## 14. Update Borsh 1.x serialization usage [COMPILE]
550 
551Anchor v1 depends on **borsh 1.x**, which removed several APIs present in borsh 0.10.
552 
553### `try_to_vec()` removed
554 
555`BorshSerialize::try_to_vec()` no longer exists. Replace every call with `borsh::to_vec(&value)?`.
556 
557```rust
558// Before
559let data = my_struct.try_to_vec()?;
560let hash = hashv(&[metadata.try_to_vec()?.as_slice()]);
561 
562// After
563let data = borsh::to_vec(&my_struct)?;
564let hash = hashv(&[borsh::to_vec(metadata)?.as_slice()]);
565```
566 
567```bash
568grep -rn "try_to_vec" --include="*.rs" .
569```
570 
571### Enum explicit discriminants conflict with anchor derive macros
572 
573In borsh 1.x, enums with explicit integer discriminants require `#[borsh(use_discriminant=true)]`. However, this attribute conflicts with `#[derive(AnchorSerialize, AnchorDeserialize)]`, producing:
574 
575```
576error: multiple `borsh` attributes not allowed on a single item
577error: cannot find attribute `borsh` in this scope
578```
579 
580**Fix**: If the explicit discriminants match the default ordinal values (0, 1, 2, …), simply remove them. The serialized layout is identical.
581 
582```rust
583// Before — conflicts with anchor derive macros
584#[derive(AnchorSerialize, AnchorDeserialize)]
585pub enum MyType {
586    Variant1 = 0,
587    Variant2 = 1,
588}
589 
590// After — remove explicit discriminants; borsh ordinal encoding is the same
591#[derive(AnchorSerialize, AnchorDeserialize)]
592pub enum MyType {
593    Variant1,
594    Variant2,
595}
596```
597 
598If discriminant values *don't* match ordinal order (e.g., `Foo = 5, Bar = 10`) you must implement borsh serialization manually instead of relying on the derive macro.
599 
600```bash
601grep -rn " = [0-9]" --include="*.rs" programs/   # find enums with explicit discriminants
602```
603 
604---
605 
606## 15. Update Solana SDK 3.x API changes [COMPILE]
607 
608Anchor v1 uses **Solana SDK 3.x**, which has breaking API changes beyond just the version bump.
609 
610### `anchor_lang::solana_program` re-export gaps
611 
612In anchor v0.31, `anchor_lang::solana_program` re-exported the full `solana-program` crate. In v1 several sub-modules are no longer re-exported:
613 
614| Module | Old import | New import |
615|--------|-----------|------------|
616| `keccak` | `anchor_lang::solana_program::keccak` | `solana_program::keccak` |
617| `hash` | `anchor_lang::solana_program::hash` | `solana_program::hash` |
618| `ed25519_program` | `anchor_lang::solana_program::ed25519_program` | `solana_program::ed25519_program` |
619| `sysvar::instructions` | `anchor_lang::solana_program::sysvar::instructions` | `solana_program::sysvar::instructions` |
620| `instruction::Instruction` | `anchor_lang::solana_program::instruction::Instruction` | `solana_program::instruction::Instruction` |
621| `program::invoke_signed` | `anchor_lang::solana_program::program::invoke_signed` | `solana_program::program::invoke_signed` |
622 
623**`system_instruction` quirk:** `system_instruction` is *not* accessible as `solana_program::system_instruction` in SDK 3.x when you depend on `solana-program` directly — that sub-module was removed from the crate root. However, it is still re-exported by Anchor: `anchor_lang::solana_program::system_instruction` continues to work. Use that path rather than importing from `solana_program` directly.
624 
625```rust
626// Fails in SDK 3.x with direct solana-program dep
627use solana_program::system_instruction;
628 
629// Works — Anchor still re-exports it
630use anchor_lang::solana_program::system_instruction;
631```
632 
633**Fix**: Add `solana-program = { workspace = true }` to the program's `Cargo.toml` and import directly from `solana_program`.
634 
635```toml
636# program/Cargo.toml
637[dependencies]
638anchor-lang = { workspace = true }
639solana-program = { workspace = true }   # add this
640```
641 
642```rust
643// Before
644use anchor_lang::{prelude::*, solana_program::keccak};
645use anchor_lang::{prelude::*, solana_program::sysvar::instructions::ID as IX_ID};
646 
647// After
648use anchor_lang::prelude::*;
649use solana_program::keccak;
650use solana_program::sysvar::instructions::ID as IX_ID;
651```
652 
653```bash
654grep -rn "anchor_lang::solana_program" --include="*.rs" programs/
655```
656 
657### `AccountInfo::realloc` renamed to `resize`
658 
659The `realloc(new_len, zero_init)` method was renamed to `resize(new_len)` in Solana SDK 3.x. The `zero_init` parameter is gone (new space is always zeroed).
660 
661```rust
662// Before
663account_info.realloc(new_len, false)?;
664account_info.realloc(0, false).map_err(Into::into)
665 
666// After
667account_info.resize(new_len)?;
668account_info.resize(0).map_err(Into::into)
669```
670 
671```bash
672grep -rn "\.realloc(" --include="*.rs" .
673```
674 
675### `MAX_PERMITTED_DATA_INCREASE` path change
676 
677```rust
678// Before
679use solana_program::entrypoint::MAX_PERMITTED_DATA_INCREASE;
680// or
681use anchor_lang::solana_program::entrypoint::MAX_PERMITTED_DATA_INCREASE;
682 
683// After
684use solana_program::account_info::MAX_PERMITTED_DATA_INCREASE;
685```
686 
687### `CpiContext::new` takes `Pubkey`, not `AccountInfo`
688 
689In anchor v1, the first argument to `CpiContext::new` / `CpiContext::new_with_signer` changed from `AccountInfo` to `Pubkey`.
690 
691```rust
692// Before
693CpiContext::new(ctx.accounts.system_program.to_account_info(), cpi_accounts)
694CpiContext::new_with_signer(ctx.accounts.system_program.to_account_info(), cpi_accounts, signer_seeds)
695 
696// After — pass the program's Pubkey directly
697CpiContext::new(System::id(), cpi_accounts)
698CpiContext::new_with_signer(System::id(), cpi_accounts, signer_seeds)
699// or use the constant
700CpiContext::new(system_program::ID, cpi_accounts)
701CpiContext::new_with_signer(solana_program::system_program::ID, cpi_accounts, signer_seeds)
702```
703 
704---
705 
706## 16. Audit external program CPI crates [COMPILE]
707 
708Any external CPI crate compiled against **anchor 0.31** will produce dozens of trait-bound errors in your workspace because the `AccountDeserialize`, `AccountSerialize`, `Owner`, and `Id` traits changed in anchor v1. Common culprits: `bubblegum-cpi`, `account-compression-cpi`, `tuktuk-program`.
709 
710**Symptoms:**
711```
712error[E0277]: the trait bound `Noop: anchor_lang::Id` is not satisfied
713error[E0277]: the trait bound `SplAccountCompression: anchor_lang::Id` is not satisfied
714error[E0277]: `Program<'info, T>: anchor_lang::Id` not satisfied
715```
716 
717### Step 1 — identify affected crates
718 
719```bash
720cargo tree 2>&1 | grep -E "anchor-lang|anchor-spl" | sort -u
721```
722 
723Look for any dependency still pulling in `anchor-lang 0.x`. Each such crate needs to be updated before your workspace will compile.
724 
725### Step 2 — check for an updated release
726 
727For each affected crate, check whether the upstream maintainer has already published an anchor v1-compatible version:
728 
729```bash
730cargo search <crate-name>
731```
732 
733Or check the crate's repository for a release or branch targeting anchor v1. If a compatible version exists, bump the version specifier in `Cargo.toml` and you're done.
734 
735### Step 3 — update the crate yourself (if you own the repo)
736 
737If you control the affected crate in a separate repository, apply the same migration steps from this guide to that crate first (deps, CPI context, borsh, SDK API changes), publish or reference it via a git dep, then return here.
738 
739```toml
740# Temporary git dep while waiting for a crates.io release
741my-cpi-crate = { git = "https://github.com/my-org/my-cpi-crate", branch = "anchor-v1" }
742```
743 
744### Step 4 (last resort) — vendor the crate locally
745 
746If no update is available and you don't control the upstream repo, vendor a minimal local copy. Create a `vendor/` crate that uses `declare_program!` against the program's IDL JSON, add it as a workspace member, and point your workspace dependency to the path.
747 
748> **Do not use `[patch]`** for workspace members — cargo will see two versions of the same crate and report `multiple 'crate-name' packages in this workspace`. Use `path = ...` in `[workspace.dependencies]` instead.
749 
750Apply the standard anchor v1 fixes to any vendored source (realloc → resize, try_to_vec → borsh::to_vec, CpiContext::new, etc.) as you go.
751 
752---
753 
754## 17. Migrate `spl-token` / `spl-token-2022` / `spl-associated-token-account` direct dependencies [COMPILE]
755 
756`spl-token 7.x`, `spl-token-2022 7.x`, and `spl-associated-token-account 6.x` depend on `solana-program 2.x`. If your program has a direct `[dependencies]` entry for any of these crates, you'll see type mismatches because your workspace uses `solana-program 3.x`:
757 
758```
759error[E0308]: mismatched types
760  expected `Pubkey` (solana-program 3.x)
761     found `__Pubkey` (solana-program 2.x, re-exported via spl-token)
762```
763 
764This also affects any import path through these crates:
765```rust
766use spl_token::solana_program::instruction::Instruction;   // wrong Instruction type
767use spl_token::ID;                                         // wrong Pubkey type
768```
769 
770### Preferred fix — migrate to the interface crates
771 
772The interface crates (`spl-token-interface`, `spl-token-2022-interface`, `spl-associated-token-account-interface`) are slim, solana-program-3.x-compatible crates that expose the IDs, instruction builders, and account types you need without dragging in the old SDK version.
773 
774**If you depend on `spl-token`** → migrate to `spl-token-interface 2.0`:
775 
776```toml
777# Cargo.toml
778spl-token-interface = "2.0"   # replaces spl-token = "7.x"
779```
780 
781```rust
782// Before
783use spl_token::ID as TOKEN_PROGRAM_ID;
784use spl_token::instruction::transfer;
785 
786// After
787use spl_token_interface::ID as TOKEN_PROGRAM_ID;
788use spl_token_interface::instruction::transfer;
789```
790 
791**If you depend on `spl-token-2022`** → migrate to `spl-token-2022-interface 2.1`:
792 
793```toml
794# Cargo.toml
795spl-token-2022-interface = "2.1"   # replaces spl-token-2022 = "7.x"
796```
797 
798```rust
799// Before
800use spl_token_2022::ID as TOKEN_2022_PROGRAM_ID;
801 
802// After
803use spl_token_2022_interface::ID as TOKEN_2022_PROGRAM_ID;
804```
805 
806**If you depend on `spl-associated-token-account`** → migrate to `spl-associated-token-account-interface 2.0`:
807 
808```toml
809# Cargo.toml
810spl-associated-token-account-interface = "2.0"   # replaces spl-associated-token-account = "6.x"
811```
812 
813```rust
814// Before
815use spl_associated_token_account::ID as ATA_PROGRAM_ID;
816use spl_associated_token_account::get_associated_token_address;
817 
818// After
819use spl_associated_token_account_interface::ID as ATA_PROGRAM_ID;
820use spl_associated_token_account_interface::get_associated_token_address;
821```
822 
823### Fallback — use `anchor_spl` re-exports
824 
825If you only need program IDs, ATAs, or account structs and don't call instruction builders directly, `anchor_spl` re-exports compatible versions and requires no extra dependency entry:
826 
827```rust
828use anchor_spl::token::ID as TOKEN_PROGRAM_ID;
829use anchor_spl::token_2022::ID as TOKEN_2022_PROGRAM_ID;
830use anchor_spl::associated_token::ID as ATA_PROGRAM_ID;
831use anchor_spl::associated_token::get_associated_token_address;
832use solana_program::instruction::Instruction;  // not via spl_token
833```
834 
835```bash
836grep -rn "spl_token::\|spl_token_2022::\|spl_associated_token_account::" --include="*.rs" programs/
837grep -rn "spl-token\|spl-token-2022\|spl-associated-token-account" --include="Cargo.toml" programs/
838```
839 
840---
841 
842## What's New in v1
843 
844Worth adopting during migration:
845 
846- **`Migration<'info, From, To>`** — safe account schema migrations between layouts.
847- **`LazyAccount`** — heap-allocated read-only access, auto-optimized for unit-variant enums and empty arrays.
848- **Relaxed seeds syntax** — PDA seeds accept richer Rust expressions beyond literals and `.as_ref()`.
849- **`FnMut` event closures** — event listeners now accept `FnMut`, allowing mutable captures.
850- **Generic `Program<'info>`** — usable without a type parameter for executable-only validation when the concrete program type is not statically known: `pub program: Program<'info>`.
851- **`declare_program!` without `anchor_lang`** — `anchor_client` alone is now sufficient for client-side `declare_program!` usage; no need to pull in `anchor_lang` as a dependency.
852- **Owner re-checked on `.reload()`** — `account.reload()` now re-validates the account owner the same as initial load. Programs that previously reloaded accounts owned by a different program will now error.
853- **`common::close` accepts references** — no need to call `.to_account_info()` at every `common::close(...)` call site.
854- **`Owners` in prelude** — `anchor_lang::prelude::Owners` is re-exported; remove any manual `use` statement for it.
855- **Borsh 1.5.7** — both Rust and TypeScript Borsh implementations upgraded. Ensure your `borsh` entry in `Cargo.toml` is compatible.
856- **Lifecycle hooks** — add a `[hooks]` section to `Anchor.toml` to run shell commands at `pre_build`, `post_build`, `pre_test`, `post_test`, `pre_deploy`, `post_deploy`.
857