Pina

Pina is a high-performance Solana smart-contract framework built on top of pinocchio. The project focuses on low compute-unit usage, small dependency surface area, and strong account validation ergonomics for on-chain Rust programs.

This book is the single place for project documentation. It complements API reference docs by describing architecture, patterns, workflows, and quality standards used across the repository.

What you get in this book

• The project’s goals and trade-offs.
• Setup and day-to-day development workflow.
• A complete CLI reference, including automation-safe output contracts.
• Installation and operating guidance for the packaged Pina agent skill.
• Core framework concepts (#[account], #[instruction], #[derive(Accounts)], discriminator model, and validation chains).
• Architecture decision records for the project’s long-lived invariants and trade-offs.
• Codama IDL/client-generation workflow (including external-project invocation).
• Guidance for examples and security-focused development.
• A production-readiness gate for asset-bearing programs.
• CI/release pipeline expectations.

Project Goals

Pina’s codebase currently optimizes for the following goals.

1. Performance and low compute units

• Prefer pinocchio primitives over heavier Solana SDK surfaces.
• Minimize instruction overhead by using zero-copy layouts and typed discriminators.
• Keep runtime checks explicit but lightweight.

2. no_std-first smart contract ergonomics

• Keep crates deployable to Solana SBF targets.
• Avoid patterns that introduce allocator/runtime assumptions.
• Gate entrypoint-specific behavior behind features.

3. Safety for account handling and state transitions

• Strong discriminator and owner checks.
• Explicit validation chains for signer, writable, PDA seeds, and type.
• Defensive arithmetic and transfer operations.

4. Macro-powered developer experience

• Reduce boilerplate with #[account], #[instruction], #[event], #[error], and #[derive(Accounts)].
• Keep generated behavior predictable, documented, and tested.

5. Maintainability and release quality

• Reproducible dev environments (devenv + pinned tooling).
• CI coverage for linting, tests, and builds.
• Changelog-driven release discipline via changesets.

Getting Started

Build a program with the CLI

To write your own program you need the pina CLI and the external tools it drives, not this repository:

• rustup: the scaffold’s rust-toolchain.toml selects the pinned nightly.
• The Agave CLI, which provides cargo-build-sbf for pina build and solana for pina deploy.
• Node.js with npx when you generate TypeScript or Dart clients.
• The Surfpool CLI for pina dev; pina test embeds Surfpool’s SDK in the generated test package.

npm install --global @pina-rs/cli
pina init my_program
cd my_program
pina doctor               # checks every prerequisite above
pina keys new             # replace the shared placeholder program ID
pina migrations create --auto true  # track every contract; record the version-0 ABI baseline
pina build
pina test --unit
pina test
pina generate

Run pina keys new and pina migrations create --auto true before anything else. The migration policy lives in the manifest that command writes, not in pina.toml, so until it runs nothing is tracked and generated clients carry no version envelope; the baseline also records the program ID it belongs to. See the pina init reference for what the scaffold contains.

Work on Pina itself

Prerequisites

• Rust nightly toolchain from rust-toolchain.toml
• devenv (Nix-based environment)
• gh (for GitHub workflows)

Setup

devenv shell
install:all

See pina init --help for options like --path and --force. The CLI reference documents every command, output contract, and automation workflow.

For agent-assisted project work, install the Pina skill.

If pnpm-workspace.yaml sets useNodeVersion, devenv shell activates the matching pnpm-managed node/npm/npx/corepack toolchain automatically.

Build and test

cargo build --all-features
cargo test

For a deterministic Docker build suitable for Solana’s verified-build workflow, install solana-verify 0.5.1, start Docker, commit the complete source tree, and run:

pina build --verify

This produces the canonical deploy artifact plus a hash-bound Pina build record. It does not perform on-chain verification. See pina build for the trust model, prerequisites, and limitations.

Common quality checks

lint:clippy
lint:format
verify:docs

Generate a Codama IDL

pina idl --path ./examples/counter_program --output ./codama/idls/counter_program.json

See Codama Workflow for end-to-end generation and external-project usage.

Before adapting an example for a program that controls assets, work through the Production Readiness gate. Examples demonstrate scoped framework behavior; they are not audited deployment templates.

Build this documentation

docs:build

The generated site is written to docs/book/.

Pina CLI

The pina command scaffolds programs, extracts Codama IDLs, renders clients, reads bundled reference material, profiles compiled SBF binaries, and plans explicit deployments. It is designed for both interactive use and scripted or agent-driven discovery.

Install

Install the prebuilt npm package. It selects the native binary for the current operating system, CPU, and Linux C library:

npm install --global @pina-rs/cli
pina --version

Or install from crates.io with Rust:

cargo install pina_cli
pina --version

Inside this repository, enter the development shell and use the pina shortcut:

devenv shell
pina --help

The shortcut runs cargo run -p pina_cli -- ... against the checked-out source.

Command map

Discover the interface

The help tree is intentionally self-describing:

pina --help
pina build --help
pina verify --help
pina verify check --help
pina verify record --help
pina verify submit --help
pina verify status --help
pina generate --help
pina cpi --help
pina idl --help
pina docs --help
pina init --help
pina lint --help
pina locks --help
pina map --help
pina keys --help
pina doctor --help
pina explain --help
pina completions --help
pina profile --help
pina rehearse --help
pina deploy --help

Long help includes the input contract, output behavior, defaults, and copyable examples. Run pina docs with no topic to discover the bundled architecture references.

Streams and exit codes

Successful commands exit with code 0. Operational failures exit with code 1. Completed comparisons that find a difference exit with code 2: verification hash mismatches, profile compare regressions, and rehearse behaviour changes. rehearse exits with code 3 when it could compare no transaction. deploy --rehearse stops before sending anything with the same codes: 2 for behaviour changes, and 3 when nothing was compared or the program is not deployed yet. Invalid command-line syntax is rejected by Clap with a non-zero usage error before an operation begins.

For reliable automation, capture stdout only when the command documents it as machine-readable. See Automation and Agent Usage for a compact discovery protocol.

Path behavior

Relative paths are resolved from the process working directory. Project-aware commands discover the nearest pina.toml or unambiguous Cargo package and use Cargo metadata for the library source and target directory. Output commands create their documented output directories where applicable, but pina idl --output expects the parent directory to exist. Identity replacement requires pina keys new --force; profile reports are published atomically and cannot alias the input binary.

Environment

Project-aware commands read pina.toml and respect standard Cargo variables such as CARGO_TARGET_DIR and CARGO. The CLI also reads these Pina-specific optional environment variables:

No configuration file is required for an unambiguous Cargo package. pina init creates a small pina.toml so every tool and agent discovers the same program and client choices.

Agents that maintain Pina projects can install the companion @pina-rs/skill package.

pina init

Create a standalone Pina program scaffold.

Synopsis

pina init [OPTIONS] <NAME>

Example

pina init counter_program
pina init counter_program --path ./programs/counter_program

The command creates:

counter_program/
├── .cargo/
│   └── config.toml
├── src/
│   ├── entrypoint.rs
│   └── lib.rs
├── tests/
│   ├── integration.rs
│   └── surfpool/
│       ├── src/
│       │   └── lib.rs
│       └── Cargo.toml
├── .gitignore
├── build.rs
├── Cargo.toml
├── pina.toml
├── README.md
└── rust-toolchain.toml

The scaffold includes:

• a no_std program library and feature-gated SBF entrypoint;
• a typed instruction discriminator and starter instruction;
• an Accounts struct with signer validation;
• a cargo build-program alias for the Agave cargo build-sbf driver;
• a pinned nightly Rust toolchain with the rust-src and clippy components, matching the nightly Pina publishes prebuilt lint drivers for;
• the build.rs rerun directive, but no migration manifest yet, because the history binds to the program address and the migration policy lives only in that manifest;
• no source-installed lint tooling; pina lint resolves a prebuilt pina_lint_driver for the project’s active toolchain, and pina lint --build-driver compiles one when no prebuilt driver matches;
• host-side discriminator and program-ID smoke tests;
• a pina dependency with the account-resize, logs, and derive features (no Mollusk; add it when you need VM-level unit tests);
• a dedicated host-only test package with one pina_test dependency for the isolated Surfpool test;
• project-local discovery and client-generation settings in pina.toml.

Every scaffold starts with the same non-system placeholder address, which nobody holds the keypair for, so it can be neither deployed nor safely snapshotted; pina doctor warns while it is in place. Run pina keys new to give the program its own identity, then pina migrations create --auto true to track every contract and record the version-0 baseline. Until that run, nothing is tracked: the program builds and its clients generate without a version envelope, so record the baseline before you generate clients you intend to keep.

Versions are counted per contract, so the default u8 width gives each account, instruction, and event 255 versions. Add --version-type u16 (or u32) to that first run only if one contract may need more: the width can change while nothing is published, and freezes at the first deployment.

SBF builds use the Agave CLI’s cargo-build-sbf, so install the Agave CLI before the first pina build. Client generation for TypeScript and Dart needs Node.js with npx.

The scaffold declares no [workspace]. When the destination is inside an existing Cargo workspace, pina init prints the enclosing manifest: add the program to that workspace’s members, and declare the dependencies generated Rust clients inherit in its [workspace.dependencies].

Existing destinations

Without --force, Pina checks every scaffold-owned destination before writing anything. If one already exists, the command exits without modifying the scaffold.

--force overwrites only the known scaffold files listed above. It does not delete unrelated files in the destination directory, but it does rewrite src/lib.rs, including resetting declare_id! to the placeholder.

Next steps

The command prints the next steps for the generated package:

cd ./counter_program
pina keys new
pina migrations create --auto true  # track every contract; record version 0
pina lint
pina build
pina test --unit
pina test
pina dev --yes
pina generate

pina keys new writes the program keypair to target/deploy/<name>-keypair.json. The scaffold’s .gitignore excludes target/, and cargo clean deletes it, so back the keypair up before deploying.

Use pina init --help for the authoritative command-line surface.

See Project Configuration for every generated pina.toml field. The scaffold writes no [migrations] table: the policy belongs to the manifest pina migrations create writes.

pina lint

Run Pina’s official security lint set against the discovered program.

The lints live in the pina_lints crate, which is published to crates.io and statically compiled into the pina_lint_driver binary, a rustc wrapper. No external lint tooling is downloaded, no precompiled lint bundles exist, and the project itself never supplies or configures lint libraries.

Synopsis

pina lint [OPTIONS]

Examples

pina lint
pina lint --fix
pina lint --project ./programs/counter
pina lint --explain require_zeroed_before_close
pina lint --build-driver

pina lint discovers the nearest pina.toml or unambiguous Cargo package. It checks only that program package and does not lint workspace dependencies.

Toolchain negotiation

A lint driver links the compiler’s unstable rustc_private crates, so a driver only loads against the exact compiler revision it was built with. Two dated nightlies that share a release line expose incompatible compiler libraries, and nothing can make a driver built for one load against another. Pina therefore resolves a driver for whatever toolchain the project activates, instead of requiring one pinned nightly.

pina lint reads the active toolchain from rustc -vV and tries, in order:

1. PINA_LINT_DRIVER_PATH, the escape hatch for a driver you built yourself.
2. A driver already cached for this CLI release and this exact compiler revision.
3. The driver bundled next to the CLI, when it loads against the active toolchain.
4. A download from the Pina release matching this CLI version.

Asking a candidate driver to start is the version check. A driver built for another compiler cannot load librustc_driver, so a driver that starts is by construction the right one. That keeps the negotiation honest — it tests the property that actually matters instead of trusting a version string — and it means a driver built for a different nightly is skipped rather than producing an opaque loader failure deep inside cargo.

The cache lives below the platform’s per-user cache directory ($XDG_CACHE_HOME or ~/.cache on Linux, ~/Library/Caches on macOS, %LOCALAPPDATA% on Windows) under pina/lint-driver/<pina-version>/<host>-<commit-hash>/. Both the host triple and the full compiler commit hash are part of the path, so two nightlies installed side by side each keep their own driver and a cached driver is never reused for a compiler it was not built with. Set PINA_LINT_CACHE_DIR to relocate it.

A download is addressed by name: pina-lint-driver-<host>-<commit-hash>. Because a release builds its driver with the nightly that release pins, a project on any other nightly asks for a name the release does not publish and gets a clear miss. That is the correct outcome — no release can publish a driver for every nightly — and the CLI reports it with the remedy rather than handing cargo a binary it cannot load.

Building the driver

pina lint --build-driver

Use this on a nightly Pina publishes no prebuilt driver for. The build compiles the pina_lints release matching this CLI version, so the driver always runs exactly the lint set the CLI ships, and it compiles with your active toolchain. It requires the rustc-dev and rust-src components:

rustup component add rustc-dev rust-src

Cargo installs the driver into a staging root, the CLI copies it into the cache, and the staging root is removed. Later runs resolve the cached driver without invoking cargo, so the build cost is paid once per toolchain.

Diagnosing driver resolution

pina doctor
pina doctor --json

pina lint failing to find a driver is the one failure a user cannot debug from the message alone, so pina doctor reports the whole state: the active toolchain, the expected release, the resolved driver and how it was obtained, both search paths, and the one-line remedy. It reports without downloading, because a diagnostic that populates a cache cannot be run to find out what is wrong.

Every pina lint success line also names the driver that ran — (bundled), (cached), (downloaded), (built from source), or (PINA_LINT_DRIVER_PATH) — so a surprising result is traceable to the binary that produced it.

How lints run

pina lint runs cargo check — or cargo fix with --fix — with the resolved driver as RUSTC_WORKSPACE_WRAPPER. Cargo calls the driver with the arguments it would have passed to rustc; the driver registers every lint statically linked into it, and compilation continues normally with the lints emitted as ordinary compiler diagnostics. If RUSTC_WRAPPER already selects a compiler cache such as sccache, Cargo preserves it as the outer wrapper.

The CLI prepends the active sysroot’s library directory to the dynamic-library search path — DYLD_LIBRARY_PATH and LD_LIBRARY_PATH on macOS, LD_LIBRARY_PATH on other Unix, PATH on Windows — for the lint run, so the driver loads regardless of how the toolchain was installed. CARGO_TARGET_DIR continues to control normal project build artifacts.

To run a driver you built yourself — typically the workspace driver while developing a lint — set PINA_LINT_DRIVER_PATH to an executable binary path and pina lint uses it without further checks. The repository’s own security:pina-lint task uses this variable to run the workspace-built driver.

Driver environment variables

The driver reads a few environment variables:

pina lint sets PINA_LINT_NO_DEPS and forwards PINA_LINT_LEVELS from the project’s [lints] table. PINA_LINT_NO_DEPS, PINA_LINT_LEVELS, and PINA_LINT_ONLY are recorded in dep-info, so changing them invalidates cargo’s cached check results.

Configuring lint levels

Lint levels are configured in the project’s pina.toml under the [lints] table. Each entry maps a lint name to allow, warn, or deny; lints that are not listed keep their built-in default level.

[lints]
deny_heap_allocations_in_onchain_instruction_handlers = "deny"
require_explicit_discriminators_and_seed_namespaces = "allow"

Unknown lint names are rejected with the list of known lints. Deny-level security lints should not be disabled at crate scope; when a finding is a false positive, scope an #[allow(...)] to the smallest item and document the invariant.

Every lint’s contract, rationale, and sanctioned blessing pattern is in the Lint Reference, and pina lint --explain <LINT> prints one entry without leaving the terminal. Start there rather than guessing at an #[allow]: each entry names the API or restructure that satisfies the lint.

Fix mode

pina lint --fix
git diff

With --fix, pina lint runs cargo fix instead of cargo check. Pina supplies --allow-dirty, --allow-staged, and --allow-no-vcs because requesting --fix is explicit permission to edit the current working tree, including a newly initialized project that has not entered version control yet. Only diagnostics carrying machine-applicable suggestions can be changed automatically; findings without a safe rewrite remain diagnostics. Always inspect and test the resulting diff.

Security boundary

The lint driver is native executable code, not a passive rule file: it links against the compiler’s unstable internals and runs with the same local permissions as the invoking user. Pina therefore ships the driver prebuilt next to the CLI from the same attested release pipeline, never loads lint libraries from project metadata, and starts a candidate driver once before the lint run so a toolchain mismatch fails fast with a clear error. Every downloaded driver comes from the same release and the same assets that carry the CLI itself, so it is covered by the release’s build provenance attestation.

Downloads only ever come from Pina’s GitHub release for this CLI version. A project’s manifest cannot redirect the driver source, and no project metadata selects a lint library, so linting an untrusted repository does not execute code that repository chose. PINA_LINT_DRIVER_BASE_URL, PINA_LINT_DRIVER_REPO, and PINA_LINT_DRIVER_RELEASE exist for the release pipeline and the CLI’s own tests; treat setting them as equivalent to installing a driver yourself.

PINA_LINT_DRIVER_PATH executes whatever binary it names, so point it only at a driver you built yourself. pina lint --build-driver compiles from the matching pina_lints release on crates.io with your own toolchain.

Exit behavior

The command exits successfully only when a driver resolves for the active toolchain, it loads, compilation finishes, and all enabled security lints succeed. Without PINA_LINT_DRIVER_PATH the run negotiates a driver and additionally fails when none can be obtained; a diagnostic at an error level, a compilation failure, or an invalid PINA_LINT_DRIVER_PATH produces a non-zero exit in every mode. When no driver matches, cargo never runs, so a toolchain problem cannot be mistaken for a lint failure. Child Cargo output stays attached to the terminal; Pina prints a short completion summary naming the driver it used only after success.

pina locks

Report which instructions can never run in parallel, and the accounts that make them wait.

pina locks [OPTIONS]

pina locks
pina locks --project ./programs/privacy_pool
pina locks --json
pina locks --deny-hotspots

Why write locks matter

Solana’s scheduler runs two transactions in parallel only when neither one write-locks an account the other one locks. Every account a transaction marks writable is locked for the whole transaction, and every other transaction that touches that account waits.

Most accounts are chosen per user, so their locks rarely collide. A PDA whose seeds are all constants is different: it has the same address in every transaction. Every instruction that writes it takes the same lock, so all of that instruction’s traffic across the cluster runs one transaction at a time, however many users send it.

Pina knows this before the program is deployed. The IDL extractor records which accounts each instruction writes and which of them are PDAs, and pina locks reads that record without building or running the program.

Address classes

Every instruction account is grouped into an account node and given one of three classes:

A slot is a PDA when its processor validates or derives it as one, or loads it as a #[pda] account type, as Generate an IDL describes.

Reading the report

The text report starts with hotspots: fixed accounts that at least one instruction writes. Each lists its derived address and seeds, the instructions that write it, the instructions that only read it, and what that costs:

merkle_tree
  address  BLquaQVntisnQpUoLpzbcFGDN9eG9Qf12TZZS5KVLaLz
  seeds    "privacy-pool-tree"
  writers  initialize, deposit, transfer
  readers  withdraw
  Every `initialize`, `deposit`, and `transfer` in the cluster runs one at a time; `withdraw` waits for each one.

A program without hotspots says so.

Next comes the conflict matrix. Rows and columns are the instructions, numbered in declaration order. The diagonal tells you whether an instruction conflicts with other transactions of itself.

none is not a promise of parallelism. Accounts the caller chooses are never compared, because two transactions may or may not pass the same one, and nothing in the program decides that. A program with too many instructions for a readable matrix gets a per-instruction list instead.

To explore the same analysis interactively, with the accounts behind each conflict and each account’s derivation, run pina map.

Fixing a hotspot

A hotspot is a design decision, not a bug, but it is usually an accidental one. Common fixes:

• Shard the account. Add a variable seed, such as a shard index or the user’s address, so writers spread over many accounts. A global counter becomes per-shard counters that a reader sums.
• Split hot fields out. Move the fields every user writes into per-user or per-position accounts, and keep the global account for values that rarely change.
• Make readers read-only. An instruction that only reads a fixed account should take it as a read-only account. Two readers never conflict; a slot declared &mut AccountView is writable even when the handler never writes it.
• Keep the singleton and say so. An admin configuration written only by admin instructions is a fine hotspot. Accept it in pina.toml so CI stops flagging it.

Accepting a hotspot

List intentional hotspots by account name under [locks] in pina.toml:

[locks]
allow = ["program_config"]

Allowed hotspots are still reported, marked (allowed in pina.toml). Every name must be a current hotspot of the program: a name that matches none, from a typo or a hotspot that was since removed, fails the command with the list of hotspots it could have named, so the allow list cannot silently go stale.

CI gate

pina locks --deny-hotspots

--deny-hotspots prints the same report, then exits with code 1 when any hotspot is not allowed. Errors such as a missing project, unparseable source, or an unknown allow entry also exit with code 1 and print the error to stderr.

Agent JSON

pina locks --json > locks.json
jq -e '.hotspots | map(select(.allowed | not)) | length == 0' locks.json

JSON is the only stdout content. Schema version 1 is a camelCase document:

• schemaVersion, program, and programId;
• nodes: every account node with its id (pda:<name>, address:<base58>, or caller:<instruction>.<slot>), name, class (fixed, keyed, or caller), address (or null), pda (or null), and seeds, each {"kind": "constant", "hex", "text"} or {"kind": "variable", "name", "type"};
• instructions: each instruction’s writes and reads, every entry naming its node, slot, signer, and optional flags;
• conflicts: each conflicting pair as instructions (declaration order, the same name twice for a self-conflict), kind (always or may), and the nodes that decide it;
• hotspots: each fixed account some instruction writes, with its node, name, writers, readers, and allowed.

pina map

Render an interactive map of a program’s instructions and the accounts they lock.

pina map [OPTIONS]

pina map
open "$(pina map)"
pina map --project ./programs/privacy_pool
pina map --output ./docs/program-map.html
pina map --json

pina map reads the program source, runs the same analysis as pina locks, and writes one self-contained HTML file. The page inlines its styles, script, and data and makes no network requests, so it opens from disk, attaches to a pull request, or ships with documentation as is.

The file goes to <target>/pina/map.html under the project’s Cargo target directory unless --output names another path; missing parent directories are created. stdout carries only the written path, so open "$(pina map)" (or xdg-open) opens it in one step. Progress goes to stderr.

What the page shows

The page is drawn as an interlocking chart, the table a railway signal box uses to show which levers lock each other. Here the levers are accounts and the rows are instructions.

• Header: the program name, its program ID with a copy button, and counts of instructions, accounts, PDAs, and hotspots.
• Hotspots: one plate per fixed account that some instruction writes, with the cost in one sentence, for example “Every deposit and transfer in the cluster runs one at a time”. Select a plate to open the account.
• Lock chart: rows are instructions in declaration order and columns are the accounts shared between instructions, hotspots first, then other fixed accounts, then keyed PDAs. A filled square is a write, an outlined square a read, a blue dot a signer, and a dashed square an account the caller may omit. A column’s top band gives its class: red for a hotspot, ink for another fixed account, blue for a keyed PDA. The last column counts each instruction’s caller-chosen accounts, which are never shared.
• Tracing: hover or focus a row and every row it conflicts with lights up, red when they can never run in parallel and amber hatching when they collide only for the same seeds; the accounts behind each conflict are outlined and everything else fades. Selecting a column lights up the rows that lock that account instead.
• Detail panel: selecting an instruction shows its docs, the instructions it never runs alongside or may wait for (with the accounts responsible), every account slot with its flags, PDA, and declarative constraints, and its arguments. Selecting an account shows its class, its account type’s docs and fields, the hotspot cost, the PDA derivation from constant seeds and typed seed slots to the derived address, and the instructions that write and read it.

The chart is keyboard accessible: rows and columns are buttons, the arrow keys move between rows (up and down) and between columns (left and right), Home and End jump to the ends, and Enter selects. It follows the system’s light or dark preference, honors reduced motion, and on a narrow screen scrolls the chart inside its frame rather than the page.

Trust boundary

Doc comments and seed strings come from the program source. The page embeds its data as JSON in a <script type="application/json"> block with <, >, &, U+2028, and U+2029 escaped, so no string can end the block, and it renders every string as text, never as markup.

Agent JSON

pina map --json > map.json
jq -e '.instructionDetails | length > 0' map.json

--json prints the map’s data instead of writing HTML, and conflicts with --output. The document is the pina locks --json schema-version-1 document with two more top-level fields:

• instructionDetails: each instruction’s name, docs, arguments (name, type, docs), and accounts in slot order, each with its slot, node, writable, signer, optional, pda, constraints, and docs;
• accountTypes: each #[account] type’s name, the pda it declares (or null), docs, and fields.

Errors such as a missing project, unparseable source, or an unwritable output path exit with code 1; an invalid flag combination exits with code 2.

pina build

Build the current Pina program for SBF and refresh its Codama IDL.

Synopsis

pina build [OPTIONS]

bpf-entrypoint is always enabled and deduplicated from explicit features.

SBF compilation delegates to the Agave CLI’s cargo-build-sbf driver, which owns the SBF toolchain (its own rustc and sbf-linker from platform-tools). The Agave CLI must therefore be installed and on PATH; a nightly toolchain with rust-src is no longer required.

Outputs

Pina uses Cargo metadata, including CARGO_TARGET_DIR, to derive stable output paths:

<cargo-target>/deploy/<library-name>.so
<cargo-target>/idl/<library-name>.json

The library target name is authoritative. It may differ from the package name when [lib].name is set.

Cargo output is streamed to the terminal. Pina stages both outputs first and atomically replaces each destination file. A project-scoped advisory lock prevents concurrent builds from interleaving different IDL and SBF versions. If the second replacement fails, Pina attempts to restore the previous IDL. A failed Cargo build does not publish either output; the two separate files do not form a crash-atomic filesystem transaction.

pina build
pina build --features logs --no-default-features
pina build --project ./programs/counter

Deterministic verified-build artifacts

pina build --verify switches the SBF compiler backend to solana-verify. It does not query a cluster, compare an on-chain program, upload verification metadata, or install any tools.

Prerequisites:

• solana-verify must report exactly version 0.5.1.

• Docker must be installed and running. Solana Verify owns Docker discovery and diagnostics.

• The project must be in a completely clean Git worktree. Staged, unstaged, and untracked files all cause the command to fail.

• The Cargo workspace root reported by Cargo metadata must contain a tracked Cargo.lock.

• Pinocchio and modular Solana SDK workspaces should declare the Solana CLI version at the workspace root so Solana Verify can select a pinned build image:

  [workspace.metadata.cli]
  solana = "3.0.0"
  

Pina copies only files tracked in the Git index into a private snapshot. Ignored files—including .env, keypairs, node_modules, .devenv, and ordinary build output—are not mounted into the container. Tracked symbolic links are rejected instead of followed. Git submodules are not supported in this first version; vendor or replace those inputs with tracked workspace dependencies.

cargo install solana-verify --version 0.5.1 --locked
docker version
pina build --verify

The deterministic build publishes the same canonical deployment paths as an ordinary build:

<cargo-target>/deploy/<library-name>.so
<cargo-target>/idl/<library-name>.json

It also retains a content-addressed copy and a Pina-local build record:

<cargo-target>/pina/verifiable/<library-name>-<executable-hash>.so
<cargo-target>/pina/verifiable/<library-name>-<executable-hash>.json

The executable hash follows Solana Verify semantics: trailing zero padding is removed before SHA-256. The JSON records only facts Pina can compute: the exact Solana Verify version, library and relative workspace paths, Cargo features, default-feature selection, lockfile hash, Git revision, repository URL when it is credential-free HTTPS, and source-state diagnostics. It is not an official on-chain verification record. Consumers must recompute the executable hash before trusting it, and publication workflows must independently confirm that the recorded revision is reachable from the public remote.

Pina atomically replaces each destination file. The content-addressed artifact and build record are written before the canonical artifact and IDL. These separate files do not form a single crash-atomic filesystem transaction; a failed final publication can leave a valid, hash-bound content-addressed record without updating the canonical deploy path.

Feature selection is identical for both backends:

pina build --verify --features logs --no-default-features

Pina forwards only its validated feature selection to Solana Verify. It intentionally offers no raw Cargo, Docker, image, or shell-argument passthrough.

A verified build does not apply the size profile. Solana Verify rebuilds from the recorded Git revision, so the inputs that shape the artifact have to live in the committed source; an override supplied only through environment variables or CLI flags is invisible to anyone reproducing that revision, which would make the verified hash unreproducible. Declare the profile under [profile.release] in the workspace manifest — the layout pina init generates — so both backends compile identically. When a requested size profile would make the two artifacts differ, pina build --verify warns and names the missing setting.

Solana Verify 0.5.1 is supported on Linux and macOS when a compatible executable and Docker runtime are available. Native Windows and FreeBSD execution fail before source staging; use a supported Linux environment instead.

Project discovery uses the nearest ancestor pina.toml. Existing projects without that file fall back to Cargo metadata; an ambiguous workspace root fails with the candidate package names instead of guessing.

See Project Configuration for the complete pina.toml schema and path rules.

Manage ABI migrations

Migration support is opt-in. Add migrations to each account, instruction payload, or event that Pina must track:

#![allow(unused)]
fn main() {
#[account(discriminator = AccountType::Profile, migrations)]
pub struct Profile {
	pub authority: Address,
	pub score: u64,
}
}

Pina inserts the version after the existing discriminator. Version 0 is the first captured shape. The source code never declares a version number, and the version field is one u8 byte unless the manifest records a wider width; see Choose the version width.

Each kind uses the version differently. An account migrates on-chain, one adjacent transition at a time. An instruction with migrations has an older payload converted to the current layout before its handler runs. An event is versioned but never converted: the program emits only the current version, and generated clients decode each historical version with its own schema. How a migration flows compares the three.

Opt whole kinds in

A program that wants every contract versioned can opt in by kind instead of annotating each declaration:

pina migrations create --auto true # or --auto accounts,events,instructions

--auto accepts true (or all) for every kind, false (or none) to clear the policy, or a comma-separated list of accounts, events, and instructions; any other name, or a name listed twice, is rejected. The policy envelopes accounts and events. It records instructions as snapshots without an envelope, so covering them does not change a payload byte; see Instructions without an envelope.

pina migrations create records the policy as auto in migrations/manifest.json and snapshots every contract of the listed kinds. A later run without --auto keeps the recorded policy, and a first run without it records no policy. The manifest is the only home of the policy and the single source of truth for macros: pina.toml holds no copy, because a proc macro does not re-expand when an unrelated toml file changes and a second copy could disagree with the first. The retired [migrations].auto and [migrations].version_type keys fail every command that reads pina.toml with an error naming the flag that replaces them. A struct that is not yet snapshotted still fails the build with the existing “run pina migrations create” error, so the workflow is unchanged.

Because the policy lives in the manifest, flipping it re-expands every contract without a source edit. When a policy is recorded, create scaffolds a build.rs containing:

fn main() {
	println!("cargo:rerun-if-changed=migrations/manifest.json");
}

The scaffold is idempotent and never overwrites an existing hand-written build script; create prints the exact line to add instead, and pina migrations check fails until it is present.

Per-item migrations = false keeps one contract out of an auto policy. Removing the envelope from a contract the manifest already records is an error rather than a silent opt-out: stripping an envelope is a wire-format change, so the build fails with the contract identity and the required remedy, and create refuses it with EnvelopeRemoval. The one exception is an unpublished instruction, which create may turn back into a snapshot. Dropping an enveloped kind with --auto is rejected the same way. A hand edit of the manifest’s auto cannot strip an envelope either: a declaration without a migrations token that the recorded policy no longer covers, but that the manifest records with an envelope, fails the build. Enabling auto on an already-launched program inserts an envelope into every account and event of the listed kinds — one recorded history entry per contract through create, behind --envelope-ack — while a new program simply captures that baseline.

Instructions without an envelope

An instruction covered by auto without the migrations token keeps its [discriminator][payload] wire format. The manifest records exactly one version of it with "envelope": false:

{
	"contracts": {
		"instruction:1:00": {
			"rustName": "InitializeInstruction",
			"envelope": false,
			"versions": [
				{
					"schema": {
						"layout": "fixed",
						"fields": [{ "name": "bump", "rustType": "u8" }]
					},
					"process": {
						"accounts": [
							{
								"name": "authority",
								"writable": true,
								"signer": true
							}
						]
					}
				}
			]
		}
	}
}

A process slot records only what sets it apart: writable, signer, and optional are written only when true, and defaultValue and pda only when set. A reader treats an absent field as false or none.

The snapshot stops wire-breaking changes rather than recording them:

• The #[instruction] macro fails the build when the struct drifts from the snapshot.
• While nothing is published, create replaces the snapshot.
• After publication, a payload change fails with PublishedPayloadChanged: declare a new discriminator, or restore the published fields.
• Appending optional accounts to a published snapshot extends it in place and consumes no version.
• A published snapshot cannot gain an envelope (EnvelopeAddition); declare a new discriminator for the migration-aware instruction.
• When an instruction stops asking to be recorded (migrations = false, or an auto policy that no longer covers instructions), check fails with StaleSnapshot and create releases the snapshot. Nothing on the wire changes.

#[instruction(discriminator = X, migrations)] opts one instruction into full migrations: a version envelope, adjacent transitions under migrations/transitions/instruction_<width>_<hex>/, and a generated dispatcher that normalizes a historical payload before the handler runs. Before publication, removing the token and running create turns it back into a snapshot; after publication it fails with EnvelopeRemoval. The macro reports the same situation at build time: “removing an envelope is a wire-format change that pina migrations create must record deliberately”. A program whose instructions were recorded under ABI 0.20 has them enveloped, and must add migrations to keep a published instruction’s wire format; see Upgrading from ABI 0.20.

Choose the version width

The width of the version field is program-wide, recorded as versionType in migrations/manifest.json, and u8 by default. Versions are counted per contract, so u8 gives every account, instruction, and event its own 255-version budget. Record a wider width only when one contract may need more:

pina migrations create --auto true --version-type u16

--version-type accepts u8, u16, or u32; there is no u64. A later run without the flag keeps the recorded width. While nothing is published (no receipt and no pending deployment), the flag rewrites the width in place and create prints the change; every history is still a single draft, so nothing else in the manifest moves. Rebuild and regenerate clients afterwards so they write the wider field. Once a deployment publishes, the width is frozen and the flag fails: “Migration version encoding is frozen as u8 because a deployment published it, so it cannot become u16”.

Capture a draft

Run the migration generator after the source ABI changes:

pina migrations create
pina migrations status

Pina writes migrations/manifest.json, migrations/publications.json, and adjacent transition files under migrations/transitions/.

If the current version has never been deployed to a non-local cluster, create replaces that draft. If a publication receipt or pending deployment contains the version, create appends the next version. A changed event appends a version with no transition file. A published instruction whose payload is unchanged but whose account list gained appended optional slots is extended in place instead (Appended optional accounts to instruction:1:00@0), and a published snapshot-only instruction cannot change its payload at all.

When a transition grows an account, create prints the estimated rent deficit (about 6,960 lamports per grown byte), names the program constant to raise (max_lamports, for example MAX_INLINE_MIGRATION_LAMPORTS), and points at the on-chain error an undersized budget produces: MigrationLamportBudgetExceeded. Cumulative worst-case growth across the supported stale ladder — every version a stale account may still hold within MAX_INLINE_STEPS, not only the adjacent hop — beyond the runtime’s 10,240-byte (MAX_PERMITTED_DATA_INCREASE) per-instruction realloc cap warns separately, because no budget raises that limit; it points at MigrationAccountGrowthExceeded. Both warnings quote the same numbers as the PinaProgramError rustdoc, so the pre-deploy estimate and a failed transaction name the same fix.

Commit the manifest, publication ledger, and transition files. Do not generate them during a build.

Preview deployment costs

pina migrations status ends with a cost preview derived from the checked-in history and, when the compiled SBF artifact exists, from pina profile’s static per-function estimates. It reports:

• per account contract: current size, the bytes a version-0 (day-one) account grows, and the approximate rent deficit at the same 6,960-lamports-per-grown-byte convention the create warning uses;
• per instruction process: the worst-case adjacent-step ladder a stale account the process names can trigger, with the step count, the rent that ladder funds, and a static CU estimate;
• one program-wide summary that sizes both budgets deliberately: the touching transaction funding the most rent (max_lamports) and, independently, the longest worst-case ladder (MAX_INLINE_STEPS) — each names its instruction, because they need not be the same one.

The preview prints the ladder model and the CU model so the numbers stay interpretable. When the history has more than eight transitions, the quoted ladder starts partway up and a note explains that a version-0 account instead fails with MigrationUnavailable; the day-one growth figure still counts every pending byte.

Two models keep the numbers interpretable. Rent reuses RENT_EXEMPT_LAMPORTS_PER_BYTE from the create warning, and the CU estimate sums pina profile’s static estimates for the generated adjacent migrate functions, so it excludes executor overhead (resize, rent transfer, validation) and runtime branch or loop effects. An artifact that has not been built, cannot be parsed, or lacks a transition function makes the CU figure print an explicit CU unavailable: ... reason instead of a zero.

Instruction processes link to account contracts by account-slot name, and only a writable, non-signer slot can hold an account the executor migrates. A writable, non-signer slot that names no checked-in account contract produces an explicit note instead of silently costing nothing — the symptom of a renamed account or a slot typo. Read-only and signer slots (authorities, payers, programs) can never be migrated, so they are skipped without noise.

--json emits the status array unchanged under statuses plus the additive cost section:

{
	"statuses": [
		{
			"identity": "account:1:01",
			"kind": "account",
			"rustName": "State",
			"envelope": true,
			"currentVersion": 2
		}
	],
	"costPreview": {
		"rentLamportsPerByte": 6960,
		"maxInlineSteps": 8,
		"ladderModel": "the oldest version within MAX_INLINE_STEPS (8) of the current version, ...",
		"cuModel": "sum of `pina profile` static estimates for the generated adjacent `migrate` functions, ...",
		"artifact": "target/deploy/my_program.so",
		"contracts": [
			{
				"identity": "account:1:01",
				"currentSizeBytes": 44,
				"dayOneGrowthBytes": 2,
				"dayOneRentDeficitLamports": 13920
			}
		],
		"instructions": [
			{
				"identity": "instruction:1:00",
				"totalSteps": 2,
				"totalRentDeficitLamports": 13920
			}
		],
		"mostExpensive": {
			"status": "identified",
			"instructionRustName": "UpdateInstruction",
			"steps": 2,
			"rentDeficitLamports": 13920
		}
	}
}

A figure that cannot be estimated serializes as { "status": "unavailable", "reason": "..." }; pina migrations check --json still emits only the status array.

Disambiguate renames

A field that disappears while another field of the same type appears is ambiguous (types are compared on the wire, so PodU64 and u64 count as the same type): a rename preserves the stored bytes, a remove-plus-add discards them and starts the new field zeroed. pina migrations create refuses to guess:

• On a terminal it prompts field by field and records the answer.
• With --no-interactive, or when no terminal is attached, it fails with one line per question naming the exact flags that answer it:

pina migrations create --rename score:points        # preserve the renamed data
pina migrations create --assume-removed score       # discard it; `points` starts zeroed

--json emits the open questions as a machine-readable array so agents can parse, decide, and re-run. With --json, --no-interactive, or no terminal attached, an unanswered question is a hard failure with a defined contract: the question array prints on stdout, the human-readable error prints on stderr, and the exit status is 1; capture both streams and re-invoke with the flags each question names. Answered renames are recorded in the manifest transition, so repeated create runs never re-ask, the generated transition copies the field’s bytes, and --assume-removed prints a data-loss warning. Type changes and unpaired removals always fall back to a manual transition with a TODO body; nothing is dropped silently.

A third answer hands one field’s conversion to you. --manual <field> names an added field and makes the whole transition manual, so the generated file is a stub you complete instead of a byte move Pina chose:

# Combine `first_name` and `last_name` into `name` yourself.
pina migrations create --rename first_name:name --assume-removed last_name --manual name

--manual is also the way to make a rename whose type changed legal: a generated rename copies bytes verbatim and so requires the same wire type, while --manual records that you own the interpretation. The answer is recorded, so repeated create runs keep generating the manual draft rather than re-deriving an automatic transition over your body.

Answers that contradict each other fail closed rather than picking a winner, whichever source they came from: a field cannot be both renamed and discarded, and a manual conversion cannot also discard the stored bytes it reads.

Resolve a manual transition

Pina generates automatic transitions only for direction-safe fixed-layout changes: copies, insertions and removals that shift later fields, and zero-filled additions. An instruction argument is never zero-filled, because the handler could not tell that default from a value a client sent, so an instruction transition that adds an argument is always manual. A type change (including a widening such as u64 to u128, but not a respelling that stores the same bytes), a reorder of existing fields, a compact layout, an ambiguous field move, or a --manual answer creates a manual Rust file with TODO(pina-manual-migration). --manual <field> also converts a draft that create already recorded as automatic.

A finished body belongs to the two layouts it was written for. While the draft’s destination schema is unchanged, create keeps it. If you change the draft’s layout again, create moves the finished body to vN_to_vM.rs.stale, writes a new stub whose header prints the new offsets, and says so. The new stub’s marker blocks the build until you port the old body; delete the .stale file once you have. This keeps an old body from compiling against a layout it was not written for and silently misplacing bytes.

Every generated transition reads its byte offsets from the stored schema. A removed field keeps occupying its bytes, so a transition that drops a field in the middle of a layout still reads the fields after it from their original offsets — and its SOURCE_SIZE counts the bytes that are actually on the account.

Replace the generated body. Pina preflights the exact historical shape for every account. Fixed transitions have generated size constants and their generated migrate stub starts with a length guard; keep it. A transition involving compact data also has target_size and working_size functions. They inspect already-validated historical bytes and must return a valid destination allocation without mutating the account. The migrate function is then total for that accepted source and must fully initialize every active destination byte.

A manual account transition cannot reject a value it cannot interpret: by the time migrate runs, rent funding and resizing may already have taken effect, so a migrate that cannot produce a valid destination aborts the whole instruction instead of returning a catchable error. Validate unambiguous value constraints inside target_size and working_size (they run before any mutation) and reserve genuinely rejectable conversions for instruction transitions, which run in scratch space before any account is touched.

Pina runs adjacent account transitions one at a time inside one invocation. It validates and commits each intermediate version before planning the next, which lets a later compact allocation depend on the prior compact result without allocating a copy of the account on the SBF stack. If any later step fails, Pina aborts the instruction so Solana rolls back all earlier resizes, lamport transfers, and byte writes. A manual instruction conversion instead runs in scratch space and may reject invalid semantic values before dispatch. Then run:

pina migrations check
pina test --compatibility

check rejects a remaining marker. Once publication is pending or complete, it also rejects any change to the transition file or either schema hash. Fix frozen transition code with another migration version.

IDL generation runs the same check. The current IDL keeps each enveloped account, instruction, or event’s migrationVersion field in place with defaultValueStrategy: "omitted" and its default value: generated client inputs omit it, encoders stamp the current value into the envelope automatically, and decoders reject any other version. A snapshot-only instruction has no migrationVersion field. Each earlier version of an event is listed as its own event node, <Event>V<n>, so clients can decode old log records; historical account and instruction schemas and all transition code remain exclusively in migrations/manifest.json. The IDL follows the recorded policy, the same one the macros expand against. Without a manifest there is no policy, so neither the program nor the IDL carries an envelope, and a declaration with an explicit migrations token fails until create records it.

Change an instruction process

Trailing optional accounts may be omitted entirely from the end of an account list; every earlier slot must still be present, using the program address as a filler where a middle optional account is absent. Omitting a middle optional account without a filler shifts every later account into an earlier slot, which only surfaces as a confusing missing-account error or a privilege check failure. Treat a trailing Option account as fully untrusted: it can be absent from any request, not only from old ones.

Pina snapshots the instruction payload and its positional account list under the same instruction version. Appending optional accounts to a published version extends its recorded account list in place: no version is consumed and no transition is written. An old request remains compatible only when:

• each existing account slot is unchanged;
• existing slots keep the same order;
• every new slot is appended at the end; and
• every appended slot is optional.

A slot’s wire facts are its name, signer flag, writable flag, and optionality, and a change to any of them is breaking. Create a new instruction discriminator for a breaking process. A slot also records two client hints, its known address (defaultValue) and its PDA (pda), which say what generated clients fill in. A client that passes the address itself sends the same account list, so hints are never compared: a hint-only change is not drift, consumes no version, and leaves the recorded snapshot as it is until a wire change replaces it (ADR 0012). Declarative constraints are program semantics and are not recorded at all.

The runtime treats an omitted optional suffix as absent. It never creates an account, signature, writable privilege, or PDA for an old client.

Respell a type

A drift check compares what a field stores, not how its type is spelled. Spellings that store the same bytes under the same reading are one schema: the PodU16, PodI16, PodU32, PodI32, PodU64, PodI64, PodU128, PodI128, and PodBool wrappers and their native names, Address and [u8; 32], PodString<N> (or PodString<N, 1>) and String<N>, and PodVec<T, N> (or PodVec<T, N, 2>) and Vec<T, N>, recursively through arrays, Option, and vectors. Respelling PodU64 as u64 therefore consumes no version and fails no build, and a real change next to a respelling still gets an automatic byte copy for the respelled field. The recorded spelling and every pinned hash stay as they were.

Types that only share a width are different schemas: u64 to i64, u32 to f32, or u8 to bool reinterprets a live value, so each needs a manual transition.

Decode historical events

Events are immutable, so Pina versions them instead of migrating them. The program emits only the current version, and nothing converts an older record. Changing a published event’s schema appends a version with its own schema and no transition file.

Generated clients decode each version with its own schema. The IDL lists every earlier version as a separate event node named <Event>V<n> (for example ValueChangedEventV0) next to the current event. The program-level log parser (parse<Program>EventsFromLogs in TypeScript and Dart) routes each record by discriminator and version and throws on a version no generated event describes, for example event "valueChangedEvent" log carries migration version 2, which this client cannot decode; regenerate it. In Rust, each event’s try_from_bytes separates a stale record from a future one and names the event to decode it with. A decoded record holds exactly the fields its version emitted; no field is zero-filled. Keep golden log bytes in pina_test::HistoricalEvent and decode them with the generated event for their version rather than encoding fixtures with the current event type.

Publish a version

Use pina deploy for a persistent cluster. Before the remote command starts, Pina atomically records the cluster, RPC target, executable digest, and the pinned history of every contract it ships as pending. A pending version is frozen because it may already be live. After deployment succeeds, Pina rechecks the planned files and appends that record to migrations/publications.json as a receipt:

{
	"abiVersion": "0.21",
	"receipts": [
		{
			"rpcUrl": "https://api.devnet.solana.com",
			"executableSha256": "…",
			"versions": {
				"account:1:01": [
					{ "schemaSha256": "…" },
					{ "schemaSha256": "…", "transitionSha256": "…" }
				]
			}
		}
	]
}

Each contract maps to the list of its pins: entry n pins version n with its schema hash and, when it has one, the hash of the transition that enters it. The highest version a receipt made live is the position of its last pin, and every receipt pins every version it made live, so rewriting published history — even with consistently recomputed hashes — fails every later check. A receipt names no program: the ledger belongs to the manifest beside it, whose programId is the only copy. Receipts are appended in deployment order, and version control is what keeps the file append-only; a hash chain over the receipts could be recomputed by anyone able to edit them, so none is stored.

Local deployments do not publish versions unless you pass --record-publication. A published version is immutable even if a later deployment replaces it.

If the deploy program cannot even start, for example because solana is not on PATH, nothing can have reached the cluster, so Pina discards the pending record it just wrote and your drafts stay editable. A pending record that an earlier attempt left behind is never discarded this way.

If deployment or receipt recording fails, stop the release. The pending record remains, and pina migrations status reports publication pending. Restore the exact planned inputs and rerun the same deployment to reconcile it; Pina rejects a different deployment while the outcome is ambiguous. The current ledger does not prove the deployed program-data hash, genesis hash, slot, or transaction signature.

When the exact planned inputs cannot be reproduced (for example a cleaned build directory), inspect the pending deployment with pina migrations reconcile. It prints the cluster, RPC endpoint, program, and executable digest that must be resumed. Once you are certain the deployment never went live, pina migrations reconcile --abandon converts the pending record into an abandoned receipt that still freezes its pinned versions and unblocks the next deployment. Losing migrations/publications.json entirely fails every later check while the manifest still records advanced versions, because published history must stay pinned; restore the ledger from version control instead of regenerating it.

A contract entry with no pins is invalid, and every command refuses the ledger (“pins no versions”), because such an entry cannot tell a rewritten published schema from the one that shipped; restore the file from version control rather than blanking a history. An ABI 0.20 ledger could name a published version without pinning it, and reading one fails with an error naming pina migrations reconcile --pin-legacy. After confirming from version control that migrations/manifest.json still records exactly what those receipts shipped, run that command once: it pins every such entry from the manifest (trust on first use), writes the ledger in the current shape, and leaves you to commit it. A 0.21 ledger has nothing to pin.

The manifest records the program ID its history belongs to. Before anything is published, pina migrations create rebinds the history to a changed declare_id! (for example after pina keys new) and says so. After publication, a different declare_id! fails every command until the original is restored.

ABI document upgrades

abiVersion belongs to Pina’s migration document. It is independent of each account or instruction version, and it names the pina_abi release line that wrote the document: the value is the major.minor committed in crates/pina_abi/ABI_VERSION, which advances with a breaking pina_abi release and with nothing else.

Reads reject a document stamped above the running build, naming the supported version, and reject one below the oldest supported version with the remedy that regenerates it. Anything between is normalized through an ordered table of adjacent converters before the typed model is read, so a document an older release wrote still opens. Conversions run in memory only: no command rewrites a checked-in document as a side effect of reading it.

The 0.20 reset replaced the integer formatVersion counters, and documents from older releases must be converted once before any Pina command can read them — create and sync included. Migrate to the reset ABI document walks the conversion for both deployed and not-yet-deployed programs.

ABI 0.21 stores each fact once: the contract key kind:width:hex is the identity, the wire codec is implied by abiVersion, a version without a transition omits the key, and a process slot omits every field left at its default. It also added "envelope": false for instructions recorded without an envelope and removed event transitions. The publication ledger keeps only what nothing else records: a receipt is its rpcUrl, executableSha256, pinned versions, and abandoned flag. A 0.20 document is converted in memory and rewritten by the next create; Upgrading from ABI 0.20 lists the source changes that can follow.

pina abi schema prints the JSON Schema for a document, generated from the same types that read and write it:

pina abi schema --document manifest > manifest.schema.json
pina abi schema --document publications

Each version’s schema is checked in under crates/pina_abi/schemas/, frozen beside its fixture under crates/pina_abi/fixtures/<version>/, and published under this book at a permanent URL — https://pina-rs.github.io/pina/abi/schemas/<version>/manifest.schema.json — which its $id names. Only the version this build writes can be printed; an older version’s shape is recorded by its frozen fixture rather than reproduced under a new build.

An ABI document upgrade does not consume an on-chain migration version.

Commands

Add --json for machine-readable output. Add --project <DIR> to select a program from another directory.

pina verify

Verify deployed executables and publish source-build records with the official solana-verify 0.5.1 workflow.

Start with a deterministic build:

pina build --verify

That command prints a content-addressed JSON record beside its .so artifact under target/pina/verifiable. Pina re-reads the record, rejects filesystem aliases and unsupported schema/tool versions, and recomputes the artifact’s trailing-zero-aware executable hash before it uses any provenance.

Compare a deployment

pina verify check \
  --program-id <ADDRESS> \
  --cluster devnet

Use --program <PROGRAM.SO> to select an executable directly or --project <DIR> to discover target/deploy/<library>.so. Pina delegates both hashes to solana-verify: executable hashing removes trailing zero padding before SHA-256, matching the official deployed-program comparison.

check is read-only.

Record verified source

pina verify record \
  --program-id <ADDRESS> \
  --cluster devnet \
  --build-record ./target/pina/verifiable/my_program-<HASH>.json \
  --authority ./upgrade-authority.json

Before invoking the repository rebuild, Pina verifies that the record’s artifact hash matches the deployed program. It then passes the record’s public repository, full revision, mount path, workspace path, library name, Cargo features, and default-feature choice to verify-from-repo. Arbitrary repository or revision overrides are intentionally unavailable.

Interactive recording prints a plan and requires typing record. Automation must pass --yes. Submissions to mainnet and unknown remote RPC origins also require --acknowledge-mainnet; --yes does not imply that acknowledgement. Exports are non-mutating and require neither flag. The authority keypair also pays transaction fees because solana-verify 0.5.1 does not support a separate payer.

Pina recognizes the upstream 0.5.1 hash-mismatch transcript as exit code 2. This guard matters because that upstream release exits successfully when its repository rebuild differs and does not write a verification record.

Repository recording uses upstream clone and Docker behavior and is supported only on Linux and macOS. Read-only comparison and remote-status commands remain available when the exact executable works on another platform.

Export for a multisig

pina verify record \
  --program-id <ADDRESS> \
  --cluster mainnet-beta \
  --build-record ./target/pina/verifiable/my_program-<HASH>.json \
  --export <MULTISIG_ADDRESS> \
  --output ./verification.tx \
  --export-encoding base64

Export never submits. It runs the separate upstream export-pda-tx operation after Pina’s build-record/deployment hash preflight. That upstream operation encodes the source and build arguments but does not rebuild the repository; remote verification happens only after the transaction is submitted. Upstream progress remains diagnostic output; only the final validated base58 or base64 transaction payload is atomically written to --output. Supplying a public address after --export does not require an authority secret.

Remote verifier

After an on-chain record exists:

pina verify submit --program-id <ADDRESS> --uploader <ADDRESS>
pina verify status --program-id <ADDRESS>

These commands target the official mainnet remote verifier. uploader is the public address that created the record, not a keypair. Status is read-only.

Tool and RPC security

Pina requires the exact version string solana-verify 0.5.1 and never installs it. Select an executable explicitly with pina verify --solana-verify <COMMAND> ....

Cluster aliases are mainnet-beta, devnet, testnet, and localnet. A custom endpoint must be a credential-free HTTPS origin with no path, query, or fragment; loopback HTTP is allowed for local development. RPC endpoints are necessarily passed to solana-verify in process arguments, where the operating system’s process listing may expose them. Put no credentials or access tokens in an RPC URL.

Authority files must be private regular files, not symbolic links. Pina bounds the file size, parses the 64-byte Solana keypair, and cryptographically verifies that its public half matches its secret half before starting the network workflow. Before confirmation, Pina freezes the reviewed provenance in memory and copies the validated keypair into a private temporary file so replacing the original paths cannot change the approved submission. Keypair bytes are never printed or passed in arguments; only that private temporary path is passed to upstream --keypair.

pina generate

Refresh the current program’s IDL and generate selected client ecosystems.

Synopsis

pina generate [OPTIONS]

pina generate
pina generate --client rust
pina generate --client cpi
pina generate --client typescript --client dart
pina generate --client cli-rust
pina generate --client cli-ts
pina generate --client cli-dart
pina generate --mode create
pina generate --mode update --no-scaffold
pina generate --mode overwrite

Repeating a language is harmless. Explicit --client values replace the configured list for that invocation. CPI-only, Rust-only, and cli-rust generation do not invoke Node.js. Each CLI variant implies its base client (cli-rust ⇒ rust, cli-ts ⇒ typescript, cli-dart ⇒ dart); projects normally pick one CLI, and Pina warns when several are selected together.

auto initializes an empty destination and otherwise updates it. Updates replace only renderer-owned generated source, preserving customized manifests and crate/package entrypoints. create and update enforce the expected destination state. overwrite deletes the entire selected client target before regeneration; use it for an intentional clean sweep. Command-line --mode and --no-scaffold override every selected target for that invocation.

Outputs are grouped by ecosystem:

clients/
├── cpi/<library-name>/
├── rust/<library-name>/
├── typescript/<library-name>/
├── dart/
├── cli-rust/<library-name>/
├── cli-ts/<library-name>/
└── cli-dart/

Pina rejects filesystem-root and symbolic-link generation targets before a renderer runs.

Generate every program in a repository by running the command once per project; scripts/generate-pina-clients.sh does exactly that for this repository’s examples.

Compute unit limits

When the program has a compute-units.json recorded by pina test --record-compute-units, the IDL carries each measured instruction’s budget as a pinaComputeUnits plugin node, and every client requests a tight, evidence-based limit instead of the runtime default:

{
	"kind": "pluginNode",
	"name": "pinaComputeUnits",
	"payload": { "measured": 379, "limit": 800 }
}

The limit is computed once, here, and copied by every generator:

limit = round_up_to_100(measured × (100 + margin_percent) / 100) + 300

• margin_percent comes from [compute_units] in pina.toml and defaults to 20, so a limit absorbs inputs more expensive than the recorded fixtures. The margin rounds up, and rounding to a hundred keeps limits stable when a measurement moves by a few units.
• The 300 units cover the compute budget instructions a priority-fee transaction carries: SetComputeUnitLimit and SetComputeUnitPrice each consume 150 compute units. Pina’s test suite measures both rather than assuming them.
• The limit never exceeds the 1,400,000 unit transaction maximum. An instruction whose measurement leaves no room for the compute budget instructions fails generation.

Each client exposes the budget its own way:

The summing helpers return no limit when a transaction carries no instruction for the program, or one without a measurement, so the runtime default applies. Their sum is conservative: every limit carries its own margin and compute budget reserve, which a transaction pays only once. They do not count instructions for other programs; add those budgets yourself.

import { setTransactionMessageComputeUnitLimit } from "@solana/kit";
import { getCounterProgramComputeUnitLimit } from "./clients/typescript/counter_program/src/generated";

const limit = getCounterProgramComputeUnitLimit(instructions);
const budgeted = setTransactionMessageComputeUnitLimit(limit, message);

An instruction without a measurement gets no plugin, and its clients are unchanged. CPI clients never set a limit: a compute unit limit belongs to the outer transaction.

A measurement names an instruction by its IDL name. If compute-units.json names one the program no longer declares, pina generate fails until you run pina test --record-compute-units again or remove the stale entry (or the whole file), so a renamed instruction cannot silently lose its budget in committed clients. pina build, pina idl, and pina test print a warning naming the stale entries and ignore them, so they never block the recording that replaces them. When the build in target/deploy differs from the one recorded in artifactSha256, pina generate still generates the limits and prints a warning naming the command that measures the current build.

See Project Configuration for client defaults and the distinction between configuration-relative and command-line paths.

pina cpi

Generate a standalone, no_std Pina CPI crate from a Codama or Anchor IDL.

Synopsis

pina cpi (--idl <FILE> | --stdin) --output <DIR> [OPTIONS]

pina cpi --idl ./target/idl/counter.json --output ./clients/counter-cpi
pina cpi --idl ./anchor-idl.json --output ./clients/anchor-cpi
pina cpi --idl ./anchor-idl.json --output ./clients/anchor-cpi --mode update

Instruction arguments may be little-endian native integers (u8-u128 and i8-i128), booleans, public keys, fixed u8 arrays, PinaPod’s bounded strings and vectors, and anything reachable through the IDL’s definedTypes: structs, enums, options, tuples, length-prefixed arrays, and maps. Anchor IDLs route most non-primitive arguments through that table, so a real third-party IDL renders without hand-editing.

Floating point, shortU16, bare (unprefixed) strings and byte slices, and big-endian integers are rejected before rendering, each with the reason in the error message.

An instruction whose arguments are all fixed-width returns [u8; LEN] from to_bytes(). When an argument’s length depends on caller-supplied data the instruction instead exposes MAX_DATA_LEN and takes a caller-owned buffer through encode_into — which bounds-checks every write and returns ProgramError::InvalidInstructionData instead of panicking when the buffer is too short or an argument exceeds its declared limit — before invoke_signed sends the encoded bytes, so the crate stays no_std and allocator-free either way.

Instructions using Anchor’s omitted optional-account strategy are rejected with the instruction named — a fixed-size CPI account array cannot drop an absent account the way that strategy requires. Pass --skip-unsupported-instructions to render the remaining instructions anyway; each skip and its reason is recorded in the generated instructions/mod.rs.

Accounts from the IDL render into a generated/accounts module with a struct, the account discriminator, an encoded-size constant, a matches guard, and — when every field has a fixed offset — a parse function.

To adopt another program’s interface end to end, including provenance and the program-ID binding test, see Import a Foreign Program.

Codama roots are rendered natively. Raw Anchor IDLs are normalized with @codama/nodes-from-anchor, then passed to the same renderer. The output crate contains a validated ProgramAccount and direct struct-based calls exposing .invoke() and .invoke_signed(). Each call contains its account references and a typed *Ix field named ix; its to_bytes() output is passed as CPI data. Account and argument fields preserve their IDL documentation and are labelled with their role.

The default auto mode creates missing scaffold files on initial generation and preserves them on updates. create fails if the target is nonempty, update fails if it is absent or empty, and overwrite removes the entire crate before generating it again. Use --no-scaffold when a workspace already supplies its own manifest and entrypoint.

The CLI test suite passes a committed raw Anchor IDL through the real pinned converter, checks the generated struct and documentation surface, and runs cargo check on the standalone no_std crate. The pina_bpf example also consumes the generated Prop AMM CPI client in its signer and PDA-signer execution paths.

Use pina generate --client cpi when the source is the current Pina program. For a reusable Codama script, install @pina-rs/codama-renderer-cpi; Codama normalizes either source format before passing its current transformed root to the visitor.

Import a Foreign Program

Call another on-chain program from your own without hand-writing its wire format. pina import fetches a foreign program’s IDL, renders a standalone no_std CPI crate, and records what the crate was generated from.

Synopsis

pina import <NAME> --program-id <PUBKEY> [OPTIONS]

Give one of --idl, --url, or --cluster. Passing --idl with --url is rejected rather than silently preferring one.

# From a vendored IDL
pina import switchboard \
  --program-id SBondMDrcV3K4kxZR1HNVT7osZxAHVHgYXL5Ze1oMUv \
  --idl ./idls/on_demand.json

# From a URL
pina import metaplex \
  --program-id metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s \
  --url https://example.com/token_metadata.json

# From the program's published on-chain IDL
pina import squads \
  --program-id SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf \
  --cluster mainnet-beta

What the generated crate contains

Each instruction becomes a call struct holding its accounts in the target program’s own order plus a typed ix field for the arguments:

RandomnessReveal {
    randomness,
    oracle,
    queue,
    ix: RandomnessRevealIx { signature, recovery_id, value },
}
.invoke_signed(program, &[signer])?;

Each account in the IDL also gets a read-only parser:

use switchboard_cpi::accounts::randomness_account_data::RandomnessAccountData;

let state = RandomnessAccountData::parse(randomness.try_borrow()?.as_ref())
    .ok_or(ProgramError::InvalidAccountData)?;
if state.reveal_slot == clock.slot {
    let value = state.value;
}

The parser carries the account’s discriminator as a public constant, its encoded size as LEN (or MAX_LEN when the layout varies), a matches guard, and a parse that returns None on a short buffer or a foreign discriminator.

An account whose layout has a variable-width field still gets its struct, discriminator, and size constant, but no parse: a variable-width field leaves every field after it with no fixed offset, so a partial parser would read the wrong bytes. The generated crate records why in a PARSER_UNSUPPORTED constant so the omission is visible at the call site.

Provenance

pina import stamps the generated README with the IDL’s SHA-256, where it came from, and the generator version:

The digest is the contract a reviewer checks. A CPI crate is a copy of another program’s interface, so without a recorded digest a reviewed crate can be regenerated from a different IDL with nothing in the diff to show it.

Re-running the same import against an unchanged IDL reports already up to date and rewrites nothing, so an import checked into CI produces no drift.

Binding the program ID

The target program address is compiled into the crate as an Address constant, and is_expected_program compares an address against it. Use it when the address arrives from caller input:

if !switchboard_cpi::is_expected_program(oracle_program.address()) {
    return Err(ProgramError::IncorrectProgramId);
}

The generated crate also ships a unit test that binds the compiled-in constant to the address spelled in the IDL. A swapped dependency could otherwise retarget every CPI in the crate without the source changing, so the expected address is asserted in full rather than only through the constant.

Supported argument shapes

Anchor routes most non-primitive arguments through definedTypes. The renderer resolves those links and declares the structs and enums it needs as Rust types with their own encoders, so nesting stays recursive instead of unrolling into the instruction body.

Supported:

• little-endian integers u8-u128 and i8-i128, booleans, and public keys
• fixed-width byte arrays
• length-prefixed strings, byte slices, arrays, and maps
• Option, including Anchor’s variable-length form
• structs, tuples, and enums whose variants carry equally sized payloads
• structs and enums referenced through definedTypeLinkNode

Rejected, with the reason in the error message:

Optional accounts

Anchor’s programId strategy — where an absent optional account becomes the program ID — is supported directly.

The omitted strategy, where an absent account is dropped from the list entirely, cannot be expressed by a fixed-size CPI account array — filling the slot with a placeholder would send the callee an account it does not expect. Instructions using this strategy therefore fail the import with the instruction named. Pass --skip-unsupported-instructions to import the rest of the program: the skipped instructions and the reasons are written into the generated instructions/mod.rs, so the gap is visible to every reviewer of the crate.

Verifying an import

The same gate that renders every checked-in fixture compiles the result for bpfel-unknown-none:

./scripts/verify-cpi-fixtures-sbf.sh

Checked-in fixtures cover Switchboard On-Demand randomness, Metaplex Token Metadata, Meteora DLMM, and Squads v4 multisig. The Switchboard fixture pins its instruction discriminators, account counts, and encoded instruction lengths against the hand-written reference crate in pina-rs/lootbox, and they match exactly.

Project Configuration

pina.toml is the project marker used by pina build and pina generate. Pina searches from the command’s --project directory, or the current directory, through its ancestors and uses the nearest configuration file. The legacy uppercase Pina.toml spelling is still discovered but deprecated and prints a warning, so new projects should use pina.toml.

The complete schema is intentionally small. Every section is optional; an empty file uses every default, and unknown sections and fields are rejected so misspellings cannot silently change a build.

[project]
program = "." # directory containing the program Cargo.toml
# idl_dir = "target/idl"             # override where generated IDLs are written

# Optional named path anchors. Values may reference `{{root}}`.
[project.paths]
sdks = "{{root}}/sdks"

[clients]
output = "clients" # root directory for generated clients
languages = ["cpi", "rust", "typescript"]
mode = "auto" # destination lifecycle policy
scaffold = true # initialize missing manifests and entrypoints

[lints] # optional per-lint level overrides
require_canonical_instruction_dispatch_for_idl = "deny"

[locks] # optional intentional write-lock hotspots for `pina locks`
allow = ["program_config"]

# Optional persisted disambiguation answers for `pina migrations create`.
[migrations.answers]
rename = ["value:points"]
assume_removed = []
manual = []

# Optional margin applied to recorded compute unit measurements.
[compute_units]
margin_percent = 20

# Optional target-specific overrides. Any of output, mode, and scaffold may be set.
[clients.cpi]
output = "onchain/cpi"
scaffold = false

[clients.dart]
mode = "update"

Path fields and anchors

Configuration paths are resolved relative to the directory containing pina.toml. Paths may also climb out of the project directory with .., or anchor at the repository root with template anchors:

• {{root}} expands to the git repository root — the working-tree top level, discovered with git rev-parse --show-toplevel. Linked worktrees resolve to the worktree itself, so each worktree gets its own output locations. Without a git binary, Pina falls back to the nearest ancestor containing a .git entry (a directory for repositories, a file for worktrees). Using {{root}} outside a repository is an error.
• A declared anchor such as {{ sdks }} expands to the value of the [project.paths] entry of the same name. Entry values may only reference {{root}} — they cannot reference each other — which keeps resolution single-step and cycle-free. Anchor names must match [A-Za-z_][A-Za-z0-9_-]*; root is reserved. Whitespace inside the braces is allowed ({{ sdks }} and {{sdks}} are the same anchor).

The discovery directory for {{root}} is the pina.toml folder, so a config nested in programs/my_program/ can still write clients to {{root}}/clients. The git root is only consulted when an anchor is actually used.

Validation rules for every configured path:

Command-line path overrides follow normal shell behavior instead: pina generate --output <DIR> resolves a relative directory from the caller’s current working directory, and .. is accepted. Standard Cargo variables remain supported. In particular, a relative CARGO_TARGET_DIR is resolved by Cargo metadata and passed to the compiler as an explicit absolute target directory.

[project] fields

[clients] fields

<target> in the per-client table below is one of the language names. Dart is the Dart and Flutter target; there is no separate Flutter generator.

Selecting a CLI target implies its base client (cli-rust ⇒ rust, cli-ts ⇒ typescript, cli-dart ⇒ dart), and projects normally pick one CLI; selecting several prints a warning. CLI apps render into clients/cli-rust, clients/cli-ts, and clients/cli-dart respectively — the Dart CLIs share one package at cli-dart with a bin/<library-name>.dart executable per program. Override a CLI target under the matching table ([clients.cli_rust], [clients.cli_ts], [clients.cli_dart]), using the kebab spelling as a deprecated alias ([clients.cli-rust]).

Override the selection for one run with repeatable --client cpi, --client rust, --client typescript, --client dart, --client cli-rust, --client cli-ts, or --client cli-dart flags.

[lints] fields

[locks] fields

[migrations.answers] fields

These answers are replayed by pina migrations create so fresh clones and CI repeat a decision made once. See the migration flow for the on-chain behavior; this section covers only the configuration.

The migration policy is not configured here. The version envelope width and the auto policy live only in migrations/manifest.json, the one source macros read, and pina migrations create --version-type and --auto record them there; see Manage ABI migrations. The retired [migrations].version_type (or version-type) and [migrations].auto keys fail every command that reads pina.toml, with an error naming the flag and value that replace them, for example:

`[migrations].auto` no longer belongs in pina.toml: migrations/manifest.json records it, and macros read only the manifest. Remove the key and run `pina migrations create --auto true` to record it.

Hand-editing the manifest, migrations/publications.json, or generated transition files is never allowed. Individual contracts can still opt out of a recorded policy with an explicit migrations = false attribute.

[compute_units] fields

These settings turn the measurements pina test --record-compute-units writes to compute-units.json into the compute unit limits generated clients request. See compute unit limits for the formula and what each client receives.

The margin applies at generation time, so changing it and running pina generate updates every limit without recording again.

Generation modes

Generation defaults to mode = "auto": it initializes an empty target, then updates only renderer-owned source directories on later runs. Use mode = "create" or mode = "update" to enforce the expected state. The CLI equivalents are --mode and --no-scaffold.

overwrite is an operator decision, not a configuration value: pina.toml cannot select it, and requesting destructive regeneration takes --mode overwrite on the command line. A pina.toml ships with the repository, so it is not trusted to authorize removing directories.

Deletion is bounded by a tracked-files record (.pina-generated.json) written at each client root: regeneration and overwrite remove only the paths a previous Pina run recorded, so files you added to a generated tree survive, and a directory Pina never generated is refused instead of removed. A destination that predates tracked manifests — generated by an older Pina — is refused by overwrite with a remedy in the error; remove it by hand once, or generate without overwrite once to record its files. Pina still refuses filesystem roots, git working-tree roots, symbolic-link targets, and output trees containing symbolic links.

Package resolution for renderers

The default --npx npx runner resolves the pinned renderer packages through the npx/pnpm dlx cache, from an isolated working directory with project-local entries removed from PATH: a committed node_modules in the project can neither shadow the pinned packages nor execute during generation. Passing a Node executable explicitly (--npx node, or a path to one) is the project-package mode — the documented way to resolve renderers from the project’s own install on purpose, which is also what keeps generation offline.

What generation owns versus what it scaffolds

Every client target separates two kinds of files, and knowing the split tells you what is safe to customize:

• Renderer-owned files are rewritten on every generation and must never be hand-edited. Update mode replaces only these.
• Scaffolded files are created once, only when missing, and are yours afterwards. Later runs never rewrite them, so manifests can be renamed, repackaged, or extended freely after the first generation.

Set scaffold = false to generate only renderer-owned files and never create package-level files — the “files, not the package” mode for embedding generated sources into a crate or package you own. Note that the Rust src/generated tree references crate::<PROGRAM>_PROGRAM_ID (the upper-snake library name), which the default lib.rs shim satisfies by glob re-exporting generated::*; an embedded tree needs an equivalent re-export at its host crate root.

An update owns only renderer-owned paths. The Rust and CPI renderers refuse to replace a src/generated tree whose mod.rs lacks Pina’s autogenerated header, and cli-rust update refuses a crate without its .pina-generated marker, so trees written by hand are never overwritten.

Names are read back from scaffolded manifests on later runs: the Rust CLI derives its dependency path from the crate name in the existing Cargo.toml, and the Dart CLI derives its package import from the name: in the existing pubspec.yaml. Renaming a client in its manifest after first generation is therefore supported and respected.

Because a scaffolded package.json is never rewritten, its @solana/kit range stays wherever the first generation left it even as the generated sources around it move forward with the renderer toolchain. The same applies to a scaffolded Dart pubspec.yaml and its Solana Kit Dart ranges. Hand-editing those ranges is the supported way to move a client between Kit versions: later runs respect whatever is written.

Generation refuses to update a client only when the existing manifest provably cannot resolve the Kit version the generated sources compile against — @solana/kit for TypeScript, the solana_kit_* packages for Dart, in either the inline or the nested version: declaration form. It judges a range by what it can resolve rather than by its first number, so a bounded range like >=7 <9 or a union like ^8.3.0 || ^7.0.0 passes because npm installs the newer version, while ^7.0.0 fails. The error names the manifest and the range to raise, and overwrite mode is the explicit way to start the scaffold over on the current ranges.

Example configurations

Defaults only — generates Rust and TypeScript clients into ./clients next to the program:

# pina.toml

A program publishing an SDK in every language, with clients at the top of the repository rather than inside the program directory:

[project]
program = "programs/lootbox"

[clients]
output = "{{root}}/clients"
languages = ["cpi", "rust", "typescript", "dart"]

[clients.cpi]
output = "{{root}}/crates/lootbox-cpi"

The same layout expressed once through named anchors, useful when several fields share a prefix:

[project]
program = "programs/lootbox"

[project.paths]
clients = "{{root}}/clients"

[clients]
output = "{{ clients }}"
languages = ["rust", "typescript"]

[clients.rust]
output = "{{ clients }}/rust"

Source-only generation beside an existing SDK crate — no manifest is created or touched, so the handwritten SDK keeps full ownership of its Cargo.toml and entrypoint. The <program> directory level is always present, so embed the tree from the SDK’s lib.rs with a #[path = "lootbox_program/src/generated/mod.rs"] pub mod generated; declaration and re-export it:

[project]
program = "programs/lootbox"

[clients]
output = "{{root}}/sdks/rust"
languages = ["rust"]
scaffold = false

[clients.rust]
output = "."

This renders only sdks/rust/lootbox_program/src/generated/**; the SDK crate’s manifest must also declare the generated dependencies (Pina scaffolds them into a fresh Cargo.toml when scaffold = true, so generate once with scaffolding to copy the pin list).

A CLI-first project that also keeps the CPI crate for other programs to compose with:

[project]
program = "."

[clients]
output = "clients"
languages = ["cpi", "rust", "cli-rust"]
mode = "auto"

[clients.cli_rust]
scaffold = false

A migration-aware program with persisted answers and lint strictness raised for the canonical-dispatch rule. Its policy, for example pina migrations create --auto accounts,events --version-type u16, is recorded in migrations/manifest.json rather than here:

[project]
program = "."

[migrations.answers]
rename = ["value:points"]
assume_removed = []

[lints]
require_canonical_instruction_dispatch_for_idl = "deny"

Command-line overrides

pina generate accepts --output <DIR> (replaces clients.output, resolved from the current working directory), repeatable --client <LANGUAGE>, --mode <MODE>, and --no-scaffold. Per-run flags override the file for that invocation only; the committed configuration remains the source of record for teammates and CI.

Pina can also discover an existing, unambiguous Cargo package without pina.toml: defaults apply and clients land in <package>/clients. Add the file when a workspace contains multiple programs or when a team wants reproducible client selections.

Test a Program

pina test keeps two deliberately different feedback loops.

# Fast host tests, including Mollusk instruction tests.
pina test --unit

# Build the real SBF program and run the generated Surfpool test package.
pina test

# Select tests by name in either layer.
pina test --filter initialize
pina test --unit --filter rejects_wrong_owner

# Verify migration history and run historical compatibility cases.
pina test --compatibility

# Measure every instruction and record the result in compute-units.json.
pina test --record-compute-units

Default SBF workflow

The default command:

1. discovers the program from --project or the current directory;
2. builds the release bpfel-unknown-none artifact with bpf-entrypoint enabled;
3. fails if the expected .so or tests/surfpool package is missing;
4. publishes the artifact at target/deploy/<library-name>.so;
5. sets PINA_SBF_ARTIFACT and runs the ignored test in tests/surfpool.

Projects created by pina init put the host-only pina_test dependency in a dedicated Cargo package under tests/surfpool. Its standalone workspace boundary isolates Surfpool’s host runtime from the program’s Mollusk dependencies and SBF build. pina_test owns the Surfpool 1.5 compatibility graph and exposes only the offline lifecycle, deployment, and instruction operations the generated test needs. The generated test starts an embedded, offline Surfnet on dynamic ports, deploys the explicit .so at a non-system declared program address, submits and confirms the starter Initialize instruction, and calls Surfnet::stop before returning. Surfnet also stops itself through Drop if an assertion panics. This avoids fixed ports, background daemon processes, readiness sleeps, leaked validator instances, and host SDK dependencies entering the on-chain artifact.

The embedded SDK is the correct fit for isolated integration tests. See Surfpool’s official SDK overview and installation guide.

Pina’s prebuilt CLI supports more operating systems and CPU targets than Surfpool currently publishes. On a machine where Surfpool or the SDK cannot run, pina test --unit remains available; the SBF integration command fails with the missing dependency instead of silently skipping it.

Unit mode

--unit runs cargo test without building SBF or requiring Surfpool. Pina intentionally leaves Cargo attached to the terminal in both test modes so filters, output, and interrupts behave like direct Cargo use. Keep pure logic and serialization tests native, and use Mollusk for fast instruction-level VM tests. Surfpool adds a real RPC boundary; it does not replace those faster layers.

Compatibility mode

pina test --compatibility verifies the checked-in ABI history and transition hashes before it runs the default SBF workflow. It sets PINA_COMPATIBILITY=1 for the Surfpool package. Use pina_test::compatibility_mode() to enable large historical fixture matrices.

Compatibility mode runs the complete Surfpool suite. Do not use the signal to skip current-flow tests.

Build historical cases with HistoricalAccount and HistoricalInstruction. These types preserve golden bytes from a released version. ProgramTest::install_historical_account installs old account data directly. ProgramTest::send_historical_instruction submits the old payload and positional account metas to the latest SBF artifact.

For a rejected migration, call ProgramTest::expect_historical_rejection_with_rollback. The helper accepts only a program-execution failure. It then compares each protected account with its exact pre-transaction state.

Recording compute units

Most transactions request the runtime’s default compute unit limit, and priority fees are charged per requested unit, so they pay for units they never use. Your Surfpool suite already runs every instruction against the real program, so it can measure what each one costs.

pina test --record-compute-units runs the complete Surfpool suite exactly as pina test does. While it runs, pina_test simulates each single-instruction transaction that ProgramTest::send, send_instruction, send_with_signers, or send_transaction submits to the program. When the whole suite passes, Pina writes compute-units.json beside the program’s Cargo.toml:

{
	"schemaVersion": 1,
	"measurement": "surfpool-simulation-max",
	"artifactSha256": "cd4f4344ca04f181016a16b7694b3ef10a93703e7c259c0be852807df8033614",
	"instructions": {
		"increment": {
			"computeUnits": 379,
			"samples": 5
		},
		"initialize": {
			"computeUnits": 1704,
			"samples": 6
		}
	}
}

• Each instruction keeps the most compute units any successful sample consumed. A transaction that fails usually stops early, so failed samples never count.
• Samples are attributed by the program’s full discriminator, whatever its width.
• An instruction no successful test sent is left out, and the command names it. Its clients keep requesting the runtime default until a test exercises it.
• artifactSha256 identifies the SBF build the suite measured. pina generate warns when target/deploy/<library-name>.so is a different build, so you know to record again.

The suite runs unfiltered: --record-compute-units conflicts with --unit and --filter, because a partial run would drop the measurements of the tests it skipped. A failing suite writes nothing.

The recording build never reads the existing compute-units.json, because the run replaces it. After you rename or remove an instruction, record again: a plain pina test, pina build, or pina idl warns about the stale entry and ignores it, and pina generate refuses to run until it is gone.

Commit compute-units.json with the clients it produced. The file is deterministic, so recording again without changing the program produces no diff. pina generate turns each measurement into the limit the generated clients request; see compute unit limits.

Options

Run pina test --help for the authoritative command contract.

Run a Development Surfnet

pina dev builds the current SBF program once, then delegates the persistent development network, artifact watching, and redeployment to Surfpool.

# First run: explicitly allow Surfpool to create txtx.yml.
pina dev --yes

# Review and commit txtx.yml, then use the safe offline default.
pina dev

# Opt into remote state explicitly.
pina dev --network devnet
pina dev --rpc-url https://api.mainnet-beta.solana.com

Pina invokes the foreground equivalent of:

surfpool start --watch --artifacts-path target/deploy \
  --manifest-file-path txtx.yml --offline

Surfpool remains in control of its terminal UI, logs, file watcher, redeployment, and shutdown. Pina intentionally leaves standard input, output, and errors attached to the foreground Surfpool process so prompts and Ctrl-C work normally. The short non-interactive version probe receives closed input and bounded output instead. Rebuild the program in another terminal to update the canonical .so and trigger redeployment.

Deployment runbook

Surfpool uses txtx.yml to describe deployment. Creating or refreshing that runbook can write project files, so Pina will not silently accept a missing manifest. Run pina dev --yes for the first invocation, then inspect and commit the generated txtx.yml. The flag is forwarded to Surfpool and authorizes its non-interactive runbook changes; omit it during ordinary development when you want Surfpool to ask before changing the runbook. Pina rejects directories, symlinks, and Windows reparse points at this path.

Network safety

Surfpool itself defaults to a mainnet datasource. Pina does not inherit that network-sensitive default: it always supplies --offline unless --network or --rpc-url is explicitly selected. The two upstream options conflict.

An explicit --rpc-url must use HTTP or HTTPS and include a host. Pina rejects user information, query parameters, fragments, and control characters. Surfpool receives every accepted URL as a child-process argument, where local process inspection can reveal it. Never put a credential or other secret anywhere in the URL, including an otherwise valid host or path. Prefer a named --network or a credential-free endpoint.

Pina requires Surfpool 1.5.0 or newer because its delegated --watch, --artifacts-path, and --runbook flags are tested against that contract. Pina’s own workspace pins and exercises Surfpool 1.6.0. See the official Surfpool CLI reference.

Options

Run pina dev --help for the authoritative command contract.

Generate and publish IDLs

pina idl owns the complete IDL lifecycle without adding another top-level command: generate a Codama document, compare it with canonical Program Metadata, fetch it, or publish an update.

Synopsis

pina idl [OPTIONS]
pina idl generate [OPTIONS]
pina idl fetch --cluster <CLUSTER> [OPTIONS]
pina idl diff --cluster <CLUSTER> [OPTIONS]
pina idl publish --cluster <CLUSTER> [OPTIONS]

Bare pina idl [OPTIONS] remains exactly equivalent to pina idl generate [OPTIONS]. Existing scripts do not need to change.

Generate a local IDL

Output contract

Without --output, stdout contains JSON and nothing else. Progress and extraction counts go to stderr, so redirection is safe:

pina idl --path ./programs/counter_program > ./counter_program.json
jq . ./counter_program.json

With --output, the JSON is written to that file and stdout is unused:

mkdir -p ./idls
pina idl \
  --path ./programs/counter_program \
  --output ./idls/counter_program.json

The output file is replaced if it exists. Its parent directory must already exist.

What the extractor reads

The extractor starts at src/lib.rs and follows Rust mod declarations, including #[path = "..."] modules. Missing unconditional module files are errors. Missing modules behind #[cfg(...)] are treated as inactive because their configuration may not apply to the IDL build. It derives the public IDL from source shapes rather than requiring a separate schema file.

It recognizes:

• #[instruction] payload structs and discriminator values;
• #[account] state layouts;
• #[error] enums;
• #[pda] typed seed declarations;
• #[derive(Accounts)] account order and mutability;
• direct validation chains for signer, writable, address, owner, and PDA metadata;
• canonical and grouped instruction dispatch arms.

Read Codama Workflow for supported dispatch shapes and source-authoring rules.

Program naming

By default, the Codama program name comes from package.name in the target Cargo.toml. --name changes the emitted name without changing the Rust package or source tree:

pina idl -p ./programs/counter_program --name counter_v2

Failure modes

The command exits unsuccessfully when the path is not a readable program crate, [package].name is absent, modules cannot be resolved, more than one source file defines process_instruction, declarations conflict, PDA attributes or validation links cannot be resolved, a supported schema cannot be represented safely, or JSON/output-file writing fails. Diagnostics include source or path context where available. These checks are fail-closed: the CLI does not silently omit malformed PDA metadata or choose one of several entrypoint dispatch sources.

For complete client generation, continue with pina generate.

Canonical Program Metadata

Pina publishes an IDL to Solana’s Program Metadata program with these fixed semantics:

• seed: idl;
• account type: canonical metadata;
• authority: the deployed program’s upgrade authority;
• source: direct, inline account data;
• encoding: UTF-8;
• compression: zlib;
• format: JSON.

The canonical PDA is derived from the program address and the fixed idl seed. This gives each program one authoritative IDL. Pina does not expose third-party metadata, custom seeds, URL data, external-account data, immutability, or account closure in this initial workflow.

The adapter delegates transaction planning to the exact official npm package @solana-program/program-metadata@0.9.0. The behavior was cross-checked against upstream commit 33eb527e124cc4a09d8aae448cd306a9bd87db14. Pina does not duplicate the upstream allocation, reallocation, buffer, rent, or transaction-packing rules.

Runtime requirement

Network IDL commands require Node.js, npm, and an npx-compatible runner. By default Pina executes:

npx --yes @solana-program/program-metadata@0.9.0 ...

The package version is pinned, never latest. npx may download that pinned package if it is not already cached. Use --npx <COMMAND> only for a runner that accepts the same npx argument contract; it is not an arbitrary shell command. Pina constructs an argument vector and never invokes a shell.

Client stdout and stderr are drained concurrently into bounded buffers. Oversized output fails explicitly; Pina never truncates a transaction export and presents it as a valid plan.

Clusters and RPC safety

Every network operation requires --cluster. Accepted aliases are mainnet-beta, mainnet, devnet, testnet, localnet, and localhost. An HTTPS RPC origin may also be supplied. Loopback HTTP is accepted for local testing; remote plaintext HTTP is rejected.

Custom RPC URLs may not contain user information, query parameters, fragments, or a path. This is intentional: RPC API credentials placed in a URL would otherwise be exposed to the child process argument list. Configure an authenticated local proxy and pass its credential-free origin when a provider requires secrets.

Fetch

pina idl fetch \
  --cluster mainnet-beta \
  --program-id <PROGRAM_ADDRESS> \
  --output ./target/fetched/program.json

--program-id may be omitted inside a discoverable Pina project. Pina then generates the local IDL only to infer program.publicKey.

Fetch is deliberately fail-closed. Pina asks the official client for the raw stored bytes, then locally applies a bounded zlib decode, UTF-8/JSON parsing, complete Codama root-node deserialization, and target-program comparison. It does not follow URL or external-account metadata. Accounts using another otherwise-valid Program Metadata representation produce an actionable unsupported-content error instead of triggering an unexpected outbound request.

The decompressed IDL is capped at 16 MiB. --output is written atomically. Without it, stdout is the IDL JSON. --json wraps the document in a versioned result envelope for agents.

Semantic diff

pina idl diff --cluster devnet

pina idl diff \
  --cluster mainnet-beta \
  --program-id <PROGRAM_ADDRESS> \
  --file ./target/idl/program.json \
  --json

The comparison parses both documents as JSON. Object key order and whitespace do not matter; array order does. Exit statuses are:

This makes pina idl diff --cluster <CLUSTER> --json suitable for deployment and release checks.

Publish directly

pina idl publish \
  --cluster devnet \
  --authority ~/.config/solana/upgrade-authority.json

Pina generates the project IDL unless --file is supplied. If --program-id is also supplied, it must equal program.publicKey inside that complete Codama document. Pina cryptographically checks that a keypair file’s public half matches its Ed25519 secret half, then gives the official client a stable private temporary copy so replacing the original path cannot change the signer after validation. Files larger than 4 KiB are rejected; on Unix, group or other permissions are also rejected and temporary copies use a 0700 directory with a 0600 file. Windows copies inherit the current user’s protected temporary-directory ACL; Windows keypair validation does not attempt to interpret arbitrary source-file ACLs. Key material is never printed.

--payer <KEYPAIR> separates transaction fees and metadata-account rent from the upgrade authority. When omitted, the authority also pays. --priority-fee <MICROLAMPORTS> defaults to 100000, matching the official client.

Interactive publication prints the cluster, program, and local IDL source, then requires the exact word publish. In CI, pass --yes. Export mode never submits and therefore does not require this confirmation.

The Program Metadata account must remain rent-exempt. Creation funds its 96-byte header and packed IDL content. Updates may transfer additional rent, extend the account in bounded steps, write through temporary buffers when a transaction cannot hold the content, trim unused bytes, and close temporary buffers. Those decisions belong to the pinned official planner.

Export for review or a multisig

Export every planned transaction without submitting anything:

pina idl publish \
  --cluster mainnet-beta \
  --authority ./upgrade-authority.json \
  --export \
  --output ./idl-plan.txt

For a Squads vault or another multisig, provide its public address instead of a secret keypair:

pina idl publish \
  --cluster mainnet-beta \
  --program-id <PROGRAM_ADDRESS> \
  --file ./target/idl/program.json \
  --export <MULTISIG_AUTHORITY> \
  --export-encoding base58 \
  --output ./idl-update.txt

An exported authority is a noop signer used only to plan the transaction messages. Do not pass --authority or --payer with --export <ADDRESS>; the multisig must authorize and pay when it imports the plan. The export contains every transaction in the upstream order, including allocation, buffer, write, initialization/update, trim, and cleanup transactions where required. Pina preserves the official [Transaction #N] framing rather than pretending the workflow is one transaction.

The default export encoding is base64. Use base58 when the receiving multisig requires it. Without --output, the complete export is written to stdout and Pina writes no status text there.

Exported transactions contain a recent blockhash. If approval takes too long, regenerate the export; do not submit a partially approved subset from an old plan.

Failure recovery

• The authority is rejected: verify the deployed program is upgradeable and the supplied signer is its current upgrade authority. Pina never falls back to non-canonical metadata.
• The process stops during a multi-transaction write: rerun pina idl diff first. If it differs, rerun the same publish command. The official planner inspects current state and creates an update plan; do not manually guess which write transaction was last confirmed.
• An exported blockhash expires: discard the complete export and regenerate it.
• A buffer transaction succeeds but a later transaction fails: retain logs and rerun publication. The upstream planner owns buffer lifecycle and recovery behavior.
• Fetch reports unsupported content: the canonical account is not direct zlib/UTF-8 JSON. Use the official Program Metadata tooling to inspect it. Pina will not follow its URL or external account.
• IDL program mismatch: regenerate from the correct program or pass the correct target. Never publish by editing only program.publicKey to bypass the check.
• npx fails: confirm Node.js and npm are installed and that the pinned package can be resolved. Corporate/offline environments should pre-cache version 0.9.0 or supply an npx-compatible runner.

pina docs

List or render reference topics in the terminal.

Synopsis

pina docs [TOPIC]

Run without a topic to list bundled topics:

pina docs

The binary currently bundles:

Render one with:

pina docs pina-idl
pina docs pina-overview
pina docs pina-validation

Markdown is rendered for the terminal rather than printed as raw source.

Each bundled topic is an mdt consumer of the repository’s templates/*.t.md providers, so docs:check fails when a topic and the template it mirrors disagree.

Custom topics

Set PINA_TEMPLATES_DIR to a directory containing <topic>.t.md files:

PINA_TEMPLATES_DIR=./team-docs pina docs deployment

For that example, Pina reads ./team-docs/deployment.t.md. A custom file takes precedence over a bundled topic with the same name. If no matching custom file exists, Pina falls back to the bundled topic.

Bare pina docs lists bundled topics only; it does not scan the custom directory. This keeps discovery deterministic even when the environment points at a large template tree.

Failure modes

An unknown topic returns a non-zero exit code and prints the bundled topic index. If PINA_TEMPLATES_DIR resolves a topic to a file that cannot be read, the command reports that path and fails.

pina keys

Inspect and manage the local program identity without exposing secret key bytes.

pina keys [OPTIONS] [COMMAND]

pina keys and pina keys show are read-only aliases. They discover the nearest Cargo program package, read its single declare_id!, and compare it with the conventional keypair at <cargo-target>/deploy/<lib-target>-keypair.json. Use --keypair to inspect a different local file and --json for automation.

Synchronize an existing keypair

pina keys sync
pina keys sync --keypair ./keys/counter-keypair.json

sync validates all 64 keypair bytes, derives the Ed25519 public key from the secret half, and refuses inconsistent files. It then parses Rust source and replaces only the string literal of exactly one declare_id!. Zero or multiple declarations fail before a write. Source identity and contents are checked again immediately before publication, so an editor save during synchronization fails instead of losing unrelated changes. The command never prints secret bytes.

Create or rotate identity

pina keys new
pina keys new --keypair ./keys/counter-keypair.json
pina keys new --force

new generates a cryptographically random Solana keypair, writes it with owner-only permissions on Unix, and synchronizes source. It refuses an existing keypair. --force is intentionally required to replace one and rotate the program identity. Windows generation currently fails before creating secret material because Rust’s safe standard API cannot construct a private ACL atomically; use a reviewed external keypair and pina keys sync instead.

Program deployments are identified by their address. Treat keys new --force as a destructive identity rotation: review downstream clients, deployment records, and funded accounts first.

The conventional keypair lives below the Cargo target directory, which pina init git-ignores, so cargo clean deletes it. Back it up outside the repository before the first deployment: it is the program’s address, and losing it after deployment means upgrades can no longer name the program by its keypair.

Identity and migration history

migrations/manifest.json records the program ID the history belongs to. When new or sync writes a different ID than the manifest records, the command prints the recorded ID and points at the next step:

• If nothing was ever deployed (no publication receipt and no pending deployment), run pina migrations create. It rebinds the unpublished history to the new declare_id! and says so. This is the normal path after pina init, whose scaffold starts with a shared placeholder address.
• If a receipt exists, the history belongs to the deployed program. Every migrations and deploy command fails with Migration history belongs to program … until the original declare_id! is restored; a new identity is a new program.

Output and failures

Human output identifies source, keypair path, public program IDs, and match status. --json emits only JSON on stdout. Failures are written to stderr and exit unsuccessfully.

Keypair inputs for show and sync must be regular, non-link files no larger than 4 KiB. Read-only selection may pass through an aliased ancestor. Generated keypair and source write destinations reject non-regular files, symbolic links, and reparse points anywhere in the destination path. The command also fails closed for malformed Rust, invalid addresses, ambiguous declarations, malformed JSON, incorrect keypair length, inconsistent secret/public halves, unavailable secure randomness, private-permission guarantees, and unauthorized replacement. Keypair and source publication use atomic replacement; failed source publication rolls the keypair back only while the generated file still has the identity created by the command. A concurrent keypair replacement is preserved and reported as a rollback failure.

pina doctor

Diagnose whether the current checkout is ready for Pina development.

pina doctor [OPTIONS]

pina doctor
pina doctor --path ./programs/counter
pina doctor --json

The report checks:

• nearest Cargo program package, source entrypoint, and declared program ID, warning when it is still the shared pina init placeholder;
• lint-driver resolution: the active toolchain, the release the shipped lints are verified against, the resolved driver with its own toolchain and how it was obtained, both search paths, and the remedy when nothing matched;
• canonical SBF artifact and program-keypair paths;
• source/keypair identity agreement;
• required Rust/SBF tools (cargo, rustc, and the Agave cargo-build-sbf driver);
• optional solana and surfpool tools;
• Node.js plus an npx or pnpm renderer when configured clients require JavaScript tooling.

Human output is stable, color-free text. It includes typed check IDs such as project.discovery, project.program-id, project.artifact, lint.driver, and tool.surfpool so the same vocabulary appears in logs and agent output.

The Lint driver: section answers the one question a failing pina lint leaves open — which toolchain is active, which driver Pina resolved for it and which toolchain that driver was built for, and what to run when none resolved. pina doctor reports this state without downloading or building anything: a diagnostic that populates a cache cannot be run to find out what is wrong. A missing driver is a warning, not an error, because it blocks pina lint only and the project can still build and deploy.

Agent JSON

pina doctor --json > doctor.json

JSON is the only stdout content. Schema version 1 includes status, project, tools, typed checks, and actionable findings. Each check has a stable id, status (pass, warn, or fail), and message. The report never includes environment-variable values or keypair secret bytes.

Every external version or capability probe receives closed stdin, bounded output capture, and a five-second deadline. Pina attempts to terminate a tool that hangs and reports it as unavailable; it also stops waiting when a descendant keeps the tool’s output pipes open. Agent diagnostics therefore return within a predictable bound even when a probe misbehaves.

Warnings—including missing optional tools, an unbuilt artifact, a missing local keypair, or an unresolved lint driver—exit with code 0. Missing project discovery, unreadable program identity, or unavailable required Rust/SBF prerequisites produce status: "error" and exit with code 1; the JSON document is still emitted in full.

pina explain

Explain why a transaction to the current program failed.

pina explain <SIGNATURE> [--network localnet|devnet|testnet|mainnet | --rpc-url <URL>] [--project <DIR>] [--json]
pina explain --transaction-file <PATH> [--network ... | --rpc-url <URL>] [--project <DIR>] [--json]

pina explain 4MeRynoBFLczcN7jND2spt4Vvwn5K8kasDeG7vaJU7fjTDDA2YzwFkYUqzTGS4m5UQPFGEDbzqpTqncwwg1rVYVV
pina explain <SIGNATURE> --network devnet
pina explain --transaction-file ./failed.json --project ./programs/counter
pina explain <SIGNATURE> --json

A failed Pina check returns a bare error code, and several checks share one: writable, address, executable, data_len, and distinct_from all return InvalidAccountData. A distinct code per check would cost every program size and compute units, so Pina keeps the codes and moves the diagnosis off-chain. pina explain reads the failed transaction’s account flags, error, and logs, matches them against the program’s #[derive(Accounts)] structs and processors, and names the field and rule that most likely failed, with its path:line.

What it reports

Transaction 4MeRyno…VYVV (slot 62, from localnet)
Instruction #0 failed: check_policy (CheckAccounts) in validation_program
Error: InvalidAccountData

Most likely cause:
  audit: writable [confirmed, matches the program log] at src/lib.rs:221
    account #2 (EdmxWPmx2WH6WgFfTdu9xfkYf3k1g5wD1zccTVySEEh1) is read-only in this transaction

Accounts:
  #   field           signer  writable  address
  0   authority       yes     no        9hSR6S7WPtxmTojgo6GG3k4yDPecgJY292j7xrsUGWBu
  1   policy          no      no        GyGKxMyg1p9SsHfm15MkNUu1u9TN2JtTspcdmrtGUdse
  2   audit           no      no        EdmxWPmx2WH6WgFfTdu9xfkYf3k1g5wD1zccTVySEEh1
  3   system_program  no      no        11111111111111111111111111111111

Program logs (last 4 lines):
  …

• The failing instruction, identified by its discriminator, with the accounts struct its dispatch parses.
• The decoded error. Built-in runtime errors keep their names. Codes in Pina’s reserved range decode to their PinaProgramError variant, and other custom codes to the program’s #[error] variant with its first documentation line.
• Ranked candidates: the checks whose error matches the observed one, each with its field, rule, location, and a confidence class. The program stops at its first failing check, so a check that runs after one the transaction proves failing is left out.
• Construction sites: where the program writes the error (ValidationError::InvalidAmount, ProgramError::InvalidArgument), sites in the failing instruction’s accounts struct, instruction struct, processor, and validation hooks first.
• The account table: each instruction slot with its field (parent.child for a nested struct, members[0] for a remaining slice), address, and the signer and writable flags the transaction gave it.
• The failing instruction’s last log lines. Pina logs a message for the checks that share InvalidAccountData, such as account has not been marked as writable, and a candidate whose message appears is ranked first.

Confidence

A rule whose validate(...) group sets error = ... is matched by that error’s code instead of the default.

Inputs and network

A signature is fetched with one getTransaction request at confirmed commitment. The default network is localnet (http://127.0.0.1:8899); Pina never queries mainnet unless --network mainnet or --rpc-url names it. When the failing instruction targets the explained program, one getMultipleAccounts request then reads the current owner, executable flag, and size of its accounts. Neither request is retried, and a failed state lookup becomes a note instead of an error.

--transaction-file reads a saved getTransaction result, or the complete JSON-RPC response around one, and works offline. Add --network or --rpc-url to also check state-dependent rules.

A transaction rejected by preflight simulation never lands, so getTransaction cannot find it. Send with preflight disabled, or explain a transaction captured from a test validator, when you need the landed failure.

--rpc-url accepts credential-free HTTP(S) URLs with a host. User information, query parameters, fragments, and control characters are rejected, plaintext http is accepted only for a loopback host, and redirects are not followed. Reports and errors name a custom endpoint as custom RPC endpoint rather than echoing its URL.

Limits

• The failing instruction must target the program in --project. A failure in another program is reported with its decoded error and accounts, and nothing more.
• A failure inside a CPI is attributed to the callee the logs name. The program’s own checks ran before the call, so no candidate is listed.
• A field whose type is not a #[derive(Accounts)] struct of the program stops the account mapping at that field.
• Processor checks are found by name on self.<field> (assert_signer, assert_owner, load_pda, and the rest), including through local aliases. A check behind a helper function is not attributed to a field, but its error constructions are still listed.
• Writability demoted by the runtime, for example a reserved account marked writable, is read as the message declares it.

Exit status and JSON

A produced explanation exits with code 0, including for a transaction that succeeded, which prints that there is nothing to explain. An invalid signature, file, or URL, a project that cannot be parsed, a transaction that cannot be fetched or found, and a malformed transaction exit with code 1. Conflicting or missing transaction sources are usage errors with code 2.

pina explain <SIGNATURE> --json > /tmp/pina-explain.json
jq -e '.candidates[0].confidence' /tmp/pina-explain.json

JSON is the only stdout content. Schema version 1 contains signature, slot, source (file or the endpoint label), program, status (succeeded or failed), failure (instruction index, program, instruction, decoded error with kind, and cpi), ranked candidates, errorSites, accounts, logs, and notes. Each candidate has scope (account, argument, or instruction), field, accountIndex, rule, location, confidence, logConfirmed, and reason. Operational failures print only the error to stderr.

pina completions

Generate a completion script from the authoritative Clap command tree.

pina completions <SHELL>

Supported shells are Bash, Elvish, Fish, PowerShell, and Zsh. The script is written to stdout without progress text:

pina completions bash > ~/.local/share/bash-completion/completions/pina
pina completions zsh > ~/.zfunc/_pina
pina completions fish > ~/.config/fish/completions/pina.fish

Regenerate the script after upgrading Pina so new commands, options, and help text are available to the shell.

pina profile

Estimate compute-unit costs in a compiled Solana SBF shared object without starting a validator, or measure them line by line from the project’s Mollusk tests with pina profile trace.

Synopsis

pina profile [OPTIONS] [PROGRAM.SO] [COMMAND]

Examples

pina profile
pina profile --project ./programs/counter_program
pina profile ./target/deploy/counter_program.so
pina profile ./target/deploy/counter_program.so --json
pina profile ./target/deploy/counter_program.so --json --output ./profile.json

The positional path remains supported for scripts and custom artifacts. When it is omitted, Pina discovers the nearest Cargo program and profiles the canonical <cargo-target>/deploy/<lib-target>.so artifact. Discovery fails with the exact expected path when the program has not been built.

JSON includes program and binary metadata, aggregate instruction/syscall/CU counts, and a per-function array with offsets, sizes, and estimates.

Function names

Function names are demangled Rust paths without the legacy ::h<hash> suffix, so a function keeps its name across rebuilds and compare can match it. The deployed artifact is stripped down to its exported symbols, so when the profiled file sits in a directory directly below the Cargo target directory (such as target/deploy/), Pina reads function names from the unstripped linker output cargo build-sbf leaves at target/sbpf-solana-solana/release/<lib-target>.so. That file is only used when its .text section is byte-identical to the profiled one. Without it, the report falls back to the exported symbols, which is usually just entrypoint. A release profile with strip = true strips the intermediate too.

Estimation model

The profiler reads the ELF text section, decodes SBF instructions, discovers functions, and applies the repository’s static cost model. Regular instructions cost 1 estimated CU and recognized syscalls cost 100 estimated CU.

This is a deterministic comparison tool, not a replacement for runtime measurement. It cannot model data-dependent branches, invocation frequency, account state, CPI behavior, or runtime syscall variation. Use it to compare binaries and identify large functions, then validate important paths in an SVM or validator.

Comparing against a baseline

pina profile compare answers “what changed between these two builds?” by profiling the current artifact and diffing it against a saved report.

pina profile compare <BASELINE> [PROGRAM.SO] [OPTIONS]

Capture a baseline before changing the program, rebuild, then compare:

pina profile --json --output ./profile.json
# ... change and rebuild the program ...
pina profile compare ./profile.json
pina profile compare ./profile.json --json
pina profile compare ./profile.json --fail-cu 100 --fail-percent 5

The baseline may be any report written by pina profile --json --output, or a versioned baseline document that carries an explicit schema_version marker. Baselines declaring a different schema version are rejected instead of silently misread.

The text summary prints total deltas, then per-function deltas sorted by absolute CU change. Functions are matched by symbol name; added and removed functions are reported separately. The summary line classifies the build as unchanged, improved, a small regression, or a threshold regression.

Exit status

Both limits must be reached, mirroring the failure policy of the repository’s CI compute-unit workflow, so a local pina profile compare reproduces the CI gate with the default thresholds.

JSON comparison document

--json emits a deterministic document with schema_version, baseline and current program names, total snapshots and deltas, the applied threshold, an overall status (unchanged, improved, regression, or threshold-regression), and a functions array sorted by delta magnitude. Identical inputs always produce identical bytes, so the output is safe to diff or store.

Tracing executed compute units

pina profile trace answers “where did the compute units of this instruction go, line by line?” by measuring instead of estimating. It builds the program, runs the project’s Mollusk tests with register tracing, and attributes every executed SBF instruction to a source line and a call stack.

pina profile trace [OPTIONS]

pina profile trace
pina profile trace --project ./programs/counter_program
pina profile trace --filter increment --instruction increment
pina profile trace --json --output ./trace.json
pina profile trace --folded > ./stacks.folded
pina profile trace --trace-dir ./target/pina/trace/traces

Setup

Mollusk records traces only when its register-tracing feature is enabled, so declare the program’s dev-dependency with it:

[dev-dependencies]
mollusk-svm = { version = "0.15", features = ["register-tracing"] }

Tests must load the program by name (for example Mollusk::new(&program_id, "my_program")), so the run can point SBF_OUT_DIR at the traced build. A copy of the program in tests/fixtures/ takes precedence over SBF_OUT_DIR and is reported as traces from another build. When no trace is recorded, the error shows the exact dependency line for the program’s manifest.

What it runs

1. cargo build-sbf with the production size profile pina build uses, plus CARGO_PROFILE_RELEASE_DEBUG=line-tables-only and CARGO_PROFILE_RELEASE_STRIP=none. The stripped program goes to <target>/pina/trace/build/, where the tests load it, and the unstripped linker output with DWARF is copied to <target>/pina/trace/<lib-target>.so.debug for attribution. Mollusk cannot load an ELF whose symbol table holds long Rust names while tracing, which is why the two are separate.
2. The same build without debug information into <target>/pina/trace/release/, to check whether debug information changed code generation.
3. cargo test --manifest-path <program>/Cargo.toml [TEST] with SBF_OUT_DIR and SBF_TRACE_DIR=<target>/pina/trace/traces set. Test output goes to stderr so --json and --folded keep stdout machine-readable. A failing test run exits with the test runner’s status; the traces recorded before the failure stay in the trace directory for --trace-dir.

--trace-dir skips all three steps and attributes the traces with the traced build from the project’s last run.

Reading the results

Every executed SBF instruction costs 1 CU, so the trace counts exactly what the program executed. The runtime charges syscalls separately and those charges are not in the trace: each syscall is listed by name, invocation count, and calling line, and only its 1-CU call instruction is counted.

Recordings that followed exactly the same instruction path are reported once, with every trace id. A profile is named after the program instruction whose discriminator it loaded from the instruction data (the loader passes its address in r2), and otherwise trace <id>. Profiles are ordered by name and then by cost, and repeated names get a #2 suffix, so identical recordings always produce identical output.

• Lines are the innermost source line of each instruction. Instructions the compiler attributed to line 0 are reported as having no line information.
• Functions report self and inclusive cost. Code that LTO inlined into entrypoint is attributed to the function it was written in through DWARF’s inlined-subroutine records; inlined frames carry DWARF’s short names, such as assert_writable or get<u8>.
• Stacks are physical call frames rebuilt from the trace’s call, callx, and exit instructions, each expanded into its inlined frames.

The text summary lists each profile’s ten most expensive lines, top functions, and syscalls, then prints the path of the HTML report at <target>/pina/trace/<lib-target>.html. The report is a single self-contained file with an instruction picker, a zoomable icicle chart of the call stacks, the hottest lines, and the sampled source files annotated with per-line cost. Source is read when the report is written. Paths of workspace members resolve against the workspace root; dependencies from a registry record paths relative to their own package (src/lib.rs), so their lines show numbers without source.

Debug information and code generation

Debug information can change SBF code generation, so the traced build is compared with the release build. When their .text sections differ the command warns with the number of differing instruction slots, and the JSON document records it under releaseBuild. Executed counts then describe the traced build and can differ slightly from the deployed program.

JSON trace document

--json emits a camelCase document with schemaVersion: 1: the program name, the SHA-256 of the traced executable, lineInfo, recordedTraces and skippedTraces, releaseBuild (or null), and an instructions array. Each instruction carries its name, the matched instruction and observed discriminator, traceIds, executedInstructions, syscallInvocations, unattributedInstructions, and lines, functions, syscalls, and stacks arrays.

Safety and failures

The command compares filesystem identity and refuses an output that is the input binary, a hardlink to it, or below a symbolic-link/reparse-point path. Reports are published atomically, so a failed write cannot truncate an existing destination or the input binary. Profiling also fails for unreadable files, invalid ELF data, binaries without an SBF text section, output creation errors, and JSON serialization errors. compare additionally fails closed for missing, unreadable, or malformed baselines, documents that are not profile reports, and unsupported baseline schema versions.

Rehearse an Upgrade

pina rehearse replays a deployed program’s real transactions against the binary you are about to ship, before you ship it. Every recent transaction runs twice on the same forked state, once against the deployed program and once against the candidate, and every difference in outcome, written account state, and compute units is reported.

# Rehearse the conventional artifact against the latest 25 devnet transactions.
pina rehearse --network devnet

# Build first, and replay a deeper sample of mainnet traffic.
pina rehearse --network mainnet --build --limit 100

# Rehearse an explicit binary against a custom endpoint.
pina rehearse --rpc-url http://127.0.0.1:8899 --program ./target/deploy/my_program.so

# Rehearse specific transactions instead of the latest ones.
pina rehearse --network devnet --signature <SIGNATURE> --signature <SIGNATURE>

Nothing is sent to the cluster and no project file is written. Pair it with pina migrations and pina deploy: migrations prove the new code can read old data, and a rehearsal proves it still behaves the same on the traffic your users actually send.

To gate the upgrade itself, run the rehearsal as part of the deployment with pina deploy --rehearse. It rehearses the exact artifact the deployment plan pins, against the cluster the deployment targets, and stops the deployment before anything is sent when behaviour changes or nothing could be compared.

How a rehearsal runs

1. Fetch. Pina confirms the program exists on the cluster (getAccountInfo), so a program that was never deployed fails before any Surfpool starts. It then asks the cluster for the program’s most recent signatures (getSignaturesForAddress, at confirmed commitment) and fetches each transaction exactly as it landed. With --signature, only the named transactions are fetched.
2. Fork. Pina starts a private Surfpool forked from the same RPC endpoint, on free loopback ports, inside a temporary directory, and waits up to a minute for it to answer. The fork is always stopped: on success, on error, on panic, and on Unix even when pina is interrupted or killed, because Surfpool runs under a small supervisor that stops it as soon as pina exits.
3. Freeze. Every account the transactions touch is loaded into the fork in one pass. Accounts that do not exist are marked offline, so the remote is never consulted again: both runs see one frozen snapshot, even on a busy cluster.
4. Baseline. Each signed transaction is profiled against the deployed program. Profiling executes on a throwaway copy of the fork, so nothing commits and every transaction sees the same snapshot.
5. Install. The candidate is written into the program’s own program-data account, as an upgrade would write it: the same account and upgrade authority, with the old executable’s tail zeroed.
6. Candidate. Each transaction is profiled again and compared with its baseline.

Two Surfpool behaviours shape the design:

• Profiling validates blockhash age. Real traffic carries blockhashes that expired long ago and would fail with Blockhash not found, so the fork runs with --skip-blockhash-check. Signature verification stays on: only authentic signed transactions are replayed.
• Surfpool hides failed program loads. When it cannot load an ELF, it logs the error and keeps executing the previously cached program, so a broken candidate could otherwise rehearse as “unchanged”. Pina confirms every program swap: it rewrites the program account with one extra lamport, which the runtime only stores after loading the ELF, and reads it back. A candidate the runtime rejects fails the rehearsal, because an upgrade to that ELF would be rejected the same way.

The fork’s clock never advances (--block-production-mode manual), so programs that read the Clock sysvar see the same time in both runs.

Reading the report

Each transaction gets one status:

Both runs execute the same signed transaction on the same snapshot, so any difference belongs to the binaries. In particular:

• A transaction that fails identically in both runs is skipped (failed_in_both). This is the common case for older traffic: an initialize whose account now exists, or a transfer from an account that has since been drained. It says nothing about the upgrade, so it is listed and never counted as a regression.
• A transaction that fails in both runs with different errors is an outcome change. Error codes are part of a program’s observable contract; clients and other programs branch on them.
• A transaction that failed in the baseline but succeeds with the candidate is an outcome change. The new code accepts something the deployed code rejects, which deserves review before it ships.
• A transaction Surfpool refuses to run is skipped (not_profiled) only when both runs refuse it identically. Surfpool refuses before the program executes, while it verifies signatures and loads accounts and lookup tables, so a refusal cannot depend on the binary: the same refusal twice comes from the forked state, such as a lookup table closed since. A refusal in only one run, or a different one in each, can only be the environment failing, and stops the rehearsal with exit code 1.

For state_changed transactions the report lists every writable account whose final state differs: lamports, owner, data length, and the data itself. For accounts the program owns, the account type is matched by discriminator and the differing bytes are decoded field by field from the project’s IR, baseline value first:

2y8JkzTSum83V1nSkpy64WHZv1S8pqWFMJ8YRxP3pqtqgwTBdyKGMwZ1rBsg4auwogTkpoJunSjxcBnj8XG4EECP  state_changed  [increment]
  compute units 473 -> 473 (0)
  account 14P1xLXPqLmxipH1tno2oKiS9GQPZJosNuK1AJPe4Ffn (CounterState)
    count: 4 -> 5

Fixed PinaPod layouts decode integers, booleans, addresses, and floats, and the discriminator and migration-version header are named too. Compact layouts, and bytes no field covers, are reported as byte ranges. Account differences are computed only when both runs succeed, because a failed run commits no state. For outcome changes the report shows the end of each run’s logs instead.

The compute-unit table covers transactions that succeeded in both runs, per instruction of your program: minimum, median, and maximum for each binary, and the change in the median. The median of an even sample is the lower middle value.

Exit status

This follows the CLI’s convention for comparisons (pina profile compare, pina idl diff, pina verify check): 2 means the comparison completed and found a difference. Clap also exits 2 for invalid arguments, but then prints usage to stderr and nothing to stdout. Use --allow-changes once the differences are reviewed and intended.

A rehearsal that compares nothing is never a pass, so 0 always means the upgrade was exercised. With exit code 3 the report still prints, and its skipped section explains each transaction. --allow-changes does not change it: there are no changes to accept. Rehearse more or newer traffic with --limit or --signature, or treat 3 as acceptable in automation for a program that has no traffic yet.

JSON report

--json prints one stable document with camelCase keys. Progress lines go to stderr, so stdout stays a single document.

{
	"schemaVersion": 1,
	"cluster": "devnet",
	"programId": "GJQcuWrT2f3f4KNuJcXhhwUa1ZQTYbxzzJ1hotzKu8hS",
	"deployedSha256": "1e62…",
	"candidateSha256": "d380…",
	"slot": 2001,
	"summary": {
		"total": 4,
		"unchanged": 0,
		"cuChanged": 0,
		"stateChanged": 3,
		"outcomeChanged": 0,
		"skipped": 1
	},
	"instructions": [
		{
			"name": "increment",
			"samples": 3,
			"baseline": { "min": 473, "median": 473, "max": 473 },
			"candidate": { "min": 473, "median": 473, "max": 473 },
			"medianDelta": 0
		}
	],
	"transactions": [
		{
			"signature": "2y8J…",
			"status": "state_changed",
			"skip": null,
			"instructions": [
				{ "name": "increment", "baselineUnits": 473, "candidateUnits": 473 }
			],
			"baseline": { "error": null, "computeUnits": 473 },
			"candidate": { "error": null, "computeUnits": 473 },
			"accounts": [
				{
					"address": "14P1…",
					"accountType": "CounterState",
					"baseline": { "lamports": 967440, "owner": "GJQc…", "dataLen": 11 },
					"candidate": { "lamports": 967440, "owner": "GJQc…", "dataLen": 11 },
					"fields": [{ "name": "count", "baseline": "4", "candidate": "5" }],
					"byteRanges": [],
					"omittedByteRanges": 0
				}
			],
			"logs": null
		}
	]
}

Every key is always present; absent values are null. status and skip.reason use the snake_case spellings shown in the status table. Executable hashes are SHA-256 with trailing zero padding removed, matching solana-verify, so a deployed program’s zero-padded program data and its local .so hash the same. The schemaVersion changes only with a breaking change to the document.

Requirements and limits

• Surfpool 1.6.0 or newer must be on PATH, or named by PINA_SURFPOOL. Pina checks the version before reading the project.
• On Windows, Surfpool runs as a direct child: it is stopped on every normal exit path, but a console interrupt that terminates pina while Surfpool is still starting can leave it running.
• The deployed program must use the upgradeable loader, as solana program deploy and pina deploy do.
• The program ID is the project’s declare_id!. The candidate defaults to <cargo-target>/deploy/<library-name>.so; --program names another file and --build runs the same build as pina build first.
• Transactions replay against the cluster’s current state, not the state they originally saw, and each one sees the same snapshot: state written by one is not visible to the next.
• Legacy and v0 messages are supported. A transaction the RPC no longer returns is skipped as unavailable; one it cannot return in a supported version is skipped as undecodable.
• --limit accepts 1 to 1000, a single getSignaturesForAddress page.

Network safety

Pina only reads from the cluster: one getAccountInfo request for the program, one getSignaturesForAddress request, and one getTransaction request per transaction, each sent exactly once with a timeout. A failed request stops the rehearsal with exit code 1 instead of being retried, so a rate-limited endpoint is not hammered; use a dedicated RPC endpoint or a smaller --limit when a public endpoint refuses. That includes JSON-RPC errors returned inside an HTTP 200 response, such as an unhealthy node (-32005) or a provider’s rate limit. The one exception is -32015, the RPC’s answer for a transaction it cannot encode in a supported version: that transaction is skipped as undecodable. Redirects are not followed. The fork fetches each account the transactions touch from the same endpoint once.

A custom --rpc-url must use HTTP or HTTPS with a host. Pina rejects user information, query parameters, fragments, and control characters. Surfpool receives the URL as a child-process argument, where local process inspection can reveal it, so never put a secret anywhere in the URL, including its path. Reports show only the URL’s origin.

Options

Run pina rehearse --help for the authoritative command contract.

pina deploy

pina deploy resolves and validates a Pina program deployment, displays the complete operation, and delegates the write to the Solana CLI. It never inherits a cluster from Solana configuration.

pina deploy [OPTIONS] --upgrade-authority <KEYPAIR> --payer <KEYPAIR> \
  --cluster <CLUSTER|URL>

Run pina deploy --help for the authoritative option list.

Rehearse first

Before upgrading a program that already has users, pass --rehearse. After printing the plan and before the confirmation prompt, Pina replays the target cluster’s recent transactions against the deployed program and the planned artifact on a private Surfpool fork, exactly as pina rehearse does, and prints the rehearsal report below the plan:

pina deploy --build --rehearse --cluster devnet \
  --upgrade-authority ./keys/devnet-authority.json \
  --payer ./keys/devnet-payer.json

Nothing is sent while the rehearsal runs, and its result decides whether anything is sent at all:

A rehearsal also proves the runtime loads the new ELF, so an upgrade the cluster would reject fails before anything is sent.

The rehearsal replays the cluster the deployment writes to. A named cluster rehearses against its public endpoint (localnet is http://127.0.0.1:8899). A custom URL is rehearsed through the same endpoint, after the URL checks pina rehearse --rpc-url applies, and the report names it by its origin only. --rehearse-limit <N> replays the N most recent transactions, from 1 to 1000 (default 25). --rehearse-limit and --allow-rehearsal-changes require --rehearse.

The rehearsed bytes are the deployed bytes. Pina reads the planned artifact once, checks it against the SHA-256 fingerprint the plan pinned, and rehearses that copy; with --build, that is the artifact the build just produced. It also refuses a project whose declare_id! no longer matches the planned program ID. The deployment later checks its private snapshot against the same fingerprint (see Build and external requirements), so an artifact replaced during or after the rehearsal stops the deployment instead of reaching the cluster.

With --dry-run, a rehearsal reports what the deployment would do and exits with the same codes, so CI can gate an upgrade without deploying it. With --dry-run --json, the plan object gains a rehearsal key holding the complete pina rehearse --json report. Rehearsal progress goes to stderr in every mode. A rehearsal stopped by a first deployment or an operational error prints no report, and with --json no document.

Safe planning

Review a deployment without building, contacting an RPC endpoint (unless --rehearse replays its traffic), or invoking the Solana CLI:

pina deploy \
  --project ./programs/counter_program \
  --cluster devnet \
  --upgrade-authority ./keys/devnet-authority.json \
  --payer ./keys/devnet-payer.json \
  --dry-run

Use --dry-run --json for agents and CI. The plan includes the canonical project, artifact, program keypair, declared program ID, upgrade authority, fee payer, cluster, complete RPC endpoint, acknowledgement policy, and ordered command argument vector. Custom URL hosts and paths are intentionally preserved, so they must not contain secrets.

Dry runs perform no build or deployment. Consequently, --dry-run conflicts with --build, --yes, and --allow-mainnet.

Input resolution

--project accepts a project directory or any directory below it. Pina uses the same project discovery as pina build: the nearest ancestor pina.toml, then unambiguous Cargo metadata as a fallback. The library target name and Cargo metadata target directory resolve:

• <cargo-target>/deploy/<lib-name>.so
• <cargo-target>/deploy/<lib-name>-keypair.json

Use --program or --program-keypair to override either conventional path. --program conflicts with --build. Every resolved file is canonicalized and must be a regular file. Keypair files cannot exceed 4 KiB and must contain a valid 64-byte Solana JSON keypair. On Unix, Pina rejects keypairs with any group or world permission bits; chmod 600 <keypair> is the recommended mode. Pina cannot inspect equivalent Windows ACL policy, so Windows operators must restrict keypair access with the operating system’s ACL tooling. The program keypair address must match the program’s declare_id!; deploy never generates or silently replaces an identity.

--upgrade-authority and --payer are always explicit. Pina does not inherit wallet paths from Solana configuration and does not store deployment credentials in pina.toml.

Targets and confirmation

One explicit target is required:

• --cluster localnet
• --cluster devnet
• --cluster testnet
• --cluster mainnet-beta
• --cluster <HTTP(S)-URL>

Custom endpoints reject URL user information, query parameters, and fragments. The Solana CLI accepts its RPC endpoint through --url, so every accepted host and path is visible in the dry-run plan, confirmation, and operating-system process listings. Pina cannot distinguish a provider token embedded in a path from a legitimate endpoint path. Never put a secret anywhere in a custom URL; prefer a named cluster when possible.

Local endpoints execute after displaying the plan. Every remote endpoint prompts the operator to type deploy. Non-interactive remote deployment fails before starting a child process unless --yes is supplied. Named mainnet and every custom remote endpoint additionally require --allow-mainnet, because Pina cannot prove which Solana cluster an arbitrary URL serves. The flag is rejected for localnet, devnet, testnet, and custom loopback endpoints.

Local means the parsed host is a loopback address (localhost, 127.0.0.0/8, or [::1]), so spellings such as localhost.example.com, 127.0.0.1.nip.io, or http://127.0.0.1@example.com are classified as remote or rejected. A loopback port is still not proof of a local cluster: an SSH tunnel or proxy that forwards 127.0.0.1:8899 to a live cluster would skip confirmation and record no publication receipt. Deploy to a forwarded cluster through its real URL instead.

Build and external requirements

Pina validates and redacts the explicit target before project discovery or any build begins. --build then invokes the same in-process project build workflow as pina build before Pina resolves and displays the final deployment plan. It does not search PATH for another Pina executable. A failed build stops immediately.

After confirmation, Pina copies the artifact and every keypair into a private, owner-only temporary directory (pina-deploy-*, mode 0700, keypairs 0600), revalidates the copies against the declared program ID and the SHA-256 fingerprints taken at planning time, and hands the child those copies rather than the original paths. A file replaced after the plan was displayed is therefore detected, and one replaced after the final check cannot reach the child. The displayed plan shows the paths you passed; the child’s argument vector names the snapshot copies.

Without --remote-command, deployment requires the external solana executable from Agave on PATH; a custom deploy command does not. Pina runs every modeled command from the resolved project root, passes an argument vector directly rather than a shell command string, and closes the child’s standard input after Pina handles confirmation. The npm-distributed Pina binary supports platforms on which Agave may not be available, so verify the local Agave installation before depending on deployment automation.

Custom deploy commands

--remote-command <COMMAND> replaces solana program deploy with sh -c <COMMAND> (cmd /C <COMMAND> on Windows), for platforms that deploy through their own tooling. Every other safeguard still applies: target policy, confirmation, snapshot validation, and publication receipts. The deployment facts reach the command only as environment variables, never interpolated into the command string:

Quote the variables inside the command ("$PINA_DEPLOY_PAYER"), and treat an exit status of zero as the command’s claim that the deployment succeeded: Pina records the publication receipt on that claim alone.

Migration publication receipts

For a program with checked-in migrations, a deployment to any non-loopback target freezes the ABI versions it ships. Before starting the deploy program, Pina writes a pending record to migrations/publications.json; after the program succeeds, it appends that record as a receipt pinning the schema of every version it shipped. From then on pina migrations create advances those contracts to a new version instead of rewriting them. --record-publication opts a loopback deployment into the same lifecycle, which is how a Surfpool run exercises it.

If the deploy program starts and then fails, the pending record stays, because the program may already be live. Rerunning the exact same deployment reconciles it, and pina migrations reconcile explains the state. If the deploy program never started, for example because solana is not installed, Pina discards the pending record it just wrote and says so, because nothing can have reached the cluster. A pending record left by an earlier attempt is never discarded this way.

Output contract

Without --json, stdout contains the plan, the rehearsal report with --rehearse, and completion status. Diagnostics, confirmation, and child failures use stderr. --dry-run --json emits one JSON object to stdout and no progress text. The full accepted RPC host and path appear in both formats and in the Solana argument plan. Missing files, malformed keypairs, program-ID mismatches, ambiguous projects, invalid RPC URLs, rejected confirmations, missing executables, signaled children, and non-zero child exits all fail closed.

Automation and Agent Usage

The CLI help and stream contracts are designed to let an agent discover capabilities without reading repository source.

Discovery protocol

Use this sequence before constructing a command:

pina --version
pina --help
pina <command> --help

For client generation, inspect the command and its ecosystems:

pina generate --help

For deployment verification, inspect the group and selected leaf:

pina verify --help
pina verify check --help
pina verify record --help

For project testing and a persistent local network:

pina lint --help
pina test --help
pina dev --help
pina rehearse --help

For project diagnostics, failed transactions, and identity:

pina doctor --help
pina explain --help
pina keys --help

For write-lock contention between instructions, and its interactive map:

pina locks --help
pina map --help

For framework and extractor constraints:

pina docs
pina docs pina-overview
pina docs pina-idl

Do not infer flags from examples alone. The command-specific --help output is the authoritative interface and includes defaults, output routing, requirements, and examples.

Machine-readable workflows

Generate and validate an IDL through stdout:

pina idl --path ./programs/counter_program --compact > /tmp/counter.json
jq -e . /tmp/counter.json

Write directly to a known artifact path:

mkdir -p ./artifacts
pina idl \
  --path ./programs/counter_program \
  --output ./artifacts/counter.json

Profile a binary as JSON:

pina profile ./target/deploy/counter_program.so --json > /tmp/profile.json
jq -e '.functions | type == "array"' /tmp/profile.json

Trace executed compute units from the project’s Mollusk tests as JSON. Build and test output goes to stderr, so stdout stays a single JSON document; a failing test run exits with the test runner’s status:

pina profile trace --json > /tmp/trace.json
jq -e '.schemaVersion == 1 and (.instructions | length > 0)' /tmp/trace.json
jq '.instructions[] | {name, executedInstructions, syscalls}' /tmp/trace.json

Diff the current build against a saved baseline; the exit status is 2 when a total CU regression reaches both --fail-cu and --fail-percent:

pina profile compare /tmp/profile.json --json > /tmp/comparison.json
jq -e '.status == "unchanged" or .status == "improved"' /tmp/comparison.json

Rehearse an upgrade against recent traffic. Gate on the exit status first: it is 0 only when at least one transaction was compared and none changed its outcome or written account state, 2 when behaviour changed, 3 when nothing could be compared, and 1 for an operational failure with empty stdout. A JSON check must require the same three conditions, so a report whose only changes are account state, or that compared nothing, never passes:

pina rehearse --network devnet --json > /tmp/rehearsal.json
jq -e '.schemaVersion == 1 and .summary.total > .summary.skipped and .summary.stateChanged == 0 and .summary.outcomeChanged == 0' /tmp/rehearsal.json

Report write-lock contention through the versioned JSON contract, and gate CI on hotspots that [locks] allow does not accept:

pina locks --json > /tmp/pina-locks.json
jq -e '.hotspots | map(select(.allowed | not)) | length == 0' /tmp/pina-locks.json
pina locks --deny-hotspots

Read the program map’s data, the locks document plus per-instruction and per-account-type detail, without writing its HTML page:

pina map --json > /tmp/pina-map.json
jq -e '.instructionDetails | length > 0' /tmp/pina-map.json

Diagnose project readiness through the versioned JSON contract:

pina doctor --json > /tmp/pina-doctor.json

Read-only identity inspection is also JSON-safe:

pina keys show --json > /tmp/pina-keys.json

Explain a failed transaction through the versioned JSON contract. A saved getTransaction result works offline:

pina explain --transaction-file ./failed.json --json > /tmp/pina-explain.json
jq -e '.status == "succeeded" or (.candidates | type == "array")' /tmp/pina-explain.json

These commands write no progress or ANSI styling to stdout. Doctor check IDs and statuses are stable agent inputs; do not parse the human report when JSON is available.

Inspect a deployment without executing a child process:

pina deploy \
  --project ./programs/counter_program \
  --cluster devnet \
  --upgrade-authority ./keys/devnet-authority.json \
  --payer ./keys/devnet-payer.json \
  --dry-run --json > /tmp/deploy-plan.json
jq -e '.program_id and .commands' /tmp/deploy-plan.json

Rehearse the planned upgrade in the same step. --rehearse replays the target cluster’s recent traffic against the exact artifact the plan pins and adds the pina rehearse --json report under a rehearsal key; the plan’s own keys are unchanged. Gate on the exit status first: 0 when the rehearsal compared at least one transaction and none changed, 2 when behaviour changed, 3 when nothing could be compared or the program is not deployed yet (no document is printed for a first deployment), and 1 for an operational failure:

pina deploy \
  --project ./programs/counter_program \
  --cluster devnet \
  --upgrade-authority ./keys/devnet-authority.json \
  --payer ./keys/devnet-payer.json \
  --rehearse --dry-run --json > /tmp/deploy-plan.json
jq -e '.rehearsal.schemaVersion == 1 and .rehearsal.summary.total > .rehearsal.summary.skipped and .rehearsal.summary.stateChanged == 0 and .rehearsal.summary.outcomeChanged == 0' /tmp/deploy-plan.json

Automation rules

• Check the exit status before consuming output.
• Run pina lint before review; use --fix only when working-tree edits are authorized and always inspect the diff.
• Treat stderr as diagnostics and progress, not as part of IDL JSON.
• Use explicit paths; relative paths depend on the process working directory.
• Create the parent of an idl --output file before invoking the command.
• Treat Codama output roots as replaceable generated directories.
• Use repeated --example flags instead of assuming comma-separated parsing.
• Inspect pina docs before requesting a topic.
• Never use the input .so path as the profile output path.
• Treat exit code 2 from verify check or verify record as a verified hash mismatch, not an operational failure.
• Treat exit code 2 from rehearse as a completed rehearsal that found behaviour changes; read transactions[].status from the JSON report. Exit code 3 means no transaction could be compared, so nothing was verified; it is never a pass. Exit code 1 is an operational failure with empty stdout. Never pass --allow-changes until every state_changed and outcome_changed transaction has been reviewed.
• pina rehearse sends each RPC request once and stops on the first failure. Do not loop it against a rate-limited public endpoint; use a dedicated endpoint or a smaller --limit.
• Run pina build --verify first and pass its printed content-addressed JSON path to pina verify record --build-record.
• Never infer a repository, revision, cluster, authority, or uploader. The build record binds source provenance; every network target and signing identity remains explicit.
• Use --yes only for a reviewed record plan. Mainnet submissions additionally require --acknowledge-mainnet; transaction export requires neither flag.
• Never put secrets in a custom RPC URL. Pina passes the RPC origin to solana-verify as argv.
• Treat pina explain candidates by their confidence: only confirmed is proven by the transaction, checked_against_current_state reads state that may have changed after the transaction, and possible needs runtime values. Exit code 0 means an explanation was produced, including for a transaction that succeeded.
• pina explain queries localnet unless --network or --rpc-url names another endpoint, and never retries a request.
• Use pina test --unit when only native Rust or Mollusk tests are required.
• Treat a missing tests/surfpool package or built .so as a failed integration setup, not a skip.
• pina dev is offline unless --network or a credential-free HTTP(S) --rpc-url is explicitly supplied. The URL is visible in Surfpool’s process arguments, so never place a secret anywhere in it.
• Always inspect deploy --dry-run --json before remote automation.
• Never pass deploy --yes until the exact target, program ID, authority, payer, and command plan have been reviewed.
• Prefer deploy --rehearse for upgrades of programs with traffic. Exit codes 2 and 3 mean the deployment stopped before anything was sent. Never pass --allow-rehearsal-changes until every state_changed and outcome_changed transaction has been reviewed, and do not treat 3 as a pass: deploy a first version without --rehearse instead.
• Never put a secret anywhere in a custom deploy RPC URL. Pina rejects user information, queries, and fragments, but accepted hosts and paths remain visible in plan output and process listings because Solana receives the endpoint through --url. Prefer named clusters.

Stable verification

CLI help is snapshot-tested at every command level. IDL stdout is also regression-tested as valid JSON. The book is built by verify:docs and published by the repository’s GitHub Pages workflow, so command changes should update help tests and this reference in the same change.

Agent Skill

@pina-rs/skill packages task-focused guidance for agents that create, audit, or maintain Pina programs. It covers project setup, account and instruction authoring, PDA and authority validation, IDL and client generation, SBF profiling, tests, and compatibility review.

Install

npm install --global @pina-rs/skill
pina-skill --install

The installer copies the runtime skill to $CODEX_HOME/skills/pina when CODEX_HOME is set, otherwise ~/.codex/skills/pina. It refuses to replace an existing directory, so local skill changes cannot be lost silently.

Inspect the packaged source or manual installation details with:

pina-skill --print-path
pina-skill --print-install

Scope

The skill is intentionally specific to Pina. Its entrypoint establishes the program invariants that matter across tasks:

• preserve no_std compatibility and the project’s feature boundary;
• validate accounts before casts, mutation, resize, close, or CPI;
• construct account-management and generated CPI operations as documented structs, then call invoke or invoke_signed;
• keep discriminators and PDA seed namespaces explicit and stable;
• treat generated IDLs and clients as reviewed public contracts;
• verify changes at the smallest meaningful layer before running the full project suite.

Detailed guidance is split into focused references for setup, program authoring, migrations, CLI and code generation, and testing. Agents load only the reference needed for the current task.

Package layout

Core Concepts

Discriminator layout (raw bytes)

Pina injects discriminator bytes as the first field of every #[account], #[instruction], and #[event] native schema. PinaPod then generates a separate zero-copy storage view with the same discriminator-first wire layout.

At runtime the parser checks the exact schema size and discriminator, delegates recursive content validation to PinaPod, and returns the generated TypeZc view under the runtime’s borrow guard.

offset | size | meaning
------ | ---- | -------
0      | N    | discriminator (N = BYTES of enum primitive: 1/2/4/8)
N      | ...  | payload fields

This contract is what enables:

• deterministic Type::SIZE checks,
• zero-copy validation with as_account() / try_from_bytes(),
• alignment-one storage fields generated by PinaPod.

Why this is safer than implicit external headers

External fixed-size headers require separate offset logic in each parse path. With an auto-injected first field, the PinaPod derive owns one schema and one validated storage layout. Pina does not manually cast the native schema or expose its object representation.

Discriminator width and compatibility

The enum primitive width controls both on-chain layout and migration surface.

• Width is set on the discriminator enum using #[discriminator(primitive = u8)] (default u8).
• Allowed widths are u8, u16, u32, and u64.
• The maximum practical width is capped at 8 bytes for zero-copy safety.

Discriminators and ABI migrations

Add migrations to an account, instruction, or event attribute to opt one contract into a framework-owned version field, or opt whole contract kinds in when you record the history:

pina migrations create --auto true # or --auto accounts,events,instructions

--auto accepts true, false, or a comma-separated list of accounts, events, and instructions. pina migrations create records the policy in migrations/manifest.json, its only home, and snapshots every contract of the listed kinds; a later run without the flag keeps the recorded policy. pina.toml holds no migration policy. Macros read the policy from the manifest, so a new struct still fails the build with “run pina migrations create” until it has a snapshot. Once a policy is recorded, create also scaffolds a build.rs emitting cargo:rerun-if-changed=migrations/manifest.json, so flipping the policy re-expands every contract without editing source. Add migrations = false to keep one contract out of an auto policy; removing an envelope the manifest already records is an error instead of a silent opt-out, because stripping an envelope is itself a wire-format change.

The policy gives accounts and events the version field. It records each instruction as a snapshot without one: the payload keeps its [discriminator][payload] wire format, and the build fails when the struct drifts from the snapshot. Add migrations to an #[instruction] to give that instruction the version field and adjacent transitions instead; the #[discriminator(entrypoint)] dispatcher then converts an older payload to the current layout before the handler runs.

Pina places the version field immediately after the discriminator. The accepted encodings are u8, u16, and u32; u8 is the default and the recommended choice. Versions are tracked per contract, not per program: each account, instruction, and event owns an independent history that starts at version 0, so u8 gives every contract its own 255-version budget. Rewriting one contract 255 times is not a realistic outcome, and the narrower field costs one byte in every enveloped account. Choose a wider encoding with pina migrations create --version-type u16 (or u32) before the first release only when you expect a single contract to exceed 255 versions. The width is program-wide, recorded as versionType in the manifest, and freezes at the first published release: after that the flag fails instead of widening it. Any other value, including u64, is rejected with an error naming the supported widths. Discriminator width is a separate setting, and that one does support u64.

Run pina migrations create before a release. Pina updates the replaceable draft when the current version is unpublished. After pina deploy records a non-local publication, the next schema change creates a new version, with an adjacent transition for an account or an enveloped instruction; the payload of a published snapshot-only instruction cannot change. Normal builds run pina migrations check and fail on drift, incomplete manual transitions, or changed published code.

An old instruction can omit only newly appended optional accounts. Pina does not synthesize signers, writable privileges, PDAs, or required accounts. Any change to an existing process slot requires a new discriminator.

Historical events are immutable, so Pina versions events instead of migrating them. The program emits only the current version. Generated clients decode each earlier version with its own schema, as a separate <Event>V<n> event, and a log record whose version no generated event describes fails instead of being misread.

Discriminator layout decision matrix

The discriminator strategy determines byte layout, parser guarantees, and cross-protocol compatibility.

Raw discriminator width by use-case

• Discriminator width only affects the first field bytes.
• Widths above 8 are rejected at macro expansion time.
• Wider discriminators improve variant space, but increase CPI payload and account rent by the exact number of bytes.
• These widths describe discriminators only. The migration version envelope is a separate setting and accepts u8, u16, or u32 — never u64.

Zero-copy account models

#[account] and #[instruction] keep the declared Rust type as a native schema and derive a separate PinaPod TypeZc storage view. Checked loaders validate the complete byte slice before returning that in-place view. The native schema itself is never reinterpreted as bytes.

Closed macro-generated schema grammar

Pina’s audited zero-copy boundary is the code generated by #[account], #[instruction], and #[event]. Those macros accept only representations whose alignment, size, initialization, and bit validity Pina can prove:

• native integer scalars and bool,
• Pina’s PodU*, PodI*, and PodBool wrappers,
• Pina’s exact Address type,
• [u8; N] with a literal length,
• [T; N] typed arrays where T is any other fixed grammar type and N is a literal length; storage is [PodT; N] little-endian with no length prefix, and validation recurses per element. Nested arrays such as [[u8; 4]; 2] compose,
• String<N> and PodString<N, PFX> with literal capacities and prefix widths,
• Vec<T, N> and PodVec<T, N, PFX> where T has a fixed audited representation,
• Option<T> where T has a fixed audited representation,
• with the floats feature: f32 and f64, stored as the bit pattern of their backing little-endian integer, and fixed-point FixedI*<Frac>/FixedU*<Frac> types from the pinned fixed crate. See Float and Fixed-Point Fields.

The fixed grammar is recursive through arrays, String, Vec, and Option. PinaPod fully initializes collection capacity and validates each active nested element. The macros still reject generics, arbitrary custom ZcField mappings, char, NonZero*, and representations whose alignment or bit validity Pina cannot prove.

Compact accounts use a narrower top-level grammar because tails need generated offset and patch logic. See Compact Accounts for the accepted forms.

Direct PinaPod derives and manual PinaAccount or PinaPodFixed implementations remain available for advanced integration, but they are outside Pina’s audited macro-generated contract. Implementing PinaPodFixed is unsafe; authors must uphold PinaPod’s bit-validity, alignment, initialization, size, validation-order, and aliasing invariants.

The optional crate = ... macro argument is path configuration for renamed dependencies. It must resolve to Pina itself, or to a transparent re-export of the same crate; it is not an extension point for substituting another derive or trait implementation universe.

Account validation chains

Validation methods on AccountView are composable and preserve the receiver type:

#![allow(unused)]
fn main() {
account.assert_signer()?.assert_writable()?.assert_owner(&program_id)?;
}

A chain that starts with &AccountView stays shared, while a chain that starts with &mut AccountView stays mutable. This keeps writability explicit without losing access to as_account_mut() later.

Use assert_program() when you explicitly validate a program account. Static .invoke() and .invoke_signed() builders encode their program ID. Pinocchio Token’s .invoke_with_program() and .invoke_signed_with_program() methods validate their supplied ID with Program::verify(). Neither form needs a preceding account assertion.

If you call .invoke_with_unverified_program() or .invoke_signed_with_unverified_program(), validate the exact supplied account first against a const or immutable static whose type contains no interior mutability, or an unmodified local alias of one. An expected ID supplied through instruction data is attacker-controlled and does not authenticate the target. A const or static whose type contains UnsafeCell — including a const of reference type aliasing an interior-mutable static — can be rewritten at runtime and is rejected as provenance for the same reason. Prefer Pina’s assert_program(), propagate assertion failure, and call the method directly. The lint requires validation on every continuing path. You can bind or chain from the account value returned by the assertion. Success-side Result callbacks, assignments, mutable borrows, &mut self method calls, and closures that may replace the validated binding invalidate the proof. The lint also rejects storing an unverified CPI method as a function value because doing so hides the target argument from its local proof.

When you need sysvar data, prefer Pinocchio’s checked typed loaders:

#![allow(unused)]
fn main() {
let clock = Clock::from_account_view(clock_account)?;
let rent = Rent::from_account_view(rent_account)?;
let instructions = Instructions::try_from(instructions_account)?;
}

These loaders validate the sysvar address while parsing. Their results can flow through normal Rust extraction, adapters, tuples, patterns, and control flow without extra assertions. Pina instead rejects constructors that do not validate identity. These include the Clock and Rent byte constructors, Instructions::new_unchecked, and SlotHashes::new or new_unchecked. Call these constructors directly. Storing one as a function value is also rejected so the unvalidated source remains visible.

Keep assert_sysvar() for identity-only checks and deliberate raw data access. A raw-access proof must call Pina’s method with the matching pina_sdk_ids::sysvar::<name>::ID. For a generic binding such as epoch_sysvar, the recognized canonical ID supplies the otherwise missing identity. Enforce its Result on every continuing path. You can bind or chain from the account value returned by the assertion. Success-side Result callbacks, assignments, mutable borrows, &mut self method calls, and closures that may replace the asserted binding invalidate the proof. Reviewed manual parsing also needs a narrow lint allowance on its constructor.

Typed account conversions

Traits in crates/pina/src/impls.rs provide typed conversion paths from raw AccountView values into strongly typed account states. as_account() returns Ref<T> and as_account_mut() returns RefMut<T> borrow guards. The type aliases LoadedAccount<'a, T> and LoadedAccountMut<'a, T> are provided for Ref<'a, T> and RefMut<'a, T> respectively, offering a more descriptive name for guard-backed typed account access.

A fixed account with a stored #[pda(bump = ...)] generates Type::load_pda and Type::load_pda_mut. These methods combine typed account validation with stored-bump address validation and return the same guard types. Prefer them over an assert_type → Type::assert_seeds → as_account* sequence when the handler immediately needs the state; the sequence recursively validates bounded fields more than once.

Use this order for fixed accounts:

1. Use generated load_pda or load_pda_mut for a stored-bump PDA when the handler needs typed fields.
2. Use as_account or as_account_mut for another fixed account when the handler needs typed fields.
3. Use assert_type only when the handler needs to validate an existing fixed account without loading its fields.

All three paths validate the owner, discriminator, exact account size, and active nested values. assert_type releases its data borrow before returning. It is therefore a moment-in-time validation, not a guard for a later raw cast or mutation. Do not call it before either typed-loader path.

A compact account with a stored bump generates two closural loaders. Type::with_stored_bump_pda validates ownership, the compact representation, and the address the stored bump derives before it runs the closure, using a single derivation. Type::with_checked_pda searches for the canonical bump instead and additionally rejects a stored bump that is not canonical, which is what catches a shadow account created at a noncanonical bump; prefer it when an untrusted caller chooses which account the handler loads. The runtime data borrow remains active for the closure in both, so the compact view cannot outlive its validated bytes. Keep assert_compact_type and generated assert_seeds for validation-only paths that do not need the compact view.

Account cursors

AccountsCursor is the runtime layer used by #[derive(Accounts)]. It advances through the account slice from left to right and rejects writable aliases for mutable accounts parsed individually through next_mut(), without heap allocation. Alias checks look forward: a mutable field must not reappear in any later slot. A readonly field followed by a mutable field for the same account is accepted, because an authority that signs readonly and also pays is one account in two slots, and the runtime marks both slots writable. When two fields must be distinct accounts, compare their addresses explicitly instead of relying on declaration order. Accounts are compared by AccountView identity: the entrypoint deserializer makes every duplicate slot a copy of the original view, so each check is a single pointer comparison. Explicit trailing-account capture via #[pina(remaining)] preserves account order and rejects duplicate mutable addresses by default; mutable trailing slices also reject readonly accounts. When duplicate addresses are an intentional part of the instruction contract, #[pina(remaining, distinct = false)] restores pass-through aliasing and the field must have a doc comment explaining the invariant that makes it safe. A missing trailing Option<&AccountView> or Option<&mut AccountView> parses as None, which lets a current process accept the shorter positional prefix sent by an older client. An optional field before another positional field still occupies a slot.

Optional accounts

Account fields wrapped in Option mark a slot as optional. Trailing optional fields may be omitted entirely; optional fields before another positional field keep their slots:

#![allow(unused)]
fn main() {
#[derive(Accounts)]
pub struct MakeAccounts<'a> {
	pub maker: &'a mut AccountView,
	pub escrow: Option<&'a mut AccountView>,
	pub witness: Option<&'a AccountView>,
}
}

Only Option<&'a AccountView> and Option<&'a mut AccountView> are supported; other inner types fail to compile.

Within a positional list, the absent convention is the executing program’s own address. Generated Codama clients may fill an omitted optional slot with a readonly account meta pointing at the program address, and on-chain parsing maps it back to None. A trailing optional suffix may instead be left out, including by an older client that predates those fields. Because the filler is readonly, provided values still enforce their declared writability through next_mut_opt().

Program logic branches on presence with plain pattern matching. Load the account directly when the branch needs its fields:

#![allow(unused)]
fn main() {
if let Some(escrow) = self.escrow {
	let escrow = escrow.as_account::<EscrowState>(&ID)?;
	// Read validated fields through `escrow`.
}
}

Optional signers are validated only when present (if let Some(witness) = self.witness { witness.assert_signer()?; }). In generated clients an optional signer input is a TransactionSigner, so providing one attaches the signature automatically.

Instruction authoring tips

• Entry points should accept &mut [AccountView] and dispatch with Accounts::try_from((program_id, accounts))?.process(data).
• Use &AccountView for read-only accounts and &mut AccountView only when you need mutable loaders, direct lamport mutation, close_* helpers, or writable IDL inference.
• &mut AccountView declares and enforces a writable slot. Use assert_writable() or #[pina(validate(writable))] only when a shared &AccountView must arrive writable.
• as_account() / as_account_mut() return Ref<T> / RefMut<T> borrow guards. Copy out the fields you need and drop(...) the guard before CPIs or later mutable borrows.
• Prefer generated load_pda* methods for stored-bump fixed PDAs, then as_account* for other fixed accounts. Use assert_type only when no typed fields are needed; do not call it before a typed loader.
• Keep validation chains direct inside process(self, ...) when possible. That makes audits easier and gives pina idl the clearest signal for signer, writable, PDA, and default-account inference.

Entrypoint model

nostd_entrypoint! wires BPF entrypoint plumbing while preserving no_std constraints for on-chain builds.

A program routed by #[discriminator(entrypoint)] can use dispatch_entrypoint!(Instruction) instead. It reads the instruction before any account, then walks only the accounts the routed struct reads, which makes most programs smaller and cheaper to run. See Program size for when each entrypoint measures smaller.

Pod types

All types are alignment-one byte-backed values that implement PinaPod’s ZcElem and ZcValidate contracts. The floats feature adds PodF32 and PodF64, which store IEEE-754 bit patterns in four and eight bytes; they validate any bit pattern and decode an all-zero field as +0.0.

Arithmetic operators (+, -, *) on Pod integer types use wrapping semantics in release builds for CU efficiency and panic on overflow in debug builds. Use checked_add, checked_sub, checked_mul, checked_div where overflow must be detected in all build profiles.

Each Pod integer type provides ZERO, MIN, and MAX constants.

This means you can write ergonomic code like:

#![allow(unused)]
fn main() {
my_account.count += 1u64;
let fee = balance.checked_mul(3u64).unwrap_or(PodU64::MAX);
}

Instruction introspection

The pina::introspection module provides helpers for reading the Instructions sysvar at runtime. This enables:

• Program checks: verify that the transaction-level instruction at the current index targets the expected program (assert_current_instruction_program_id). The Instructions sysvar cannot distinguish self-CPI, so this is not a no-CPI or flash-loan guard.
• Transaction inspection: count instructions (get_instruction_count) or find the current index (get_current_instruction_index)
• Sandwich detection: check whether a specific program appears before or after the current instruction (has_instruction_before, has_instruction_after)

Float and Fixed-Point Fields

Pina schemas can store fractional numbers two ways, each behind its own optional feature:

• floats enables native f32 and f64 fields, converted to and from their bit pattern under the hood through the PodF32/PodF64 pods that pinapod provides, and
• fixed enables fixed-point FixedI*<Frac> and FixedU*<Frac> types from the pinned fixed crate, re-exported as pina::fixed.

Both forms are stored as the complete bit pattern of a backing little-endian integer pod. Every bit pattern is a valid stored value, so zero-copy reads stay total and validation stays O(1) per field.

The features are independent: enabling floats alone does not pull in the fixed crate, and enabling fixed alone does not provide f32/f64 fields. Enable what the program actually stores:

[dependencies]
pina = { version = "...", features = ["floats"] } # f32/f64 fields
pina = { version = "...", features = ["fixed"] } # FixedI*/FixedU* fields
pina = { version = "...", features = ["floats", "fixed"] } # both

Either feature also enables derive, so no separate dependency entries are needed.

Native float fields

With floats enabled, declare f32 and f64 exactly like any other scalar. The generated zero-copy view converts through pinapod’s PodF32 and PodF64 storage pods, so accessors take and return native floats — the same ergonomics as u32 fields converting through PodU32:

#![allow(unused)]
fn main() {
use pina::*;

#[account(discriminator = ReadingKind::Live)]
pub struct LiveReading {
	pub temperature: f32,
	pub depth: f64,
	pub bias: Option<f32>,
	pub samples: Vec<f32, 4>,
}

#[instruction(discriminator = ReadingKind::Calibrate)]
pub struct Calibrate {
	pub offset: f64,
}
}

Storage accessors convert automatically:

• state.temperature.set(-12.5) stores (-12.5f32).to_bits() little-endian.
• state.temperature.get() returns the decoded f32.
• Option<f32> and Vec<f32, N> compose with the standard bounded-collection grammar.
• Compact accounts accept f32/f64 as inline header fields, and compact patches take native floats. Both spellings work for optional fields: patch.maybe_bias(Some(0.5)) and patch.maybe_bias(None) need no pod import, because pinapod implements the field mapping for the f32 primitive itself.

Fixed-point fields

Fixed-point types represent fractional values as scaled integers: a FixedU64<U16> stores value × 2¹⁶ in a u64. Declare them with a typenum fractional-bits parameter, which Pina re-exports through pina::fixed:

#![allow(unused)]
fn main() {
use pina::fixed::FixedU64;
use pina::fixed::types::extra::U16;
use pina::*;

#[account(discriminator = PriceKind::Live)]
pub struct LivePrice {
	pub price: FixedU64<U16>,
	pub authority: Address,
}
}

Fixed-point fields expose their backing bits through the standard pod accessors. Convert at the boundary with from_bits/to_bits, or construct exact values with from_num:

#![allow(unused)]
fn main() {
let price = FixedU64::<U16>::from_num(3);          // exactly 3.0
state.price.set(price.to_bits());
let decoded = FixedU64::<U16>::from_bits(state.price.get());
assert_eq!(decoded.to_bits(), 3 << 16);
}

Valid Frac widths depend on the backing width; a FixedU64<Frac> supports 0–64 fractional bits. The fixed crate rejects invalid parameters at compile time and provides checked_*, saturating_*, and wrapping_* arithmetic alongside the default operators.

Wire format and generated clients

Both families are stored as the complete bit pattern of a backing little-endian integer:

Generated Codama clients describe these fields as their backing little-endian integers (u32, u64, i64, and so on). The IDL describes the wire, and the wire is an integer bit pattern; a client that wants a float divides by 2^Frac (fixed-point) or converts the bits itself (IEEE-754). This keeps every existing Rust, TypeScript, and Dart client working without float codec support.

Choosing between fixed-point and floating point

Prefer fixed-point for anything that touches value, accounting, or consensus-sensitive math:

Use native floats when the values are inherently approximate sensor-style readings, when the math must match an off-chain float model bit-for-bit, or when interoperating with a program that already stores raw float bits (for example, Anchor’s floats pattern, which Pina’s float_accounts_program example ports). In that case store the bits and treat them as opaque: comparisons and aggregation belong off-chain, where the float model is defined.

Solana execution is deterministic across validators, but IEEE-754 does not make cross-platform float math trivially reproducible (FMA contraction, libm differences in transcendentals, and NaN payload propagation all vary). Fixed-point avoids the entire class: integer addition is integer addition everywhere.

Build impact

The two features have very different costs, which is part of why they are separate:

• floats adds no crates. PodF32/PodF64 are four- and eight-byte wrappers in pinapod, which Pina already depends on. A program that enables the feature without using it links nothing extra, and the pina rlib stays byte-identical (609,304 bytes when measured).
• fixed adds two no_std crates to the dependency graph — fixed =1.30.0 and its only dependency typenum. Compiling them costs about 9.5 seconds once, and about 0.4 seconds on a cached rebuild. A program that only stores f32/f64 fields can leave this out entirely.
• The fixed crate is heavily generic: its own rlib is large (about 28 MB with debug metadata), but only the fixed-point types a program actually instantiates are monomorphized into the final SBF binary. A program that uses one FixedU64<U16> field pays for exactly that instantiation.
• The exact =1.30.0 pin is deliberate: Pina’s generated code and pinapod’s ZcField implementations expand against fixed’s type-level contracts, so mixed versions cannot be allowed to coexist. Pina re-exports the pinned instance as pina::fixed; derive your schema fields from that path and the version question disappears.

Security notes

• Every bit pattern is a valid value. Unlike char or NonZero*, no float or fixed-point bit pattern is an invalid state, so zero-copy casts remain sound and validation cannot reject a legitimate value.
• Zeroed storage is value zero, not an invalid account. The typed discriminator still guards account identity: a fully zeroed account fails validation until write_discriminator runs. After initialization, an unset Option<f32> reads as None and a zeroed fixed-point reads as 0.0.
• NaN is a value, not an error. Float storage preserves bit patterns exactly, including NaN payloads, and PodF32/PodF64 compare bitwise so Eq stays sound. On-chain float arithmetic is still the author’s responsibility: NaN == NaN is false in native float math, and validators cannot detect a program that treats NaN inconsistently.
• Use checked arithmetic for value-bearing state. Fixed-point operators panic on overflow in debug builds and wrap in release, matching Rust integer semantics. Prefer checked_add/checked_sub (or the pod’s checked_* helpers on the backing integer pods) in any path that moves value.
• Float precision is a protocol decision. Two floats written by the same instruction read back identically; only arithmetic introduces rounding. Keep multi-step float computation off-chain or in fixed-point, and use on-chain floats as stored configuration or recorded observations.
• Clients see integers. A TypeScript or Dart client that naively renders a fixed-point field shows the raw scaled integer. Scale on the client with an exact divisor derived from the documented Frac parameter.

Declarative Validation

Pina’s opt-in validation feature adds allocation-free application validation to #[account], #[instruction], #[event], and #[derive(Accounts)]. Add it to the program dependency:

[dependencies]
pina = { version = "0.15", features = ["validation"] }

Each annotated macro generates a PinaValidate implementation with fn validate(&self) -> ProgramResult. Validation fails fast with the first Solana ProgramError; it does not allocate, collect an error tree, deserialize into a second value, or use dynamic dispatch.

Pina runs generated validation automatically after structural decoding in try_from_bytes, after fixed or compact initialization, after compact updates, and after #[derive(Accounts)] parses the received account slice. Failed initialization leaves the destination zeroed. Call .validate() directly when validating an already-borrowed value.

Mutating a fixed view can invalidate a previously checked rule, so validate again before emitting an event or committing application state when the mutation itself must be checked. Compact updates return an error when the completed representation violates an application rule. Always propagate that error with ?; Solana transaction rollback is what restores the pre-update bytes and any earlier rent movement.

Value Rules

Use #[pina(validate(...))] on fields of #[account], #[instruction], and #[event] structs. Each rule is a comparison over the field’s value or its len, so the annotation reads as the check it generates:

String lengths are UTF-8 byte lengths. Vector and array lengths are element counts. Chain bounds on the same receiver with && (value >= 1 && value <= 10, len == 4) and separate rules with ,. A range can also be written as one rule — 100 < value <= u64::MAX — which generates the same two checks joined by &&. A rule that must fail in different ways takes error = ERROR in the same group.

The min, max, min_len, max_len, and exact_len parameter spellings predate comparisons. They still parse and generate the identical checks, but they are deprecated and warn at the parameter.

Use validate(with = function) in the outer macro for cross-field or domain validation. The hook is a named parameter, not a comparison: it keeps =. Fixed schemas pass their generated *Zc view; compact accounts pass their generated *Ref<'_> view. The function must return ProgramResult.

#![allow(unused)]
fn main() {
#[instruction(
	discriminator = Instruction::Transfer,
	validate(with = validate_transfer)
)]
pub struct TransferInstruction {
	#[pina(validate(value >= 1 && value <= 1_000_000, error = TransferError::InvalidAmount))]
	pub amount: u64,

