tapimo 0.10.2 → 0.12.0

package/src/internal/EarnVaults.test.ts

@@ -1,6 +1,7 @@
 import { parseAbi } from 'viem'
 import { tempoTestnet } from 'viem/tempo/chains'
 
+import * as TestEarn from '../../test/Earn.js'
 import * as Runtime from '../../test/runtime.js'
 import * as TestViem from '../../test/Viem.js'
 import * as Zones from '../apps/Zones.js'
@@ -43,6 +44,17 @@ describe('schema.ResolveInput', () => {
   })
 })
 
+describe('schema.ZoneRoute', () => {
+  test('normalizes the router address', () => {
+    expect(
+      EarnVaults.schema.ZoneRoute.parse({
+        ...TestEarn.zoneRoute,
+        earnRouter: TestEarn.zoneRoute.earnRouter.toUpperCase().replace('0X', '0x'),
+      }),
+    ).toStrictEqual(TestEarn.zoneRoute)
+  })
+})
+
 describe('classifyEngineType', () => {
   test('classifies supported capability fingerprints', () => {
     expect([
@@ -193,3 +205,70 @@ describe('resolve', () => {
     60_000,
   )
 })
+
+describe('resolveZoneRoutes', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'verifies immutable router bindings and derives private tokens',
+    async () => {
+      const getClient = Viem.createGetClient({
+        defaultChainId: tempoTestnet.id,
+        rpc: TestViem.rpc,
+        zones: [TestEarn.zone],
+      })
+      const discovery = await EarnVaults.resolve({
+        getClient,
+        input: {
+          chainId: tempoTestnet.id,
+          vaultAddress: TestEarn.zoneVaultAddress,
+        },
+        zones: [TestEarn.zone],
+      })
+      const routes = await EarnVaults.resolveZoneRoutes({
+        discovery,
+        getClient,
+        routes: [TestEarn.zoneRoute],
+        zones: [TestEarn.zone],
+      })
+
+      expect(routes).toHaveLength(1)
+      expect(routes[0]).toMatchObject({
+        ...TestEarn.zoneRoute,
+        name: TestEarn.zone.name,
+      })
+      expect(routes[0]?.inputTokens).toHaveLength(1)
+      expect(routes[0]?.outputTokens).toStrictEqual(routes[0]?.inputTokens)
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [TestEarn.zoneRoute, TestEarn.zoneRoute],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `[EarnVaults.InvalidRegistryError: Zone 1424310001 is configured more than once.]`,
+      )
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [
+            { ...TestEarn.zoneRoute, deploymentBlock: TestEarn.zoneRoute.deploymentBlock + 1 },
+          ],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toMatchObject({
+        result: {
+          issues: [
+            {
+              actual: String(TestEarn.zoneRoute.deploymentBlock + 1),
+              code: 'zone-deployment-block-mismatch',
+              message: 'Earn router deployment block does not match its code boundary.',
+            },
+          ],
+          status: 'mismatch',
+        },
+      })
+    },
+    60_000,
+  )
+})

package/src/internal/EarnVaults.ts

@@ -1,3 +1,4 @@
+import { ZoneId } from 'ox/tempo'
 import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
@@ -161,6 +162,28 @@ export namespace schema {
     })
     .check(z.describe('Onchain identity of an Earn vault.'))
 
+  /** Schema for one curated Earn route through a private Zone. */
+  export const ZoneRoute = z
+    .strictObject({
+      chainId: Schema.ChainId.check(
+        z.describe('Private Zone chain id.'),
+        z.meta({ examples: [1424310001] }),
+      ),
+      deploymentBlock: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Parent-chain block that deployed the Earn router.'),
+          z.meta({ examples: [31039238] }),
+        ),
+      earnRouter: Schema.Address.check(
+        z.describe('Parent-chain router for this Zone and Earn vault.'),
+        z.meta({ examples: ['0x9144086a79dea966d8bf1b52125ebed8919fc45c'] }),
+      ),
+    })
+    .check(z.describe('Curated Earn route through one private Zone.'))
+
   /** Schema for live state resolved from one Earn vault. */
   export const Discovery = z
     .strictObject({
@@ -228,12 +251,48 @@ export type Discovery = z.output<typeof schema.Discovery>
 /** Onchain identity of an Earn vault. */
 export type ResolveInput = z.output<typeof schema.ResolveInput>
 
+/** Curated Earn route through one private Zone. */
+export type ZoneRoute = z.output<typeof schema.ZoneRoute>
+
+/** Curated Zone route with immutable router bindings resolved onchain. */
+export type ResolvedZoneRoute = ZoneRoute & {
+  /** Tokens accepted by private deposits. */
+  inputTokens: readonly Address[]
+  /** Configured private Zone name. */
+  name: string
+  /** Tokens returned by private redemptions. */
+  outputTokens: readonly Address[]
+}
+
+/** Adds capabilities proven by a verified private Zone route. */
+export function addZoneRouteCapabilities(
+  capabilities: NonNullable<Discovery['capabilities']>,
+): NonNullable<Discovery['capabilities']> {
+  return { ...capabilities, privateRouting: true, routerSwaps: true }
+}
+
+/** Derives a Zone ID from any supported Zone chain-ID scheme. */
+export function deriveZoneId(chainId: number): number {
+  for (const sourceId of [4_217, 42_431] satisfies readonly ZoneId.SourceId[]) {
+    const zoneId = ZoneId.fromChainId(chainId, sourceId)
+    if (zoneId >= 0 && ZoneId.toChainId(zoneId, sourceId) === chainId) return zoneId
+  }
+  throw new InvalidRegistryError(`Chain ${chainId} does not use a supported Zone chain-ID scheme.`)
+}
+
 /** Stable code describing an onchain verification issue. */
 export type VerificationIssueCode =
   | 'chain-mismatch'
   | 'engine-asset-mismatch'
   | 'policy-unsupported'
   | 'read-failed'
+  | 'zone-deployment-block-mismatch'
+  | 'zone-flow-unsupported'
+  | 'zone-id-mismatch'
+  | 'zone-router-invalid'
+  | 'zone-share-mismatch'
+  | 'zone-vault-asset-mismatch'
+  | 'zone-vault-mismatch'
 
 /** One onchain verification issue. */
 export type VerificationIssue = {
@@ -303,6 +362,16 @@ type RouterCapabilities = {
   redeem: boolean
 }
 
+type ZoneRouteBindings = {
+  allowedZoneId: number
+  deposit: boolean
+  earnShare: Address
+  earnVault: Address
+  privateAsset: Address
+  redeem: boolean
+  vaultAsset: Address
+}
+
 type TokenMetadata = Omit<Discovery['assetToken'], 'address'>
 
 const engineBindingsAbi = parseAbi(['function vault() view returns (address)'])
@@ -363,6 +432,139 @@ export declare namespace resolve {
   }
 }
 
+/** Resolves and verifies every curated Zone route for one Earn vault. */
+export async function resolveZoneRoutes(
+  options: resolveZoneRoutes.Options,
+): Promise<ResolvedZoneRoute[]> {
+  const result = z.array(schema.ZoneRoute).safeParse(options.routes)
+  if (!result.success) throw invalid(result.error)
+
+  const chainIds = new Set<number>()
+  const routers = new Set<string>()
+  for (const route of result.data) {
+    if (chainIds.has(route.chainId))
+      throw new InvalidRegistryError(`Zone ${route.chainId} is configured more than once.`)
+    if (routers.has(route.earnRouter))
+      throw new InvalidRegistryError(
+        `Earn router ${route.earnRouter} is configured more than once.`,
+      )
+    chainIds.add(route.chainId)
+    routers.add(route.earnRouter)
+  }
+  if (result.data.length === 0) return []
+
+  const client = options.getClient(options.discovery.chainId)
+  return Promise.all(
+    result.data.map(async (route) => {
+      const zone = options.zones.find((candidate) => candidate.id === route.chainId)
+      if (!zone) throw new InvalidRegistryError(`Zone ${route.chainId} is not configured.`)
+      if (zone.sourceId !== options.discovery.chainId)
+        throw new InvalidRegistryError(
+          `Zone ${route.chainId} does not belong to chain ${options.discovery.chainId}.`,
+        )
+      const expectedZoneId = deriveZoneId(route.chainId)
+
+      const [code, previousCode] = await Promise.all([
+        client.getCode({
+          address: route.earnRouter,
+          blockNumber: BigInt(route.deploymentBlock),
+        }),
+        route.deploymentBlock === 0
+          ? undefined
+          : client.getCode({
+              address: route.earnRouter,
+              blockNumber: BigInt(route.deploymentBlock - 1),
+            }),
+      ])
+      if (!code || code === '0x' || (previousCode !== undefined && previousCode !== '0x'))
+        throw mismatch({
+          discovery: options.discovery,
+          issues: [
+            {
+              actual: String(route.deploymentBlock),
+              code: 'zone-deployment-block-mismatch',
+              message: 'Earn router deployment block does not match its code boundary.',
+            },
+          ],
+        })
+
+      const bindings = await readZoneRouteBindings(client, { earnRouter: route.earnRouter }).catch(
+        (error) => {
+          if (!isMissingOptionalFunctionError(error)) throw error
+          throw mismatch({
+            discovery: options.discovery,
+            issues: [
+              {
+                actual: route.earnRouter,
+                code: 'zone-router-invalid',
+                message: 'Earn router does not expose the required immutable bindings.',
+              },
+            ],
+          })
+        },
+      )
+      const issues: VerificationIssue[] = []
+      if (bindings.allowedZoneId !== expectedZoneId)
+        issues.push({
+          actual: bindings.allowedZoneId.toString(),
+          code: 'zone-id-mismatch',
+          expected: String(expectedZoneId),
+          message: 'Earn router is configured for a different Zone.',
+        })
+      compareAddress(
+        issues,
+        'zone-vault-mismatch',
+        'Earn router is configured for a different Earn vault.',
+        options.discovery.vaultAddress,
+        bindings.earnVault,
+      )
+      compareAddress(
+        issues,
+        'zone-vault-asset-mismatch',
+        'Earn router vault asset does not match the Earn vault.',
+        options.discovery.assetToken.address,
+        bindings.vaultAsset,
+      )
+      compareAddress(
+        issues,
+        'zone-share-mismatch',
+        'Earn router share token does not match the Earn vault.',
+        options.discovery.shareToken.address,
+        bindings.earnShare,
+      )
+      if (!bindings.deposit || !bindings.redeem)
+        issues.push({
+          actual: `deposit=${bindings.deposit},redeem=${bindings.redeem}`,
+          code: 'zone-flow-unsupported',
+          expected: 'deposit=true,redeem=true',
+          message: 'Earn router must support private deposits and redemptions.',
+        })
+      if (issues.length > 0) throw mismatch({ discovery: options.discovery, issues })
+
+      return {
+        ...route,
+        inputTokens: [bindings.privateAsset],
+        name: zone.name,
+        outputTokens: [bindings.privateAsset],
+      }
+    }),
+  )
+}
+
+export declare namespace resolveZoneRoutes {
+  /** Inputs for resolving and verifying curated Zone routes. */
+  type Options = {
+    /** Live state of the Earn vault bound by every router. */
+    discovery: Discovery
+    /** Resolves the parent-chain client used to read each router. */
+    getClient: Viem.GetClient
+    /** Curated Zone routes to verify. */
+    routes: unknown
+    /** Private Zones configured by the API. */
+    zones: readonly Chain[]
+  }
+}
+
 /** Infers the supported engine type from its capability fingerprint. */
 export function classifyEngineType(
   options: classifyEngineType.Options,
@@ -729,6 +931,60 @@ declare namespace readEngineBindings {
   }
 }
 
+async function readZoneRouteBindings(
+  client: Client,
+  options: readZoneRouteBindings.Options,
+): Promise<ZoneRouteBindings> {
+  const [allowedZoneId, earnShare, earnVault, privateAsset, vaultAsset, deposit, redeem] =
+    await Promise.all([
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'allowedZoneId',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'earnShare',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'earnVault',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'privateAsset',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'vaultAsset',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        args: [0],
+        functionName: 'supportsFlow',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        args: [1],
+        functionName: 'supportsFlow',
+      }),
+    ])
+  return { allowedZoneId, deposit, earnShare, earnVault, privateAsset, redeem, vaultAsset }
+}
+
+declare namespace readZoneRouteBindings {
+  type Options = {
+    /** Parent-chain Earn router to inspect. */
+    earnRouter: Address
+  }
+}
+
 async function readRouterCapabilities(
   client: Client,
   options: readRouterCapabilities.Options,
@@ -840,6 +1096,27 @@ function compareAddress(
   if (!isAddressEqual(actual, expected)) issues.push({ actual, code, expected, message })
 }
 
+function mismatch(options: mismatch.Options): VerificationError {
+  return new VerificationError({
+    issues: options.issues,
+    snapshot: {
+      assetToken: options.discovery.assetToken,
+      isSynced: options.discovery.state.isAccountingAligned,
+      shareToken: options.discovery.shareToken,
+    },
+    status: 'mismatch',
+  })
+}
+
+declare namespace mismatch {
+  type Options = {
+    /** Live vault state captured with the mismatch. */
+    discovery: Discovery
+    /** Verification issues that rejected the deployment. */
+    issues: readonly VerificationIssue[]
+  }
+}
+
 function unavailable(): VerificationUnavailable {
   return {
     issues: [