openclaw/1kalin/afrexai-web3-engineering

Web3 & Blockchain Engineering

Complete methodology for evaluating, designing, building, securing, and operating blockchain-based systems. Covers smart contract development, DeFi protocol design, token economics, security auditing, and production operations.

Zero dependencies. Framework-agnostic. Works with any blockchain, any language, any AI agent.

---

Phase 1: Should You Use Blockchain?

The Database Test

Before writing a single line of Solidity, answer honestly:

blockchain_evaluation:
  problem: "[describe the core problem]"
  
  requirements:
    multiple_untrusting_parties: true/false    # >1 org needs shared truth
    no_trusted_authority: true/false            # no single party everyone trusts
    immutability_critical: true/false           # history must be tamper-proof
    censorship_resistance_needed: true/false    # no entity should block access
    value_transfer_required: true/false         # moving assets between parties
    transparency_required: true/false           # all parties need verifiable state
  
  disqualifiers:
    single_org_controls_data: true/false        # → use a database
    data_deletion_required: true/false          # → GDPR conflict, careful
    high_throughput_low_latency: true/false     # → >10K TPS? consider L2 or database
    users_cant_manage_wallets: true/false       # → account abstraction or custodial
    trusted_authority_exists: true/false        # → database with audit log
  
  score: "[count true requirements - count true disqualifiers]"
  verdict: "blockchain / hybrid / database"

Decision rules:

• Score ≤ 0 → Use PostgreSQL with audit logs
• Score 1-2 → Hybrid (anchoring/notarization on-chain, logic off-chain)
• Score 3+ → Blockchain is justified

Platform Selection Matrix

| Platform | TPS | Finality | Gas Cost | Best For | |----------|-----|----------|----------|----------| | Ethereum L1 | ~30 | ~12 min | $1-50+ | Settlement, high-value DeFi | | Arbitrum | ~4,000 | ~1 sec (soft) | $0.01-0.10 | DeFi, general dApps | | Optimism | ~2,000 | ~2 sec (soft) | $0.01-0.15 | Public goods, governance | | Base | ~2,000 | ~2 sec (soft) | $0.001-0.05 | Consumer apps, social | | Polygon PoS | ~7,000 | ~2 sec | $0.001-0.01 | Gaming, mass-market | | Solana | ~65,000 | ~400ms | $0.00025 | High-frequency, DePIN | | Avalanche C | ~4,500 | ~1 sec | $0.01-0.10 | Enterprise, subnets | | BNB Chain | ~2,000 | ~3 sec | $0.01-0.05 | Retail, low-cost | | Bitcoin L1 | ~7 | ~60 min | $0.50-5+ | Store of value, settlement | | Bitcoin L2 (Lightning) | ~1M+ | instant | <$0.01 | Micropayments, P2P |

Selection decision tree:

1. Store of value / settlement only? → Bitcoin
2. Micropayments / instant P2P? → Lightning Network
3. Need EVM compatibility? → Yes: continue. No: consider Solana, Cosmos
4. High-value DeFi / maximum security? → Ethereum L1
5. General dApp with low gas? → Arbitrum or Base
6. Mass-market consumer? → Base or Polygon
7. Enterprise with custom rules? → Avalanche subnets or Hyperledger

---

Phase 2: Smart Contract Architecture

Design Principles

1. Minimize on-chain state — Storage is expensive. Put data on-chain only if it needs consensus
2. Fail loudly — Use require() / revert() with descriptive messages, never silent failures
3. Immutability by default — Upgradeability adds attack surface. Only use if genuinely needed
4. Separation of concerns — One contract per responsibility
5. Gas-conscious design — Every operation costs money. Optimize hot paths

Contract Architecture Patterns

architecture_brief:
  project: "[name]"
  type: "DeFi / NFT / DAO / Token / Marketplace / Infrastructure"
  
  contracts:
    core:
      - name: "[MainContract]"
        responsibility: "[single clear purpose]"
        state_variables: ["list key storage"]
        external_calls: ["contracts it calls"]
    
    periphery:
      - name: "[Router/Helper]"
        responsibility: "[user-facing convenience]"
    
    libraries:
      - name: "[MathLib/SafeLib]"
        responsibility: "[shared pure functions]"
  
  upgrade_strategy: "immutable / transparent-proxy / UUPS / diamond / beacon"
  access_control: "Ownable / AccessControl / Timelock+Multisig / DAO"

Upgrade Pattern Decision

