Crate jiminy

Expand description

Jiminy — Anchor-style safety abstractions for pinocchio programs.

Pinocchio is the engine. Jiminy keeps it honest.

Zero-copy, no_std, no_alloc, BPF-safe. Account checks, token + mint readers, Token-2022 extension screening, CPI reentrancy guards, DeFi math with u128 intermediates, slippage protection, time/deadline checks, state machine validation, zero-copy cursors, and more. All #[inline(always)].

§Quick-start

use jiminy::prelude::*;

One import gives you everything: account checks, token/mint readers, Token-2022 screening, CPI guards, DeFi math, slippage, time checks, state machines, cursors, macros, AccountList, and the pinocchio core types.

§Account validation

Function	What it verifies
`check_signer`	account is a transaction signer
`check_writable`	account is marked writable
`check_owner`	account is owned by your program
`check_pda`	account address equals a derived PDA
`check_system_program`	account is the system program
`check_executable`	account is an executable program
`check_uninitialized`	account has no data yet (anti-reinit)
`check_has_one`	stored address field matches account key
`check_keys_eq`	two addresses are equal
`check_lamports_gte`	account holds at least N lamports
`check_rent_exempt`	account holds enough lamports for rent exemption
`check_closed`	account has zero lamports and empty data
`check_size`	raw data slice is at least N bytes
`check_discriminator`	first byte matches expected type tag
`check_account`	owner + size + discriminator in one call
`check_accounts_unique_2`	two accounts have different addresses
`check_accounts_unique_3`	three accounts all different (src ≠ dest ≠ fee)
`check_instruction_data_len`	exact instruction data length
`check_instruction_data_min`	minimum instruction data length
`check_version`	header version byte ≥ minimum
`rent_exempt_min`	compute minimum lamports for rent exemption

§Assert functions

Function	What it does
`assert_pda`	derive PDA, verify match, return bump
`assert_pda_with_bump`	verify PDA with known bump (cheaper)
`assert_pda_external`	same as `assert_pda` for external programs
`assert_token_program`	account is SPL Token or Token-2022
`assert_address`	account address matches expected key
`assert_program`	address matches + account is executable
`assert_not_initialized`	lamports == 0 (account doesn’t exist yet)

§Token account readers + checks

Zero-copy reads from the 165-byte SPL Token layout.

Function	What it reads / checks
`token_account_owner`	owner address (bytes 32..64)
`token_account_amount`	token balance as u64 (bytes 64..72)
`token_account_mint`	mint address (bytes 0..32)
`token_account_delegate`	optional delegate address
`token_account_state`	state byte (0=uninit, 1=init, 2=frozen)
`token_account_close_authority`	optional close authority
`token_account_delegated_amount`	delegated amount (u64)
`check_token_account_mint`	mint matches expected
`check_token_account_owner`	owner matches expected
`check_token_account_initialized`	state == 1
`check_no_delegate`	no active delegate
`check_no_close_authority`	no close authority set
`check_token_balance_gte`	token balance ≥ minimum
`check_token_program_match`	account owned by the right token program

§Mint account readers + checks

Zero-copy reads from the 82-byte SPL Mint layout.

Function	What it reads / checks
`mint_authority`	optional mint authority address
`mint_supply`	total supply (u64)
`mint_decimals`	decimals (u8)
`mint_is_initialized`	is initialized (bool)
`mint_freeze_authority`	optional freeze authority
`check_mint_owner`	mint owned by expected token program
`check_mint_authority`	mint authority matches expected

§Token-2022 extension screening

Programs accepting Token-2022 tokens must screen for dangerous extensions. See the token_2022 module for full TLV extension reading and one-line safety guards like token_2022::check_safe_token_2022_mint.

§CPI reentrancy protection

See the cpi_guard module. Reads the Sysvar Instructions account to detect CPI callers: cpi_guard::check_no_cpi_caller, cpi_guard::check_cpi_caller.

§DeFi math

