docs (flashblocks): add overview, architecture, websocket-reference page, update content, improve readability/organization

docs/base-chain/flashblocks/apps.mdx

@@ -1,10 +1,10 @@
 ---
-title: Flashblocks
+title: Flashblocks Integration
 sidebarTitle: Apps
-description: Experience lightning-fast transaction confirmations of Base by using Flashblocks. Preconfirmations happen in just 200 milliseconds—designed for real-time apps, games, and seamless UX.
+description: Integrate Flashblocks into your app for 200ms transaction confirmations using RPC APIs and popular libraries like Ethers, Wagmi and Viem.
 ---
 
-## Overview
+Get **200ms transaction confirmations** on Base—10x faster than the standard 2-second block time.
 
 Flashblocks enable up to 200 millisecond transaction confirmations on Base by leveraging preconfirmations, ultra-fast signals that arrive before the next block is sealed. Built for developers who demand instant UX, it's ideal for high-frequency apps, games, and real-time interactions where waiting even a few seconds is too long. By integrating directly within Base's infrastructure, Flashblocks enables seamless, ultrafast and snappy user experiences without compromising security.
 

docs/base-chain/flashblocks/architecture.mdx

@@ -0,0 +1,39 @@
+---
+title: Flashblocks Architecture
+sidebarTitle: Architecture
+description: Understand the sequencer architecture and infrastructure components that power Flashblocks on Base.
+---
+
+## Before Flashblocks
+
+Base operates a high-availability sequencer system with five sequencer instances:
+
+| Component | Role |
+|-----------|------|
+| **op-node** | Standard OP Stack consensus layer (CL) |
+| **op-geth** | Standard OP Stack execution layer (EL) |
+| **op-conductor** | High availability controller with Raft consensus for leader election |
+
+One sequencer instance acts as the **leader**, responsible for building blocks and propagating them via P2P. The remaining four act as **followers** that sync the chain. Leadership transfers if the current leader stops producing blocks.
+
+## With Flashblocks
+
+Flashblocks introduce several new infrastructure components:
+
+| Component | Purpose | What It Unlocks |
+|-----------|---------|-----------------|
+| **rollup-boost** | CL↔EL Engine API proxy | Enables sharing Flashblocks with the EL without modifying the CL. Provides a stable seam for future block-building evolutions (multi-builder, etc.) |
+| **op-rbuilder** | Out-of-protocol builder at 200ms cadence | Produces the sub-second Flashblocks, decoupled from the EL. Enables pluggable builder mechanisms |
+| **websocket-proxy** | Flashblocks stream fan-out | Broadcast layer so many consumers can read the stream without overwhelming the builder |
+| **[base](http://github.com/base/base)** | RPC surface exposing preconfirmations | Converts streamed Flashblocks into familiar RPCs so apps and wallets can consume preconfirmation state |
+
+Both [rollup-boost](http://github.com/flashbots/rollup-boost) and [op-rbuilder](http://github.com/flashbots/op-rbuilder) are built and maintained by Flashbots, while Base maintains the websocket-proxy and [base](http://github.com/base/base) components.
+
+---
+
+## Further Reading
+
+- [Flashblocks Overview](/base-chain/flashblocks/overview) — Key concepts and transaction lifecycle
+- [Enable Flashblocks](/base-chain/node-operators/run-a-base-node#enable-flashblocks) — Run your own Flashblocks-aware RPC node
+- [WebSocket Reference](/base-chain/flashblocks/websocket-reference) — Technical reference for infrastructure-to-node data syncing
+- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details

docs/base-chain/flashblocks/faq.mdx

@@ -0,0 +1,143 @@
+---
+title: Flashblocks FAQ
+sidebarTitle: FAQ
+description: Frequently asked questions about Flashblocks, including block building, WebSocket data, RPC usage, and node setup.
+---
+
+<Info>
+For a comprehensive introduction to how Flashblocks work, see the [Flashblocks Overview](/base-chain/flashblocks/overview).
+</Info>
+
+## Block Building
+
+<AccordionGroup>
+  <Accordion title="Are Flashblocks optional?">
+    All Base blocks are built by the Flashblocks builder, meaning **Flashblocks are always live**. However, apps may choose not to rely on preconfirmations and can continue using standard RPCs without any Flashblocks integration.
+  </Accordion>
+
+  <Accordion title="Is there any difference in transaction inclusion for Flashblocks vs. 2-second blocks?">
+    No significant differences—both order transactions by fee. The main difference is timing: Flashblocks occur every 200ms instead of every 2 seconds. 
+
+    See [Block Building](/base-chain/network-information/block-building#flashblocks) for details.
+  </Accordion>
+
+  <Accordion title="Can the sequencer stop publishing Flashblocks?">
+    The sequencer will not stop publishing Flashblocks unless an extreme circumstance makes running them unsafe. If this happens, preconfirmations are disabled network-wide and confirmations fall back to standard 2-second blocks. The sequencer continues operating normally.
+  </Accordion>
+
+  <Accordion title="Why is my transaction having trouble getting included?">
+    Transactions with large gas limits (> ~18.75M gas, which is 1/10 of the ~187.5M block limit) may have longer inclusion times. This is because the builder allocates gas cumulatively—each Flashblock `j` can use up to `j/10` of the total block gas limit. Large transactions can be included once enough cumulative capacity exists.
+
+    See [Gas Allocation](/base-chain/flashblocks/overview#gas-allocation) for the full breakdown.
+  </Accordion>
+
+  <Accordion title="How do I ensure my transaction is in the first Flashblock?">
+    There's no way to guarantee which Flashblock a transaction lands in, similar to how you can't guarantee a specific block. To improve chances of quick inclusion:
+
+    - Set a higher priority fee
+    - Keep gas limits below ~18.75M (1/10 of block limit) to be eligible for Flashblock 1
+  </Accordion>
+
+  <Accordion title="Why do transactions sometimes appear out of order by fee?">
+    The Flashblock builder uses a **dynamic mempool** that continuously accepts new transactions while building. This design prioritizes **low inclusion latency** over strict fee ordering.
+
+    **What this means:**
+    - Transactions are ordered by fee *at the time they're selected* for inclusion
+    - If a high-fee transaction arrives after a lower-fee transaction has already been committed to the current Flashblock, the high-fee transaction will appear after it (or in the next Flashblock)
+    - This is expected behavior, not a bug—the builder doesn't "reorder" already-committed transactions
+
+    **Why this tradeoff?**
+
+    A "snapshot" mempool (freezing the transaction pool at the start of each block) would guarantee strict fee ordering but increase inclusion latency. The dynamic approach gets transactions included faster at the cost of occasionally "breaking" the expected priority gas auction (PGA) order.
+
+    **For traders and bots:** If strict fee-based ordering is critical for your use case, be aware that arrival timing matters as much as fee amount within a 200ms Flashblock window.
+  </Accordion>
+
+  <Accordion title="How frequently do Flashblock reorgs happen?">
+    Base targets a Flashblock reorg rate of < 0.1%. While reorgs are rare, applications should implement fallback logic for critical operations. 
+
+    Check current metrics at [base.org/stats](https://base.org/stats).
+  </Accordion>
+
+  <Accordion title="What does it mean when a Flashblock is reorged?">
+    A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements in rollup-boost that prevent tail Flashblock reorgs. Apps should handle this possibility gracefully, but occurrences are minimal.
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## WebSocket
+
+<AccordionGroup>
+  <Accordion title="Can I connect directly to the Flashblocks WebSocket stream?">
+    **No.** The raw Flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is reserved for infrastructure-to-node data syncing. Applications should not connect to it directly.
+
+    Instead, query your RPC node or node provider (e.g., QuickNode, Alchemy, Infura, dRPC) for Flashblocks data via:
+    - **RPC API**: Standard JSON-RPC methods with the `pending` tag
+    - **WebSocket subscriptions**: Use `eth_subscribe` via your node provider's WebSocket endpoint
+
+    See [App Integration](/base-chain/flashblocks/apps) for implementation details.
+  </Accordion>
+
+  <Accordion title="Why are there 11 Flashblock indices (0-10)?">
+    Index 0 contains only system transactions and doesn't use any gas limit. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool.
+  </Accordion>
+
+  <Accordion title="Why are there sometimes fewer than 10 Flashblocks?">
+    This is expected. When the previous block takes longer to build, the system compensates by allocating less time to the next block, resulting in fewer Flashblocks.
+  </Accordion>
+
+  <Accordion title="What encoding format is the transaction data in?">
+    Transaction data in the [`diff.transactions`](/base-chain/flashblocks/websocket-reference#diff-object) array is Recursive Length Prefix (RLP) encoded.
+  </Accordion>
+
+  <Accordion title="Why am I getting rate limited on the WebSocket?">
+    The public WebSocket has a maximum connection limit. For production use, we recommend:
+
+    1. Running your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks)
+    2. Using a third-party node provider with Flashblocks support
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## RPC
+
+<AccordionGroup>
+  <Accordion title="Why am I getting rate limited using mainnet-preconf.base.org?">
+    The public endpoint has explicit rate limiting. For production use:
+
+    - Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC)
+    - Run your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks)
+  </Accordion>
+
+  <Accordion title="What RPC methods support Flashblocks?">
+    The following methods are Flashblocks-enabled:
+
+    | Method | Usage |
+    |--------|-------|
+    | `eth_getBlockByNumber` | Use `pending` tag |
+    | `eth_getBalance` | Use `pending` tag |
+    | `eth_getTransactionReceipt` | Returns preconfirmed receipts |
+    | `eth_getTransactionByHash` | Use `pending` tag |
+    | `eth_getTransactionCount` | Use `pending` tag |
+    | `eth_call` | Use `pending` tag |
+    | `eth_simulateV1` | Use `pending` tag |
+    | `eth_estimateGas` | Use `pending` tag |
+    | `eth_getLogs` | Use `pending` for `toBlock` |
+    | `eth_subscribe` | Stream Flashblock data in real-time (Beta) |
+    | `base_transactionStatus` | Check if transaction is in mempool (Beta) |
+
+    See [App Integration](/base-chain/flashblocks/apps#rpc-api-reference) for full examples.
+  </Accordion>
+</AccordionGroup>
+
+---
+
+## Node Setup
+
+<AccordionGroup>
+  <Accordion title="How do I set up a Flashblocks-aware RPC node?">
+    Use the Reth binary from the [Base node repository](http://github.com/base/node/tree/main/reth). See the [Enable Flashblocks guide](/base-chain/node-operators/run-a-base-node#enable-flashblocks) for complete setup instructions.
+  </Accordion>
+</AccordionGroup>