| Pattern | Complexity | Gas Overhead | Storage Layout Risk | Best For | |---------|-----------|-------------|-------------------|----------| | Immutable | None | None | None | Simple contracts, tokens | | Transparent Proxy | Medium | +gas per call | High | Standard upgradeable | | UUPS | Medium | Lower than transparent | High | Gas-efficient upgradeable | | Diamond (EIP-2535) | High | Medium | High | Large modular systems | | Beacon | Medium | Medium | High | Many identical instances |

Rule: If you can avoid upgradeability, do it. If you must upgrade, use UUPS with timelock + multisig governance.

Solidity Development Standards

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

// — IMPORTS: Use named imports, pin versions —
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

/// @title VaultV1
/// @notice Single-asset vault with deposit/withdraw
/// @dev Uses SafeERC20 for all token transfers
contract VaultV1 is ReentrancyGuard {
    using SafeERC20 for IERC20;

    // — STATE: Group by slot for packing —
    IERC20 public immutable asset;       // slot 0
    uint128 public totalDeposits;        // slot 1 (packed)
    uint128 public totalShares;          // slot 1 (packed)
    
    mapping(address => uint256) public shares;

    // — EVENTS: Index searchable fields —
    event Deposited(address indexed user, uint256 amount, uint256 shares);
    event Withdrawn(address indexed user, uint256 amount, uint256 shares);

    // — ERRORS: Custom errors save gas vs strings —
    error ZeroAmount();
    error InsufficientShares(uint256 requested, uint256 available);

    constructor(IERC20 _asset) {
        asset = _asset;
    }

    /// @notice Deposit assets, receive proportional shares
    /// @param amount Asset amount to deposit
    /// @return mintedShares Shares minted to caller
    function deposit(uint256 amount) external nonReentrant returns (uint256 mintedShares) {
        if (amount == 0) revert ZeroAmount();
        
        // Calculate shares BEFORE transfer (prevent manipulation)
        mintedShares = totalDeposits == 0
            ? amount
            : (amount * totalShares) / totalDeposits;
        
        // Effects before interactions (CEI pattern)
        totalDeposits += uint128(amount);
        totalShares += uint128(mintedShares);
        shares[msg.sender] += mintedShares;
        
        // Interaction last
        asset.safeTransferFrom(msg.sender, address(this), amount);
        
        emit Deposited(msg.sender, amount, mintedShares);
    }
}

Coding Standards Checklist

• [ ] NatSpec on every public/external function
• [ ] Custom errors instead of require strings (saves ~50 gas each)
• [ ] Events for every state change
• [ ] CEI pattern (Checks-Effects-Interactions) on every external call
• [ ] nonReentrant on functions with external calls
• [ ] immutable / constant where possible
• [ ] SafeERC20 for all token transfers
• [ ] No tx.origin for auth (phishing vector)
• [ ] Explicit visibility on all functions and state variables
• [ ] Storage variable packing (group smaller types together)

---

Phase 3: Token Economics (Tokenomics)

Token Type Decision

| Type | Standard | Use Case | Regulatory Risk | |------|----------|----------|----------------| | Utility token | ERC-20 | Access, governance, gas | Medium | | Governance token | ERC-20 + voting | Protocol control | Medium | | Security token | ERC-1400/3643 | Equity, revenue share | HIGH — requires compliance | | NFT (unique) | ERC-721 | Collectibles, identity, access | Low-Medium | | Semi-fungible | ERC-1155 | Gaming items, editions | Low | | Soulbound (SBT) | ERC-5192 | Credentials, reputation | Low | | Stablecoin | ERC-20 + peg | Payments, DeFi collateral | HIGH — regulatory scrutiny |

Token Design Framework

tokenomics:
  token_name: "[Name]"
  symbol: "[SYM]"
  standard: "ERC-20 / ERC-721 / ERC-1155"
  total_supply: "[fixed / capped / inflationary]"
  
  distribution:
    team: "[%] — [vesting schedule]"
    investors: "[%] — [vesting schedule]"
    community: "[%] — [distribution mechanism]"
    treasury: "[%] — [governance-controlled]"
    ecosystem: "[%] — [grants, incentives]"
    liquidity: "[%] — [DEX pairs, market making]"
  
  vesting:
    team_cliff: "12 months minimum"
    team_linear: "24-48 months after cliff"
    investor_cliff: "6-12 months"
    investor_linear: "12-36 months"
  
  value_accrual:
    mechanism: "[fee sharing / buyback-burn / staking yield / utility demand]"
    fee_structure: "[% of protocol revenue → token holders]"
    burn_mechanism: "[deflationary pressure source]"
  
  governance:
    voting_power: "1 token = 1 vote / quadratic / conviction"
    quorum: "[% of supply needed]"
    timelock: "[delay between vote and execution]"
    
  inflation_schedule:
    year_1: "[%]"
    year_2: "[%]"
    long_term: "[target %/year]"
    
  sustainability_test:
    without_new_buyers: "Does the token have utility even if price = 0?"
    revenue_source: "Where does yield come from? (real yield vs emissions)"
    death_spiral_risk: "Can selling pressure create feedback loop?"

