> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/normative-design/robinhood-chain.md).

# Robinhood Chain implementation

Status: read-only mainnet discovery, verified price states, public-address portfolio reads, and Arcus Robinhood Chain-rooted perpetual reads implemented. Signing and transactions are intentionally disabled.

## Product boundary

NIGHTSHIFT is a multi-venue decision OS, not a Robinhood-branded client and not an implied Robinhood partner. Arcus supplies a Robinhood Chain-rooted multi-asset perpetual rail, Hyperliquid supplies a separate crypto-perpetual rail, and Robinhood Chain supplies the EVM-compatible RWA and DeFi control plane. Robinhood Agentic Trading/MCP is a separate brokerage integration and must use a separate authorization, policy, audit, and revocation boundary if added later.

## Implemented slice

* Venue switcher and venue-aware command palette.
* Arcus mainnet online-market discovery, REST history, live WebSocket updates, L2, funding, compliance, public account state, and deposit/withdrawal reconciliation attributed to Robinhood Chain.
* Official Robinhood Chain mainnet configuration: chain ID 4663, ETH gas, Blockscout explorer and public development RPC.
* Read-only EIP-6963 multi-wallet discovery with an EIP-1193 fallback, opt-in account access, account/chain/disconnect observation, explicit chain-4663 switching and server-authoritative holdings inspection. No wallet label is trusted as identity and no signing method exists.
* Single immutable, source-attributed allowlist of all 25 canonical equity/ETF Stock Token contracts from the official registry, plus native ETH and the official WETH/USDG funding contracts. All contract-bearing venue/UI assets derive from this registry rather than duplicating identity.
* Release-time `pnpm audit:rhc-registry` proof against the exact official HTTPS contract page with a bounded response, deterministic parser and fail-closed missing/unexpected/mismatch/duplicate reporting. It never auto-accepts source drift.
* Independent 21-feed Chainlink Robinhood snapshot with primary/secondary proxy, heartbeat, decimals and exact source/review provenance. `pnpm audit:rhc-oracles` reports source drift without auto-accepting it; the four unmatched canonical assets remain identity-only.
* Server-side JSON-RPC probe for `eth_chainId` and `eth_blockNumber`; the browser never accepts an arbitrary RPC URL.
* Shared `@terminal/venues` adapter with typed asset/network/price/portfolio/simulation read models and no execution method.
* Deterministic `RHC_DATA_MODE=mock` fixtures for offline development; mock contexts are structurally `simulated` and forbidden in production.
* Live network health, block height, asset identity and contract explorer links.
* RWA-specific access gate and AI abstention copy.
* Explicit no-synthetic-price behavior.
* Reviewed Chainlink feed registry, live-versus-reviewed decimal checks, round reads, heartbeat checks and fail-closed price states.
* Sequencer uptime and grace-period gate; numeric live prices remain unavailable until the reviewed feed address is configured server-side.
* Token pause and ERC-8056 current and pending multiplier context.
* Public-address native ETH, WETH, USDG, Stock Token and ETF balance reads, including `balanceOfUI`, typed partial failure and incomplete valuation.
* Bounded RPC transport, response-size limits, circuit breaking, all-read primary-to-fallback routing, live fallback divergence checks and registry-drift tests.
* Chain-verified `newHeads` WebSocket supervision with handshake timeout, stale-head detection, bounded jittered reconnect and post-incident stabilization.
* Privacy-safe provider telemetry at `GET /api/rhc/providers`: provider class (never URL), rolling error/latency/circuit state, active role, failover, block gap, archive state, observed WSS heads and a truthful production-readiness reason.
* Durable public-wallet activity at `GET /api/rhc/activity/:address`: safe-head checkpoints, bounded canonical `eth_getLogs` chunks, independently bounded Alchemy external native-ETH transfer pages, reorg-tail replay, gap repair, retention and archive-gated pagination. Token values are raw ERC-20 units and native values are raw wei; internal ETH transfers remain explicitly unavailable.

## Target architecture

