# solana-program/token architecture

> Architecture diagram of the GitHub repository solana-program/token, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solana-program/token
- Repository: https://github.com/solana-program/token

## Overview

This repository is a Solana token monorepo centered on the SPL Token program, with a clear split between on-chain execution, shared ABI definitions, and off-chain clients.

At a high level, there are two execution stacks:

- The canonical SPL Token program in `program/`, which is the main on-chain implementation.
- An alternate Pinocchio-based implementation under `pinocchio/`, which mirrors the token domain model but uses a different runtime/framework and includes fuzzing assets.

Surrounding those are shared interface crates and generated clients that let off-chain code construct valid instructions, derive accounts, and decode token state.

Main subsystems

- `program/`
  - This is the primary Solana on-chain program.
  - Core files:
    - `entrypoint.rs`: Solana entrypoint boundary.
    - `instruction.rs`: instruction enum / decoding.
    - `processor.rs`: top-level dispatch into per-instruction handlers.
    - `state.rs`: token account, mint, multisig, and account-state data structures.
    - `error.rs`: program error definitions.
    - `native_mint.rs`: special handling for wrapped native SOL.
  - `program/src/processor/` contains one module per token operation: initialize, mint, transfer, burn, approve, freeze/thaw, close account, sync native, UI amount conversions, authority changes, and associated helper flows.
  - `program/src/processor/shared/` holds reusable logic that is shared across multiple instruction variants, especially the “v2/v3” style instructions such as `initialize_account2`, `initialize_mint2`, and `initialize_multisig2`.
  - `program/idl.json` is the published interface artifact for consumers and generators.
  - `program/tests/` contains integration-style tests against the Solana runtime.

- `interface/`
  - A shared Rust interface crate that defines the token ABI without the execution logic.
  - Contains:
    - `instruction.rs`
    - `state.rs`
    - `error.rs`
    - `native_mint.rs`
  - This is the contract boundary used by both the program and client generation pipeline to keep layouts and discriminants aligned.

- `clients/js/`
  - The TypeScript/JavaScript SDK for consumers.
  - Most of the SDK is generated under `src/generated/`, including:
    - account codecs and type definitions
    - instruction builders
    - PDA helpers
    - program identifiers
    - error mappings
  - Hand-authored helpers in `src/` add convenience APIs on top of the generated layer, such as:
    - `createMint.ts`
    - `mintToATA.ts`
    - `transferToATA.ts`
    - `plugin.ts`
  - This client also includes tests that validate the generated instruction builders and helper flows against a local validator.
  - `codama.json`, `tsup.config.ts`, and `typedoc.json` indicate a generation/build/doc pipeline for the SDK.

- `clients/rust/`
  - A Rust client crate for off-chain Rust consumers.
  - It is the Rust analogue of the JS SDK: a consumer-facing package that wraps the token interface for application code.

- `pinocchio/interface/` and `pinocchio/program/`
  - A second, parallel token implementation stack.
  - It contains the same conceptual pieces as the canonical program stack:
    - interface definitions
    - account/mint/multisig state
    - instruction and error definitions
    - processor modules for each token operation
  - `pinocchio/program/src/processor/shared/` shows the same reuse pattern as the canonical program.
  - `pinocchio/program/fuzz/` contains fuzz inputs, expected outputs, and corpus material, making this stack a security/robustness boundary as well as an implementation.
  - This subtree is important architecturally because it validates token semantics independently of the main program runtime.

Key boundaries and data flow

1. Off-chain consumers build token instructions
   - Applications use `clients/js` or `clients/rust`.
   - They rely on shared interface definitions and generated account/PDA helpers.
   - For ATA-related flows, the SDK also exposes helpers around associated token account derivation and creation.

2. Transactions enter the Solana runtime
   - The Solana validator/runtime passes instruction data and account metadata into the on-chain program entrypoint.
   - The runtime boundary is explicit: the program cannot assume any state except what is provided via accounts and instruction data.

3. The program decodes and dispatches
   - `entrypoint.rs` hands control to the instruction processor.
   - `instruction.rs` identifies the instruction variant.
   - `processor.rs` routes to the appropriate handler module.

4. Handlers mutate token state
   - Processor modules operate on mint, token account, multisig, and native mint-related state.
   - Shared helper modules reduce duplication across instruction variants and preserve consistent semantics.
   - Special cases include wrapped native SOL behavior, account freezing/thawing, authority management, and associated token account flows.

5. State and ABI are kept consistent across crates
   - `interface/` defines the canonical token data model.
   - `program/idl.json` and the generated JS artifacts are downstream representations of the same contract.
   - This is the main contract boundary that keeps on-chain and off-chain code in sync.