Tokenomics Red Flags

| Red Flag | Why It's Bad | Fix | |----------|-------------|-----| | >20% team allocation | Centralization, dump risk | Cap at 15-20%, long vesting | | No cliff period | Immediate sell pressure | 12-month cliff minimum | | Inflationary without utility | Token printing → zero | Emissions tied to real revenue | | "Yield" from new deposits | Ponzi economics | Real yield from fees only | | Governance without timelock | Admin can rug | Timelock + multisig mandatory | | 100% unlocked at launch | Massive sell pressure | Staged unlock over 2-4 years |

---

Phase 4: DeFi Protocol Design

Core DeFi Primitives

| Primitive | What It Does | Key Risk | Examples | |-----------|-------------|----------|----------| | AMM (DEX) | Trustless token swaps | Impermanent loss | Uniswap, Curve | | Lending | Overcollateralized loans | Liquidation cascades | Aave, Compound | | Stablecoin | Price-stable token | Depeg risk | MakerDAO, Ethena | | Yield aggregator | Optimize yield farming | Smart contract risk stacking | Yearn | | Perpetuals | Leveraged derivatives | Liquidation, oracle manipulation | GMX, dYdX | | Liquid staking | Stake + maintain liquidity | Slashing, depeg | Lido, Rocket Pool | | Bridges | Cross-chain transfers | Bridge exploits (billions lost) | LayerZero, Wormhole | | Restaking | Re-use staked assets | Cascading slashing | EigenLayer |

AMM Design (Uniswap V2/V3 Pattern)

Constant Product: x * y = k
Price Impact: Δy = y - k/(x + Δx)
Slippage: (expected_price - actual_price) / expected_price

V3 Concentrated Liquidity:
- LPs choose price range [Pa, Pb]
- Capital efficiency: up to 4000x vs V2
- Trade-off: must actively manage positions

DeFi Security Invariants

Every DeFi protocol MUST maintain these:

1. Solvency — Total assets ≥ total liabilities (always)
2. No free tokens — No path creates tokens from nothing
3. Monotonic shares — Depositing increases shares, withdrawing decreases
4. Oracle freshness — Price data is within acceptable staleness window
5. Liquidation viability — Undercollateralized positions can always be liquidated
6. Access control — Admin functions behind timelock + multisig
7. Withdrawal guarantee — Users can always withdraw their assets (no lock-up without consent)

---

Phase 5: Security Auditing

Vulnerability Taxonomy

| Category | Severity | Common Patterns | |----------|----------|-----------------| | Reentrancy | Critical | External call before state update | | Oracle manipulation | Critical | Flash loan → price manipulation → profit | | Access control | Critical | Missing auth on privileged functions | | Integer overflow | High | Pre-0.8 math without SafeMath | | Front-running | High | Sandwich attacks, MEV extraction | | Flash loan attacks | High | Atomic arbitrage exploiting price feeds | | Logic errors | High | Wrong formula, edge cases, rounding | | Denial of service | Medium | Gas limit exploitation, stuck states | | Centralization | Medium | Single admin key, no timelock | | Griefing | Medium | Making others' transactions fail/expensive |

Security Audit Checklist (100+ Points)

Critical (Must Pass)

• [ ] Reentrancy protection — All external calls follow CEI pattern OR use nonReentrant
• [ ] Access control — Every privileged function has appropriate modifier
• [ ] Oracle security — Price feeds have freshness checks, manipulation resistance
• [ ] Integer safety — Solidity ≥0.8 (built-in overflow checks) or SafeMath
• [ ] Flash loan resistance — Protocol functions work correctly within single transaction
• [ ] Approval hygiene — No unlimited approvals to untrusted contracts
• [ ] Initialization — Proxy contracts can only be initialized once
• [ ] Self-destruct protection — No selfdestruct in implementation contracts
• [ ] Signature replay — Nonces prevent signature reuse across chains/contracts

High Priority