```
Terminal UI
  -> VenueRouter
       -> ArcusAdapter (public REST/WS plus disabled protected RHC perp boundary)
       -> HyperliquidAdapter (Info/WS; current)
       -> RobinhoodChainAdapter
            -> RegistryProvider (official contracts, versioned)
            -> RpcProvider (Alchemy production; public RPC development only)
            -> OracleProvider (Chainlink feeds + sequencer + heartbeat)
            -> QuoteProvider (RFQ/aggregator adapter)
            -> PortfolioIndexer (balances, transfers, ERC-8056 UI amounts)
  -> IntentService
  -> DeterministicRiskEngine
  -> ExplicitConfirmation
  -> IsolatedVenueSigner
```

The adapter contract should expose `getAssets`, `getNetworkState`, `getPriceContext`, `getPortfolio`, `simulate`, and `submitConfirmedIntent`. AI may consume normalized context and produce a typed proposal. It must never call the signer or construct executable calldata.

## API strategy

Current routes:

* `GET /api/robinhood-chain` returns a validated mainnet chain ID, latest block, gas symbol, explorer URL and redacted provider-readiness summary. Upstream errors return `503`; no cached success is presented as live indefinitely.
* `GET /api/rhc/providers` independently probes configured HTTP providers, compares chain and block state, reports rolling transport/failover/archive evidence plus supervised WSS head state, and never serializes credential-bearing endpoint URLs.
* `GET /api/rhc/assets/:symbol/price` returns reviewed oracle, sequencer, pause and ERC-8056 multiplier state.
* `GET /api/rhc/portfolio/:address` returns canonical native/token/Stock Token balances with partial-provider and valuation states.
* `GET /api/profile/portfolio?address=...` requires dual Privy tokens and restricts the same live portfolio read to an exact provider-verified linked EVM wallet; it returns strict private/no-store operation locks and grants no signing authority.
* `GET /api/rhc/activity/:address` persists and resumes canonical WETH, USDG, Stock Token and ETF transfer logs. With an Alchemy primary endpoint it also persists exact external native-ETH value transfers behind a separate checkpoint; unsupported providers expose the missing capability. `before` pagination is enabled only after redundant archive attestation.
* `GET /api/rhc/activity/health` returns aggregate checkpoint-store and retention health without wallet identifiers.
* `GET /api/nightshift/radar` returns the immutable canonical identity catalog plus separately versioned/source-attributed 21-feed oracle subset with no execution capability.

Future routes (capital-moving `POST` routes remain gated):

* `GET /api/venues` — capability and health matrix.
* `GET /api/rhc/assets` — server-owned registry snapshot with registry version and source timestamp.
* `POST /api/rhc/quotes` — typed RFQ request after eligibility; return quote expiry, route, allowance target, slippage and total cost.
* `POST /api/rhc/simulations` — execute `eth_call`/trace against the exact calldata and block context.
* `POST /api/rhc/intents/:id/confirm` — short-lived confirmation bound to wallet, chain, calldata hash, policy version and quote expiry.

Robinhood's current connection guide recommends Alchemy and also lists QuickNode, Blockdaemon, dRPC and Validation Cloud. It provides HTTP and WSS endpoint forms and says historical reads require archive access. The official public endpoint is rate-limited and not recommended for production, so NIGHTSHIFT labels it diagnostic and requires two distinct managed providers, explicit operator archive claims, fresh endpoint-bound evidence from historical state reads, observed chain-4663 `newHeads` streams and an uninterrupted stabilization window before `productionReady` can become true. Pin chain ID 4663 and reject mismatches. `docs/runbooks/rhc-provider-attestation.md` defines the credential-safe probe and refresh procedure.

## RWA risk policy

All controls are deny-by-default:

1. Jurisdiction and eligibility resolve before price/quote/trade surfaces—not only at submit.
2. Contract address matches the versioned official allowlist; symbol/name matching is insufficient.
3. Chain ID is 4663 and sequencer is up beyond the configured recovery grace period.
4. Chainlink answer is positive, heartbeat-fresh, uses reported decimals, and matches the canonical feed registry.
5. `oraclePaused()` is false; corporate-action multiplier and any scheduled update are displayed consistently.
6. RFQ or swap route is allowlisted, unexpired and within liquidity/slippage/notional limits.
7. Allowances use exact amounts and approved spenders; unlimited approvals are forbidden by default.
8. Simulation succeeds at fresh state and shows no unexpected transfers, delegate calls or token approvals.
9. User confirms the exact asset, amount, price/quote, fees, route, wallet, chain and calldata hash.
10. Session keys, if introduced via ERC-4337, are scoped by contract, method, spend, time and revocation policy.

