Skip to content
This repository was archived by the owner on Mar 17, 2026. It is now read-only.

Commit 017fd78

Browse files
soheimamsoheimam
authored
Merge branch 'master' into docs/ai-guide
2 parents 26c9207 + d1c553e commit 017fd78

2 files changed

Lines changed: 201 additions & 0 deletions

File tree

‎apps/base-docs/docs/pages/chain/flashblocks.mdx‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: Flashblocks
3+
slug: /flashblocks
4+
description: Experience lightning-fast transaction confirmations on Base by using Flashblocks. Preconfirmations happen in just 200 milliseconds—designed for real-time apps, games, and seamless UX.
5+
---
6+
7+
# Flashblocks
8+
9+
## Overview
10+
11+
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.
12+
13+
## Integrating Flashblocks
14+
15+
Flashblocks is enabled for developers on Base Sepolia with full support for mainnet coming very soon. There are two ways you can integrate with Flashblocks data. You can either use the WebSocket API to stream real-time block updates, or use the RPC API to query the Flashblocks-aware RPC endpoint.
16+
17+
### WebSocket API
18+
19+
Use our API to stream realtime block updates over a WebSocket.
20+
21+
You can connect to the websocket endpoint with any WebSocket library of CLI tool. The endpoint is available at wss://sepolia.flashblocks.base.org/ws.
22+
23+
Two recommended tools for connecting to the WebSocket endpoint are [Websocat](https://github.com/vi/websocat) and the [Javascript Websocket Client](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applicationsjk).
24+
25+
#### Websocat Example
26+
27+
Firstly install websocat, [following these instructions](https://github.com/vi/websocat?tab=readme-ov-file#installation).
28+
29+
From your terminal, you can then connect to the websocket stream by running:
30+
```
31+
websocat wss://sepolia.flashblocks.base.org/ws
32+
```
33+
34+
In your terminal, you'll see a stream of all the Flashblocks being sent over the websocket connection.
35+
36+
#### Interpreting the data
37+
38+
To minimize the amount of data sent to clients, each Flashblock only includes the diff data from the previous block. The initial Flashblock (when index is zero) includes the block properties (e.g. number, gas limit) and the subsequent Flashblocks only include the diff data (e.g. transactions that are present in that Flashblock).
39+
40+
**Example Initial Response**
41+
```
42+
{
43+
"payload_id": "0x03997352d799c31a",
44+
"index": 0,
45+
"base": {
46+
"parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
47+
"fee_recipient": "0x4200000000000000000000000000000000000011",
48+
"block_number": "0x158a0e9",
49+
"gas_limit": "0x3938700",
50+
"timestamp": "0x67bf8332",
51+
"base_fee_per_gas": "0xfa"
52+
// ... other base fields ...
53+
},
54+
"diff": {
55+
"state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333",
56+
"block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
57+
"gas_used": "0xab3f",
58+
"transactions": [
59+
"0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."
60+
],
61+
"withdrawals": []
62+
// ... other diff fields ...
63+
},
64+
"metadata": {
65+
"block_number": 22585577,
66+
"new_account_balances": {
67+
"0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0",
68+
// ... other balances ...
69+
},
70+
"receipts": {
71+
"0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": {
72+
"Deposit": {
73+
"status": "0x1",
74+
"depositNonce": "0x158a0ea"
75+
// ... other receipt fields ...
76+
}
77+
}
78+
}
79+
}
80+
}
81+
```
82+
83+
**Example Diff Response**
84+
```
85+
{
86+
"payload_id": "0x03e303378749418d",
87+
"index": 4,
88+
"diff": {
89+
"state_root": "0x7a8f45038665072f382730e689f4a1561835c9987fca8942fa95872fb9367eaa",
90+
"block_hash": "0x9b32f7a14cbd1efc8c2c5cad5eb718ec9e0c5da92c3ba7080f8d4c49d660c332",
91+
"gas_used": "0x1234f",
92+
"transactions": [
93+
"0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."
94+
],
95+
"withdrawals": []
96+
// ... other diff fields ...
97+
},
98+
"metadata": {
99+
"block_number": 22585577,
100+
"new_account_balances": {
101+
"0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0",
102+
"0x4200000000000000000000000000000000000015": "0x1234"
103+
// ... other balances ...
104+
},
105+
"receipts": {
106+
"0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": {
107+
"status": "0x1",
108+
"gasUsed": "0x1234f",
109+
"logs": []
110+
// ... other receipt fields ...
111+
}
112+
}
113+
}
114+
}
115+
```
116+
117+
### RPC API
118+
119+
You can also utilize our Flashblock aware RPC endpoint at `https://sepolia-preconf.base.org`.
120+
121+
In addition to these flashblock-specific methods, all standard Ethereum JSON-RPC methods are supported as usual.
122+
123+
#### eth_getBlockByNumber
124+
125+
Use the `pending` tag to retrieve the latest Flashblock:
126+
```
127+
curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",true],"id":1}'
128+
```
129+
130+
**Example Response**
131+
```
132+
{
133+
"jsonrpc": "2.0",
134+
"id": 1,
135+
"result": {
136+
"number": "0x1234",
137+
"hash": "0x...",
138+
"transactions": [...]
139+
}
140+
}
141+
```
142+
143+
#### eth_getTransactionReceipt
144+
145+
Use the existing receipt RPC to get preconfirmed receipts:
146+
```
147+
curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}'
148+
```
149+
150+
**Example Response**
151+
```
152+
{
153+
"jsonrpc": "2.0",
154+
"id": 1,
155+
"result": {
156+
"transactionHash": "0x...",
157+
"blockNumber": "0x1234",
158+
"status": "0x1"
159+
}
160+
}
161+
```
162+
163+
#### eth_getBalance
164+
165+
Use the `pending` tag to get the address balance in the latest Flashblock:
166+
```
167+
curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...","pending"],"id":1}'
168+
```
169+
170+
**Example Response**
171+
```
172+
{
173+
"jsonrpc": "2.0",
174+
"id": 1,
175+
"result": "0x0234"
176+
}
177+
```
178+
179+
#### eth_getTransactionCount
180+
181+
Use the `pending` tag to get the address nonce in the latest Flashblock:
182+
```
183+
curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x...","pending"],"id":1}'
184+
```
185+
186+
**Example Response**
187+
```
188+
{
189+
"jsonrpc": "2.0",
190+
"id": 1,
191+
"result": "0x1b" // 27 transactions
192+
}
193+
```
194+
195+
## Support
196+
197+
For feedback, support or questions about Flashblocks, please don't hesitate to contact us in the `#developer-chat` channel in the [Base Discord](https://base.org/discord).

‎apps/base-docs/sidebar.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1040,6 +1040,10 @@ export const sidebar: Sidebar = [
10401040
},
10411041
],
10421042
},
1043+
{
1044+
text: 'Flashblocks',
1045+
link: '/chain/flashblocks',
1046+
},
10431047
{
10441048
text: 'Base Contracts',
10451049
link: '/chain/base-contracts',

0 commit comments

Comments
 (0)