tapimo 0.14.0 → 0.15.0

package/src/cli/commands/admin.ts

@@ -1,7 +1,15 @@
+import * as fs from 'node:fs'
+
 import { Cli as incur_Cli, z } from 'incur'
+import * as zod from 'zod/mini'
 
 import * as Analytics from '../../analytics/Analytics.js'
 import * as Db from '../../db/Db.js'
+import * as RewardEligibilityAssociations from '../../db/tables/rewardEligibilityAssociations.js'
+import * as Audit from '../../internal/rewards/Audit.js'
+import * as Credits from '../../internal/rewards/Credits.js'
+import * as Schema from '../../internal/Schema.js'
+import * as Tidx from '../../internal/Tidx.js'
 
 /**
  * Applies pending Postgres migrations, connecting directly via
@@ -106,6 +114,273 @@ const migrate = incur_Cli.create('migrate', {
   },
 })
 
+const rewardEligibilityImport = zod.array(
+  zod.strictObject({
+    chainId: Schema.ChainId,
+    transactionHash: zod.optional(Schema.Hash),
+    vaultAddress: Schema.Address,
+    walletAddress: Schema.Address,
+  }),
+)
+
+/** Reviews or applies an import of existing reward eligibility associations. */
+const importRewardEligibility = incur_Cli.create('import-reward-eligibility', {
+  description: 'Review or import existing reward eligibility associations.',
+  env: z.object({
+    DATABASE_URL: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Used when --database-url is omitted.'),
+  }),
+  options: z.object({
+    apply: z.boolean().default(false).describe('Persist the reviewed import. Defaults to dry-run.'),
+    databaseUrl: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Overrides DATABASE_URL.'),
+    dbSchema: z.string().optional().describe('Postgres schema containing the API tables.'),
+    file: z.string().describe('JSON file containing reward eligibility associations.'),
+  }),
+  async run(c) {
+    const parsed = rewardEligibilityImport.safeParse(
+      (() => {
+        try {
+          return JSON.parse(fs.readFileSync(c.options.file, 'utf8'))
+        } catch {
+          return undefined
+        }
+      })(),
+    )
+    if (!parsed.success)
+      return c.error({
+        code: 'invalid_reward_eligibility_import',
+        message: 'The import file must contain valid reward eligibility associations.',
+      })
+    const associations = parsed.data
+    if (!c.options.apply) return { applied: false, associations }
+
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString)
+      return c.error({
+        code: 'missing_database_url',
+        message: 'Set --database-url or DATABASE_URL to apply the import.',
+      })
+    const db = c.options.dbSchema
+      ? Db.postgres({ connectionString, schema: c.options.dbSchema })
+      : Db.postgres({ connectionString })
+    try {
+      const results = await db.transaction(async (tx) => {
+        const results: RewardEligibilityAssociations.upsert.Result[] = []
+        for (const association of associations)
+          results.push(await RewardEligibilityAssociations.upsert(tx, association))
+        return results
+      })
+      return {
+        applied: true,
+        created: results.filter((result) => result.created).length,
+        replayed: results.filter((result) => !result.created).length,
+      }
+    } catch (error) {
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Import failed.'
+      return c.error({ code: 'reward_eligibility_import_failed', message })
+    } finally {
+      await db.close()
+    }
+  },
+})
+
+/**
+ * Compares stored Earn reward projections with a fresh TIDX replay and, with
+ * `--apply`, resets under-allocated accounts so the next run rebuilds them.
+ */
+const auditRewardAccounts = incur_Cli.create('audit-reward-accounts', {
+  description: 'Review or repair Earn reward accounts that missed deposits.',
+  env: z.object({
+    DATABASE_URL: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Used when --database-url is omitted.'),
+    TIDX_AUTH: z.string().optional().describe('TIDX credential. Used when --tidx-auth is omitted.'),
+    TIDX_URL: z.string().optional().describe('TIDX base URL. Used when --tidx-url is omitted.'),
+  }),
+  options: z.object({
+    apply: z
+      .boolean()
+      .default(false)
+      .describe('Reset accounts with missing deposits for replay. Defaults to dry-run.'),
+    chainId: z.number().int().default(4217).describe('Chain containing the vault.'),
+    databaseUrl: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Overrides DATABASE_URL.'),
+    dbSchema: z.string().optional().describe('Postgres schema containing the API tables.'),
+    tidxAuth: z.string().optional().describe('TIDX credential. Overrides TIDX_AUTH.'),
+    tidxUrl: z.string().optional().describe('TIDX base URL. Overrides TIDX_URL.'),
+    vaultAddress: z.string().describe('EarnVault address of the campaign.'),
+  }),
+  async run(c) {
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString)
+      return c.error({
+        code: 'missing_database_url',
+        message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
+      })
+    const vaultAddress = Schema.Address.safeParse(c.options.vaultAddress)
+    if (!vaultAddress.success)
+      return c.error({
+        code: 'invalid_vault_address',
+        message: 'The vault address must be a 20-byte hex address.',
+      })
+    const baseUrl = c.options.tidxUrl ?? c.env.TIDX_URL
+    const auth = c.options.tidxAuth ?? c.env.TIDX_AUTH
+    const tidx = Tidx.getClient({
+      chainId: c.options.chainId,
+      tidx: { ...(auth ? { auth } : {}), ...(baseUrl ? { baseUrl } : {}) },
+    })
+    const db = c.options.dbSchema
+      ? Db.postgres({ connectionString, schema: c.options.dbSchema })
+      : Db.postgres({ connectionString })
+    try {
+      const report = await Audit.audit({
+        chainId: c.options.chainId,
+        db,
+        tidx,
+        vaultAddress: vaultAddress.data,
+      })
+      if (!c.options.apply) return { applied: false, ...report }
+      // Only the allocation-shortfall accounts are reset; other drift stays for manual review.
+      const reset = await Audit.reset({
+        chainId: c.options.chainId,
+        db,
+        recipients: report.missingDeposits.map((entry) => entry.recipient),
+        vaultAddress: vaultAddress.data,
+      })
+      return { applied: true, reset, ...report }
+    } catch (error) {
+      if (error instanceof Audit.AuditError)
+        return c.error({ code: 'reward_audit_unavailable', message: error.message })
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Audit failed.'
+      return c.error({ code: 'reward_audit_failed', message })
+    } finally {
+      await db.close()
+    }
+  },
+})
+
+const rewardCreditBatch = zod.array(
+  zod.strictObject({
+    assets: zod.string().check(zod.regex(/^[1-9]\d*$/)),
+    recipient: Schema.Address,
+  }),
+)
+
+/**
+ * Adds run-once manual credits to stored Earn reward accounts so the next
+ * settlement pays them out. `--apply` requires a paused campaign with no run in
+ * flight, because a settlement commit replaces `reward_accounts` wholesale.
+ */
+const creditRewardAccounts = incur_Cli.create('credit-reward-accounts', {
+  description: 'Review or apply run-once credits to Earn reward accounts.',
+  env: z.object({
+    DATABASE_URL: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Used when --database-url is omitted.'),
+  }),
+  options: z.object({
+    apply: z.boolean().default(false).describe('Write the reviewed credits. Defaults to dry-run.'),
+    chainId: z.number().int().default(4217).describe('Chain containing the vault.'),
+    databaseUrl: z
+      .string()
+      .optional()
+      .describe('Postgres connection string. Overrides DATABASE_URL.'),
+    dbSchema: z.string().optional().describe('Postgres schema containing the API tables.'),
+    file: z
+      .string()
+      .describe('JSON file of `{ recipient, assets }` credits with assets in base units.'),
+    reference: z
+      .string()
+      .min(1)
+      .describe('Batch reference. A recipient is never credited twice under one reference.'),
+    vaultAddress: z.string().describe('EarnVault address of the campaign.'),
+  }),
+  async run(c) {
+    const parsed = rewardCreditBatch.safeParse(
+      (() => {
+        try {
+          return JSON.parse(fs.readFileSync(c.options.file, 'utf8'))
+        } catch {
+          return undefined
+        }
+      })(),
+    )
+    if (!parsed.success)
+      return c.error({
+        code: 'invalid_reward_credit_batch',
+        message:
+          'The credit file must contain an array of { recipient, assets } with positive integer base units.',
+      })
+    const credits = parsed.data.map((credit) => ({
+      assets: BigInt(credit.assets),
+      recipient: credit.recipient,
+    }))
+    const connectionString = c.options.databaseUrl ?? c.env.DATABASE_URL
+    if (!connectionString)
+      return c.error({
+        code: 'missing_database_url',
+        message: 'Set --database-url or DATABASE_URL to the Postgres connection string.',
+      })
+    const vaultAddress = Schema.Address.safeParse(c.options.vaultAddress)
+    if (!vaultAddress.success)
+      return c.error({
+        code: 'invalid_vault_address',
+        message: 'The vault address must be a 20-byte hex address.',
+      })
+    const db = c.options.dbSchema
+      ? Db.postgres({ connectionString, schema: c.options.dbSchema })
+      : Db.postgres({ connectionString })
+    const options = {
+      chainId: c.options.chainId,
+      credits,
+      db,
+      reference: c.options.reference,
+      vaultAddress: vaultAddress.data,
+    }
+    try {
+      const report = await Credits.review(options)
+      const summary = {
+        appliedAssets: report.appliedAssets.toString(),
+        blockers: report.blockers,
+        latestRunPhase: report.latestRunPhase,
+        lines: report.lines.map((line) => ({ ...line, assets: line.assets.toString() })),
+        missing: report.missing,
+        paused: report.paused,
+        pendingAssets: report.pendingAssets.toString(),
+        ready: report.ready,
+      }
+      if (!c.options.apply) return { applied: false, ...summary }
+      const result = await Credits.apply(options)
+      return {
+        applied: true,
+        credited: result.credited,
+        creditedAssets: result.creditedAssets.toString(),
+        replayed: result.replayed,
+        ...summary,
+      }
+    } catch (error) {
+      if (error instanceof Credits.CreditsError)
+        return c.error({ code: 'reward_credit_unavailable', message: error.message })
+      /* v8 ignore next */
+      const message = error instanceof Error ? error.message : 'Credit failed.'
+      return c.error({ code: 'reward_credit_failed', message })
+    } finally {
+      await db.close()
+    }
+  },
+})
+
 /**
  * Super admin commands that run against a deployment's infrastructure rather
  * than the hosted API (database migrations, …).
@@ -114,6 +389,9 @@ export const admin = incur_Cli
   .create('admin', {
     description: 'Super admin commands for a Tempo API deployment.',
   })
+  .command(auditRewardAccounts)
+  .command(creditRewardAccounts)
+  .command(importRewardEligibility)
   .command(migrate)
 
 /**

package/src/cloudflare.ts

@@ -5,7 +5,7 @@
 import { DurableObject as CloudflareDurableObject } from 'cloudflare:workers'
 
 import * as Db from './db/Db.js'
-import * as Funding from './internal/funding/index.js'
+import * as Routes from './internal/routes/index.js'
 import * as Metrics from './Metrics.js'
 import * as Store from './internal/Store.js'
 
@@ -72,41 +72,41 @@ export class DurableObject extends CloudflareDurableObject {
   }
 }
 
-const fundingSourceAlarmIntervalMs = 500
-const fundingSourceRetryIntervalMs = 2_000
+const routesSourceAlarmIntervalMs = 500
+const routesSourceRetryIntervalMs = 2_000
 
-type FundingSourceConfiguration = {
+type RoutesSourceConfiguration = {
   chainId: string
   rpcUrls: readonly string[]
   tokenAddress: string
 }
 
-type FundingSourceRoute = Funding.SourceObservation.Route
+type RoutesSourceRoute = Routes.SourceObservation.Route
 
-type FundingSourceRegisterOptions = FundingSourceConfiguration & {
-  route: FundingSourceRoute
+type RoutesSourceRegisterOptions = RoutesSourceConfiguration & {
+  route: RoutesSourceRoute
 }
 
-type FundingSourceSyncOptions = FundingSourceConfiguration & {
-  routes: readonly FundingSourceRoute[]
+type RoutesSourceSyncOptions = RoutesSourceConfiguration & {
+  routes: readonly RoutesSourceRoute[]
 }
 
-type FundingSourceConfigurationRow = {
+type RoutesSourceConfigurationRow = {
   value: string
 }
 
-type FundingSourceRouteRow = {
+type RoutesSourceRouteRow = {
   address: string
   id: string
 }
 
-type FundingSourceStateRow = {
+type RoutesSourceStateRow = {
   value: string
 }
 
-/** Cloudflare Durable Object that detects EVM funding deposits before provider indexing. */
-export class FundingSourceObserver<
-  environment extends FundingSourceObserver.Environment = FundingSourceObserver.Environment,
+/** Cloudflare Durable Object that detects EVM route deposits before provider indexing. */
+export class RoutesSourceObserver<
+  environment extends RoutesSourceObserver.Environment = RoutesSourceObserver.Environment,
 > extends CloudflareDurableObject {
   /** Durable Object storage and alarm context. */
   protected context: State
@@ -132,10 +132,10 @@ export class FundingSourceObserver<
   }
 
   /** Registers one newly created deposit address and starts source observation. */
