tapimo 0.14.0 → 0.15.0

package/src/internal/Webhooks.test.ts

@@ -1,6 +1,7 @@
-import { Webhooks } from 'tapimo'
+import { Webhooks } from 'tapimo/server'
 import { sql } from 'kysely'
 import * as TestApp from '../../test/App.js'
+import * as Organizations from '../db/tables/organizations.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import * as Metrics from '../Metrics.js'
 import * as Cursor from './Cursor.js'
@@ -157,6 +158,54 @@ describe('createSubscription', () => {
     expect(await Webhooks.listSubscriptions(getDb(), apiKeyOwner)).toHaveLength(3)
   })
 
+  test('enforces the cap across concurrent creates by sibling organizations', async () => {
+    const getDb = TestApp.databaseFactory()
+    await Organizations.create(getDb(), { id: 'org_sibling_a', name: 'Sibling A', userId: 'usr_owner' }) // prettier-ignore
+    await Organizations.create(getDb(), { id: 'org_sibling_b', name: 'Sibling B', userId: 'usr_owner' }) // prettier-ignore
+    const ownerA = { orgId: 'org_sibling_a', type: 'api_key' } as const
+    const ownerB = { orgId: 'org_sibling_b', type: 'api_key' } as const
+    await Webhooks.createSubscription(getDb(), createInput({ owner: ownerA }), { maxPerOwner: 2 })
+
+    const results = await Promise.allSettled([
+      Webhooks.createSubscription(getDb(), createInput({ owner: ownerA }), { maxPerOwner: 2 }),
+      Webhooks.createSubscription(getDb(), createInput({ owner: ownerB }), { maxPerOwner: 2 }),
+    ])
+
+    expect(results.map((result) => result.status).sort()).toMatchInlineSnapshot(`
+      [
+        "fulfilled",
+        "rejected",
+      ]
+    `)
+    const rejected = results.find((result) => result.status === 'rejected')
+    expect(rejected?.reason).toBeInstanceOf(Webhooks.LimitExceededError)
+    expect(
+      (await Webhooks.listSubscriptions(getDb(), ownerA)).length +
+        (await Webhooks.listSubscriptions(getDb(), ownerB)).length,
+    ).toBe(2)
+  })
+
+  test('keeps memberless organizations on independent caps', async () => {
+    const getDb = TestApp.databaseFactory()
+    await Organizations.create(getDb(), { id: 'org_admin_a', name: 'Admin A' })
+    await Organizations.create(getDb(), { id: 'org_admin_b', name: 'Admin B' })
+
+    await expect(
+      Promise.all([
+        Webhooks.createSubscription(
+          getDb(),
+          createInput({ owner: { orgId: 'org_admin_a', type: 'api_key' } }),
+          { maxPerOwner: 1 },
+        ),
+        Webhooks.createSubscription(
+          getDb(),
+          createInput({ owner: { orgId: 'org_admin_b', type: 'api_key' } }),
+          { maxPerOwner: 1 },
+        ),
+      ]),
+    ).resolves.toHaveLength(2)
+  })
+
   test('rejects an undeliverable URL before persisting', async () => {
     const db = TestApp.database()
     await expect(
@@ -172,25 +221,25 @@ describe('createSubscription', () => {
   })
 })
 
-describe('listActiveForFundingEvent', () => {
+describe('listActiveForRoutesEvent', () => {
   test('keeps selected subscriptions until the caller transaction commits', async () => {
     const getDb = TestApp.databaseFactory()
-    const owner = { orgId: 'org_funding_subscription_lock', type: 'api_key' } as const
+    const owner = { orgId: 'org_routes_subscription_lock', type: 'api_key' } as const
     const subscription = await Webhooks.createSubscription(
       getDb(),
       createInput({
         environment: 'production',
-        eventType: 'funding:transfer.updated',
+        eventType: 'routes:transfer.updated',
         owner,
       }),
     )
     const locked = Promise.withResolvers<void>()
     const release = Promise.withResolvers<void>()
     const read = getDb().transaction(async (tx) => {
-      const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(tx, {
+      const subscriptions = await WebhookSubscriptions.listActiveForRoutesEvent(tx, {
         chainId: 4217,
         environment: 'production',
-        eventType: 'funding:transfer.updated',
+        eventType: 'routes:transfer.updated',
         now: new Date().toISOString(),
         orgId: owner.orgId,
       })
@@ -923,6 +972,36 @@ async function stagedObligation(db: ReturnType<typeof TestApp.database>, logInde
 }
 
 describe('ensureQueueEvents', () => {
+  test('sanitizes nested NUL strings before persistence', async () => {
+    const db = TestApp.database()
+    const subscription = await Webhooks.createSubscription(db, createInput())
+    const envelope = Webhooks.buildEnvelope({
+      blockNumber: 123,
+      createdAt: fixedNow(),
+      data: {
+        token: {
+          name: 'Before\0After',
+          symbol: 'US\0D',
+        },
+        unchanged: 'before\\u0000after',
+      },
+      logIndex: 4,
+      subscription,
+    })
+
+    const { references: [reference] } = await Webhooks.ensureQueueEvents(db, [{ envelope, subscription }]) // prettier-ignore
+
+    expect((await Webhooks.getQueueEvent(db, reference!))?.envelope.data).toMatchInlineSnapshot(`
+      {
+        "token": {
+          "name": "Before�After",
+          "symbol": "US�D",
+        },
+        "unchanged": "before\\u0000after",
+      }
+    `)
+  })
+
   test('keeps oversized envelopes behind compact idempotent Queue references', async () => {
     const db = TestApp.database()
     const subscription = await Webhooks.createSubscription(

package/src/internal/Webhooks.ts

@@ -183,9 +183,8 @@ export type Delivery = {
 }
 
 /**
- * Creates a subscription, validating its URL and (optionally) enforcing a
- * per-owner cap, then persists it. Capped writes serialize per owner so
- * concurrent requests cannot exceed the limit.
+ * Creates a subscription, validates its URL, and optionally enforces a live
+ * subscription cap. API-key subscriptions share the cap across their creator's organizations.
  */
 export async function createSubscription(
   db: Db.Db,
@@ -245,7 +244,7 @@ export async function createSubscription(
 export declare namespace createSubscription {
   /** Options for {@link createSubscription}. */
   type Options = {
-    /** Reject creation once the owner has this many live subscriptions. */
+    /** Reject creation once the owner or API-key creator has this many live subscriptions. */
     maxPerOwner?: number | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
@@ -313,6 +312,25 @@ export declare namespace countSubscriptions {
   type Options = { access?: Access | undefined }
 }
 
+/** Counts subscriptions against the direct-owner or API-key creator cap. */
+export function countSubscriptionsForLimit(
+  db: Db.Db,
+  options: countSubscriptionsForLimit.Options,
+): Promise<number> {
+  return WebhookSubscriptions.countForLimit(db, {
+    now: new Date().toISOString(),
+    owner: options.owner,
+  })
+}
+
+export declare namespace countSubscriptionsForLimit {
+  /** Options for {@link countSubscriptionsForLimit}. */
+  type Options = {
+    /** Owner whose direct or creator-wide cap is counted. */
+    owner: Owner
+  }
+}
+
 /**
  * Patches an owner's subscription, re-validating the URL when changed.
  * Returns null when absent. The status column drives the partial active

package/src/internal/ZoneRpc.ts

@@ -0,0 +1,50 @@
+/** Read-only methods available through Zone RPC. */
+export const readMethods = new Set([
+  'eth_blobBaseFee',
+  'eth_blockNumber',
+  'eth_call',
+  'eth_chainId',
+  'eth_createAccessList',
+  'eth_estimateGas',
+  'eth_feeHistory',
+  'eth_fillTransaction',
+  'eth_gasPrice',
+  'eth_getBalance',
+  'eth_getBlockAccessList',
+  'eth_getBlockByHash',
+  'eth_getBlockByNumber',
+  'eth_getBlockReceipts',
+  'eth_getBlockTransactionCountByHash',
+  'eth_getBlockTransactionCountByNumber',
+  'eth_getCode',
+  'eth_getLogs',
+  'eth_getProof',
+  'eth_getRawTransactionByHash',
+  'eth_getStorageAt',
+  'eth_getStorageValues',
+  'eth_getTransactionByBlockHashAndIndex',
+  'eth_getTransactionByBlockNumberAndIndex',
+  'eth_getTransactionByHash',
+  'eth_getTransactionCount',
+  'eth_getTransactionReceipt',
+  'eth_getUncleByBlockHashAndIndex',
+  'eth_getUncleByBlockNumberAndIndex',
+  'eth_getUncleCountByBlockHash',
+  'eth_getUncleCountByBlockNumber',
+  'eth_maxPriorityFeePerGas',
+  'eth_simulateV1',
+  'eth_syncing',
+  'net_listening',
+  'net_peerCount',
+  'net_version',
+  'web3_clientVersion',
+  'web3_sha3',
+  'zone_getEncryptionKey',
+  'zone_getZoneInfo',
+])
+
+/** Methods that broadcast caller-signed Zone transactions. */
+export const writeMethods = new Set(['eth_sendRawTransaction', 'eth_sendRawTransactionSync'])
+
+/** Reads that require the public node to enforce the caller's account authorization. */
+export const tokenMethods = new Set(['zone_getAuthorizationTokenInfo', 'zone_getDepositStatus'])

package/src/internal/exchange/Provider.test.ts

@@ -47,9 +47,9 @@ describe('is', () => {
       name: 'Incomplete',
       type: 'exchange',
     })
-    const funding = core_Provider.from({ id: 'funding', name: 'Funding', type: 'funding' })
+    const routes = core_Provider.from({ id: 'routes', name: 'Routes', type: 'routes' })
 
-    expect([exchange, incomplete, funding].map(Provider.is)).toEqual([true, false, false])
+    expect([exchange, incomplete, routes].map(Provider.is)).toEqual([true, false, false])
   })
 })
 

package/src/internal/index.test.ts

@@ -13,7 +13,7 @@ test('exports internal modules', () => {
       "Exchange",
       "Fees",
       "Fetch",
-      "Funding",
+      "Routes",
       "Id",
       "Idempotency",
       "Log",
@@ -23,6 +23,7 @@ test('exports internal modules', () => {
       "Path",
       "Provider",
       "RateLimit",
+      "Rewards",
       "Response",
       "RpcSchema",
       "Schema",
@@ -31,6 +32,7 @@ test('exports internal modules', () => {
       "Timing",
       "Ttl",
       "Value",
+      "VercelOidc",
       "VerifiedTokens",
       "Viem",
       "WebhookDestination",

package/src/internal/index.ts

@@ -8,7 +8,7 @@ export * as Errors from './Errors.js'
 export * as Exchange from './exchange/index.js'
 export * as Fees from './Fees.js'
 export * as Fetch from './Fetch.js'
-export * as Funding from './funding/index.js'
+export * as Routes from './routes/index.js'
 export * as Id from './Id.js'
 export * as Idempotency from './Idempotency.js'
 export * as Log from './Log.js'
@@ -18,6 +18,7 @@ export * as OpenApi from './OpenApi.js'
 export * as Path from './Path.js'
 export * as Provider from './Provider.js'
 export * as RateLimit from './RateLimit.js'
+export * as Rewards from './rewards/index.js'
 export * as Response from './Response.js'
 export * as RpcSchema from './RpcSchema.js'
 export * as Schema from './Schema.js'
@@ -26,6 +27,7 @@ export * as Tidx from './Tidx.js'
 export * as Timing from './Timing.js'
 export * as Ttl from './Ttl.js'
 export * as Value from './Value.js'
+export * as VercelOidc from './VercelOidc.js'
 export * as VerifiedTokens from './VerifiedTokens.js'
 export * as Viem from './Viem.js'
 export * as WebhookDestination from './WebhookDestination.js'

package/src/internal/rewards/Audit.ts

@@ -0,0 +1,231 @@
+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 RewardEligibilityAssociations from '../../db/tables/rewardEligibilityAssociations.js'
+import type * as Tidx from '../Tidx.js'
+import type * as Campaigns from './Campaigns.js'
+import * as Events from './Events.js'
+import * as Projection from './Projection.js'
+
+/** Stored and replayed values of one projected balance. */
+export type Comparison = {
+  /** Value a fresh historical replay produces. */
+  expected: string
+  /** Value currently persisted in `reward_accounts`. */
+  stored: string
+}
+
+/** One registered recipient whose stored projection differs from its replay. */
+export type Discrepancy = {
+  /** Principal permanently allocated against campaign caps. */
+  allocatedPrincipalAssets: Comparison
+  /** Attributable public EarnShare balance. */
+  publicEarnShares: Comparison
+  /** Qualified EarnShare balance. */
+  qualifiedEarnShares: Comparison
+  /** Registered recipient. */
+  recipient: Address
+}
+
+/** Result of comparing one campaign's stored projections against replayed history. */
+export type Report = {
+  /** Total principal allocated across every stored and every replayed account. */
+  allocatedPrincipalAssets: Comparison
+  /** Campaign identity and the cursor the replay was bounded to. */
+  campaign: {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Last event applied by the delivered projection. */
+    eventCursor: Campaigns.EventCursor
+    /** Whether the campaign is paused. */
+    paused: boolean
+    /** Per-user principal cap in base-asset units. */
+    perUserPrincipalCapAssets: string
+    /** Campaign-wide principal cap in base-asset units. */
+    totalPrincipalCapAssets: string
+    /** EarnVault address. */
+    vaultAddress: Address
+  }
+  /** Accounts whose stored balances differ from replay without an allocation shortfall. */
+  drift: readonly Discrepancy[]
+  /** Accounts whose replay allocates more principal than is stored: deposits the projection never applied. */
+  missingDeposits: readonly Discrepancy[]
+  /** Stored account count. */
+  storedAccounts: number
+  /** Eligible registrations for the campaign. */
+  registrations: number
+  /** Registered recipients without a stored account; the next run replays them. */
+  unprojected: readonly Address[]
+}
+
+/**
+ * Replays every eligible registration's deposit and EarnShare history through
+ * the campaign's committed cursor and compares it with the stored projections.
+ */
+export async function audit(options: audit.Options): Promise<Report> {
+  const { db, tidx } = options
+  const campaign = await RewardCampaigns.get(db, options)
+  if (!campaign) throw new AuditError('Reward campaign not found.')
+  const boost = campaign.config.boostRewards
+  if (!boost) throw new AuditError('Reward campaign has no boost rewards to audit.')
+  if (!campaign.eventCursor) throw new AuditError('Reward campaign has not delivered a run yet.')
+  const eventCursor = campaign.eventCursor
+  const eligible = await allEligible(db, campaign)
+  const registrations = eligible.map((entry) => ({
+    recipient: getAddress(entry.walletAddress),
+    registeredAt: entry.latestRegisteredAt,
+    registrationOrder: BigInt(entry.registrationOrder),
+  }))
+  const stored = await RewardAccounts.list(db, campaign)
+  const storedByRecipient = new Map(
+    stored.map((account) => [account.recipient.toLowerCase(), account]),
+  )
+  // Replay from an empty projection so every registration is rebuilt from history. Exclusions are
+  // skipped: they only remove protocol contracts, which cannot register as eligible wallets.
+  const replayed =
+    registrations.length === 0
+      ? []
+      : (
+          await Projection.reconcilePages({
+            accounts: [],
+            eligible: registrations,
+            excluded: [],
+            pages: () =>
+              boundedPages(
+                Events.accountEventPages(tidx, {
+                  accounts: registrations.map((entry) => entry.recipient),
+                  earnShare: campaign.earnShareAddress,
+                  earnVault: campaign.vaultAddress,
+                  throughBlock: eventCursor.blockNumber,
+                }),
+                eventCursor,
+              ),
+            perUserPrincipalCapAssets: BigInt(boost.perUserPrincipalCapAssets),
+            principalAllocationOrder: 'deposit',
+            totalPrincipalCapAssets: BigInt(boost.totalPrincipalCapAssets),
+          })
+        ).accounts
+  const missingDeposits: Discrepancy[] = []
+  const drift: Discrepancy[] = []
+  const unprojected: Address[] = []
+  for (const account of replayed) {
+    const record = storedByRecipient.get(account.recipient.toLowerCase())
+    if (!record) {
+      unprojected.push(account.recipient)
+      continue
+    }
+    const discrepancy: Discrepancy = {
+      allocatedPrincipalAssets: compare(
+        record.allocatedPrincipalAssets,
+        account.allocatedPrincipalAssets,
+      ),
+      publicEarnShares: compare(record.publicEarnShares, account.publicEarnShares),
+      qualifiedEarnShares: compare(record.qualifiedEarnShares, account.qualifiedEarnShares),
+      recipient: account.recipient,
+    }
+    if (account.allocatedPrincipalAssets > BigInt(record.allocatedPrincipalAssets))
+      missingDeposits.push(discrepancy)
+    else if (
+      discrepancy.allocatedPrincipalAssets.expected !==
+        discrepancy.allocatedPrincipalAssets.stored ||
+      discrepancy.publicEarnShares.expected !== discrepancy.publicEarnShares.stored ||
+      discrepancy.qualifiedEarnShares.expected !== discrepancy.qualifiedEarnShares.stored
+    )
+      drift.push(discrepancy)
+  }
+  return {
+    allocatedPrincipalAssets: compare(
+      stored.reduce((sum, account) => sum + BigInt(account.allocatedPrincipalAssets), 0n),
+      replayed.reduce((sum, account) => sum + account.allocatedPrincipalAssets, 0n),
+    ),
+    campaign: {
+      chainId: campaign.chainId,
+      eventCursor,
+      paused: campaign.paused,
+      perUserPrincipalCapAssets: boost.perUserPrincipalCapAssets,
+      totalPrincipalCapAssets: boost.totalPrincipalCapAssets,
+      vaultAddress: campaign.vaultAddress,
+    },
+    drift,
+    missingDeposits,
+    registrations: registrations.length,
+    storedAccounts: stored.length,
+    unprojected,
+  }
+}
+
+export declare namespace audit {
+  /** Campaign selector and data sources. */
+  type Options = {
+    /** Chain containing the vault. */
+    chainId: number
+    /** Authoritative Postgres connection. */
+    db: Db.Db
+    /** TIDX client for the campaign chain. */
+    tidx: Tidx.Client
+    /** EarnVault address. */
+    vaultAddress: string
+  }
+}
+
+/**
+ * Clears deposit-derived state for the given recipients so the next reward run
+ * replays their history through the registration reconciliation path.
+ */
+export async function reset(options: reset.Options): Promise<number> {
+  return RewardAccounts.resetPrincipal(options.db, options)
+}
+
+export declare namespace reset {
+  /** Recipients to rebuild on the next run. */
+  type Options = RewardAccounts.resetPrincipal.Options & {
+    /** Authoritative Postgres connection. */
+    db: Db.Db
+  }
+}
+
+/** Drops events past the committed cursor; pages are block-bounded, the cursor is log-bounded. */
+async function* boundedPages(
+  pages: AsyncIterable<readonly Projection.Event[]>,
+  cursor: Campaigns.EventCursor,
+): AsyncGenerator<Projection.reconcilePages.Page> {
+  for await (const page of pages) {
+    const events = page.filter((event) => compareCursors(event.cursor, cursor) <= 0)
+    if (events.length > 0) yield { events }
+  }
+}
+
+async function allEligible(db: Db.Db, campaign: RewardCampaigns.Record) {
+  const records: RewardEligibilityAssociations.Record[] = []
+  let cursor: string | undefined
+  do {
+    const page = await RewardEligibilityAssociations.list(db, {
+      chainId: campaign.chainId,
+      ...(cursor ? { cursor } : {}),
+      limit: 1_000,
+      vaultAddress: campaign.vaultAddress,
+    })
+    records.push(...page.data)
+    cursor = page.nextCursor ?? undefined
+  } while (cursor)
+  return records
+}
+
+function compare(stored: bigint | string, expected: bigint): Comparison {
+  return { expected: expected.toString(), stored: stored.toString() }
+}
+
+function compareCursors(left: Campaigns.EventCursor, right: Campaigns.EventCursor): number {
+  if (left.blockNumber !== right.blockNumber) return left.blockNumber < right.blockNumber ? -1 : 1
+  if (left.transactionIndex !== right.transactionIndex)
+    return left.transactionIndex < right.transactionIndex ? -1 : 1
+  if (left.logIndex !== right.logIndex) return left.logIndex < right.logIndex ? -1 : 1
+  return 0
+}
+
+/** The campaign cannot be audited in its current state. */
+export class AuditError extends Error {
+  override name = 'Audit.AuditError'
+}