update docs for v0.8.0 release

docs/base-chain/api-reference/flashblocks-api/eth_simulateV1.mdx

@@ -50,15 +50,19 @@ Only available on Flashblocks endpoints: `https://mainnet-preconf.base.org` / `h
   Array of simulated block results, one per entry in `blockStateCalls`.
 
   <Expandable title="Block result fields">
+    <ResponseField name="number" type="string">Simulated block number (hex).</ResponseField>
+    <ResponseField name="hash" type="string">Simulated block hash.</ResponseField>
+    <ResponseField name="gasUsed" type="string">Total gas used across all calls in this simulated block (hex).</ResponseField>
+    <ResponseField name="baseFeePerGas" type="string">Base fee per gas for this simulated block (hex).</ResponseField>
     <ResponseField name="calls" type="array">
       Array of individual call results.
 
       <Expandable title="Call result fields">
         <ResponseField name="status" type="string">`"0x1"` for success, `"0x0"` for failure.</ResponseField>
-        <ResponseField name="gasUsed" type="string">Gas used as a hexadecimal integer.</ResponseField>
-        <ResponseField name="returnData" type="string">Hex-encoded return data.</ResponseField>
-        <ResponseField name="logs" type="array">Logs emitted (including ETH transfer logs if `traceTransfers` is `true`).</ResponseField>
-        <ResponseField name="error" type="string">Revert reason if the call failed. Optional.</ResponseField>
+        <ResponseField name="gasUsed" type="string">Gas used by this call (hex).</ResponseField>
+        <ResponseField name="returnData" type="string">Hex-encoded return data from the call.</ResponseField>
+        <ResponseField name="logs" type="array">Logs emitted by this call. Includes ETH transfer logs if `traceTransfers` is `true`.</ResponseField>
+        <ResponseField name="error" type="object">Present if the call reverted. Contains `message` (string) and `code` (number).</ResponseField>
       </Expandable>
     </ResponseField>
   </Expandable>
@@ -97,11 +101,15 @@ curl https://sepolia-preconf.base.org \
   "id": 1,
   "result": [
     {
+      "number": "0x29442bb",
+      "hash": "0xcefc6e6e...",
+      "gasUsed": "0x79ce",
+      "baseFeePerGas": "0xfa",
       "calls": [
         {
           "status": "0x1",
-          "gasUsed": "0x5208",
-          "returnData": "0x",
+          "gasUsed": "0x79ce",
+          "returnData": "0x00000000000000000000000000000000000000000000000000000000011420f9",
           "logs": []
         }
       ]

docs/base-chain/api-reference/flashblocks-api/flashblocks-api-overview.mdx

@@ -103,15 +103,19 @@ Contains the incremental block state changes for this specific Flashblock. Prese
 **The `metadata` object is not stable.** Fields may be added, modified, or removed without prior notice. Do not build production dependencies on it — use the [`diff`](#diff-object) object or query finalized block data via standard RPC instead.
 </Warning>
 
+<Warning>
+**Azul breaking change:** The `new_account_balances` and `receipts` fields are removed from `metadata` as of the [Azul upgrade](/base-chain/protocol-api/specs/upgrades/azul/overview). After activation, the `metadata` object will only contain `block_number`.
+</Warning>
+
 <Card>
 <ParamField path="block_number" type="number">Block number as a decimal integer.</ParamField>
-<ParamField path="new_account_balances" type="object">Map of addresses to their updated ETH balances (hex). Only includes accounts whose balances changed in this Flashblock.</ParamField>
-<ParamField path="receipts" type="object">Map of transaction hashes to their [Receipt](#receipt-object) objects.</ParamField>
+<ParamField path="new_account_balances" type="object">**Removed in Azul.** Map of addresses to their updated ETH balances (hex). Only includes accounts whose balances changed in this Flashblock.</ParamField>
+<ParamField path="receipts" type="object">**Removed in Azul.** Map of transaction hashes to their [Receipt](#receipt-object) objects. Use [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions) with `full: true` to access receipt fields instead.</ParamField>
 </Card>
 
 ### Receipt Object
 
-The abbreviated transaction receipt included in `metadata.receipts`. Check the `type` field to determine transaction type.
+The abbreviated transaction receipt included in `metadata.receipts`. **Removed from `metadata` in the Azul upgrade.** Receipt fields are now available on individual transaction objects via the [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions) subscription with `full: true`.
 
 <Card>
 <ParamField path="type" type="string">Transaction type: `0x0` Legacy, `0x1` Access List, `0x2` EIP-1559, `0x7e` Deposit (L1→L2).</ParamField>
@@ -124,14 +128,27 @@ The abbreviated transaction receipt included in `metadata.receipts`. Check the `
 
 ### Log Object
 