-  async register(options: FundingSourceRegisterOptions): Promise<void> {
-    const configuration = serializeFundingSourceConfiguration(options)
+  async register(options: RoutesSourceRegisterOptions): Promise<void> {
+    const configuration = serializeRoutesSourceConfiguration(options)
     const route = this.context.storage.sql
-      .exec<FundingSourceRouteRow>('SELECT id, address FROM routes WHERE id = ?', options.route.id)
+      .exec<RoutesSourceRouteRow>('SELECT id, address FROM routes WHERE id = ?', options.route.id)
       .toArray()[0]
     this.context.storage.transactionSync(() => {
       this.context.storage.sql.exec(
@@ -157,13 +157,13 @@ export class FundingSourceObserver<
   }
 
   /** Replaces the active routes from the database and repairs alarm scheduling. */
-  async sync(options: FundingSourceSyncOptions): Promise<void> {
-    const configuration = serializeFundingSourceConfiguration(options)
+  async sync(options: RoutesSourceSyncOptions): Promise<void> {
+    const configuration = serializeRoutesSourceConfiguration(options)
     const existing = new Map(
       this.context.storage.sql
-        .exec<FundingSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
+        .exec<RoutesSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
         .toArray()
-        .map((route: FundingSourceRouteRow) => [route.id, route.address.toLowerCase()] as const),
+        .map((route: RoutesSourceRouteRow) => [route.id, route.address.toLowerCase()] as const),
     )
     const changed = options.routes.filter(
       (route) => existing.get(route.id) !== route.address.toLowerCase(),
@@ -195,16 +195,16 @@ export class FundingSourceObserver<
   async alarm(): Promise<void> {
     const metrics = this.createMetrics()
     const configuration = this.#readConfiguration()
-    const routes: FundingSourceRouteRow[] = this.context.storage.sql
-      .exec<FundingSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
+    const routes: RoutesSourceRouteRow[] = this.context.storage.sql
+      .exec<RoutesSourceRouteRow>('SELECT id, address FROM routes ORDER BY id')
       .toArray()
     if (!configuration || routes.length === 0) return
 
     try {
       const cursor = this.context.storage.sql
-        .exec<FundingSourceStateRow>("SELECT value FROM state WHERE key = 'cursor'")
+        .exec<RoutesSourceStateRow>("SELECT value FROM state WHERE key = 'cursor'")
         .toArray()[0]
-      const result = await Funding.SourceObservation.scan({
+      const result = await Routes.SourceObservation.scan({
         chainId: configuration.chainId,
         ...(cursor ? { cursor: BigInt(cursor.value) } : {}),
         routes,
@@ -212,14 +212,14 @@ export class FundingSourceObserver<
         tokenAddress: configuration.tokenAddress,
       })
       const backfills = this.context.storage.sql
-        .exec<FundingSourceRouteRow>(
+        .exec<RoutesSourceRouteRow>(
           'SELECT routes.id, routes.address FROM routes INNER JOIN backfills ON backfills.id = routes.id ORDER BY routes.id',
         )
         .toArray()
       // Backfill new routes independently so the main cursor retains any older shard backlog.
       const backfill = await (async () => {
         if (!cursor || backfills.length === 0) return undefined
-        return Funding.SourceObservation.scan({
+        return Routes.SourceObservation.scan({
           chainId: configuration.chainId,
           routes: backfills,
           rpcUrls: configuration.rpcUrls,
@@ -227,7 +227,10 @@ export class FundingSourceObserver<
         })
       })()
       const database = Db.get(() =>
-        Db.postgres({ connectionString: this.environment.HYPERDRIVE.connectionString }),
+        Db.postgres({
+          connectionString: this.environment.HYPERDRIVE.connectionString,
+          maxConnections: 5,
+        }),
       )
       const routesById = new Map(routes.map((route) => [route.id, route] as const))
       const observations = new Map(
@@ -239,22 +242,24 @@ export class FundingSourceObserver<
       for (const observation of observations) {
         const route = routesById.get(observation.addressId)
         if (!route) continue
-        const persisted = await Funding.SourceObservation.observe(database, {
+        const persisted = await Routes.SourceObservation.observe(database, {
           ...observation,
           recipient: route.address,
         })
         if (
           persisted.type === 'ignored' ||
           persisted.record.providerRequestId !== null ||
-          Funding.Deposit.isTerminal(persisted.record.status)
+          Routes.Deposit.isTerminal(persisted.record.status)
         )
           continue
-        await this.environment.FUNDING_RECONCILIATION_QUEUE.send({
+        if (persisted.type === 'created')
+          Routes.Observability.recordDeposit(metrics, { record: persisted.record })
+        await this.environment.ROUTES_RECONCILIATION_QUEUE.send({
           addressId: observation.addressId,
           trigger: 'chain',
-          type: 'funding:deposit-address:reconcile',
+          type: 'routes:deposit-address:reconcile',
         })
-        metrics.count('funding_source_observer_deposit_count', 1, {
+        metrics.count('routes_source_observer_deposit_count', 1, {
           chain: configuration.chainId,
           outcome: persisted.type,
         })
@@ -267,25 +272,25 @@ export class FundingSourceObserver<
         for (const route of backfills)
           this.context.storage.sql.exec('DELETE FROM backfills WHERE id = ?', route.id)
       })
-      metrics.count('funding_source_observer_scan_count', 1, {
+      metrics.count('routes_source_observer_scan_count', 1, {
         chain: configuration.chainId,
         outcome: 'completed',
       })
       metrics.gauge(
-        'funding_source_observer_block_lag',
+        'routes_source_observer_block_lag',
         Math.max(0, Number(result.head - result.cursor)),
         { chain: configuration.chainId },
       )
       await this.context.storage.setAlarm(
-        result.cursor < result.head ? Date.now() : Date.now() + fundingSourceAlarmIntervalMs,
+        result.cursor < result.head ? Date.now() : Date.now() + routesSourceAlarmIntervalMs,
       )
     } catch (cause) {
-      metrics.count('funding_source_observer_scan_count', 1, {
+      metrics.count('routes_source_observer_scan_count', 1, {
         chain: configuration.chainId,
         outcome: 'failed',
       })
       this.capture(cause)
-      await this.context.storage.setAlarm(Date.now() + fundingSourceRetryIntervalMs)
+      await this.context.storage.setAlarm(Date.now() + routesSourceRetryIntervalMs)
     } finally {
       metrics.flush()
     }
@@ -307,7 +312,7 @@ export class FundingSourceObserver<
 
   #configuration(): string | undefined {
     return this.context.storage.sql
-      .exec<FundingSourceConfigurationRow>('SELECT value FROM configuration WHERE id = 1')
+      .exec<RoutesSourceConfigurationRow>('SELECT value FROM configuration WHERE id = 1')
       .toArray()[0]?.value
   }
 
@@ -316,21 +321,21 @@ export class FundingSourceObserver<
       await this.context.storage.setAlarm(Date.now())
   }
 
-  #readConfiguration(): FundingSourceConfiguration | undefined {
+  #readConfiguration(): RoutesSourceConfiguration | undefined {
     const value = this.#configuration()
-    return value ? (JSON.parse(value) as FundingSourceConfiguration) : undefined
+    return value ? (JSON.parse(value) as RoutesSourceConfiguration) : undefined
   }
 }
 
-export declare namespace FundingSourceObserver {
+export declare namespace RoutesSourceObserver {
   /** Cloudflare bindings and deployment metadata used by the observer. */
   type Environment = {
     /** Deployment environment included in operational metrics. */
     ENVIRONMENT?: string | undefined
     /** Queue that receives deposit-address reconciliation work. */
-    FUNDING_RECONCILIATION_QUEUE: {
+    ROUTES_RECONCILIATION_QUEUE: {
       /** Enqueues one chain-detected address for reconciliation. */
-      send(message: Funding.Provider.Webhook.receive.Dispatchable): Promise<unknown>
+      send(message: Routes.Provider.Webhook.receive.Dispatchable): Promise<unknown>
     }
     /** Authoritative Postgres connection exposed through Hyperdrive. */
     HYPERDRIVE: {
@@ -340,10 +345,10 @@ export declare namespace FundingSourceObserver {
   }
 }
 
-function serializeFundingSourceConfiguration(options: FundingSourceConfiguration): string {
+function serializeRoutesSourceConfiguration(options: RoutesSourceConfiguration): string {
   return JSON.stringify({
     chainId: options.chainId,
     rpcUrls: options.rpcUrls,
     tokenAddress: options.tokenAddress.toLowerCase(),
-  } satisfies FundingSourceConfiguration)
+  } satisfies RoutesSourceConfiguration)
 }