tapimo 0.15.0 → 0.18.0

package/src/internal/EarnWithdrawals.ts

@@ -0,0 +1,266 @@
+import type { Address } from 'viem'
+import * as z from 'zod/mini'
+
+import * as EarnSharePrices from './EarnSharePrices.js'
+import * as Schema from './Schema.js'
+import type * as Tidx from './Tidx.js'
+import type * as Viem from './Viem.js'
+
+/** Reads outgoing shares not already accounted for by the wallet's own vault exits. */
+export async function read(tidx: Tidx.Client, options: read.Options) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    // Dynamic addresses and bounds are validated by the owning route and registry.
+    // Aggregate each branch to avoid row truncation without exceeding TIDX's query-nesting limit.
+    query: `
+      WITH candidates AS (
+        SELECT DISTINCT tx_hash FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}'
+          AND "from" = '${options.account}' AND "to" != '${options.account}'
+          AND toUInt256(amount) > 0
+          AND block_num > ${options.startBlockNumber} AND block_num <= ${options.blockNumber}
+      )
+        SELECT toJSONString(groupArray(tuple('transfer', tx_hash, log_idx, "from", "to",
+          toString(toUInt256(amount)), '0', block_num))) AS events
+        FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}' AND tx_hash IN (SELECT tx_hash FROM candidates)
+          AND toUInt256(amount) > 0
+          AND block_num > ${options.startBlockNumber} AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT toJSONString(groupArray(tuple('withdrawal', tx_hash, log_idx, caller, receiver,
+          toString(toUInt256(earnShares)), toString(toUInt256(assets)), block_num))) AS events
+        FROM Redeemed
+        WHERE address = '${options.vault}'
+          AND tx_hash IN (SELECT tx_hash FROM candidates)
+          AND block_num > ${options.startBlockNumber} AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT toJSONString(groupArray(tuple('withdrawal', tx_hash, log_idx, caller, receiver,
+          toString(toUInt256(earnSharesBurned)), toString(toUInt256(assets)), block_num))) AS events
+        FROM WithdrewExact
+        WHERE address = '${options.vault}'
+          AND tx_hash IN (SELECT tx_hash FROM candidates)
+          AND block_num > ${options.startBlockNumber} AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT toJSONString(groupArray(tuple('request', tx_hash, log_idx, requester, receiver,
+          toString(toUInt256(earnShares)), '0', block_num))) AS events
+        FROM RedeemRequested
+        WHERE address = '${options.vault}' AND requester = '${options.account}'
+          AND tx_hash IN (SELECT tx_hash FROM candidates)
+          AND block_num > ${options.startBlockNumber} AND block_num <= ${options.blockNumber}
+    ` as string,
+    signatures: [
+      'event Redeemed(address indexed caller,address indexed receiver,uint256 earnShares,uint256 assets)',
+      'event WithdrewExact(address indexed caller,address indexed receiver,uint256 assets,uint256 earnSharesBurned)',
+      'event RedeemRequested(bytes32 indexed requestId,address indexed requester,address indexed receiver,uint256 earnShares)',
+    ],
+  })
+  if (result.rows.length !== 4) throw new Error('TIDX returned incomplete Earn withdrawal history.')
+  const tuples = result.rows.flatMap((row) =>
+    z.array(schema.Event).parse(JSON.parse(String(row['events']))),
+  )
+  return classify({
+    ...options,
+    events: tuples.map(
+      ([kind, transactionHash, logIndex, sender, receiver, shares, assets, blockNumber]) => ({
+        assets: BigInt(assets),
+        blockNumber,
+        kind,
+        logIndex,
+        receiver,
+        sender,
+        shares: BigInt(shares),
+        transactionHash,
+      }),
+    ),
+  })
+}
+
+export declare namespace read {
+  /** Scope of one wallet's indexed share history. */
+  type Options = {
+    /** Wallet whose shares fund withdrawals. */
+    account: Address
+    /** Inclusive indexed upper bound. */
+    blockNumber: number
+    /** Share token belonging to the vault. */
+    shareToken: Address
+    /** Exclusive indexed lower bound. */
+    startBlockNumber: number
+    /** Vault emitting withdrawal events. */
+    vault: Address
+  }
+}
+
+/** Values transfers at historical redemption quotes, retaining actual proceeds for proven vault exits. */
+export async function value(client: Viem.getClient.ReturnType, options: value.Options) {
+  let total = 0n
+  // Bound archive RPC fan-out; missing quotes must never silently become zero withdrawals.
+  for (let index = 0; index < options.withdrawals.length; index += 4) {
+    const amounts = await Promise.all(
+      options.withdrawals.slice(index, index + 4).map(async (withdrawal) => {
+        if (withdrawal.assets !== undefined) return withdrawal.assets
+        try {
+          return await client.earn.getRedeemQuote({
+            blockNumber: BigInt(withdrawal.blockNumber),
+            shareAmount: withdrawal.shares,
+            vault: options.vault,
+          })
+        } catch (error) {
+          if (EarnSharePrices.isUnavailable(error)) return undefined
+          throw error
+        }
+      }),
+    )
+    for (const amount of amounts) {
+      if (amount === undefined) return undefined
+      total += amount
+    }
+  }
+  return total
+}
+
+export declare namespace value {
+  /** Withdrawals and the vault used for historical asset valuation. */
+  type Options = {
+    /** Vault owning the transferred shares. */
+    vault: Address
+    /** Outgoing shares, with actual proceeds when unambiguous. */
+    withdrawals: readonly classify.Withdrawal[]
+  }
+}
+
+/** Separates already-accounted protocol exits from recipient-independent wallet withdrawals. */
+export function classify(options: match.Options) {
+  const transactions = new Map<string, match.Event[]>()
+  for (const event of options.events) {
+    if (event.shares === 0n || (event.kind === 'transfer' && event.sender === event.receiver))
+      continue
+    const events = transactions.get(event.transactionHash) ?? []
+    events.push(event)
+    transactions.set(event.transactionHash, events)
+  }
+  const withdrawals: classify.Withdrawal[] = []
+  for (const events of transactions.values()) {
+    const outgoing = events
+      .filter((event) => event.kind === 'transfer' && event.sender === options.account)
+      .sort((a, b) => a.logIndex - b.logIndex)
+    const accounted = new Set<number>()
+    // Direct exits and async requests are accounted by protocol history, including later finalization or cancellation.
+    for (const exit of events
+      .filter((event) => event.kind !== 'transfer' && event.sender === options.account)
+      .sort((a, b) => a.logIndex - b.logIndex)) {
+      const transfer = outgoing.findLast(
+        (event) =>
+          event.receiver === options.vault &&
+          event.shares === exit.shares &&
+          event.logIndex < exit.logIndex &&
+          !accounted.has(event.logIndex),
+      )
+      if (transfer) accounted.add(transfer.logIndex)
+    }
+    const matched = match({ ...options, events })
+    for (const transfer of outgoing) {
+      if (accounted.has(transfer.logIndex)) continue
+      withdrawals.push({
+        assets: matched.find((exit) => exit.logIndex === transfer.logIndex)?.assets,
+        blockNumber: transfer.blockNumber,
+        logIndex: transfer.logIndex,
+        shares: transfer.shares,
+        transactionHash: transfer.transactionHash,
+      })
+    }
+  }
+  return withdrawals
+}
+
+export declare namespace classify {
+  /** Outgoing share value not already included in protocol withdrawal totals. */
+  type Withdrawal = Pick<match.Event, 'blockNumber' | 'logIndex' | 'shares' | 'transactionHash'> & {
+    /** Actual proceeds when matched; otherwise use a historical quote. */
+    assets: bigint | undefined
+  }
+}
+
+/** Matches actual proceeds for single-funder, single-exit routes without a spender allowlist. */
+export function match(options: match.Options) {
+  const matched: match.Withdrawal[] = []
+  for (const exit of options.events) {
+    if (exit.kind !== 'withdrawal') continue
+    if (exit.sender === options.account || exit.sender === options.vault) continue
+    // Zero-value transfers cannot fund an exit and must not make a valid route ambiguous.
+    const events = options.events.filter(
+      (event) => event.transactionHash === exit.transactionHash && event.shares > 0n,
+    )
+    if (
+      events.filter((event) => event.kind === 'withdrawal' && event.sender === exit.sender)
+        .length !== 1
+    )
+      continue
+    const received = events.filter(
+      (event) => event.kind === 'transfer' && event.receiver === exit.sender,
+    )
+    const sent = events.filter((event) => event.kind === 'transfer' && event.sender === exit.sender)
+    // Requiring exactly two share movements prevents attributing another funder's or a batched exit's assets to this wallet.
+    if (received.length !== 1 || sent.length !== 1) continue
+    const incoming = received[0]!
+    const outgoing = sent[0]!
+    if (
+      incoming.sender !== options.account ||
+      outgoing.receiver !== options.vault ||
+      incoming.shares === 0n ||
+      incoming.shares !== exit.shares ||
+      outgoing.shares !== exit.shares ||
+      incoming.logIndex >= outgoing.logIndex ||
+      outgoing.logIndex >= exit.logIndex
+    )
+      continue
+    matched.push({
+      assets: exit.assets,
+      logIndex: incoming.logIndex,
+      transactionHash: exit.transactionHash,
+    })
+  }
+  return matched
+}
+
+export declare namespace match {
+  /** A decoded event scoped to the selected share token or vault. */
+  type Event = {
+    /** Assets paid by a vault exit; zero for share transfers. */
+    assets: bigint
+    /** Indexed block used for historical share valuation. */
+    blockNumber: number
+    /** Decoded event family. */
+    kind: 'transfer' | 'withdrawal' | 'request'
+    /** Transaction-local log position. */
+    logIndex: number
+    /** Transfer recipient or withdrawal receiver. */
+    receiver: Address
+    /** Share sender or withdrawal caller. */
+    sender: Address
+    /** Shares transferred or burned. */
+    shares: bigint
+    /** Transaction containing this event. */
+    transactionHash: z.output<typeof Schema.Hash>
+  }
+  /** Matched wallet debit and corresponding withdrawal proceeds. */
+  type Withdrawal = Pick<Event, 'assets' | 'logIndex' | 'transactionHash'>
+  /** Complete candidate transactions for one wallet and vault. */
+  type Options = Pick<read.Options, 'account' | 'vault'> & {
+    /** All share transfers and vault exits in candidate transactions. */
+    events: readonly Event[]
+  }
+}
+
+namespace schema {
+  export const Event = z.tuple([
+    z.union([z.literal('transfer'), z.literal('withdrawal'), z.literal('request')]),
+    Schema.Hash,
+    z.number().check(z.int(), z.nonnegative()),
+    Schema.Address,
+    Schema.Address,
+    Schema.DecimalString,
+    Schema.DecimalString,
+    z.number().check(z.int(), z.nonnegative()),
+  ])
+}

