tapimo 0.13.0 → 0.15.0

package/src/db/tables/rewardCredits.ts

@@ -0,0 +1,110 @@
+import type { ColumnType, Selectable } from 'kysely'
+import { sql } from 'kysely'
+import type { Address } from 'viem'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `reward_credits` table. */
+export type Table = Omit<db_Schema.RewardCredit, 'chainId'> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+}
+
+/** A stored manual reward credit. */
+export type Record = db_Schema.RewardCredit
+
+/**
+ * Records one credit and adds it to the recipient's pending rewards atomically.
+ * A repeated `(recipient, reference)` is a no-op, so a batch can be replayed safely.
+ */
+export async function apply(db: Db.Db, options: apply.Options): Promise<apply.Result> {
+  return db.transaction(async (tx) => {
+    const inserted = await tx.kysely
+      .insertInto('reward_credits')
+      .values({
+        assets: options.assets.toString(),
+        chainId: options.chainId,
+        createdAt: new Date().toISOString(),
+        recipient: normalize(options.recipient),
+        reference: options.reference,
+        vaultAddress: normalize(options.vaultAddress),
+      })
+      .onConflict((oc) =>
+        oc.columns(['chainId', 'vaultAddress', 'recipient', 'reference']).doNothing(),
+      )
+      .returning('assets')
+      .executeTakeFirst()
+    if (!inserted) return { credited: false }
+    const updated = await tx.kysely
+      .updateTable('reward_accounts')
+      .set({
+        pendingRewardAssets: sql<string>`reward_accounts.pending_reward_assets + ${options.assets.toString()}::numeric`,
+      })
+      .where('chainId', '=', String(options.chainId))
+      .where('vaultAddress', '=', normalize(options.vaultAddress))
+      .where('recipient', '=', normalize(options.recipient))
+      .executeTakeFirst()
+    // Crediting an unknown account would strand assets nobody can settle; roll back.
+    if (updated.numUpdatedRows !== 1n) throw new MissingAccountError(options.recipient)
+    return { credited: true }
+  })
+}
+
+export declare namespace apply {
+  /** One credit to record. */
+  type Options = {
+    /** Base-asset reward units to add. */
+    assets: bigint
+    /** Chain containing the vault. */
+    chainId: number
+    /** Registered recipient with a stored `reward_accounts` row. */
+    recipient: string
+    /** Batch reference; the same reference never credits a recipient twice. */
+    reference: string
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+  /** Whether this call recorded the credit or found it already applied. */
+  type Result = { credited: boolean }
+}
+
+/** Lists one campaign's credits, optionally for one reference. */
+export async function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  let query = db.kysely
+    .selectFrom('reward_credits')
+    .selectAll()
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+  if (options.reference !== undefined) query = query.where('reference', '=', options.reference)
+  const rows = await query.orderBy('createdAt', 'asc').orderBy('recipient', 'asc').execute()
+  return rows.map(toRecord)
+}
+
+export declare namespace list {
+  /** Campaign identity and optional batch filter. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Batch reference to filter by. */
+    reference?: string | undefined
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+function normalize(address: string): Address {
+  return address.toLowerCase() as Address
+}
+
+function toRecord(row: Selectable<Table>): Record {
+  return { ...row, chainId: Number(row.chainId) }
+}
+
+/** Thrown when a credit targets a recipient without a stored reward account. */
+export class MissingAccountError extends Error {
+  override name = 'RewardCredits.MissingAccountError'
+  constructor(recipient: string) {
+    super(`Reward account ${recipient} does not exist.`)
+  }
+}

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

@@ -0,0 +1,271 @@
+import { nanoid } from 'nanoid'
+
+import * as TestApp from '../../../test/App.js'
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as Cursor from '../../internal/Cursor.js'
+import * as Schema from '../../internal/Schema.js'
+import * as RewardEligibilityAssociations from './rewardEligibilityAssociations.js'
+
+const input = {
+  chainId: 4217,
+  transactionHash: `0x${'33'.repeat(32)}`,
+  vaultAddress: Schema.Address.parse(`0x${'Aa'.repeat(20)}`),
+  walletAddress: Schema.Address.parse(`0x${'Bb'.repeat(20)}`),
+} as const satisfies RewardEligibilityAssociations.upsert.Options
+
+describe('upsert', () => {
+  test('creates a normalized association and refreshes its latest registration', async () => {
+    vi.useFakeTimers()
+    try {
+      const db = TestApp.database()
+      vi.setSystemTime('2026-08-25T20:00:00.000Z')
+      const first = await RewardEligibilityAssociations.upsert(db, input)
+      vi.setSystemTime('2026-08-25T21:00:00.000Z')
+      const replay = await RewardEligibilityAssociations.upsert(db, {
+        ...input,
+        transactionHash: `0x${'44'.repeat(32)}`,
+      })
+
+      expect({ first, replay }).toMatchInlineSnapshot(`
+        {
+          "first": {
+            "created": true,
+            "record": {
+              "chainId": 4217,
+              "firstRegisteredAt": "2026-08-25T20:00:00.000Z",
+              "latestRegisteredAt": "2026-08-25T20:00:00.000Z",
+              "registrationOrder": "1",
+              "transactionHash": "0x3333333333333333333333333333333333333333333333333333333333333333",
+              "vaultAddress": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+              "walletAddress": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+            },
+          },
+          "replay": {
+            "created": false,
+            "record": {
+              "chainId": 4217,
+              "firstRegisteredAt": "2026-08-25T20:00:00.000Z",
+              "latestRegisteredAt": "2026-08-25T21:00:00.000Z",
+              "registrationOrder": "1",
+              "transactionHash": "0x4444444444444444444444444444444444444444444444444444444444444444",
+              "vaultAddress": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+              "walletAddress": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+            },
+          },
+        }
+      `)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('creates one row across concurrent duplicates', async () => {
+    const db = TestApp.databaseFactory()
+    const results = await Promise.all([
+      RewardEligibilityAssociations.upsert(db(), input),
+      RewardEligibilityAssociations.upsert(db(), input),
+    ])
+
+    expect(results.filter((result) => result.created)).toHaveLength(1)
+  })
+
+  test('does not let an older registration replace newer fields', async () => {
+    vi.useFakeTimers()
+    try {
+      const db = TestApp.database()
+      vi.setSystemTime('2026-08-25T21:00:00.000Z')
+      const newer = await RewardEligibilityAssociations.upsert(db, {
+        ...input,
+        transactionHash: `0x${'44'.repeat(32)}`,
+      })
+      vi.setSystemTime('2026-08-25T20:00:00.000Z')
+      const older = await RewardEligibilityAssociations.upsert(db, input)
+
+      expect(older.record).toEqual({
+        ...newer.record,
+        firstRegisteredAt: '2026-08-25T20:00:00.000Z',
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  test('accepts a missing transaction hash and preserves the latest known hash', async () => {
+    const db = TestApp.database()
+    const first = await RewardEligibilityAssociations.upsert(db, input)
+    const replay = await RewardEligibilityAssociations.upsert(db, {
+      chainId: input.chainId,
+      vaultAddress: input.vaultAddress,
+      walletAddress: input.walletAddress,
+    })
+
+    expect({ first: first.record.transactionHash, replay: replay.record.transactionHash }).toEqual({
+      first: input.transactionHash,
+      replay: input.transactionHash,
+    })
+  })
+
+  test('isolates the same association by chain', async () => {
+    const db = TestApp.database()
+    const results = await Promise.all([
+      RewardEligibilityAssociations.upsert(db, input),
+      RewardEligibilityAssociations.upsert(db, { ...input, chainId: 42_431 }),
+    ])
+
+    expect(results.map(({ created, record }) => ({ chainId: record.chainId, created }))).toEqual([
+      { chainId: 4217, created: true },
+      { chainId: 42_431, created: true },
+    ])
+  })
+})
+
+describe('list', () => {
+  test('returns only response-owned association columns', async () => {
+    const db = TestApp.database()
+    await db.kysely.schema
+      .alterTable('rewardEligibilityAssociations')
+      .addColumn('futureColumn', 'text')
+      .execute()
+    await RewardEligibilityAssociations.upsert(db, input)
+
+    const page = await RewardEligibilityAssociations.list(db, {
+      chainId: input.chainId,
+      limit: 10,
+      vaultAddress: input.vaultAddress,
+    })
+
+    expect(page.data[0]).not.toHaveProperty('futureColumn')
+  })
+
+  test('locks and reads a schema-scoped table', async () => {
+    const db = Db.postgres({
+      connectionString: Runtime.postgresUrl,
+      schema: `t_${nanoid()}`,
+    })
+    await db.migrate()
+    await RewardEligibilityAssociations.upsert(db, input)
+
+    expect(
+      await RewardEligibilityAssociations.list(db, {
+        chainId: input.chainId,
+        limit: 10,
+        vaultAddress: input.vaultAddress,
+      }),
+    ).toMatchObject({ data: [{ walletAddress: input.walletAddress.toLowerCase() }] })
+  })
+
+  test('paginates at a fixed checkpoint and excludes later registrations', async () => {
+    const db = TestApp.database()
+    const second = {
+      ...input,
+      walletAddress: Schema.Address.parse(`0x${'Cc'.repeat(20)}`),
+    }
+    const later = {
+      ...input,
+      walletAddress: Schema.Address.parse(`0x${'Dd'.repeat(20)}`),
+    }
+    await RewardEligibilityAssociations.upsert(db, input)
+    await RewardEligibilityAssociations.upsert(db, second)
+
+    const first = await RewardEligibilityAssociations.list(db, {
+      chainId: input.chainId,
+      limit: 1,
+      vaultAddress: input.vaultAddress,
+    })
+    await RewardEligibilityAssociations.upsert(db, later)
+    if (!first.nextCursor) throw new Error('Expected another eligibility page.')
+    const next = await RewardEligibilityAssociations.list(db, {
+      chainId: input.chainId,
+      cursor: first.nextCursor,
+      limit: 1,
+      vaultAddress: input.vaultAddress,
+    })
+    const fresh = await RewardEligibilityAssociations.list(db, {
+      chainId: input.chainId,
+      limit: 2,
+      vaultAddress: input.vaultAddress,
+    })
+    if (!fresh.nextCursor) throw new Error('Expected a fresh eligibility cursor.')
+
+    expect({
+      first: {
+        checkpoint: Cursor.decode(first.nextCursor, ['uint', 'uint'])?.[0],
+        nextCursor: first.nextCursor === null ? null : 'present',
+        wallets: first.data.map((record) => record.walletAddress),
+      },
+      fresh: {
+        checkpoint: Cursor.decode(fresh.nextCursor, ['uint', 'uint'])?.[0],
+        wallets: fresh.data.map((record) => record.walletAddress),
+      },
+      next: {
+        nextCursor: next.nextCursor,
+        wallets: next.data.map((record) => record.walletAddress),
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "first": {
+          "checkpoint": "2",
+          "nextCursor": "present",
+          "wallets": [
+            "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          ],
+        },
+        "fresh": {
+          "checkpoint": "3",
+          "wallets": [
+            "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+            "0xcccccccccccccccccccccccccccccccccccccccc",
+          ],
+        },
+        "next": {
+          "nextCursor": null,
+          "wallets": [
+            "0xcccccccccccccccccccccccccccccccccccccccc",
+          ],
+        },
+      }
+    `)
+  })
+
+  test('waits for in-flight registrations before fixing the checkpoint', async () => {
+    const getDb = TestApp.databaseFactory()
+    let release = () => {}
+    let inserted = () => {}
+    const pending = new Promise<void>((resolve) => (release = resolve))
+    const started = new Promise<void>((resolve) => (inserted = resolve))
+    const write = getDb().transaction(async (tx) => {
+      await RewardEligibilityAssociations.upsert(tx, input)
+      inserted()
+      await pending
+    })
+    await started
+    const pagePromise = RewardEligibilityAssociations.list(getDb(), {
+      chainId: input.chainId,
+      limit: 10,
+      vaultAddress: input.vaultAddress,
+    })
+    release()
+    await write
+
+    expect((await pagePromise).data.map((record) => record.walletAddress)).toEqual([
+      input.walletAddress.toLowerCase(),
+    ])
+  })
+
+  test('treats cursor integers above PostgreSQL bigint as invalid', async () => {
+    const db = TestApp.database()
+    await RewardEligibilityAssociations.upsert(db, input)
+
+    const page = await RewardEligibilityAssociations.list(db, {
+      chainId: input.chainId,
+      cursor: Cursor.encode(['9223372036854775808', '9223372036854775808']),
+      limit: 10,
+      vaultAddress: input.vaultAddress,
+    })
+
+    expect(page.data.map((record) => record.walletAddress)).toEqual([
+      input.walletAddress.toLowerCase(),
+    ])
+  })
+})

package/src/db/tables/rewardEligibilityAssociations.ts

@@ -0,0 +1,184 @@
+import { sql, type ColumnType, type Selectable } from 'kysely'
+import type { Hex } from 'ox'
+import type { Address } from 'viem'
+
+import * as Cursor from '../../internal/Cursor.js'
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `reward_eligibility_associations` table. */
+export type Table = Omit<
+  db_Schema.RewardEligibilityAssociation,
+  'chainId' | 'registrationOrder' | 'transactionHash'
+> & {
+  /** Bigint chain id, read as a string from pg and written as a number. */
+  chainId: ColumnType<string, number, number>
+  /** Database-assigned monotonic registration order. */
+  registrationOrder: ColumnType<string, never, never>
+  /** Optional transaction hash, stored as nullable text. */
+  transactionHash: Hex.Hex | null
+}
+
+/** A stored reward eligibility association. */
+export type Record = db_Schema.RewardEligibilityAssociation
+
+/** Inserts or refreshes one eligibility association. */
+export async function upsert(db: Db.Db, options: upsert.Options): Promise<upsert.Result> {
+  const now = new Date().toISOString()
+  const row = await db.kysely
+    .insertInto('reward_eligibility_associations')
+    .values({
+      chainId: options.chainId,
+      firstRegisteredAt: now,
+      latestRegisteredAt: now,
+      transactionHash: options.transactionHash ?? null,
+      vaultAddress: normalize(options.vaultAddress),
+      walletAddress: normalize(options.walletAddress),
+    })
+    .onConflict((oc) =>
+      oc.columns(['chainId', 'vaultAddress', 'walletAddress']).doUpdateSet({
+        firstRegisteredAt: sql<string>`LEAST(reward_eligibility_associations.first_registered_at, ${now})`,
+        latestRegisteredAt: sql<string>`GREATEST(reward_eligibility_associations.latest_registered_at, ${now})`,
+        transactionHash: sql<Hex.Hex | null>`CASE WHEN reward_eligibility_associations.latest_registered_at <= ${now} THEN COALESCE(${options.transactionHash ?? null}, reward_eligibility_associations.transaction_hash) ELSE reward_eligibility_associations.transaction_hash END`,
+      }),
+    )
+    .returning([
+      'chainId',
+      'firstRegisteredAt',
+      'latestRegisteredAt',
+      'registrationOrder',
+      'transactionHash',
+      'vaultAddress',
+      'walletAddress',
+    ])
+    .returning(sql<boolean>`xmax = 0`.as('created'))
+    .executeTakeFirstOrThrow()
+  const { created, ...record } = row
+  return { created, record: toRecord(record) }
+}
+
+export declare namespace upsert {
+  /** Fields supplied by one authorized registration source. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Transaction establishing the eligibility association, when available. */
+    transactionHash?: Hex.Hex | undefined
+    /** Earn vault address. */
+    vaultAddress: Address
+    /** Eligible wallet address. */
+    walletAddress: Address
+  }
+
+  /** Persisted association and whether this call inserted it. */
+  type Result = {
+    /** Whether this call inserted the association. */
+    created: boolean
+    /** Persisted association after the write. */
+    record: Record
+  }
+}
+
+/** Lists one vault's associations within a fixed high-water checkpoint. */
+export async function list(db: Db.Db, options: list.Options): Promise<list.Result> {
+  const value = options.cursor ? Cursor.decode(options.cursor, ['uint', 'uint']) : undefined
+  const decoded = isPaginationCursor(value) ? value : undefined
+  const checkpoint = decoded?.[0]
+  const after = decoded?.[1]
+  const highWater =
+    checkpoint !== undefined
+      ? checkpoint
+      : await db.transaction(async (tx) => {
+          await sql`LOCK TABLE ${sql.table('reward_eligibility_associations')} IN SHARE MODE`.execute(
+            tx.kysely,
+          )
+          return (
+            (
+              await tx.kysely
+                .selectFrom('reward_eligibility_associations')
+                .select((eb) => eb.fn.max('registrationOrder').as('checkpoint'))
+                .where('chainId', '=', String(options.chainId))
+                .where('vaultAddress', '=', normalize(options.vaultAddress))
+                .executeTakeFirstOrThrow()
+            ).checkpoint ?? '0'
+          )
+        })
+
+  let query = db.kysely
+    .selectFrom('reward_eligibility_associations')
+    .select([
+      'chainId',
+      'firstRegisteredAt',
+      'latestRegisteredAt',
+      'registrationOrder',
+      'transactionHash',
+      'vaultAddress',
+      'walletAddress',
+    ])
+    .where('chainId', '=', String(options.chainId))
+    .where('vaultAddress', '=', normalize(options.vaultAddress))
+    .where('registrationOrder', '<=', highWater)
+  if (after !== undefined) query = query.where('registrationOrder', '>', after)
+  const rows = await query
+    .orderBy('registrationOrder', 'asc')
+    .limit(options.limit + 1)
+    .execute()
+  const page = rows.slice(0, options.limit)
+  const last = page.at(-1)
+  return {
+    data: page.map(toRecord),
+    nextCursor:
+      rows.length > options.limit && last
+        ? Cursor.encode([highWater, last.registrationOrder])
+        : null,
+  }
+}
+
+export declare namespace list {
+  /** One checkpointed eligibility page selector. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Opaque cursor carrying the checkpoint and last registration order. */
+    cursor?: string | undefined
+    /** Maximum associations to return. */
+    limit: number
+    /** Earn vault address. */
+    vaultAddress: Address
+  }
+
+  /** One fixed-snapshot eligibility page. */
+  type Result = {
+    /** Persisted associations in registration order. */
+    data: Record[]
+    /** Cursor for the next page, or null at the end. */
+    nextCursor: string | null
+  }
+}
+
+function normalize(address: Address): Address {
+  // SAFETY: Lowercasing preserves the validated 20-byte address format.
+  return address.toLowerCase() as Address
+}
+
+function isPaginationCursor(value: Cursor.Cursor | undefined): value is [string, string] {
+  return (
+    value?.length === 2 &&
+    typeof value[0] === 'string' &&
+    typeof value[1] === 'string' &&
+    BigInt(value[0]) <= pgBigintMax &&
+    BigInt(value[1]) <= pgBigintMax
+  )
+}
+
+const pgBigintMax = 9_223_372_036_854_775_807n
+
+function toRecord(row: Selectable<Table>): Record {
+  const { transactionHash, ...record } = row
+  if (!transactionHash) return { ...record, chainId: Number(row.chainId) }
+  return {
+    ...record,
+    chainId: Number(row.chainId),
+    transactionHash,
+  }
+}