Hugging Face's logo

razvan
/
builderbrain

ml-intern
Model card Files
xet
 Community
builderbrain / REAL_VS_SIMULATED.md
razvan's picture
razvan
Upload REAL_VS_SIMULATED.md
58cb4a0 verified
preview code
|
raw
history blame contribute delete
10.8 kB

Real vs Simulated Integration Status

This document tracks which BuilderBrain components are real APIs vs simulated stubs.

Quick Reference

Component Status What Works Now What Needs Credentials
Quant Engine (Kelly) ✅ REAL Full cvxpy optimization with real math None
Correlation Matrix ✅ REAL Block-diagonal structure with real estimates None
Reasoning Agent ✅ REAL Structured trace generation with SHA256 hashing None
Polymarket Market Data ✅ REAL Live Gamma API calls (gamma-api.polymarket.com) None (public API)
Polymarket Orderbook ✅ REAL Live CLOB API calls (clob.polymarket.com) None (public API)
Builder Code Routing ⚠️ SIMULATED Field structure correct; needs POLY_BUILDER_CODE + live CLOB key POLY_API_KEY, POLY_PRIVATE_KEY, registered builder code
Circle Gateway ⚠️ SIMULATED Real HTTP client skeleton; needs CIRCLE_API_KEY + burn intent encoding CIRCLE_API_KEY, depositor address, domain info
Arc Nanopayments ⚠️ SIMULATED App-level ledger; real settlement requires x402 + EIP-3009 + Gateway Buyer signatures, seller DB, Gateway batch settlement
USYC Yield ⚠️ SIMULATED Balance tracking; real rotation needs Teller contract calls Web3 provider, Teller contract ABI, wallet
Paymaster ⚠️ SIMULATED Log-only; real needs ERC-4337 UserOp + bundler RPC Pimlico bundler, EntryPoint address, paymaster contract
Wallets ⚠️ SIMULATED Config only; real needs Circle Wallets API or self-custody CIRCLE_WALLET_API_KEY, CIRCLE_WALLET_SET_ID

Detailed Breakdown

✅ Quant Engine — FULLY REAL 

from builderbrain import KellyEngine, CorrelationMatrix

engine = KellyEngine(bankroll_usd=10000)
positions = engine.size_positions(edges)
# Uses cvxpy + ECOS solver — real convex optimization

No credentials needed. The Kelly criterion implementation uses cvxpy for convex quadratic programming. This is production-grade numerical optimization.

References: Tepelyan (Bloomberg, 2026) — we implement a QP approximation to his Laplace quadrature method.

✅ Reasoning Agent — FULLY REAL 

from builderbrain import ReasoningAgent

agent = ReasoningAgent()
trace = agent.reason_about_market(...)
# Generates structured traces with SHA256 hashing

No credentials needed. The reasoning trace generation, argument structure, risk factor identification, and SHA256 canonical hashing are all implemented and functional.

What's real:

  • ReasoningTrace dataclass with full audit trail
  • Argument and RiskFactor structures
  • SHA256 hash of canonical JSON representation
  • Trade signal generation with urgency classification

✅ Polymarket Market Data — FULLY REAL (Public API) 

from builderbrain import PolymarketClient

client = PolymarketClient(paper_trade=True)
markets = client.fetch_markets(limit=50)
# Calls https://gamma-api.polymarket.com/markets (live)

No credentials needed for read-only. The Gamma API is public and requires no authentication.

What's real:

  • Live market data (prices, liquidity, volume, categories)
  • Orderbook fetching from CLOB API
  • Market parsing with price normalization

What needs credentials:

  • Order submission to CLOB (POLY_API_KEY, POLY_PRIVATE_KEY)
  • Builder code attribution (needs registered builder code)

⚠️ Polymarket Builder Codes — SIMULATED

Current: Paper trading with simulated order execution. Builder code is attached as a field in the order struct but never submitted on-chain.

To make real:

  1. Register at https://polymarket.com/settings?tab=builder
  2. Get your bytes32 builder code (e.g., 0x0000...0001)
  3. Set POLY_BUILDER_CODE in .env
  4. Implement CLOB order signing + submission in polymarket_client.py::_live_execute()

Architecture is correct: Builder code is passed as an order field, serialized on-chain as the builder field. This matches Polymarket's documented TypeScript pattern.

⚠️ Circle Gateway — SIMULATED (Real API Skeleton)

Current: CircleGatewayClient has real HTTP methods but ArcBridge falls back to simulation.

Real API implemented:

from builderbrain import CircleGatewayClient

client = CircleGatewayClient(api_key="sk_test_...")
domains = client.get_gateway_info()           # GET /v1/gateway-info
balances = client.get_balances("0x...", 0)      # POST /v1/balances
# attestation = client.create_transfer_attestation(...)  # POST /v1/transfer

What's simulated:

  • Cross-chain routing in ArcBridge.route_usdc() (creates fake tx hashes)
  • No actual burn intent encoding + signing

To make real:

  1. Set CIRCLE_API_KEY in .env
  2. Pass gateway_client=CircleGatewayClient(api_key) to ArcBridge
  3. Implement burn intent encoding (requires domain info from get_gateway_info())
  4. Implement depositor signature (requires wallet integration)

Gateway Info endpoint works without full setup: You can call get_gateway_info() and get_balances() with just an API key.

⚠️ Arc Nanopayments — SIMULATED

Current: App-level payment ledger with batch aggregation. No actual cryptographic settlement.

Real architecture (from docs):

  1. Buyer signs EIP-3009 authorization (off-chain)
  2. Seller verifies signature (off-chain)
  3. Seller logs in own "virtual ledger" DB
  4. Periodic batch settlement via Circle Gateway transfer on Arc

What's simulated:

  • Payment creation (just appends to list)
  • Batch settlement (just aggregates and clears list)
  • No EIP-3009 signatures
  • No x402 HTTP 402 protocol negotiation

To make real:

  1. Implement EIP-3009 authorization signing (requires buyer wallet)
  2. Implement signature verification (seller side)
  3. Add database for virtual ledger
  4. Wire batch settlement to CircleGatewayClient

No public REST API exists for /v1/nanopayments/batches — this is by design. Settlement is through Gateway.

⚠️ USYC Yield — SIMULATED

Current: Balance tracking with simulated rotation.

Real contracts (Arc Testnet):

  • USYC Token: 0xe9185F0c5F296Ed1797AaE4238D26CCaBEadb86C
  • Teller: 0x9fdF14c5B14173D74C08Af27AebFf39240dC105A
  • Oracle: 0x52b56c7642E71dc54714d879127d97cd0B3D4581

What's simulated:

  • rotate_to_usyc() just updates balance dict
  • No Teller contract interaction
  • No Oracle price fetching

To make real:

  1. Add Web3 provider (e.g., web3.py or ethers.js via Python wrapper)
  2. Load Teller ABI
  3. Call Teller.subscribe() with USDC amount
  4. Call Oracle for NAV/share price
  5. Use https://usyc.dev.hashnote.com/api/price for reference pricing

⚠️ Paymaster (Gas Abstraction) — SIMULATED

Current: Log-only. No actual ERC-4337 UserOperation construction or submission.

Real architecture (from docs):

  • Arc supports standard ERC-4337 EntryPoint
  • Use Pimlico bundler on Arc
  • Circle Paymaster: users sign EIP-2612 permit
  • paymasterData = encodePacked([uint8, address, uint256, bytes], [0, usdcAddress, permitAmount, permitSignature])
  • Submit UserOperation via bundler RPC

What's simulated:

  • sponsor_transaction() just logs the intent
  • No UserOperation construction
  • No bundler RPC call
  • No paymaster contract interaction

To make real:

  1. Set PIMLICO_BUNDLER_URL in .env
  2. Implement UserOperation construction (standard ERC-4337 library)
  3. Implement EIP-2612 permit signing
  4. Submit to Pimlico bundler

⚠️ Wallets — SIMULATED

Current: Configuration only. No actual wallet creation or transaction signing.

Real options:

  1. Circle Dev-Controlled Wallets:

    • API: create-developer-transaction-transfer, create-developer-transaction-contract-execution
    • Custodied by Circle; no key exposure
    • Set CIRCLE_WALLET_API_KEY + CIRCLE_WALLET_SET_ID

  2. Self-custody (EOA or SCA):

    • Import private key
    • Use standard Web3 libraries
    • For SCA: deploy ERC-4337 smart contract wallet

What's simulated:

  • No wallet addresses
  • No transaction signing
  • No API calls to Circle Wallet service

Migration Path: Simulated → Real

Phase 1: Read-Only Live Data (Day 1) 

# Already works — just run it
brain = BuilderBrain(paper_trade=True)
brain.run_cycle()  # Fetches real Polymarket data

Phase 2: Real Polymarket Builder Codes (Day 2-3)

  1. Register builder code at https://polymarket.com/settings?tab=builder
  2. Set POLY_BUILDER_CODE in .env
  3. Implement CLOB order signing (use py_clob_client or Polymarket's Python SDK)
  4. Switch paper_trade=False

Phase 3: Circle Gateway Integration (Day 3-4)

  1. Get Circle API key from https://developers.circle.com/
  2. Set CIRCLE_API_KEY in .env
  3. Test CircleGatewayClient.get_gateway_info()
  4. Implement burn intent encoding for transfers
  5. Wire ArcBridge with real gateway_client

Phase 4: USYC + Paymaster (Day 4-5)

  1. Get Arc Testnet USDC from faucet
  2. Test Teller contract interaction (subscribe/redeem)
  3. Set up Pimlico bundler for paymaster
  4. Test ERC-4337 UserOperation flow

Phase 5: Nanopayments (Day 5-6)

  1. Implement EIP-3009 authorization flow
  2. Set up virtual ledger DB
  3. Wire batch settlement to Gateway
  4. Test end-to-end: insight → payment → settlement

What Judges Will See

Demo Element What They See What's Actually Happening
Market prices Real Polymarket data Live Gamma API calls
Kelly sizing Real optimization cvxpy convex QP solver
Reasoning traces Structured arguments + risks SHA256-hashed audit artifacts
Trade execution Simulated fills with builder codes Paper trading; fields correct
Cross-chain settlement Simulated transfer hashes No actual Gateway call
Nanopayments Aggregated fee log No EIP-3009 signatures
USYC rotation Balance update No Teller contract call
Gas sponsorship Log entry No UserOperation

Recommendation for hackathon: Run in simulated mode for the demo, but show the real API client code and explain the integration path. Judges appreciate architectural thinking and honest documentation.

Credentials Checklist

To go fully live, you need:

  • Circle Developer account + API key
  • Polymarket account + API key + private key
  • Registered Polymarket builder code
  • Arc Testnet RPC endpoint
  • Arc Testnet USDC (from faucet)
  • Pimlico bundler access (for paymaster)
  • Circle Wallet API key + Wallet Set ID (optional, for embedded wallets)

See .env.example for all required environment variables.