REAL_VS_SIMULATED.md

# 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.