audit-system 2.0.0

package/obsidian-vault/invariant-catalog/defi-invariants.md

@@ -0,0 +1,307 @@
+# DeFi Invariants Catalog
+
+tags: #invariants #defi #catalog #security
+
+---
+
+## Overview
+This catalog documents common invariants in DeFi protocols. Each invariant represents a property that must always hold true. Breaking an invariant typically indicates a vulnerability.
+
+---
+
+## Lending Protocol Invariants
+
+### LI-01: Collateralization Ratio
+```
+invariant: total_collateral >= total_debt * liquidation_threshold / 100
+violation: Undercollateralized positions not liquidated
+severity: CRITICAL
+```
+
+### LI-02: Solvency
+```
+invariant: contract_token_balance >= total_user_deposits
+violation: Users cannot withdraw deposits
+severity: CRITICAL
+```
+
+### LI-03: Interest Accumulation
+```
+invariant: debt_amount only increases (or stays same) over time
+violation: Debt incorrectly calculated
+severity: HIGH
+```
+
+### LI-04: Liquidation Economics
+```
+invariant: liquidation_incentive > 0 && liquidation_incentive < 100%
+violation: Liquidators lose money or can extract excessive value
+severity: HIGH
+```
+
+---
+
+## DEX/AMM Invariants
+
+### DEX-01: Constant Product (x*y=k)
+```
+invariant: reserve0 * reserve1 >= k (approximately, before fees)
+violation: Pool manipulation, price manipulation
+severity: CRITICAL
+```
+
+### DEX-02: Price Consistency
+```
+invariant: spot_price ≈ time_weighted_average_price (within reasonable bounds)
+violation: Oracle manipulation, flash loan attacks
+severity: CRITICAL
+```
+
+### DEX-03: LP Token Value
+```
+invariant: total_lp_supply <= total_reserves (in value terms)
+violation: LP tokens minted without backing
+severity: CRITICAL
+```
+
+### DEX-04: K Invariant Monotonicity
+```
+invariant: k only increases with fees
+violation: Fees not properly collected
+severity: MEDIUM
+```
+
+---
+
+## Staking Protocol Invariants
+
+### ST-01: Staked Balance
+```
+invariant: user_staked_balance <= user_token_balance (at deposit time)
+violation: Can stake more than owned
+severity: CRITICAL
+```
+
+### ST-02: Reward Accrual
+```
+invariant: pending_rewards >= 0 && monotonically increasing
+violation: Rewards incorrectly calculated
+severity: HIGH
+```
+
+### ST-03: Unstaking Period
+```
+invariant: unstake_time >= stake_time + lock_duration
+violation: Early withdrawal possible
+severity: HIGH
+```
+
+### ST-04: Total Staked
+```
+invariant: sum(user_stakes) == total_staked
+violation: Accounting discrepancy
+severity: CRITICAL
+```
+
+---
+
+## Governance Token Invariants
+
+### GOV-01: Voting Power
+```
+invariant: voting_power <= token_balance (or delegated amount)
+violation: Double voting
+severity: CRITICAL
+```
+
+### GOV-02: Proposal Threshold
+```
+invariant: proposal_creator_votes >= proposal_threshold
+violation: Spam proposals
+severity: MEDIUM
+```
+
+### GOV-03: Execution Delay
+```
+invariant: execution_time >= creation_time + voting_period + timelock
+violation: Premature execution
+severity: HIGH
+```
+
+### GOV-04: Quorum
+```
+invariant: for votes + against votes + abstain votes >= quorum (for valid proposals)
+violation: Proposals pass without sufficient participation
+severity: CRITICAL
+```
+
+---
+
+## Vault/Yield Aggregator Invariants
+
+### VAULT-01: Share Price
+```
+invariant: share_price >= 1e18 (or base value)
+violation: First depositor / inflation attack
+severity: CRITICAL
+```
+
+### VAULT-02: Deposit/Withdraw Ratio
+```
+invariant: assets_withdrawn ≈ shares_burned * share_price (with tolerance)
+violation: Price manipulation, rounding error exploitation
+severity: HIGH
+```
+
+### VAULT-03: Strategy Allocation
+```
+invariant: sum(strategy_allocations) == 100%
+violation: Funds lost or locked
+severity: CRITICAL
+```
+
+### VAULT-04: Harvest Timing
+```
+invariant: harvest_profit > harvest_gas_cost (or harvest blocked)
+violation: Loss through excessive harvests
+severity: MEDIUM
+```
+
+---
+
+## Bridge/Cross-Chain Invariants
+
+### BRIDGE-01: Token Conservation
+```
+invariant: tokens_locked_on_source == tokens_minted_on_target (per user)
+violation: Double minting, unbacked tokens
+severity: CRITICAL
+```
+
+### BRIDGE-02: Verification
+```
+invariant: message must be signed by threshold of validators
+violation: Unauthorized minting/burning
+severity: CRITICAL
+```
+
+### BRIDGE-03: Nonce Uniqueness
+```
+invariant: each bridge transaction has unique nonce
+violation: Replay attacks
+severity: CRITICAL
+```
+
+---
+
+## Token Standard Invariants
+
+### ERC20-01: Balance Conservation
+```
+invariant: sum(all_balances) == total_supply (with allowances caveat)
+violation: Inflation bugs, minting exploits
+severity: CRITICAL
+```
+
+### ERC20-02: Approval
+```
+invariant: transferFrom succeeds only if allowance >= amount
+violation: Unauthorized transfers
+severity: CRITICAL
+```
+
+### ERC721-01: Ownership
+```
+invariant: ownerOf(tokenId) returns single address
+violation: Double ownership
+severity: CRITICAL
+```
+
+---
+
+## Insurance Protocol Invariants
+
+### INS-01: Capital Pool
+```
+invariant: capital_pool >= total_coverage_amount * risk_factor
+violation: Insufficient funds for claims
+severity: CRITICAL
+```
+
+### INS-02: Claim Validity
+```
+invariant: claim_amount <= coverage_amount && claim_approved == true
+violation: Fraudulent claims
+severity: HIGH
+```
+
+### INS-03: Premium Calculation
+```
+invariant: premium >= expected_claims / capital_pool (simplified)
+violation: Underpricing, insolvency
+severity: HIGH
+```
+
+---
+
+## Derivatives/Options Invariants
+
+### DER-01: Collateralization
+```
+invariant: collateral >= max_payout (for sellers)
+violation: Unable to pay out
+severity: CRITICAL
+```
+
+### DER-02: Exercise Validity
+```
+invariant: option_exercisable only if strike_price conditions met
+violation: Invalid exercise
+severity: HIGH
+```
+
+### DER-03: Settlement
+```
+invariant: settlement_price >= 0 && settlement_price <= market_price * max_multiple
+violation: Oracle manipulation
+severity: CRITICAL
+```
+
+---
+
+## Using This Catalog
+
+### During Audit
+1. Identify protocol type
+2. Review relevant invariants
+3. Test each invariant with property-based tests
+4. Document any violations
+
+### Hypothesis Generation
+```
+Pattern: "What if [INVARIANT] is violated via [ATTACK_VECTOR]?"
+Example: "What if total_collateral < total_debt via flash loan manipulation?"
+```
+
+### Tool Integration
+Use with:
+- Echidna: Define as `invariant()` functions
+- Foundry: Write as `testInvariant_*` tests
+- Certora: Specify as `invariant` rules
+
+---
+
+## Solana-Specific Additions
+
+See [[solana-invariants]] for invariants specific to Solana/Anchor programs:
+- Account model invariants (ownership, discrimination, uniqueness)
+- PDA derivation invariants (canonical bump, seed validation)
+- CPI invariants (program ID validation, return check, reentrancy)
+- SPL token invariants (ownership, mint authority, balance conservation)
+- State machine invariants (discriminator, initialization, close)
+
+## Links
+- [[attack-patterns/state-inconsistency]] — Many invariants enforce state consistency
+- [[test-strategies/invariant-testing]] — How to test these
+- [[novel-patterns/pattern-mutation-framework]] — Combine invariants for novel attacks
+- [[solana-invariants]] — Solana/Anchor-specific invariants