6. Tests and fuzzing validate behavior
   - `program/tests/` and `pinocchio/program/tests/` verify instruction behavior.
   - `pinocchio/program/fuzz/` provides a fuzzing boundary for adversarial input coverage.
   - The repo also includes local validator scripts and CI workflows for repeatable validation.

Technologies and tooling that matter architecturally

- Rust workspace for the on-chain program and shared interface crates.
- TypeScript/JavaScript package for the generated SDK.
- Solana runtime and local validator as the execution environment.
- Code generation driven by Codama artifacts.
- GitHub Actions for CI and publishing (`publish-js.yml`, `publish-rust.yml`, `main.yml`).
- PNPM for JS workspace management and Rust/Cargo for the program/client crates.

In diagram terms, the most important boxes are:
- the canonical on-chain token program,
- the shared token interface/IDL layer,
- the generated off-chain clients,
- and the optional Pinocchio reimplementation with its fuzz/test harness.

The most important arrows are:
- interface/IDL → generated clients,
- client instruction builders → Solana transaction → program entrypoint,
- entrypoint → instruction dispatch → per-op processor modules,
- processors ↔ token account/mint/multisig/native mint state,
- and tests/fuzzers → program behavior validation.

Main entry points: [`clients/js/src/generated`](https://github.com/solana-program/token/tree/HEAD/clients/js/src/generated) (JS generated), [`pinocchio/program/src/processor/mod.rs`](https://github.com/solana-program/token/blob/HEAD/pinocchio/program/src/processor/mod.rs) (Pin processor), [`program/src/instruction.rs`](https://github.com/solana-program/token/blob/HEAD/program/src/instruction.rs) (Instructions), [`program/src/processor.rs`](https://github.com/solana-program/token/blob/HEAD/program/src/processor.rs) (Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Canonical SPL Token"
  program_entrypoint["Entrypoint<br/>on-chain boundary<br/>[entrypoint.rs]"]
  program_instruction["Instructions<br/>ABI decode<br/>[instruction.rs]"]
  program_processor["Processor<br/>dispatch core<br/>[processor.rs]"]
  program_ops["Token ops<br/>handlers"]
  program_shared["Shared flows<br/>reusable logic"]
  program_state["Token state<br/>account models<br/>[state.rs]"]
  program_error["Errors<br/>error set<br/>[error.rs]"]
  program_native_mint["Native mint<br/>special-case logic<br/>[native_mint.rs]"]
end

subgraph "Shared Contract"
  program_idl["IDL<br/>interface artifact<br/>[idl.json]"]
  interface_instruction["ABI instructions<br/>shared ABI<br/>[instruction.rs]"]
  interface_state["ABI state<br/>shared ABI<br/>[state.rs]"]
  interface_error["ABI errors<br/>shared ABI<br/>[error.rs]"]
  interface_native_mint["ABI native mint<br/>shared ABI<br/>[native_mint.rs]"]
end

subgraph "Off-chain Clients"
  js_generated["JS generated<br/>sdk codegen"]
  js_helpers["JS helpers<br/>sdk helpers"]
  rust_client["Rust client<br/>consumer SDK<br/>[lib.rs]"]
end

subgraph "Pinocchio Stack"
  pin_interface["Pinocchio ABI<br/>shared ABI"]
  pin_entrypoint["Pin entrypoint<br/>on-chain boundary<br/>[entrypoint.rs]"]
  pin_processor["Pin processor<br/>dispatch core<br/>[mod.rs]"]
  pin_shared["Pin shared<br/>reusable logic<br/>[mod.rs]"]
  pin_fuzz["Fuzz corpus<br/>robustness harness"]
end

solana_runtime(("Solana runtime<br/>runtime boundary"))

solana_runtime -->|"delivers tx"| program_entrypoint
program_entrypoint -->|"decodes"| program_instruction
program_instruction -->|"dispatches"| program_processor
program_processor -->|"routes to"| program_ops
program_ops -->|"mutates"| program_state
program_ops -->|"reuses"| program_shared
program_ops -->|"special-cases"| program_native_mint
program_processor -->|"raises"| program_error
program_state -->|"mirrors"| interface_state
program_instruction -->|"aligns with"| interface_instruction
program_error -->|"aligns with"| interface_error
program_native_mint -->|"aligns with"| interface_native_mint
program_idl -->|"feeds codegen"| js_generated
interface_instruction -->|"feeds codegen"| js_generated
interface_state -->|"feeds codegen"| js_generated
interface_error -->|"feeds codegen"| js_generated
js_generated -->|"powers"| js_helpers
js_helpers -->|"builds tx"| solana_runtime
rust_client -->|"builds tx"| solana_runtime
pin_interface -->|"contracts"| pin_entrypoint
pin_entrypoint -->|"dispatches"| pin_processor
pin_processor -->|"reuses"| pin_shared
pin_processor -->|"mutates"| pin_interface
pin_fuzz -->|"validates"| pin_processor
pin_fuzz -->|"checks"| pin_interface

click program_entrypoint "https://github.com/solana-program/token/blob/main/program/src/entrypoint.rs"
click program_instruction "https://github.com/solana-program/token/blob/main/program/src/instruction.rs"
click program_processor "https://github.com/solana-program/token/blob/main/program/src/processor.rs"
click program_state "https://github.com/solana-program/token/blob/main/program/src/state.rs"
click program_error "https://github.com/solana-program/token/blob/main/program/src/error.rs"
click program_native_mint "https://github.com/solana-program/token/blob/main/program/src/native_mint.rs"
click program_idl "https://github.com/solana-program/token/blob/main/program/idl.json"
click interface_instruction "https://github.com/solana-program/token/blob/main/interface/src/instruction.rs"
click interface_state "https://github.com/solana-program/token/blob/main/interface/src/state.rs"
click interface_error "https://github.com/solana-program/token/blob/main/interface/src/error.rs"
click interface_native_mint "https://github.com/solana-program/token/blob/main/interface/src/native_mint.rs"
click js_generated "https://github.com/solana-program/token/tree/main/clients/js/src/generated"
click js_helpers "https://github.com/solana-program/token/tree/main/clients/js/src"
click rust_client "https://github.com/solana-program/token/blob/main/clients/rust/src/lib.rs"
click pin_interface "https://github.com/solana-program/token/tree/main/pinocchio/interface/src"
click pin_entrypoint "https://github.com/solana-program/token/blob/main/pinocchio/program/src/entrypoint.rs"
click pin_processor "https://github.com/solana-program/token/blob/main/pinocchio/program/src/processor/mod.rs"
click pin_shared "https://github.com/solana-program/token/blob/main/pinocchio/program/src/processor/shared/mod.rs"
click pin_fuzz "https://github.com/solana-program/token/tree/main/pinocchio/program/fuzz"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class program_entrypoint,program_instruction,program_processor,program_ops,program_shared,program_state,program_error,program_native_mint toneBlue
class program_idl,interface_instruction,interface_state,interface_error,interface_native_mint toneAmber
class js_generated,js_helpers,rust_client toneMint
class pin_interface,pin_entrypoint,pin_processor,pin_shared,pin_fuzz toneRose
class solana_runtime toneNeutral
```

## Components

### Canonical SPL Token

Main on-chain program stack

- [Entrypoint](https://github.com/solana-program/token/blob/HEAD/program/src/entrypoint.rs): on-chain boundary · Receives Solana instructions and hands off to the program processor · `program/src/entrypoint.rs`
- [Instructions](https://github.com/solana-program/token/blob/HEAD/program/src/instruction.rs): ABI decode · Token instruction enum and decoding logic · `program/src/instruction.rs`
- [Processor](https://github.com/solana-program/token/blob/HEAD/program/src/processor.rs): dispatch core · Top-level routing from instruction variants to handlers · `program/src/processor.rs`
- **Token ops**: handlers · Per-operation modules for mint, transfer, burn, authority, and account lifecycle
- **Shared flows**: reusable logic · Common logic shared across initialize and v2/v3 style instruction variants
- [Token state](https://github.com/solana-program/token/blob/HEAD/program/src/state.rs): account models · Mint, token account, multisig, and related state layouts · `program/src/state.rs`
- [Errors](https://github.com/solana-program/token/blob/HEAD/program/src/error.rs): error set · Program error definitions · `program/src/error.rs`
- [Native mint](https://github.com/solana-program/token/blob/HEAD/program/src/native_mint.rs): special-case logic · Wrapped SOL and native mint handling · `program/src/native_mint.rs`

### Shared Contract

ABI and IDL used across runtimes and clients

- [IDL](https://github.com/solana-program/token/blob/HEAD/program/idl.json): interface artifact · Published interface artifact for downstream consumers and generators · `program/idl.json`
- [ABI instructions](https://github.com/solana-program/token/blob/HEAD/interface/src/instruction.rs): shared ABI · Canonical instruction definitions for program and clients · `interface/src/instruction.rs`
- [ABI state](https://github.com/solana-program/token/blob/HEAD/interface/src/state.rs): shared ABI · Canonical token data layouts and types · `interface/src/state.rs`
- [ABI errors](https://github.com/solana-program/token/blob/HEAD/interface/src/error.rs): shared ABI · Shared error definitions aligned with the program · `interface/src/error.rs`
- [ABI native mint](https://github.com/solana-program/token/blob/HEAD/interface/src/native_mint.rs): shared ABI · Native mint constants and helpers shared by consumers · `interface/src/native_mint.rs`

### Off-chain Clients

Generated and hand-authored consumer SDKs

- [JS generated](https://github.com/solana-program/token/tree/HEAD/clients/js/src/generated): sdk codegen · Generated accounts, instructions, PDAs, programs, types, and errors · `clients/js/src/generated`
- [JS helpers](https://github.com/solana-program/token/tree/HEAD/clients/js/src): sdk helpers · Hand-authored convenience APIs for minting and token account flows · `clients/js/src`
- [Rust client](https://github.com/solana-program/token/blob/HEAD/clients/rust/src/lib.rs): consumer SDK · Off-chain Rust wrapper around the token interface · `clients/rust/src/lib.rs`

### Pinocchio Stack

Alternate implementation plus fuzzing and tests

- [Pinocchio ABI](https://github.com/solana-program/token/tree/HEAD/pinocchio/interface/src): shared ABI · Pinocchio-specific mirror of the token interface and state · `pinocchio/interface/src`
- [Pin entrypoint](https://github.com/solana-program/token/blob/HEAD/pinocchio/program/src/entrypoint.rs): on-chain boundary · Pinocchio program entry boundary · `pinocchio/program/src/entrypoint.rs`
- [Pin processor](https://github.com/solana-program/token/blob/HEAD/pinocchio/program/src/processor/mod.rs): dispatch core · Pinocchio dispatcher and per-instruction handlers · `pinocchio/program/src/processor/mod.rs`
- [Pin shared](https://github.com/solana-program/token/blob/HEAD/pinocchio/program/src/processor/shared/mod.rs): reusable logic · Shared flows reused across multiple Pinocchio instruction variants · `pinocchio/program/src/processor/shared/mod.rs`
- [Fuzz corpus](https://github.com/solana-program/token/tree/HEAD/pinocchio/program/fuzz): robustness harness · Fuzz inputs, expected outputs, and corpus material for adversarial validation · `pinocchio/program/fuzz`

### Other components

- **Solana runtime**: runtime boundary · Validator/runtime entry boundary for transactions and accounts

## Connections

- Solana runtime → Entrypoint: delivers tx · Solana passes instruction data and accounts into the on-chain program
- Entrypoint → Instructions: decodes · Entrypoint boundary forwards instruction bytes into decoding
- Instructions → Processor: dispatches · Instruction variants are routed into the top-level processor
- Processor → Token ops: routes to · Instruction-specific handlers implement token operations
- Token ops → Token state: mutates · Handlers read and update token account and mint state
- Token ops → Shared flows: reuses · Common logic is factored into shared instruction flows
- Token ops → Native mint: special-cases · Wrapped SOL behavior is handled as a dedicated flow
- Processor → Errors: raises · Dispatch and validation surface program errors
- Token state → ABI state: mirrors · On-chain layouts align with the shared contract definitions
- Instructions → ABI instructions: aligns with · Instruction discriminants and payloads are kept consistent
- Errors → ABI errors: aligns with · Program and shared error sets stay synchronized
- Native mint → ABI native mint: aligns with · Native mint behavior is shared across program and consumers
- IDL → JS generated: feeds codegen · IDL drives generated JS accounts, instructions, PDAs, and types
- ABI instructions → JS generated: feeds codegen · Shared ABI definitions back the generated JavaScript SDK
- ABI state → JS generated: feeds codegen · Shared account layouts are used to generate codecs and types
- ABI errors → JS generated: feeds codegen · Shared errors are emitted into the generated client layer
- JS generated → JS helpers: powers · Generated builders and codecs underpin convenience APIs
- JS helpers → Solana runtime: builds tx · Off-chain consumers assemble transactions for the validator/runtime
- Rust client → Solana runtime: builds tx · Rust consumers construct token transactions for Solana
- Pinocchio ABI → Pin entrypoint: contracts · Pinocchio program is built against its mirrored token ABI
- Pin entrypoint → Pin processor: dispatches · Pinocchio entrypoint routes into instruction handlers
- Pin processor → Pin shared: reuses · Shared helper flows reduce duplication across variants
- Pin processor → Pinocchio ABI: mutates · Pinocchio handlers operate on the mirrored token state
- Fuzz corpus → Pin processor: validates · Fuzz corpus exercises Pinocchio instruction semantics
- Fuzz corpus → Pinocchio ABI: checks · Fuzz cases validate ABI and state expectations
