pinocchio-tkn

The Complete Token Toolkit for Pinocchio Programs

Zero-dependency, zero-allocation CPI helpers for SPL Token and Token-2022. Built for Pinocchio, the fastest Solana framework.

Why pinocchio-tkn?

While official packages exist (pinocchio-token, pinocchio-token-2022), they are fragmented and incomplete:

• pinocchio-token: Legacy SPL Token only
• pinocchio-token-2022: Core instructions only, no extensions
• No unified interface

pinocchio-tkn provides:

• Complete coverage across core instructions and extensions
• Broad Token-2022 extension coverage (non-confidential; confidential extensions are documented only)
• Unified API: Single interface for both SPL Token and Token-2022
• State parsing: Zero-copy Mint and TokenAccount readers
• Calculation helpers: Fees, interest, space, rent, UI amounts
• Validation helpers: Security checks and assertions
• Battle-tested: Comprehensive tests covering edge cases
• Production-ready: Used in real protocols

Quick Start

Installation

[dependencies]
pinocchio = "0.9"
pinocchio-tkn = "0.2"  # Includes: common, state, helpers (default)

Optional Features

Choose only what you need to minimize binary size:

# Minimal: Only transfers and basic instructions
pinocchio-tkn = { version = "0.2", default-features = false, features = ["common"] }

# Common + State parsing
pinocchio-tkn = { version = "0.2", default-features = false, features = ["common", "state"] }

# With specific Token-2022 extensions
pinocchio-tkn = { version = "0.2", features = ["ext-transfer-fee", "ext-metadata"] }

# Everything (all extensions)
pinocchio-tkn = { version = "0.2", features = ["full"] }

Available features:

• common - Common instructions (SPL Token + Token-2022 core)
• state - State parsing (Mint, TokenAccount)
• helpers - Calculation, validation, detection helpers
• ext-transfer-fee - Transfer fee instructions
• ext-metadata - On-chain metadata instructions
• ext-interest - Interest bearing mint
• ext-pointers - Metadata/Group/Member pointers
• ext-misc - CpiGuard, MemoTransfer, Pause, Reallocate, etc
• extensions - All non-confidential Token-2022 extensions
• full - Everything

Default: ["common", "state", "helpers"]

Basic Usage

use pinocchio_tkn::prelude::*;

// Transfer tokens (works with both SPL Token and Token-2022)
Transfer {
    source,
    destination,
    authority,
    amount: 1_000_000,
    program_id: None,  // Auto-detect from account owner
}.invoke()?;

// Initialize Token-2022 with transfer fees
InitializeTransferFeeConfig {
    mint,
    transfer_fee_config_authority: Some(authority.key()),
    withdraw_withheld_authority: Some(withdraw_authority.key()),
    transfer_fee_basis_points: 100,  // 1%
    maximum_fee: 5000,
}.invoke()?;

// Parse mint data (zero-copy)
let mint = Mint::from_account_info(&mint_account)?;
let decimals = mint.decimals();
let supply = mint.supply();

// Calculate transfer fee
let fee = calculate_transfer_fee(1_000_000, 100, 5_000);  // 1% fee capped at 5000

// Validate accounts (security checks)
assert_is_mint(&mint_account)?;
assert_is_token_account(&token_account, Some(&mint.key()), Some(&owner.key()))?;
assert_account_not_frozen(&token_account)?;

Features

Complete Instruction Coverage

Common Instructions (20) - Work with both SPL Token and Token-2022:

• Transfer, TransferChecked
• MintTo, MintToChecked, Burn, BurnChecked
• InitializeAccount, InitializeAccount2, InitializeAccount3
• InitializeMint, InitializeMint2
• Approve, ApproveChecked, Revoke
• SetAuthority, CloseAccount
• FreezeAccount, ThawAccount
• SyncNative, InitializeMultisig

Token-2022 Extensions (37) - Advanced features:

• Transfer Fees: InitializeTransferFeeConfig, TransferCheckedWithFee, etc.
• Metadata: InitializeTokenMetadata, UpdateField, RemoveKey, Emit
• Interest: InitializeInterestBearingMint, UpdateInterestRate
• Transfer Hooks: InitializeTransferHook, SetTransferHook
• State Management: DefaultAccountState, NonTransferable, Pause/Resume
• Authorities: MintCloseAuthority, PermanentDelegate
• Pointers: MetadataPointer, GroupPointer, GroupMemberPointer
• Security: CpiGuard, MemoTransfer
• Advanced: ScaledUiAmount, ImmutableOwner

Zero-Copy State Parsing

use pinocchio_tkn::state::{Mint, TokenAccount};

// Parse mint (works with Token-2022 extensions)
let mint = Mint::from_account_info(&mint_account)?;
assert_eq!(mint.decimals(), 6);
assert_eq!(mint.supply(), 1_000_000_000);

// Parse token account
let account = TokenAccount::from_account_info(&token_account)?;
assert_eq!(account.amount(), 500_000);
assert!(!account.is_frozen());
assert_eq!(account.mint(), &mint_pubkey);

No allocations, no copying - just direct byte access.

Calculation Helpers

use pinocchio_tkn::helpers::*;