• [ ] Front-running protection — Commit-reveal or deadline parameters on sensitive operations
• [ ] Slippage protection — Min output amounts on swaps/withdrawals
• [ ] Rounding direction — Always round in protocol's favor (against user)
• [ ] Gas griefing — External calls can't force excessive gas consumption
• [ ] Token compatibility — Handles fee-on-transfer, rebasing, and missing-return tokens
• [ ] Withdrawal path — Users can always exit, even if admin functions fail
• [ ] Timelock on admin — Governance changes have delay period
• [ ] Key management — Multisig for all admin functions, no single points of failure
• [ ] Upgrade safety — Storage layout preserved across upgrades (no slot collision)

Medium Priority

• [ ] Event emission — All state changes emit events for off-chain tracking
• [ ] Input validation — Zero address checks, bounds checking on parameters
• [ ] Dust attacks — Small deposits can't grief the accounting
• [ ] Block timestamp — No reliance on exact block.timestamp (manipulable ±15s)
• [ ] Gas optimization — No unbounded loops, batch operations have limits
• [ ] Error messages — Custom errors with meaningful context
• [ ] Test coverage — >95% line coverage, 100% on critical paths

Common Attack Vectors with Mitigations

1. Reentrancy
   Attack: Call back into contract before state is updated
   Fix: CEI pattern + ReentrancyGuard
   
2. Oracle Manipulation (Flash Loan)
   Attack: Borrow → manipulate price → exploit → repay (atomic)
   Fix: TWAP oracles, Chainlink price feeds, manipulation-resistant design
   
3. Sandwich Attack (MEV)
   Attack: Front-run user's swap → inflate price → back-run to profit
   Fix: Deadline parameter, max slippage, private mempools (Flashbots)
   
4. Governance Attack
   Attack: Flash-borrow governance tokens → vote → execute
   Fix: Snapshot at proposal creation, timelock, vote escrow (ve-model)
   
5. Price Oracle Stale Data
   Attack: Use outdated price to exploit arbitrage
   Fix: Chainlink heartbeat check, staleness threshold, circuit breakers

Audit Process

audit_checklist:
  pre_audit:
    - [ ] Code freeze — no changes during audit
    - [ ] Documentation complete (spec, architecture, flow diagrams)
    - [ ] Test suite passing with >95% coverage
    - [ ] Known issues documented
    - [ ] Deployment scripts tested on testnet
    
  audit_scope:
    contracts: ["list all in-scope contracts"]
    lines_of_code: "[total Solidity LoC]"
    complexity: "low / medium / high / critical"
    prior_audits: "[list previous audit firms]"
    
  recommended_firms:
    tier_1: ["Trail of Bits", "OpenZeppelin", "Consensys Diligence"]
    tier_2: ["Spearbit", "Code4rena", "Sherlock"]
    bug_bounty: ["Immunefi (post-deployment)"]
    
  budget_guide:
    simple_token: "$5K-15K"
    defi_protocol: "$50K-200K"
    complex_system: "$200K-500K+"
    
  post_audit:
    - [ ] All critical/high findings fixed
    - [ ] Fix review by auditor
    - [ ] Audit report published (transparency)
    - [ ] Bug bounty program launched

---

Phase 6: Testing Strategy

Test Pyramid for Smart Contracts

                    /\
                   /  \        Mainnet Fork Tests
                  /    \       (real state, real tokens)
                 /------\
                /        \     Integration Tests
               /          \    (multi-contract interactions)
              /------------\
             /              \   Unit Tests
            /                \  (single function, isolated)
           /------------------\
          /                    \ Static Analysis
         /                      \ (Slither, Mythril, Aderyn)
        /________________________\

Testing Checklist

testing_requirements:
  static_analysis:
    tools: ["Slither", "Mythril", "Aderyn"]
    run: "On every commit (CI)"
    
  unit_tests:
    coverage_target: ">95% line, 100% critical paths"
    framework: "Foundry (preferred) or Hardhat"
    must_test:
      - All require/revert conditions
      - Boundary values (0, 1, max_uint256)
      - Access control on every privileged function
      - Math precision and rounding
      
  integration_tests:
    must_test:
      - Full user flows (deposit → earn → withdraw)
      - Multi-contract interactions
      - Upgrade paths (storage layout preservation)
      - Governance proposal → execution flow
      
  fork_tests:
    must_test:
      - Real mainnet state interactions
      - Oracle price feed behavior
      - Token compatibility (USDT, USDC, DAI, etc.)
      - Gas costs with real-world state size
      
  fuzz_tests:
    tool: "Foundry fuzz / Echidna / Medusa"
    invariants:
      - "Total supply == sum of all balances"
      - "Total assets >= total liabilities"
      - "Share price monotonically increases (yield vaults)"
      - "No function creates tokens from nothing"
      
  formal_verification:
    when: "Critical DeFi with >$10M TVL"
    tools: ["Certora", "Halmos", "KEVM"]

