# solana-program/token-wrap architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Solana on-chain program (Rust) packaged in a monorepo with two clients (Rust CLI and TypeScript JS).
- Purpose: permissionless bidirectional “wrap” and “unwrap” of SPL tokens and SPL Token-2022 tokens, using PDAs (Program Derived Addresses) for wrapped mints, backpointers, and escrow accounts.

##### File structure
- Top-level:
- program/ – the Solana on-chain Rust program
- clients/cli/ – Rust command-line interface
- clients/js/ – TypeScript client library and examples
- scripts/ – build/test/publish scripts for Rust and JS
- CI/CD workflows (.github/)
- program/src modules follow a classic instruction-processor pattern (entrypoint.rs → processor.rs → instruction.rs, state.rs, error.rs).
- clients/cli/src implements one file per instruction plus config, common utilities, and output formatting, with corresponding tests.
- clients/js/src contains generated IDL bindings (accounts, instructions, PDAs), plus hand-written wrappers (wrap.ts, unwrap.ts, create-mint.ts) and examples.

##### Main components and their relationships
A. On-chain Program
- Entrypoint
- Processor (dispatches CreateMint, Wrap, Unwrap)
- Instruction definitions (instruction.rs)
- Account state (state.rs) and error types (error.rs)
- PDAs:
– Wrapped Mint PDA (derives the mint address)
– Backpointer PDA (stores original mint address)
– Escrow PDA (holds unwrapped tokens)
- SPL Token program (external) – the on-chain program that actually mints, burns, and transfers tokens
B. Clients
1. Rust CLI
– Implements commands mapping to each instruction
– Reads config, handles wallets, pays rent, submits transactions
– Tests simulate end-to-end wrapping/unwrapping
2. JS Client Library
– TypeScript wrappers auto-generated from IDL plus helper functions
– Example scripts (multisig.ts, single-signer.ts)
– Publishes to npm, uses pnpm workspace
C. Tooling & CI/CD
– scripts/ for building, linting, formatting, testing both Rust and JS
– GitHub Actions workflows for test, lint, publish
– pnpm-workspace.yaml for monorepo package management

