anchor-audit 0.1.0

package/rules/018-cpi-confused-deputy.md

@@ -0,0 +1,50 @@
+# Rule 018: CPI Confused Deputy
+
+**Severity:** High
+**Category:** CPI
+
+## Description
+A program holds privileged authority (a PDA that owns a vault, mints a token, or controls an admin function) and exposes an instruction that performs a privileged CPI on a caller's behalf without checking that the caller is authorized for *that specific* resource. The program is the "deputy": it has authority, and the attacker confuses it into using that authority for the attacker's benefit.
+
+## Vulnerable pattern
+```rust
+// Program PDA is the mint authority. This instruction mints to any
+// destination the caller names, with no check on who may mint or how much.
+pub fn mint_reward(ctx: Context<MintReward>, amount: u64) -> Result<()> {
+    let seeds = &[b"mint_auth", &[ctx.accounts.config.bump]];
+    token::mint_to(
+        CpiContext::new_with_signer(/* ... */, &[&seeds[..]]),
+        amount, // attacker-chosen, to an attacker-owned token account
+    )?;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The PDA signs the CPI, so from the token program's perspective the mint is fully authorized. The attacker calls `mint_reward` directly, names their own token account as the destination and an arbitrary amount, and the deputy mints unlimited tokens. The missing piece is authorization on the *caller* and bounds on the action.
+
+## Fix pattern
+```rust
+pub fn mint_reward(ctx: Context<MintReward>, amount: u64) -> Result<()> {
+    // Verify the caller is entitled to this reward and the amount is bounded
+    require_keys_eq!(ctx.accounts.config.distributor, ctx.accounts.distributor.key());
+    require!(amount <= ctx.accounts.reward.claimable, ErrorCode::ExceedsClaimable);
+    ctx.accounts.reward.claimable -= amount;
+    // ...then perform the signed mint CPI
+    Ok(())
+}
+```
+Require a `Signer` for the privileged role and bind the destination to validated state.
+
+## Detection heuristic
+- `invoke_signed` with a program-held PDA where the instruction lacks an authorization check on the caller
+- Privileged CPIs (mint, transfer-from-vault, set-authority) whose amount/destination come straight from instruction args
+- Instructions that expose the program's signing authority without `has_one`/`address`/signer gating tied to the affected resource
+
+## References
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Sec3 — Solana security best practices (https://www.sec3.dev/blog)
+
+## Real-world exploits (if any)
+The confused-deputy pattern underlies several DeFi drains where a vault/mint authority PDA was invocable without adequate caller authorization; it recurs as a critical finding in public audits.

package/rules/019-missing-program-id-check-spl.md

@@ -0,0 +1,51 @@
+# Rule 019: Missing Program ID Check on SPL CPIs
+
+**Severity:** High
+**Category:** CPI
+
+## Description
+A specialization of arbitrary CPI (Rule 017) for SPL Token / Token-2022 / Associated Token Program calls. Code constructs a token CPI but passes the token program as an unvalidated `AccountInfo`, or fails to distinguish SPL Token from Token-2022. The attacker substitutes a counterfeit token program that satisfies the call signature without moving real tokens.
+
+## Vulnerable pattern
+```rust
+pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
+    let cpi_accounts = Transfer {
+        from: ctx.accounts.user_token.to_account_info(),
+        to: ctx.accounts.vault_token.to_account_info(),
+        authority: ctx.accounts.user.to_account_info(),
+    };
+    // token_program is AccountInfo, never checked against spl_token::ID
+    let cpi = CpiContext::new(ctx.accounts.token_program.to_account_info(), cpi_accounts);
+    token::transfer(cpi, amount)?;
+    // program credits the user as if `amount` arrived
+    Ok(())
+}
+```
+
+## Why this is dangerous
+With a fake token program, the "transfer" succeeds (the fake program returns Ok and does nothing), but the program's own bookkeeping credits the user a deposit. The attacker mints protocol credit for free, then withdraws real tokens through a legitimate path. Token-2022 confusion is a related risk: assuming SPL Token semantics for a Token-2022 mint with transfer hooks/fees.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Deposit<'info> {
+    pub token_program: Program<'info, Token>, // pins spl_token::ID
+    // ...
+}
+// For Token-2022 support, use anchor_spl::token_interface and the
+// TokenInterface program type, and validate the mint's program owner.
+```
+
+## Detection heuristic
+- Token CPIs (`token::transfer`, `mint_to`, `burn`, `set_authority`) built from a `token_program: AccountInfo` instead of `Program<'info, Token>` / `Interface`
+- Token-account types as `AccountInfo` rather than `Account<'info, TokenAccount>` / `InterfaceAccount`
+- No `require_keys_eq!(token_program.key(), spl_token::ID)` when raw `AccountInfo` is used
+- Code that assumes received amount equals requested amount (ignores Token-2022 transfer fees)
+
+## References
+- Coral sealevel-attacks — 5-arbitrary-cpi (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/5-arbitrary-cpi)
+- anchor_spl docs — Token / TokenInterface (https://docs.rs/anchor-spl/latest/anchor_spl/)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+
+## Real-world exploits (if any)
+No single attributed public exploit; spoofed-token-program findings are common in public audits of staking and vault programs.

package/rules/020-reentrancy-via-cpi.md

@@ -0,0 +1,50 @@
+# Rule 020: Reentrancy via CPI
+
+**Severity:** High
+**Category:** CPI
+
+## Description
+Solana's runtime forbids a program from being re-entered while already on the call stack *except* through self-recursion, which mitigates classic EVM-style reentrancy. But a check-then-CPI-then-effect ordering is still dangerous: if a program reads state, performs a CPI into another program, and that program (or a later instruction in the same transaction) can alter the first program's accounts before the effect is written, invariants break. The safe discipline is checks-effects-interactions: update your own state *before* the external call.
+
+## Vulnerable pattern
+```rust
+pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
+    require!(ctx.accounts.position.balance >= amount, ErrorCode::Insufficient);
+    // Interaction BEFORE effect: transfer out first...
+    token::transfer(/* vault -> user */, amount)?;
+    // ...then decrement. If the CPI path can re-enter a sibling instruction
+    // that also reads `balance`, the stale balance is double-spent.
+    ctx.accounts.position.balance -= amount;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+A callback program, a Token-2022 transfer hook, or a crafted multi-instruction transaction can observe the un-decremented balance and act on it (withdraw again, use it as collateral) before the effect lands. Even without true reentrancy, doing effects after interactions widens the window for cross-instruction inconsistencies and partial-failure states.
+
+## Fix pattern
+```rust
+pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
+    require!(ctx.accounts.position.balance >= amount, ErrorCode::Insufficient);
+    // Effect first
+    ctx.accounts.position.balance = ctx.accounts.position.balance
+        .checked_sub(amount).ok_or(ErrorCode::Underflow)?;
+    // Interaction last
+    token::transfer(/* vault -> user */, amount)?;
+    Ok(())
+}
+```
+Be especially careful with Token-2022 transfer hooks, which run untrusted code during the transfer.
+
+## Detection heuristic
+- State mutations placed *after* CPIs that depend on the pre-CPI state (withdraw/transfer before decrement)
+- CPIs into programs that can call back (transfer hooks, callback registries) mid-update
+- Missing per-account "in progress"/lock flags around multi-step flows that span CPIs
+
+## References
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Sec3 — checks-effects-interactions on Solana (https://www.sec3.dev/blog)
+- Solana docs — CPI and call depth (https://solana.com/docs/core/cpi)
+
+## Real-world exploits (if any)
+No single attributed public Solana exploit (the runtime blocks the classic form); included because Token-2022 transfer hooks reintroduce callback-driven reentrancy surface.

package/rules/021-untrusted-callback.md

@@ -0,0 +1,49 @@
+# Rule 021: Untrusted Callback Execution
+
+**Severity:** High
+**Category:** CPI
+
+## Description
+A program invokes a caller-supplied program as a "callback" or "hook" — flash-loan receivers, transfer hooks, router callbacks — without constraining which program may be called or validating the state it leaves behind. The callback runs arbitrary attacker code, often while the calling program is mid-operation and holding elevated authority or unsettled balances.
+
+## Vulnerable pattern
+```rust
+pub fn flash_loan(ctx: Context<FlashLoan>, amount: u64) -> Result<()> {
+    let pre = ctx.accounts.vault.amount;
+    token::transfer(/* vault -> borrower */, amount)?;
+    // Calls an arbitrary borrower-supplied program with no allowlist...
+    invoke(&ctx.accounts.callback_ix, ctx.remaining_accounts)?;
+    // ...and never re-checks that the loan was repaid.
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The borrower's callback program does whatever it wants with the borrowed funds and the accounts handed to it, then returns. Without a post-callback invariant check (balance restored + fee), the attacker keeps the loan. More broadly, any unvalidated callback can re-enter sibling instructions, manipulate oracle/price accounts, or abuse the caller's signer authority.
+
+## Fix pattern
+```rust
+pub fn flash_loan(ctx: Context<FlashLoan>, amount: u64) -> Result<()> {
+    let pre = ctx.accounts.vault.amount;
+    let fee = amount / 1000;
+    token::transfer(/* vault -> borrower */, amount)?;
+    invoke(&ctx.accounts.callback_ix, ctx.remaining_accounts)?;
+    ctx.accounts.vault.reload()?;
+    require!(ctx.accounts.vault.amount >= pre + fee, ErrorCode::LoanNotRepaid);
+    Ok(())
+}
+```
+Where possible, allowlist callback program IDs and minimize the accounts/authority exposed to them.
+
+## Detection heuristic
+- `invoke`/`invoke_signed` of a program ID taken from instruction data or `remaining_accounts` with no allowlist
+- Flash-loan / hook patterns lacking a post-callback `reload()` + invariant assertion
+- Callbacks passed the calling program's PDA signer or mutable core accounts
+
+## References
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Sec3 — flash loan and callback safety (https://www.sec3.dev/blog)
+- SPL Token-2022 — transfer hook interface (https://spl.solana.com/token-2022/extensions#transfer-hook)
+
+## Real-world exploits (if any)
+Flash-loan callbacks that fail to enforce repayment invariants have driven multiple DeFi drains across chains; on Solana this is a standard high-severity audit finding for lending/flash-loan programs.

package/rules/022-cpi-with-attacker-accounts.md

@@ -0,0 +1,58 @@
+# Rule 022: CPI Invoked with Attacker-Controlled Accounts
+
+**Severity:** High
+**Category:** CPI
+
+## Description
+A program performs a CPI to a trusted program but forwards accounts that the caller chose, without validating that those accounts are the correct ones for the operation. The target program ID is right, yet the *accounts* passed into it (source token account, destination, mint, authority) are attacker-substituted, so the trusted CPI executes against the wrong assets.
+
+## Vulnerable pattern
+```rust
+pub fn payout(ctx: Context<Payout>, amount: u64) -> Result<()> {
+    // token_program is correctly the SPL Token program, but `from` is
+    // whatever token account the caller supplied — including the protocol
+    // treasury — and the PDA authority signs for it.
+    let seeds = &[b"vault_auth", &[ctx.accounts.config.bump]];
+    token::transfer(
+        CpiContext::new_with_signer(
+            ctx.accounts.token_program.to_account_info(),
+            Transfer {
+                from: ctx.accounts.from.to_account_info(),       // unvalidated
+                to: ctx.accounts.to.to_account_info(),           // unvalidated
+                authority: ctx.accounts.vault_auth.to_account_info(),
+            },
+            &[&seeds[..]],
+        ),
+        amount,
+    )?;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+Because the program's PDA signs the transfer, it authorizes movement from whatever `from` account is supplied. The attacker points `from` at a token account the PDA controls (or `to` at their own wallet) and drains it through an otherwise-legitimate, correctly-targeted token CPI. The program ID check alone is insufficient — the accounts must be pinned too.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Payout<'info> {
+    #[account(mut, address = config.vault_token)] // pin the source
+    pub from: Account<'info, TokenAccount>,
+    #[account(mut, token::mint = config.mint, token::authority = recipient)]
+    pub to: Account<'info, TokenAccount>,
+    // ...
+}
+```
+
+## Detection heuristic
+- CPIs whose account fields (`from`, `to`, `mint`, `authority`) are `AccountInfo`/`Account` with no `address =`, `token::*`, `has_one`, or seed binding
+- A PDA signer used in a CPI where the source account is not constrained to the PDA-owned account
+- `remaining_accounts` forwarded into CPIs without validation
+
+## References
+- Coral sealevel-attacks — 5-arbitrary-cpi (account-level variant) (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/5-arbitrary-cpi)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- anchor_spl docs — token constraints (https://docs.rs/anchor-spl/latest/anchor_spl/)
+
+## Real-world exploits (if any)
+No single attributed public exploit; unconstrained CPI accounts are a frequent critical/high finding in public audits of vault and payout programs.

package/rules/023-lamport-overflow.md

@@ -0,0 +1,50 @@
+# Rule 023: Lamport Arithmetic Overflow / Underflow
+
+**Severity:** High
+**Category:** Math
+
+## Description
+Lamport balances are `u64`. Adding to or subtracting from them with plain `+`/`-` (or `+=`/`-=`) risks wrapping: in release builds Rust arithmetic does not panic on overflow unless `overflow-checks` is enabled, so an underflow silently wraps to a huge number. Direct lamport manipulation via `try_borrow_mut_lamports` is especially exposed because it bypasses any token-program accounting.
+
+## Vulnerable pattern
+```rust
+pub fn settle(ctx: Context<Settle>, fee: u64) -> Result<()> {
+    let vault = ctx.accounts.vault.to_account_info();
+    let user = ctx.accounts.user.to_account_info();
+    // If fee > vault balance, this underflows and wraps to ~u64::MAX
+    **vault.try_borrow_mut_lamports()? -= fee;
+    **user.try_borrow_mut_lamports()? += fee;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+An underflow on the debit side wraps the vault's lamport field to an enormous value, and a paired credit can mint lamports out of nothing, breaking the transaction's lamport-conservation invariant (the runtime rejects unbalanced lamports, but intra-program accounting fields tracking "balance" can still be corrupted). Overflow on a credit can zero out a balance. Either way, accounting is falsified.
+
+## Fix pattern
+```rust
+pub fn settle(ctx: Context<Settle>, fee: u64) -> Result<()> {
+    let vault = ctx.accounts.vault.to_account_info();
+    let user = ctx.accounts.user.to_account_info();
+    let v = vault.lamports();
+    **vault.try_borrow_mut_lamports()? = v.checked_sub(fee).ok_or(ErrorCode::Underflow)?;
+    let u = user.lamports();
+    **user.try_borrow_mut_lamports()? = u.checked_add(fee).ok_or(ErrorCode::Overflow)?;
+    Ok(())
+}
+```
+Also set `overflow-checks = true` in the program's release profile in `Cargo.toml`.
+
+## Detection heuristic
+- `try_borrow_mut_lamports` with `+=`/`-=`/`+`/`-` instead of `checked_add`/`checked_sub`
+- Lamport math on `account.lamports()` without checked operations
+- `Cargo.toml` profile missing `overflow-checks = true`
+- Any `u64` balance field updated with unchecked arithmetic
+
+## References
+- Neodyme — Solana common pitfalls: integer overflow (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Solana program security course — overflow and underflow (https://solana.com/developers/courses/program-security)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+
+## Real-world exploits (if any)
+Unchecked arithmetic is a contributing factor in numerous DeFi accounting exploits; it is one of the most frequently flagged issues in public Solana audit reports.

package/rules/024-token-amount-overflow.md

@@ -0,0 +1,52 @@
+# Rule 024: Token Amount Arithmetic Overflow
+
+**Severity:** High
+**Category:** Math
+
+## Description
+The same overflow/underflow risk as lamport math (Rule 023) applied to SPL token amounts, share calculations, reward accumulators, and any `u64`/`u128` balance the program tracks itself. Vaults that compute shares from deposits, AMMs that compute output amounts, and staking programs accumulating rewards all multiply and add large numbers; without checked arithmetic these wrap silently in release builds.
+
+## Vulnerable pattern
+```rust
+pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
+    let vault = &mut ctx.accounts.vault;
+    // shares = amount * total_shares / total_assets
+    // amount * total_shares overflows u64 for large inputs
+    let shares = amount * vault.total_shares / vault.total_assets;
+    vault.total_shares += shares;   // unchecked
+    vault.total_assets += amount;   // unchecked
+    ctx.accounts.user_position.shares += shares;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+An overflow in `amount * total_shares` wraps to a small number, minting too few or — combined with a wrapped denominator — too many shares, letting an attacker mint shares disproportionate to their deposit and then redeem more than they put in. Accumulator overflows can reset reward debt. The conservation invariant (shares ↔ assets) is broken.
+
+## Fix pattern
+```rust
+pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
+    let vault = &mut ctx.accounts.vault;
+    let shares = (amount as u128)
+        .checked_mul(vault.total_shares as u128).ok_or(ErrorCode::Overflow)?
+        .checked_div(vault.total_assets as u128).ok_or(ErrorCode::DivByZero)?;
+    let shares = u64::try_from(shares).map_err(|_| ErrorCode::Overflow)?;
+    vault.total_shares = vault.total_shares.checked_add(shares).ok_or(ErrorCode::Overflow)?;
+    vault.total_assets = vault.total_assets.checked_add(amount).ok_or(ErrorCode::Overflow)?;
+    Ok(())
+}
+```
+
+## Detection heuristic
+- `*`, `+`, `-` on token-amount/share/reward fields instead of `checked_*` (or widening to `u128` for intermediates)
+- Multiplications of two `u64` token amounts without widening
+- Reward/index accumulators using unchecked `+=`
+- Missing `overflow-checks = true` in release profile
+
+## References
+- Neodyme — Solana common pitfalls: integer overflow (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Sec3 — arithmetic safety in Solana programs (https://www.sec3.dev/blog)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+
+## Real-world exploits (if any)
+Share/asset arithmetic errors are a recurring root cause of vault and AMM exploits across DeFi; standard high-severity audit finding.

package/rules/025-precision-loss.md

@@ -0,0 +1,42 @@
+# Rule 025: Precision Loss (Division Before Multiplication)
+
+**Severity:** Medium
+**Category:** Math
+
+## Description
+Integer division truncates. Performing division before multiplication discards the remainder early, magnifying rounding error in the final result. The canonical bug is `(a / b) * c` where `a / b` rounds to zero or loses significant digits before being scaled up, instead of `(a * c) / b`, which preserves precision by dividing last.
+
+## Vulnerable pattern
+```rust
+// reward = stake / total_stake * reward_pool
+// stake / total_stake is integer division: for any stake < total_stake
+// it evaluates to 0, so reward is always 0.
+let reward = (stake / total_stake) * reward_pool;
+```
+
+## Why this is dangerous
+A user with 1 of 1000 total stake computes `1 / 1000 = 0`, then `0 * reward_pool = 0` — they earn nothing, while the rounding "dust" silently accrues somewhere or is lost. In fee or exchange-rate math, the same error lets an attacker structure amounts so the protocol rounds in their favor repeatedly, extracting value over many small transactions.
+
+## Fix pattern
+```rust
+// Multiply first, divide last, and widen to u128 to avoid overflow:
+let reward = (stake as u128)
+    .checked_mul(reward_pool as u128).ok_or(ErrorCode::Overflow)?
+    .checked_div(total_stake as u128).ok_or(ErrorCode::DivByZero)?;
+let reward = u64::try_from(reward).map_err(|_| ErrorCode::Overflow)?;
+```
+Where exactness matters, track and distribute remainders explicitly.
+
+## Detection heuristic
+- Expressions of the form `(a / b) * c` or `a / b * c` on token/share/fee amounts
+- Division applied to operands that are then scaled up
+- Ratio/rate math done entirely in `u64` without widening to `u128`
+- Reward-per-share or price calculations dividing before applying a multiplier
+
+## References
+- Sec3 — arithmetic precision in Solana programs (https://www.sec3.dev/blog)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+
+## Real-world exploits (if any)
+No single attributed public exploit; precision-loss findings are common in audits of staking and AMM math and can leak value continuously.

package/rules/026-rounding-direction.md

@@ -0,0 +1,43 @@
+# Rule 026: Incorrect Rounding Direction
+
+**Severity:** Medium
+**Category:** Math
+
+## Description
+When integer math must round, the direction must always favor the protocol, not the user. Minting shares should round *down*; charging fees or computing how much a user must repay should round *up*. A consistent "round in the user's favor" or naive truncation lets an attacker repeatedly extract the rounding difference, and in share-based vaults enables inflation/donation attacks.
+
+## Vulnerable pattern
+```rust
+// Withdrawal: assets owed for `shares`. Truncating division rounds DOWN
+// the amount burned-for but the protocol pays out the rounded-up assets
+// elsewhere — or, mint rounds UP giving free shares:
+let shares_to_mint = (deposit * total_shares + total_assets) / total_assets; // rounds up on mint
+```
+
+## Why this is dangerous
+If minting rounds up, an attacker deposits tiny amounts many times, each rounding up to extra shares, and redeems for more than deposited. The first-depositor / share-inflation attack combines zero-supply edge cases with favorable rounding to steal later depositors' funds. Rounding that favors the user is a slow, repeatable drain.
+
+## Fix pattern
+```rust
+// Mint shares: round DOWN (truncating division is correct here)
+let shares = deposit.checked_mul(total_shares)?.checked_div(total_assets)?;
+// Repay / fee owed by user: round UP
+let owed = amount.checked_mul(rate)?
+    .checked_add(scale - 1)?       // ceil division
+    .checked_div(scale)?;
+```
+Add a minimum-liquidity / dead-shares mechanism to neutralize first-depositor inflation.
+
+## Detection heuristic
+- Share-minting math that rounds up, or redemption math that rounds up in the user's favor
+- Fee/interest/repayment calculations that truncate (round down) what the user owes
+- Vaults with no first-depositor protection (dead shares, minimum liquidity)
+- Mixed rounding directions used inconsistently between deposit and withdraw paths
+
+## References
+- Sec3 — rounding and share inflation (https://www.sec3.dev/blog)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- OpenZeppelin — ERC4626 inflation attack writeups (concept reference) (https://docs.openzeppelin.com/contracts/4.x/erc4626)
+
+## Real-world exploits (if any)
+Share-inflation/first-depositor attacks have caused losses in vault protocols across ecosystems; rounding-direction errors are a standard medium/high audit finding.

package/rules/027-token-decimal-mismatch.md

@@ -0,0 +1,50 @@
+# Rule 027: Token Decimal Mismatch
+
+**Severity:** Medium
+**Category:** Math
+
+## Description
+Different SPL mints have different `decimals`. Code that compares, adds, or exchanges raw token amounts across mints without normalizing for decimals treats `1 USDC` (6 decimals → 1_000_000) and `1 of an 9-decimal token` (1_000_000_000) as if they were the same magnitude. Any cross-mint price, swap, or collateral computation that ignores decimals is wrong by orders of magnitude.
+
+## Vulnerable pattern
+```rust
+// Collateral value compared directly to debt, different mints/decimals:
+let collateral_amount = ctx.accounts.collateral_token.amount; // 9 decimals
+let debt_amount = ctx.accounts.debt_token.amount;             // 6 decimals
+require!(collateral_amount >= debt_amount, ErrorCode::Undercollateralized);
+// 1.0 collateral (1e9) looks like 1000x the debt of 1.0 (1e6)
+```
+
+## Why this is dangerous
+The attacker exploits the scale error in whichever direction helps them: borrowing against collateral that appears 1000x more valuable than it is, or swapping at a wildly mispriced rate. Hardcoding a decimal assumption (e.g. always 6) breaks the moment a mint with different decimals is used, which an attacker can arrange when mints are user-supplied.
+
+## Fix pattern
+```rust
+// Normalize both sides to a common scale using each mint's decimals:
+fn to_scaled(amount: u64, decimals: u8, target: u8) -> Option<u128> {
+    let a = amount as u128;
+    if decimals <= target {
+        a.checked_mul(10u128.pow((target - decimals) as u32))
+    } else {
+        Some(a / 10u128.pow((decimals - target) as u32))
+    }
+}
+let coll = to_scaled(collateral_amount, collateral_mint.decimals, 18)?;
+let debt = to_scaled(debt_amount, debt_mint.decimals, 18)?;
+require!(coll >= debt, ErrorCode::Undercollateralized);
+```
+Read `decimals` from the actual `Mint` account, never hardcode.
+
+## Detection heuristic
+- Cross-mint comparisons/arithmetic on raw `.amount` without reading each `Mint::decimals`
+- Hardcoded decimal constants (e.g. `1_000_000`) instead of `mint.decimals`
+- Price/collateral/swap math mixing amounts from different mints
+- Mint accounts passed but `decimals` never read
+
+## References
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- SPL Token docs — mint decimals (https://spl.solana.com/token)
+- Sec3 — token handling pitfalls (https://www.sec3.dev/blog)
+
+## Real-world exploits (if any)
+No single attributed public exploit; decimal-handling errors are a frequent audit finding in lending and DEX programs that support arbitrary mints.

package/rules/028-integer-cast-truncation.md

@@ -0,0 +1,42 @@
+# Rule 028: Integer Cast Truncation
+
+**Severity:** Medium
+**Category:** Math
+
+## Description
+The Rust `as` operator performs a silent, lossy cast: `large_u128 as u64`, `u64 as u32`, or `i64 as u8` discard high bits without any error. Casting a computed value down to a narrower type — common when interfacing with `u64` token amounts after `u128` intermediate math — can wrap a large number to a small one, falsifying amounts and bypassing bound checks.
+
+## Vulnerable pattern
+```rust
+let scaled: u128 = (amount as u128) * (price as u128) / DENOM;
+// scaled may exceed u64::MAX; `as u64` silently keeps only the low 64 bits
+let payout: u64 = scaled as u64;
+token::transfer(/* ... */, payout)?;
+```
+
+## Why this is dangerous
+A `u128` result that legitimately exceeds `u64::MAX` wraps to a small `payout`, or a near-boundary value wraps in a way the attacker can engineer to mint/withdraw an amount that passes earlier `<=` checks (performed in the wide type) but executes with a different narrow value. Downcasting indices or counts (`as u32`, `as u8`) can also wrap loop bounds.
+
+## Fix pattern
+```rust
+let scaled: u128 = (amount as u128)
+    .checked_mul(price as u128).ok_or(ErrorCode::Overflow)?
+    .checked_div(DENOM).ok_or(ErrorCode::DivByZero)?;
+// Fallible conversion: errors instead of truncating
+let payout: u64 = u64::try_from(scaled).map_err(|_| ErrorCode::Overflow)?;
+token::transfer(/* ... */, payout)?;
+```
+
+## Detection heuristic
+- `as u64` / `as u32` / `as u16` / `as u8` applied to wider computed values (especially after `u128` math)
+- Narrowing casts on token amounts, lamports, prices, or indices
+- Casts used in place of `try_from` / `try_into` where the source range exceeds the target
+- Signed/unsigned casts (`as i64` ↔ `as u64`) on values that could be negative or large
+
+## References
+- Neodyme — Solana common pitfalls: casting (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Rust reference — numeric cast semantics (https://doc.rust-lang.org/reference/expressions/operator-expr.html#numeric-cast)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+
+## Real-world exploits (if any)
+No single attributed public exploit; truncating casts are a recurring audit finding wherever `u128` intermediate math is narrowed back to `u64`.

package/rules/029-off-by-one.md

@@ -0,0 +1,45 @@
+# Rule 029: Off-by-One Errors
+
+**Severity:** Low
+**Category:** Math
+
+## Description
+Boundary mistakes in iteration, indexing, slicing, and threshold comparisons: `<` where `<=` was meant, loops that skip the last element or read one past the end, and slice ranges that drop or duplicate a byte. On Solana these surface in manual account-data parsing, `remaining_accounts` iteration, and threshold checks (quorums, caps, expiry).
+
+## Vulnerable pattern
+```rust
+// Quorum check off by one: requires strictly more than half, but the
+// intent was "at least half" — or vice-versa. Either way the boundary
+// case is wrong.
+require!(votes > total / 2, ErrorCode::QuorumNotMet);
+
+// Slice that drops the last byte of the discriminator/region:
+let body = &data[8..data.len() - 1];
+```
+
+## Why this is dangerous
+A threshold off by one lets a proposal pass with one vote too few, or blocks a legitimate one. Slice/index off-by-ones either panic (DoS for that instruction) or, worse, read adjacent bytes, mis-parsing a field that feeds into authorization or amount logic. In `remaining_accounts` loops, an off-by-one can skip a required account check.
+
+## Fix pattern
+```rust
+// State the boundary explicitly and test it:
+require!(votes.checked_mul(2).ok_or(ErrorCode::Overflow)? >= total,
+         ErrorCode::QuorumNotMet); // >= half
+
+let body = data.get(8..).ok_or(ErrorCode::Malformed)?; // no manual len math
+```
+Prefer `.get(range)` (returns `Option`) over direct indexing, and add explicit boundary tests.
+
+## Detection heuristic
+- Threshold comparisons (`>`, `>=`, `<`, `<=`) on quorums, caps, expiries, min/max where the boundary intent is ambiguous
+- Manual slice ranges with `+ 1` / `- 1` / `len() - 1` arithmetic
+- `for i in 0..n` loops indexing `arr[i + 1]` or `arr[i - 1]`
+- Direct slice indexing (`data[a..b]`) on attacker-sized data instead of `.get`
+
+## References
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Sec3 — common Solana logic bugs (https://www.sec3.dev/blog)
+- Rust docs — slice::get (https://doc.rust-lang.org/std/primitive.slice.html#method.get)
+
+## Real-world exploits (if any)
+No single attributed public exploit; off-by-one bugs are common low/medium audit findings, occasionally escalating when they govern authorization thresholds.

package/rules/030-missing-authorization.md

@@ -0,0 +1,51 @@
+# Rule 030: Missing Authorization on Privileged Instruction
+
+**Severity:** Critical
+**Category:** Auth
+
+## Description
+A privileged instruction — withdraw, close, set-config, pause, mint, upgrade-authority change — performs its action without verifying that the caller is allowed to. This is broader than a missing signer (Rule 001): even with a signer present, the program may fail to check that the signer is *the right* principal for this resource (the vault's owner, the protocol admin, the position holder).
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct SetFee<'info> {
+    #[account(mut)]
+    pub config: Account<'info, Config>,
+    pub caller: Signer<'info>, // any signer at all
+}
+
+pub fn set_fee(ctx: Context<SetFee>, new_fee: u16) -> Result<()> {
+    // No check that caller == config.admin
+    ctx.accounts.config.fee_bps = new_fee;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+Anyone can sign a transaction, so requiring "a signer" without binding it to the privileged role lets any user set the protocol fee, withdraw from any vault, or change critical config. The attacker simply calls the instruction with their own signature. This is the most direct privilege-escalation class.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct SetFee<'info> {
+    #[account(mut, has_one = admin)] // config.admin must equal admin.key()
+    pub config: Account<'info, Config>,
+    pub admin: Signer<'info>,
+}
+```
+Use `has_one`, `address = config.admin`, or an explicit `require_keys_eq!(caller.key(), config.admin)` plus a signer requirement.
+
+## Detection heuristic
+- Privileged handlers (set_*, withdraw, close, mint, pause, transfer_authority) with a `Signer` that is never compared to a stored authority
+- Missing `has_one` / `address =` / `require_keys_eq!` linking the signer to the resource's owner/admin
+- Config or vault mutations where the only gate is "is a signer"
+- Admin functions reachable by accounts with no role binding
+
+## References
+- Solana program security course — signer & owner authorization (https://solana.com/developers/courses/program-security/signer-auth)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Anchor docs — has_one and address constraints (https://www.anchor-lang.com/docs/account-constraints)
+
+## Real-world exploits (if any)
+Missing/weak authorization is among the most common root causes in public Solana exploit post-mortems and audit critical findings.