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

Zero-copy: All state parsing uses direct byte access (no allocations)
Zero-allocation: Instruction data built on stack using MaybeUninit
Unified interface: Single API for SPL Token and Token-2022
Type-safe: Rust types prevent common errors
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

Feature	pinocchio-tkn	pinocchio-token-2022	anchor-spl	spl-token
SPL Token support	✅ Full	❌ No	✅ Full	✅ Full
Token-2022 core	✅ Full	✅ Full	✅ Full	✅ Full
Token-2022 extensions	✅ Broad (non-confidential)	❌ None	⚠️ Partial	✅ Full
State parsing	✅ Zero-copy	❌ No	✅ Yes	✅ Yes
Unified API	✅ Yes	❌ No	⚠️ Separate	❌ No
Calculation helpers	✅ Comprehensive	❌ No	❌ No	⚠️ Limited
Validation helpers	✅ Comprehensive	❌ No	❌ No	❌ No
Dependencies	✅ Minimal	⚠️ Some	⚠️ Many	⚠️ Many
Proc macros	❌ No	❌ No	✅ Heavy	❌ No
Build time	✅ Fast	✅ Fast	⚠️ Slower	⚠️ Slower
Binary size impact	✅ Small	✅ Small	⚠️ Larger	⚠️ Larger

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

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

pinocchio-tkn 0.2.2