	#[pina(validate(len <= 64))]
	pub memo: String<64>,
}

fn validate_transfer(value: &TransferInstructionZc) -> ProgramResult {
	if value.amount() == value.memo().len() as u64 {
		return Err(TransferError::AmbiguousTransfer.into());
	}

	Ok(())
}
}

For accounts, the default error is ProgramError::InvalidAccountData. Instructions and events default to ProgramError::InvalidInstructionData. Put error = ... in a validation group when callers need a domain-specific error.

Read Migrate value rules to comparisons for the rewrite table from the deprecated parameter spellings.

Instruction Account Rules

Fields in #[derive(Accounts)] accept these rules:

Use &mut AccountView or Option<&mut AccountView> to declare a writable slot. Parsing already enforces writability for those types, so adding writable is a compile-time error with a suggested fix. Use the annotation only when a shared reference must still arrive writable.

#![allow(unused)]
fn main() {
#[derive(Accounts)]
#[pina(validate(with = validate_transfer_accounts))]
pub struct TransferAccounts<'a> {
	#[pina(validate(signer))]
	pub authority: &'a AccountView,

	#[pina(validate(owner = ID, not_empty))]
	pub source: &'a mut AccountView,

	#[pina(validate(owner = ID, not_empty, distinct_from = source))]
	pub destination: &'a mut AccountView,

	#[pina(validate(program = token::ID))]
	pub token_program: &'a AccountView,
}

