tapimo 0.14.0 → 0.15.1

package/src/internal/rewards/Credits.ts

@@ -0,0 +1,165 @@
+import { getAddress, type Address } from 'viem'
+
+import type * as Db from '../../db/Db.js'
+import * as RewardAccounts from '../../db/tables/rewardAccounts.js'
+import * as RewardCampaigns from '../../db/tables/rewardCampaigns.js'
+import * as RewardCredits from '../../db/tables/rewardCredits.js'
+import * as RewardRuns from '../../db/tables/rewardRuns.js'
+
+/** One requested manual credit. */
+export type Credit = {
+  /** Base-asset reward units to add to pending rewards. */
+  assets: bigint
+  /** Registered recipient. */
+  recipient: Address
+}
+
+/** Requested credit annotated with whether it can be applied. */
+export type Line = Credit & {
+  /**
+   * `pending` has a stored account and no credit under this reference yet; `applied` was already
+   * credited under this reference; `missing_account` has no `reward_accounts` row to receive it.
+   */
+  status: 'applied' | 'missing_account' | 'pending'
+}
+
+/** Result of examining one credit batch against the campaign's stored state. */
+export type Report = {
+  /** Credits already applied under this reference; replaying them is a no-op. */
+  appliedAssets: bigint
+  /** Why `ready` is false, for operator output. */
+  blockers: readonly string[]
+  /** Latest run phase, or null when the campaign never ran. */
+  latestRunPhase: string | null
+  /** Requested credits with their per-recipient status. */
+  lines: readonly Line[]
+  /** Recipients without a stored reward account. */
+  missing: readonly Address[]
+  /** Whether the campaign is paused; settlement must not commit while credits are written. */
+  paused: boolean
+  /** Credits that would be written by `apply`. */
+  pendingAssets: bigint
+  /** Whether `apply` would proceed: paused, no run in flight, and no missing accounts. */
+  ready: boolean
+}
+
+/** Run phases after which no settlement commit can overwrite `reward_accounts`. */
+const settledPhases = new Set(['delivered', 'failed'])
+
+/** Examines a credit batch without writing anything. */
+export async function review(options: review.Options): Promise<Report> {
+  const { credits, db, reference } = options
+  const campaign = await RewardCampaigns.get(db, options)
+  if (!campaign) throw new CreditsError('Reward campaign not found.')
+  if (!campaign.config.boostRewards)
+    throw new CreditsError('Reward campaign has no boost rewards to credit.')
+  const duplicate = findDuplicate(credits)
+  if (duplicate) throw new CreditsError(`Recipient ${duplicate} appears more than once.`)
+  const latest = await RewardRuns.latestSummary(db, options)
+  const latestRunPhase = latest?.phase ?? null
+  const accounts = new Set(
+    (await RewardAccounts.list(db, options)).map((account) => account.recipient.toLowerCase()),
+  )
+  const applied = new Set(
+    (await RewardCredits.list(db, { ...options, reference })).map((credit) =>
+      credit.recipient.toLowerCase(),
+    ),
+  )
+  const lines = credits.map((credit): Line => {
+    const key = credit.recipient.toLowerCase()
+    if (applied.has(key)) return { ...credit, status: 'applied' }
+    if (!accounts.has(key)) return { ...credit, status: 'missing_account' }
+    return { ...credit, status: 'pending' }
+  })
+  const missing = lines
+    .filter((line) => line.status === 'missing_account')
+    .map((line) => line.recipient)
+  const blockers: string[] = []
+  if (!campaign.paused) blockers.push('Campaign is not paused.')
+  if (latestRunPhase !== null && !settledPhases.has(latestRunPhase))
+    blockers.push(`Latest run is still in phase "${latestRunPhase}".`)
+  if (missing.length > 0) blockers.push(`${missing.length} recipient(s) have no reward account.`)
+  return {
+    appliedAssets: sum(lines.filter((line) => line.status === 'applied')),
+    blockers,
+    latestRunPhase,
+    lines,
+    missing,
+    paused: campaign.paused,
+    pendingAssets: sum(lines.filter((line) => line.status === 'pending')),
+    ready: blockers.length === 0,
+  }
+}
+
+export declare namespace review {
+  /** Campaign identity and the credit batch to examine. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Requested credits. */
+    credits: readonly Credit[]
+    /** Database owning the campaign. */
+    db: Db.Db
+    /** Batch reference that makes the credits run-once. */
+    reference: string
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+/**
+ * Writes every pending credit into `pending_reward_assets`. Refuses unless `review` reports the
+ * campaign ready, because a settlement commit replaces `reward_accounts` wholesale.
+ */
+export async function apply(options: apply.Options): Promise<apply.Result> {
+  const { chainId, credits, db, reference, vaultAddress } = options
+  const report = await review(options)
+  if (!report.ready) throw new CreditsError(`Cannot apply credits: ${report.blockers.join(' ')}`)
+  let credited = 0
+  let replayed = 0
+  for (const credit of credits) {
+    const result = await RewardCredits.apply(db, {
+      assets: credit.assets,
+      chainId,
+      recipient: credit.recipient,
+      reference,
+      vaultAddress,
+    })
+    if (result.credited) credited += 1
+    else replayed += 1
+  }
+  return { credited, creditedAssets: report.pendingAssets, replayed }
+}
+
+export declare namespace apply {
+  /** Same inputs as `review`. */
+  type Options = review.Options
+  /** Counts of what this call wrote versus found already written. */
+  type Result = {
+    /** Recipients credited by this call. */
+    credited: number
+    /** Base-asset units written by this call. */
+    creditedAssets: bigint
+    /** Recipients already credited under this reference before this call. */
+    replayed: number
+  }
+}
+
+function findDuplicate(credits: readonly Credit[]): Address | undefined {
+  const seen = new Set<string>()
+  for (const credit of credits) {
+    const key = credit.recipient.toLowerCase()
+    if (seen.has(key)) return getAddress(credit.recipient)
+    seen.add(key)
+  }
+  return undefined
+}
+
+function sum(lines: readonly Line[]): bigint {
+  return lines.reduce((total, line) => total + line.assets, 0n)
+}
+
+/** Thrown when a credit batch cannot be examined or applied. */
+export class CreditsError extends Error {
+  override name = 'Credits.CreditsError'
+}

package/src/internal/rewards/Events.local.test.ts

@@ -0,0 +1,113 @@
+/** @module-tag localnet */
+
+import { sendTransactionSync } from 'viem/actions'
+import { Actions } from 'viem/tempo'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as TestTempo from '../../../test/Tempo.js'
+import * as Events from './Events.js'
+import * as Tidx from '../Tidx.js'
+import * as Value from '../Value.js'
+
+describe.runIf(Runtime.get().mode === 'localnet')('boundary', () => {
+  test('waits until the indexer has crossed the requested boundary', async () => {
+    const runtime = Runtime.get()
+    const tidx = Tidx.getClient({
+      chainId: runtime.chainId,
+      tidx: { baseUrl: runtime.tidxUrl },
+    })
+    const head = await tidx.fetch({ query: 'SELECT max(timestamp) AS timestamp FROM blocks' })
+    const indexedAt = Value.toIsoDateTime(head.rows[0]?.['timestamp'])
+    if (!indexedAt) throw new Error('Local TIDX did not return its indexed head.')
+    const timestamp = Math.floor(Date.parse(indexedAt) / 1_000)
+
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.max(timestamp * 1_000 + 1_000 - Date.now(), 0)),
+    )
+    await Actions.faucet.fundSync(TestTempo.client, {
+      account: TestTempo.accounts[4],
+      timeout: 60_000,
+    })
+
+    await expect
+      .poll(
+        () =>
+          Events.boundary(tidx, timestamp + 1)
+            .then((boundary) => boundary.timestamp)
+            .catch(() => timestamp + 1),
+        { timeout: 30_000 },
+      )
+      .toBeLessThan(timestamp + 1)
+
+    const chainHead = await TestTempo.client.getBlock()
+    const unavailableTimestamp = Number(chainHead.timestamp) + 1
+    await expect(Events.boundary(tidx, unavailableTimestamp)).rejects.toThrow(
+      `TIDX has not indexed reward boundary ${unavailableTimestamp}.`,
+    )
+  })
+})
+
+describe.runIf(Runtime.get().mode === 'localnet')('accountEventPages', () => {
+  test('reads relevant account pages and distinct capital changes from TIDX', async () => {
+    const runtime = Runtime.get()
+    const tidx = Tidx.getClient({
+      chainId: runtime.chainId,
+      tidx: { baseUrl: runtime.tidxUrl },
+    })
+    const account = TestTempo.accounts[0]
+    const client = TestTempo.getClient({ account })
+    const { token } = await Actions.token.createSync(client, {
+      currency: 'USD',
+      name: 'Reward Principal',
+      symbol: 'PRINCIPAL',
+    })
+    const opening = await sendTransactionSync(client, {
+      calls: [
+        Actions.token.grantRoles.call(client, { role: 'issuer', to: account.address, token }),
+        Actions.token.mint.call(client, { amount: 1_000n, to: account.address, token }),
+      ],
+    })
+    const minted = await Actions.token.mintSync(client, {
+      amount: 100n,
+      to: account.address,
+      token,
+    })
+    const burned = await Actions.token.burnSync(client, { amount: 100n, token })
+    const throughBlock = Number(burned.receipt.blockNumber)
+    await expect
+      .poll(
+        async () => {
+          const changes = await Events.capitalChanges(tidx, {
+            afterBlock: Number(opening.blockNumber),
+            earnShare: token,
+            throughBlock,
+          })
+          return changes.map((entry) => entry.blockNumber)
+        },
+        { timeout: 30_000 },
+      )
+      .toStrictEqual([Number(minted.receipt.blockNumber), throughBlock])
+
+    const pages = Events.accountEventPages(tidx, {
+      after: {
+        blockNumber: Number(opening.blockNumber),
+        logIndex: Number.MAX_SAFE_INTEGER,
+        transactionIndex: Number.MAX_SAFE_INTEGER,
+      },
+      accounts: [account.address],
+      earnShare: token,
+      earnVault: token,
+      throughBlock,
+    })
+    const events = (await Array.fromAsync(pages)).flat()
+    expect(
+      events.map((event) => ({
+        blockNumber: event.cursor.blockNumber,
+        kind: event.kind,
+      })),
+    ).toStrictEqual([
+      { blockNumber: Number(minted.receipt.blockNumber), kind: 'transfer' },
+      { blockNumber: throughBlock, kind: 'transfer' },
+    ])
+  })
+})