package/obsidian-vault/invariant-catalog/solana-invariants.md

@@ -0,0 +1,213 @@
+# Solana Program Invariants Catalog
+
+tags: #invariants #solana #anchor #catalog #security
+
+---
+
+## Overview
+This catalog documents invariants specific to Solana/Anchor programs. These must ALWAYS hold for secure operation.
+
+---
+
+## Account Model Invariants
+
+### SOL-ACC-01: Account Discrimination
+```
+invariant: every instruction verifies the account discriminator before reading data
+violation: account data misinterpreted, reinitialization attacks
+severity: CRITICAL
+```
+
+### SOL-ACC-02: Account Ownership
+```
+invariant: account.owner == expected_program_id for all program-owned accounts
+violation: unauthorized account access, fake accounts
+severity: CRITICAL
+```
+
+### SOL-ACC-03: Account Uniqueness
+```
+invariant: no two accounts of same type in an instruction can be the same pubkey
+  (unless explicitly designed for it)
+violation: account confusion, self-dealing
+severity: HIGH
+```
+
+### SOL-ACC-04: Signer Verification
+```
+invariant: every privileged action requires a Signer check
+violation: unauthorized state modification
+severity: CRITICAL
+```
+
+### SOL-ACC-05: Writable Permissions
+```
+invariant: accounts whose data is modified must be marked `mut`
+violation: failed transactions, unexpected behavior
+severity: HIGH
+```
+
+---
+
+## PDA Invariants
+
+### SOL-PDA-01: Deterministic Derivation
+```
+invariant: PDA seeds produce deterministic, unique addresses
+violation: two users share same PDA, fund confusion
+severity: CRITICAL
+```
+
+### SOL-PDA-02: Canonical Bump
+```
+invariant: only the canonical (highest valid) bump seed is used
+violation: multiple valid bumps create ambiguity
+severity: MEDIUM
+```
+
+### SOL-PDA-03: Seed Validation
+```
+invariant: seeds used in PDA derivation are validated against instruction data
+violation: arbitrary PDA signing, forged authority
+severity: CRITICAL
+```
+
+### SOL-PDA-04: PDA Signing
+```
+invariant: PDA signs via `invoke_signed` with correct seeds and bump
+violation: CPI with wrong authority, unauthorized transfers
+severity: CRITICAL
+```
+
+---
+
+## CPI Invariants
+
+### SOL-CPI-01: Program ID Validation
+```
+invariant: program_id in CPI is validated against expected constant
+violation: arbitrary CPI execution, malicious program calls
+severity: CRITICAL
+```
+
+### SOL-CPI-02: CPI Return Check
+```
+invariant: CPI return value is checked for errors
+violation: silent failure, incorrect state transition
+severity: HIGH
+```
+
+### SOL-CPI-03: CPI Reentrancy Protection
+```
+invariant: contract state is committed before CPI to untrusted program
+violation: reentrancy via CPI callback
+severity: CRITICAL
+```
+
+---
+
+## Token (SPL) Invariants
+
+### SOL-TOK-01: Token Account Ownership
+```
+invariant: token account owner matches expected authority
+violation: unauthorized transfers, token theft
+severity: CRITICAL
+```
+
+### SOL-TOK-02: Mint Authority
+```
+invariant: only authorized programs/users can mint new tokens
+violation: token inflation, unbacked minting
+severity: CRITICAL
+```
+
+### SOL-TOK-03: Balance Conservation
+```
+invariant: sum(token_balances) == total_supply (per mint)
+violation: token creation/destruction outside mint/burn
+severity: CRITICAL
+```
+
+### SOL-TOK-04: Close Account Destination
+```
+invariant: closed token account lamports go to the correct owner
+violation: rent theft, fund loss
+severity: HIGH
+```
+
+---
+
+## State Machine Invariants
+
+### SOL-SM-01: Discriminator Immutability
+```
+invariant: account discriminator (first 8 bytes) never changes after init
+violation: account reinterpretation, type confusion
+severity: CRITICAL
+```
+
+### SOL-SM-02: Initialization Check
+```
+invariant: initialized accounts cannot be reinitialized
+violation: reinitialization attack, privilege escalation
+severity: HIGH
+```
+
+### SOL-SM-03: Close Protection
+```
+invariant: closed accounts cannot be used without reinitialization
+violation: use-after-close, stale data access
+severity: HIGH
+```
+
+---
+
+## Economic Invariants
+
+### SOL-ECO-01: Solvency
+```
+invariant: program-owned token balance >= user deposits tracked in program state
+violation: insolvency, inability to withdraw
+severity: CRITICAL
+```
+
+### SOL-ECO-02: Rent Exemption
+```
+invariant: all program accounts remain rent-exempt
+violation: account purged, data loss
+severity: MEDIUM
+```
+
+### SOL-ECO-03: Fee Correctness
+```
+invariant: protocol fees are correctly calculated and cannot be bypassed
+violation: revenue loss, attacker profit at protocol expense
+severity: HIGH
+```
+
+---
+
+## Using This Catalog
+
+### During Audit
+1. Identify program type (AMM, lending, staking, etc.)
+2. Review relevant Solana invariants
+3. Test each invariant with Anchor test suite
+4. Document any violations
+
+### Hypothesis Generation
+```
+Pattern: "What if [SOL-INVARIANT] is violated via [ATTACK_VECTOR]?"
+Example: "What if SOL-ACC-02 (account ownership) is violated via account confusion?"
+Example: "What if SOL-CPI-03 (CPI reentrancy) is violated via malicious program callback?"
+```
+
+---
+
+## Links
+- [[../vulnerabilities/solana-account-confusion]]
+- [[../vulnerabilities/solana-cpi-attacks]]
+- [[../vulnerabilities/solana-signer-authorization]]
+- [[../vulnerabilities/solana-close-account]]
+- [[defi-invariants]] (general DeFi invariants)