fn validate_transfer_accounts(accounts: &TransferAccounts<'_>) -> ProgramResult {
	if accounts.authority.address() == accounts.destination.address() {
		return Err(TransferError::InvalidAuthority.into());
	}

	Ok(())
}
}

Generated account validation has a stable order: account-slice parsing and implicit writable/duplicate checks; signer, writable, and executable checks; address and owner checks; data checks; cross-field relationships; nested Accounts validation; then the struct-level hook. This puts cheap header checks before account-data borrows and gives custom hooks a fully validated input.

Constraints that perform lifecycle work—account creation, PDA discovery, realloc, and close—remain explicit builders or validation calls. They are not hidden in .validate().

Manual Validation and Codama

The annotations are syntax sugar, not a separate validation engine. Every account rule delegates to the existing AccountInfoValidation method with the same name or meaning. You can keep direct validation chains without enabling validation or using the new annotations:

#![allow(unused)]
fn main() {
self.authority.assert_signer()?;
self.state
	.assert_owner(&ID)?
	.assert_not_empty()?
	.assert_writable()?;
self.system_program.assert_program(&system::ID)?;
}

You can also write an ordinary function returning ProgramResult, call it at the boundary, or manually implement PinaValidate when the validation feature is enabled. Prefer the form that keeps the security contract easiest to audit.