Stock Tokens are tokenized debt securities providing economic exposure; they do not convey ownership rights in the underlying. U.S. persons are ineligible and additional jurisdictions are restricted. Product/legal review owns the eligibility matrix and disclosures.

## Delivery milestones

### RHC-0 — Observe (complete)

Canonical discovery, network health, premium multi-venue UX, read-only gating and tests.

### RHC-1 — Price and portfolio

Integrate the current Chainlink feed registry without hard-coded feed addresses. Add sequencer/heartbeat/pause/multiplier validation, wallet balance reads, ERC-8056 UI units, indexed activity, cache policy and degraded-state UX. Canonical-token and Alchemy external native-ETH value-transfer activity are implemented; internal ETH transfers remain unavailable on this L2 and complete production history still requires the configured provider/archive topology.

Exit: every displayed numeric value has source, timestamp and freshness state; unsafe price state renders unavailable.

### RHC-2 — Paper RFQ and replay (complete)

Normalize quote sources, paper-simulate Stock Token ↔ USDG intents, include market-hours/oracle state, and add post-intent replay scoring discipline rather than raw P\&L.

Exit: deterministic fixtures reproduce quotes, rejections and portfolio changes with zero signing capability.

Implemented as server-owned mock fixtures with fixed-point quote selection, fail-closed policy reasons, deterministic paper portfolio updates, and a discipline score based on decision quality, gate compliance, plan adherence and evidence completeness. The API declares `executionCapability: "none"`; no live quote provider, wallet, calldata, approval or signer was added.

### RHC-3 — Testnet wallet and account abstraction

Add wallet connection, EIP-712 intent review, transaction simulation, ERC-4337 smart accounts, narrowly scoped session keys, revocation and sponsored-gas policy on chain 46630.

Exit: threat model, dependency review, signer isolation, kill switch and 14-day testnet soak pass.

### RHC-4 — Capped mainnet canary

Enable one audited quote route for eligible users with a small notional cap, exact approvals, explicit confirmation, reconciliation and 24/7 incident response.

Exit: legal/security sign-off, live monitoring, rollback drill and zero unresolved reconciliation errors.

## Testing plan

* Unit: registry uniqueness/address format, JSON-RPC quantity parsing, chain mismatch rejection, oracle staleness/pause/multiplier rules, quote expiry and calldata hashing.
* Contract: recorded JSON-RPC and oracle fixtures, provider error/timeout/rate-limit behavior, registry drift detection.
* Integration: fork/testnet balance reads, multicall partial failure, sequencer downtime, reorg/finality, wallet chain switching and quote invalidation.
* Security: malicious token metadata, lookalike contracts, arbitrary RPC/URL injection, approval escalation, signature replay, session-key scope escape and poisoned AI context.
* UX/accessibility: keyboard venue switching/search, screen-reader status announcements, narrow screens, reduced motion and all degraded/blocked states.
* Soak: reconnects and polling across provider incidents; compare block/oracle state across two providers; alert on divergence.

## Retention without dark patterns

Build return loops around competence: “what changed” briefs, paper missions, post-trade replay, a discipline score, strategy version history and shareable evidence cards. Reward correct abstention, plan adherence, loss-limit compliance and journaling. Never reward trade count, leverage, deposits, loss-chasing or randomized financial actions.

## Primary references

* <https://docs.robinhood.com/chain/>
* <https://docs.robinhood.com/chain/connecting/>
* <https://docs.robinhood.com/chain/run-a-full-node/>
* <https://docs.robinhood.com/chain/contracts/>
* <https://docs.robinhood.com/chain/oracles-and-price-feeds/>
* <https://docs.robinhood.com/chain/building-with-stock-tokens/>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/normative-design/robinhood-chain.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.