Foundry Test Pattern

// test/VaultV1.t.sol
contract VaultV1Test is Test {
    VaultV1 vault;
    MockERC20 token;
    address alice = makeAddr("alice");
    
    function setUp() public {
        token = new MockERC20("Test", "TST", 18);
        vault = new VaultV1(IERC20(address(token)));
        token.mint(alice, 1000e18);
        vm.prank(alice);
        token.approve(address(vault), type(uint256).max);
    }
    
    function test_deposit_mintsShares() public {
        vm.prank(alice);
        uint256 shares = vault.deposit(100e18);
        
        assertEq(shares, 100e18, "First deposit: 1:1 shares");
        assertEq(vault.shares(alice), 100e18);
        assertEq(vault.totalDeposits(), 100e18);
    }
    
    function test_deposit_revertsOnZero() public {
        vm.prank(alice);
        vm.expectRevert(VaultV1.ZeroAmount.selector);
        vault.deposit(0);
    }
    
    // Fuzz test: any deposit amount preserves invariants
    function testFuzz_deposit_invariants(uint128 amount) public {
        vm.assume(amount > 0 && amount <= token.balanceOf(alice));
        
        uint256 prevTotal = vault.totalDeposits();
        vm.prank(alice);
        vault.deposit(amount);
        
        assertEq(vault.totalDeposits(), prevTotal + amount);
        assertTrue(vault.totalShares() > 0);
    }
}

---

Phase 7: Deployment & Operations

Deployment Checklist

pre_deployment:
  - [ ] All tests passing (unit, integration, fork, fuzz)
  - [ ] Static analysis clean (no high/critical findings)
  - [ ] Audit complete, all findings addressed
  - [ ] Deployment scripts tested on testnet (exact same flow)
  - [ ] Multisig wallets created and configured
  - [ ] Timelock contracts deployed and tested
  - [ ] Constructor arguments verified
  - [ ] Gas estimates confirmed within budget
  
deployment:
  - [ ] Deploy to mainnet from hardened machine
  - [ ] Verify source on block explorer (Etherscan)
  - [ ] Transfer ownership to multisig/timelock
  - [ ] Renounce deployer privileges
  - [ ] Test all functions with small amounts
  - [ ] Set initial parameters (fees, limits, oracles)
  
post_deployment:
  - [ ] Bug bounty program live (Immunefi)
  - [ ] Monitoring dashboards deployed
  - [ ] Alert rules configured
  - [ ] Documentation published
  - [ ] Community announcement

Monitoring Dashboard

smart_contract_monitoring:
  on_chain:
    - metric: "TVL (Total Value Locked)"
      alert: "Drop >10% in 1 hour"
      severity: "P0"
    - metric: "Unique active users (daily)"
      alert: "Drop >50% vs 7-day avg"
      severity: "P1"
    - metric: "Gas costs per transaction"
      alert: "Spike >3x average"
      severity: "P2"
    - metric: "Admin function calls"
      alert: "ANY unexpected admin call"
      severity: "P0"
    - metric: "Large withdrawals"
      alert: ">5% of TVL in single tx"
      severity: "P1"
      
  oracle:
    - metric: "Price feed freshness"
      alert: "Stale >30 minutes"
      severity: "P0"
    - metric: "Price deviation vs CEX"
      alert: ">2% deviation"
      severity: "P1"
      
  infrastructure:
    - metric: "RPC node health"
      alert: "Latency >500ms or errors"
      severity: "P1"
    - metric: "Indexer sync status"
      alert: ">100 blocks behind"
      severity: "P1"

Incident Response

| Severity | Response Time | Actions | |----------|-------------|---------| | P0 — Active exploit | < 5 min | Pause contracts, war room, post-mortem | | P1 — Vulnerability found | < 1 hour | Assess impact, prepare fix, notify team | | P2 — Degraded service | < 4 hours | Investigate, fix, monitor | | P3 — Minor issue | < 24 hours | Schedule fix in next deployment |

P0 Emergency Protocol:

1. Activate circuit breaker / pause contracts
2. Assess: What was exploited? What's the exposure?
3. Communicate: Alert team + trusted security researchers
4. Contain: Block exploit path if possible
5. Recover: Plan rescue transaction if funds recoverable
6. Post-mortem: Full timeline, root cause, fix, prevention

---

Phase 8: Wallet & Key Management

Key Hierarchy