+Log objects appear in `newFlashblockTransactions` (full mode) and in `metadata.receipts` (infrastructure stream, pre-Azul).
+
 <Card>
 <ParamField path="address" type="string">Contract address that emitted the event.</ParamField>
 <ParamField path="topics" type="string[]">Array of indexed event parameters. Topic 0 is typically the event signature hash.</ParamField>
 <ParamField path="data" type="string">ABI-encoded non-indexed event parameters.</ParamField>
+<ParamField path="blockHash" type="string">Hash of the partial block at time of pre-confirmation. Note: this is a Flashblock hash, not a final block hash.</ParamField>
+<ParamField path="blockNumber" type="string">Block number this log belongs to (hex).</ParamField>
+<ParamField path="blockTimestamp" type="string">Unix timestamp of the block (hex).</ParamField>
+<ParamField path="transactionHash" type="string">Hash of the transaction that emitted this log.</ParamField>
+<ParamField path="transactionIndex" type="string">Index of the transaction within the block (hex).</ParamField>
+<ParamField path="logIndex" type="string">Index of this log within the block (hex).</ParamField>
+<ParamField path="removed" type="boolean">Always `false` for Flashblocks logs. Would be `true` if a reorg removed the log, which does not apply to Flashblocks.</ParamField>
 </Card>
 
 ### Complete Examples
 
+<Note>
+The examples below show the pre-Azul `metadata` format. After the [Azul upgrade](/base-chain/protocol-api/specs/upgrades/azul/overview), `metadata.new_account_balances` and `metadata.receipts` will no longer be present in the stream.
+</Note>
+
 **Index 0** — includes the `base` object (block header):
 
 ```json

docs/base-chain/api-reference/flashblocks-api/newFlashblockTransactions.mdx

@@ -4,36 +4,149 @@ sidebarTitle: 'newFlashblockTransactions'
 description: 'Subscribe to receive each transaction as it is pre-confirmed into a Flashblock. Only available on Flashblocks WebSocket endpoints.'
 ---
 
-Subscribe via `eth_subscribe` to receive each transaction as it is pre-confirmed into a Flashblock. Pass `true` as the second parameter to receive full transaction and log data.
+Subscribe via `eth_subscribe` to receive each transaction as it is pre-confirmed into a Flashblock. Pass `true` as the second parameter to receive the full transaction object, associated logs, and receipt fields.
 
 <Info>
 Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` / `wss://sepolia-preconf.base.org`.
 </Info>
 
 <Note>