Codama generation supports both styles. pina idl reads declarative signer and writable rules plus known address, program, and sysvar constants from #[derive(Accounts)]. Direct assert_signer, assert_writable, assert_address, and PDA validation-chain inference remains supported, including validation inside module-level helper functions the processor passes an account to, and typed loads of #[pda] account types such as as_account::<T>(). Runtime-only value bounds, owners, data lengths, relationships, and custom hooks do not have Codama account-meta equivalents; they stay on-chain constraints and do not prevent IDL or client generation.

Before and After

Before the validation feature, programs wrote boundary checks directly in each processor. This remains supported:

#![allow(unused)]
fn main() {
let args = TransferInstruction::try_from_bytes(data)?;
if args.amount() == 0 || args.amount() > 1_000_000 {
	return Err(TransferError::InvalidAmount.into());
}

self.authority.assert_signer()?;
self.source.assert_owner(&ID)?.assert_not_empty()?;
self.token_program.assert_program(&token::ID)?;
}

With the feature enabled, the same reusable checks can live beside the fields that declare the boundary. try_from_bytes and #[derive(Accounts)] run them automatically before process receives the decoded values:

#![allow(unused)]
fn main() {
#[instruction(discriminator = Instruction::Transfer)]
pub struct TransferInstruction {
	#[pina(validate(
		value >= 1 && value <= 1_000_000,
		error = TransferError::InvalidAmount
	))]
	pub amount: u64,
}

