Skip to content

AUDIT.md

Latest commit

 

History

History
70 lines (56 loc) · 4.34 KB

AUDIT.md

File metadata and controls

70 lines (56 loc) · 4.34 KB

BidKit Production Readiness Audit

Audit date: 2026-04-13 Scope: All source files in src/ (excluding src/demo/)

Issues Found and Fixed

Hardcoded Addresses (8 found, 8 fixed)

  • USDC address 0xA0b86991... appeared in 4 files (strategy-engine, exit-executor, lp-manager, post-auction/index). Replaced with chain-aware USDC_ADDRESSES[chainId] lookup from config.
  • Zero address 0x000... appeared in 4 files (config, discovery/index, bidding/index, post-auction/index). Replaced with ADDRESS_ZERO constant.
  • Comparable engine token addresses remain as a configurable default list with knownTokens parameter override.

Hardcoded Chain IDs (4 found, 4 fixed)

  • Raw 1 for Ethereum mainnet in cca-client.ts (2 occurrences), discovery/index.ts, bidding/index.ts.
  • Added CHAIN_IDS constant: { ETHEREUM: 1, ARBITRUM: 42161, XLAYER: 196, BASE: 8453 }.

Hardcoded API Paths (7 found, 7 fixed)

  • All OKX API endpoint paths in okx-client.ts moved to OKX_ENDPOINTS constant in config.ts.

Magic Numbers (60+ found, 60+ fixed)

  • Scoring weights (discovery/index.ts): extracted to SCORING_WEIGHTS.
  • Fair value weights (fair-value.ts): 30+ magic numbers extracted to FAIR_VALUE_WEIGHTS, TRAJECTORY_MULTIPLIERS, SIGNAL_MULTIPLIERS, SECURITY_RANGE, CONFIDENCE_WEIGHTS, BID_STRATEGIES.
  • Rate limiting (okx-client.ts): 334ms → OKX_RATE_LIMIT_MS.
  • Cache TTLs (okx-client.ts): 30_000/300_000 → CACHE_TTL.MARKET/CACHE_TTL.SECURITY.
  • Block time (discovery/index.ts): 12 → AVG_BLOCK_TIME[chainId] (chain-aware).
  • Signal lookback (signal-analyzer.ts): 7-day window → SIGNAL_LOOKBACK_MS.
  • Max signals (signal-analyzer.ts): 20 → MAX_SIGNALS.
  • Trajectory threshold (cca-state-reader.ts): 100 → TRAJECTORY_BLOCKS_THRESHOLD.
  • Lookback blocks (auction-scanner.ts): 50_000n → AUCTION_LOOKBACK_BLOCKS.
  • Caution score (security-filter.ts): 30 → DEFAULT_CAUTION_SCORE.
  • Hold threshold (strategy-engine.ts): 90n → HOLD_THRESHOLD_PCT.
  • Max comparables (comparable-engine.ts): 5 → MAX_COMPARABLES.

Logic Bugs Fixed (2)

  • medianMarketCap (fair-value.ts): was computing median of bottom 3 by market cap instead of true median. Fixed to sort descending and compute correct median over full array.
  • blocksRemaining (discovery/index.ts): was using totalBlocks (full duration) instead of blocks remaining. Renamed to estimatedBlocksRemaining with clear documentation.

Stub Documentation (6 stubs improved)

All simulation-mode stubs now log "Simulation mode: ..." messages:

  • bid-submitter.ts: "Simulation mode: bid recorded without on-chain submission"
  • claim-manager.ts: "Simulation mode: claim recorded without on-chain execution"
  • swap-executor.ts: "Simulation mode: swap recorded without on-chain execution"
  • x402-server.ts: "Simulation mode: payment validation bypassed"

Configuration Improvements

  • USDC_ADDRESSES per-chain lookup (Ethereum, Arbitrum, Base).
  • AVG_BLOCK_TIME per-chain (Ethereum 12s, Arbitrum 0.25s).
  • OKX_DEFAULT_BASE_URL constant.
  • Comparable engine accepts optional custom token list parameter.
  • All new constants exported from src/config.ts for user override.

Remaining Known Limitations (Hackathon Scope)

These are intentional for hackathon scope and documented with TODO comments:

  1. Bid submission — Simulated, not broadcast on-chain. Production: use wallet client + tx confirmation.
  2. Token claiming — Simulated. Production: check claimBlock, call claim(), parse TokensClaimed event.
  3. Swap execution — Simulated. Production: build Universal Router calldata or use OKX DEX aggregator.
  4. LP provision — Returns deep link only. Production: execute via Uniswap V4 position manager.
  5. x402 payment validation — Stub. Production: verify payment on X Layer.
  6. Pool security validation — Address format check only. Production: use v4-security-foundations skill.
  7. Comparable token data — Uses static reference list. Production: fetch live rankings from OKX API.
  8. Price trajectory — Simplified heuristic. Production: compare clearing prices across historical blocks.

Verification

  • pnpm lint — zero TypeScript errors
  • pnpm test — 50/50 tests passing
  • pnpm build — clean ESM + CJS + DTS output
  • pnpm demo — demo mode runs with realistic mock data