Seed Phrase (BIP-39)
  └── Master Key
      ├── m/44'/60'/0'/0/0  → Ethereum Account 0
      ├── m/44'/60'/0'/0/1  → Ethereum Account 1
      ├── m/44'/0'/0'/0/0   → Bitcoin Account 0
      └── m/84'/0'/0'/0/0   → Bitcoin SegWit Account 0

Wallet Security Tiers

| Tier | Type | Use Case | Security Level | |------|------|----------|---------------| | Hot wallet | Browser extension (MetaMask) | Daily interactions, small amounts | Low | | Warm wallet | Mobile wallet (Rainbow, Trust) | Medium amounts, on-the-go | Medium | | Cold wallet | Hardware (Ledger, Trezor) | Large holdings, long-term | High | | Air-gapped | Keystone, dedicated offline | Maximum security, institutional | Very High | | Multisig | Safe (Gnosis) | Treasury, protocol admin | Highest |

Multisig Best Practices

multisig_config:
  protocol_treasury:
    signers: 5
    threshold: 3  # 3-of-5
    signer_diversity:
      - Different devices/locations
      - Different key types (hardware + mobile)
      - No single point of failure
    timelock: "48 hours for >$100K"
    
  operational:
    signers: 3
    threshold: 2  # 2-of-3
    use_case: "Day-to-day parameter changes"
    timelock: "24 hours"

Self-Custody Security Rules

1. Seed phrase storage — Metal plate (Cryptosteel/Billfodl), never digital
2. Geographic distribution — Copies in ≥2 physical locations
3. Test recovery — Verify you can restore from seed BEFORE storing value
4. Phishing defense — Bookmark official URLs, never click links, verify contract addresses
5. Hardware wallet firmware — Update only from official sources
6. Transaction simulation — Use Tenderly/Fire before signing large transactions
7. Approval hygiene — Revoke unused token approvals regularly (revoke.cash)

---

Phase 9: Layer 2 & Scaling

L2 Architecture Types

| Type | How It Works | Data Availability | Examples | |------|-------------|-------------------|----------| | Optimistic Rollup | Assume valid, challenge period | On-chain calldata | Arbitrum, Optimism, Base | | ZK Rollup | Prove validity with ZK proof | On-chain calldata | zkSync, StarkNet, Scroll | | Validium | ZK proof + off-chain data | Off-chain (DAC) | Immutable X | | Plasma | Exit game mechanism | Off-chain | (largely deprecated) | | State Channel | Off-chain with on-chain settlement | Off-chain | Lightning Network | | Sidechain | Independent chain with bridge | Own consensus | Polygon PoS |

Cross-Chain Bridge Security

Bridges are the #1 attack vector in crypto (>$2.5B lost).

Bridge security checklist:

• [ ] Multisig or decentralized validator set (not single key)
• [ ] Rate limiting on bridge transfers
• [ ] Monitoring for unusual withdrawal patterns
• [ ] Emergency pause functionality
• [ ] Regular security audits
• [ ] Insurance fund for bridge exploits

Safer bridging approaches:

1. Native bridges (Arbitrum/Optimism canonical) → Slow but trustless
2. LayerZero/Axelar → Decentralized messaging
3. Circle CCTP → Native USDC bridging (no wrapped tokens)
4. Avoid: New/unaudited bridges, single-key admin bridges

---

Phase 10: Regulatory & Compliance

Regulatory Landscape (2025)

| Jurisdiction | Framework | Token Classification | Key Requirement | |-------------|-----------|---------------------|----------------| | US (SEC) | Howey Test | Security vs Utility | Registration or exemption | | US (CFTC) | CEA | Commodity (BTC, ETH) | Derivatives regulation | | EU (MiCA) | Markets in Crypto-Assets | Utility/E-Money/ART | Licensing, reserves | | UK (FCA) | Financial Promotions | Crypto-asset | Marketing restrictions | | Singapore (MAS) | Payment Services Act | Digital Payment Token | Licensing | | Japan (FSA) | FIEA/PSA | Crypto-asset | Registration |

Compliance Checklist

compliance:
  token_classification:
    - [ ] Legal opinion on token classification (security vs utility)
    - [ ] Howey test analysis documented
    - [ ] Jurisdictional analysis complete
    
  aml_kyc:
    - [ ] KYC/AML provider integrated (if applicable)
    - [ ] Sanctions screening (OFAC, EU, UN)
    - [ ] Transaction monitoring for suspicious activity
    - [ ] SAR (Suspicious Activity Report) filing process
    
  mca_eu:
    - [ ] Whitepaper published (if issuing tokens)
    - [ ] Notification to competent authority
    - [ ] Reserve requirements (for stablecoins)
    
  tax:
    - [ ] Tax treatment documented per jurisdiction
    - [ ] Reporting infrastructure (1099/DAC8)
    - [ ] Cost basis tracking for users

