tapimo 0.13.0 → 0.15.0

package/src/db/tables/rewardTransactionAttempts.ts

@@ -0,0 +1,272 @@
+import { sql, type ColumnType, type JSONColumnType, type Selectable } from 'kysely'
+import type { Address, Hex } from 'viem'
+import { customAlphabet } from 'nanoid'
+
+import type * as Campaigns from '../../internal/rewards/Campaigns.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+const id = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyz', 24)
+
+/** Columns of the `reward_transaction_attempts` table. */
+export type Table = Omit<db_Schema.RewardTransactionAttempt, 'chainId' | 'intent' | 'receipt'> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+  /** Typed transaction intent. */
+  intent: JSONColumnType<Campaigns.TransactionIntent, string, string>
+  /** Canonical receipt evidence. */
+  receipt: JSONColumnType<Campaigns.TransactionReceipt | null, string | null, string | null>
+}
+
+/** A stored signed transaction attempt. */
+export type Record = db_Schema.RewardTransactionAttempt
+
+/** Creates a typed attempt before requesting a signature. */
+export async function create(db: Db.Db, options: create.Options): Promise<Record> {
+  const now = new Date().toISOString()
+  const row = await db.kysely
+    .insertInto('reward_transaction_attempts')
+    .values({
+      chainId: options.chainId,
+      confirmedBlockHash: null,
+      createdAt: now,
+      expiresAt: null,
+      id: `rat_${id()}`,
+      intent: JSON.stringify(options.intent),
+      intentId: options.intent.id,
+      nonce: null,
+      receipt: null,
+      replacementOf: options.replacementOf ?? null,
+      runId: options.runId ?? null,
+      signedBytes: null,
+      signer: normalize(options.signer),
+      state: 'created',
+      transactionHash: null,
+      updatedAt: now,
+      vaultAddress: normalize(options.vaultAddress),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+  return toRecord(row)
+}
+
+export declare namespace create {
+  /** Typed transaction attempt input. */
+  type Options = {
+    /** Chain receiving the transaction. */
+    chainId: number
+    /** Typed signer intent. */
+    intent: Campaigns.TransactionIntent
+    /** Replaced attempt id. */
+    replacementOf?: string | undefined
+    /** Owning reward run id. */
+    runId?: string | undefined
+    /** Signing account. */
+    signer: Address
+    /** Bound EarnVault. */
+    vaultAddress: Address
+  }
+}
+
+/** Persists exact signed bytes before broadcast. */
+export async function recordSignature(
+  db: Db.Db,
+  options: recordSignature.Options,
+): Promise<Record | undefined> {
+  const row = await db.kysely
+    .updateTable('reward_transaction_attempts')
+    .set({
+      expiresAt: options.expiresAt,
+      nonce: options.nonce,
+      signedBytes: options.signedBytes,
+      state: 'signed',
+      transactionHash: options.transactionHash,
+      updatedAt: new Date().toISOString(),
+    })
+    .where('id', '=', options.id)
+    .where('state', '=', 'created')
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace recordSignature {
+  /** Signed transaction evidence. */
+  type Options = {
+    /** Expiring nonce deadline (ISO 8601). */
+    expiresAt: string | null
+    /** Attempt id. */
+    id: string
+    /** Account nonce. */
+    nonce: string | null
+    /** Exact signed transaction bytes. */
+    signedBytes: Hex
+    /** Hash derived from the signed bytes. */
+    transactionHash: Hex
+  }
+}
+
+/** Marks a signed attempt as broadcast without changing its bytes. */
+export async function recordBroadcast(db: Db.Db, id: string): Promise<Record | undefined> {
+  const row = await db.kysely
+    .updateTable('reward_transaction_attempts')
+    .set({ state: 'broadcast', updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .where('state', 'in', ['signed', 'broadcast'])
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+/** Marks an unconfirmed expiring-nonce attempt terminal before replacement. */
+export async function expire(db: Db.Db, id: string): Promise<Record | undefined> {
+  const row = await db.kysely
+    .updateTable('reward_transaction_attempts')
+    .set({ state: 'expired', updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .where('state', 'in', ['signed', 'broadcast'])
+    .where('expiresAt', '<=', new Date().toISOString())
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+/** Records a canonical terminal receipt. */
+export async function confirm(db: Db.Db, options: confirm.Options): Promise<Record | undefined> {
+  const row = await db.kysely
+    .updateTable('reward_transaction_attempts')
+    .set({
+      confirmedBlockHash: options.receipt.blockHash,
+      ...(options.intent ? { intent: JSON.stringify(options.intent) } : {}),
+      receipt: JSON.stringify(options.receipt),
+      state: options.receipt.status === 'success' ? 'confirmed' : 'reverted',
+      updatedAt: new Date().toISOString(),
+    })
+    .where('id', '=', options.id)
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace confirm {
+  /** Confirmed receipt evidence. */
+  type Options = {
+    /** Attempt id. */
+    id: string
+    /** Compact terminal intent retained after exact bytes can no longer be retried. */
+    intent?: Campaigns.TransactionIntent | undefined
+    /** Canonical transaction receipt. */
+    receipt: Campaigns.TransactionReceipt
+  }
+}
+
+/** Marks a confirmed transaction that produced no requested state change as terminal. */
+export async function markIneffective(db: Db.Db, id: string): Promise<Record | undefined> {
+  const row = await db.kysely
+    .updateTable('reward_transaction_attempts')
+    .set({ state: 'ineffective', updatedAt: new Date().toISOString() })
+    .where('id', '=', id)
+    .where('state', '=', 'confirmed')
+    .returningAll()
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+/** Reads one transaction attempt. */
+export async function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  const row = await db.kysely
+    .selectFrom('reward_transaction_attempts')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+/** Reads the newest attempt for one deterministic intent within its execution. */
+export async function latestForIntent(
+  db: Db.Db,
+  options: latestForIntent.Options,
+): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('reward_transaction_attempts')
+    .selectAll()
+    .where('intentId', '=', options.intentId)
+  query = options.runId
+    ? query.where('runId', '=', options.runId)
+    : query.where('runId', 'is', null)
+  const row = await query
+    .orderBy(
+      sql<number>`CASE state WHEN 'confirmed' THEN 0 WHEN 'broadcast' THEN 1 WHEN 'signed' THEN 2 WHEN 'created' THEN 3 WHEN 'reverted' THEN 4 WHEN 'ineffective' THEN 5 ELSE 6 END`,
+      'asc',
+    )
+    .orderBy('createdAt', 'desc')
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace latestForIntent {
+  /** Intent and execution identity. */
+  type Options = {
+    /** Deterministic typed intent id. */
+    intentId: Hex
+    /** Owning reward run, omitted only for campaign provisioning. */
+    runId?: string | undefined
+  }
+}
+
+/** Lists confirmed transaction evidence for one run in creation order. */
+export async function confirmedForRun(db: Db.Db, runId: string): Promise<Record[]> {
+  const rows = await db.kysely
+    .selectFrom('reward_transaction_attempts')
+    .selectAll()
+    .where('runId', '=', runId)
+    .where('state', '=', 'confirmed')
+    .orderBy('createdAt', 'asc')
+    .execute()
+  return rows.map(toRecord)
+}
+
+/** Lists every durable transaction attempt for one run in creation order. */
+export async function listForRun(db: Db.Db, runId: string): Promise<Record[]> {
+  const rows = await db.kysely
+    .selectFrom('reward_transaction_attempts')
+    .selectAll()
+    .where('runId', '=', runId)
+    .orderBy('createdAt', 'asc')
+    .execute()
+  return rows.map(toRecord)
+}
+
+/** Reads the newest nonterminal or confirmed attempt recoverable by one run operation. */
+export async function latestRecoverable(
+  db: Db.Db,
+  options: latestRecoverable.Options,
+): Promise<Record | undefined> {
+  const row = await db.kysely
+    .selectFrom('reward_transaction_attempts')
+    .selectAll()
+    .where('runId', '=', options.runId)
+    .where('state', 'in', ['created', 'signed', 'broadcast', 'confirmed'])
+    .where(sql<boolean>`intent ->> 'operation' = ${options.operation}`)
+    .orderBy('createdAt', 'desc')
+    .executeTakeFirst()
+  return row ? toRecord(row) : undefined
+}
+
+export declare namespace latestRecoverable {
+  /** Run operation selector. */
+  type Options = {
+    /** Typed signer operation. */
+    operation: Campaigns.TransactionIntent['operation']
+    /** Owning reward run. */
+    runId: string
+  }
+}
+
+function normalize(address: string): Address {
+  return address.toLowerCase() as Address
+}
+
+function toRecord(row: Selectable<Table>): Record {
+  return { ...row, chainId: Number(row.chainId) }
+}

package/src/db/tables/routesCatalog.test.ts

@@ -0,0 +1,185 @@
+import { sql } from 'kysely'
+
+import * as TestApp from '../../../test/App.js'
+import * as RoutesCatalog from './routesCatalog.js'
+
+// Matches the table module's private `fcat` advisory-lock key.
+const publishLockKey = 0x66636174
+
+const catalog = {
+  chains: [
+    {
+      aliases: ['eth'],
+      id: 'eip155:1',
+      name: 'Ethereum',
+      parentChainId: null,
+      rpcUrls: ['https://ethereum.example'],
+      slug: 'ethereum',
+    },
+    {
+      aliases: [],
+      id: 'eip155:4217',
+      name: 'Tempo',
+      parentChainId: null,
+      rpcUrls: ['https://tempo.example'],
+      slug: 'tempo',
+    },
+  ],
+  chainTokens: [
+    {
+      address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+      chainId: 'eip155:1',
+      decimals: 6,
+      name: null,
+      standard: 'ERC-20',
+      tokenId: 'usdc',
+    },
+    {
+      address: '0x20c000000000000000000000b9537d11c60e8b50',
+      chainId: 'eip155:4217',
+      decimals: 6,
+      name: null,
+      standard: 'TIP-20',
+      tokenId: 'usdce',
+    },
+  ],
+  routes: [
+    {
+      destinationChainId: 'eip155:4217',
+      destinationTokenId: 'usdce',
+      providerId: 'relay',
+      sourceChainId: 'eip155:1',
+      sourceTokenId: 'usdc',
+    },
+  ],
+  tokens: [
+    {
+      currency: 'USD',
+      id: 'usdc',
+      name: 'USD Coin',
+      symbol: 'USDC',
+    },
+    {
+      currency: 'USD',
+      id: 'usdce',
+      name: 'Bridged USDC (Stargate)',
+      symbol: 'USDC.e',
+    },
+  ],
+} as const satisfies RoutesCatalog.publish.Input
+
+describe('read', () => {
+  test('runs concurrently with another reader', async () => {
+    const factory = TestApp.databaseFactory()
+    await RoutesCatalog.publish(factory(), catalog)
+    const locked = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const holder = factory().transaction(async (tx) => {
+      await sql`SELECT pg_advisory_xact_lock_shared(${publishLockKey})`.execute(tx.kysely)
+      locked.resolve()
+      await release.promise
+    })
+    await locked.promise
+
+    const read = RoutesCatalog.read(factory())
+    const timeout = Promise.withResolvers<'waiting'>()
+    const timer = setTimeout(() => timeout.resolve('waiting'), 1_000)
+    let state: 'read' | 'waiting'
+    try {
+      state = await Promise.race([read.then(() => 'read' as const), timeout.promise])
+    } finally {
+      clearTimeout(timer)
+      release.resolve()
+      await holder
+      await read
+    }
+
+    expect(state).toBe('read')
+  })
+
+  test('waits for a publisher lock', async () => {
+    const factory = TestApp.databaseFactory()
+    await RoutesCatalog.publish(factory(), catalog)
+    const locked = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const holder = factory().transaction(async (tx) => {
+      await sql`SELECT pg_advisory_xact_lock(${publishLockKey})`.execute(tx.kysely)
+      locked.resolve()
+      await release.promise
+    })
+    await locked.promise
+
+    const read = RoutesCatalog.read(factory())
+    const timeout = Promise.withResolvers<'waiting'>()
+    const timer = setTimeout(() => timeout.resolve('waiting'), 100)
+    let state: 'read' | 'waiting'
+    try {
+      state = await Promise.race([read.then(() => 'read' as const), timeout.promise])
+    } finally {
+      clearTimeout(timer)
+      release.resolve()
+      await holder
+      await read
+    }
+
+    expect(state).toBe('waiting')
+  })
+})
+
+describe('publish', () => {
+  test('round-trips a complete route catalog', async () => {
+    const db = TestApp.database()
+    const head = await RoutesCatalog.publish(db, catalog)
+    expect(await RoutesCatalog.read(db)).toStrictEqual({
+      catalog: head,
+      chainTokens: catalog.chainTokens,
+      chains: catalog.chains,
+      // Optional route JSON persists as null.
+      routes: catalog.routes.map((route) => ({
+        ...route,
+        capabilities: null,
+        configuration: null,
+      })),
+      tokens: catalog.tokens,
+    })
+  })
+
+  test('round-trips route capabilities', async () => {
+    const db = TestApp.database()
+    const capabilities = { transfer: { modes: ['exactSource'] } } as const
+    await RoutesCatalog.publish(db, {
+      ...catalog,
+      routes: [{ ...catalog.routes[0]!, capabilities }],
+    })
+    expect((await RoutesCatalog.read(db)).routes[0]?.capabilities).toStrictEqual(capabilities)
+  })
+
+  test('round-trips route configuration', async () => {
+    const db = TestApp.database()
+    const configuration = { poolAddress: `0x${'11'.repeat(20)}` }
+    await RoutesCatalog.publish(db, {
+      ...catalog,
+      routes: [{ ...catalog.routes[0]!, configuration }],
+    })
+    expect((await RoutesCatalog.read(db)).routes[0]?.configuration).toStrictEqual(configuration)
+  })
+
+  test('replaces rows and advances the catalog version', async () => {
+    const db = TestApp.database()
+    const first = await RoutesCatalog.publish(db, catalog)
+    const second = await RoutesCatalog.publish(db, {
+      chainTokens: [],
+      chains: catalog.chains.slice(0, 1),
+      routes: [],
+      tokens: [],
+    })
+    expect(second.version > first.version).toBe(true)
+    expect(await RoutesCatalog.read(db)).toStrictEqual({
+      catalog: second,
+      chainTokens: [],
+      chains: catalog.chains.slice(0, 1),
+      routes: [],
+      tokens: [],
+    })
+  })
+})

package/src/db/tables/routesCatalog.ts

@@ -0,0 +1,163 @@
+import type { JSONColumnType } from 'kysely'
+import { sql } from 'kysely'
+import { Hex } from 'ox'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+const catalogId = 'default'
+const publishLockKey = 0x66636174
+
+/** Columns of the `routes_catalogs` table. */
+export type CatalogTable = db_Schema.RoutesCatalog
+
+/** Columns of the `routes_chains` table. */
+export type ChainTable = Omit<db_Schema.RoutesChain, 'aliases' | 'rpcUrls'> & {
+  /** Caller-facing chain aliases stored as JSON. */
+  aliases: JSONColumnType<db_Schema.RoutesChain['aliases'], string, string>
+  /** Public RPC endpoints stored as JSON. */
+  rpcUrls: JSONColumnType<db_Schema.RoutesChain['rpcUrls'], string, string>
+}
+
+/** Columns of the `routes_tokens` table. */
+export type TokenTable = db_Schema.RoutesToken
+
+/** Columns of the `routes_chain_tokens` table. */
+export type ChainTokenTable = db_Schema.RoutesChainToken
+
+/** Columns of the `routes_routes` table. */
+export type RouteTable = db_Schema.RoutesRoute
+
+/** A route row whose optional JSON fields may be absent in validated input. */
+export type RouteRow = Omit<db_Schema.RoutesRoute, 'capabilities' | 'configuration'> & {
+  /** Executable capability; absent and null both mean indicative-only. */
+  capabilities?: db_Schema.RoutesRoute['capabilities'] | undefined
+  /** Provider-specific route configuration; absent and null are equivalent. */
+  configuration?: db_Schema.RoutesRoute['configuration'] | undefined
+}
+
+/** Stored route catalog rows and version metadata. */
+export type Rows = {
+  /** Current catalog metadata, or undefined before the first publish. */
+  catalog: db_Schema.RoutesCatalog | undefined
+  /** Chain-scoped route token rows. */
+  chainTokens: readonly db_Schema.RoutesChainToken[]
+  /** Route chain rows. */
+  chains: readonly db_Schema.RoutesChain[]
+  /** Route provider route rows. */
+  routes: readonly RouteRow[]
+  /** Route token rows. */
+  tokens: readonly db_Schema.RoutesToken[]
+}
+
+/** Reads the current route catalog version metadata. */
+export async function head(db: Db.Db): Promise<db_Schema.RoutesCatalog | undefined> {
+  return db.kysely
+    .selectFrom('routes_catalogs')
+    .selectAll()
+    .where('id', '=', catalogId)
+    .executeTakeFirst()
+}
+
+/** Reads every row in the current route catalog. */
+export function read(db: Db.Db): Promise<Rows> {
+  return db.transaction(async (tx) => {
+    await sql`SELECT pg_advisory_xact_lock_shared(${publishLockKey})`.execute(tx.kysely)
+    const catalog = await head(tx)
+    const chains = await tx.kysely.selectFrom('routes_chains').selectAll().orderBy('id').execute()
+    const tokens = await tx.kysely.selectFrom('routes_tokens').selectAll().orderBy('id').execute()
+    const chainTokens = await tx.kysely
+      .selectFrom('routes_chain_tokens')
+      .selectAll()
+      .orderBy('chainId')
+      .orderBy('tokenId')
+      .execute()
+    const routes = await tx.kysely
+      .selectFrom('routes_routes')
+      .selectAll()
+      .orderBy('providerId')
+      .orderBy('sourceChainId')
+      .orderBy('sourceTokenId')
+      .orderBy('destinationChainId')
+      .orderBy('destinationTokenId')
+      .execute()
+    return { catalog, chainTokens, chains, routes, tokens }
+  })
+}
+
+/** Replaces the complete route catalog and advances its version. */
+export function publish(db: Db.Db, input: publish.Input): Promise<db_Schema.RoutesCatalog> {
+  return db.transaction(async (tx) => {
+    await sql`SELECT pg_advisory_xact_lock(${publishLockKey})`.execute(tx.kysely)
+    const catalog = {
+      id: catalogId,
+      updatedAt: new Date().toISOString(),
+      version: nextVersion(),
+    }
+
+    await tx.kysely.deleteFrom('routes_routes').execute()
+    await tx.kysely.deleteFrom('routes_chain_tokens').execute()
+    await tx.kysely.deleteFrom('routes_tokens').execute()
+    await tx.kysely.deleteFrom('routes_chains').execute()
+
+    if (input.chains.length > 0)
+      await tx.kysely
+        .insertInto('routes_chains')
+        .values(
+          input.chains.map((chain) => ({
+            ...chain,
+            aliases: JSON.stringify(chain.aliases),
+            rpcUrls: JSON.stringify(chain.rpcUrls),
+          })),
+        )
+        .execute()
+    if (input.tokens.length > 0)
+      await tx.kysely.insertInto('routes_tokens').values(input.tokens).execute()
+    if (input.chainTokens.length > 0)
+      await tx.kysely.insertInto('routes_chain_tokens').values(input.chainTokens).execute()
+    if (input.routes.length > 0)
+      await tx.kysely
+        .insertInto('routes_routes')
+        .values(
+          input.routes.map((route) => ({
+            ...route,
+            capabilities: route.capabilities ?? null,
+            configuration: route.configuration ?? null,
+          })),
+        )
+        .execute()
+
+    await tx.kysely
+      .insertInto('routes_catalogs')
+      .values(catalog)
+      .onConflict((oc) =>
+        oc.column('id').doUpdateSet({
+          updatedAt: catalog.updatedAt,
+          version: catalog.version,
+        }),
+      )
+      .execute()
+    return catalog
+  })
+}
+
+export declare namespace publish {
+  /** Complete validated route catalog rows. */
+  type Input = {
+    /** Chain-scoped route token rows. */
+    chainTokens: readonly db_Schema.RoutesChainToken[]
+    /** Route chain rows. */
+    chains: readonly db_Schema.RoutesChain[]
+    /** Route provider route rows. */
+    routes: readonly RouteRow[]
+    /** Route token rows. */
+    tokens: readonly db_Schema.RoutesToken[]
+  }
+}
+
+let lastVersionMs = 0
+
+function nextVersion() {
+  lastVersionMs = Math.max(Date.now(), lastVersionMs + 1)
+  return `${lastVersionMs.toString().padStart(15, '0')}_${Hex.random(4).slice(2)}`
+}