#[derive(Accounts)]
pub struct TransferAccounts<'a> {
	#[pina(validate(signer))]
	pub authority: &'a AccountView,

	#[pina(validate(owner = ID, not_empty))]
	pub source: &'a mut AccountView,

	#[pina(validate(program = token::ID))]
	pub token_program: &'a AccountView,
}
}

The generated code calls the same validation primitives as the manual form. This makes the annotations removable syntax sugar rather than a second security model.

Complete Boundary-Validation Example

The examples/validation_program project uses the feature across every supported macro boundary:

The processor also keeps one policy rule explicit because it combines decoded instruction data with loaded account state. That distinction is intentional: annotations validate one received value or account list, while ordinary Rust remains the clearest place for rules spanning multiple boundaries.

Run its native and deployed-program tests from the repository root:

devenv shell -- cargo test -p validation_program
devenv shell -- pina test --project examples/validation_program

The existing events_program also enables validation and applies event rules without changing its transport-focused structure. It is the smaller reference for adding validation to an established program.

How a migration flows

This page is the map of the whole migration system: what happens when a developer changes a contract, what the program does at runtime, and exactly what is expected from clients. Everything described here is the implemented behavior — ADR 0008 collects the parts that are designed but not built yet.

An interactive version of this page is at flow-interactive.html.