Decentralization as Compliance Strategy

The more decentralized a protocol, the stronger the argument it's not a security:

| Factor | Centralized (Risky) | Decentralized (Safer) | |--------|-------------------|---------------------| | Development | Single company | Multiple contributor orgs | | Governance | Admin key | Token-weighted DAO | | Treasury | Company-controlled | Community-governed | | Revenue | Flows to team | Flows to token holders | | Upgrades | Admin deploys | Governance proposal + timelock | | Front-end | Single website | Multiple alternative UIs |

---

Phase 11: Bitcoin & Lightning Network

Bitcoin Development

| Layer | Purpose | Key Technologies | |-------|---------|-----------------| | L1 (Base) | Settlement, store of value | Script, Taproot, SegWit | | Lightning | Instant micropayments | Payment channels, HTLCs | | Ordinals/BRC-20 | NFTs, tokens on Bitcoin | Inscription, witness data | | Stacks/Liquid | Smart contracts on Bitcoin | Clarity, Federated sidechain |

Lightning Network Integration

lightning_integration:
  use_cases:
    - Micropayments (<$1)
    - Point-of-sale payments
    - Streaming payments (per-second)
    - Machine-to-machine payments
    - Tipping / donations
    
  implementation:
    self_hosted:
      options: ["LND", "CLN (Core Lightning)", "Eclair"]
      requirements: "Bitcoin full node + Lightning node"
      complexity: "High"
      
    hosted_api:
      options: ["Strike API", "Voltage", "LNbits", "BTCPay Server"]
      requirements: "API key"
      complexity: "Low-Medium"
      
    standards:
      invoices: "BOLT11 (payment request)"
      keysend: "Spontaneous payments (no invoice)"
      lnurl: "User-friendly payment flows"
      bolt12: "Reusable offers (emerging)"

Bitcoin Self-Custody Best Practices

1. UTXO management — Consolidate during low-fee periods
2. Address reuse — Never reuse addresses (privacy)
3. Coin selection — Use coin control for privacy-sensitive transactions
4. Fee estimation — Use mempool.space for current fee rates
5. Multi-sig — 2-of-3 for significant holdings (Sparrow, Nunchuk)
6. Verify receive addresses — On hardware wallet screen, not just software

---

Phase 12: Advanced Patterns

MEV (Maximal Extractable Value)

mev_awareness:
  what: "Value extracted by block producers reordering/inserting transactions"
  
  types:
    - sandwich_attack: "Front-run + back-run user's swap"
    - arbitrage: "Cross-DEX price differences"  
    - liquidation: "Race to liquidate undercollateralized positions"
    - jit_liquidity: "Just-in-time LP provision around large swaps"
    
  protection:
    users:
      - "Use private mempools (Flashbots Protect, MEV Blocker)"
      - "Set tight slippage limits"
      - "Use DEX aggregators with MEV protection (CoW Swap)"
      - "Submit transactions through RPC endpoints with MEV protection"
    developers:
      - "Commit-reveal schemes for sensitive operations"
      - "Batch auctions instead of continuous swaps"
      - "Deadline parameters on all swap functions"
      - "Internal oracle (TWAP) instead of spot price"

Account Abstraction (ERC-4337)

account_abstraction:
  what: "Smart contract wallets as first-class citizens"
  
  benefits:
    - Social recovery (friends can help recover account)
    - Gas sponsorship (app pays gas for users)
    - Batch transactions (multiple actions in one click)
    - Session keys (limited permissions for games/dApps)
    - Any token for gas (pay gas in USDC)
    
  implementation:
    frameworks: ["Safe{Core}", "ZeroDev", "Biconomy", "Alchemy AA"]
    bundlers: ["Pimlico", "Stackup", "Alchemy"]
    paymasters: ["Pimlico Verifying Paymaster", "Alchemy Gas Manager"]
    
  when_to_use:
    - Consumer-facing dApps (abstract wallet complexity)
    - Games (session keys, gasless)
    - B2B (multisig, spending policies)

Zero-Knowledge Applications

| Application | What ZK Proves | Example | |-------------|---------------|---------| | Privacy transactions | "I have enough funds" without revealing amount | Tornado Cash, Zcash | | Identity | "I'm over 18" without revealing age | Polygon ID, Worldcoin | | Scaling (zkRollup) | "These transactions are valid" without re-executing | zkSync, StarkNet | | Voting | "I voted" without revealing choice | MACI | | Compliance | "I passed KYC" without sharing data | zkKYC |

