Merge pull request #742 from AugurProject/t3code/check-liquidator-deployment-1

Guard liquidator scans until deployment

Author: KillariDev

bots/liquidator/README.md

@@ -409,7 +409,7 @@ bun run check
 The reusable Ethereum, connectivity, quorum, block synchronization, signer gate,
 retry, and transaction-submission primitives live in `../shared`.
 
-> Live liquidation is experimental. Use a dedicated low-balance signer, begin on
-> Sepolia, keep dry-run logs, and supervise pool health. Assumed pool open interest
+> Use a dedicated low-balance signer, begin on Sepolia, keep dry-run logs, and
+> supervise pool health. Assumed pool open interest
 > remains an economic obligation even when the fixed liquidation bonus is
 > positive.

bots/liquidator/src/cli/run.ts

@@ -28,6 +28,7 @@ import { clearOrphanedDexEvidenceForHeadReplacement, discardDexMarketObservation
 import { canonicalBlockHash, chainFor, desiredPoolStatus } from '#monitoring/operator-chain'
 import { canonicalMarketPriceAllowsExecution, marketConfigurations, marketPriceAllowsExecution, selectedCandidate } from '#core/candidate-selection'
 import { reconcilePendingStagedOperations, recoverPendingTransactions } from '#execution/recovery'
+import { createSystemDeploymentGate } from '#core/deployment-gate'
 
 const constantProductPairAbi = [
 	{ inputs: [], name: 'token0', outputs: [{ type: 'address' }], stateMutability: 'view', type: 'function' },
@@ -397,6 +398,8 @@ async function runOperator(loaded: Awaited<ReturnType<typeof loadSettings>>, pro
 		status: 'info',
 	})
 	let lastDryRunKey: string | undefined
+	let missingDeploymentAddress: string | undefined
+	const checkSystemDeployment = createSystemDeploymentGate()
 	await pollUntilStopped(
 		async () => {
 			if (shutdown.isRequested()) return true
@@ -408,6 +411,21 @@ async function runOperator(loaded: Awaited<ReturnType<typeof loadSettings>>, pro
 				const currentChain = chainFor(settings)
 				chain = currentChain
 				client = createPrimaryClient()
+				const deploymentStatus = await checkSystemDeployment(client, settings.network.chainId, settings.deployment)
+				if (!deploymentStatus.deployed) {
+					state.status = state.paused ? 'paused' : 'starting'
+					if (missingDeploymentAddress !== deploymentStatus.address) {
+						recordActivity(state, {
+							details: `chain=${settings.network.chainId.toString()} contract=${deploymentStatus.address}`,
+							kind: 'deployment',
+							message: `${deploymentStatus.name} is not deployed; waiting before checking again`,
+							status: 'info',
+						})
+						missingDeploymentAddress = deploymentStatus.address
+					}
+					return 'deferred'
+				}
+				missingDeploymentAddress = undefined
 				let primary
 				if (settings.runtime.execute) {
 					const endpoints = [settings.connectivity.readRpcUrl, ...settings.connectivity.quorumRpcUrls]

bots/liquidator/src/core/deployment-gate.ts

@@ -0,0 +1,39 @@
+import type { Address, Hex } from '@zoltar/bot-shared/ethereum'
+
+type DeploymentReader = {
+	getCode(parameters: { address: Address }): Promise<Hex | undefined>
+}
+
+type CoreDeployment = {
+	securityPoolFactory: Address
+	weth: Address
+	zoltar: Address
+}
+
+export type SystemDeploymentStatus = { deployed: true } | { address: Address; deployed: false; name: string }
+
+export async function systemDeploymentStatus(client: DeploymentReader, deployment: CoreDeployment): Promise<SystemDeploymentStatus> {
+	const contracts = [
+		{ address: deployment.zoltar, name: 'Zoltar' },
+		{ address: deployment.securityPoolFactory, name: 'security-pool factory' },
+		{ address: deployment.weth, name: 'WETH' },
+	] as const
+
+	for (const contract of contracts) {
+		const code = await client.getCode({ address: contract.address })
+		if (code === undefined || code === '0x') return { ...contract, deployed: false }
+	}
+	return { deployed: true }
+}
+
+export function createSystemDeploymentGate() {
+	let verifiedDeployment: string | undefined
+	return async (client: DeploymentReader, chainId: number, deployment: CoreDeployment): Promise<SystemDeploymentStatus> => {
+		const deploymentKey = `${chainId.toString()}:${deployment.zoltar}:${deployment.securityPoolFactory}:${deployment.weth}`
+		if (verifiedDeployment === deploymentKey) return { deployed: true }
+		verifiedDeployment = undefined
+		const status = await systemDeploymentStatus(client, deployment)
+		if (status.deployed) verifiedDeployment = deploymentKey
+		return status
+	}
+}

bots/liquidator/tests/cli/run-startup.test.ts

@@ -20,6 +20,14 @@ async function waitForJson(origin: string, path: string) {
 	throw new Error('Dashboard did not become ready')
 }
 
+async function waitForRpcMethod(methods: string[], method: string) {
+	for (let attempt = 0; attempt < 100; attempt++) {
+		if (methods.includes(method)) return
+		await Bun.sleep(20)
+	}
+	throw new Error(`Liquidator did not call ${method}`)
+}
+
 afterEach(async () => {
 	for (const child of children.splice(0)) {
 		child.kill()
@@ -174,3 +182,45 @@ test('rejects a wrong-chain private relay during startup validation', async () =
 	expect(exitCode).toBe(1)
 	expect(output).toContain('Expected chain 11155111, received 1')
 })
+
+test('queries only deployment bytecode when the configured system is undeployed', async () => {
+	const directory = await mkdtemp(join(tmpdir(), 'zoltar-liquidator-undeployed-'))
+	directories.push(directory)
+	const methods: string[] = []
+	const rpc = Bun.serve({
+		async fetch(request) {
+			const body = (await request.json()) as { id: unknown; method: string }
+			methods.push(body.method)
+			return Response.json({ id: body.id, jsonrpc: '2.0', result: body.method === 'eth_chainId' ? '0xaa36a7' : '0x' })
+		},
+		hostname: '127.0.0.1',
+		port: 0,
+	})
+	servers.push(rpc)
+	if (rpc.port === undefined) throw new Error('Test RPC did not expose a port')
+	const examplePath = join(import.meta.dir, '..', '..', 'config', 'operator.example.json')
+	const configuration = JSON.parse(await Bun.file(examplePath).text()) as {
+		connectivity: { publicRpcUrls: string[]; quorumRpcUrls: string[]; readRpcUrl: string }
+		runtime: { pollMilliseconds: number; stateFile: string; ui: boolean }
+	}
+	const rpcUrl = `http://127.0.0.1:${rpc.port.toString()}`
+	configuration.connectivity = { publicRpcUrls: [rpcUrl], quorumRpcUrls: [], readRpcUrl: rpcUrl }
+	Reflect.set(configuration, 'network', { chainId: 11_155_111, explorerUrl: 'https://sepolia.etherscan.io', name: 'sepolia' })
+	configuration.runtime.pollMilliseconds = 1_000
+	configuration.runtime.stateFile = join(directory, 'state.json')
+	configuration.runtime.ui = false
+	const configurationPath = join(directory, 'operator.json')
+	await writeFile(configurationPath, JSON.stringify(configuration), 'utf8')
+	const child = Bun.spawn([process.execPath, join(import.meta.dir, '..', '..', 'src', 'cli', 'run.ts')], {
+		cwd: join(import.meta.dir, '..', '..'),
+		env: { ...process.env, ZOLTAR_LIQUIDATOR_CONFIG: configurationPath },
+		stderr: 'pipe',
+		stdout: 'pipe',
+	})
+	children.push(child)
+
+	await waitForRpcMethod(methods, 'eth_getCode')
+	const deploymentCheckIndex = methods.indexOf('eth_getCode')
+	await Bun.sleep(100)
+	expect(methods.slice(deploymentCheckIndex)).toEqual(['eth_getCode'])
+})

bots/liquidator/tests/core/deployment-gate.test.ts

@@ -0,0 +1,91 @@
+import { expect, test } from 'bun:test'
+import { createSystemDeploymentGate, systemDeploymentStatus } from '#core/deployment-gate'
+
+const zoltar = '0x0000000000000000000000000000000000000001' as const
+const securityPoolFactory = '0x0000000000000000000000000000000000000002' as const
+const weth = '0x0000000000000000000000000000000000000003' as const
+
+test('stops deployment checks at the first contract without runtime bytecode', async () => {
+	const queried: string[] = []
+	const status = await systemDeploymentStatus(
+		{
+			getCode: async ({ address }) => {
+				queried.push(address)
+				return undefined
+			},
+		},
+		{ securityPoolFactory, weth, zoltar },
+	)
+
+	expect(status).toEqual({ address: zoltar, deployed: false, name: 'Zoltar' })
+	expect(queried).toEqual([zoltar])
+})
+
+test('requires runtime bytecode for every core system contract', async () => {
+	const queried: string[] = []
+	const status = await systemDeploymentStatus(
+		{
+			getCode: async ({ address }) => {
+				queried.push(address)
+				return address === securityPoolFactory ? '0x' : '0x6000'
+			},
+		},
+		{ securityPoolFactory, weth, zoltar },
+	)
+
+	expect(status).toEqual({ address: securityPoolFactory, deployed: false, name: 'security-pool factory' })
+	expect(queried).toEqual([zoltar, securityPoolFactory])
+})
+
+test('reports the system deployed only after all core contracts have runtime bytecode', async () => {
+	const queried: string[] = []
+	const status = await systemDeploymentStatus(
+		{
+			getCode: async ({ address }) => {
+				queried.push(address)
+				return '0x6000'
+			},
+		},
+		{ securityPoolFactory, weth, zoltar },
+	)
+
+	expect(status).toEqual({ deployed: true })
+	expect(queried).toEqual([zoltar, securityPoolFactory, weth])
+})
+
+test('caches a verified deployment across scan cycles and resets for another chain', async () => {
+	const queried: string[] = []
+	const client = {
+		getCode: async ({ address }: { address: string }) => {
+			queried.push(address)
+			return '0x6000' as const
+		},
+	}
+	const checkDeployment = createSystemDeploymentGate()
+
+	await expect(checkDeployment(client, 1, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ deployed: true })
+	await expect(checkDeployment(client, 1, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ deployed: true })
+	expect(queried).toHaveLength(3)
+
+	await expect(checkDeployment(client, 2, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ deployed: true })
+	expect(queried).toHaveLength(6)
+})
+
+test('does not reuse readiness after an intervening undeployed identity', async () => {
+	const queried: string[] = []
+	let deployed = true
+	const client = {
+		getCode: async ({ address }: { address: string }) => {
+			queried.push(address)
+			return deployed ? ('0x6000' as const) : undefined
+		},
+	}
+	const checkDeployment = createSystemDeploymentGate()
+
+	await expect(checkDeployment(client, 1, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ deployed: true })
+	deployed = false
+	await expect(checkDeployment(client, 2, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ address: zoltar, deployed: false, name: 'Zoltar' })
+	deployed = true
+	await expect(checkDeployment(client, 1, { securityPoolFactory, weth, zoltar })).resolves.toEqual({ deployed: true })
+	expect(queried).toHaveLength(7)
+})

bots/open-oracle-arbitrager/README.md

@@ -15,10 +15,9 @@ Dry-run is the example default. The bot cannot submit a transaction unless
 `runtime.execute` is enabled in its configuration and a signer is saved in that
 configuration or supplied through the local dashboard.
 
-> **Live execution is experimental.** Mainnet commands below are operator
-> references, not production approval. Rehearse on Sepolia with a dedicated
-> low-balance key, validate current executable liquidity, and supervise every
-> position; no automated strategy can guarantee a profit or prevent every loss.
+> Use a dedicated low-balance key, validate current executable liquidity, and
+> supervise every position; no automated strategy can guarantee a profit or prevent
+> every loss.
 > The [latest pinned market fixture](./docs/market-fixture.html#open-oracle-market-fixture)
 > is dated historical evidence, not a live liquidity or profitability claim.
 
@@ -143,41 +142,6 @@ dashboard binds to `127.0.0.1`; the host-loopback container setup is documented
 under [Docker](#docker). The execution key still lives in the bot process and must
 be protected like any hot wallet.
 
-## End-user readiness backlog
-
-The repository implementation is a guarded operator tool, not yet a supported
-retail release. Complete these items before declaring or packaging a supported
-end-user release. The commands below remain experimental operator references:
-
-1. Publish separate, reviewed mainnet and Sepolia **execution manifests** containing
-   the deployed executor, OpenOracle, approved coordinators, router, factory,
-   quoter, WETH, and executable tokens with runtime bytecode hashes. The protocol
-   deployment manifests for other projects are not a substitute for this bot trust
-   root.
-2. Deploy and source-verify the stateless executor on each supported network, then
-   reproduce every manifest hash through at least two independently operated RPCs.
-3. Run a funded, low-limit Sepolia rehearsal covering entry, replacement, normal
-   settlement, withdrawal, restart after each journal stage, relay rejection,
-   RPC disagreement, and signer-authorized manual reconciliation. Retain transaction
-   hashes and recovery evidence as release artifacts.
-4. Add an external signer or encrypted-keystore interface so routine operators do
-   not need to paste a raw private key into the dashboard or save it in plaintext.
-   Until then, use a dedicated low-balance key and leave **Save this new key in
-   plaintext for future restarts** off.
-5. Extend the deterministic interrupted-write, partial-relay, same-origin RPC,
-   clock-skew, and deep-reorganization tests with host-level disk-full and
-   provider-specific chaos rehearsals.
-6. Publish a supported relay/RPC compatibility matrix and continuously exercise
-   exact bundle simulation, submission, receipt, and archive-read behavior against
-   those providers.
-7. Package a versioned release with pinned Bun support, checksums or signatures,
-   reproducible installation, default service supervision, log rotation, health
-   checks, and alerts for paused, syncing, error, stale-head, recovery-required,
-   low-inventory, and unconfirmed-bundle states.
-8. Commission an independent review of the final deployed addresses, manifests,
-   signer integration, release package, and funded rehearsal evidence. Repeat the
-   review whenever execution dependencies or token allowlists change.
-
 ## Install
 
 From the monorepo root, install the root package before entering the arbitrager
@@ -1321,7 +1285,6 @@ entry from depending on wallet inventory already committed to recovery.
   tokens, OpenOracle/Uniswap defects, compromised keys, and market movement can
   still cause loss. Start on Sepolia, use a dedicated low-balance wallet, set small
   risk limits, and supervise every live position.
-- A profitable dry-run observation is not production approval. Before enabling
-  execution, verify the current pools, relay simulations, inventory, risk limits,
+- Before enabling execution, verify the current pools, relay simulations, inventory, risk limits,
   deployment manifest, settlement path, and recovery procedure with a low-value
-  rehearsal.
+  transaction.

bots/open-oracle-arbitrager/docs/operator-guide.html

@@ -12,8 +12,8 @@
 				<h1>OpenOracle Arbitrager</h1>
 				<p>This operator guide explains how the bot discovers OpenOracle games, compares their exchange rate with onchain liquidity, submits an atomic hedge and dispute, and accounts for the final withdrawal. It covers the operator configuration, local dashboard, strategy math, supported exchanges, durable recovery, and the balances an execution wallet needs.</p>
 				<div class="callout">
-					<strong>Experimental operator software</strong>
-					Dry-run first, rehearse with a dedicated low-balance key on Sepolia, and supervise every funded position. A modeled profit is not a guarantee: fees, failed inclusion, later disputes, token behavior, RPC failure, MEV, and market movement can still cause loss.
+					<strong>Execution risk</strong>
+					Use a dedicated low-balance key and supervise every funded position. A modeled profit is not a guarantee: fees, failed inclusion, later disputes, token behavior, RPC failure, MEV, and market movement can still cause loss.
 				</div>
 				<nav class="guide-nav" aria-label="Guide sections">
 					<a href="#quick-start">Quick start</a>

bots/open-oracle-arbitrager/src/dashboard/dashboard.ts

@@ -995,8 +995,8 @@ function render(snapshot: PublicOperatorSnapshot) {
 		launchNotice.dataset['tone'] = 'warning'
 	} else {
 		launchNotice.hidden = true
-		setText('launch-notice-title', 'Sepolia rehearsal network')
-		setText('launch-notice-copy', 'Use this network to rehearse execution and recovery. Testnet success is not production approval.')
+		setText('launch-notice-title', 'Sepolia network')
+		setText('launch-notice-copy', 'Use this network to exercise execution and recovery with a dedicated low-balance key and low risk limits.')
 		launchNotice.dataset['tone'] = 'warning'
 	}
 	const notice = element('notice')

bots/open-oracle-arbitrager/tests/dashboard/dashboard-server.test.ts

@@ -205,7 +205,8 @@ test('serves dashboard state and protects mutable controls with same-origin JSON
 	expect(browserSource).toContain('aria-labelledby')
 	expect(browserSource).toContain('Recent exact price samples')
 	expect(browserSource).toContain('Mainnet execution network')
-	expect(browserSource).toContain('Sepolia rehearsal network')
+	expect(browserSource).toContain('Sepolia network')
+	expect(browserSource).not.toContain('production approval')
 	expect(browserSource).toContain('details.dataset["reportId"]')
 	expect(browserSource).toContain('focus({ preventScroll: true })')
 	expect(browserSource).toContain('stroke-dasharray')