afrexai-web3-engineering

name	afrexai-web3-engineering
description	Web3 & Blockchain 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: 
     
     
    
  
     
     
     

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)"]
    
  
     
     
     
    
  
     [ ]    
     [ ]    
     [ ]    
     [ ]    

---

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  
           
      
  
    
          
          
            
            
      
  
     
    
       
       
       
       
      
  
     
     [, , ]

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   
   [ ]      
   [ ]    
   [ ]   
   [ ]      
   [ ]      
  

   [ ]     
   [ ]   
   [ ]   
   [ ]  
   [ ]  

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:
      
       
       
      
       
       

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  
     [ ]    
    
  
     [ ]     
     [ ]   
     [ ]     

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", ]
    
  
         
        
        

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