tapimo 0.15.1 → 0.18.0

package/src/internal/routes/Reconciliation.ts

@@ -13,6 +13,7 @@ import * as Deposit from './Deposit.js'
 import * as DepositWebhook from './DepositWebhook.js'
 import * as Observability from './Observability.js'
 import * as Provider from './Provider.js'
+import * as Policy from './Policy.js'
 import * as Subsidy from './Subsidy.js'
 
 const defaultBatchSize = 25
@@ -973,35 +974,57 @@ export async function reconcileRequest(
           : record.providerTransferIndex === providerTransferIndex,
       )
       if (!deposit) {
-        deposit = await Deposit.create(db, {
-          detectionTrigger: trigger,
-          now: new Date(options.request.createdAt),
-          ...(observation?.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
-          providerRequestId: options.request.id,
-          providerTransferIndex,
-          snapshot: {
-            depositAddressId: options.address.id,
-            ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
-            destinationChain: options.address.snapshot.destinationChain,
-            destinationToken: options.address.snapshot.destinationToken,
-            provider: options.address.snapshot.provider,
-            recipient: options.address.recipient,
-            refundAddress: options.address.refundAddress,
-            ...(transfer.sender ? { sender: transfer.sender } : {}),
-            sourceAmount,
-            sourceChain: options.address.snapshot.sourceChain,
-            sourceToken: options.address.snapshot.sourceToken,
-            sourceTransactionHashes: [transfer.transactionHash],
+        const result = await RoutesDeposits.withSourceTransaction(db, {
+          depositAddressId: options.address.id,
+          fn: async (tx): Promise<RoutesDeposits.insertOrGetSource.Result> => {
+            const records = await RoutesDeposits.listBySourceTransaction(tx, {
+              depositAddressId: options.address.id,
+              sourceTransactionHash: transfer.transactionHash,
+            })
+            const existing = records.find(
+              (record) => record.sourceTransferIndex === transfer.transferIndex,
+            )
+            if (existing) return { record: existing, type: 'existing' }
+            return {
+              record: await Deposit.create(tx, {
+                detectionTrigger: trigger,
+                now: new Date(options.request.createdAt),
+                ...(observation?.pollObservedAt
+                  ? { pollObservedAt: observation.pollObservedAt }
+                  : {}),
+                providerRequestId: options.request.id,
+                providerTransferIndex,
+                snapshot: {
+                  depositAddressId: options.address.id,
+                  ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
+                  destinationChain: options.address.snapshot.destinationChain,
+                  destinationToken: options.address.snapshot.destinationToken,
+                  provider: options.address.snapshot.provider,
+                  recipient: options.address.recipient,
+                  refundAddress: options.address.refundAddress,
+                  ...(transfer.sender ? { sender: transfer.sender } : {}),
+                  sourceAmount,
+                  sourceChain: options.address.snapshot.sourceChain,
+                  sourceToken: options.address.snapshot.sourceToken,
+                  sourceTransactionHashes: [transfer.transactionHash],
+                },
+                sourceTransactionHash: transfer.transactionHash,
+                sourceTransferIndex: transfer.transferIndex,
+                ...(observation?.webhookReceivedAt
+                  ? { webhookReceivedAt: observation.webhookReceivedAt }
+                  : {}),
+              }),
+              type: 'created',
+            }
           },
           sourceTransactionHash: transfer.transactionHash,
-          sourceTransferIndex: transfer.transferIndex,
-          ...(observation?.webhookReceivedAt
-            ? { webhookReceivedAt: observation.webhookReceivedAt }
-            : {}),
         })
-        Observability.recordDeposit(options.metrics, { record: deposit })
+        deposit = result.record
+        if (result.type === 'created') {
+          Observability.recordDeposit(options.metrics, { record: deposit })
+          created += 1
+        }
         source.deposits.push(deposit)
-        created += 1
       }
       if (
         !Deposit.isTerminal(deposit.status) ||
@@ -1036,6 +1059,16 @@ export async function reconcileRequest(
       verified.push({ deposit, required, source: transfer, sourceAmount: BigInt(transfer.amount) })
     }
   }
+  // Chain observation can add deposits after the initial timestamp update but before source verification completes.
+  if (observation)
+    await RoutesDeposits.recordRequestObservation(db, {
+      depositAddressId: observation.depositAddressId,
+      ...(observation.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
+      providerRequestId: observation.providerRequestId,
+      ...(observation.webhookReceivedAt
+        ? { webhookReceivedAt: observation.webhookReceivedAt }
+        : {}),
+    })
   if (verified.length === 0) return { created, terminal: false, updated: updatedIds.size }
   if (!sourceEvidenceComplete) {
     return { created, terminal: false, updated: updatedIds.size }
@@ -1277,6 +1310,37 @@ async function reconcileProviderRecovery(db: Db.Db, options: ReconcileDeliveryOp
   }
 }
 
+function providerSubsidyUpdate(options: {
+  address: RoutesDepositAddresses.Record
+  deposit: RoutesDeposits.Record
+  subsidy: Provider.Subsidy
+}): Pick<Deposit.transition.Options, 'providerState' | 'providerSubsidy'> {
+  const { address, deposit, subsidy } = options
+  if (deposit.providerSubsidy || deposit.providerState?.['unbilledProviderSubsidy']) return {}
+  const commitment = Policy.commitment(address.providerState)
+  const destinationToken = address.snapshot.destinationToken
+  const settled =
+    deposit.settlementTransactionHash && deposit.subsidyAmount
+      ? scaleBaseUnits(
+          BigInt(deposit.subsidyAmount.baseUnits),
+          deposit.subsidyAmount.decimals,
+          destinationToken.decimals,
+        )
+      : 0n
+  const provider = scaleBaseUnits(
+    BigInt(subsidy.amount.baseUnits),
+    subsidy.amount.decimals,
+    destinationToken.decimals,
+  )
+  if (
+    !commitment ||
+    Subsidy.supportsGap(commitment, { amount: settled + provider, destinationToken })
+  )
+    return { providerSubsidy: subsidy }
+  // Provider expense is already irreversible. Preserve evidence without billing beyond the pinned cap.
+  return { providerState: { unbilledProviderSubsidy: subsidy } }
+}
+
 async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
   let followUp: reconcileRequest.ReturnType['followUp']
   let terminal = true
@@ -1287,7 +1351,10 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
   if (
     allTerminal &&
     (!options.address.snapshot.subsidize ||
-      options.verified.some((entry) => entry.deposit.providerSubsidy))
+      options.verified.some(
+        (entry) =>
+          entry.deposit.providerSubsidy || entry.deposit.providerState?.['unbilledProviderSubsidy'],
+      ))
   )
     return { terminal, updatedIds }
   const deliveryObservation = await observeProviderDelivery(options)
@@ -1310,8 +1377,10 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
     ),
   )
   const destinationTransfers = destinationEvidence.flat()
+  const providerSucceeded =
+    options.request?.status === 'success' || deliveryObservation?.type === 'verified'
   const providerEvidenceComplete =
-    (options.request?.status === 'success' || deliveryObservation?.type === 'verified') &&
+    providerSucceeded &&
     destinationEvidence.length > 0 &&
     destinationEvidence.every((transfers) => transfers.length > 0)
   const providerOutput = destinationTransfers.reduce(
@@ -1332,7 +1401,13 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
     const deposit = options.verified.find(
       (entry) => entry.deposit.id === providerSubsidyDepositId,
     )?.deposit
-    if (!deposit || deposit.providerSubsidy) return { terminal, updatedIds }
+    if (!deposit || deposit.providerSubsidy || deposit.providerState?.['unbilledProviderSubsidy'])
+      return { terminal, updatedIds }
+    const update = providerSubsidyUpdate({
+      address: options.address,
+      deposit,
+      subsidy: providerSubsidy,
+    })
     const result = await transitionDeposit(db, {
       current: deposit,
       metrics: options.metrics,
@@ -1340,12 +1415,27 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
       transition: {
         expectedVersion: deposit.version,
         id: deposit.id,
-        providerSubsidy,
+        ...update,
+        ...(update.providerState
+          ? { providerState: { ...deposit.providerState, ...update.providerState } }
+          : {}),
       },
     })
-    if (result.type === 'applied') updatedIds.add(deposit.id)
+    if (result.type === 'applied') {
+      updatedIds.add(deposit.id)
+      if (update.providerState)
+        options.metrics?.count('routes_deposit_subsidy_count', 1, {
+          outcome: 'provider_subsidy_unbilled',
+          provider: options.address.providerId,
+        })
+    }
     return {
-      terminal: result.type !== 'stale' || Boolean(result.current.providerSubsidy),
+      terminal:
+        result.type !== 'stale' ||
+        Boolean(
+          result.current.providerSubsidy ||
+          result.current.providerState?.['unbilledProviderSubsidy'],
+        ),
       updatedIds,
     }
   }
@@ -1366,13 +1456,31 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
       const settlement = await reconcileSubsidy(database, {
         address: options.address,
         delivered,
-        deposit,
+        deposit:
+          providerSubsidy && deposit.id === providerSubsidyDepositId
+            ? { ...deposit, providerSubsidy }
+            : deposit,
         providerEvidenceComplete,
+        providerSucceeded,
         required,
         sourceAmount,
         subsidies: options.subsidies,
         verifyTransfers: options.verifyTransfers,
       })
+      const providerUpdate =
+        providerSubsidy && deposit.id === providerSubsidyDepositId
+          ? providerSubsidyUpdate({
+              address: options.address,
+              deposit: {
+                ...deposit,
+                ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
+                ...(settlement.settlementTransactionHash
+                  ? { settlementTransactionHash: settlement.settlementTransactionHash }
+                  : {}),
+              },
+              subsidy: providerSubsidy,
+            })
+          : {}
       const destinationAmount = Value.tokenAmount({
         baseUnits: delivered + settlement.delivered,
         currency: options.address.snapshot.destinationToken.currency,
@@ -1403,17 +1511,16 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
               }
             : {}),
           ...(providerEvidenceComplete ? { providerDeliveredAt: new Date().toISOString() } : {}),
-          ...(providerSubsidy && deposit.id === providerSubsidyDepositId
-            ? { providerSubsidy }
-            : {}),
+          ...providerUpdate,
           providerRequestIds: options.request
             ? unique([...deposit.providerRequestIds, options.request.id])
             : deposit.providerRequestIds,
-          ...(deliveryObservation?.providerState
+          ...(deliveryObservation?.providerState || providerUpdate.providerState
             ? {
                 providerState: {
                   ...deposit.providerState,
-                  ...deliveryObservation.providerState,
+                  ...deliveryObservation?.providerState,
+                  ...providerUpdate.providerState,
                 },
               }
             : {}),
@@ -1489,6 +1596,14 @@ async function reconcileDelivery(db: Db.Db, options: ReconcileDeliveryOptions) {
       })
       options.onDeposit?.(result.record, committed.references)
       updatedIds.add(deposit.id)
+      if (
+        !deposit.providerState?.['unbilledProviderSubsidy'] &&
+        result.record.providerState?.['unbilledProviderSubsidy']
+      )
+        options.metrics?.count('routes_deposit_subsidy_count', 1, {
+          outcome: 'provider_subsidy_unbilled',
+          provider: options.address.providerId,
+        })
     }
     if (result.type === 'applied' || result.type === 'unchanged') {
       if (settlement.broadcast && options.subsidies) {
@@ -1514,6 +1629,7 @@ type ReconcileSubsidyOptions = {
   delivered: bigint
   deposit: RoutesDeposits.Record
   providerEvidenceComplete: boolean
+  providerSucceeded: boolean
   required: bigint
   sourceAmount: bigint
   subsidies?: Subsidy.Settler | undefined
@@ -1643,11 +1759,25 @@ async function reconcileSubsidy(
       },
     }
   }
+  // Fixed-rate delivery belongs in the provider fill; never add a second destination transaction.
+  if (options.address.providerState?.['fixedRate'] === '1:1' && options.providerSucceeded)
+    return {
+      ...empty,
+      outcome: 'underfilled',
+      status: 'action-required',
+      statusReason: {
+        code: 'subsidy_failed',
+        message: 'The provider completed without delivering the fixed-rate amount.',
+      },
+    }
   if (!options.providerEvidenceComplete) return { ...empty, status: 'bridging' }
-  const policy = await Subsidy.check(db, {
-    environment: options.address.environment,
-    orgId: options.address.orgId,
-  })
+  const commitment = Policy.commitment(options.address.providerState)
+  const policy = commitment
+    ? ({ maxAmount: commitment.maxAmount, type: 'allowed' } as const)
+    : await Subsidy.check(db, {
+        environment: options.address.environment,
+        orgId: options.address.orgId,
+      })
   if (policy.type === 'denied')
     return {
       ...empty,
@@ -1658,9 +1788,21 @@ async function reconcileSubsidy(
         message: Subsidy.denialMessages[policy.reason],
       },
     }
+  const providerExpense =
+    options.deposit.providerSubsidy ??
+    Provider.schema.Subsidy.safeParse(options.deposit.providerState?.['unbilledProviderSubsidy'])
+      .data
+  const providerSubsidyAmount =
+    commitment && providerExpense
+      ? scaleBaseUnits(
+          BigInt(providerExpense.amount.baseUnits),
+          providerExpense.amount.decimals,
+          options.address.snapshot.destinationToken.decimals,
+        )
+      : 0n
   if (
     !Subsidy.supportsGap(policy, {
-      amount: deficit,
+      amount: deficit + providerSubsidyAmount,
       destinationToken: options.address.snapshot.destinationToken,
     })
   )
@@ -1684,6 +1826,7 @@ async function reconcileSubsidy(
       },
     }
   if (
+    !commitment &&
     !Subsidy.supports(options.subsidies.policy, {
       amount: options.sourceAmount.toString(),
       destinationToken: options.address.snapshot.destinationToken,
@@ -1741,6 +1884,14 @@ async function reconcileSubsidy(
   }
 }
 
+function scaleBaseUnits(amount: bigint, fromDecimals: number, toDecimals: number): bigint {
+  if (fromDecimals === toDecimals) return amount
+  if (fromDecimals < toDecimals) return amount * 10n ** BigInt(toDecimals - fromDecimals)
+  // Round upward: a fractional destination base unit still consumes commitment capacity.
+  const divisor = 10n ** BigInt(fromDecimals - toDecimals)
+  return (amount + divisor - 1n) / divisor
+}
+
 function destinationBaseUnits(amount: bigint, sourceDecimals: number, destinationDecimals: number) {
   if (destinationDecimals >= sourceDecimals)
     return amount * 10n ** BigInt(destinationDecimals - sourceDecimals)

package/src/internal/routes/SolanaTransferSettlement.ts

@@ -0,0 +1,232 @@
+import { Hash, Hex } from 'ox'
+
+import * as Value from '../Value.js'
+import * as SolanaTransferSubsidy from './SolanaTransferSubsidy.js'
+import * as Transfer from './Transfer.js'
+import type * as TransferSettlement from './TransferSettlement.js'
+
+/** Advances a persisted Solana subsidy through signing, broadcast, and finality. */
+export async function settle(options: settle.Options): Promise<TransferSettlement.Result> {
+  let current = options.current
+  const existing = SolanaTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+  const prepared = SolanaTransferSubsidy.readPrepared(
+    current.providerState?.['solanaTransferSubsidyPrepared'],
+  )
+  const terms = {
+    account: existing?.account ?? prepared?.account ?? current.subsidyAccount ?? '',
+    amount: options.deficit,
+    chainId: options.destinationChain.id,
+    recipient: current.snapshot.recipient,
+    token: current.snapshot.destinationToken.address,
+  }
+  if (
+    (existing && !SolanaTransferSubsidy.matchesTerms(existing, terms)) ||
+    (prepared && !SolanaTransferSubsidy.matchesTerms(prepared, terms))
+  ) {
+    options.recordSubsidy('evidence_conflict')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'Destination subsidy evidence conflicts with the verified delivery.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const account = existing?.account ?? prepared?.account ?? current.subsidyAccount
+  const settler = options.settlers?.find((entry) => entry.account === account)
+  if (!settler) {
+    options.recordSubsidy('unavailable')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'Destination subsidy settlement is unavailable.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const commitment = current.subsidyCommitmentAmount
+  if (!existing && !prepared && (!commitment || options.deficit > BigInt(commitment.baseUnits))) {
+    options.recordSubsidy('routes_subsidy_limit_exceeded')
+    return {
+      reason: {
+        code: 'routes_subsidy_limit_exceeded',
+        message: 'The required destination subsidy exceeds its approved commitment.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  const recipient = current.snapshot.recipient
+  const token = current.snapshot.destinationToken.address
+  const subsidyAmount = Value.tokenAmount({
+    baseUnits: options.deficit,
+    currency: current.snapshot.destinationToken.currency,
+    decimals: current.snapshot.destinationToken.decimals,
+  })
+  let signed = existing
+  if (!signed) {
+    const result = await Transfer.prepareSolanaSubsidy(options.db, {
+      account: settler.account,
+      chainId: options.destinationChain.id,
+      expiring: (prepared) => settler.expiring({ chain: options.destinationChain, prepared }),
+      id: current.id,
+      orgId: current.orgId,
+      prepare: ({ reservations }) =>
+        settler.prepare({
+          amount: options.deficit,
+          chain: options.destinationChain,
+          recipient,
+          reservations,
+          token,
+        }),
+      subsidyAmount,
+      tokenAddress: token,
+    }).catch((cause) => {
+      if (cause instanceof SolanaTransferSubsidy.BalanceUnavailableError) return 'balance' as const
+      if (cause instanceof Transfer.SubsidySignerBlockedError) return 'blocked' as const
+      throw cause
+    })
+    if (result === 'balance' || result === 'blocked') {
+      options.recordSubsidy(result === 'balance' ? 'balance_unavailable' : 'signer_blocked')
+      return {
+        reason: {
+          code: result === 'balance' ? 'subsidy_balance_unavailable' : 'subsidy_failed',
+          message:
+            result === 'balance'
+              ? 'Tempo lacks enough destination token inventory or native gas.'
+              : 'Destination subsidy settlement requires operator recovery.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    if (result.type === 'not_found' || result.type === 'invalid' || result.type === 'pending')
+      return { type: 'pending' }
+    current = result.record
+    if ('references' in result && result.references && options.dispatchTransferUpdates)
+      await options.dispatchTransferUpdates(result.references)
+    if (result.type === 'signed' || result.type === 'shared') {
+      signed = result.signed
+      if (result.type === 'shared') options.recordSubsidy('shared')
+    } else {
+      options.recordSubsidy('prepared')
+      if (await settler.expiring({ chain: options.destinationChain, prepared: result.prepared }))
+        return { type: 'pending' }
+      // A refreshed blockhash changes the request, so Horcrux must use a new replay key.
+      const signature = await settler.sign({
+        idempotencyKey: `${current.id}:${Hash.sha256(Hex.fromBytes(Buffer.from(result.prepared.request.transaction, 'base64')))}`,
+        prepared: result.prepared,
+      })
+      if (await settler.expiring({ chain: options.destinationChain, prepared: result.prepared }))
+        return { type: 'pending' }
+      const persisted = await Transfer.signSolanaSubsidy(options.db, {
+        id: current.id,
+        signed: signature,
+      })
+      if (persisted.type === 'not_found' || persisted.type === 'invalid') return { type: 'pending' }
+      signed = persisted.signed
+      current = persisted.record
+      if ('references' in persisted && options.dispatchTransferUpdates)
+        await options.dispatchTransferUpdates(persisted.references)
+      options.recordSubsidy(persisted.type === 'shared' ? 'shared' : 'signed')
+    }
+  }
+  if (
+    typeof current.providerState?.['transferSubsidyOwnerId'] === 'string' &&
+    current.providerState['transferSubsidyOwnerId'] !== current.id
+  ) {
+    const result = await Transfer.syncSharedSolanaSubsidy(options.db, {
+      id: current.id,
+      orgId: current.orgId,
+      signed,
+    })
+    if (result.type === 'not_found' || result.type === 'pending') return { type: 'pending' }
+    if (result.type === 'synchronized') {
+      current = result.record
+      signed = result.signed
+      options.recordSubsidy('shared')
+      if (options.dispatchTransferUpdates) await options.dispatchTransferUpdates(result.references)
+    }
+  }
+  const status = await settler.status({
+    chain: options.destinationChain,
+    recipient,
+    signed,
+    token,
+  })
+  if (status === 'expired') {
+    const result = await Transfer.recoverExpiredSolanaSubsidy(options.db, {
+      id: current.id,
+      orgId: current.orgId,
+      signed,
+    })
+    if (result.type === 'recovered') {
+      options.recordSubsidy('expired_recovered')
+      if (options.dispatchTransferUpdates) await options.dispatchTransferUpdates(result.references)
+    }
+    return { type: 'pending' }
+  }
+  if (status === 'ambiguous') {
+    options.recordSubsidy('expiry_ambiguous')
+    return {
+      reason: {
+        code: 'manual_recovery_required',
+        message: 'The Solana subsidy transaction could not be verified after expiry.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  if (status === 'reverted') {
+    options.recordSubsidy('reverted')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'The destination subsidy transaction reverted.',
+      },
+      record: current,
+      state: {
+        subsidyAmount: Value.tokenAmount({
+          baseUnits: 0n,
+          currency: current.snapshot.destinationToken.currency,
+          decimals: current.snapshot.destinationToken.decimals,
+        }),
+      },
+      type: 'action-required',
+    }
+  }
+  if (status === 'pending') {
+    const rejected = await settler.broadcast({ chain: options.destinationChain, signed }).then(
+      () => false,
+      (cause: unknown) => {
+        if (SolanaTransferSubsidy.isPermanentBroadcastError(cause)) return true
+        throw cause
+      },
+    )
+    if (rejected) {
+      options.recordSubsidy('broadcast_rejected')
+      return {
+        reason: {
+          code: 'subsidy_failed',
+          message: 'The Solana subsidy transaction was rejected.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    options.recordSubsidy('broadcast')
+    return { type: 'pending' }
+  }
+  options.recordSubsidy('completed')
+  return { amount: options.deficit, hash: signed.hash, record: current, type: 'success' }
+}
+
+export declare namespace settle {
+  /** Dependencies for one Solana settlement attempt. */
+  type Options = TransferSettlement.Options & {
+    /** Available Horcrux-managed Solana wallets. */
+    settlers?: readonly SolanaTransferSubsidy.Settler[] | undefined
+  }
+}