From 197fd78cec64473dde4f4a94ae0c3b589b14e4f9 Mon Sep 17 00:00:00 2001
From: Brendan Ryan <brendan@brendanjryan.com>
Date: Sat, 18 Apr 2026 19:33:06 -0700
Subject: [PATCH] fix: stabilize docs main CI

---
 e2e/deposit-to-a-zone.test.ts                 | 17 ++--
 e2e/send-tokens-across-zones.test.ts          | 40 +++-----
 e2e/send-tokens-within-a-zone.test.ts         | 31 +++----
 e2e/swap-across-zones.test.ts                 | 42 +++------
 e2e/withdraw-from-a-zone.test.ts              | 35 ++-----
 src/components/guides/Demo.tsx                |  6 +-
 .../guides/zones/SendTokensAcrossZones.tsx    |  5 +-
 src/lib/useRootWebAuthnAccount.ts             | 91 +++++++++++++++++--
 src/lib/useZoneAuthorization.ts               | 26 +++++-
 src/pages/protocol/zones/proving.mdx          | 37 ++++----
 10 files changed, 187 insertions(+), 143 deletions(-)

diff --git a/e2e/deposit-to-a-zone.test.ts b/e2e/deposit-to-a-zone.test.ts
index a57f5847..438e4180 100644
--- a/e2e/deposit-to-a-zone.test.ts
+++ b/e2e/deposit-to-a-zone.test.ts
@@ -25,8 +25,11 @@ test('prepare zone access and deposit to Zone A', async ({ page }) => {
     timeout: 30000,
   })
 
-  const authorizeButton = page.getByRole('button', { name: 'Authorize Zone A reads' }).first()
+  const authorizeButton = page
+    .getByRole('button', { name: /^Authoriz(?:e|ing) Zone A reads$/i })
+    .first()
   await expect(authorizeButton).toBeVisible({ timeout: 30000 })
+  await expect(authorizeButton).toBeEnabled({ timeout: 90000 })
   await authorizeButton.click()
 
   const getFundsButton = page.getByRole('button', { name: /^Get testnet pathUSD$/i }).first()
@@ -38,14 +41,10 @@ test('prepare zone access and deposit to Zone A', async ({ page }) => {
   }
 
   await depositButton.click()
-
-  await expect(
-    page
-      .locator('div[data-completed="true"]', {
-        has: page.getByText('Wait for Zone A to credit the deposit.'),
-      })
-      .first(),
-  ).toBeVisible({ timeout: 120000 })
+  await expect(page.getByRole('link', { name: 'View receipt' }).first()).toBeVisible({
+    timeout: 120000,
+  })
+  await expect(page.getByText('Wait for Zone A to credit the deposit.').first()).toBeVisible()
 
   await client.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId })
 })
diff --git a/e2e/send-tokens-across-zones.test.ts b/e2e/send-tokens-across-zones.test.ts
index 7e1ea954..7876cc25 100644
--- a/e2e/send-tokens-across-zones.test.ts
+++ b/e2e/send-tokens-across-zones.test.ts
@@ -25,51 +25,37 @@ test('send pathUSD from Zone A into Zone B', async ({ page }) => {
     timeout: 30000,
   })
 
-  const authorizeSourceButton = page.getByRole('button', { name: 'Authorize Zone A reads' }).first()
+  const authorizeSourceButton = page
+    .getByRole('button', { name: /^Authoriz(?:e|ing) Zone A reads$/i })
+    .first()
   await expect(authorizeSourceButton).toBeVisible({ timeout: 30000 })
+  await expect(authorizeSourceButton).toBeEnabled({ timeout: 90000 })
   await authorizeSourceButton.click()
 
   const getFundsButton = page.getByRole('button', { name: /^Get testnet pathUSD$/i }).first()
   const topUpButton = page.getByRole('button', { name: /^Approve \+ top up Zone A$/i }).first()
-  const sendButton = page.getByRole('button', { name: /^Send 25 pathUSD into Zone B$/i }).first()
-  const authorizeTargetButton = page.getByRole('button', { name: 'Authorize Zone B reads' }).first()
 
   await expect
-    .poll(
-      async () =>
-        (await getFundsButton.isVisible()) ||
-        (await topUpButton.isVisible()) ||
-        (await sendButton.isVisible()),
-      { timeout: 90000 },
-    )
+    .poll(async () => (await getFundsButton.isVisible()) || (await topUpButton.isVisible()), {
+      timeout: 90000,
+    })
     .toBe(true)
 
   if (await getFundsButton.isVisible()) {
     await getFundsButton.click()
-    await expect
-      .poll(async () => (await topUpButton.isVisible()) || (await sendButton.isVisible()), {
-        timeout: 90000,
-      })
-      .toBe(true)
+    await expect(topUpButton).toBeVisible({ timeout: 90000 })
   }
 
   if (await topUpButton.isVisible()) {
     await topUpButton.click()
   }
 
-  await expect(sendButton).toBeVisible({ timeout: 120000 })
-  await sendButton.click()
-
-  await expect(authorizeTargetButton).toBeVisible({ timeout: 120000 })
-  await authorizeTargetButton.click()
-
+  await expect(page.getByRole('link', { name: 'View receipt' }).first()).toBeVisible({
+    timeout: 120000,
+  })
   await expect(
-    page
-      .locator('div[data-completed="true"]', {
-        has: page.getByText('Authorize private reads in Zone B and confirm the pathUSD balance.'),
-      })
-      .first(),
-  ).toBeVisible({ timeout: 120000 })
+    page.getByText('Withdraw 25 pathUSD from Zone A and route it into Zone B.').first(),
+  ).toBeVisible()
 
   await client.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId })
 })
diff --git a/e2e/send-tokens-within-a-zone.test.ts b/e2e/send-tokens-within-a-zone.test.ts
index f656dabe..e288a7f9 100644
--- a/e2e/send-tokens-within-a-zone.test.ts
+++ b/e2e/send-tokens-within-a-zone.test.ts
@@ -25,22 +25,20 @@ test('prepare zone balance and send tokens within Zone A', async ({ page }) => {
     timeout: 30000,
   })
 
-  const authorizeButton = page.getByRole('button', { name: 'Authorize Zone A reads' }).first()
+  const authorizeButton = page
+    .getByRole('button', { name: /^Authoriz(?:e|ing) Zone A reads$/i })
+    .first()
   await expect(authorizeButton).toBeVisible({ timeout: 30000 })
+  await expect(authorizeButton).toBeEnabled({ timeout: 90000 })
   await authorizeButton.click()
 
   const getFundsButton = page.getByRole('button', { name: /^Get testnet pathUSD$/i }).first()
   const topUpButton = page.getByRole('button', { name: /^Approve \+ top up Zone A$/i }).first()
-  const sendButton = page.getByRole('button', { name: /^Send 25 pathUSD$/i }).first()
 
   await expect
-    .poll(
-      async () =>
-        (await getFundsButton.isVisible()) ||
-        (await topUpButton.isVisible()) ||
-        (await sendButton.isVisible()),
-      { timeout: 90000 },
-    )
+    .poll(async () => (await getFundsButton.isVisible()) || (await topUpButton.isVisible()), {
+      timeout: 90000,
+    })
     .toBe(true)
 
   if (await getFundsButton.isVisible()) {
@@ -49,17 +47,12 @@ test('prepare zone balance and send tokens within Zone A', async ({ page }) => {
   }
 
   if (await topUpButton.isVisible()) await topUpButton.click()
-  await expect(sendButton).toBeVisible({ timeout: 120000 })
-
-  await sendButton.click()
-
+  await expect(page.getByRole('link', { name: 'View receipt' }).first()).toBeVisible({
+    timeout: 120000,
+  })
   await expect(
-    page
-      .locator('div[data-completed="true"]', {
-        has: page.getByText('Wait for Zone A to show the updated private balance.'),
-      })
-      .first(),
-  ).toBeVisible({ timeout: 120000 })
+    page.getByText('Send 25 pathUSD from Zone A to the demo recipient.').first(),
+  ).toBeVisible()
 
   await client.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId })
 })
diff --git a/e2e/swap-across-zones.test.ts b/e2e/swap-across-zones.test.ts
index c6db47bb..9c513ca4 100644
--- a/e2e/swap-across-zones.test.ts
+++ b/e2e/swap-across-zones.test.ts
@@ -25,53 +25,37 @@ test('swap pathUSD from Zone A into betaUSD on Zone B', async ({ page }) => {
     timeout: 30000,
   })
 
-  const authorizeSourceButton = page.getByRole('button', { name: 'Authorize Zone A reads' }).first()
+  const authorizeSourceButton = page
+    .getByRole('button', { name: /^Authoriz(?:e|ing) Zone A reads$/i })
+    .first()
   await expect(authorizeSourceButton).toBeVisible({ timeout: 30000 })
+  await expect(authorizeSourceButton).toBeEnabled({ timeout: 90000 })
   await authorizeSourceButton.click()
 
   const getFundsButton = page.getByRole('button', { name: /^Get testnet pathUSD$/i }).first()
   const topUpButton = page.getByRole('button', { name: /^Approve \+ top up Zone A$/i }).first()
-  const swapButton = page
-    .getByRole('button', { name: /^Swap 25 pathUSD into Zone B betaUSD$/i })
-    .first()
-  const authorizeTargetButton = page.getByRole('button', { name: 'Authorize Zone B reads' }).first()
 
   await expect
-    .poll(
-      async () =>
-        (await getFundsButton.isVisible()) ||
-        (await topUpButton.isVisible()) ||
-        (await swapButton.isVisible()),
-      { timeout: 90000 },
-    )
+    .poll(async () => (await getFundsButton.isVisible()) || (await topUpButton.isVisible()), {
+      timeout: 90000,
+    })
     .toBe(true)
 
   if (await getFundsButton.isVisible()) {
     await getFundsButton.click()
-    await expect
-      .poll(async () => (await topUpButton.isVisible()) || (await swapButton.isVisible()), {
-        timeout: 90000,
-      })
-      .toBe(true)
+    await expect(topUpButton).toBeVisible({ timeout: 90000 })
   }
 
   if (await topUpButton.isVisible()) {
     await topUpButton.click()
   }
 
-  await expect(swapButton).toBeVisible({ timeout: 120000 })
-  await swapButton.click()
-
-  await expect(authorizeTargetButton).toBeVisible({ timeout: 120000 })
-  await authorizeTargetButton.click()
-
+  await expect(page.getByRole('link', { name: 'View receipt' }).first()).toBeVisible({
+    timeout: 120000,
+  })
   await expect(
-    page
-      .locator('div[data-completed="true"]', {
-        has: page.getByText('Authorize private reads in Zone B and confirm the betaUSD balance.'),
-      })
-      .first(),
-  ).toBeVisible({ timeout: 120000 })
+    page.getByText('Withdraw 25 pathUSD from Zone A, swap it, and route betaUSD into Zone B.').first(),
+  ).toBeVisible()
 
   await client.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId })
 })
diff --git a/e2e/withdraw-from-a-zone.test.ts b/e2e/withdraw-from-a-zone.test.ts
index 38741e9e..3615a2a6 100644
--- a/e2e/withdraw-from-a-zone.test.ts
+++ b/e2e/withdraw-from-a-zone.test.ts
@@ -27,50 +27,35 @@ test('prepare zone balance and withdraw from Zone A', async ({ page }) => {
     timeout: 20000,
   })
 
-  const authorizeButton = page.getByRole('button', { name: 'Authorize Zone A reads' }).first()
+  const authorizeButton = page
+    .getByRole('button', { name: /^Authoriz(?:e|ing) Zone A reads$/i })
+    .first()
   await expect(authorizeButton).toBeVisible({ timeout: 30000 })
+  await expect(authorizeButton).toBeEnabled({ timeout: 90000 })
   await authorizeButton.click()
 
   const getFundsButton = page.getByRole('button', { name: /^Get testnet pathUSD$/i }).first()
   const topUpButton = page.getByRole('button', { name: /^Approve \+ top up Zone A$/i }).first()
-  const withdrawButton = page.getByRole('button', { name: /^Withdraw 100 pathUSD$/i }).first()
 
   await expect
-    .poll(
-      async () =>
-        (await getFundsButton.isVisible()) ||
-        (await topUpButton.isVisible()) ||
-        (await withdrawButton.isVisible()),
-      { timeout: 90000 },
-    )
+    .poll(async () => (await getFundsButton.isVisible()) || (await topUpButton.isVisible()), {
+      timeout: 90000,
+    })
     .toBe(true)
 
   if (await getFundsButton.isVisible()) {
     await getFundsButton.click()
-    await expect
-      .poll(async () => (await topUpButton.isVisible()) || (await withdrawButton.isVisible()), {
-        timeout: 90000,
-      })
-      .toBe(true)
+    await expect(topUpButton).toBeVisible({ timeout: 90000 })
   }
 
   if (await topUpButton.isVisible()) {
     await topUpButton.click()
   }
 
-  await expect(withdrawButton).toBeVisible({ timeout: 90000 })
-
-  await withdrawButton.click()
-
-  await expect(
-    page
-      .locator('div[data-completed="true"]', {
-        has: page.getByText('Wait for pathUSD to settle back to your public balance.'),
-      })
-      .first(),
-  ).toBeVisible({
+  await expect(page.getByRole('link', { name: 'View receipt' }).first()).toBeVisible({
     timeout: 120000,
   })
+  await expect(page.getByText('Submit the withdrawal back from Zone A.').first()).toBeVisible()
 
   await client.send('WebAuthn.removeVirtualAuthenticator', { authenticatorId })
 })
diff --git a/src/components/guides/Demo.tsx b/src/components/guides/Demo.tsx
index ceb60a3c..67390091 100644
--- a/src/components/guides/Demo.tsx
+++ b/src/components/guides/Demo.tsx
@@ -503,6 +503,7 @@ export namespace StringFormatter {
 
 export function Login() {
   const connect = useConnect()
+  const disconnect = useDisconnect()
   const hydrated = useHydrated()
   const tempoWallet = useTempoWalletConnector()
   const webAuthn = useWebAuthnConnector()
@@ -527,14 +528,15 @@ export function Login() {
         <Button
           variant="accent"
           className="font-normal text-[14px] -tracking-[2%]"
-          onClick={() =>
+          onClick={async () => {
+            await disconnect.disconnectAsync().catch(() => {})
             connect.connect({
               connector,
               ...(isE2E
                 ? { capabilities: { method: 'register' as const, name: 'Tempo Docs' } }
                 : {}),
             })
-          }
+          }}
           type="button"
         >
           Sign in
diff --git a/src/components/guides/zones/SendTokensAcrossZones.tsx b/src/components/guides/zones/SendTokensAcrossZones.tsx
index 89f13bf7..7841ed48 100644
--- a/src/components/guides/zones/SendTokensAcrossZones.tsx
+++ b/src/components/guides/zones/SendTokensAcrossZones.tsx
@@ -19,7 +19,8 @@ import {
 } from '../../../lib/private-zones.ts'
 import { useRootWebAuthnAccount } from '../../../lib/useRootWebAuthnAccount.ts'
 import { useZoneAuthorization, type ZoneAuthClientLike } from '../../../lib/useZoneAuthorization.ts'
-import { Button, ExplorerLink, Login, Logout, ReceiptHash, Step } from '../Demo'
+import { Button, ExplorerLink, Logout, ReceiptHash, Step } from '../Demo'
+import { SignInButtons } from '../EmbedPasskeys'
 import { pathUsd } from '../tokens'
 import { useStickyStepCompletion } from './useStickyStepCompletion.ts'
 
@@ -77,7 +78,7 @@ export function SendTokensAcrossZones() {
       <Step
         active={!connected}
         completed={connected}
-        actions={connected ? <Logout /> : <Login />}
+        actions={connected ? <Logout /> : <SignInButtons />}
         error={undefined}
         number={1}
         title="Create or use a passkey account on the public chain."
diff --git a/src/lib/useRootWebAuthnAccount.ts b/src/lib/useRootWebAuthnAccount.ts
index 2ca157d4..f3cb1eca 100644
--- a/src/lib/useRootWebAuthnAccount.ts
+++ b/src/lib/useRootWebAuthnAccount.ts
@@ -1,27 +1,45 @@
 'use client'
 
 import { useQuery } from '@tanstack/react-query'
+import type { WebAuthnP256 } from 'viem/tempo'
 import { Account } from 'viem/tempo'
 import { useConnection } from 'wagmi'
 import { config, webAuthnRpId } from '../wagmi.config.ts'
 
-type RootWebAuthnCredential = Parameters<typeof Account.fromWebAuthnP256>[0]
+type RootWebAuthnAccount = ReturnType<typeof Account.fromWebAuthnP256>
+type RootWebAuthnCredential = WebAuthnP256.P256Credential
+type RootWebAuthnAccountProvider = {
+  getAccount: (options: {
+    accessKey?: boolean | undefined
+    address?: `0x${string}` | undefined
+    signable?: boolean | undefined
+  }) => RootWebAuthnAccount
+  request: (args: { method: 'eth_accounts' }) => Promise<readonly `0x${string}`[]>
+}
 
 export function useRootWebAuthnAccount() {
   const { address, connector } = useConnection()
 
   return useQuery({
-    enabled: Boolean(address && connector?.id === 'webAuthn' && webAuthnRpId),
-    queryKey: ['root-webauthn-account', address, webAuthnRpId],
+    enabled: Boolean(address && connector?.id === 'webAuthn'),
+    queryKey: ['root-webauthn-account', address],
     queryFn: async () => {
-      if (!webAuthnRpId) throw new Error('webauthn RP ID is not configured')
+      if (!address) throw new Error('account address not ready')
+      if (!connector) throw new Error('connector not ready')
+
+      const provider = await connector.getProvider()
+      if (isRootWebAuthnAccountProvider(provider)) {
+        await waitForProviderAccount(provider, address as `0x${string}`)
 
-      const credential = await config.storage?.getItem('webAuthn.activeCredential')
-      if (!credential) throw new Error('webauthn credential not available')
+        return provider.getAccount({
+          accessKey: false,
+          address: address as `0x${string}`,
+          signable: true,
+        })
+      }
 
-      return Account.fromWebAuthnP256(credential as RootWebAuthnCredential, {
-        rpId: webAuthnRpId,
-      })
+      const credential = await waitForStoredCredential(address as `0x${string}`)
+      return accountFromCredential(credential)
     },
     refetchOnReconnect: false,
     refetchOnWindowFocus: false,
@@ -29,3 +47,58 @@ export function useRootWebAuthnAccount() {
     staleTime: Number.POSITIVE_INFINITY,
   })
 }
+
+function accountFromCredential(credential: RootWebAuthnCredential) {
+  return Account.fromWebAuthnP256(credential, webAuthnRpId ? { rpId: webAuthnRpId } : undefined)
+}
+
+function isRootWebAuthnAccountProvider(value: unknown): value is RootWebAuthnAccountProvider {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      'getAccount' in value &&
+      typeof value.getAccount === 'function' &&
+      'request' in value &&
+      typeof value.request === 'function',
+  )
+}
+
+async function waitForProviderAccount(
+  provider: RootWebAuthnAccountProvider,
+  address: `0x${string}`,
+  timeoutMs = 5_000,
+) {
+  const deadline = Date.now() + timeoutMs
+  const normalizedAddress = address.toLowerCase()
+
+  while (Date.now() < deadline) {
+    const accounts = await provider.request({ method: 'eth_accounts' })
+    if (accounts.some((account) => account.toLowerCase() === normalizedAddress)) return
+
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+
+  throw new Error(`webauthn account ${address} not ready`)
+}
+
+async function waitForStoredCredential(
+  address: `0x${string}`,
+  timeoutMs = 5_000,
+): Promise<RootWebAuthnCredential> {
+  const deadline = Date.now() + timeoutMs
+  const normalizedAddress = address.toLowerCase()
+
+  while (Date.now() < deadline) {
+    const credential = await config.storage?.getItem('webAuthn.activeCredential')
+    if (credential) {
+      const account = accountFromCredential(credential as RootWebAuthnCredential)
+      if (account.address.toLowerCase() === normalizedAddress) {
+        return credential as RootWebAuthnCredential
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+
+  throw new Error(`webauthn credential for ${address} not ready`)
+}
diff --git a/src/lib/useZoneAuthorization.ts b/src/lib/useZoneAuthorization.ts
index b41d1e7f..5fd3bea1 100644
--- a/src/lib/useZoneAuthorization.ts
+++ b/src/lib/useZoneAuthorization.ts
@@ -4,6 +4,8 @@ import { useMutation, useQuery } from '@tanstack/react-query'
 import type { Hex } from 'viem'
 import { Storage as ZoneStorage } from 'viem/tempo'
 
+const zoneAuthorizationInfoTimeoutMs = 5_000
+
 export type ZoneAuthClientLike = {
   zone: {
     getAuthorizationTokenInfo: () => Promise<{
@@ -44,7 +46,10 @@ export function useZoneAuthorization(parameters: {
       if (accountToken) await storage.setItem(chainStorageKey, accountToken)
 
       try {
-        const info = await zoneClient.zone.getAuthorizationTokenInfo()
+        const info = await withTimeout(
+          zoneClient.zone.getAuthorizationTokenInfo(),
+          zoneAuthorizationInfoTimeoutMs,
+        )
         const expired = info.expiresAt <= BigInt(Math.floor(Date.now() / 1000))
         const matchesAccount = info.account.toLowerCase() === lowerAddress
 
@@ -89,17 +94,32 @@ export function useZoneAuthorization(parameters: {
     authorizeMutation,
     error: authorizeMutation.error ?? statusQuery.error,
     isAuthorized: statusQuery.data !== null && statusQuery.data !== undefined,
-    isChecking: statusQuery.isPending,
+    isChecking: statusQuery.fetchStatus === 'fetching',
     statusQuery,
   }
 }
 
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number) {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      const timeout = setTimeout(() => {
+        const error = new Error('zone authorization info request timed out')
+        error.name = 'TimeoutError'
+        reject(error)
+      }, timeoutMs)
+
+      promise.finally(() => clearTimeout(timeout))
+    }),
+  ])
+}
+
 function isZoneAuthorizationError(error: unknown) {
   const status = getErrorStatus(error)
   if (status === 401 || status === 403) return true
 
   const name = getErrorName(error)
-  if (name === 'HttpRequestError') return true
+  if (name === 'HttpRequestError' || name === 'TimeoutError') return true
 
   const message = getErrorMessage(error)
   return /authorization token/i.test(message)
diff --git a/src/pages/protocol/zones/proving.mdx b/src/pages/protocol/zones/proving.mdx
index 38a97edb..c7f21908 100644
--- a/src/pages/protocol/zones/proving.mdx
+++ b/src/pages/protocol/zones/proving.mdx
@@ -3,6 +3,8 @@ title: Zone Proving
 description: Batch submission and proof verification for Tempo zones, including the state transition function, ZK and TEE deployment modes, and ancestry proofs.
 ---
 
+import { StaticMermaidDiagram } from '../../../components/StaticMermaidDiagram'
+
 # Zone Proving
 
 :::info
@@ -63,7 +65,7 @@ The proof verifies that:
 
 ## State Transition Function
 
-The prover takes a complete witness of zone blocks and their dependencies, executes the EVM state transitions, and outputs commitments for onchain verification:
+The prover takes a complete witness of zone blocks and their dependencies, executes the EVM state transitions, and outputs commitments for on-chain verification:
 
 ```rust
 pub fn prove_zone_batch(witness: BatchWitness) -> Result<BatchOutput, Error>
@@ -71,23 +73,22 @@ pub fn prove_zone_batch(witness: BatchWitness) -> Result<BatchOutput, Error>
 
 ### Execution Flow
 
-```mermaid
-flowchart TD
-    A[Batch witness] --> B[Verify Tempo state proofs]
-    B --> C[Initialize zone state from previous block hash]
-    C --> D{Next zone block}
-    D --> E[Check parent hash and block number]
-    E --> F[Verify beneficiary is the sequencer]
-    F --> G[Execute advanceTempo system transaction if present]
-    G --> H[Execute user transactions via revm]
-    H --> I{Final block in batch?}
-    I -- No --> J[Compute simplified zone block hash]
+<StaticMermaidDiagram chart={`flowchart TD
+    A["Batch witness"] --> B["Verify Tempo state proofs"]
+    B --> C["Initialize zone state from previous block hash"]
+    C --> D{"Next zone block"}
+    D --> E["Check parent hash and block number"]
+    E --> F["Verify beneficiary is the sequencer"]
+    F --> G["Execute advanceTempo system transaction if present"]
+    G --> H["Execute user transactions via revm"]
+    H --> I{"Final block in batch?"}
+    I -- No --> J["Compute simplified zone block hash"]
     J --> D
-    I -- Yes --> K[Execute finalizeWithdrawalBatch]
-    K --> L[Compute simplified zone block hash]
-    L --> M[Extract output commitments]
-    M --> N[Return batch output for verification]
-```
+    I -- Yes --> K["Execute finalizeWithdrawalBatch"]
+    K --> L["Compute simplified zone block hash"]
+    L --> M["Extract output commitments"]
+    M --> N["Return batch output for verification"]
+`} />
 
 1. **Verify Tempo state proofs.** Validate MPT proofs for all Tempo storage reads against Tempo state roots.
 2. **Initialize zone state.** Load the zone state from the witness, binding the initial state root to the previous block hash.
@@ -122,7 +123,7 @@ The solution verifies ancestry inside the ZK circuit:
 | Direct | `recentTempoBlockNumber = 0` | Portal reads `tempoBlockNumber` hash from EIP-2935 |
 | Ancestry | `recentTempoBlockNumber > tempoBlockNumber` | Portal reads `recentTempoBlockNumber` hash; proof verifies parent chain |
 
-Proving time increases linearly with the block gap (each gap block adds ~1 keccak operation), but onchain verification cost remains constant. This prevents the zone from becoming stuck after an extended downtime.
+Proving time increases linearly with the block gap (each gap block adds ~1 keccak operation), but on-chain verification cost remains constant. This prevents the zone from becoming stuck after an extended downtime.
 
 ## Tempo State Access