The one-paragraph answer

Migration happens on-chain, inside the program, on demand. A client never migrates account data and never needs to know a migration exists. An account carries a version envelope right after its discriminator, and the program migrates a stale account to its current representation inside the transaction that touches it. An instruction payload is recorded as a snapshot that fails the build on a wire-breaking change; only an instruction that opts in with migrations carries the envelope, and the generated dispatcher normalizes an older payload before the handler runs. An event is versioned, not migrated: the program emits only the current version, and generated clients decode each historical version with the schema that emitted it. Wherever an envelope exists, every client writes the version it was generated with. If the transaction fails, Solana rolls the migration back with everything else.

What each contract kind carries

The manifest key kind:width:hex (for example instruction:1:00) is the contract’s identity, and version numbers are positions in its versions array. ABI document versioning covers the document itself.

Development-time flow

Opting in

One contract opts in with the migrations token; a whole program opts in with the --auto flag of pina migrations create:

pina migrations create --auto true # or --auto accounts,events,instructions, or a staged subset

create records the policy as auto in migrations/manifest.json and snapshots every contract of the listed kinds; a later run without the flag keeps it. The manifest is the only home of the policy and of the version width, so it stays the checked-in source of truth that macros consult. pina.toml holds neither: its retired [migrations].auto and [migrations].version_type keys fail every command that reads it, naming the flag that replaces them. A declaration the manifest does not record yet still fails the build with the pina migrations create remedy. Because a proc macro does not re-expand when the manifest changes, a program with a policy also gets a build script emitting cargo:rerun-if-changed=migrations/manifest.json; create scaffolds it or reports the exact line when a hand-written build script must be edited. Explicit migrations = false overrides the policy for one contract, and removing an envelope the manifest already records fails closed as a wire-format change, whether it comes from the token, from --auto, or from a hand edit of the manifest’s auto.

The policy envelopes accounts and events. It records an instruction without an envelope unless the declaration opts in with #[instruction(discriminator = X, migrations)].

                 ┌──────────────────────────────┐
                 │ developer changes a struct,  │
                 │ instruction, or event        │
                 └──────────────┬───────────────┘
                                │
                                ▼
                 ┌──────────────────────────────┐
                 │ `pina build` / macro drift   │
                 │ gate fails:                  │
                 │ "run pina migrations create"   │
                 └──────────────┬───────────────┘
                                │
                                ▼
                 ┌──────────────────────────────┐
        ┌────────│   `pina migrations create`     │─────────┐
        │        └──────────────┬───────────────┘         │
        │                       │                         │
        │ ambiguous change?     │ plain change            │ unpaired removal
        ▼                       ▼                         ▼
┌───────────────┐   ┌────────────────────────┐   ┌──────────────────┐
│ terminal:     │   │ automatic transition   │   │ fails with the   │
│ prompt per    │   │ generated (byte moves, │   │ exact flag:      │
│ field         │   │ zero-fill, relayout)   │   │ --assume-removed │
│               │   └───────────┬────────────┘   └────────┬─────────┘
│ no terminal:  │               │ type change / compact?  │
│ fails naming  │               ▼                         │
│ --rename a:b  │   ┌────────────────────────┐            │
│ or            │   │ manual TODO transition │            │
│ --assume-     │   │ developer fills body,  │            │
│  removed a    │   │ re-runs make to record │            │
└───────┬───────┘   │ its hash               │            │
        │           └───────────┬────────────┘            │
        └─────────────┬─────────┴─────────────────────────┘
                      ▼
        ┌──────────────────────────────┐
        │ `pina migrations check`      │
        │ drift, hashes, publication   │
        │ pins all verified            │
        └──────────────┬───────────────┘
                       ▼
        ┌──────────────────────────────┐
        │ `pina build`                 │
        │ program compiles with the    │
        │ manifest + transitions       │
        │ embedded (include! bytes)    │
        └──────────────┬───────────────┘
                       ▼
        ┌──────────────────────────────┐
        │ `pina deploy`                │
        │ 1. pending record written    │
        │    atomically (versions      │
        │    frozen — may already be   │
        │    live)                     │
        │ 2. remote command runs       │
        │    (solana program deploy or │
        │    --remote-command)         │
        │ 3. immutable receipt with    │
        │    pinned schema history     │
        └──────────────┬───────────────┘
                       ▼
        ┌──────────────────────────────┐
        │ `pina generate`             │
        │ TypeScript, Rust, Dart, CPI  │
        │ clients embed the CURRENT    │
        │ version as an omitted        │
        │ constant — callers never     │
        │ pass a version               │
        └──────────────────────────────┘

Once a version appears in a receipt or pending record it is frozen: create appends the next version instead of rewriting it, and any edit to a pinned schema or transition hash fails every later check. A snapshot-only instruction has no next version, so its published payload is fixed.

Drift is decided by what a field stores, not by how its type is spelled. Respelling PodU64 as u64, or Address as [u8; 32], stores the same bytes under the same reading, so it consumes no version and fails no build, and the recorded spelling and pinned hashes stay as they were. Types that only share a width, such as u64 and i64, are a real change that needs a manual transition.

Instructions: a snapshot unless they opt in

An instruction covered by auto keeps its plain wire format, [discriminator][payload], and the manifest records exactly one version of it with "envelope": false. The snapshot is a gate, not a history:

• The proc macro compares the struct with the snapshot and fails the build when they drift.
• While nothing is published, pina migrations create replaces the snapshot with the current struct.
• Once published, a payload change fails with PublishedPayloadChanged, because no byte tells the program which layout a client sent. Declare a new discriminator for the new payload, or restore the published fields.
• Appending optional accounts to a published snapshot is allowed: create extends its process contract in place without consuming a version, and older clients simply omit the new slots.
• A published snapshot cannot gain an envelope (EnvelopeAddition), because existing clients send no version byte. Declare a new discriminator for the migration-aware instruction.
• An instruction that stops asking to be recorded (migrations = false, or an auto policy that no longer covers instructions) leaves a stale snapshot behind. pina migrations check fails with StaleSnapshot and create releases it; nothing on the wire changes.

An instruction that must keep accepting older payloads under one discriminator opts into full migrations with #[instruction(discriminator = X, migrations)]. It carries the envelope [discriminator][version][payload], and every later version has an adjacent transition at migrations/transitions/instruction_<width>_<hex>/vN_to_vN+1.rs. create never zero-fills an added instruction argument, because the handler could not tell that default from a value a client sent: a transition that adds an argument is scaffolded as a manual transition for you to fill in. A transition that only moves or drops bytes stays automatic.

An envelope is part of the wire format, so it can change only before publication. When the source stops asking for an envelope the manifest records, the macro fails the build: “removing an envelope is a wire-format change that pina migrations create must record deliberately”. Before publication, pina migrations create then records the instruction as a snapshot again; after publication it fails with EnvelopeRemoval. An explicit migrations = false on an enveloped contract is always rejected. A program published under ABI 0.20, where every recorded instruction was enveloped, keeps its wire format by adding migrations to each of those #[instruction] attributes.

Events: versioned, not migrated

Transaction logs are immutable, so an event is never converted. An event with migrations, or covered by auto, carries the envelope [discriminator][version][payload]. The program emits only the current version. Changing a published event’s schema appends a version with its own schema and writes no transition file; there is no migrations/transitions/event_* directory. Generated clients decode each version with that version’s schema, as described in Generated client helpers.

Persisted answers

Disambiguation answers do not have to travel as flags every run. A [migrations.answers] table in pina.toml persists them for the whole checkout:

[migrations.answers]
rename = ["value:points"]
assume_removed = []

create consults the table before prompting, command-line flags override it per field, and a flag that contradicts a persisted rename (for example --assume-removed value when the file renames value) fails closed. Fresh clones and CI therefore replay an answer made locally without anyone re-deriving flag lists, and --json failures print a machine-actionable envelope carrying the message plus the exact outstanding questions.

Runtime flow inside the program

This is the generated dispatcher’s decision tree for one invocation of an instruction that opts into migrations. An instruction recorded as a snapshot has no version to inspect: the dispatcher parses its payload directly, and only the account branch applies.

                transaction arrives
                        │
                        ▼
        ┌───────────────────────────────┐
        │ read discriminator, dispatch   │
        │ to the instruction             │
        └───────────────┬───────────────┘
                        ▼
        ┌───────────────────────────────┐
        │ inspect instruction version    │
        │ (one read after the disc)      │
        └───────┬───────────┬───────────┘
        current │    stale   │   future/corrupt
                ▼           ▼               ▼
      ┌──────────────┐ ┌──────────────────┐ ┌────────────────┐
      │ validate &   │ │ normalize:       │ │ reject now —   │
      │ run handler  │ │ zero workspace,  │ │ no trial       │
      │ (hot path:   │ │ walk adjacent    │ │ decoding       │
      │ no history   │ │ payload steps,   │ └────────────────┘
      │ scans)       │ │ validate each,   │
      └──────┬───────┘ │ commit current   │
             │         │ version marker    │
             │         └────────┬─────────┘
             │                  ▼
             │    ┌───────────────────────────────┐
             │    │ for each migratable account   │
             │    │ the route touches:            │
             │    │                               │
             │    │  version == current?          │
             │    │    yes → validate, done       │
             │    │    no  → PLAN                 │
             │    │      (validate exact source   │
             │    │       shape, owned detached   │
             │    │       state, no borrows)      │
             │    │          │                    │
             │    │          ▼                    │
             │    │    need growth & rent?        │
             │    │      yes → explicit capped    │
             │    │      payer transfers deficit  │
             │    │          │                    │
             │    │          ▼                    │
             │    │    RESIZE → APPLY (infallible)│
             │    │    → VALIDATE destination     │
             │    │    → WRITE version → re-      │
             │    │    VALIDATE                   │
             │    │          │                    │
             │    │          ▼                    │
             │    │    next adjacent version      │
             │    │    until current              │
             │    └──────────────┬────────────────┘
             │                   │
             └────────┬──────────┘
                      ▼
        ┌───────────────────────────────┐
        │ run current handler with      │
        │ current types only            │
        └───────────────────────────────┘

The version envelope supports `u8`, `u16`, and `u32` encodings (program-wide, `u8` by default) — never `u64`.

  failure BEFORE first mutation  → ordinary ProgramError
  failure AFTER first mutation   → instruction ABORTS (never a
                                   catchable error) so the transaction
                                   rolls back every resize, transfer,
                                   and byte write together

Accounts in one instruction migrate independently — a mixed set (Profile@v0, Journal@v1, …) each climb their own ladder atomically within the same invocation.

The payload normalization is generated, not written in the handler. #[discriminator(entrypoint)] routes every instruction the manifest records with an envelope through that instruction’s generated process_versioned, which converts a historical payload into the current layout and then calls ProcessAccountInfos::process_from_version(self, data, source_version). The default implementation forwards to process(data), so a handler reads data as the current layout. Override process_from_version only when the handler must tell a field a transition filled in from one the client sent. A program with a hand-written dispatcher calls <Instruction>::process_versioned(parsed_accounts, data) itself, and pina::normalize_instruction_data returns a NormalizedInstruction (as_bytes(), source_version(), was_migrated()) for manual use.

What is expected from each side

Paying for growth

Migration that only moves bytes is free beyond compute. Migration that makes an account bigger must also make it rent-exempt at its new size, and that lamports transfer happens inside the touching transaction:

• the program transfers only the deficit (rent-exempt minimum at the new size minus what the account already holds), never more;
• the payer is the instruction’s declared migration payer — a transaction signer, or one of the program’s own PDAs signing through invoke_signed;
• the transfer is capped by the max_lamports budget the program passes to the executor. An undersized budget fails the whole transaction with MigrationLamportBudgetExceeded — nothing is half-migrated — but the account also stays stale until the budget is raised, so size it deliberately. The error names the budget to raise, and pina migrations create quotes the same deficit figure before you deploy.

A planning figure for that budget: rent exemption costs about 6,960 lamports per byte (3,480 lamports per byte-year at the two-year exemption threshold), so growing an account by N bytes needs roughly N × 6,960 lamports of head room on top of what the account already holds. pina migrations create prints a warning with the exact growth and estimate whenever a transition grows an account or keeps a compact (capacity-driven) layout, and adds the remedy for the failure the grown account would hit on chain.

The executor keeps the workspace, realloc-growth, and lamport budgets as separate codes, so each failure names one fix:

Builds before the split reported the workspace, account-growth, and lamport-budget failures as MigrationBudgetExceeded (0xFFFF_FFF5); MigrationUnavailable was already its own code and was not part of that split. The aggregate code stays reserved so published binaries remain decodable.

The growth check covers the whole supported ladder, not one hop: the executor captures the account size before the first step, so a v0 account walking two individually sub-limit transitions can still cross MAX_PERMITTED_DATA_INCREASE in one instruction. pina migrations create warns on that cumulative worst case, and publishing an intermediate version only resets the cap when it migrates in its own transaction.

Two consequences follow from the payer model:

1. An old client cannot fund growth. A client generated before the instruction gained its optional migrationPayer slot submits without a payer; if the account it touches now needs rent, that transaction fails with MigrationRequired. The fix is a current client (or a payer-carrying migration path) — by design, rent is never taken from an account the client did not offer.
2. The compute bill lands on the touching transaction. A stale account pays its ladder’s compute cost inside whichever transaction finds it, and MAX_INLINE_STEPS (at most 8 adjacent transitions) bounds how long that ladder may be. Accounts further behind than that fail with MigrationUnavailable rather than silently burning the budget; the remedy is rebalancing the history into more frequent, smaller versions. The reserved Migrate instruction below is the out-of-band route for carrying a payer, but it enforces the same step limit.

The reserved Migrate instruction

Pina reserves the all-ones value of every instruction discriminator width (0xff, 0xffff, 0xffff_ffff, 0xffff_ffff_ffff_ffff) for a framework migration instruction; #[discriminator] rejects user variants that claim it at compile time. A program with migratable accounts wires the reserved route before parsing its own instruction enum:

if is_migrate_instruction(data) {
    return process_migrate(program_id, accounts);
}

The trigger must match the program’s own discriminator width. is_migrate_instruction tests one byte, so a program whose instruction enum uses primitive = u16 (or u32, or u64) matches with is_migrate_instruction_u16 (or _u32, _u64) instead — the one-byte helper never matches a two-byte 0xffff, which would leave the reserved path unreachable. Generated entrypoints select the matching helper from the enum’s primitive, so #[discriminator(entrypoint)] needs no hand-written guard at all.

Its account layout is [payer, systemProgram, accountA, accountB, …]. Slot 0 is a writable payer funding every rent deficit (or the program address when the invocation needs no funding), slot 1 is the system program the rent transfers invoke, and each later slot is a program-owned, self-describing migratable account.

The ladder is derived, not declared. #[discriminator(entrypoint)] wires the route on its own: the slots are read from migrations/manifest.json, one per enveloped account contract, in the manifest’s identity-sorted order — exactly the order generated clients compose. Declaring a contract list is optional and only needed to batch several accounts of the same contract in one sweep, because the manifest records contracts rather than account instances:

The route calls the resize executor, so a program that serves migrations needs pina’s account-resize feature. pina init scaffolds it; the generated code names it when it is missing.

#[discriminator(entrypoint)]
pub enum Instruction { /* … */ }

// Optional ceiling, and optional slot override for same-contract batching.
#[discriminator(
	entrypoint,
	migrations(State, State),
	migrations_max_lamports = MAX_INLINE_MIGRATION_LAMPORTS,
)]

migrations_max_lamports is optional and off by default. Declaring one caps the total lamports the reserved instruction may transfer; leaving it out enforces no ceiling, which is safe because a transfer is never more than the rent deficit of a growth the runtime already caps at MAX_PERMITTED_DATA_INCREASE. Declare one to refuse an expensive migration rather than to permit it. A slot holding the program address (the placeholder generated clients write for an omitted optional account) or an index past the end of the list is skipped, so a client sends only the accounts it needs. MigrateContext validates ownership, rejects duplicated account slots, migrates each slot at most once, and runs each slot through the same MigrateAccount executor — the same step, growth, and lamport caps as the inline path.

That makes the client flow explicit: when an account is stale and the business instruction cannot carry a payer, prepend [Migrate { payer }, …real instructions] in the same transaction — the payer authorizes exactly the migration cost, and the real instruction observes current data or the whole transaction fails.

Reading without migrating

Migration is a mutation, and the runtime forbids writes and resizes on a read-only account. A program that only reads a stale account therefore has no migration path in that instruction. Generated account code now offers a read-only alternative: <Account>::try_from_bytes_versioned(bytes) validates the exact representation named by the version envelope and borrows it immutably. It never rewrites, resizes, or clears anything, and it never requires a writable borrow; foreign discriminators, unknown versions, future versions, and malformed lengths all fail closed.

The generated <Account>Versioned enum has one variant per historical version plus Current, so the caller must handle every stored representation:

let data = account.try_borrow()?;
match State::try_from_bytes_versioned(&data)? {
    StateVersioned::V0(view) => read_v0(view),
    StateVersioned::V1(view) => read_v1(view),
    StateVersioned::Current(view) => read_current(view),
}

This is a deliberate trade-off, not a replacement for migration. A program that reads historical layouts must handle two (or more) representations in its business logic, which is exactly the branching the migration system exists to remove. Treat the view as the complement for read-heavy accounts whose one-time writable touch is genuinely hard to schedule; the reserved Migrate instruction remains the primary fix. The accessor is generated only for accounts declared with migrations.

Generated client helpers

Generated clients turn that flow into a one-call routine. Next to each migratable account module the TypeScript, Dart, and Rust clients emit:

• a <Account>MIGRATION_VERSION constant — the schema version the client was generated from;
• the generic needsMigration envelope check is that per-account helper (stateNeedsMigration for a State account, and so on);
• <account>NeedsMigration(bytes) — a cheap envelope check that returns true only when the bytes name this account’s discriminator and a version older than the client’s schema. Future versions and foreign discriminators return false; the decoder explains those when the account is decoded.

The clients also emit a Migrate instruction composer (TypeScript getMigrateInstruction, Dart getMigrateInstruction, Rust Migrate::new().instruction()). In the Migrate composer, the payer and system program slots are always sent, and systemProgram defaults to the system program because the program rejects anything else in slot 1. Every migratable slot is optional: omitted slots become program-address placeholders and trailing omitted migratable slots are truncated, so a client sends only the accounts it needs. The intended catch → migrate → retry loop:

const account = await fetchEncodedAccount(rpc, address);
if (account.exists && stateNeedsMigration(account.data)) {
	// `getMigrateInstruction` returns a complete instruction; add it to a
	// transaction message like any other.
	await send(getMigrateInstruction({ state: address, payer }));
}
// now decode `state` and send the real instruction

migrateIfNeeded — fetching, checking, and migrating in one call over an RPC handle — is designed in ADR 0008.

Versioned events are decoded, never converted. The IDL lists each earlier version of an event as its own event node named <Event>V<n> (for example ValueChangedEventV0), with that version’s schema and codec, next to the current event. The program-level log parser (parse<Program>EventsFromLogs in TypeScript and Dart) dispatches each record by discriminator and version to the matching event and throws on a version no generated event describes — for example event "valueChangedEvent" log carries migration version 2, which this client cannot decode; regenerate it. A decoded record carries that version’s own fields: nothing is projected into the current shape or zero-filled. In Rust, each version’s try_from_bytes tells a stale record from a future one and names the event generated for the other version. The parser also attributes each line to the program that emitted it by following the transaction’s invoke/success frames, so pass it a transaction’s complete, ordered logs. Clients render these decoders from the IDL alone; the migration manifest is read only when the IDL is generated.

The sweep instruction

A typed reader refuses a stale account: as_account, as_account_mut, and validate_account_data all inspect the version envelope and return MigrationRequired for anything older than the program’s current schema. The refusal happens wherever the handler loads the account, and it does not care whether the account was passed writable or read-only. Migration itself does care: MigrateAccount asserts writability and program ownership before it inspects a single byte, because the executor may rewrite, resize, and fund the account. An instruction that treats a migratable account as read-only therefore has no way to bring it current, and keeps failing until some other transaction migrates the account once. The sweep instruction is that other transaction: one instruction whose only job is putting migratable accounts in a writable position and running the executor on each.

The instruction

Write one sweep per program with its own discriminator. Every migratable account appears as an optional, writable view, the payer funding growth appears once, and the system program the rent transfers invoke is declared:

#[discriminator]
pub enum SwapInstruction {
	Swap = 0,
	SweepAccounts = 1,
}

#[derive(Accounts)]
pub struct SweepAccounts<'a> {
	/// Writable signer funding every rent deficit, usually the fee payer.
	#[pina(validate(signer))]
	pub payer: Option<&'a mut AccountView>,
	/// The system program every growth transfer invokes.
	pub system_program: &'a AccountView,
	/// Every migratable account this program owns, writable and optional.
	pub state: Option<&'a mut AccountView>,
	pub profile: Option<&'a mut AccountView>,
	pub vault: Option<&'a mut AccountView>,
}

impl<'a> ProcessAccountInfos<'a> for SweepAccounts<'a> {
	fn process(self, _data: &[u8]) -> ProgramResult {
		let SweepAccounts {
			payer,
			system_program,
			state,
			profile,
			vault,
		} = self;
		system_program.assert_address(&system::ID)?;
		let payer = payer.map(|account| &*account);

		if let Some(state) = state {
			MigrateAccount {
				account: state,
				payer,
				program_id: &ID,
				max_lamports: MAX_MIGRATION_LAMPORTS,
			}
			.invoke::<State>()?;
		}
		// The same call for profile and vault: one independent invoke each.

		Ok(())
	}
}

The handler is a straight line of independent calls. Each invoke::<T>() is complete on its own: it validates the account, plans the adjacent transitions, and commits the current version. An absent account arrives as None and the call is skipped, so nothing is validated, charged, or written for it. A missing middle slot still needs the program-address filler the account parser expects; trailing absent slots can be omitted.

The payer must be writable and a transaction signer, or a PDA signing through invoke_signed. max_lamports caps what one call may transfer from it, so a sweep pays at most the sum of its calls’ caps — set each one deliberately.

The client sends it first

Prepend the sweep, then send the real instruction in the same transaction:

[sweep(state, profile, payer), swap(...)]

First, not last: instructions run in order and any failure aborts the whole transaction. The real instruction loads the stale account and fails with MigrationRequired, so a sweep placed after it never runs. The sweep can carry every account the transaction might touch; the real instruction then observes current bytes, or the whole transaction — migrations included — rolls back. A sweep sent alone, with no business instruction, is a maintenance transaction that pre-migrates accounts ahead of future use. That standalone form is the only trailing sweep worth sending.

What happens per account

The failures are sharp and in front of the first mutation:

• a growing step with no payer fails with MigrationRequired; a deficit above max_lamports fails with MigrationBudgetExceeded — the account stays stale, nothing is half-migrated;
• a read-only or foreign-owned account fails the writability or ownership assertion before the version is even read, and a wrong discriminator fails with InvalidAccountData;
• a version newer than the program’s current schema fails with InvalidMigrationVersion instead of guessing at the layout.

Why it is safe to expose

Every account is owner-checked and writability-checked before anything is inspected. Transition planning validates the exact historical shape and accepts only adjacent steps the published history proves; the destination representation is validated before the current version marker is committed, and an invariant failure after the first byte or lamport moves aborts the instruction instead of returning an error the caller could catch. The payer can only add lamports — the deficit, never more than max_lamports — and shrinking never moves lamports at all. Because each caller supplies the payer it wants to charge, a sweep cannot spend an account its sender did not offer: nobody can be made to fund someone else’s migration.

Forward compatibility

The reserved Migrate instruction above is the framework-owned instance of this pattern. MigrateContext runs the same [payer, systemProgram, …accounts] layout through the same MigrateAccount executor, and run_optional treats a slot holding the program address — or an index past the end of the list — as absent, so it is also a sweep. Generated clients emit a Migrate composer and the per-account needsMigration checks, so the standard sweep needs no hand-composed metas; the one-call migrateIfNeeded wrapper is tracked in #339. A hand-written sweep stays compatible with that route because it drives the same executor and produces exactly the same account state. Prefer it when the handler needs policy the generated route does not carry — extra gates, per-account caps, or a different payer rule — and prefer the reserved instruction when it does not.

The four scenarios

1. Current client → current program (the hot path)

client encodes v_N payload ──► program sees version == current
                                   │
                                   ▼
                          validate current shape
                                   │
                                   ▼
                          handler runs — zero
                          migration work done

For an enveloped contract, one version comparison is the entire overhead. A snapshot-only instruction has no version to compare.

2. Old client → updated program (the migration path)

old client encodes v_0 payload
        │
        ▼
program sees 0 < current ──► stale
        │
        ▼
normalize payload: v_0 → v_1 → … → v_N
(zeroed workspace, each step validated,
 current marker committed last)
        │
        ▼
migrate every stale account the route touches
(plan → fund → resize → apply → validate → commit,
 one adjacent step at a time)
        │
        ▼
current authorization + business logic run
with current types
        │
        ▼
success: one transaction did everything
failure anywhere: everything rolls back

The old client cannot tell that anything happened. This is the property the whole design protects: backwards compatibility is the default, and the program owns it.

The payload step runs only for an instruction that opts into migrations. A snapshot-only instruction cannot change its payload after publication, so an old client’s request is already in the current layout and only the account steps apply.

3. Old client → rolled-back program (the honest limit)

Rolling back the binary to a previous executable does not roll back accounts. Accounts written by version N carry N; a program compiled when current == N-1 sees those as future versions and rejects them without trial decoding. The supported rollback is redeploying an executable built from the current manifest history (an old binary with the current ABI), which keeps every live account readable. This is a deliberate security stance, not an implementation gap: silently guessing at newer layouts would let a rolled-back program misinterpret post-rollback data.

4. Where the migration lives: program or client?

Implemented: the program. Inline, on-demand, per-account — the transaction that touches a stale account performs its migration before the handler runs, funded by the payer that transaction already declared.

