STOCKFACTORY DOCS

StockFactory is a workbench for building deterministic, portable equity-basket strategies from Robinhood Stock Tokens — ERC-20 wrappers of real US equities that live on Robinhood Chain (ID 4663).

Instead of clicking around a brokerage, you drop tokens onto an assembly line, set target weights, run quality control, and mint a Blueprint: a hash-stamped recipe that anyone can look up, share, or reproduce.

The whole app is intentionally shaped like a factory floor:

• Warehouse — raw parts (every listed Stock Token).
• Assembly Line — the conveyor where you build the basket.
• Quality Control — 6 stations that must clear before shipping.
• Blueprint Vault — the archive of shipped strategies.
• Control Room — live NAV + wallet-side portfolio view.

• Stock Token — ERC-20 on Robinhood Chain that represents 1:1 exposure to a listed US equity.
• Basket — an unshipped draft on the assembly line: 2–6 slots with target weights.
• Weight (bps) — target allocation in basis points. Weights must sum to 10,000.
• Blueprint — a shipped, hash-stamped recipe. Immutable; new edits create a new version.
• Recipe hash — SHA-256 over the canonical (sorted) list of symbol → weightBps.
• NAV — Net Asset Value: sum(weight × mid-price) for a blueprint, sampled every 15 min.
• QC Grade — PASS / WARN / FAIL rollup from the 6 QC stations.

The Warehouse is a live index of every Stock Token exposed by the Robinhood public REST API (/rhj/assets). Metadata includes the on-chain contract, ticker, venue (NYSE/NASDAQ), current halt status, corporate actions, and mid-price.

Prices come from /rhj/prices/{symbol} and are cached server-side inside a TanStack server function. The Warehouse is read-only — it's where you shop for parts before heading to the line.

The Assemble page is a 2–6 slot conveyor. Drop a Stock Token into a slot, dial its weight in bps, then either rebalance manually or hit Auto-Balance to distribute the remainder evenly.

Rules enforced client-side:

• Minimum 2 slots, maximum 6.
• No duplicate symbols.
• Weights must sum to exactly 10,000 bps to ship.
• No single component > 60% (concentration guard).

You also set a Paper Notional (USDG). That number is what the Route Inspector uses to simulate a real 1inch-style split across the basket.

Pressing RUN QC pushes the basket through six checks:

1. WEIGHT CHECK — sum = 10,000 bps, concentration ≤ 60%, slot count in range.
2. AUTHENTICITY — every symbol resolves to a listed Stock Token with a valid on-chain contract on chain 4663.
3. PRICE FRESHNESS — the Robinhood price snapshot for each component is under 5 minutes old.
4. CORPORATE ACTIONS — flags any component with an active halt, split, or dividend event that would break the basket.
5. ORACLE CROSS-CHECK — Robinhood mid vs Pyth mid. Divergence > 2% raises a WARN; > 5% is a FAIL.
6. ROUTE INSPECTOR — effective slippage from the Paper Routing engine must stay under the 50 bps cap.

The overall QC Grade is FAIL if any station fails, else WARN if any warns, else PASS. Only PASS or WARN blueprints can be shipped to the vault.

A Blueprint is what comes off the end of the line. It records the components, weights, QC grade, and a deterministic recipe hash.

The hash is computed as:

sha256(
  components
    .sort((a,b) => a.symbol.localeCompare(b.symbol))
    .map(c => `${c.symbol}:${c.weightBps}`)
    .join("|")
)

Order-independent: AAPL 60% / MSFT 40% hashes identically no matter what order you added them. Two people who build the same basket land on the same Blueprint ID.

Public blueprints live in the Blueprint Vault. Every version is retained in blueprint_versions so you can fork or diff over time.

Robinhood Chain doesn't have 1inch yet, so StockFactory ships a deterministic Paper Router. Given a notional and a basket, it:

1. Splits the notional per component using weight × notional.
2. Prices each leg at the Robinhood ask (buy side).
3. Applies a spread-derived slippage per leg.
4. Charges a flat 25 bps protocol fee.
5. Reports per-leg tokens out + a blended effective slippage in bps.

Halted or unpriced components short-circuit the route so QC can flag the basket instead of silently misquoting.

Every priced component is looked up on Pyth Hermes under the Equity.US.<TICKER>/USD feed. The Oracle panel on the assembly line renders Robinhood mid vs Pyth mid with a live Δ%, and the same values feed the QC station.

This catches stale Robinhood snapshots, mispriced feeds, and any drift that would make a Blueprint dangerous to manufacture at scale.

The Control Roomis the operator view once a wallet is connected. It reads your token balances on Robinhood Chain and matches them against known Stock Tokens and Blueprints.

NAV for every public Blueprint is snapshotted every 15 minutes by a cron job and stored in nav_snapshots. That's what powers the historical strip on each Blueprint card.

Wallet auth uses Reown AppKit + wagmi v2. StockFactory is wired to chain ID 4663 (Robinhood Chain). Reads only, today: no swaps, no signatures beyond wallet connect.

Anonymous sign-in on Lovable Cloud lets you save blueprints and QC runs without creating an account — link a wallet later and the history follows.

• stockfactory-nav-snapshot — every 15 min. Recomputes NAV for every public Blueprint and inserts into nav_snapshots.
• stockfactory-api-health — every 5 min. Probes the Robinhood REST endpoints, records latency + status into api_health_events, and drives the status bar in the header.

• Live 1inch quotes + execution when routing is available on chain 4663.
• FactoryBlueprintRegistry.sol — on-chain blueprint registration and manufacture receipts.
• Chainlink price feeds as a second oracle when supported on Robinhood Chain.
• Fork + diff UI for public Blueprints.
• Mobile-tuned assembly line.