tapimo 0.7.0 → 0.7.2

package/src/internal/Webhooks.ts

@@ -5,6 +5,7 @@ import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
+import * as Cursor from './Cursor.js'
 import * as Id from './Id.js'
 import * as MetricSink from './MetricSink.js'
 import * as WebhookDestination from './WebhookDestination.js'
@@ -170,9 +171,18 @@ export async function createSubscription(
   options: createSubscription.Options = {},
 ): Promise<Subscription> {
   WebhookDestination.assertDestination(input.destination)
+  if (
+    options.startBlockNumber !== undefined &&
+    (!Number.isSafeInteger(options.startBlockNumber) || options.startBlockNumber < 0)
+  )
+    throw new RangeError('startBlockNumber must be a non-negative safe integer.')
 
   const now = (options.now ?? (() => new Date()))()
   const iso = now.toISOString()
+  // A one-field checkpoint records the live creation head without claiming it
+  // was scanned. The poller expands it using its confirmation depth.
+  const pollerCursor =
+    options.startBlockNumber === undefined ? undefined : Cursor.encode([options.startBlockNumber])
 
   const subscription: Subscription = {
     chainId: input.chainId,
@@ -196,9 +206,15 @@ export async function createSubscription(
     const inserted = await WebhookSubscriptions.insertWithinLimit(db, subscription, {
       maxPerOwner: options.maxPerOwner,
       now: iso,
+      ...(pollerCursor === undefined ? {} : { pollerCursor }),
     })
     if (!inserted) throw new LimitExceededError(options.maxPerOwner)
-  } else await WebhookSubscriptions.insert(db, subscription)
+  } else
+    await WebhookSubscriptions.insert(
+      db,
+      subscription,
+      pollerCursor === undefined ? {} : { pollerCursor },
+    )
   return subscription
 }
 
@@ -209,6 +225,8 @@ export declare namespace createSubscription {
     maxPerOwner?: number | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
+    /** Chain head observed immediately before the subscription becomes visible. */
+    startBlockNumber?: number | undefined
   }
 }
 
@@ -316,6 +334,19 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
   return WebhookSubscriptions.getCursor(db, subscriptionId)
 }
 
