How solana-program/token-wrap works
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.