-Requires [base/base](https://github.com/base/base) minimum client version v0.3.1.
+Requires [base/base](https://github.com/base/base) minimum client version v0.8.0. Receipt fields in `full` mode were added in v0.8.0.
 </Note>
 
 <Warning>
 Each subscription emits **one item per WebSocket message**. Events arrive approximately every 200ms. If your handler performs heavy processing per event, throttle or debounce it to avoid blocking.
 </Warning>
 
+<Warning>
+**Breaking change in v0.8.0:** The `gasUsed` field changed from an optional integer (`null` or `123456`) to a required hex string (`"0x1e240"`). Existing consumers of `newFlashblockTransactions` with `full: true` must update their parsers before upgrading to v0.8.0.
+</Warning>
+
 ## Parameters
 
 <ParamField body="subscriptionType" type="string" required>
   Must be `"newFlashblockTransactions"`.
 </ParamField>
 
-<ParamField body="full" type="boolean">
-  If `true`, each notification includes the full transaction object and associated logs. Defaults to `false` (minimal data only).
+<ParamField body="full" type="boolean | object">
+  Controls the notification content. Three modes are supported:
+
+  - **`false` (default)** — each notification delivers a transaction hash string.
+  - **`true`** — each notification delivers the full `TransactionWithLogs` object (transaction fields + logs + receipt fields).
+  - **Filter object** — pass `{ "address": "0x...", "topics": [...] }` to stream only transactions where at least one emitted log matches the filter. Each matching notification delivers the full `TransactionWithLogs` object. All logs for the transaction are included, not just the matching ones.
+
+  The filter object accepts the same `address` and `topics` fields as `eth_getLogs`.
 </ParamField>
 
 ## Returns
 
-<ResponseField name="result" type="string">
-  Hex-encoded subscription ID.
+The initial `eth_subscribe` response returns a hex-encoded subscription ID string. After that, the node pushes one notification per WebSocket message for each pre-confirmed transaction.
+
+**When `full` is `false` (default):** each notification's `result` is a transaction hash string.
+
+**When `full` is `true`:** each notification's `result` is a transaction object with the following fields:
+
+<ResponseField name="result" type="object">
+  The pre-confirmed transaction object. Only present when `full` is `true`; otherwise `result` is a transaction hash string.
+
+  <Expandable title="Transaction and receipt fields">
+    <ResponseField name="hash" type="string">Transaction hash.</ResponseField>
+    <ResponseField name="from" type="string">Sender address.</ResponseField>
+    <ResponseField name="to" type="string">Recipient address. `null` for contract deployments.</ResponseField>
+    <ResponseField name="value" type="string">ETH value transferred (hex).</ResponseField>
+    <ResponseField name="gas" type="string">Gas limit (hex).</ResponseField>
+    <ResponseField name="gasPrice" type="string">Effective gas price (hex).</ResponseField>
+    <ResponseField name="maxFeePerGas" type="string">Max fee per gas for EIP-1559 transactions (hex).</ResponseField>
+    <ResponseField name="maxPriorityFeePerGas" type="string">Max priority fee per gas for EIP-1559 transactions (hex).</ResponseField>
+    <ResponseField name="nonce" type="string">Sender nonce (hex).</ResponseField>
+    <ResponseField name="input" type="string">ABI-encoded calldata.</ResponseField>
+    <ResponseField name="type" type="string">Transaction type: `0x0` Legacy, `0x1` Access List, `0x2` EIP-1559.</ResponseField>
+    <ResponseField name="chainId" type="string">Chain ID (hex). Base mainnet: `0x2105`.</ResponseField>
+    <ResponseField name="blockNumber" type="string">Block number this transaction was pre-confirmed in (hex).</ResponseField>
+    <ResponseField name="transactionIndex" type="string">Index of this transaction within the block (hex).</ResponseField>
+    <ResponseField name="blockHash" type="string">Always `null` for Flashblocks (block not yet finalized).</ResponseField>
+    <ResponseField name="accessList" type="array">EIP-2930 access list entries.</ResponseField>
+    <ResponseField name="r" type="string">ECDSA signature r value.</ResponseField>
+    <ResponseField name="s" type="string">ECDSA signature s value.</ResponseField>
+    <ResponseField name="v" type="string">ECDSA signature v value.</ResponseField>
+    <ResponseField name="yParity" type="string">Signature y-parity for EIP-1559/2930 transactions.</ResponseField>
+    <ResponseField name="gasUsed" type="string">Gas actually used by this transaction (hex). **Required** as of v0.8.0 — previously this field was optional and returned as an integer. Update parsers accordingly.</ResponseField>
+    <ResponseField name="status" type="string">`0x1` for success, `0x0` for failure. Added in v0.8.0.</ResponseField>
+    <ResponseField name="cumulativeGasUsed" type="string">Cumulative gas used in the block up to and including this transaction (hex). Added in v0.8.0.</ResponseField>
+    <ResponseField name="contractAddress" type="string">Address of the deployed contract for contract-creation transactions. `null` otherwise. Added in v0.8.0.</ResponseField>
+    <ResponseField name="logsBloom" type="string">Bloom filter for the logs in this transaction (hex). Added in v0.8.0.</ResponseField>
+    <ResponseField name="logs" type="array">Event logs emitted by this transaction. See the [Log Object](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#log-object) schema.</ResponseField>
+  </Expandable>
 </ResponseField>
 
+## Notification Format
+
+When `full` is `false` (default), each notification delivers a transaction hash:
+
+```json Notification (default)
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "subscription": "0x1887ec8b9589ccad00000000000532da",
+    "result": "0xabc123..."
+  }
+}
+```
+
+When `full` is `true`, each notification delivers the full transaction object. Receipt fields (`gasUsed`, `status`, `cumulativeGasUsed`, `contractAddress`, `logsBloom`) are included directly on the transaction object — there is no nested receipt sub-object:
+
+```json Notification (full=true)
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "subscription": "0x4f029cbb4655559c37784ec4f3983914",
+    "result": {
+      "type": "0x2",
+      "chainId": "0x2105",
+      "nonce": "0x36f0",
+      "gas": "0x26b12",
+      "maxFeePerGas": "0x146a608",
+      "maxPriorityFeePerGas": "0xf4240",
+      "to": "0xda3983e1ea25051b242ec0df4acf18e68d08a212",
+      "value": "0x0",
+      "accessList": [],
+      "input": "0x67243482...",
+      "r": "0x82df735d...",
+      "s": "0x431fa018...",
+      "yParity": "0x1",
+      "v": "0x1",
+      "hash": "0xb2ce9822...",
+      "blockHash": null,
+      "blockNumber": "0x27920be",
+      "transactionIndex": "0xbe",
+      "from": "0x68acbb03...",
+      "gasPrice": "0xaae286",
+      "gasUsed": "0x1a4b2",
+      "status": "0x1",
+      "cumulativeGasUsed": "0x8f3a1",
+      "contractAddress": null,
+      "logsBloom": "0x00200000...",
+      "logs": [
+        {
+          "address": "0xda3983e1ea25051b242ec0df4acf18e68d08a212",
+          "topics": ["0xddf252ad..."],
+          "data": "0x",
+          "blockHash": "0x000...000",
+          "blockNumber": "0x27920be",
+          "blockTimestamp": "0x697c9e5f",
+          "transactionHash": "0xb2ce9822...",
+          "transactionIndex": "0xbe",
+          "logIndex": "0x2d9",
+          "removed": false
+        }
+      ]
+    }
+  }
+}
+```
+
 ## Example
 
 <CodeGroup>
@@ -45,7 +158,45 @@ Each subscription emits **one item per WebSocket message**. Events arrive approx
 {"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", true]}
 ```
 
+```json Subscribe (filtered by log)
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "eth_subscribe",
+  "params": [
+    "newFlashblockTransactions",
+    {
+      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
+    }
+  ]
+}
+```
+
 ```json Subscription ID Response
 {"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
 ```
+
+```javascript JavaScript
+import WebSocket from 'ws';
+
+const ws = new WebSocket('wss://mainnet-preconf.base.org');
+
+ws.on('open', () => {
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'eth_subscribe',
+    params: ['newFlashblockTransactions', true],
+    id: 1
+  }));
+});
+
+ws.on('message', (data) => {
+  const msg = JSON.parse(data.toString());
+  if (msg.method === 'eth_subscription') {
+    const tx = msg.params.result;
+    console.log('Pre-confirmed tx:', tx.hash, '| status:', tx.status);
+  }
+});
+```
 </CodeGroup>