From 408c13ab34d63819d9a435f83498daff3f21747c Mon Sep 17 00:00:00 2001 From: Cody Wang Date: Thu, 24 Apr 2025 21:39:51 -0400 Subject: [PATCH 1/5] node provider docs for flashblocks --- .../{flashblocks.mdx => flashblocks/apps.mdx} | 158 +++++++++--------- .../chain/flashblocks/node-providers.mdx | 51 ++++++ apps/base-docs/sidebar.ts | 6 +- 3 files changed, 136 insertions(+), 79 deletions(-) rename apps/base-docs/docs/pages/chain/{flashblocks.mdx => flashblocks/apps.mdx} (97%) create mode 100644 apps/base-docs/docs/pages/chain/flashblocks/node-providers.mdx diff --git a/apps/base-docs/docs/pages/chain/flashblocks.mdx b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx similarity index 97% rename from apps/base-docs/docs/pages/chain/flashblocks.mdx rename to apps/base-docs/docs/pages/chain/flashblocks/apps.mdx index 1f787a3aa3..874499cd6c 100644 --- a/apps/base-docs/docs/pages/chain/flashblocks.mdx +++ b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx @@ -1,6 +1,6 @@ --- title: Flashblocks -slug: /flashblocks +slug: /flashblocks/apps 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. --- @@ -14,9 +14,87 @@ Flashblocks enable up to 200 millisecond transaction confirmations on Base by le 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. +### RPC API + +You can utilize our Flashblock aware RPC endpoint at `https://sepolia-preconf.base.org`. + +In addition to these flashblock-specific methods, all standard Ethereum JSON-RPC methods are supported as usual. + +#### eth_getBlockByNumber + +Use the `pending` tag to retrieve the latest Flashblock: +``` +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}' +``` + +**Example Response** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "number": "0x1234", + "hash": "0x...", + "transactions": [...] + } +} +``` + +#### eth_getTransactionReceipt + +Use the existing receipt RPC to get preconfirmed receipts: +``` +curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' +``` + +**Example Response** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactionHash": "0x...", + "blockNumber": "0x1234", + "status": "0x1" + } +} +``` + +#### eth_getBalance + +Use the `pending` tag to get the address balance in the latest Flashblock: +``` +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}' +``` + +**Example Response** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x0234" +} +``` + +#### eth_getTransactionCount + +Use the `pending` tag to get the address nonce in the latest Flashblock: +``` +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}' +``` + +**Example Response** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0x1b" // 27 transactions +} +``` + ### WebSocket API -Use our API to stream realtime block updates over a WebSocket. +You can also use our WebSocket API to stream realtime flashblocks updates. 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. @@ -114,83 +192,7 @@ To minimize the amount of data sent to clients, each Flashblock only includes th } ``` -### RPC API - -You can also utilize our Flashblock aware RPC endpoint at `https://sepolia-preconf.base.org`. - -In addition to these flashblock-specific methods, all standard Ethereum JSON-RPC methods are supported as usual. - -#### eth_getBlockByNumber - -Use the `pending` tag to retrieve the latest Flashblock: -``` -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}' -``` - -**Example Response** -``` -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "number": "0x1234", - "hash": "0x...", - "transactions": [...] - } -} -``` - -#### eth_getTransactionReceipt - -Use the existing receipt RPC to get preconfirmed receipts: -``` -curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' -``` - -**Example Response** -``` -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "transactionHash": "0x...", - "blockNumber": "0x1234", - "status": "0x1" - } -} -``` - -#### eth_getBalance - -Use the `pending` tag to get the address balance in the latest Flashblock: -``` -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}' -``` - -**Example Response** -``` -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x0234" -} -``` - -#### eth_getTransactionCount -Use the `pending` tag to get the address nonce in the latest Flashblock: -``` -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}' -``` - -**Example Response** -``` -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x1b" // 27 transactions -} -``` ## Support diff --git a/apps/base-docs/docs/pages/chain/flashblocks/node-providers.mdx b/apps/base-docs/docs/pages/chain/flashblocks/node-providers.mdx new file mode 100644 index 0000000000..9acfe0c36b --- /dev/null +++ b/apps/base-docs/docs/pages/chain/flashblocks/node-providers.mdx @@ -0,0 +1,51 @@ +--- +title: Flashblocks +slug: /flashblocks/node-providers +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. +--- + +# How to host Flashblocks-aware RPC nodes + +## Quick Start + +1. **Prerequisites**: + + - Docker and Docker Compose + - Minimum hardware requirements (see [node README](https://github.com/base/node?tab=readme-ov-file#hardware-requirements)) + - Access to a Flashblocks websocket endpoint, we provide public endpoints in the env files in the repo + +2. **Set Up Environment**: + + ```bash + # Clone the repository + git clone https://github.com/base/node.git + cd node + ``` + +3. **Start the Node with Flashblocks Support**: + ```bash + NODE_TYPE=base CLIENT=reth docker-compose up + ``` + +## Configuration Options + +- **Node Type**: Use `NODE_TYPE=base` to enable base reth node withFlashblocks functionality +- **Network**: Use `NETWORK_ENV=.env.mainnet` for mainnet or `NETWORK_ENV=.env.sepolia` for testnet + +## Verifying Flashblocks Functionality + +Test that your node is properly supporting Flashblocks by querying a pending block: + +```bash +curl -X POST \ + --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \ + http://localhost:8545 +``` + +## Available RPC Methods + +Flashblocks-aware nodes provide all standard Ethereum JSON-RPC methods plus specialized Flashblocks endpoints. For more details, see the [Flashblocks RPC API documentation](https://docs.base.org/chain/flashblocks/apps#rpc-api). + +## Further Resources + +For detailed information about node setup, including hardware requirements and additional configuration options, refer to the [Reth node README](https://github.com/base/op-geth/blob/main/node/reth/README.md). diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index 91eefbf387..7a2113dfe8 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1058,7 +1058,11 @@ export const sidebar: Sidebar = [ }, { text: 'Flashblocks ↗', - link: '/chain/flashblocks', + collapsed: true, + items: [ + { text: 'Apps', link: '/chain/flashblocks/apps' }, + { text: 'Node Providers', link: '/chain/flashblocks/node-providers' }, + ], }, { text: 'Base Contracts', From afb039dfb533e6006d81fa63c5dbf95aa1740819 Mon Sep 17 00:00:00 2001 From: Cody Wang Date: Thu, 24 Apr 2025 21:45:35 -0400 Subject: [PATCH 2/5] add notes for libraries --- apps/base-docs/docs/pages/chain/flashblocks/apps.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx index 874499cd6c..7e8f576685 100644 --- a/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx +++ b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx @@ -92,6 +92,15 @@ curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json } ``` +### Libraries + +For popular libraries, they sometimes require additional RPC support for transaction preconfirmation to work properly. +We are working on adding Flashblocks support to the following libraries: + +- [Ethers](https://github.com/ethers-io/ethers.js) (Completed 🟢) +- [viem](https://github.com/viem/viem) (Coming soon 🟡) +- [wagmi](https://github.com/wagmi-dev/wagmi) (Coming soon 🟡) + ### WebSocket API You can also use our WebSocket API to stream realtime flashblocks updates. From 8bfa71a99955a17848da5d6f8ed4c0783ce6ad23 Mon Sep 17 00:00:00 2001 From: Cody Wang Date: Thu, 24 Apr 2025 21:51:30 -0400 Subject: [PATCH 3/5] adding examples for apps library too --- .../docs/pages/chain/flashblocks/apps.mdx | 39 +++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx index 7e8f576685..e4d6d311f5 100644 --- a/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx +++ b/apps/base-docs/docs/pages/chain/flashblocks/apps.mdx @@ -97,9 +97,42 @@ curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json For popular libraries, they sometimes require additional RPC support for transaction preconfirmation to work properly. We are working on adding Flashblocks support to the following libraries: -- [Ethers](https://github.com/ethers-io/ethers.js) (Completed 🟢) -- [viem](https://github.com/viem/viem) (Coming soon 🟡) -- [wagmi](https://github.com/wagmi-dev/wagmi) (Coming soon 🟡) +#### [Ethers](https://github.com/ethers-io/ethers.js) (Completed 🟢) + +``` + const providerA = new ethers.JsonRpcProvider( + "https://sepolia-preconf.base.org" + ); + + const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, providerA); + + try { + // Create a simple transaction (sending 0.001 ETH to a random address) + const tx = { + to: "", + value: ethers.parseEther("0.0000001"), + }; + + // Submit transaction + const submissionTime = new Date(); + const transaction = await wallet.sendTransaction(tx); + + console.log(`Submitting transaction at: ${submissionTime.toISOString()}`); + console.log(`Transaction hash: ${transaction.hash}`); + + await transaction.wait(0); // Make sure to set the confirmation count to 0 + + console.log("Transaction confirmed"); + const confirmationTime = new Date(); + console.log(`Transaction confirmed at: ${confirmationTime.toISOString()}`); + console.log(`Time difference: ${confirmationTime - submissionTime}ms`); + } +``` +You should see the confirmation time significantly lower than the standard RPC endpoint. + +#### Viem (Coming soon 🟡) + +#### Wagmi (Coming soon 🟡) ### WebSocket API From e6abc1e58500aec472ead6c3037470a9b6cd69c1 Mon Sep 17 00:00:00 2001 From: Cody Wang Date: Tue, 29 Apr 2025 16:57:17 -0400 Subject: [PATCH 4/5] redirect --- apps/base-docs/docs/public/serve.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/base-docs/docs/public/serve.json b/apps/base-docs/docs/public/serve.json index 9b842c4473..1b04fd2a18 100644 --- a/apps/base-docs/docs/public/serve.json +++ b/apps/base-docs/docs/public/serve.json @@ -169,6 +169,10 @@ { "source": "/identity/smart-wallet/guides/sub-accounts/incorporate-spend-permissions", "destination": "/identity/smart-wallet/guides/sub-accounts/" + }, + { + "source": "/chain/flashblocks", + "destination": "/chain/flashblocks/apps" } ] } From 16b1603b41cca7a4e70bd7677661b3e26687c2a1 Mon Sep 17 00:00:00 2001 From: Cody Wang Date: Tue, 29 Apr 2025 16:59:19 -0400 Subject: [PATCH 5/5] remove redundent --- apps/base-docs/sidebar.ts | 8 -------- 1 file changed, 8 deletions(-) diff --git a/apps/base-docs/sidebar.ts b/apps/base-docs/sidebar.ts index c6e2155dba..255ac8bb6a 100644 --- a/apps/base-docs/sidebar.ts +++ b/apps/base-docs/sidebar.ts @@ -1059,10 +1059,6 @@ export const sidebar: Sidebar = [ text: 'Base Contracts', link: '/chain/base-contracts', }, - { - text: 'Flashblocks', - link: '/chain/flashblocks', - }, { text: 'Security Council', link: '/chain/security-council', @@ -1079,10 +1075,6 @@ export const sidebar: Sidebar = [ { text: 'Node Providers', link: '/chain/flashblocks/node-providers' }, ], }, - { - text: 'Base Contracts', - link: '/chain/base-contracts', - }, ], }, {