// UI amount conversions
let raw = ui_amount_to_amount(1.5, 6);  // 1.5 USDC -> 1_500_000
let ui = amount_to_ui_amount(1_500_000, 6);  // -> 1.5

// Transfer fee calculation
let fee = calculate_transfer_fee(1_000_000, 100, 5_000);  // 1% capped

// Inverse fee (amount needed to receive X after fees)
let (amount, fee) = calculate_inverse_transfer_fee(100_000, 100, 5_000);

// Interest calculation
let interest = calculate_accrued_interest(
    1_000_000,  // balance
    500,        // 5% APY (basis points)
    365 * 24 * 3600,  // 1 year
);

// Space calculation for rent
let space = mint_space_for_extensions(&[
    ExtensionType::TransferFeeConfig,
    ExtensionType::MetadataPointer,
]);
let rent = rent_exempt_minimum(space, 3480);

Validation Helpers

use pinocchio_tkn::helpers::*;

// Security checks
assert_owned_by(&account, &TOKEN_2022_PROGRAM_ID)?;
assert_is_mint(&mint_account)?;
assert_is_token_account(&token_account, Some(&mint.key()), Some(&owner.key()))?;

// State validation
assert_account_not_frozen(&token_account)?;
assert_mint_authority(&mint, &authority)?;
assert_freeze_authority(&mint, &authority)?;

// Auto-detection
let program_id = get_token_program_id(&account);
if is_token_2022(&account) {
    // Use Token-2022 features
}

Architecture

Design Principles

1. Zero-copy: All state parsing uses direct byte access (no allocations)
2. Zero-allocation: Instruction data built on stack using MaybeUninit
3. Unified interface: Single API for SPL Token and Token-2022
4. Type-safe: Rust types prevent common errors
5. Inline everything: All helpers are #[inline] for optimal performance

Module Structure

pinocchio-tkn/
├── common/         # Common instructions (SPL + Token-2022)
├── extensions/     # Token-2022 exclusive features
├── state/          # Zero-copy Mint and TokenAccount parsing
└── helpers/        # Calculations, validation, detection

See docs/architecture/overview.md for detailed design decisions.

Comparison

TL;DR: pinocchio-tkn is the only complete solution for Pinocchio programs.

NOTE : ok, let me be honest ... ZK extensions aren't implemented (yet) but will eventually ... 22/22 looks waaaaay better that something incomplete also, i need some time to understand how ZK works, now looks like magic to me tbh

Examples

Transfer with Auto-Detection

use pinocchio_tkn::common::Transfer;

// Works with both SPL Token and Token-2022
Transfer {
    source: &source_account,
    destination: &destination_account,
    authority: &authority_account,
    amount: 1_000_000,
    program_id: None,  // Detects from source.owner()
}.invoke()?;

Token-2022 with Transfer Fees

use pinocchio_tkn::extensions::*;

// Initialize mint with transfer fees
InitializeTransferFeeConfig {
    mint: &mint_account,
    transfer_fee_config_authority: Some(&authority.key()),
    withdraw_withheld_authority: Some(&withdraw_authority.key()),
    transfer_fee_basis_points: 100,  // 1%
    maximum_fee: 5_000,
}.invoke()?;

// Transfer with fees
TransferCheckedWithFee {
    source: &source_account,
    mint: &mint_account,
    destination: &destination_account,
    authority: &authority_account,
    amount: 1_000_000,
    decimals: 6,
}.invoke()?;

On-Chain Metadata

use pinocchio_tkn::extensions::*;

InitializeTokenMetadata {
    mint: &mint_account,
    update_authority: &authority_account,
    mint_authority: &mint_authority_account,
    name: "My Token",
    symbol: "MTK",
    uri: "https://example.com/metadata.json",
}.invoke()?;

More examples in examples/ directory.

Testing

Comprehensive tests covering:

• All instructions (happy path + error cases)
• State parsing (edge cases, invalid data)
• Calculation helpers (overflow, rounding, edge values)
• Validation helpers (security checks)
• Integration workflows

cargo test

Coverage status is tracked in docs/architecture/overview.md.

Performance

• Zero allocations in core paths
• O(1) state parsing and instruction building
• Benchmarks: See benches/instruction_building.rs

Status

Version: 0.2.1 Stability: Production-ready Audit Status: Not audited (use at own risk)

Coverage:

• SPL Token core instructions
• Token-2022 core instructions
• Token-2022 extensions (non-confidential)
• Confidential extensions are documented but not implemented

Canonical coverage status: docs/architecture/overview.md

Contributing

Contributions welcome! Open an issue or PR on GitHub.

Areas for contribution:

• Additional examples
• Benchmarks
• Documentation improvements
• Edge case tests

License

MIT OR Apache-2.0

Resources

• SPL Token-2022 Official Docs
• Pinocchio Framework
• Architecture Details
• Roadmap

Disclaimer

NOT AUDITED. USE AT YOUR OWN RISK.

This is an unofficial toolkit. Review the code and test thoroughly before using it in production. We built it because we got tired of writing instruction bytes by hand and wanted a clean, unified API.

Built by 888 Team

Questions? Open an issue on GitHub