tapimo 0.7.2 → 0.8.0

package/src/internal/funding/Evidence.test.ts

@@ -83,7 +83,7 @@ describe('resolveRpcUrls', () => {
 })
 
 describe('createVerifier', () => {
-  test('verifies finalized Solana and Tron token transfers', async () => {
+  test('verifies finalized Solana and one-confirmation Tron token transfers', async () => {
     const tron = TestFunding.depositAddressSnapshot()
     const solana = TestFunding.transferSnapshot({
       sourceChain: {
@@ -118,7 +118,7 @@ describe('createVerifier', () => {
         return
       }
       const result = request.url?.includes('getnowblock')
-        ? { block_header: { raw_data: { number: 200 } } }
+        ? { block_header: { raw_data: { number: 150 } } }
         : request.url?.includes('gettransactioninfobyid')
           ? {
               blockNumber: 150,

package/src/internal/funding/Evidence.ts

@@ -14,6 +14,7 @@ const transferEvent = AbiEvent.from(
 )
 const transferTopic = AbiEvent.getSelector(transferEvent).slice(2)
 const catalogCacheTtlMs = 60_000
+const defaultConfirmations = 1
 
 type SolanaRpcSchema = RpcSchema.From<{
   Request: {
@@ -117,7 +118,7 @@ export declare namespace resolveRpcUrls {
   }
 }
 
-/** Creates a finalized token-transfer verifier for EVM, Solana, and Tron chains. */
+/** Creates a token-transfer verifier for EVM, Solana, and Tron chains. */
 export function createVerifier(options: createVerifier.Options): Reconciliation.VerifyTransfers {
   const fetch = options.fetch ?? globalThis.fetch
   // Delay this shared read until reconciliation releases its claim transaction.
@@ -156,15 +157,13 @@ export function createVerifier(options: createVerifier.Options): Reconciliation.
     if (!urls || urls.length === 0) throw new ChainConfigurationError(parameters.chain.id)
     if (parameters.chain.kind === 'evm')
       return verifyEvm(parameters, {
-        confirmations:
-          options.confirmations?.[parameters.chain.id] ?? options.defaultEvmConfirmations ?? 12,
+        confirmations: options.confirmations?.[parameters.chain.id] ?? defaultConfirmations,
         fetch,
         urls,
       })
     if (parameters.chain.kind === 'solana') return verifySolana(parameters, { fetch, urls })
     return verifyTron(parameters, {
-      confirmations:
-        options.confirmations?.[parameters.chain.id] ?? options.defaultTronConfirmations ?? 20,
+      confirmations: options.confirmations?.[parameters.chain.id] ?? defaultConfirmations,
       fetch,
       urls,
     })
@@ -180,10 +179,6 @@ export declare namespace createVerifier {
     db: Db.Source
     /** Tempo chain that receives a shared RPC URL override. */
     defaultChainId?: Viem.ChainId | undefined
-    /** Default confirmation requirement for EVM chains. */
-    defaultEvmConfirmations?: number | undefined
-    /** Default confirmation requirement for Tron. */
-    defaultTronConfirmations?: number | undefined
     /** Fetch implementation override for tests. */
     fetch?: typeof globalThis.fetch | undefined
     /** Shared or per-EVM-chain RPC URL environment value. */

package/src/internal/funding/Provider.ts

@@ -249,6 +249,7 @@ export namespace schema {
     createdAt: z.iso.datetime(),
     destinationTransactionHashes: z.array(z.string()),
     id: z.string().check(z.minLength(1)),
+    providerState: z.optional(z.record(z.string(), z.unknown())),
     sourceTransactionHashes: z.array(z.string()),
     status: z.string().check(z.minLength(1)),
     updatedAt: z.iso.datetime(),
@@ -478,6 +479,68 @@ export declare namespace listDepositAddressRequests {
   type ReturnType = z.output<typeof schema.DepositAddressRequestsResult>
 }
 
+/** Contract of the provider `observeDepositAddressRequest` method. */
+export declare namespace observeDepositAddressRequest {
+  /** Verified source transfer used to correlate provider delivery. */
+  type Source = {
+    /** Token quantity in base units. */
+    amount: string
+    /** Verified source transaction reference. */
+    transactionHash: string
+  }
+
+  /** Input passed to a provider observing one pending reusable-address request. */
+  type Parameters = {
+    /** Provider-owned reusable deposit address. */
+    address: string
+    /** Chain that receives provider delivery. */
+    destinationChain: ChainRef
+    /** Token delivered by the provider. */
+    destinationToken: TokenRef
+    /** Bounded private provider correlation from an earlier observation. */
+    providerState?: Record<string, unknown> | undefined
+    /** Final beneficiary on the destination chain. */
+    recipient: string
+    /** Source-chain account credited by the provider deposit. */
+    refundAddress: string
+    /** Pending provider request being accelerated. */
+    request: listDepositAddressRequests.ReturnType['requests'][number]
+    /** One verified source transfer attributed to the request. */
+    source: Source
+    /** Chain containing the source transfer. */
+    sourceChain: ChainRef
+    /** Token received by the reusable address. */
+    sourceToken: TokenRef
+  }
+
+  /** Private provider evidence shared by pending and verified observations. */
+  type Evidence = {
+    /** Bounded private provider correlation retained for reconciliation. */
+    providerState?: Record<string, unknown> | undefined
+    /** Verified provider-leg transaction references. */
+    providerTransactionHashes?: readonly string[] | undefined
+  }
+
+  /** Bounded provider delivery observation. */
+  type ReturnType = Evidence &
+    (
+      | {
+          /** No matching provider delivery has reached the destination yet. */
+          type: 'pending'
+        }
+      | {
+          /** This provider or route cannot produce authenticated delivery observations. */
+          type: 'unsupported'
+        }
+      | {
+          /** Verified destination transaction references. */
+          destinationTransactionHashes: readonly string[]
+          /** Authenticated provider delivery was observed onchain. */
+          type: 'verified'
+        }
+    )
+}
+
 /** Optional webhook capability implemented by a complete funding integration. */
 export type Webhook = {
   /** Authenticates, resolves, and enqueues one provider status event. */
@@ -502,12 +565,46 @@ export declare namespace Webhook {
     type Dispatchable = {
       /** Stored funding deposit address id. */
       addressId: string
+      /** Bounded follow-up state for work awaiting provider or settlement confirmation. */
+      followUp?: FollowUp | undefined
       /** Reconciliation lease fencing token, when a scheduled poll already claimed the address. */
       pollLeaseVersion?: number | undefined
       /** Optional provider request id that triggered reconciliation. */
       requestId?: string | undefined
+      /** Mechanism that requested reconciliation. */
+      trigger: 'chain' | 'manual' | 'poll' | 'webhook'
       /** Reconciliation queue message discriminator. */
       type: 'funding:deposit-address:reconcile'
+      /** Authenticated provider webhook timing carried into reconciliation. */
+      webhookTiming?: WebhookTiming | undefined
+    }
+
+    /** Bounded follow-up state carried between delayed reconciliation messages. */
+    type FollowUp = {
+      /** Zero-based attempt in the current follow-up schedule. */
+      attempt: number
+      /** Work that still awaits confirmation. */
+      kind: 'delivery' | 'provider' | 'settlement'
+    }
+
+    /** Authenticated provider webhook timing used for latency measurement. */
+    type WebhookTiming = {
+      /** When Tempo sent the reconciliation message to its queue. */
+      enqueuedAt: string
+      /** Bounded provider status carried by the webhook. */
+      providerStatus: string
+      /** When the provider last changed the request status. */
+      providerUpdatedAt: string
+      /** When Tempo started processing the webhook request. */
+      receivedAt: string
+      /** When the provider sent the signed webhook. */
+      sentAt: string
+    }
+
+    /** Durable reconciliation message, including messages queued before trigger attribution. */
+    type Queued = Omit<Dispatchable, 'trigger'> & {
+      /** Mechanism that requested reconciliation, when written by a trigger-aware producer. */
+      trigger?: Dispatchable['trigger'] | undefined
     }
 
     /** Safe disposition of one authenticated funding provider webhook. */
@@ -526,8 +623,14 @@ export declare namespace Webhook {
     type ReturnType = {
       /** Reusable provider address, when the provider attributed one. */
       address?: string | undefined
+      /** Bounded provider status carried by the webhook. */
+      providerStatus?: string | undefined
+      /** When the provider last changed the request status. */
+      providerUpdatedAt?: string | undefined
       /** Provider request id, when included in the event. */
       requestId?: string | undefined
+      /** When the provider sent the signed webhook. */
+      sentAt?: string | undefined
     }
   }
 }
@@ -546,6 +649,11 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
     input: listDepositAddressRequests.Parameters,
     signal: AbortSignal,
   ): Promise<listDepositAddressRequests.ReturnType>
+  /** Observes authenticated delivery for a pending reusable-address request, when supported. */
+  observeDepositAddressRequest?(
+    input: observeDepositAddressRequest.Parameters,
+    signal: AbortSignal,
+  ): Promise<observeDepositAddressRequest.ReturnType>
   /** Prepares an executable funding transfer, when the provider supports it. */
   prepareTransfer?(
     input: prepareTransfer.Parameters,
@@ -595,6 +703,13 @@ export function canListDepositAddressRequests(provider: Provider): provider is P
   return typeof provider.listDepositAddressRequests === 'function'
 }
 
+/** Narrows a funding provider to one that observes reusable-address delivery onchain. */
+export function canObserveDepositAddressRequest(provider: Provider): provider is Provider & {
+  observeDepositAddressRequest: NonNullable<Provider['observeDepositAddressRequest']>
+} {
+  return typeof provider.observeDepositAddressRequest === 'function'
+}
+
 /** Narrows a funding provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider: Provider): provider is Provider & {
   webhook: Webhook

package/src/internal/funding/Reconciliation.local.test.ts

@@ -210,9 +210,11 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
       {
         "createdAt": Any<String>,
         "depositAddressId": Any<String>,
+        "detectionTrigger": "poll",
         "environment": "production",
         "id": Any<String>,
         "orgId": "org_local_subsidy",
+        "pollObservedAt": null,
         "projectId": null,
         "providerOutputAmount": {
           "baseUnits": "950000",
@@ -318,6 +320,7 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
         "tempoGasPaid": null,
         "updatedAt": Any<String>,
         "version": 3,
+        "webhookReceivedAt": null,
       }
     `,
     )
@@ -366,9 +369,11 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
         "completed": {
           "createdAt": Any<String>,
           "depositAddressId": Any<String>,
+          "detectionTrigger": "poll",
           "environment": "production",
           "id": Any<String>,
           "orgId": "org_local_subsidy",
+          "pollObservedAt": null,
           "projectId": null,
           "providerOutputAmount": {
             "baseUnits": "950000",
@@ -480,6 +485,7 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
           "tempoGasPaid": Any<String>,
           "updatedAt": Any<String>,
           "version": 7,
+          "webhookReceivedAt": null,
         },
         "first": {
           "created": 1,
@@ -489,6 +495,7 @@ describe.skipIf(runtime.mode !== 'localnet')('reconcileRequest', () => {
         "memoMatchesDeposit": true,
         "second": {
           "created": 0,
+          "followUp": "settlement",
           "terminal": false,
           "updated": 1,
         },