Gas Optimization Techniques

| Technique | Gas Saved | Complexity | |-----------|-----------|-----------| | Use calldata instead of memory for read-only params | ~60 per 32 bytes | Low | | Pack storage variables (<256 bit types together) | ~20,000 per slot | Low | | Use immutable / constant | ~2,100 per SLOAD avoided | Low | | Custom errors vs require strings | ~50 per error | Low | | Unchecked math (when overflow impossible) | ~80 per operation | Medium | | Batch operations | Varies (amortize base cost) | Medium | | Assembly for hot paths | 20-50% on targeted code | High | | Minimal proxy (EIP-1167) for clones | ~90% deployment cost | Medium |

---

Quality Rubric (0-100)

| Dimension | Weight | Score Guide | |-----------|--------|-------------| | Security | 25% | 0: No audit, known vulns. 50: Basic testing. 100: Full audit, bug bounty, formal verification | | Architecture | 15% | 0: Monolithic, no separation. 50: Some patterns. 100: Clean separation, upgrade path, gas-optimized | | Testing | 15% | 0: No tests. 50: Unit tests. 100: Full pyramid (unit/integration/fork/fuzz/invariant) | | Tokenomics | 10% | 0: Ponzi mechanics. 50: Basic utility. 100: Sustainable value accrual, aligned incentives | | Documentation | 10% | 0: No docs. 50: Basic README. 100: NatSpec, architecture docs, user guides | | Operations | 10% | 0: No monitoring. 50: Basic alerts. 100: Full dashboard, incident playbooks, SLOs | | Compliance | 10% | 0: Unaddressed. 50: Basic legal opinion. 100: Multi-jurisdictional analysis, KYC/AML | | Decentralization | 5% | 0: Single admin key. 50: Multisig. 100: DAO governance, timelock, multiple UIs |

Grade: 80+ Excellent | 60-79 Good | 40-59 Needs Work | <40 Critical Risk

---

Common Mistakes

| # | Mistake | Fix | |---|---------|-----| | 1 | Shipping without audit | Budget for audit from day 1 | | 2 | Single admin key | Multisig + timelock always | | 3 | Using spot price as oracle | TWAP or Chainlink | | 4 | Ignoring MEV | Private mempool + slippage protection | | 5 | No emergency pause | Circuit breaker on every protocol | | 6 | Testing only happy path | Fuzz testing + invariant tests | | 7 | Unlimited token approvals | Approve exact amounts needed | | 8 | Ignoring gas optimization | Profile gas costs, optimize hot paths | | 9 | No upgrade plan OR reckless upgrades | Decide upgrade strategy early | | 10 | Building blockchain when database works | Run the Database Test first |

---

Edge Cases

Startup / Hackathon:

• Use Foundry + OpenZeppelin for speed
• Deploy to Base (low gas, large ecosystem)
• Skip formal verification (do it pre-mainnet)
• Focus: working product > perfect security

Enterprise / Institutional:

• Hyperledger Besu or Avalanche Subnets for permissioned needs
• Formal verification for critical paths
• Multi-jurisdictional compliance from day 1
• Hardware security modules (HSMs) for key management

High-Value DeFi (>$100M TVL):

• Multiple independent audits (minimum 2 firms)
• Formal verification (Certora)
• $1M+ bug bounty on Immunefi
• Real-time monitoring with automatic pause triggers
• Insurance coverage (Nexus Mutual, InsurAce)

NFT / Gaming:

• ERC-1155 for gas efficiency (batch operations)
• Off-chain metadata (IPFS/Arweave for permanence)
• Account abstraction for onboarding (gasless minting)
• Consider L2 (Immutable X, Base, Polygon) for low gas

Cross-Chain:

• Start with one chain, expand after PMF
• Use canonical bridges (slow but safe) over third-party
• Implement chain-specific parameter tuning
• Monitor bridge TVL and security track record

---

Natural Language Commands

When prompted, this skill responds to:

1. evaluate blockchain fit — Run the Database Test decision framework
2. design smart contract — Generate architecture brief + coding standards
3. design tokenomics — Create token economics framework with distribution
4. audit security — Run full security checklist against a contract
5. plan deployment — Generate deployment + post-deployment checklist
6. assess DeFi protocol — Evaluate DeFi design against security invariants
7. optimize gas — Review code for gas optimization opportunities
8. review wallet security — Generate wallet + key management recommendations
9. evaluate L2 — Compare Layer 2 options for specific use case
10. check compliance — Run regulatory compliance checklist
11. design bridge strategy — Evaluate cross-chain approach
12. full web3 review — Complete assessment across all dimensions