package/src/internal/rewards/Events.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from 'vitest'
+
+import * as Campaigns from './Campaigns.js'
+import * as Events from './Events.js'
+
+const account = '0x0000000000000000000000000000000000000001'
+const other = '0x0000000000000000000000000000000000000002'
+const share = '0x0000000000000000000000000000000000000003'
+const vault = '0x0000000000000000000000000000000000000004'
+
+test('boundary excludes blocks exactly on the next interval boundary', () => {
+  expect(Events.boundaryQuery(1_788_005_100)).toMatchInlineSnapshot(`
+    "
+        SELECT num, timestamp, (SELECT max(timestamp) FROM blocks) AS indexed_through
+        FROM blocks
+        WHERE timestamp < '2026-08-29 12:05:00.000'
+        ORDER BY timestamp DESC, num DESC
+        LIMIT 1
+      "
+  `)
+})
+
+describe('accountEventsQuery', () => {
+  test('bounds history to nonzero external transfers involving tracked accounts', () => {
+    const query = Events.accountEventsQuery({
+      accounts: [account, other, account],
+      after: { blockNumber: 10, logIndex: 2, transactionIndex: 1 },
+      earnShare: share,
+      earnVault: vault,
+      throughBlock: 20,
+    })
+
+    expect(query).toContain(`lower(receiver) IN ('${account}', '${other}')`)
+    expect(query).toContain(
+      `(lower("from") IN ('${account}', '${other}') OR lower("to") IN ('${account}', '${other}'))`,
+    )
+    expect(query).toContain('AND lower("from") != lower("to")')
+    expect(query).toContain('AND toUInt256(amount) > 0')
+    expect(query).toContain(
+      'AND (block_num > 10 OR (block_num = 10 AND (tx_idx > 1 OR (tx_idx = 1 AND log_idx > 2))))',
+    )
+    expect(query).toContain('LIMIT 10000')
+  })
+})
+
+describe('accountDepositsQuery', () => {
+  test('reads distinct positive deposits received by one tracked account', () => {
+    const query = Events.accountDepositsQuery({
+      account,
+      after: { blockNumber: 10, logIndex: 2, transactionIndex: 1 },
+      earnVault: vault,
+      throughBlock: 20,
+    })
+
+    expect(query).toContain("SELECT DISTINCT 'deposit' AS kind")
+    expect(query).toContain(`AND lower(receiver) = '${account}'`)
+    expect(query).toContain('AND toUInt256(assets) > 0')
+    expect(query).toContain('AND toUInt256("earnShares") > 0')
+    expect(query).not.toContain('token_transfers')
+    expect(query).toContain(
+      'AND (block_num > 10 OR (block_num = 10 AND (tx_idx > 1 OR (tx_idx = 1 AND log_idx > 2))))',
+    )
+  })
+})
+
+describe('capitalChangesQuery', () => {
+  test('bounds target principal history to distinct nonzero supply-change blocks', () => {
+    const query = Events.capitalChangesQuery({
+      afterBlock: 10,
+      earnShare: share,
+      throughBlock: 20,
+    })
+
+    expect(query).toContain(
+      `AND (lower("from") = '0x0000000000000000000000000000000000000000' OR lower("to") = '0x0000000000000000000000000000000000000000')`,
+    )
+    expect(query).toContain('AND toUInt256(amount) > 0')
+    expect(query).toContain('AND block_num > 10')
+    expect(query).toContain('AND block_num <= 20')
+    expect(query).toContain('GROUP BY block_num')
+    expect(query).toContain('LIMIT 10000')
+  })
+
+  test('retains same-second principal changes on their own bases', () => {
+    const states = [
+      {
+        assets: 100_000_000n,
+        blockNumber: 10,
+        price: 1_000_000_000n,
+        supply: 100_000_000n,
+        timestamp: 300,
+      },
+      {
+        assets: 500_000_000n,
+        blockNumber: 11,
+        price: 500_000_000n,
+        supply: 1_000_000_000n,
+        timestamp: 301,
+      },
+      {
+        assets: 1_100_000_000n,
+        blockNumber: 12,
+        price: 1_000_000_000n,
+        supply: 1_100_000_000n,
+        timestamp: 301,
+      },
+      {
+        assets: 1_100_000_000n,
+        blockNumber: 13,
+        price: 1_000_000_000n,
+        supply: 1_100_000_000n,
+        timestamp: 600,
+      },
+    ]
+    const boundaries = [
+      { blockNumber: 11, timestamp: 301 },
+      { blockNumber: 12, timestamp: 301 },
+    ]
+    const checkpoints = [
+      states[0]!,
+      ...boundaries.map(
+        ({ blockNumber }) => states.find((state) => state.blockNumber === blockNumber)!,
+      ),
+      states[3]!,
+    ]
+    const periods = checkpoints.slice(0, -1).map((opening, index) => {
+      const closing = checkpoints[index + 1]!
+      return {
+        closingValuePerEarnShare: closing.price,
+        contributions: [],
+        elapsedSeconds: closing.timestamp - opening.timestamp,
+        openingAssets: opening.assets,
+        openingEarnShareSupply: opening.supply,
+        openingValuePerEarnShare: opening.price,
+      }
+    })
+    // The loss and recovery occur on different principal bases, leaving organic growth below the target.
+    expect(
+      Campaigns.targetFunding({
+        annualRateBps: 1_000,
+        funding: [{ remainder: true, wallet: share }],
+        periods,
+        remainders: [],
+      }).assets,
+    ).toMatchInlineSnapshot(`
+      [
+        0n,
+      ]
+    `)
+    expect(periods.map((period) => period.elapsedSeconds)).toStrictEqual([1, 0, 299])
+  })
+})