prool 0.2.5 → 0.2.7

package/dist/testcontainers/Instance.js

@@ -1,6 +1,7 @@
-import { GenericContainer, PullPolicy, Wait, } from 'testcontainers';
+import { GenericContainer, Network, PullPolicy, Wait, } from 'testcontainers';
 import * as Instance from '../Instance.js';
 import { command } from '../instances/tempo.js';
+import { command as zoneCommand, } from '../instances/tempoZone.js';
 import * as ContainerOptions from './containerOptions.js';
 /**
  * Defines a Tempo instance.
@@ -86,4 +87,174 @@ export const tempo = Instance.define((parameters) => {
         },
     };
 });
+/**
+ * Defines a Tempo Zone instance.
+ *
+ * Starts a Tempo dev L1 container and a zone container (`tempo-zone dev`) on a
+ * shared network, provisioning a fresh zone against the L1. Pass `l1.rpcUrl`
+ * to attach to an existing L1 instead (the URL must be reachable from inside
+ * the container, e.g. `ws://host.docker.internal:8546`).
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.tempoZone({ port: 9545 })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const tempoZone = Instance.define((parameters) => {
+    const { containerName = `tempo-zone.${crypto.randomUUID()}`, image = 'ghcr.io/tempoxyz/tempo-zone:latest', l1: l1Parameters, log: log_, startupTimeout, ...args } = parameters || {};
+    const log = (() => {
+        try {
+            return JSON.parse(log_);
+        }
+        catch {
+            return log_;
+        }
+    })();
+    const RUST_LOG = log && typeof log !== 'boolean' ? log : '';
+    // L1 ports inside the container (only reachable over the shared network).
+    const l1HttpPort = 8545;
+    const l1WsPort = 8546;
+    const name = 'tempo-zone';
+    let container;
+    let l1Container;
+    let network;
+    let privateRpcPort;
+    async function teardown() {
+        if (container)
+            await container.stop().catch(() => { });
+        if (l1Container)
+            await l1Container.stop().catch(() => { });
+        if (network)
+            await network.stop().catch(() => { });
+        container = undefined;
+        l1Container = undefined;
+        network = undefined;
+        privateRpcPort = undefined;
+    }
+    return {
+        _internal: {
+            args,
+            get l1() {
+                if (!l1Container)
+                    return undefined;
+                return {
+                    host: l1Container.getHost(),
+                    port: l1Container.getMappedPort(l1HttpPort),
+                    wsPort: l1Container.getMappedPort(l1WsPort),
+                };
+            },
+            get privateRpc() {
+                if (!container || !privateRpcPort)
+                    return undefined;
+                return {
+                    host: container.getHost(),
+                    port: container.getMappedPort(privateRpcPort),
+                };
+            },
+        },
+        host: args.host ?? 'localhost',
+        name,
+        port: args.port ?? 9545,
+        async start({ port = args.port }, { emitter, setEndpoint }) {
+            const containerPort = port ?? 9545;
+            // Mirrors the `zoneCommand` default; serves authenticated `eth_*` + `zone_*`.
+            privateRpcPort =
+                args['privateRpc']?.port ??
+                    containerPort + 3;
+            const timeout = ContainerOptions.resolveStartupTimeout(startupTimeout);
+            const logConsumer = (reject) => (stream) => {
+                stream.on('data', (data) => {
+                    const message = data.toString();
+                    emitter.emit('message', message);
+                    emitter.emit('stdout', message);
+                    if (log)
+                        console.log(message);
+                    if (message.includes('shutting down'))
+                        reject(new Error(`Failed to start: ${message}`));
+                });
+                stream.on('error', (error) => {
+                    if (log)
+                        console.error(error.message);
+                    emitter.emit('message', error.message);
+                    emitter.emit('stderr', error.message);
+                    reject(new Error(`Failed to start: ${error.message}`));
+                });
+            };
+            try {
+                // Start a dev L1 on a shared network unless attaching to an existing one.
+                let l1RpcUrl = l1Parameters?.rpcUrl;
+                if (!l1RpcUrl) {
+                    network = await new Network().start();
+                    l1Container = await new GenericContainer(l1Parameters?.image ?? 'ghcr.io/tempoxyz/tempo:latest')
+                        .withPullPolicy(PullPolicy.alwaysPull())
+                        .withPlatform('linux/x86_64')
+                        .withNetwork(network)
+                        .withNetworkAliases('l1')
+                        .withExposedPorts(l1HttpPort, l1WsPort)
+                        .withName(`${containerName}.l1`)
+                        .withEnvironment({ RUST_LOG })
+                        .withCommand(command({
+                        port: l1HttpPort,
+                        // The zone anchors to the L1 over WebSocket.
+                        ws: [true, { addr: '0.0.0.0', api: 'all', port: l1WsPort }],
+                    }))
+                        .withWaitStrategy(Wait.forLogMessage(/Received (block|new payload) from consensus engine/))
+                        .withLogConsumer(logConsumer(() => {
+                        // L1 shutdown surfaces via the zone container failing to start.
+                    }))
+                        .withStartupTimeout(timeout)
+                        .start();
+                    l1RpcUrl = `ws://l1:${l1WsPort}`;
+                }
+                const promise = Promise.withResolvers();
+                let c = new GenericContainer(image)
+                    .withPullPolicy(PullPolicy.alwaysPull())
+                    .withPlatform('linux/x86_64')
+                    .withExposedPorts(containerPort, privateRpcPort)
+                    .withExtraHosts([
+                    { host: 'host.docker.internal', ipAddress: 'host-gateway' },
+                ])
+                    .withName(containerName)
+                    .withEnvironment({ RUST_LOG })
+                    .withCommand(zoneCommand({
+                    ...args,
+                    l1: {
+                        ...(l1Parameters?.factoryAddress
+                            ? { factoryAddress: l1Parameters.factoryAddress }
+                            : {}),
+                        rpcUrl: l1RpcUrl,
+                    },
+                    port: containerPort,
+                }))
+                    // Fires after the public RPC; last server to start.
+                    .withWaitStrategy(Wait.forLogMessage('Private zone RPC server started'))
+                    .withLogConsumer(logConsumer(promise.reject))
+                    .withStartupTimeout(timeout);
+                if (network)
+                    c = c.withNetwork(network);
+                c.start()
+                    .then((started) => {
+                    container = started;
+                    setEndpoint?.({
+                        host: started.getHost(),
+                        port: started.getMappedPort(containerPort),
+                    });
+                    promise.resolve();
+                })
+                    .catch(promise.reject);
+                await promise.promise;
+            }
+            catch (error) {
+                await teardown();
+                throw error;
+            }
+        },
+        async stop() {
+            await teardown();
+        },
+    };
+});
 //# sourceMappingURL=Instance.js.map

package/dist/testcontainers/Instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"Instance.js","sourceRoot":"","sources":["../../src/testcontainers/Instance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Instance.js","sourceRoot":"","sources":["../../src/testcontainers/Instance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "prool",
   "description": "HTTP testing instances for Ethereum",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "sideEffects": false,
   "files": [

package/src/Instance.ts

@@ -3,6 +3,7 @@ import { EventEmitter } from 'eventemitter3'
 export { alto } from './instances/alto.js'
 export { anvil } from './instances/anvil.js'
 export { tempo } from './instances/tempo.js'
+export { tempoZone } from './instances/tempoZone.js'
 
 type EventTypes = {
   exit: [code: number | null, signal: NodeJS.Signals | null]

package/src/instances/tempo.test.ts

@@ -2,6 +2,7 @@ import * as os from 'node:os'
 import getPort from 'get-port'
 import { Instance } from 'prool'
 import { afterEach, expect, test } from 'vitest'
+import { type MessageEvent, WebSocket } from 'ws'
 import { command } from './tempo.js'
 
 const instances: Instance.Instance[] = []
@@ -140,12 +141,34 @@ test(
   },
 )
 
+test(
+  'behavior: serves websocket on http port',
+  { timeout: slowTestTimeout },
+  async () => {
+    const instance = defineInstance()
+    await instance.start()
+
+    const ws = new WebSocket(`ws://localhost:${port}`)
+    await new Promise((resolve, reject) => {
+      ws.addEventListener('open', resolve)
+      ws.addEventListener('error', reject)
+    })
+    ws.send(JSON.stringify({ id: 0, jsonrpc: '2.0', method: 'eth_chainId' }))
+    const { data } = await new Promise<MessageEvent>((resolve) =>
+      ws.addEventListener('message', resolve),
+    )
+    ws.close()
+
+    expect(JSON.parse(data.toString()).result).toBeDefined()
+  },
+)
+
 const redact = (args: string[]) =>
   args.join(' ').replaceAll(os.tmpdir(), '<tmpdir>')
 
 test('command: default', () => {
   expect(redact(command({ port: 8545 }))).toMatchInlineSnapshot(
-    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:8545 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws.port 8565"`,
+    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:8545 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws --ws.addr 0.0.0.0 --ws.api all --ws.port 8545"`,
   )
 })
 
@@ -155,7 +178,7 @@ test('command: behavior: faucet node address', () => {
       command({ faucet: { nodeAddress: 'http://localhost:1337' }, port: 8545 }),
     ),
   ).toMatchInlineSnapshot(
-    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:1337 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws.port 8565"`,
+    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:1337 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws --ws.addr 0.0.0.0 --ws.api all --ws.port 8545"`,
   )
 })
 
@@ -163,7 +186,15 @@ test('command: behavior: faucet disabled', () => {
   expect(
     redact(command({ faucet: { enabled: false }, port: 8545 })),
   ).toMatchInlineSnapshot(
-    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled false --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws.port 8565"`,
+    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled false --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws --ws.addr 0.0.0.0 --ws.api all --ws.port 8545"`,
+  )
+})
+
+test('command: behavior: ws port override', () => {
+  expect(
+    redact(command({ port: 8545, ws: [true, { port: 8565 }] })),
+  ).toMatchInlineSnapshot(
+    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:8545 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 8545 --port 8555 --ws --ws.port 8565"`,
   )
 })
 
@@ -171,6 +202,6 @@ test('command: behavior: http port override', () => {
   expect(
     redact(command({ http: { port: 1337 }, port: 8545 })),
   ).toMatchInlineSnapshot(
-    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:1337 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 1337 --port 8555 --ws.port 8565"`,
+    `"node --authrpc.port 8575 --datadir <tmpdir>/.prool/tempo.8545 --dev --dev.block-time 50ms --engine.disable-precompile-cache --engine.legacy-state-root --faucet.address 0x20c0000000000000000000000000000000000000 0x20c0000000000000000000000000000000000001 0x20c0000000000000000000000000000000000002 0x20c0000000000000000000000000000000000003 --faucet.amount 1000000000000 --faucet.enabled --faucet.private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --faucet.node-address http://localhost:1337 --http.addr 0.0.0.0 --http.api all --http.corsdomain * --http.port 1337 --port 8555 --ws --ws.addr 0.0.0.0 --ws.api all --ws.port 1337"`,
   )
 })

package/src/instances/tempo.ts

@@ -45,9 +45,13 @@ export function command(parameters: tempo.Parameters): string[] {
       port: port!,
     },
     port: port! + 10,
-    ws: {
-      port: port! + 20,
-    },
+    ws: [
+      true,
+      {
+        addr: '0.0.0.0',
+        api: 'all',
+      },
+    ],
   }
 
   const args = deepAssign(defaultParameters, rest)
@@ -58,6 +62,13 @@ export function command(parameters: tempo.Parameters): string[] {
   if (faucet?.enabled && !faucet.nodeAddress)
     faucet.nodeAddress = `http://localhost:${http.port}`
 
+  // WS defaults to the http port: one endpoint (and one proxied server port) serves both protocols.
+  const ws = args['ws'] as [true, { port?: number | undefined }?] | undefined
+  if (Array.isArray(ws) && ws[0] === true) {
+    ws[1] ??= {}
+    ws[1].port ??= http.port
+  }
+
   return [
     'node',
     ...toArgs(args, {

package/src/instances/tempoZone.test.ts

@@ -0,0 +1,60 @@
+import * as os from 'node:os'
+import { expect, test } from 'vitest'
+import { command } from './tempoZone.js'
+
+const redact = (args: string[]) =>
+  args.join(' ').replaceAll(os.tmpdir(), '<tmpdir>')
+
+test('command: default', () => {
+  expect(redact(command({ port: 9545 }))).toMatchInlineSnapshot(
+    `"dev --datadir <tmpdir>/.prool/tempo-zone.9545 --http.addr 0.0.0.0 --http.port 9545 --l1.rpc-url ws://localhost:8546 --private-rpc.port 9548 -- --authrpc.port 9549 --ipcdisable"`,
+  )
+})
+
+test('command: behavior: l1 options', () => {
+  expect(
+    redact(
+      command({
+        l1: {
+          factoryAddress: '0x00000000000000000000000000000000000fac70',
+          rpcUrl: 'ws://l1:8546',
+        },
+        port: 9545,
+      }),
+    ),
+  ).toMatchInlineSnapshot(
+    `"dev --datadir <tmpdir>/.prool/tempo-zone.9545 --http.addr 0.0.0.0 --http.port 9545 --l1.rpc-url ws://l1:8546 --l1.factory-address 0x00000000000000000000000000000000000fac70 --private-rpc.port 9548 -- --authrpc.port 9549 --ipcdisable"`,
+  )
+})
+
+test('command: behavior: dev options', () => {
+  expect(
+    redact(
+      command({
+        dev: {
+          key: '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+          token: '0x20c0000000000000000000000000000000000001',
+        },
+        port: 9545,
+      }),
+    ),
+  ).toMatchInlineSnapshot(
+    `"dev --datadir <tmpdir>/.prool/tempo-zone.9545 --http.addr 0.0.0.0 --http.port 9545 --l1.rpc-url ws://localhost:8546 --private-rpc.port 9548 --dev.key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --dev.token 0x20c0000000000000000000000000000000000001 -- --authrpc.port 9549 --ipcdisable"`,
+  )
+})
+
+test('command: behavior: node args', () => {
+  expect(
+    redact(command({ nodeArgs: ['--full'], port: 9545 })),
+  ).toMatchInlineSnapshot(
+    `"dev --datadir <tmpdir>/.prool/tempo-zone.9545 --http.addr 0.0.0.0 --http.port 9545 --l1.rpc-url ws://localhost:8546 --private-rpc.port 9548 -- --authrpc.port 9549 --ipcdisable --full"`,
+  )
+})
+
+test('command: behavior: private rpc port override', () => {
+  expect(
+    redact(command({ port: 9545, privateRpc: { port: 1337 } })),
+  ).toMatchInlineSnapshot(
+    `"dev --datadir <tmpdir>/.prool/tempo-zone.9545 --http.addr 0.0.0.0 --http.port 9545 --l1.rpc-url ws://localhost:8546 --private-rpc.port 1337 -- --authrpc.port 9549 --ipcdisable"`,
+  )
+})

package/src/instances/tempoZone.ts

@@ -0,0 +1,208 @@
+import * as os from 'node:os'
+import * as path from 'node:path'
+import * as Instance from '../Instance.js'
+import { deepAssign, toArgs } from '../internal/utils.js'
+import { execa } from '../processes/execa.js'
+
+// `tempo-zone dev` derives the WS RPC (port + 1) and P2P (port + 2) ports from
+// `http.port`. Each instance occupies the compact block [port, port + 4].
+export function command(parameters: tempoZone.Parameters): string[] {
+  const { nodeArgs, port, ...rest } = parameters
+
+  const datadir = path.join(os.tmpdir(), '.prool', `tempo-zone.${port}`)
+  const defaultParameters = {
+    datadir,
+    http: {
+      addr: '0.0.0.0',
+      port: port!,
+    },
+    l1: {
+      rpcUrl: 'ws://localhost:8546',
+    },
+    privateRpc: {
+      port: port! + 3,
+    },
+  }
+
+  const args = deepAssign(defaultParameters, rest)
+
+  return [
+    'dev',
+    ...toArgs(args, {
+      arraySeparator: null,
+    }),
+    // Forwarded to `tempo-zone node`; keeps concurrent instances from colliding.
+    '--',
+    '--authrpc.port',
+    String(port! + 4),
+    '--ipcdisable',
+    ...((nodeArgs as string[] | undefined) ?? []),
+  ]
+}
+
+/**
+ * Defines a Tempo Zone instance.
+ *
+ * Provisions a fresh zone against a Tempo dev L1 (`tempo-zone dev`) and runs
+ * the zone node. Requires a reachable Tempo dev L1 websocket RPC (`l1.rpcUrl`).
+ *
+ * @example
+ * ```ts
+ * const instance = Instance.tempoZone({
+ *   l1: { rpcUrl: 'ws://localhost:8546' },
+ *   port: 9545,
+ * })
+ * await instance.start()
+ * // ...
+ * await instance.stop()
+ * ```
+ */
+export const tempoZone = Instance.define(
+  (parameters?: tempoZone.Parameters) => {
+    const { binary = 'tempo-zone', log: log_, ...args } = parameters || {}
+
+    const log = (() => {
+      try {
+        return JSON.parse(log_ as string)
+      } catch {
+        return log_
+      }
+    })()
+    const RUST_LOG = log && typeof log !== 'boolean' ? log : ''
+
+    const name = 'tempo-zone'
+    const process = execa({ name })
+
+    return {
+      _internal: {
+        args,
+        get process() {
+          return process._internal.process
+        },
+      },
+      host: args.host ?? 'localhost',
+      name,
+      port: args.port ?? 9545,
+      async start({ port = args.port }, options) {
+        return await process.start(
+          ($) =>
+            $({
+              env: {
+                RUST_LOG,
+              },
+            })`${[binary, ...command({ ...args, port })]}`,
+          {
+            ...options,
+            // Resolve when the private zone RPC is listening (last server to start).
+            resolver({ process, reject, resolve }) {
+              let stderr = ''
+              process.stdout.on('data', (data) => {
+                const message = data.toString()
+                if (log) console.log(message)
+                if (message.includes('Private zone RPC server started'))
+                  resolve()
+                if (message.includes('shutting down')) reject('shutting down')
+              })
+              process.stderr.on('data', (data) => {
+                const message = data.toString()
+                if (log) console.error(message)
+                stderr += message
+              })
+              // Provisioning failures (e.g. unreachable L1) exit non-zero before the RPC starts.
+              process.once('exit', (code) => {
+                if (code) reject(stderr || `exited with code ${code}`)
+              })
+            },
+          },
+        )
+      },
+      async stop() {
+        await process.stop()
+      },
+    }
+  },
+)
+
+export declare namespace tempoZone {
+  export type Parameters = {
+    /**
+     * Path or alias to the Tempo Zone binary.
+     */
+    binary?: string | undefined
+    /**
+     * Directory for genesis.json, zone.json, node data, and logs. Wiped on start.
+     */
+    datadir?: string | undefined
+    /**
+     * Dev provisioning options.
+     */
+    dev?:
+      | {
+          /**
+           * Dev private key (hex): L1 fee payer, factory deployer, portal admin,
+           * and zone sequencer.
+           */
+          key?: string | undefined
+          /**
+           * Initial TIP-20 token enabled on the portal.
+           * @default pathUSD (0x20c0000000000000000000000000000000000000)
+           */
+          token?: string | undefined
+        }
+      | undefined
+    /**
+     * Host the server will listen on.
+     */
+    host?: string | undefined
+    /**
+     * Tempo L1 options.
+     */
+    l1?:
+      | {
+          /**
+           * Existing ZoneFactory address on the L1. Deploys the bundled factory
+           * when omitted.
+           */
+          factoryAddress?: string | undefined
+          /**
+           * Tempo L1 WebSocket RPC URL.
+           * @default "ws://localhost:8546"
+           */
+          rpcUrl?: string | undefined
+        }
+      | undefined
+    /**
+     * Rust log level configuration (sets RUST_LOG environment variable).
+     * Can be a log level or a custom filter string.
+     */
+    log?:
+      | 'trace'
+      | 'debug'
+      | 'info'
+      | 'warn'
+      | 'error'
+      | (string & {})
+      | boolean
+      | undefined
+    /**
+     * Extra arguments forwarded to `tempo-zone node`.
+     */
+    nodeArgs?: string[] | undefined
+    /**
+     * Port the server will listen on.
+     */
+    port?: number | undefined
+    /**
+     * Private RPC options.
+     */
+    privateRpc?:
+      | {
+          /**
+           * Zone private RPC port.
+           * @default `port + 3`
+           */
+          port?: number | undefined
+        }
+      | undefined
+  } & Record<string, unknown>
+}