Implemented: the reserved prefix. A program wires the reserved Migrate instruction (see “The reserved Migrate instruction” above) so a client can prepend [Migrate { payer }, …real instructions] when an account is stale and the business instruction declares no payer. Still designed, not built (ADR 0008, tracked in #339): the generated migrateIfNeeded helper that fetches accounts, compares the version constant it already embeds, and prepends the migration only when needed. Until that ships, any instruction that can touch a migratable account during a growth step must also declare an optional migration_payer slot, and current clients pass it.

Version exhaustion

Run out of versions and nothing can fix it afterwards. Two facts decide how much this matters.

Versions are counted per contract, not per program. Every account, instruction, and event owns an independent history that starts at 0, keyed by its own discriminator in migrations/manifest.json. A snapshot-only instruction never consumes a version. A program can hold one account at version 3 and another still at 0; they do not share a counter, and exhausting one says nothing about the rest. So the budget is “255 versions of this one contract”, not “255 versions of the program”.

The width is program-wide and freezes at the first publication. pina migrations create --version-type records one width for every contract as versionType in the manifest, and a later run without the flag keeps it. Before the first release the width is still yours to choose: pina migrations create --version-type u16 rewrites it in place, because every history is still a single draft. Once a receipt or pending record exists the width is frozen, and the flag fails with “Migration version encoding is frozen as u8 because a deployment published it, so it cannot become u16”. After the first release there is no widening path.

That combination makes u8 the right default. 255 versions of a single account type is not a realistic lifetime for a program that migrates sensibly, and it costs one byte per enveloped account; u16 costs two and is worth choosing up front only if you expect a single contract to exceed 255 revisions.

pina migrations status reports the remaining budget per contract so drift toward the ceiling is visible:

account State v3 (published, 252 version(s) remaining)
instruction InitializeInstruction (published, snapshot without envelope)

When a contract does reach its ceiling

pina migrations create fails closed with VersionExhausted rather than wrapping. There is no silent reuse of version numbers, and the on-chain side rejects out-of-range versions via try_from_u32 instead of truncating, so a wrapped version can never be written or misread.

The remedy is a successor contract, not a larger counter:

1. Declare a new discriminator variant for the successor account and give it a fresh version-0 history. It is a new contract identity, so it gets its own full budget.
2. Add a bridge instruction that loads the exhausted account through the current loaders and writes the successor account, then closes or drains the old one.
3. Migrate accounts lazily: the bridge runs once per account, driven by a client sweep, the same way the reserved Migrate route works.

Old history cannot be pruned to make room. A program cannot enumerate its own accounts — Solana offers no such primitive — so retiring history requires an external proof that every account of that type has been converted. Plan the successor before the ceiling, because the bridge needs the old layout to still be readable by the binary you ship.

Seeing it live

The whole of this page runs for real in the ten-deployment walkthrough:

pnpm walkthrough:migrations            # full run, ~3 minutes
pnpm walkthrough:migrations -- --from-step 6 --to-step 8 --keep

It scaffolds a program, evolves it through ten published generations (add field, rename through the question flow, type change via a manual transition, compact growth, payload growth, appended optional accounts, event growth, acknowledged removal, full-ladder replay), deploys each one to an isolated Surfpool network through pina deploy, regenerates every client each time, and proves that step-1 clients keep submitting successfully against the step-9 program with their data preserved.

ABI document versioning

Pina’s ABI document is the checked-in migrations/manifest.json and the publication ledger at migrations/publications.json. Both carry an abiVersion that belongs to Pina itself and has nothing to do with any user contract’s on-chain version.

This page covers how that version is chosen, how older documents are normalized, what the document stores versus derives, and how its JSON Schemas are generated and published. For the runtime decision tree that governs on-chain migrations, read How ABI migrations flow. For the decision record behind this design, read ADR 0009.

Three version axes

A Pina program carries three unrelated kinds of version, and confusing them is the most common source of migration bugs.

Only the first one is written into account bytes. An ABI document upgrade never consumes an on-chain migration version, and an on-chain migration never changes abiVersion.

pina_abi is not part of the core release group. It releases on its own single-member group, so a CLI fix or a renderer tweak in core moves nothing here, while any pina_abi release cascades into a core release because pina_cli and pina_macros consume it. The contract moves deliberately and consumers follow; core releases never move the contract.

The version value

abiVersion is a committed value, one line of text in crates/pina_abi/ABI_VERSION, embedded with include_str!:

pub const ABI_VERSION: &str = include_str!("../ABI_VERSION").trim_ascii_end();

The file is pinned to pina_abi’s major.minor and is allowed to lead the crate. A shape-changing pull request advances the file while Cargo.toml still reads the old version — the pre-release window — and the release planner’s bump catches the crate up. This is the monochange model: a committed SCHEMA_VERSION that can sit ahead of its crate (verified at 0.7 against a crate at 0.6.3), which a compile-time derivation of CARGO_PKG_VERSION cannot express. monochange tried derivation twice and reverted both times; ADR 0009 carries the history and the reasoning.

Pre-1.0 bump semantics

While the major is 0, the release planner shifts bump severity: a breaking changeset advances the minor, a feat or fix advances only the patch. Since abiVersion keeps major.minor, only a breaking changeset moves it:

The version moves if and only if the contract moved. This property is why pina_abi stays pre-1.0: at 1.0.0 the shift switches off, a feat would advance major.minor with no wire change, and 1.0.0 is not reachable through the planner anyway. Every 0.N version also keeps a permanent schema URL under the publishing policy, and every ABI version is a real contract worth one.

Reading a document

Every reader goes through the decode path rather than deserializing straight into the typed model:

1. parse the JSON value;
2. read abiVersion and reject a document stamped above the reader’s own version, naming the supported version in the error;
3. apply each adjacent converter in order, from the document’s version up to the current one;
4. deserialize into the current typed model;
5. validate every content-addressed invariant, re-deriving everything the document no longer stores.

Step 2 is a capability marker, not a compatibility promise, and behaves like Cargo.lock’s version field: a repository’s documents are read by the same Pina the repository builds with, so the rejection only reaches a human who downgraded, and the remedy is one line — upgrade.

Conversions run in memory only. No command rewrites a checked-in document as a side effect of reading it.

The converter contract

The reader carries an ordered table of adjacent converters — one edge per ABI version step — keyed by the version itself. There is no separate epoch table: the version advances exactly at contract changes, so it is the only axis. Both documents share one abiVersion, so each step carries a converter for each document, and walk_document(AbiDocument::Manifest | AbiDocument::Publications, from, value) applies the matching one and stamps the step’s to version on the result:

pub const ABI_STEPS: &[AbiStep] = &[AbiStep {
	from: "0.20",
	to: "0.21",
	manifest: convert::manifest_0_20_to_0_21,
	publications: convert::publications_0_20_to_0_21,
}];

Four rules make the chain trustworthy.

Every step has an edge, including no-ops. The version follows every breaking pina_abi release, but the document shape changes only some of those times. A breaking change with an unchanged document registers a validating no-op edge that decodes, validates, and returns the document unchanged. monochange’s v0.6 → v0.7 edge is the precedent — payloads unchanged, version advanced because a config contract changed — and the edge exists so the 0.6 contract stays frozen while the walk stays gapless.

Forward only. Writers always emit the current version, and a document that must reach an older tool is regenerated from source by that tool. A downgrade entry point does not exist, so no best-effort write can lose information.

Never deleted. Once an edge ships, it is part of published history. Fixing a defective converter means a new version, never editing the old one — the same immutability rule the on-chain migration system applies to its transitions.

Gapless by construction and by test. The table is an ordered walk over adjacent versions, and a test decodes every frozen fixture to the current model, so a missing or mis-wired edge is a CI failure rather than a runtime error on a user’s machine.

Stored versus derived

The 0.20 baseline stored facts and re-derived everything else at load, and 0.21 removed the remaining stored copies. What the document used to carry, and where it comes from now:

What stays is what cannot be derived: rust_name (macro lookup), the auto policy, envelope (written only as "envelope": false, on an instruction recorded without one), identity validation including the path-traversal proofs, mode, renames, implementation_sha256 (the hash of an external transition file), and the publication ledger: each receipt’s credential-free rpcUrl, its executableSha256, the pinned schema history of every contract it made live, and its abandoned flag, plus the pending record’s cluster. Publication receipts pin schema hashes by computing them from the decoded manifest at pin time.

A field’s rustType is stored as the source spelled it when the version was recorded. Drift is decided with DataSchema::same_wire, which compares the layout, the field names, and each type after pina_abi::wire_type collapses spellings that store the same bytes under the same reading (PodU64 and u64, Address and [u8; 32], PodString<N> and String<N>, PodVec<T, N> and Vec<T, N>). A later respelling therefore neither rewrites the recorded spelling nor changes a pinned hash.

The wire codec left the stored schema but not the schema hash. schemaSha256 still hashes layout, fields, and "codec": "pinaPodV2" in the order 0.20 serialized them, so every published pin keeps its value. A PinaPod release that changes wire bytes changes SCHEMA_CODEC through a breaking pina_abi release, and the converter for that release records the old format on every historical schema it carries forward.

Because deny_unknown_fields applies, any field change is a breaking change for older readers, and every document change therefore advances the ABI version through a breaking changeset. The converse does not hold — a breaking crate change with an unchanged document is the no-op edge above.

The frozen fixture matrix

crates/pina_abi/fixtures/0.20/manifest.json
crates/pina_abi/fixtures/0.20/publications.json
crates/pina_abi/fixtures/0.20/manifest.schema.json
crates/pina_abi/fixtures/0.20/publications.schema.json
crates/pina_abi/fixtures/0.21/…
crates/pina_abi/fixtures/current/…

• A <version>/ directory is frozen when that release ships and is never regenerated. They are the only artifacts that record what an older release actually wrote; a fixture regenerated from current code would encode today’s shape under yesterday’s version and prove nothing.
• current/ is regenerated by the schema and fixture task whenever the model changes.
• Fixtures are generated deterministically from fixed seeds, the way the monochange schema assets are, so the frozen bytes are reproducible on every machine rather than hand-maintained.
• The fixtures prove the shape changed; the committed value only names it. The fixture-drift guard pairs the two: regenerating current/ must reproduce the frozen bytes unless ABI_VERSION advanced. A serialization change without a version change fails CI; a version change with unchanged bytes is the deliberate no-op edge, which registers a new frozen directory with identical bytes.
• A test decodes every frozen fixture through the current reader and asserts it reaches the current model — the gapless-walk guard.
• The not-lag guard asserts the committed value never lags the crate’s major.minor, and the ahead-requires-changeset guard asserts that a value ahead of the crate — the pre-release window — has an active pina_abi changeset behind it. Any other ahead state fails.

JSON Schemas

The document types derive schemars::JsonSchema, so the schema is generated from the same types that serialize and deserialize the document — deny_unknown_fields becomes additionalProperties: false, and the schema can never drift from the code that enforces it.

• Canonical artifacts are checked in at crates/pina_abi/schemas/manifest.schema.json and publications.schema.json, regenerated and drift-checked in CI the way Codama IDL fixtures are.
• Each version’s schema is frozen inside its fixture directory, so the schema for any historical shape stays printable.
• Every version’s schema is hosted at a permanent URL under this book: https://pina-rs.github.io/pina/abi/schemas/<version>/manifest.schema.json, with $id set to that URL. Every 0.N version keeps its URL permanently.
• pina abi schema [--document manifest|publications] [--version <major.minor>] prints the JSON with stable output, so editors, CI jobs, and non-Rust toolchains can validate a document without trusting the bytes:

pina abi schema --document manifest > manifest.schema.json

Upgrading from ABI 0.20

A 0.20 document still opens: the reader converts it in memory, and the next pina migrations create writes it at 0.21. The one exception is a ledger entry that names a published version without pinning it, covered below. The manifest step:

• drops each history’s identity object after proving that its kind, width, and hex spell the contract key;
• drops each schema’s "codec": "pinaPodV2" after proving it is that codec;
• drops every event transition, because an event is decoded with the schema of the version that emitted it;
• keeps every instruction enveloped, because every 0.20 instruction history was.

The publication ledger step drops every stored copy of a fact the ledger or its manifest already records:

• drops each receipt’s sequence after proving it equals the receipt’s position;
• drops programId from every receipt and the pending record after proving they all name the same program;
• drops each contract’s version after proving it is the position of its last pin, leaving the entry as the bare list of pins;
• drops manifestSha256 and the previousReceiptSha256 chain link unchecked, because nothing compared the one and anyone able to edit the file could recompute the other;
• drops the pinned transitionSha256 of every event:* contract.

Every schemaSha256 pin keeps its value. A 0.21 entry must pin every version it made live, so a 0.20 entry that pinned nothing cannot convert, and reading it fails with an error naming pina migrations reconcile --pin-legacy. Confirm from version control that migrations/manifest.json still records exactly what those receipts shipped, then run that command once: it pins each such entry from the manifest (trust on first use) and writes the ledger in the 0.21 shape.

Five source changes can follow the conversion:

1. Instructions recorded through auto. An instruction that 0.20 recorded only because auto covered instructions stays enveloped after conversion, but under 0.21 an auto policy alone records an instruction without one, so the build fails: “the migration manifest records UpdateInstruction with a version envelope, but it no longer opts in with the migrations token”. If the instruction is published, add migrations to its #[instruction] attribute to keep its wire format; pina migrations create rejects the other direction with EnvelopeRemoval. If nothing is published, you may instead run pina migrations create, which records the instruction as a snapshot without a version byte; delete its migrations/transitions/instruction_* directory afterwards, because nothing reads it.
2. Event transitions. migrations/transitions/event_* directories are no longer read or verified. Delete them. Code that called normalize_event_data, with_current_event_data, MigratableEvent, or CurrentEventData must decode a historical record with the generated client’s <Event>V<n> event instead.
3. Instruction handlers. #[discriminator(entrypoint)] now normalizes an enveloped instruction’s payload before the handler runs, through the generated process_versioned and ProcessAccountInfos::process_from_version. Remove handler-side calls to with_current_instruction_data: the payload is already current, and the helper’s closure now takes the source version as a second argument, so existing calls no longer compile.
4. pina.toml migration keys. [migrations].version_type (or version-type) and [migrations].auto are retired, because the manifest already records both. Every command that reads pina.toml fails until they are removed, and the error names the pina migrations create --version-type or --auto value that records the same setting. [migrations.answers] stays.
5. TypeScript event decoders. The generated per-event decoder is decode<Event>Event (for example decodeValueChangedEventEvent and decodeValueChangedEventV0Event), matching the Dart clients. It decodes one version and converts nothing; rename calls to the old normalize<Event>Event.

Upgrading from pre-0.20 integer formats

The integer formatVersion era is retired, not migrated. Migrate to the reset ABI document walks the conversion. After upgrading Pina:

1. run pina migrations sync (or pina migrations create) in the program directory — every checked-in draft is regenerated at the current abiVersion;
2. commit the rewritten manifest.json and publications.json.

A ledger that pinned a real deployment would have no upgrade path from the integer formats. None exists today — the only non-empty receipt in any example records the fixture cluster — and accepting that one-time stranding is recorded in ADR 0009.

What this does not cover

This mechanism governs the document. It is not the on-chain migration system:

• it does not read or write account bytes;
• it does not allocate or consume a contract version;
• a broken converter cannot corrupt an account, because no account data passes through it.

The publication ledger records no manifest digest. A 0.20 receipt carried a manifestSha256, but it hashed a manifest that later versions rewrite and nothing compared it, so 0.21 drops it. What a receipt proves comes from its pins instead: the schema and transition hashes of every version it made live, which every later check compares with the checked-in manifest. ADR 0009 records the decision.

The on-chain rules — envelopes, adjacent transitions, rent, the publication ledger, and the four scenarios — are in How ABI migrations flow.

Checklist for an ABI-affecting release

1. Change the document shape, or the pina_abi contract. deny_unknown_fields means every document change is breaking; there are no additive-only changes.
2. Advance crates/pina_abi/ABI_VERSION to the next minor. The value leads the crate until the release bump catches up.
3. Add the adjacent converter edge — a real one when the bytes changed, a validating no-op when they did not.
4. Add the breaking changeset on pina_abi. The ahead-requires-changeset guard fails without it.
5. Regenerate the canonical schemas and the current/ fixtures, freeze the outgoing version’s fixture directory, and copy the new version’s schemas into the hosted location.
6. Run pina migrations sync so every checked-in example is rewritten at the current version, and confirm the current/ fixtures changed — or, for a no-op edge, did not.
7. Run pina migrations check and the pina_abi suite. The not-lag, ahead-requires-changeset, fixture-drift, and gapless-walk tests are the four gates that must pass.

Migrate value rules to comparisons

Value rules in #[pina(validate(...))] are now comparisons over the field’s value or its len, so the annotation reads as the check it generates. The min, max, min_len, max_len, and exact_len parameter spellings are deprecated: they still parse and generate the identical checks, but each one warns at the parameter and names its replacement.

Nothing on the wire changes. Value rules are not recorded in the ABI document or migration manifests, and the deprecated spellings generate the same checks their replacements generate, so migrating an annotation is a rename, not a release.

Rewrite each named bound as a comparison

#![allow(unused)]
fn main() {
// before
#[pina(validate(min = 1, max = 1_000_000, error = TransferError::InvalidAmount))]
pub amount: u64,

// after
#[pina(validate(value >= 1 && value <= 1_000_000, error = TransferError::InvalidAmount))]
pub amount: u64,
}

Chain bounds on one receiver with && and separate rules with ,. A chain may also put the receiver in the middle, mirroring the range it checks:

#![allow(unused)]
fn main() {
#[pina(validate(100 < value <= u64::MAX))]
pub amount: u64,

#[pina(validate(4 < len <= 100))]
pub memo: String<100>,
}

Comparisons also express what the named bounds could not. Use value != 0 for a declarative non-zero check, or len != EXPR to reject one specific length.

What keeps its single =

Named parameters that are not comparisons keep their spelling:

• error = ERROR names the failure to raise, not a comparison. It stays in the validation group it overrides.
• validate(with = function) in the outer macro is a hook parameter and keeps =.
• Account rules in #[derive(Accounts)] — signer, address = EXPR, owner = EXPR, owners = EXPR, program = EXPR, sysvar = EXPR, data_len = EXPR, distinct_from = FIELD, empty, not_empty, writable, executable — are unchanged. Only value rules over value and len moved to comparisons.

Read the deprecation warning

Each deprecated parameter warns at the token the author wrote, which is the ordinary deprecated lint: #[allow(deprecated)] silences it and -D warnings fails on it.

warning: use of deprecated constant `_::PINA_DEPRECATED_VALIDATION_BOUND`: `min` is deprecated;
write the bound as a comparison, as in `value >= 1`
 --> src/lib.rs:8:22
  |
8 |     #[pina(validate(min = 1, max = 10))]
  |                      ^^^

The warning lowers to an empty const block, so it costs no compute units and adds no bytes to the program.

Type gates and duplicates carry over

A comparison is subject to the same gates its named bound was: value rules require an integer field (u8 through u128, i8 through i128, or the Pina Pod* integer types), and len rules require String<N>, PodString<N, PFX>, Vec<T, N>, PodVec<T, N, PFX>, or [u8; N]. Duplicates and the exact_len conflict are diagnosed the same way, spelled for the new grammar where the rule that triggered them is new.

See Declarative Validation for the complete rule table.

Migrate to the reset ABI document

Pina 0.20 replaced the ABI document’s two integer counters with one abiVersion pinned to the pina_abi release line, and removed every derived field from the document. The old documents are not readable by the new release — not rejected as unsupported, but unparseable — so a program with checked-in migration documents must convert them once.

Your on-chain bytes are untouched. Discriminators, version envelopes, PinaPod payloads, and generated clients are identical before and after. This migration rewrites JSON files on disk; no account data moves and no instruction changes. If your program never enabled migrations, there is nothing to do.

The design is recorded in ADR 0009, and the versioning rules it introduced are in ABI document versioning.

The current release writes abiVersion 0.21. The conversion below still produces 0.20 documents. Step 3 rewrites the ledger at the current version, and every reader converts the manifest in memory until the next pina migrations create writes it at the current version. 0.21 also changed how instructions and events are recorded, so read Upgrading from ABI 0.20 once this guide is done.

The symptom

After upgrading, the first Pina command that reads a migration document fails:

error: Could not decode migration file migrations/manifest.json: migration manifest is
missing a string `abiVersion` field

That is the old document. The new reader fails closed on it because every removed field is rejected by deny_unknown_fields, and the version key itself was renamed. There is no converter from the integer formats: they described a document shape nothing external ever consumed, so the reset retires them instead of migrating them.

Choose a path

A program that was never deployed can always start fresh: version numbers have no on-chain meaning until an account is written. A deployed program must keep its history — accounts on chain carry the version numbers your manifest recorded, and resetting that history makes every existing account read as a future version the program refuses to load.

Either way, first delete version_type (or version-type) and auto from the [migrations] table of pina.toml, keeping any [migrations.answers]. Current releases record the version width and the auto policy only in the manifest and refuse both keys, naming the pina migrations create flag and value that record the same setting.

Start fresh

From the program directory:

rm -rf migrations
pina migrations create --no-interactive --auto true --version-type u8
pina migrations check

Pass the --auto and --version-type values your pina.toml used to set, or omit either flag for no auto policy and u8 versions. create rebuilds the manifest from source at the current abiVersion, regenerates tests/abi_layout.rs, and recreates the publication ledger on your next deploy. Draft version history collapses to version zero — which is exactly why this path is for programs nothing has been deployed to yet.

Keep your history

Two edits and one repair command, then the normal verify loop. Work from the program directory.

1. Convert the manifest

Save this as convert-manifest.jq:

del(.formatVersion)
| .abiVersion = "0.20"
| .contracts |= with_entries(
	.value.versions |= map(
		del(.version, .schemaSha256, .processSha256)
		| .schema |= del(.physical)
		| .transition |= del(
			.from,
			.to,
			.sourceSchemaSha256,
			.destinationSchemaSha256,
			.sourceProcessSha256,
			.destinationProcessSha256,
			.process
		)
		| if .process then .process.accounts |= map(del(.constraints)) else . end
	)
)

Every deleted key is a field the new model derives on load: the version number is the entry’s position, the hashes are computed from the decoded content, the physical descriptor comes from the field grammar, and a transition’s adjacency is implied by the version it sits on. Apply it:

jq -f convert-manifest.jq migrations/manifest.json > manifest.next &&
	mv manifest.next migrations/manifest.json

2. Convert the publication ledger

Save this as convert-publications.jq:

del(.formatVersion)
| .abiVersion = "0.20"
| .receipts |= map(
	del(.cluster)
	| .versions |= with_entries(.value |= {version: .version, history: []})
)
| if .pending then
	.pending.versions |= with_entries(.value |= {version: .version, history: []})
else
	.
end

jq -f convert-publications.jq migrations/publications.json > publications.next &&
	mv publications.next migrations/publications.json

Two things happen here, and both are deliberate. The cluster label is gone from receipts — the credential-free rpcUrl is the record now, and the pending record keeps its label because pina deploy matches on it. And each receipt’s history is emptied: the old pins hashed a document shape that no longer exists, so keeping them would fail every future check, while emptying them keeps what matters — the recorded version, which the next step pins again.

3. Pin the receipts

A current ledger must pin every version each receipt made live, so every command refuses the emptied histories until they are pinned again, naming the repair:

publication ledger 0.20 cannot be upgraded: receipt 0 names `account:1:01` without pinning its
published schemas. Confirm with version control that migrations/manifest.json still records exactly
what was deployed, then run `pina migrations reconcile --pin-legacy` to pin it

Once version control confirms that the manifest you converted in step 1 still describes exactly what those receipts made live, run:

pina migrations reconcile --pin-legacy

For each emptied entry it pins versions 0 through the recorded version from the manifest: the schema hash of each and, when it has one, the hash of the transition that enters it. That is trust on first use, which is why the confirmation comes first. The command writes the ledger in the current shape, so sequence, programId, manifestSha256, the previousReceiptSha256 chain link, and each contract’s version are gone and each contract becomes its list of pins. Nothing checks the old chain, so the edit in step 2 needs no chain repair.

4. Regenerate and verify

pina migrations create --no-interactive
pina migrations check
pina migrations status

create rewrites the manifest canonically and regenerates tests/abi_layout.rs. check must pass before anything builds. status is your proof the conversion preserved state: every contract shows the same version number it showed before the upgrade, and deployed contracts still read published. Confirm one live account still loads with pina migrations inspect <ADDRESS>, then commit the rewritten documents.

What pina_abi library consumers must change

If you import pina_abi directly — a custom indexer, a verification tool — the API moved from stored fields to derived values. The mapping:

Added: walk_document and AbiStep for converter tables, parse_document_version and current_abi_version for comparisons, and document_schema / render_document_schema / schema_url behind the new pina abi schema command.

0.21 changed the API again. DataCodec and DataSchema::codec are removed: the wire codec is SCHEMA_CODEC, implied by abiVersion. ContractHistory::identity is no longer serialized and is filled from the contract key when a manifest is read (ContractIdentity::from_key parses one). ContractHistory gains envelope and is_migrated(). AbiStep carries one converter per document (manifest and publications), and walk_document takes an AbiDocument instead of a label.

The 0.21 ledger keeps only what nothing else records. PublicationReceipt and PendingPublication lose sequence, program_id, manifest_sha256, and previous_receipt_sha256, and PublicationReceipt::sha256 is removed. PublishedContract serializes as its list of pins: its version field and PublishedContract::legacy are gone, version() returns the position of the last pin, and pins(n) reports whether version n is pinned. pin_legacy_publications pins a 0.20 ledger’s unpinned entries from a manifest. wire_type and DataSchema::same_wire compare types by what they store, and MigrationAuto and MigrationVersionType implement FromStr for the --auto and --version-type spellings.

Troubleshooting

After the conversion, abiVersion is maintained for you: pina migrations create writes the current version, and the value advances only when a future pina_abi release changes the document contract — never for a CLI fix, never for a program schema change.

Migrate to automatic migrations

Automatic migrations let a program keep reading the bytes it already wrote. Instead of treating every schema change as a breaking deploy, Pina gives each opted-in account and event a framework-owned version field, snapshots the history into a checked-in manifest, and migrates accounts on demand when a stale one is touched. Instructions are recorded as snapshots that stop a wire-breaking change at build time, and gain a version field only when they opt in.

This guide upgrades a program to that workflow and opts it in wholesale with an auto policy, so new contracts are versioned without per-declaration annotations. It also lists the compatibility work that the change brings: the envelope is a wire-format change for accounts and events, and the generated clients change shape.

Before you start: this guide assumes the program is new, or that you are prepared to change the wire format of its accounts, instructions, and events deliberately. If the program is already live and its accounts were written without an envelope, read Adopting on a live program before you start.

What the envelope changes

Every enveloped contract gains one field immediately after its discriminator:

before: [discriminator][payload]
after:  [discriminator][schema version][payload]

An instruction covered by auto without the token keeps [discriminator][payload]. The manifest records one snapshot of it ("envelope": false), the build fails when the struct drifts from that snapshot, and after publication its payload is fixed: a new payload needs a new discriminator. How a migration flows covers the rules.

The version is little-endian, stored per contract, and hidden from generated accessors, patches, and instruction arguments. Each account, instruction, and event carries its own history starting at version 0, so a program with one account at version 3 and another still at 0 is normal. Only the width is program-wide: pina migrations create --version-type records it once for the program as versionType in the manifest: u8 (255 versions per contract, the default and the recommendation), u16, or u32. There is deliberately no u64; see Core Concepts.

Because the version is part of the bytes, changing it after publication is a breaking change for every migration-aware contract. That is why --version-type can change the width only while nothing is published, and why the manifest is checked in.

Step 1: Upgrade the dependency

[dependencies]
pina = { version = "0.17", default-features = false, features = ["derive"] }

Keep whatever feature set your program already uses. The breaking changes in this release are listed in What changes for clients and in the changelog.

A program that already has a migrations/manifest.json at abiVersion 0.20 recorded every instruction with an envelope. Read Upgrading from ABI 0.20 before running create, so a published instruction keeps its wire format.

Step 2: Choose the policy

The policy is a flag on the command that records the history in the next step:

pina migrations create --auto true # or --auto accounts,events,instructions, or a staged subset

--auto accepts true (or all) for every kind, false (or none) to clear the policy, or a comma-separated list of accounts, events, and instructions. Any other name, or a name listed twice, is rejected. Add --version-type u16 (or u32) to the same run only if one contract may need more than 255 versions.

Staging is a real option because the kinds cost different amounts. Covering instructions does not change their payload bytes: auto records each instruction as a snapshot without an envelope. An instruction you opt in with #[instruction(discriminator = X, migrations)] does gain the envelope, which changes its payload bytes and ripples into CPI call sites, so opt instructions in one at a time while your callers catch up.

The policy lives only in the manifest: the macros read the checked-in migrations/manifest.json, and pina.toml holds no copy, because a proc macro does not re-expand when an unrelated toml file changes and a second copy could disagree with the first. A program that still carries the retired [migrations].auto or [migrations].version_type keys fails every command that reads pina.toml until they are removed; the error names the create flag and value that record the same setting.

Step 3: Snapshot the history

pina migrations create --auto true

This records the policy in migrations/manifest.json, snapshots the current schema of every contract of the listed kinds, and generates an adjacent transition for each change it can prove structurally. Later runs keep the recorded policy, so they need no flag. Commit the manifest with your source: it is the checked-in source of truth the build consults.

A declaration the manifest does not record yet fails the build with the pina migrations create remedy, so you cannot forget a contract by accident.

Adding migrations to a program that is already published is a bulk wire-format change: for each newly enveloped contract, create records the envelope as a migration step rather than pretending the bytes already had one. A snapshot-only instruction adds no byte, so it does not count.

Step 4: Keep the build honest

When a policy is recorded, create scaffolds a build script so a policy flip re-expands every contract without a source edit:

fn main() {
	println!("cargo:rerun-if-changed=migrations/manifest.json");
}

The scaffold is idempotent and never overwrites a hand-written build script — when it cannot safely write one, it prints the exact line to add. Run pina migrations check in CI: it fails on drift, on incomplete manual transitions, and on a missing rerun directive.

Step 5: Answer what the diff cannot

Structural changes generate themselves (added, removed, reordered, or reseated fields). Semantic ones do not: a rename that changes meaning, a type narrowing, a split or merge of a field, or an authority change stops the build until you implement the transition and supply fixtures. That is the intended safety property — Pina will not guess what a value should become. A respelling that stores the same bytes, such as PodU64 as u64 or Address as [u8; 32], is not a change at all: it consumes no version and needs no transition.

Run pina migrations create after every schema change; when it reports an unresolved transition, implement it there. Fixed-account transitions are total and infallible once the exact source shape is validated; manual instruction transitions run in scratch space, so they can reject a value before anything is written. An instruction transition that adds an argument is always manual, because a zero-filled default is indistinguishable from a value the client sent. Events have no transitions: a changed event appends a version with its own schema.

Step 6: Know the bill before you ship

pina migrations status
pina migrations status --json

The status output now carries the cost preview: per contract, the current size, the pending growth for a day-one account, and the approximate rent deficit at the established ~6,960 lamports per grown byte; per instruction, the worst-case adjacent-step ladder a stale account can trigger with its static compute estimate; and a program-wide summary of the most expensive touching transaction. Sizing max_lamports and MAX_INLINE_STEPS stops being guesswork.

When a transition grows an account, create states the estimated deficit and names the on-chain error a too-small budget produces. Each budget failure is separately diagnosable on-chain, and each error’s rustdoc names its remedy:

Step 7: Regenerate the clients

Regenerate the IDL and every client after the program surface changes. pina generate refreshes the project IDL as part of the same run:

pina generate --client rust --client typescript --client dart
pina generate --client cpi
pina generate --client cli-rust

Generated clients write the current envelope version automatically, so they need no new arguments. Three client-side behaviors are new and worth reviewing in the diff:

• Event decoders enforce the envelope. Each earlier version of an event is its own generated event, <Event>V<n>, with that version’s codec. The program-level log parser (parse<Program>EventsFromLogs in TypeScript and Dart) routes each record by discriminator and version and throws on a version no generated event describes; regenerate the client to decode it. Nothing is projected into the current shape. Prefer the generated log entry points over decoding event bytes by hand.
• Account decoders and the read-only view. Account loaders still reject a foreign version with an actionable error. When a program only ever reads a migratable account, try_from_bytes_versioned returns a Current or historical view without migrating; you then handle each representation your history exposes.
• Migration-aware helpers. Generated clients carry the per-account needsMigration checks and the reserved Migrate composer, so a client can send the sweep before the real instruction described in How a migration flows.

Step 8: Roll out

1. Deploy the program. A stale enveloped account is migrated by whichever instruction touches it writably; a read-only touch fails with MigrationRequired until one writable touch happens.
2. For read-heavy accounts, send the sweep instruction first — it migrates every listed account that is behind and is cheap to send speculatively. The full pattern, including the payer rules, is in How a migration flows.
3. Ship the regenerated clients. A client generated from an older release keeps working: it writes its own frozen version, the program migrates the accounts it touches, and an instruction that opts into migrations has its payload normalized before the handler runs.

Adopting on a live program

This is the case the automated flow deliberately does not decide for you.

Pina refuses to interpret unversioned bytes as version zero, because the first bytes of an old payload could look like a valid version by accident. So a program whose accounts were written before the envelope existed cannot simply switch auto on: the existing accounts have no version field, and no generated transition can read a layout nobody recorded. Instructions do not have this problem: auto records them as snapshots without an envelope, which match the bytes live clients already send.

You have two honest options:

1. A new discriminator. Ship the versioned layout under a fresh account or instruction discriminator. Nothing is silently reinterpreted, and both layouts can coexist while you move accounts over.
2. A deliberate legacy bridge. Record the unversioned layout as the baseline and write the transition into the enveloped shape by hand, then migrate accounts through a writable path you control.

The framework ergonomics for the second option are specified in ADR 0008 and are not built yet. Until they are, treat adoption on a live program as a migration project rather than a configuration flip — and confirm the exact account bytes you expect with pina migrations status before enabling the policy in production.

What changes for clients

• The wire format of every enveloped contract gains the version field. Anything that parses raw account data, event records, or the payload of an instruction that opts into migrations without going through the generated client must be updated. A snapshot-only instruction’s payload is unchanged.
• Generated event decoders changed shape: decoded events include the envelope’s discriminator and migration version, and each historical version is its own <Event>V<n> event decoded with its own schema. Decoded records carry no source-version or was-migrated flag, because nothing is converted.
• The on-chain budget error was split into the three distinguishable codes above. The legacy aggregate code keeps its original value so binaries compiled before the split stay decodable, but client error mappings should learn the new codes.

Verify the result

• pina migrations check in CI, to fail on drift or a missing rerun directive.
• pina test --compatibility to exercise every historical version of every contract against checked-in fixtures.
• pina migrations status to review the cost picture before deploying.

Once those pass and the manifest is committed, the next schema change flows through create instead of through a breaking deploy.

Migrate Pina to PinaPod v0.2

This guide covers the coordinated PinaPod v0.2 and Pina migration. PinaPod v0.2 breaks Rust source compatibility, but preserves existing fixed and compact wire bytes. Both repositories are maintained together, so the migration removes the v0.1 names instead of carrying aliases.

Merge and release in dependency order

1. Merge the PinaPod v0.2 pull request after its native, Miri, compile-fail, and benchmark checks pass.
2. Publish PinaPod v0.2 and its mdBook documentation.
3. Replace Pina’s temporary path or Git dependency with the published v0.2 version.
4. Update Cargo.lock and run Pina’s locked test matrix.
5. Regenerate Pina’s IDLs and Rust, TypeScript, and Dart clients.
6. Merge the Pina pull request after its generated-artifact and SBF checks pass.

Do not merge Pina first. Published Pina crates must not contain a path dependency, and Pina’s CI rejects a manifest-only dependency update because it runs Cargo with --locked.

Update public names

Replace the v0.1 names as one change:

Pina re-exports the new names from crates/pina/src/lib.rs. Pina’s #[account], #[instruction], and #[event] macros inject #[derive(PinaPod)], so application schemas normally do not name the derive.

Manual PinaPodFixed implementations are unsafe. The implementation must prove the layout, alignment, initialization, and validation invariants documented by PinaPod. Prefer Pina’s schema macros.

Use fixed strings, vectors, and options directly

Fixed Pina schemas now accept bounded collections and recursively fixed options:

#![allow(unused)]
fn main() {
#[account(discriminator = AccountType)]
pub struct Profile {
	pub authority: Address,
	pub display_name: String<32>,
	pub scores: Vec<u64, 8>,
	pub delegate: Option<Address>,
	pub note: Option<String<64>>,
	pub history: Vec<Option<u16>, 16>,
}
}

The fixed layout reserves every field’s full capacity. For example, String<32> occupies its length prefix plus 32 data bytes even when it is empty. PinaPod zeroes inactive capacity during initialization and after values become shorter. It also validates every active nested value before returning a safe view.

String<N> and Vec<T, N> are PinaPod schema aliases. Their source is visible to Rust tooling, but the short names keep declarations readable. Use the Pod* forms to select a prefix width:

#![allow(unused)]
fn main() {
#[account(discriminator = AccountType)]
pub struct Archive {
	pub title: PodString<1024, 2>,
	pub entries: PodVec<u64, 1024, 2>,
}
}

The final const argument is the prefix width in bytes. It must be 1, 2, 4, or 8. Do not use #[pinapod(prefix = u16)]; v0.2 does not use an attribute to configure container prefixes.

Move the fixed collection fixtures from tests/ui/fail to tests/ui/pass. Keep runtime tests for empty, full, and over-capacity values, invalid UTF-8, invalid option tags, invalid nested elements, clearing, and replacement.

Initialize fixed accounts in one pass

Typed fixed-account creation now has two initialization paths:

• invoke::<T>() and invoke_signed::<T>(signers) write the discriminator and leave every other byte at zero. Use them only when that completed representation is valid.
• invoke_with::<T>(initialize) and invoke_signed_with::<T>(signers, initialize) run a caller-supplied initializer before PinaPod validates the completed representation. Use them when the account needs nonzero initial values.
• invoke_with_bump::<T>(initialize) and invoke_signed_with_bump::<T>(signers, initialize) also pass the canonical bump into the initializer so the account can store it without a second derivation.

Move a create-then-mutate sequence into the creation call:

#![allow(unused)]
fn main() {
CreateProgramAccountWithBump {
	account: self.profile,
	payer: self.authority,
	owner: &ID,
	seeds: &seeds.as_slices(),
	bump,
}
.invoke_with::<Profile>(|profile| {
	profile.authority = *self.authority.address();
	profile.name.try_set("Alice")?;
	profile.scores.try_set([10, 20, 30])?;
	Ok(())
})?;
}

The closure receives &mut T::Zc and returns Result<(), PinaPodError>. PinaPod zeros the complete account representation, Pina writes the discriminator, the closure configures the remaining fields, and PinaPod validates once at the end. If the closure or validation fails, PinaPod zeros the account bytes again and the create instruction returns InvalidAccountData.

This distinction matters for advanced manual PinaAccount implementations. A storage enum such as Ready = 1 has no valid all-zero discriminant, so invoke::<T>() fails validation. Set the field inside invoke_with instead:

#![allow(unused)]
fn main() {
.invoke_with::<RequiredState>(|state| {
	state.mode = RequiredMode::Ready.into();
	Ok(())
})?;
}

Pina’s audited #[account] grammar still rejects arbitrary custom enum fields. The enum example applies to a direct PinaPod schema with a manual PinaAccount implementation. Use invoke_with for ordinary macro-generated accounts too when atomic initialization is clearer than borrowing and mutating the account after creation.

When the payer needs additional PDA signatures, pass them before the initializer:

#![allow(unused)]
fn main() {
builder.invoke_signed_with::<Profile>(&payer_signers, |profile| {
	profile.authority = authority;
	Ok(())
})?;
}

Load fixed PDA accounts in one pass

Do not validate a fixed PDA with assert_type, load it again through the generated assert_seeds, and then load it a third time for mutation. Bounded strings and nested containers make each recursive validation meaningful, so repeating the boundary also repeats its compute cost.

Use the one-pass helpers generated for fixed #[account] plus #[pda(bump = ...)] schemas:

#![allow(unused)]
fn main() {
let mut profile = Profile::load_pda_mut(
	self.profile,
	self.authority.address(),
	&ID,
)?;
profile.name.try_set("Alice")?;
}

load_pda_mut checks writability, owner, exact size, discriminator, every active PinaPod value, and the account address derived from the stored bump before it returns the mutable guard. load_pda provides the same one-pass contract for immutable access. Both guards retain the runtime data borrow, so drop them before a CPI that can access the account.

Keep Type::assert_seeds for a validation-only path that does not need a typed guard. The one-pass loaders are the preferred path when code reads or writes the account immediately afterward.

Apply the same rule to non-PDA fixed accounts: replace assert_type::<T>() followed by as_account::<T>() or as_account_mut::<T>() with the typed loader alone. Both loaders perform the owner, discriminator, exact-size, and nested-value validation before returning their borrow guard. Keep assert_type only when validation is the final operation on typed data, such as a close path that never reads the fields. It releases the borrow before returning and must not be treated as proof for a later raw cast.

Typed fixed-account boundaries now return PinaProgramError::InvalidAccountSize when the account is undersized or oversized. This applies to assert_type, as_account, as_account_mut, load_pda, and load_pda_mut. Update any precise error matching that previously expected ProgramError::AccountDataTooSmall or ProgramError::InvalidAccountData for these size failures. The generic assert_data_len check retains its existing ProgramError::InvalidAccountData contract.

Load compact PDA accounts in one borrow

Do not validate a compact PDA with assert_compact_type, load its bump through generated assert_seeds, and then parse it again with with_compact_account.

Use Type::with_pda for a compact #[account] with #[pda(bump = ...)]:

#![allow(unused)]
fn main() {
let (revision, entries) = Journal::with_pda(
	self.journal,
	self.authority.address(),
	&ID,
	|journal| Ok((journal.revision.get(), journal.entries().len())),
)?;
}

with_pda validates ownership, compact data, and the address the stored bump derives before it runs the closure, using a single derivation. with_checked_pda searches for the canonical bump instead and rejects an account at any other address or with a noncanonical stored bump. The closure cannot return the borrowed compact view. Use assert_compact_type or generated assert_seeds only when code needs validation without field access.

Keep compact nesting inside the supported grammar

A compact account places fixed fields first and compact tails last. It can contain several tails. PinaPod v0.2 accepts these compact forms:

• String<N>
• Vec<T, N> where T has a fixed PinaPod representation
• Option<T> where T has a fixed PinaPod representation
• Option<String<N>>
• Option<Vec<T, N>> where T has a fixed PinaPod representation
• Vec<String<M>, N>

Option<T> for fixed T remains an inline header field. The other forms use compact tail storage. Vec<String<M>, N> stores fixed-footprint string elements, so each active element occupies its own prefix plus M bytes. The strings can have different logical lengths.

#![allow(unused)]
fn main() {
#[account(discriminator = AccountType, compact)]
pub struct Journal {
	pub authority: Address,
	pub revision: u32,
	pub archived_at: Option<u64>,
	pub title: String<64>,
	pub entries: PodVec<u64, 1024, 2>,
	pub note: Option<String<128>>,
	pub labels: Vec<String<24>, 16>,
}
}

Pina’s schema classifier is closed. It rejects unsupported nesting instead of accepting an arbitrary ZcField implementation. The diagnostic lists the supported forms.

Compact creation also requires an initial patch. Pass it to invoke, or construct it from the canonical bump with invoke_with_bump:

#![allow(unused)]
fn main() {
CreateCompactProgramAccount {
	account: self.journal,
	payer: self.authority,
	owner: &ID,
	seeds: &Journal::seeds(self.authority.address()).as_slices(),
	space: Journal::MIN_SIZE,
}
.invoke_with_bump::<Journal, _>(|bump| {
	JournalPatch::new()
		.bump(bump)
		.authority(*self.authority.address())
		.revision(0)
})?;
}

The builder applies patch while it initializes the allocated bytes. Omitted patch fields use their zero, empty, or absent representation. Include nonempty tail replacements in the patch and allocate enough space for those encoded values.

Replace staged compact mutation with a patch

PinaPod v0.1 exposed a mutable view whose setters accumulated changes before commit(). The caller also had to order ReallocCompactAccount differently for growth and shrink. Remove that lifecycle.

Build a generated patch and pass it to Pina’s typed update operation:

#![allow(unused)]
fn main() {
UpdateResizableAccount {
	account: self.journal,
	rent_account: self.authority,
	program_id: &ID,
	patch: JournalPatch::new()
		.revision(next_revision)
		.replace_entries(&entries)
		.note(Some("Updated")),
}
.invoke::<Journal>()?;
}

JournalPatch distinguishes an unchanged field from a field set to an empty or absent value. A method named after a fixed field replaces that field. A replace_* method replaces a collection tail. The patch validates every requested value and computes the target length before Pina changes account bytes or lamports.

The typed creation and update builders accept the generated patch associated with the account. They no longer accept an unrelated custom PinaPodPatch<T> implementation, because that could bypass the account’s generated structural and application validation. Existing calls that pass JournalPatch are unchanged. For a generic helper, replace a PinaPodPatch<T> bound with PinaCompactPatch<T>. A wrapper may implement PinaCompactPatch<T> by returning the generated patch it contains:

#![allow(unused)]
fn main() {
struct JournalUpdate<'a> {
	patch: JournalPatch<'a>,
}

impl PinaCompactPatch<Journal> for JournalUpdate<'_> {
	fn as_pina_patch(&self) -> &JournalPatch<'_> {
		&self.patch
	}
}
}