##### Architectural patterns and design principles
- PDA-based determinism: all wrapped mints, backpointers, and escrow accounts are derived by seeds.
- Permissionless, trust-minimized design: no centralized authority; any user may call CreateMint, Wrap, or Unwrap if they meet lamport/rent requirements.
- Modular instruction-processor pattern in Rust.
- Monorepo with language-specific client libraries generated from a single IDL (program/idl.json → clients/js/src/generated).
- Separation of concerns: core on-chain logic vs off-chain transaction orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        subgraph "Rust CLI" 
            direction TB
            CLI_Main["main.rs"]:::client
            CLI_CreateMint["create_mint.rs"]:::client
            CLI_Wrap["wrap.rs"]:::client
            CLI_Unwrap["unwrap.rs"]:::client
            CLI_CreateEscrow["create_escrow_account.rs"]:::client
            CLI_FindPDAs["find_pdas.rs"]:::client
            CLI_Config["config.rs"]:::client
            CLI_Common["common.rs"]:::client
            CLI_Output["output.rs"]:::client
            CLI_Tests["tests/"]:::client
        end
        subgraph "JS Client Library" 
            direction TB
            JS_Index["index.ts"]:::client
            JS_CreateMint["create-mint.ts"]:::client
            JS_Wrap["wrap.ts"]:::client
            JS_Unwrap["unwrap.ts"]:::client
            JS_Utilities["utilities.ts"]:::client
            subgraph "Examples"
                direction TB
                JS_Multisig["multisig.ts"]:::client
                JS_SingleSigner["single-signer.ts"]:::client
            end
            subgraph "Generated IDL Bindings"
                direction TB
                JS_Gen_Accounts["accounts/"]:::client
                JS_Gen_Instructions["instructions/"]:::client
                JS_Gen_PDAs["pdas/"]:::client
                JS_Gen_Programs["tokenWrap.ts"]:::client
                JS_Gen_Errors["errors/tokenWrap.ts"]:::client
                JS_Gen_Shared["shared/"]:::client
            end
        end
    end

    %% External RPC
    SolanaRPC["Solana JSON RPC API"]:::external

    %% On-chain Program
    subgraph "On-chain Program (Rust)" 
        direction TB
        Entrypoint["entrypoint.rs"]:::onchain
        Processor["processor.rs"]:::onchain
        InstructionDefs["instruction.rs"]:::onchain
        State["state.rs"]:::onchain
        ErrorTypes["error.rs"]:::onchain
        IDL["idl.json"]:::onchain
        subgraph "PDAs" 
            direction TB
            PDA_WrappedMint["Wrapped Mint PDA"]:::onchain
            PDA_Backpointer["Backpointer PDA"]:::onchain
            PDA_Escrow["Escrow PDA"]:::onchain
        end
    end

    %% External dependencies and data store
    SPLToken["SPL Token Program"]:::external
    SolanaLedger["Solana Ledger (Accounts)"]:::external

    %% Tooling & CI/CD
    subgraph "Tooling & CI/CD" 
        direction TB
        Scripts_Rust["scripts/rust/"]:::tooling
        Scripts_JS["scripts/js/"]:::tooling
        Scripts_CI["scripts/ci/"]:::tooling
        Workflows[".github/workflows/"]:::tooling
        CustomAction[".github/actions/setup/action.yml"]:::tooling
        PNPM["pnpm-workspace.yaml"]:::tooling
    end

    %% Data Flows
    CLI_Main -->|"sends tx"| SolanaRPC
    JS_Index -->|"sends tx"| SolanaRPC
    SolanaRPC -->|"invoke"| Entrypoint
    Entrypoint -->|"dispatch"| Processor
    Processor -->|"handles"| InstructionDefs
    Processor -->|"reads/writes"| State
    Processor -->|"on error"| ErrorTypes
    Processor -->|"uses PDA"| PDA_WrappedMint
    Processor -->|"uses PDA"| PDA_Backpointer
    Processor -->|"uses PDA"| PDA_Escrow
    Processor -->|"CPI call"| SPLToken
    Processor -->|"store data"| SolanaLedger
    IDL -->|"codegen"| JS_Gen_Accounts
    IDL -->|"codegen"| JS_Gen_Instructions
    IDL -->|"codegen"| JS_Gen_PDAs
    IDL -->|"codegen"| JS_Gen_Programs
    IDL -->|"codegen"| JS_Gen_Errors
    IDL -->|"codegen"| JS_Gen_Shared
    Scripts_Rust -->|"build/test/publish"| Workflows
    Scripts_JS -->|"build/test/publish"| Workflows
    Scripts_CI -->|"setup env"| Workflows
    Workflows -->|"publish Rust"| crates_io["crates.io"]:::external
    Workflows -->|"publish JS"| npm["npm registry"]:::external
    PNPM -->|"manage packages"| JS_Index

    %% Click Events
    click Entrypoint "https://github.com/solana-program/token-wrap/blob/main/program/src/entrypoint.rs"
    click Processor "https://github.com/solana-program/token-wrap/blob/main/program/src/processor.rs"
    click InstructionDefs "https://github.com/solana-program/token-wrap/blob/main/program/src/instruction.rs"
    click State "https://github.com/solana-program/token-wrap/blob/main/program/src/state.rs"
    click ErrorTypes "https://github.com/solana-program/token-wrap/blob/main/program/src/error.rs"
    click IDL "https://github.com/solana-program/token-wrap/blob/main/program/idl.json"
    click CLI_Main "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/main.rs"
    click CLI_CreateMint "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/create_mint.rs"
    click CLI_Wrap "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/wrap.rs"
    click CLI_Unwrap "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/unwrap.rs"
    click CLI_CreateEscrow "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/create_escrow_account.rs"
    click CLI_FindPDAs "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/find_pdas.rs"
    click CLI_Config "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/config.rs"
    click CLI_Common "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/common.rs"
    click CLI_Output "https://github.com/solana-program/token-wrap/blob/main/clients/cli/src/output.rs"
    click CLI_Tests "https://github.com/solana-program/token-wrap/tree/main/clients/cli/tests"
    click JS_CreateMint "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/create-mint.ts"
    click JS_Wrap "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/wrap.ts"
    click JS_Unwrap "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/unwrap.ts"
    click JS_Utilities "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/utilities.ts"
    click JS_Index "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/index.ts"
    click JS_Multisig "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/examples/multisig.ts"
    click JS_SingleSigner "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/examples/single-signer.ts"
    click JS_Gen_Accounts "https://github.com/solana-program/token-wrap/tree/main/clients/js/src/generated/accounts"
    click JS_Gen_Instructions "https://github.com/solana-program/token-wrap/tree/main/clients/js/src/generated/instructions"
    click JS_Gen_PDAs "https://github.com/solana-program/token-wrap/tree/main/clients/js/src/generated/pdas"
    click JS_Gen_Programs "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/generated/programs/tokenWrap.ts"
    click JS_Gen_Errors "https://github.com/solana-program/token-wrap/blob/main/clients/js/src/generated/errors/tokenWrap.ts"
    click JS_Gen_Shared "https://github.com/solana-program/token-wrap/tree/main/clients/js/src/generated/shared"
    click Scripts_Rust "https://github.com/solana-program/token-wrap/tree/main/scripts/rust"
    click Scripts_JS "https://github.com/solana-program/token-wrap/tree/main/scripts/js"
    click Scripts_CI "https://github.com/solana-program/token-wrap/tree/main/scripts/ci"
    click Workflows "https://github.com/solana-program/token-wrap/tree/main/.github/workflows"
    click CustomAction "https://github.com/solana-program/token-wrap/blob/main/.github/actions/setup/action.yml"
    click PNPM "https://github.com/solana-program/token-wrap/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef onchain fill:#D0E6FF,stroke:#004080,stroke-width:1px
    classDef client fill:#E6FFE6,stroke:#006600,stroke-width:1px
    classDef tooling fill:#FFF5CC,stroke:#806600,stroke-width:1px
    classDef external fill:#F2F2F2,stroke:#666666,stroke-width:1px
```