Function	What it does
`checked_add`	overflow-safe u64 addition
`checked_sub`	underflow-safe u64 subtraction
`checked_mul`	overflow-safe u64 multiplication
`checked_div`	division with zero check
`checked_div_ceil`	ceiling division
`checked_mul_div`	`(a * b) / c` with u128 intermediate
`checked_mul_div_ceil`	same, ceiling
`bps_of`	basis point fee: `amount * bps / 10_000`
`bps_of_ceil`	same, ceiling
`checked_pow`	exponentiation via repeated squaring
`to_u64`	safe u128 → u64 narrowing

§Slippage + economic bounds

See the slippage module: slippage::check_slippage, slippage::check_min_amount, slippage::check_nonzero, slippage::check_within_bps, slippage::check_price_bounds, and more.

§Time + deadline checks

Function	What it does
`check_not_expired`	current time ≤ deadline
`check_expired`	current time > deadline
`check_within_window`	time is within [start, end]
`check_cooldown`	rate limiting (oracle updates, admin changes)
`check_deadline`	read Clock sysvar + check not expired
`check_after`	read Clock sysvar + check expired

§Sysvar readers

Function	What it does
`read_clock`	read (slot, timestamp) from Clock sysvar
`read_clock_epoch`	read epoch from Clock sysvar
[`read_rent`]	read (lamports_per_byte_year, exemption_threshold) from Rent

§State machine validation

See the state module: state::check_state, state::check_state_transition, state::write_state, state::check_state_not, state::check_state_in.

§PDA utilities

Macro / Function	What it does
`find_pda!`	find canonical PDA + bump via syscall
`derive_pda!`	derive PDA with known bump (cheap, ~100 CU)
`derive_pda_const!`	derive PDA at compile time
`derive_ata`	derive ATA address for wallet + mint
`derive_ata_with_program`	derive ATA with explicit token program
`derive_ata_with_bump`	derive ATA with known bump (cheap)
`derive_ata_const!`	derive ATA at compile time

§Zero-copy cursors

SliceCursor reads typed fields sequentially from account data. DataWriter writes them when initializing a new account. zero_init zero-fills account data before the first write.

§Account iteration

AccountList provides iterator-style account consumption with inline constraint checks, replacing manual index arithmetic.

§Well-known program IDs

programs module: SYSTEM, TOKEN, TOKEN_2022, ASSOCIATED_TOKEN, METADATA, BPF_LOADER, COMPUTE_BUDGET, SYSVAR_CLOCK, SYSVAR_RENT, SYSVAR_INSTRUCTIONS.

Re-exports§

pub use pinocchio;
pub use pinocchio_system;
pub use pinocchio_token;

Modules§

cpi: Safe CPI wrappers that bundle validation + invocation.
cpi_guard: CPI reentrancy protection via Sysvar Instructions introspection.
prelude: Convenience re-exports for the common Jiminy usage pattern.
programs
realloc: Safe account reallocation with rent top-up.
slippage: Slippage, price bounds, and economic constraint checks.
state: State machine transition checks.
token_2022: Token-2022 extension reader and safety checks.

Macros§

derive_ata_const: Derive an ATA address at compile time. Requires known bump.
derive_pda: Derive a PDA with a known bump. Cheap (~100 CU, no curve check).
derive_pda_const: Derive a PDA at compile time. Requires const seeds and bump.
find_pda: Find a PDA and return (Address, u8) with the canonical bump.
require: Require a boolean condition: return $err (converted via Into) if false.
require_accounts_ne: Require two accounts to have different addresses.
require_eq: Require a == b for scalar types.
require_flag: Require bit n to be set in $byte, else return $err.
require_gt: Require a > b.
require_gte: Require a >= b.
require_keys_eq: Require two Address values to be equal.
require_keys_neq: Require two Address values to be different.
require_lt: Require a < b.
require_lte: Require a <= b.
require_neq: Require a != b for scalar types.

Structs§

AccountList: Iterator-style account accessor with inline constraint checks.
AccountView: Wrapper struct for a RuntimeAccount.
Address: The address of a Solana account.
DataWriter: Zero-copy write cursor over a mutable byte slice.
SliceCursor: Zero-copy read cursor over a byte slice.