UpdateResizableAccount ends the data borrow before resizing. It grows the account before writing, or writes a structurally valid shorter representation before shrinking. It clears bytes removed by the update. If structural preflight fails, account bytes and lamport balances remain unchanged. With the validation feature, application rules run after the patch is written; propagate the returned error so Solana rolls back the bytes and any earlier rent movement.

Use rent_account for this builder. The account both funds growth and receives excess rent after a shrink. The lower-level ReallocAccount, ReallocAccountZeroed, and ReallocCompactAccount builders use the same field name and take an explicit target_size. Creation and allocation builders retain payer because those APIs only fund a new account.

Keep wire bytes stable

The following source changes do not change existing serialized data:

• Renaming the derive and traits changes Rust names only.
• Replacing fixed read method names changes validation entry points only.
• Replacing create-then-mutate code with invoke_with changes initialization order, not the completed fixed-account bytes.
• Replacing assert_type plus assert_seeds plus as_account* with load_pda* changes validation order, not account bytes.
• Replacing assert_compact_type plus assert_seeds plus with_compact_account with with_pda changes validation order, not account bytes.
• Replacing staged compact mutation with a patch changes how callers produce the same compact bytes.
• Adding client capacity metadata changes validation, not the encoded prefix or payload.

The following schema changes do change layout and require the normal on-chain migration process:

• Adding a new field to an existing account.
• Changing a field’s capacity or prefix width.
• Moving a field or changing its fixed versus compact classification.
• Changing a discriminator value or width.

PinaPod pins byte-for-byte v0.1 fixtures. Pina also keeps account, instruction, IDL, and generated-client fixtures so both sides detect an accidental layout change.

Regenerate clients and enforce capacity

Run Pina’s normal IDL and client generation commands after the Rust schemas compile. Compact capacity must be structured schema data, not a number recovered from field documentation. Generated TypeScript and Dart clients enforce each capacity at both boundaries:

• Encoders reject capacity + 1 before writing a prefix.
• Decoders reject an oversized prefix before allocating or iterating.
• Multi-tail accounts check each field against its own capacity.
• Decoders keep discriminator checks and consume the exact encoded length.

Do not edit files under codama/clients/*/generated by hand.

Verify the migration

Run these commands from the Pina repository:

devenv shell docs:sync
devenv shell verify:docs
devenv shell cargo test -p pina_root --test ui --locked
devenv shell cargo test -p pina --all-features --locked
devenv shell cargo test -p pina_cli --all-features --locked
devenv shell cargo test -p pina_codama_renderer --locked
devenv shell build:pina:no-default
devenv shell test:idl
devenv shell -- report:cu:compare:main

Then run the generated TypeScript and Dart contract suites, the tracked SBF compact-account build, and the Surfpool lifecycle tests. The failure cases must compare both account data and lamport balances before and after the rejected update.

The compute-unit report must show savings as positive values and increases as negative values. Exact runtime increases fail unless scripts/compute-unit-policy.json records a reviewed exception matching the PR base commit and measured baseline. See Compute-unit performance for the PinaPod v0.2 measurements and methodology.

Migrate lamport mutation calls

Pina now checks program ownership inside every public helper that directly debits lamports. This release changes Rust source APIs but does not change instruction or account wire formats.

Replace send with send_owned

Remove the separate assert_owner call and pass the executing program ID to send_owned:

#![allow(unused)]
fn main() {
// Before
vault.assert_owner(&ID)?;
vault.send(amount, recipient)?;

// After
vault.send_owned(&ID, amount, recipient)?;
}

send_owned rejects a sender that ID does not own before it changes either balance. It also retains the existing writable, self-transfer, insufficient-funds, and overflow checks.

Pass the program ID when closing an account

Pass the executing program ID to both close methods:

#![allow(unused)]
fn main() {
// Before
account.close_with_recipient(recipient)?;
account.close_account_zeroed(recipient)?;

// After
account.close_with_recipient(&ID, recipient)?;
account.close_account_zeroed(&ID, recipient)?;
}

Add program_id to the close builders:

#![allow(unused)]
fn main() {
CloseAccountZeroed {
	account,
	recipient,
	program_id: &ID,
}
.invoke()?;
}

Both builders validate ownership before changing account data or lamports. CloseAccountZeroed still clears the existing data bytes before closing. CloseAccount still leaves the old backing bytes unchanged.

Remove the old lint configuration

Delete require_program_owned_before_lamport_mutation from pina.toml if the project lists it explicitly. Pina removed the lint because send_owned now performs the check itself. Other close and lamport safety lints remain available.

Verify the migration

Run the program tests and Pina lints after updating every call:

cargo test
pina lint

Migrate to safe token loaders

Pina now exposes one clearly checked name for each token loader. The previous unsuffixed loaders were already owner-safe because the pinned pinocchio-token and pinocchio-token-2022 account-view parsers validate ownership and layout together. Pina continues to delegate to those parsers without a duplicate owner comparison. The ATA loader additionally validates the derived address and the current authority and mint stored in token-account data. This change removes the redundant checked method names and the lints that required preceding assertions.

Remove checked suffixes

Replace each removed method with its shorter equivalent:

The replacement methods enforce the same owner checks through the same checked upstream parsers. They preserve guard-backed lifetimes and return the same typed views as the removed methods.

Remove duplicate assertions

Delete owner and ATA assertions that exist only to guard an immediate loader call:

#![allow(unused)]
fn main() {
// Before
account.assert_owner(&token::ID)?;
let account = account.as_token_account()?;

vault.assert_associated_token_address(wallet, mint, token_program)?;
let vault = vault.as_associated_token_account(wallet, mint, token_program)?;

// After
let account = account.as_token_account()?;
let vault = vault.as_associated_token_account(wallet, mint, token_program)?;
}

Keep assert_owner(), assert_owners(), and assert_associated_token_address() in validation-only paths that do not read token data and do not reach an ATA instruction.

Delete an ATA address assertion that is immediately followed by associated_token_account::instructions::Create or CreateIdempotent on the same account. The associated token program derives the same [wallet, token_program, mint] seeds under its own program id and returns InvalidSeeds when they do not produce the named account, so the assertion repeats a canonical bump search worth roughly 4,500 compute units. CreateIdempotent runs that check before its idempotent branch, so it applies to existing accounts too.

#![allow(unused)]
fn main() {
// Before
vault.assert_empty()?.assert_writable()?;
vault.assert_associated_token_address(wallet, mint, token_program)?;
associated_token_account::instructions::Create { account: vault, /* ... */ }.invoke()?;

// After
vault.assert_empty()?.assert_writable()?;
associated_token_account::instructions::Create { account: vault, /* ... */ }.invoke()?;
}

Keep assert_empty() and assert_writable(): they enforce initialization state and runtime permissions, which no CPI restates.

Pick the loader by program policy

Use the unqualified legacy loaders when the instruction requires the original SPL Token program:

#![allow(unused)]
fn main() {
let mint = mint_account.as_token_mint()?;
let token_account = token_account.as_token_account()?;
}

Use the explicit Token-2022 loaders when the instruction requires Token-2022:

#![allow(unused)]
fn main() {
let mint = mint_account.as_token_2022_mint()?;
let token_account = token_account.as_token_2022_account()?;
}

Use *_for_program() when the instruction accepts either canonical token program:

#![allow(unused)]
fn main() {
token_program.assert_addresses(&[token::ID, token_2022::ID])?;
let program_id = *token_program.address();
let mint = mint_account
	.as_token_mint_for_program(&program_id)?
	.assert_no_extensions()?;
let account = token_account.as_token_account_for_program(&program_id)?;
}

The dynamic loaders reject unsupported program IDs and require each account’s runtime owner to equal program_id.

Update lint configuration

Remove these retired lint names from [lints] in pina.toml:

require_owner_before_token_cast = "deny"
require_associated_token_address_before_ata_cast = "deny"

Pina no longer needs lexical checks for these conditions because the loader boundary enforces them at runtime. require_consistent_token_program and require_explicit_token_2022_extension_policy remain active.

Check ATA assumptions

as_associated_token_account() is a canonical ATA loader. It rejects the address before parsing when it is not the ATA derived from wallet, mint, and token_program. It then rejects a token account when its stored current authority or mint differs from those inputs. A token account whose authority was reassigned remains at its original associated address, but it is no longer canonical for the original wallet under this loader. If a program intentionally accepts that state, load it with as_token_account_for_program() and validate the program-specific relationship explicitly.

The loader does not require the account to be initialized or unfrozen, and it does not restrict delegates, close authority, or Token-2022 extensions. Apply those protocol-specific checks after loading. For Token-2022, use assert_extensions_allowed() or assert_no_extensions() where the protocol has an extension policy.

Check error-code expectations

The checked upstream parsers preserve their own precise errors. In particular, the legacy and Token-2022 token-account parsers currently report a wrong owner as InvalidAccountData, while their mint parsers and Token-2022 extension-aware wrapper report InvalidAccountOwner. Code should normally propagate these errors rather than branching on them. Tests that asserted an exact error from a removed *_checked wrapper may need to be updated.

Migrate to hardened security lints

This release adds a deny-by-default check for unchecked mutable remaining accounts and makes existing lint analysis follow more source-level control flow. A project that previously passed pina lint can therefore fail until it makes duplicate-account and compute bounds explicit.

Reject duplicate mutable accounts by default

Replace direct remaining_mut() calls with the distinct loader:

#![allow(unused)]
fn main() {
let remaining = cursor.remaining_mut_distinct()?;
}

The lint covers method syntax, UFCS, stored function items, and calls produced by local or dependency macros. If duplicate mutable addresses are part of the protocol, prefer the typed escape hatch and explain the invariant where reviewers can see it:

#![allow(unused)]
fn main() {
#[derive(Accounts)]
struct WeightedAccounts<'a> {
	/// Duplicate entries intentionally apply the same account's weight more than once.
	#[pina(remaining, distinct = false)]
	positions: &'a mut [AccountView],
}
}

For a manual parser, contain remaining_mut() in the smallest reviewed helper and add a local lint allowance with a specific safety comment. Do not disable the lint for the crate.

Re-establish bounds after mutation

The remaining-account bound check now follows local aliases and loop-carried state. Reassignment, mutable borrowing, a mutable method receiver, a mutable-reference function argument, or a closure that can replace a checked binding invalidates the earlier proof, including for later iterations of an enclosing loop. Move the guard after the last possible mutation:

#![allow(unused)]
fn main() {
replace_remaining(&mut remaining, replacement);

if remaining.len() > MAX_REMAINING_ACCOUNTS {
	return Err(ProgramError::InvalidArgument);
}

for account in remaining {
	process(account)?;
}
}

A constant .take(MAX) is also accepted, including when the bounded iterator is stored in a local variable. Use it only when silently ignoring surplus accounts is part of the instruction contract:

#![allow(unused)]
fn main() {
let bounded = remaining.iter().take(MAX_REMAINING_ACCOUNTS);
for account in bounded {
	process(account)?;
}
}

Adapters that cannot increase the number of items, such as filter, map, and enumerate, preserve the bound. Apply take after flat_map, flatten, cycle, or another adapter that can expand its input.

Every remaining-account source in a chained iterator needs its own dominating length check. The lint only accepts the built-in length of a slice or array as evidence; a custom method named len cannot establish a security bound.

Review unused borrow-guard warnings

The unused-borrow-guard lint now classifies each binding’s inferred type instead of matching loader names inside an expression. It therefore catches Ref and RefMut results returned through aliases or function pointers, including guards nested in tuple and let ... else patterns, while no longer treating an unrelated wrapper result as a guard merely because the wrapper consumed one. If code intentionally stores a guard, read through the binding; otherwise discard the loader result immediately with ? so the runtime borrow ends at the statement boundary. Write let _ = account.try_borrow()?; at the creation site when an explicit discard reads better. Do not write let _ = guard; after binding a guard: Rust’s wildcard pattern does not move that local, so the borrow remains live and the lint continues to warn.

Refresh the managed lint driver

No manual cache cleanup is required because there is no cache anymore. The lint driver ships prebuilt next to the pina CLI in every release archive and npm platform package, built by the release pipeline from the pinned nightly in rust-toolchain.toml — the same release pina init scaffolds. The CLI resolves the driver beside its own executable and starts it once before the lint run to confirm it loads; a CLI installed with cargo install pina_cli does not bundle a driver, so install the prebuilt CLI or set PINA_LINT_DRIVER_PATH for local lint development.

The lint run also prepends the active toolchain’s sysroot library directory to the dynamic-library search path (DYLD_LIBRARY_PATH and LD_LIBRARY_PATH on macOS, LD_LIBRARY_PATH on other Unix). Because the compiler internals in librustc_driver are keyed to the exact nightly build, the project’s active toolchain must be that pinned nightly; a mismatch fails the load check with an error naming the required toolchain instead of failing deep inside cargo with a loader exit. If PINA_LINT_DRIVER_PATH is set, make sure it points to a driver built by the same toolchain as the project.

Run the complete catalog after migrating:

pina lint

Review every lint-level override in pina.toml. Temporary allow entries can unblock an incremental migration, but restore deny-level security checks before deployment.

Migrate to internal creation emptiness checks

Pina’s typed creation builders now enforce emptiness themselves and return AccountAlreadyInitialized when the target storage holds any nonzero byte. The deny-by-default require_empty_before_init lint is retired.

Remove the lint from pina.toml

Delete the [lints] entry; the CLI now rejects the unknown name.

[lints]
# remove:
# require_empty_before_init = "deny"

Remove manual pre-creation assertions

Delete assert_empty() calls that exist only immediately before a typed creation builder. Keep assert_empty() calls that guard other operations, such as raw CreateAccount allocations or token-account creation, where the typed builders are not involved.

#![allow(unused)]
fn main() {
// before
self.state.assert_empty()?;
CreateProgramAccountWithBump { account: self.state, /* .. */ }.invoke_with::<State>(/* .. */)?;

// after
CreateProgramAccountWithBump { account: self.state, /* .. */ }.invoke_with::<State>(/* .. */)?;
}

Error behavior is preserved: the builders return the same AccountAlreadyInitialized error the manual assertions produced.

Migrate to canonical PDA builders

Pina’s typed PDA creation builders now own canonical bump validation. Remove assert_canonical_bump and assert_seeds_with_bump when they occur immediately before CreateProgramAccount, CreateProgramAccountWithBump, CreateCompactProgramAccount, or CreateCompactProgramAccountWithBump. All four validate the PDA: the explicit-bump builders reject a noncanonical supplied bump, and the bump-free builders derive and sign with the canonical one.

Keep assert_empty before creation. It preserves the distinct AccountAlreadyInitialized error and remains part of Pina’s initialization lint contract.

Migrate a supplied bump

Previously, a handler derived the PDA three times: once to find the canonical bump, once to validate the explicit bump, and once inside the creation builder.

#![allow(unused)]
fn main() {
let canonical_bump = account.assert_canonical_bump(&seeds.as_slices(), &ID)?;
if canonical_bump != args.bump {
	return Err(ProgramError::InvalidSeeds);
}

let seeds_with_bump = seeds.with_bump(args.bump);
account.assert_empty()?;
account.assert_seeds_with_bump(&seeds_with_bump.as_slices(), &ID)?;

CreateProgramAccountWithBump {
	account,
	payer,
	owner: &ID,
	seeds: &seeds.as_slices(),
	bump: args.bump,
}
.invoke_with::<State>(|state| {
	state.bump = args.bump;
	Ok(())
})?;
}

Now the builder performs one canonical search, verifies both the account address and supplied bump, and reuses that result for the PDA signer:

#![allow(unused)]
fn main() {
account.assert_empty()?;

CreateProgramAccountWithBump {
	account,
	payer,
	owner: &ID,
	seeds: &seeds.as_slices(),
	bump: args.bump,
}
.invoke_with::<State>(|state| {
	state.bump = args.bump;
	Ok(())
})?;
}

The explicit-bump builder now rejects a valid but noncanonical PDA with ProgramError::InvalidSeeds. This is an intentional security change.

Derive and store the bump

If the instruction does not need to carry a bump, let the canonical builder derive it and pass it into the initializer:

#![allow(unused)]
fn main() {
let (_address, bump) = CreateProgramAccount {
	account,
	payer,
	owner: &ID,
	seeds: &seeds.as_slices(),
}
.invoke_with_bump::<State>(|state, bump| {
	state.bump = bump;
	Ok(())
})?;
}

invoke_signed_with_bump provides the same initializer and also accepts signer seeds for a PDA payer.

Migrate compact creation

CreateCompactProgramAccount no longer stores a patch field. Pass an ordinary patch to invoke, or construct it from the derived bump with invoke_with_bump:

#![allow(unused)]
fn main() {
CreateCompactProgramAccount {
	account: journal,
	payer,
	owner: &ID,
	seeds: &Journal::seeds(authority).as_slices(),
	space: Journal::MIN_SIZE,
}
.invoke_with_bump::<Journal, _>(|bump| {
	JournalPatch::new().authority(*authority).bump(bump)
})?;
}

Code that already has a patch but does not store a bump uses .invoke::<Journal>(patch). Both signed forms take the additional signer slice before the patch or bump-aware patch factory.

CreateCompactProgramAccountWithBump keeps its patch field, but now rejects a noncanonical supplied bump before allocation.

Keep generated-client PDA resolution

The IDL extractor recognizes all four typed creation builders as canonical PDA checks:

• CreateProgramAccount
• CreateProgramAccountWithBump
• CreateCompactProgramAccount
• CreateCompactProgramAccountWithBump

Removing the redundant assertions does not make the target account required in generated clients. JavaScript callers can keep using the asynchronous builder and omit the PDA account:

const instruction = await getInitializeInstructionAsync({
	authority,
	bump,
});

The generated client derives the account from the PDA metadata in the IDL. You can still pass the account explicitly when needed.

Use noncanonical allocation only for compatibility

AllocateAccountWithBump is deprecated. Its replacement is AllocateAccountWithNonCanonicalBump, which makes the relaxed guarantee clear in code review. It accepts any valid PDA bump and only allocates untyped bytes. Use it for an existing address scheme that cannot migrate to canonical bumps. Use AllocateAccount for new PDA namespaces.

The noncanonical allocation and unchecked typed-creation builders now hash the supplied seeds locally and let the runtime perform the curve check during CPI signer derivation. An on-curve bump therefore aborts execution rather than returning a catchable Err(ProgramError::InvalidSeeds) from the builder. If an instruction catches invalid bumps and continues, call create_program_address with the full seed list, including the bump, before invoking the builder and handle its error there. This optional preflight restores recovery while keeping the default creation path cheap. Canonical builders already prove a valid bump before allocating.

Architecture decision records

This section captures the durable architectural decisions behind Pina’s public model, safety posture, and verification strategy.

ADR format and naming

• Files live under docs/src/adrs/.
• ADRs use the naming pattern NNNN-short-slug.md.
• The starter template lives at docs/src/adrs/0000-template.md.
• Architecture-impacting pull requests should link the ADR they follow or update.

ADR index

How to use this section

Use these ADRs when you need to answer questions like:

• why Pina uses discriminator-first layouts instead of external headers
• when zero-copy is allowed, and where the safety boundaries are
• why typed account loaders must be guard-backed instead of returning bare references
• why no_std and allocator constraints are treated as architecture, not implementation detail
• why token helpers are optional instead of always-on
• why Miri, compile-fail tests, feature matrices, and compute-unit checks all exist at once
• why the ABI document’s abiVersion is a committed value pinned to pina_abi’s own release line instead of counting format revisions
• why a changed PDA or known-address hint on an instruction account never blocks a published version

ADR 0001: Keep discriminator-first typed layouts

• Status: Accepted
• Date: 2026-04-18
• Deciders: Pina maintainers
• Related: Core concepts, Security model

Context

Pina’s account, instruction, and event types are designed around fixed-size, zero-copy layouts.

That only works if the byte contract is explicit and stable. The project needs a layout model that is easy to validate at runtime, easy to generate through Codama, and hard to reinterpret accidentally.

Decision

Pina keeps discriminator bytes as the first field inside every typed #[account], #[instruction], and #[event] layout.

The discriminator width is part of the ABI and is limited to u8, u16, u32, or u64.

From that decision follow a few rules:

• discriminator values are part of the protocol contract
• field order is part of the protocol contract
• widening or changing discriminator values is a breaking change
• incompatible layout changes require explicit migration instead of in-place reinterpretation

Consequences

Benefits:

• runtime validation can do a fixed discriminator read plus size_of::<T>() checks
• generated Rust clients can match on-chain layouts exactly
• zero-copy parsing stays simple and predictable
• the compatibility surface is easy to explain in docs and reviews

Costs:

• account and instruction layouts must be treated like ABI, not ordinary Rust structs
• field reordering and in-place discriminator changes become explicit migrations
• compatibility with systems that expect external discriminator headers needs adapters, not silent reuse

Alternatives considered

External discriminator headers

Rejected because they split the byte contract across a manual header parser plus a typed payload parser. That makes validation paths less uniform and weakens compiler-assisted layout guarantees.

Dynamic serialization formats

Rejected because they add copy/parse overhead, complicate no_std use, and weaken the fixed-layout guarantees that Pina uses for predictable compute costs.

ADR 0002: Keep zero-copy behind explicit validation

• Status: Accepted, amended for PinaPod v0.2
• Date: 2026-04-18
• Last amended: 2026-09-07
• Deciders: Pina maintainers
• Related: Security model, PinaPod v0.2 migration, security/loaders-audit.md