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

Minimize on-chain state — Storage is expensive. Put data on-chain only if it needs consensus
Fail loudly — Use require() / revert() with descriptive messages, never silent failures
Immutability by default — Upgradeability adds attack surface. Only use if genuinely needed
Separation of concerns — One contract per responsibility
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:

Solvency — Total assets ≥ total liabilities (always)
No free tokens — No path creates tokens from nothing
Monotonic shares — Depositing increases shares, withdrawing decreases
Oracle freshness — Price data is within acceptable staleness window
Liquidation viability — Undercollateralized positions can always be liquidated
Access control — Admin functions behind timelock + multisig
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

Seed phrase storage — Metal plate (Cryptosteel/Billfodl), never digital
Geographic distribution — Copies in ≥2 physical locations
Test recovery — Verify you can restore from seed BEFORE storing value
Phishing defense — Bookmark official URLs, never click links, verify contract addresses
Hardware wallet firmware — Update only from official sources
Transaction simulation — Use Tenderly/Fire before signing large transactions
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

UTXO management — Consolidate during low-fee periods
Address reuse — Never reuse addresses (privacy)
Coin selection — Use coin control for privacy-sensitive transactions
Fee estimation — Use mempool.space for current fee rates
Multi-sig — 2-of-3 for significant holdings (Sparrow, Nunchuk)
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:

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