Enums§

ProgramError: Reasons the program may fail

Constants§

HEADER_LEN: Size of the Jiminy standard account header, in bytes.
MINT_LEN: Minimum size of an SPL Token mint account.
TOKEN_ACCOUNT_LEN: Minimum size of an SPL Token account.

Functions§

assert_address: Verify an account’s address matches an expected address exactly.
assert_not_initialized: Verify an account has never been initialized by checking that its lamports are zero.
assert_pda: Derive a PDA from the given seeds and program id, verify it matches the account’s address, and return the bump.
assert_pda_external: Verify a PDA derived from an external program’s seeds. Returns the bump.
assert_pda_with_bump: Verify a PDA matches when the bump is already known. Way cheaper than assert_pda because it only does one derivation instead of searching all 256 bumps.
assert_program: Verify an account’s address matches a known program id.
assert_token_program: Verify the account is the SPL Token program.
bps_of: Compute basis-point fee: amount * bps / 10_000 (floor).
bps_of_ceil: Compute basis-point fee with ceiling: ceil(amount * bps / 10_000).
check_account: Combined check: ownership + minimum size + discriminator.
check_accounts_unique_2: Verify two accounts have different addresses.
check_accounts_unique_3: Verify three accounts all have different addresses.
check_after: Combined: read clock timestamp and verify expired.
check_any_flag: Return true if ANY bit in mask is set in byte.
check_ata: Verify a token account is the correct ATA for a wallet + mint pair.
check_ata_with_program: Verify a token account is the correct ATA for a specific token program.
check_clock_sysvar: Verify the account is the Clock sysvar.
check_closed: Verify an account is fully closed: zero lamports and empty data.
check_cooldown: Verify enough time has passed since the last action (cooldown/rate-limit).
check_deadline: Combined: read clock timestamp and verify not expired.
check_discriminator: Verify the first byte of account data matches the expected discriminator.
check_executable: Verify the account is an executable program.
check_expired: Verify the current time HAS passed a deadline.
check_flags: Return true if ALL bits in mask are set in byte.
check_has_one: Verify that a stored address field matches an account’s actual address.
check_header: Validate the discriminator and minimum version of an account header.
check_instruction_data_len: Verify instruction data is exactly the expected length.
check_instruction_data_min: Verify instruction data has at least N bytes.
check_keys_eq: Verify two addresses are equal.
check_lamports_gte: Verify account holds at least min_lamports.
check_mint_authority: Verify the mint authority matches an expected address.
check_mint_owner: Verify a mint account is owned by the expected token program.
check_no_close_authority: Reject token accounts that have a close authority set.
check_no_delegate: Reject token accounts that have an active delegate.
check_not_expired: Verify the current time has NOT passed a deadline.
check_not_frozen: Reject frozen token accounts.
check_owner: Verify the account is owned by program_id.
check_pda: Verify the account’s address equals the expected PDA.
check_rent_exempt: Verify an account holds enough lamports to be rent-exempt for its data size.
check_rent_sysvar: Verify the account is the Rent sysvar.
check_signer: Verify the account signed the transaction.
check_size: Verify account data is at least min_len bytes.
check_system_program: Verify the account is the canonical system program.
check_token_account_frozen: Verify a token account is frozen (state byte == 2).
check_token_account_initialized: Verify a token account is in the Initialized state (state byte == 1).
check_token_account_mint: Verify a token account’s mint matches the expected mint address.
check_token_account_owner: Verify a token account’s owner matches the expected authority.
check_token_balance_gte: Verify a token account holds at least min_amount tokens.
check_token_program_match: Verify that a token account’s owning program matches the passed token program.
check_uninitialized: Verify the account has no data (uninitialized). Prevents reinitialization attacks.
check_version: Verify the header version byte (data[1]) meets a minimum version.
check_within_window: Verify the current time is within an inclusive window [start, end].
check_writable: Verify the account is marked writable in the transaction.
checked_add: Checked u64 addition: returns ArithmeticOverflow on overflow.
checked_div: Checked u64 division: returns ArithmeticOverflow on divide-by-zero.
checked_div_ceil: Checked ceiling division: ceil(a / b). Returns ArithmeticOverflow on zero.
checked_mul: Checked u64 multiplication: returns ArithmeticOverflow on overflow.
checked_mul_div: Compute (a * b) / c with u128 intermediate to prevent overflow.
checked_mul_div_ceil: Compute ceil((a * b) / c) with u128 intermediate.
checked_pow: Checked exponentiation via repeated squaring.
checked_sub: Checked u64 subtraction: returns ArithmeticOverflow on underflow.
clear_bit: Clear bit n in a byte, returning the modified value.
derive_address: Derive a program address from the given seeds, optional bump, and program id.
derive_address_const: Compile-time version of derive_address.
derive_ata: Derive the associated token account (ATA) address for a wallet + mint pair.
derive_ata_with_bump: Derive an ATA address with a known bump. Skips the bump search.
derive_ata_with_program: Derive an ATA address with an explicit token program (SPL Token or Token-2022).
header_payload: Return the payload slice that follows the 8-byte header.
header_payload_mut: Return the mutable payload slice that follows the 8-byte header.
mint_authority: Read the mint authority field (bytes 0..36).
mint_decimals: Read the decimals field (byte 44).
mint_freeze_authority: Read the freeze authority field (bytes 46..82).
mint_is_initialized: Check if the mint is initialized (byte 45).
mint_supply: Read the total supply field (bytes 36..44).
read_bit: Read bit n from a byte. Returns true if the bit is set.
read_clock: Read both slot and unix_timestamp from the Clock sysvar account.
read_clock_epoch: Read the epoch from the Clock sysvar.
read_clock_slot: Read just the slot from the Clock sysvar.
read_clock_timestamp: Read just the unix_timestamp from the Clock sysvar.
read_data_len: Read the data_len field (bytes 4-7) from an account header.
read_flags_at: Read the flags byte from a data slice at offset, returning the value. Bounds-checked: AccountDataTooSmall if offset is out of range.
read_header_flags: Read the flags byte from an account header.
read_rent_lamports_per_byte_year: Read the lamports_per_byte_year from the Rent sysvar.
read_version: Read the version byte from an account header.
rent_exempt_min: Approximate minimum lamports for rent exemption at the current mainnet rate.
safe_close: Close account, sending all its lamports to destination.
set_bit: Set bit n in a byte, returning the modified value.
to_u64: Safe narrowing cast from u128 to u64.
toggle_bit: Toggle bit n in a byte, returning the modified value.
token_account_amount: Read the amount field from a token account (bytes 64..72).
token_account_close_authority: Read the close authority field from a token account (bytes 129..165).
token_account_delegate: Read the delegate field from a token account (bytes 76..108).
token_account_delegated_amount: Read the delegated amount from a token account (bytes 121..129).
token_account_mint: Read the mint field from a token account (bytes 0..32).
token_account_owner: Read the owner field from a token account (bytes 32..64).
token_account_state: Read the state byte from a token account (byte 108).
write_discriminator: Write a discriminator byte to data[0].
write_flags_at: Write value to the flags byte at offset in a mutable data slice. Bounds-checked: AccountDataTooSmall if offset is out of range.
write_header: Write the standard 8-byte Jiminy account header.
write_header_with_len: Write the full 8-byte header including an explicit data_len value.
zero_init: Zero-fill data before writing any fields.

Type Aliases§

ProgramResult

Crate jiminy

Crate jiminy Copy item path

§Quick-start

§Account validation

§Assert functions

§Token account readers + checks

§Mint account readers + checks

§Token-2022 extension screening

§CPI reentrancy protection

§DeFi math

§Slippage + economic bounds

§Time + deadline checks

§Sysvar readers

§State machine validation

§PDA utilities

§Zero-copy cursors

§Account iteration

§Well-known program IDs

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate jiminy