+/** Writes a cursor only when its stored value matches the expected cursor. */
+export async function compareAndSetCursor(
+  db: Db.Db,
+  options: compareAndSetCursor.Options,
+): Promise<boolean> {
+  return WebhookSubscriptions.compareAndSetCursor(db, options)
+}
+
+export declare namespace compareAndSetCursor {
+  /** Options for {@link compareAndSetCursor}. */
+  type Options = WebhookSubscriptions.compareAndSetCursor.Options
+}
+
 /** Writes a subscription's keyset cursor. */
 export async function setCursor(db: Db.Db, subscriptionId: string, cursor: string): Promise<void> {
   await WebhookSubscriptions.setCursor(db, subscriptionId, cursor)
@@ -790,18 +821,11 @@ export declare namespace ping {
 }
 
 function generateId(now: Date): string {
-  // Zero-pad the epoch-ms so ids sort chronologically by string comparison
-  // (mirroring delivery ids), letting listSubscriptions page newest-first; 15
-  // digits leaves headroom well past the year 5138.
-  const timestamp = now.getTime().toString().padStart(15, '0')
-  return `wh_${timestamp}_${Id.random()}`
+  return Id.generateSortable('wh', now)
 }
 
 function generateDeliveryId(now: Date): string {
-  // Zero-pad the epoch-ms so ids sort chronologically by string comparison; 15
-  // digits leaves headroom well past the year 5138.
-  const timestamp = now.getTime().toString().padStart(15, '0')
-  return `whd_${timestamp}_${Id.random()}`
+  return Id.generateSortable('whd', now)
 }
 
 function generateSecret(): string {

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

@@ -0,0 +1,216 @@
+import * as core_Provider from '../Provider.js'
+import * as Provider from './Provider.js'
+
+describe('from', () => {
+  test('preserves provider identity and adds the exchange category', () => {
+    const provider = Provider.from({
+      id: 'example',
+      name: 'Example',
+      async quote() {
+        throw new Provider.RouteUnavailableError()
+      },
+    })
+
+    expect(provider).toMatchObject({
+      id: 'example',
+      name: 'Example',
+      type: 'exchange',
+    })
+  })
+
+  test('rejects provider ids that are not normalized', () => {
+    expect(() =>
+      Provider.from({
+        id: ' Example ',
+        name: 'Example',
+        async quote() {
+          throw new Provider.RouteUnavailableError()
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[ExchangeProvider.ProviderConfigurationError: Provider ids must be lowercase and trimmed.]`,
+    )
+  })
+})
+
+describe('is', () => {
+  test('accepts only exchange providers with quote capability', () => {
+    const exchange = Provider.from({
+      id: 'exchange',
+      name: 'Exchange',
+      async quote() {
+        throw new Provider.RouteUnavailableError()
+      },
+    })
+    const incomplete = core_Provider.from({
+      id: 'incomplete',
+      name: 'Incomplete',
+      type: 'exchange',
+    })
+    const funding = core_Provider.from({ id: 'funding', name: 'Funding', type: 'funding' })
+
+    expect([exchange, incomplete, funding].map(Provider.is)).toEqual([true, false, false])
+  })
+})
+
+describe('failure', () => {
+  const provider = Provider.from({
+    id: 'example',
+    name: 'Example',
+    async quote() {
+      throw new Provider.RouteUnavailableError()
+    },
+  })
+
+  test('reports the upstream operation and status', () => {
+    expect(
+      Provider.failure(
+        new Provider.ProviderResponseError({ operation: 'check_approval', status: 429 }),
+        { chainId: 4217, operation: 'quote', provider },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "rate_limit",
+        "id": "example",
+        "operation": "check_approval",
+        "status": 429,
+      }
+    `)
+  })
+
+  test('reports payload failures at the enclosing operation', () => {
+    expect(
+      Provider.failure(new Provider.ProviderPayloadError(), {
+        chainId: 4217,
+        operation: 'finalize',
+        provider,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "payload",
+        "id": "example",
+        "operation": "finalize",
+      }
+    `)
+  })
+
+  test('reports bounded payload validation codes', () => {
+    expect(
+      Provider.failure(new Provider.ProviderPayloadError({ code: 'quote.response.permitData' }), {
+        chainId: 4217,
+        operation: 'quote',
+        provider,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "code": "quote.response.permitData",
+        "failure": "payload",
+        "id": "example",
+        "operation": "quote",
+      }
+    `)
+  })
+
+  test('reports the upstream operation for network failures', () => {
+    expect(
+      Provider.failure(
+        new Provider.ProviderNetworkError({
+          cause: new TypeError('secret network detail'),
+          operation: 'check_approval',
+        }),
+        { chainId: 4217, operation: 'quote', provider },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "failure": "network",
+        "id": "example",
+        "operation": "check_approval",
+      }
+    `)
+  })
+
+  test('ignores failures outside the provider boundary', () => {
+    expect(
+      Provider.failure(new Error('metadata lookup failed'), {
+        chainId: 4217,
+        operation: 'quote',
+        provider,
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('validateExecution', () => {
+  const account = '0x1111111111111111111111111111111111111111'
+  const destinationToken = '0x20c0000000000000000000000000000000000002'
+  const sourceToken = '0x20c0000000000000000000000000000000000001'
+  const router = '0x2222222222222222222222222222222222222222'
+
+  test('accepts transfers within exact-source bounds', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          minimumDestinationAmount: '99',
+          mode: 'exactSource',
+          sourceAmount: '50',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 50n, from: account, to: router, token: sourceToken },
+          { amount: 99n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).not.toThrow()
+  })
+
+  test('rejects a different outgoing token', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          minimumDestinationAmount: '99',
+          mode: 'exactSource',
+          sourceAmount: '50',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 1n, from: account, to: router, token: destinationToken },
+          { amount: 50n, from: account, to: router, token: sourceToken },
+          { amount: 100n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+
+  test('rejects execution outside exact-destination bounds', () => {
+    expect(() =>
+      Provider.validateExecution({
+        account,
+        execution: {
+          destinationAmount: '100',
+          destinationToken,
+          gasUnits: '1',
+          maximumSourceAmount: '50',
+          mode: 'exactDestination',
+          sourceAmount: '49',
+          sourceToken,
+        },
+        transfers: [
+          { amount: 51n, from: account, to: router, token: sourceToken },
+          { amount: 100n, from: router, to: account, token: destinationToken },
+        ],
+      }),
+    ).toThrow(Provider.ProviderPayloadError)
+  })
+})

package/src/internal/exchange/Provider.ts

@@ -0,0 +1,326 @@
+import type { Hex } from 'ox'
+
+import * as core_Provider from '../Provider.js'
+import type * as Log from '../Log.js'
+
+/** Exchange quote provider called after the native DEX cannot route a swap. */
+export type Provider<id extends string = string> = core_Provider.Provider<id, 'exchange'> & {
+  /** Converts a signed continuation into final executable calls. */
+  finalizeQuote?(
+    this: void,
+    input: FinalizeQuoteInput,
+    signal: AbortSignal,
+  ): Promise<FinalizeQuoteResult>
+  /** Returns the approvals, signature, or executable calls needed to continue. */
+  quote(this: void, input: QuoteInput, signal: AbortSignal): Promise<QuoteResult>
+}
+
+/** Provider-neutral unsigned transaction call. */
+export type Call = {
+  /** ABI-encoded call data. */
+  data: Hex.Hex
+  /** Contract receiving the call. */
+  to: `0x${string}`
+  /** Native token value as a JSON-RPC quantity. */
+  value: Hex.Hex
+}
+
+/** Input used to finish a provider quote after signing. */
+export type FinalizeQuoteInput = {
+  /** Wallet signing and executing the swap. */
+  account: `0x${string}`
+  /** Tempo chain id. */
+  chainId: number
+  /** Opaque provider state returned by `quote`. */
+  continuation: string
+  /** EIP-712 signature requested by the quote result. */
+  signature: Hex.Hex
+}
+
+/** Final executable calls returned after a signature. */
+export type FinalizeQuoteResult = {
+  /** Calls to execute in order. */
+  calls: readonly Call[]
+  /** Quote constraints that the final calls must satisfy. */
+  execution: Execution
+}
+
+/** Constraints used to validate executable provider calls. */
+export type Execution = QuoteAmounts & {
+  /** Token received by the swap. */
+  destinationToken: `0x${string}`
+  /** Side whose requested amount remains exact. */
+  mode: 'exactDestination' | 'exactSource'
+  /** Token spent by the swap. */
+  sourceToken: `0x${string}`
+}
+
+/** Token movement observed while simulating provider calls. */
+export type Transfer = {
+  /** Amount moved in base units. */
+  amount: bigint
+  /** Account sending the tokens. */
+  from: `0x${string}`
+  /** Account receiving the tokens. */
+  to: `0x${string}`
+  /** Token contract that emitted the transfer. */
+  token: `0x${string}`
+}
+
+/** Provider-neutral quote input. */
+export type QuoteInput = {
+  /** Wallet receiving and executing the swap. */
+  account: `0x${string}`
+  /** Exact source or destination amount in base units. */
+  amount: string
+  /** Tempo chain id. */
+  chainId: number
+  /** Token received by the swap. */
+  destinationToken: `0x${string}`
+  /** Side whose requested amount remains exact. */
+  mode: 'exactDestination' | 'exactSource'
+  /** Maximum execution slippage in basis points. */
+  slippageBps: number
+  /** Token spent by the swap. */
+  sourceToken: `0x${string}`
+}
+
+/** Quote with the approvals, signature, or transaction needed for its next step. */
+export type QuoteResult =
+  | (QuoteAmounts & {
+      /** Calls that must confirm before requesting a fresh quote. */
+      approval: { calls: readonly Call[] }
+      /** Onchain approval is required before this swap can be quoted for execution. */
+      status: 'approvalRequired'
+    })
+  | (QuoteAmounts & {
+      /** Quote is ready for execution. */
+      status: 'ready'
+      /** Ordered calls required to execute the quote. */
+      transaction: { calls: readonly Call[] }
+    })
+  | (QuoteAmounts & {
+      /** Opaque provider state passed to `finalizeQuote`. */
+      continuation: string
+      /** Quote needs a wallet signature before final calldata can be built. */
+      status: 'signatureRequired'
+      /** EIP-712 payload the wallet must sign. */
+      typedData: TypedData
+    })
+
+/** Defines an exchange provider while preserving its concrete identity. */
+export function from<const id extends string>(options: from.Options<id>): Provider<id> {
+  if (options.id !== options.id.trim().toLowerCase() || options.id.length === 0)
+    throw new ProviderConfigurationError('Provider ids must be lowercase and trimmed.')
+  return core_Provider.from({ ...options, type: 'exchange' })
+}
+
+export declare namespace from {
+  /** Exchange provider definition. */
+  type Options<id extends string> = Omit<Provider<id>, 'type'>
+}
+
+/** Returns whether a registered provider implements exchange quotes. */
+export function is(provider: core_Provider.Provider): provider is Provider {
+  return provider.type === 'exchange' && 'quote' in provider && typeof provider.quote === 'function'
+}
+
+/** Returns bounded exchange-provider failure details for structured request logs. */
+export function failure(cause: unknown, options: failure.Options): Log.ProviderFailure | undefined {
+  const { chainId, operation, provider } = options
+  if (cause instanceof ProviderResponseError)
+    return {
+      chainId,
+      failure: cause.status === 429 ? 'rate_limit' : 'http',
+      id: provider.id,
+      operation: cause.operation,
+      status: cause.status,
+    }
+  if (cause instanceof ProviderNetworkError)
+    return { chainId, failure: 'network', id: provider.id, operation: cause.operation }
+  if (cause instanceof ProviderPayloadError)
+    return {
+      chainId,
+      ...(cause.code ? { code: cause.code } : {}),
+      failure: 'payload',
+      id: provider.id,
+      operation,
+    }
+  return undefined
+}
+
+export declare namespace failure {
+  /** Exchange-provider context retained when a quote operation fails. */
+  type Options = {
+    /** Chain selected by the quote request. */
+    chainId: number
+    /** Provider operation used when the error has no narrower operation. */
+    operation: string
+    /** Exchange provider that handled the request. */
+    provider: Provider
+  }
+}
+
+/** Validates simulated token movements against an executable quote. */
+export function validateExecution(options: validateExecution.Options): void {
+  const account = options.account.toLowerCase()
+  const destinationToken = options.execution.destinationToken.toLowerCase()
+  const sourceToken = options.execution.sourceToken.toLowerCase()
+  let destinationReceived = 0n
+  let sourceIncoming = 0n
+  let sourceOutgoing = 0n
+
+  for (const transfer of options.transfers) {
+    const token = transfer.token.toLowerCase()
+    if (transfer.from.toLowerCase() === account) {
+      if (token !== sourceToken) throw new ProviderPayloadError()
+      sourceOutgoing += transfer.amount
+    }
+    if (transfer.to.toLowerCase() !== account) continue
+    if (token === sourceToken) sourceIncoming += transfer.amount
+    if (token === destinationToken) destinationReceived += transfer.amount
+  }
+
+  const sourceSpent = sourceOutgoing - sourceIncoming
+  if (sourceSpent <= 0n) throw new ProviderPayloadError()
+  if (options.execution.mode === 'exactSource') {
+    if (
+      sourceSpent !== BigInt(options.execution.sourceAmount) ||
+      options.execution.minimumDestinationAmount === undefined ||
+      destinationReceived < BigInt(options.execution.minimumDestinationAmount)
+    )
+      throw new ProviderPayloadError()
+    return
+  }
+
+  if (
+    options.execution.maximumSourceAmount === undefined ||
+    sourceSpent > BigInt(options.execution.maximumSourceAmount) ||
+    destinationReceived < BigInt(options.execution.destinationAmount)
+  )
+    throw new ProviderPayloadError()
+}
+
+export declare namespace validateExecution {
+  /** Simulated transfers and quote constraints to validate. */
+  type Options = {
+    /** Wallet executing the provider calls. */
+    account: `0x${string}`
+    /** Quote constraints bound to the executable calls. */
+    execution: Execution
+    /** Token transfers emitted by the simulated calls. */
+    transfers: readonly Transfer[]
+  }
+}
+
+/** Amount bounds returned by an exchange provider. */
+export type QuoteAmounts = {
+  /** Expected destination amount in base units. */
+  destinationAmount: string
+  /** Estimated execution gas units. */
+  gasUnits: string
+  /** Maximum source amount for an exact-destination quote. */
+  maximumSourceAmount?: string | undefined
+  /** Minimum destination amount for an exact-source quote. */
+  minimumDestinationAmount?: string | undefined
+  /** Expected source amount in base units. */
+  sourceAmount: string
+}
+
+/** Provider-neutral EIP-712 payload accepted by Privy and common wallet clients. */
+export type TypedData = {
+  /** EIP-712 signing domain. */
+  domain: Record<string, unknown>
+  /** EIP-712 message values. */
+  message: Record<string, unknown>
+  /** Root EIP-712 type. */
+  primaryType: string
+  /** EIP-712 type definitions. */
+  types: Record<string, readonly { name: string; type: string }[]>
+}
+
+/** Raised when a provider has no executable route for the requested swap. */
+export class RouteUnavailableError extends Error {
+  override name = 'ExchangeProvider.RouteUnavailableError'
+}
+
+/** Raised when a continuation cannot be decoded or validated. */
+export class ProviderContinuationError extends Error {
+  override name = 'ExchangeProvider.ProviderContinuationError'
+}
+
+/** Raised when required provider configuration is invalid. */
+export class ProviderConfigurationError extends Error {
+  override name = 'ExchangeProvider.ProviderConfigurationError'
+}
+
+/** Raised when an upstream provider request fails before receiving a response. */
+export class ProviderNetworkError extends Error {
+  override name = 'ExchangeProvider.ProviderNetworkError'
+
+  /** Upstream operation that failed. */
+  operation: string
+
+  constructor(options: ProviderNetworkError.Options) {
+    super(`Provider ${options.operation} request failed`, { cause: options.cause })
+    this.operation = options.operation
+  }
+}
+
+export declare namespace ProviderNetworkError {
+  /** Safe request details retained for operational reporting. */
+  type Options = {
+    /** Original network error. */
+    cause: TypeError
+    /** Stable upstream operation identifier. */
+    operation: string
+  }
+}
+
+/** Raised when an upstream provider returns an invalid payload. */
+export class ProviderPayloadError extends Error {
+  override name = 'ExchangeProvider.ProviderPayloadError'
+
+  /** Stable validation code safe for operational reporting. */
+  code?: string | undefined
+
+  constructor(options: ProviderPayloadError.Options = {}) {
+    super(options.code ? `Provider payload failed ${options.code}` : undefined)
+    this.code = options.code
+  }
+}
+
+export declare namespace ProviderPayloadError {
+  /** Bounded invalid-payload details. */
+  type Options = {
+    /** Stable validation code safe for operational reporting. */
+    code?: string | undefined
+  }
+}
+
+/** Raised when an upstream provider request fails. */
+export class ProviderResponseError extends Error {
+  override name = 'ExchangeProvider.ProviderResponseError'
+
+  /** Upstream operation that returned the response. */
+  operation: string
+
+  /** Upstream HTTP status. */
+  status: number
+
+  constructor(options: ProviderResponseError.Options) {
+    super(`Provider ${options.operation} request failed with status ${options.status}`)
+    this.operation = options.operation
+    this.status = options.status
+  }
+}
+
+export declare namespace ProviderResponseError {
+  /** Safe upstream response details retained for operational reporting. */
+  type Options = {
+    /** Stable upstream operation identifier. */
+    operation: string
+    /** Upstream HTTP status. */
+    status: number
+  }
+}

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

@@ -0,0 +1,6 @@
+import * as Exchange from './index.js'
+
+test('exports the exchange provider contract', () => {
+  expect(Exchange.Provider.from).toBeTypeOf('function')
+  expect(Exchange.Provider.is).toBeTypeOf('function')
+})

package/src/internal/exchange/index.ts

@@ -0,0 +1 @@
+export * as Provider from './Provider.js'