Flashblocks for app devs and chain operators

pages/operators/chain-operators/features.mdx

@@ -31,4 +31,6 @@ This section provides information on various features for chain operators. You'l
   <Card title="Op stack preinstalls" href="/operators/chain-operators/features/preinstalls" />
 
   <Card title="Span batches" href="/operators/chain-operators/features/span-batches" />
+
+  <Card title="Flashblocks" href="/operators/chain-operators/features/flashblocks" />
 </Cards>

pages/operators/chain-operators/features/_meta.json

@@ -1,5 +1,6 @@
 {
     "preinstalls": "Preinstalls",
+    "flashblocks": "Flashblocks",
     "alt-da-mode": "Run an Alt-DA Mode chain",
     "span-batches": "Use and enable span batches on your chain",
     "bridged-usdc-standard": "Bridged USDC Standard for the OP Stack"

pages/operators/chain-operators/features/flashblocks.mdx

@@ -0,0 +1,30 @@
+---
+title: Flashblocks
+lang: en-US
+description: >-
+  Learn about Flashblocks for lightning-fast transaction confirmations on OP Stack chains.
+  This guide provides detailed information for both app developers and chain operators.
+content_type: landing-page
+topic: flashblocks
+personas:
+  - app-developer
+  - chain-operator
+  - protocol-developer
+categories:
+  - protocol
+  - block-production
+  - developer-tools
+is_imported_content: 'false'
+---
+
+import { Card, Cards } from 'nextra/components'
+
+# Flashblocks
+
+Flashblocks delivers sub-second transaction confirmations on OP Stack chains, enabling lightning-fast user experiences without compromising security. This section provides comprehensive guides for both app developers and chain operators.
+
+<Cards>
+  <Card title="Flashblocks" href="/operators/chain-operators/features/flashblocks/apps" />
+
+  <Card title="Flashblocks: A Guide for Chain Operators" href="/operators/chain-operators/features/flashblocks/chain-operators" />
+</Cards>

pages/operators/chain-operators/features/flashblocks/_meta.json

@@ -0,0 +1,4 @@
+{
+  "apps": "Apps",
+  "chain-operators": "Chain Operators"
+}

pages/operators/chain-operators/features/flashblocks/apps.mdx

@@ -0,0 +1,244 @@
+---
+title: Flashblocks
+description: Learn how to integrate Flashblocks for lightning-fast transaction confirmations on OP Stack, with pre-confirmations in just 200 milliseconds.
+lang: en-US
+content_type: guide
+topic: flashblocks
+personas:
+  - app-developer
+  - protocol-developer
+  - chain-operator
+categories:
+  - protocol
+  - block-production
+  - developer-tools
+is_imported_content: 'false'
+---
+
+# Flashblocks
+
+Flashblocks is a block builder sidecar for OP Stack chains that delivers sub-second transaction confirmations - 250 ms on OP Mainnet, configurable down to 200 ms.
+
+By streaming pre-confirmations, "signals" that arrive before the next block is finalized, Flashblocks make OP Stack chains up to 10x faster, unlocking seamless user experiences without compromising security guarantees.
+
+Built for developers who need lightning fast UX, flashblocks are ideal for DeFi apps, payments, games, and real-time interactions where instant is the only answer.
+
+*   **Payments**: Instant payment confirmations
+*   **DeFi**: Swaps and positions that update immediately
+*   **Marketplaces**: Fast, frictionless checkout flows
+*   **Games**: Real-time actions with no waiting between moves
+
+## How it works
+
+By default, blocks are produced every 1–2 seconds.
+Flashblocks break that window into smaller intervals so instead of waiting the full block time to execute all transactions, the execution client continuously creates and broadcasts a "flash" block every few hundred milliseconds.
+
+Each flashblock includes all transactions processed so far, along with updated balances and contract states.
+Apps can query this near-real-time state using RPC providers (Ankr, QuickNode, Alchemy, etc) and deliver the speed their users expect.
+
+## Integrate Flashblocks
+
+Integration is designed to be simple and low-friction. Most apps benefit with minimal code changes.
+
+*   In production, point your app to a a Flashblocks‑aware RPC endpoint from your provider of choice. If your provider doesn't support flashblocks yet, let us know on Discord
+    and we'll work with them to get it added.
+*   Alternatively, you can run your own flashblocks-aware node using Base's [reth](https://github.com/base/node-reth) image.
+
+### Supported RPC methods
+
+Developers can access Flashblocks using the same familiar Ethereum JSON-RPC calls.
+The difference is using the "pending" tag to query the pre-confirmed state instead of the last finalized block.
+
+*   **`eth_getBlockByNumber`**: Use the `pending` tag to retrieve the latest flashblock snapshot.
+    <details>
+      <summary>Sample response</summary>
+
+      ```json
+          {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "result": {
+              "number": "0x1234",
+              "hash": "0x...",
+              "transactions": [...]
+            }
+          }
+      ```
+    </details>
+
+*   **`eth_call`**: Use the `pending` tag to execute calls against the most recent pre-confirmed state.
+
+    <details>
+      <summary>Sample request</summary>
+
+      ```json
+      {
+        "jsonrpc": "2.0",
+        "method": "eth_call",
+        "params": [{"to": "0x...", "data": "0x..."}, "pending"],
+        "id": 1
+      }
+      ```
+    </details>
+
+*   `eth_getBalance` / `eth_getTransactionCount`: Use the `pending` tag to fetch balances or transaction counts as they evolve within the block window.
+
+    <details>
+      <summary>Sample response for `eth_getBalance`</summary>
+
+      ```json
+      {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "result": "0x0234"
+      }
+      ```
+    </details>
+
+    <details>
+      <summary>Sample response for `eth_getTransactionCount`</summary>
+
+      ```json
+      {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "result": "0x1b" // 27 transactions
+      }
+      ```
+    </details>
+
+    Other methods, like `eth_getTransactionReceipt` and `eth_getTransactionByHash`, return data from pre-confirmed transactions without requiring the `pending` tag.
+    Consult the [Flashblocks specification](https://specs.optimism.io/protocol/flashblocks.html#flashblock-json-rpc-apis) for more details on each of these methods.
+
+## Libraries
+
+You will need a Flashblocks‑aware RPC endpoint to use the following libraries:
+
+### Viem
+
+```ts
+import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { opSepolia } from 'viem/chains';
+import { publicActionsL2, walletActionsL2 } from 'viem/op-stack';
+
+const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
+
+const walletClient = createWalletClient({
+  account,
+  chain: opSepolia,
+  transport: http("https://sepolia.optimism.io"),
+}).extend(walletActionsL2());
+
+const publicClient = createPublicClient({
+  chain: opSepolia,
+  transport: http("https://sepolia.optimism.io"),
+}).extend(publicActionsL2());
+
+const submissionTime = new Date();
+const hash = await walletClient.sendTransaction({
+  to: '0x...',
+  value: parseEther('0.0001'),
+});
+
+// Wait for pre-confirmation
+const receipt = await publicClient.waitForTransactionReceipt({ hash });
+const confirmTime = new Date();
+console.log('pre-confirmed in ms:', confirmTime.getTime() - submissionTime.getTime());
+```
+
+### Ethers
+
+```ts
+import { ethers } from 'ethers';
+
+// Here, provider is a Flashblocks-enabled RPC provider
+const provider = new ethers.JsonRpcProvider("https://sepolia.optimism.io");
+const wallet = new ethers.Wallet(process.env.PRIVATE_KEY as string, provider);
+
+const tx = { to: '0x...', value: ethers.parseEther('0.0001') };
+const submission = new Date();
+
+const sent = await wallet.sendTransaction(tx);
+
+await sent.wait(0);
+const confirmed = new Date();
+
+// should represent the transaction (pre)confirmation faster than standard RPC
+console.log('Pre-confirmed in ms:', confirmed.getTime() - submission.getTime()); 
+
+// validates the transaction hash returned by the pre-confirmed transaction above
+const receipt = await provider.getTransactionReceipt(sent.hash);
+console.log('Receipt validated in ms:', validated.getTime() - submission.getTime());
+console.log('Transaction receipt:', receipt); 
+
+```
+
+## Flashblocks FAQ
+
+### Block building and availability
+
+<details>
+  <summary>How often are Flashblocks produced?</summary>
+  The flashblocks target interval is variable.
+  OP Mainnet runs flashblocks at 250ms while Base and Unichain run them at 200ms.
+  A 2-second block at 250 ms produces 9 flashblocks, indexed 0 to 8.
+  The index-0 block contains deposit-only transactions, followed by 8 normal Flashblocks.
+</details>
+
+<details>
+  <summary>Will the number of Flashblocks per block always be the maximum?</summary>
+  Not always. Heavy execution in one interval may reduce time available for subsequent intervals. The FLASHBLOCKS\_TIME setting is a target, not a strict guarantee.
+</details>
+
+<details>
+  <summary>Do large gas transactions get delayed?</summary>
+  High gas transactions can be included in any flashblock with sufficient gas capacity. Placement is optimized by heuristics, but available gas decreases as transactions fill earlier flashblocks.
+</details>
+
+### High availability and safety
+
+<details>
+  <summary>What happens if the flashblocks builder fails?</summary>
+  In a default/non-HA setup, the system falls back to regular block building while preserving pre-confirmations. In an HA setup, `op-conductor` seamlessly transfers leadership to a healthy sequencer without interruption.
+  When leadership changes, streaming continues seamlessly from the new leader so downstream consumers always receive a continuous stream from a single stable endpoint.
+</details>
+
+<details>
+  <summary>How is continuity handled in high availability setups with multiple sequencers?</summary>
+  Only the current leader streams Flashblocks. On leader change, streaming continues from the new leader so downstream consumers see a continuous stream from a single stable endpoint. For details on high-availability sequencer setups, see the [op-conductor documentation](https://docs.optimism.io/operators/chain-operators/tools/op-conductor).
+</details>
+
+<details>
+  <summary>Do flashblocks change the safety model of the chain?</summary>
+  No. Each flashblock is validated by the same execution engine as normal blocks.
+</details>
+
+### Pre-confirmations and reorgs
+
+<details>
+  <summary>Can pre-confirmations be revoked?</summary>
+  Rarely. If the sequencer reorgs, pre-confirmed state may change - but this carries no more risk than the reorg of normal blocks.
+</details>
+
+<details>
+  <summary>Why can a pre-confirmed transaction later disappear?</summary>
+  If the sequencer reorgs, pre-confirmed state can be replaced. This does not add risk beyond the pending state reorg risk that already exists.
+</details>
+
+<details>
+  <summary>Does Flashblocks change liveness or withdrawals?</summary>
+  No. Protocol guarantees remain the same; Flashblocks only speed up transaction confirmation.
+</details>
+
+<details>
+  <summary>What is the structure of a pre-confirmation response?</summary>
+  In pre-confirmation responses, `blockHash`, `stateRoot`, and `receiptsRoot` are the values that represent the cumulative state of all transactions included up to that point in the block. The blockNumber reflects the current pending block number.
+  Each flashblock's view shows the complete state incorporating all transactions processed so far.
+</details>
+
+## Next steps
+
+*   Explore the [high-level guide](/operators/chain-operators/features/flashblocks/chain-operators) for operators.
+*   Review the [technical specs](https://specs.optimism.io/protocol/flashblocks.html) for architecture details.
+*   Join our [community](https://discord.gg/jPQhHTdemH) to share best practices and get support!