package/src/internal/ExecutionContext.ts

@@ -0,0 +1,31 @@
+import type { Context as hono_Context } from 'hono'
+
+/**
+ * Returns the request's `waitUntil` where the runtime provides an execution
+ * context, so background work outlives the response; `undefined` elsewhere,
+ * where callers either await the work or let it run unattended.
+ */
+export function waitUntil(c: waitUntil.Context): waitUntil.ReturnType {
+  // `c.executionCtx` throws in runtimes without one.
+  try {
+    const context = c.executionCtx
+    return context ? context.waitUntil.bind(context) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export declare namespace waitUntil {
+  /** A Hono context, or any holder of an optional Workers execution context. */
+  type Context =
+    | Pick<hono_Context, 'executionCtx'>
+    | { executionCtx?: ExecutionContext | undefined }
+
+  /** The bound `waitUntil`, or `undefined` where the runtime has none. */
+  type ReturnType = ((promise: Promise<unknown>) => void) | undefined
+}
+
+/** The subset of a Workers execution context this module relies on. */
+type ExecutionContext = {
+  waitUntil(promise: Promise<unknown>): void
+}

package/src/internal/Log.test.ts

@@ -20,6 +20,149 @@ function stable(entry: Log.Entry) {
 }
 
 describe('middleware', () => {
+  test.each([
+    ['/v1/tokenlist', '/v1/tokenlist'],
+    ['/v1/routes/transfers/:id', '/v1/routes/transfers/transfer_123'],
+  ])('attributes early errors to the matched %s route', async (route, path) => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.use('*', async (c) =>
+      Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+    )
+    api.get(route, (c) => c.json({ ok: true }))
+
+    const response = await api.request(path)
+
+    expect(response.status).toMatchInlineSnapshot(`504`)
+    expect(entries.map((entry) => entry.route)).toEqual([route])
+  })
+
+  test.each([
+    ['/rpc/relay', '/rpc/relay'],
+    ['/rpc/relay/:chainId', '/rpc/relay/4217'],
+    ['/rpc/sponsor', '/rpc/sponsor'],
+    ['/rpc/sponsor/:chainId', '/rpc/sponsor/4217'],
+  ])('attributes early errors to the ALL endpoint %s', async (route, path) => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.use('*', async (c) =>
+      Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+    )
+    api.all(route, (c) => c.json({ ok: true }))
+
+    const response = await api.request(path, { method: 'POST' })
+
+    expect(response.status).toMatchInlineSnapshot(`504`)
+    expect(entries.map((entry) => entry.route)).toEqual([route])
+  })
+
+  test.each([
+    { basePath: '/', method: 'GET' },
+    { basePath: '/', method: 'POST' },
+    { basePath: '/api', method: 'GET' },
+    { basePath: '/api', method: 'POST' },
+  ])(
+    'attributes early $method errors to wildcard endpoints mounted at $basePath',
+    async ({ basePath, method }) => {
+      const entries: Log.Entry[] = []
+      const api = app({ emit: (entry) => void entries.push(entry) })
+      api.use('*', async (c) =>
+        Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+      )
+      const auth = new Hono()
+        .use('*', (_c, next) => next())
+        .use('/v1/auth/*', (_c, next) => next())
+        .on(['GET', 'POST'], '/v1/auth/*', (c) => c.text('auth'))
+      api.route(basePath, auth)
+      const prefix = basePath === '/' ? '' : basePath
+
+      const response = await api.request(`${prefix}/v1/auth/get-session`, { method })
+
+      expect(response.status).toMatchInlineSnapshot(`504`)
+      expect(entries.map((entry) => entry.route)).toEqual([`${prefix}/v1/auth/*`])
+    },
+  )
+
+  test('prefers an earlier wildcard endpoint to an unreached concrete endpoint', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.use('*', async (c) =>
+      Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+    )
+    api.post('/v1/auth/*', (c) => c.text('auth'))
+    api.all('/v1/auth/get-session', (c) => c.text('later endpoint'))
+
+    const response = await api.request('/v1/auth/get-session', { method: 'POST' })
+
+    expect(response.status).toMatchInlineSnapshot(`504`)
+    expect(entries.map((entry) => entry.route)).toMatchInlineSnapshot(`
+      [
+        "/v1/auth/*",
+      ]
+    `)
+  })
+
+  test.each([
+    { early: false, fallback: '*', method: 'GET', route: '/v1/tokenlist' },
+    { early: true, fallback: '*', method: 'GET', route: '/v1/tokenlist' },
+    { early: false, fallback: '/v1/auth/*', method: 'POST', route: '/v1/auth/siwe/challenge' },
+    { early: true, fallback: '/v1/auth/*', method: 'POST', route: '/v1/auth/siwe/challenge' },
+  ])(
+    'preserves $route before $fallback with early=$early',
+    async ({ early, fallback, method, route }) => {
+      const entries: Log.Entry[] = []
+      const api = app({ emit: (entry) => void entries.push(entry) })
+      if (early)
+        api.use('*', async (c) =>
+          Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+        )
+      api.on(method, route, (c) => c.json({ ok: true }))
+      api.route(
+        '/',
+        new Hono().on(method, fallback, (c) => c.text('fallback')),
+      )
+
+      const response = await api.request(route, { method })
+
+      expect(response.status).toBe(early ? 504 : 200)
+      expect(entries.map((entry) => entry.route)).toEqual([route])
+    },
+  )
+
+  test('uses the responding endpoint after an earlier route calls next', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.get('/things/:id', (_c, next) => next())
+    api.get('/things/special', (c) => c.text('special'))
+    api.get('*', (c) => c.text('fallback'))
+
+    await api.request('/things/special')
+
+    expect(entries.map((entry) => entry.route)).toMatchInlineSnapshot(`
+      [
+        "/things/special",
+      ]
+    `)
+  })
+
+  test.each(['GET', 'ALL'])(
+    'preserves a %s wildcard that actually handles the request',
+    async (method) => {
+      const entries: Log.Entry[] = []
+      const api = app({ emit: (entry) => void entries.push(entry) })
+      api.get('/things/:id', (_c, next) => next())
+      api.on(method, '/things/*', (c) => c.text('fallback'))
+
+      await api.request('/things/example')
+
+      expect(entries.map((entry) => entry.route)).toMatchInlineSnapshot(`
+        [
+          "/things/*",
+        ]
+      `)
+    },
+  )
+
   test('reports recovered request errors without changing the response', async () => {
     const causes: Error[] = []
     const entries: Log.Entry[] = []
@@ -187,6 +330,73 @@ describe('middleware', () => {
     `)
   })
 
+  test('includes the presented credential before a principal resolves', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    api.use('*', async (c, next) => {
+      c.set('credential', 'api_key')
+      await next()
+    })
+    api.get('/secure', (c) =>
+      Response.error(c, { code: 'request_timeout', message: 'Request timed out', status: 504 }),
+    )
+
+    await api.request('/secure')
+
+    expect(stable(entries[0]!)).toMatchInlineSnapshot(`
+      {
+        "credential": "api_key",
+        "errorCode": "request_timeout",
+        "level": "error",
+        "method": "GET",
+        "path": "/secure",
+        "route": "/secure",
+        "status": 504,
+      }
+    `)
+  })
+
+  test('emits one canceled entry when the client disconnects first', async () => {
+    const entries: Log.Entry[] = []
+    const api = app({ emit: (entry) => void entries.push(entry) })
+    const controller = new AbortController()
+    const release = Promise.withResolvers<void>()
+    api.use('*', async (c, next) => {
+      c.set('credential', 'api_key')
+      await next()
+    })
+    api.get('/slow', async (c) => {
+      await Timing.time(c, 'auth_key', () => release.promise)
+      return c.json({ ok: true }, 200)
+    })
+
+    const response = api.request('/slow', { signal: controller.signal })
+    await Promise.resolve()
+    controller.abort()
+    const [canceled] = entries.map(stable)
+    release.resolve()
+    await response
+
+    expect(entries).toHaveLength(1)
+    expect({
+      ...canceled,
+      pendingTimings: Object.keys(canceled?.pendingTimings ?? {}),
+    }).toMatchInlineSnapshot(`
+      {
+        "credential": "api_key",
+        "errorCode": "client_canceled",
+        "level": "warn",
+        "method": "GET",
+        "path": "/slow",
+        "pendingTimings": [
+          "auth_key",
+        ],
+        "route": "/slow",
+        "status": 499,
+      }
+    `)
+  })
+
   test('includes the MPP payment reason for paid calls', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })