Upload REAL_VS_SIMULATED.md

REAL_VS_SIMULATED.md

@@ -0,0 +1,292 @@
+# 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
+
+```python
+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
+
+```python
+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)
+
+```python
+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:**
+```python
+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)
+
+```python
+# 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.