tapimo 0.15.0 → 0.18.0

package/src/internal/routes/Transfer.ts

@@ -13,9 +13,12 @@ import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import type * as Webhooks from '../Webhooks.js'
 import * as Action from './Action.js'
+import * as Policy from './Policy.js'
 import * as Provider from './Provider.js'
+import * as SolanaTransferSubsidy from './SolanaTransferSubsidy.js'
 import * as TransferSubsidy from './TransferSubsidy.js'
 import * as TransferWebhook from './TransferWebhook.js'
+import * as TronTransferSubsidy from './TronTransferSubsidy.js'
 
 /** Public route transfer statuses, in the order documented by the API. */
 export const statuses = [
@@ -387,9 +390,11 @@ export namespace schema {
             ),
         ),
         sourceChain: z
-          .string()
+          .optional(z.string())
           .check(
-            z.describe('Source chain CAIP-2 id, slug, or alias.'),
+            z.describe(
+              'Source chain CAIP-2 id, slug, or alias. Defaults to the destination chain.',
+            ),
             z.meta({ examples: ['tempo', 'base', 'ethereum', 'eip155:4217'] }),
           ),
         sourceToken: z
@@ -403,7 +408,7 @@ export namespace schema {
           .optional(z.boolean())
           .check(
             z.describe(
-              'Guarantees normalized 1:1 delivery for exact-source Tempo USD transfers to Base or Ethereum. A Tempo Admin must enable subsidies for the organization.',
+              'Guarantees normalized 1:1 USD delivery for exact-source transfers to Tempo or from Tempo to Base, Ethereum, Solana, or Tron. Requires organization subsidy approval.',
             ),
             z.meta({ examples: [true] }),
           ),
@@ -477,13 +482,21 @@ export async function createIn(tx: Db.Db, input: create.Input): Promise<createIn
     status: 'awaiting-source',
     statusReason: null,
     statusUpdatedAt: now.toISOString(),
-    subsidyAccount: input.subsidyCommitment?.account.toLowerCase() ?? null,
+    subsidyAccount: input.subsidyCommitment
+      ? input.subsidyCommitment.chainId.startsWith('eip155:')
+        ? input.subsidyCommitment.account.toLowerCase()
+        : input.subsidyCommitment.account
+      : null,
     subsidyAmount: null,
     subsidyChainId: input.subsidyCommitment?.chainId ?? null,
     subsidyCommitmentAmount: input.subsidyCommitment?.amount ?? null,
     subsidyMeterReportedAt: null,
     subsidyNativeAmount: input.subsidyCommitment?.nativeAmount ?? null,
-    subsidyTokenAddress: input.subsidyCommitment?.tokenAddress.toLowerCase() ?? null,
+    subsidyTokenAddress: input.subsidyCommitment
+      ? input.subsidyCommitment.chainId.startsWith('eip155:')
+        ? input.subsidyCommitment.tokenAddress.toLowerCase()
+        : input.subsidyCommitment.tokenAddress
+      : null,
     subsidyTransactionHash: null,
     updatedAt: now.toISOString(),
     version: 1,
@@ -954,6 +967,786 @@ export declare namespace reserveSubsidy {
     | { type: 'not_found' }
 }
 
+/** Persists an unsigned Solana subsidy before contacting the signer. */
+export async function prepareSolanaSubsidy(
+  db: Db.Db,
+  options: prepareSolanaSubsidy.Options,
+): Promise<prepareSolanaSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    await RoutesSubsidies.lockOrganization(tx, options.orgId)
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.orgId !== options.orgId || current.status !== 'processing')
+      return { current, type: 'invalid' }
+    const signed = SolanaTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (signed) {
+      if (
+        !SolanaTransferSubsidy.matchesTerms(signed, {
+          account: options.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      return { record: current, signed, type: 'signed' }
+    }
+    const existing = SolanaTransferSubsidy.readPrepared(
+      current.providerState?.['solanaTransferSubsidyPrepared'],
+    )
+    if (existing) {
+      if (
+        !SolanaTransferSubsidy.matchesTerms(existing, {
+          account: options.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      if (!(await options.expiring(existing)))
+        return { prepared: existing, record: current, type: 'prepared' }
+    }
+    if (
+      !current.subsidyCommitmentAmount ||
+      BigInt(options.subsidyAmount.baseUnits) > BigInt(current.subsidyCommitmentAmount.baseUnits)
+    )
+      throw new SubsidyCommitmentExceededError()
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const settlement = await RoutesTransferSubsidies.getForUpdateIn(tx, {
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+    })
+    if (settlement) {
+      const signed = SolanaTransferSubsidy.readSigned(settlement.transaction)
+      if (
+        !signed ||
+        settlement.destinationChainId !== options.chainId ||
+        settlement.recipient !== current.snapshot.recipient ||
+        settlement.tokenAddress !== options.tokenAddress ||
+        !SolanaTransferSubsidy.matchesTerms(signed, {
+          account: signed.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      // The original owner alone can replace the expired canonical transaction.
+      if (settlement.status === 'expired') {
+        if (settlement.transferId !== current.id) return { type: 'pending' }
+      } else {
+        const result = await transitionIn(tx, {
+          current,
+          expectedVersion: current.version,
+          id: current.id,
+          // Preserve Solana transaction bytes as serialized text for exact replay.
+          providerState: {
+            ...current.providerState,
+            transferSubsidy: JSON.stringify(signed),
+            transferSubsidyOwnerId: settlement.transferId,
+          },
+          subsidyAccount: signed.account,
+          subsidyAmount: null,
+          subsidyChainId: signed.chainId,
+          subsidyCommitmentAmount: null,
+          subsidyNativeAmount: null,
+          subsidyTokenAddress: settlement.tokenAddress,
+          subsidyTransactionHash: signed.hash,
+        })
+        if (result.type !== 'applied') throw new AtomicTransitionError()
+        return { record: result.record, references: result.references, signed, type: 'shared' }
+      }
+    }
+    await RoutesTransferSubsidyNonces.lockAvailableIn(tx, {
+      account: options.account,
+      chainId: options.chainId,
+    }).catch((cause) => {
+      if (cause instanceof RoutesTransferSubsidyNonces.BlockedError)
+        throw new SubsidySignerBlockedError()
+      throw cause
+    })
+    const reservations = await RoutesTransfers.subsidyReservations(tx, {
+      account: options.account,
+      chainId: options.chainId,
+      excludeId: current.id,
+      tokenAddress: options.tokenAddress,
+    })
+    const prepared = await options.prepare({ reservations })
+    if (
+      !SolanaTransferSubsidy.matchesTerms(prepared, {
+        account: options.account,
+        amount: BigInt(options.subsidyAmount.baseUnits),
+        chainId: options.chainId,
+        recipient: current.snapshot.recipient,
+        token: options.tokenAddress,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      // Keep the native transaction bytes and Horcrux request intact across database round trips.
+      providerState: {
+        ...current.providerState,
+        solanaTransferSubsidyPrepared: JSON.stringify(prepared),
+      },
+      subsidyAccount: options.account,
+      subsidyAmount: options.subsidyAmount,
+      subsidyChainId: options.chainId,
+      subsidyNativeAmount: prepared.nativeAmount,
+      subsidyTokenAddress: options.tokenAddress,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { prepared, record: result.record, references: result.references, type: 'prepared' }
+  })
+}
+
+export declare namespace prepareSolanaSubsidy {
+  /** Solana subsidy preparation under the organization and signer locks. */
+  type Options = {
+    /** Horcrux-managed Solana account. */
+    account: string
+    /** Destination chain identifier. */
+    chainId: string
+    /** Checks whether a persisted unsigned transaction needs a fresh blockhash. */
+    expiring: (prepared: SolanaTransferSubsidy.Prepared) => Promise<boolean>
+    /** Route transfer identifier. */
+    id: string
+    /** Owning organization identifier. */
+    orgId: string
+    /** Builds an unsigned transaction against reserved inventory. */
+    prepare: (options: {
+      reservations: RoutesTransfers.subsidyReservations.Result
+    }) => Promise<SolanaTransferSubsidy.Prepared>
+    /** Subsidy amount approved by policy. */
+    subsidyAmount: NonNullable<Snapshot['destinationAmountRequired']>
+    /** Solana USDC contract address. */
+    tokenAddress: string
+  }
+
+  /** Durable preparation or existing signed settlement. */
+  type Result =
+    | { current: RoutesTransfers.Record; type: 'invalid' }
+    | { type: 'not_found' }
+    | { type: 'pending' }
+    | {
+        prepared: SolanaTransferSubsidy.Prepared
+        record: RoutesTransfers.Record
+        references?: readonly Webhooks.QueueReference[] | undefined
+        type: 'prepared'
+      }
+    | { record: RoutesTransfers.Record; signed: SolanaTransferSubsidy.Signed; type: 'signed' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        signed: SolanaTransferSubsidy.Signed
+        type: 'shared'
+      }
+}
+
+/** Persists a verified Solana signature before broadcasting the transaction. */
+export async function signSolanaSubsidy(
+  db: Db.Db,
+  options: signSolanaSubsidy.Options,
+): Promise<signSolanaSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+    const existing = SolanaTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (existing) return { record: current, signed: existing, type: 'replayed' }
+    const prepared = SolanaTransferSubsidy.readPrepared(
+      current.providerState?.['solanaTransferSubsidyPrepared'],
+    )
+    if (
+      !prepared ||
+      prepared.request.transaction !== options.signed.request.transaction ||
+      prepared.lastValidBlockHeight !== options.signed.lastValidBlockHeight ||
+      prepared.account !== options.signed.account ||
+      prepared.amount !== options.signed.amount ||
+      prepared.chainId !== options.signed.chainId ||
+      !SolanaTransferSubsidy.matchesTerms(options.signed, {
+        account: prepared.account,
+        amount: BigInt(prepared.amount),
+        chainId: prepared.chainId,
+        recipient: current.snapshot.recipient,
+        token: current.snapshot.destinationToken.address,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const settlement = await RoutesTransferSubsidies.getForUpdateIn(tx, {
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+    })
+    const signed =
+      settlement?.status === 'active'
+        ? SolanaTransferSubsidy.readSigned(settlement.transaction)
+        : options.signed
+    if (
+      !signed ||
+      (settlement &&
+        (settlement.destinationChainId !== prepared.chainId ||
+          settlement.recipient !== current.snapshot.recipient ||
+          settlement.tokenAddress !== current.snapshot.destinationToken.address ||
+          (settlement.status === 'expired' && settlement.transferId !== current.id) ||
+          !SolanaTransferSubsidy.matchesTerms(signed, {
+            account: signed.account,
+            amount: BigInt(prepared.amount),
+            chainId: prepared.chainId,
+            recipient: current.snapshot.recipient,
+            token: current.snapshot.destinationToken.address,
+          })))
+    )
+      throw new SubsidyEvidenceError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: {
+        ...current.providerState,
+        transferSubsidy: JSON.stringify(signed),
+        ...(settlement?.status === 'active'
+          ? { transferSubsidyOwnerId: settlement.transferId }
+          : {}),
+      },
+      ...(settlement?.status === 'active'
+        ? { subsidyAmount: null, subsidyCommitmentAmount: null, subsidyNativeAmount: null }
+        : {}),
+      subsidyTransactionHash: signed.hash,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return {
+      record: result.record,
+      references: result.references,
+      signed,
+      type: settlement?.status === 'active' ? 'shared' : 'signed',
+    }
+  })
+}
+
+export declare namespace signSolanaSubsidy {
+  /** Signed transaction and owning route transfer. */
+  type Options = { id: string; signed: SolanaTransferSubsidy.Signed }
+  /** Persisted signed settlement or a stale transfer. */
+  type Result =
+    | { current: RoutesTransfers.Record; type: 'invalid' }
+    | { type: 'not_found' }
+    | { record: RoutesTransfers.Record; signed: SolanaTransferSubsidy.Signed; type: 'replayed' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        signed: SolanaTransferSubsidy.Signed
+        type: 'shared' | 'signed'
+      }
+}
+
+/** Follows the canonical subsidy when another transfer owns the source payment. */
+export async function syncSharedSolanaSubsidy(
+  db: Db.Db,
+  options: syncSharedSolanaSubsidy.Options,
+): Promise<syncSharedSolanaSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    await RoutesSubsidies.lockOrganization(tx, options.orgId)
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.orgId !== options.orgId || current.status !== 'processing')
+      return { type: 'pending' }
+    const signed = SolanaTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (
+      !signed ||
+      signed.hash !== options.signed.hash ||
+      current.subsidyTransactionHash !== signed.hash
+    )
+      return { type: 'pending' }
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const settlement = await RoutesTransferSubsidies.getForUpdateIn(tx, {
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+    })
+    if (
+      !settlement ||
+      settlement.destinationChainId !== signed.chainId ||
+      settlement.recipient !== signed.recipient ||
+      settlement.tokenAddress !== signed.token
+    )
+      throw new SubsidyEvidenceError()
+    if (settlement.transferId === current.id) return { type: 'unchanged' }
+    // The owner has already proved expiry; shared transfers wait for its replacement.
+    if (settlement.status === 'expired') return { type: 'pending' }
+    const replacement = SolanaTransferSubsidy.readSigned(settlement.transaction)
+    if (
+      !replacement ||
+      !SolanaTransferSubsidy.matchesTerms(replacement, {
+        account: signed.account,
+        amount: BigInt(signed.amount),
+        chainId: signed.chainId,
+        recipient: signed.recipient,
+        token: signed.token,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    if (replacement.hash === signed.hash) return { type: 'unchanged' }
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: {
+        ...current.providerState,
+        solanaTransferSubsidyPrepared: null,
+        transferSubsidy: JSON.stringify(replacement),
+        transferSubsidyOwnerId: settlement.transferId,
+      },
+      subsidyTransactionHash: replacement.hash,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return {
+      record: result.record,
+      references: result.references,
+      signed: replacement,
+      type: 'synchronized',
+    }
+  })
+}
+
+export declare namespace syncSharedSolanaSubsidy {
+  /** Transfer and previously shared signed transaction. */
+  type Options = {
+    /** Route transfer identifier. */
+    id: string
+    /** Owning organization identifier. */
+    orgId: string
+    /** Signed attempt currently stored on the transfer. */
+    signed: SolanaTransferSubsidy.Signed
+  }
+
+  /** Canonical replacement, unchanged transaction, or a pending owner refresh. */
+  type Result =
+    | { type: 'not_found' }
+    | { type: 'pending' }
+    | { type: 'unchanged' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        signed: SolanaTransferSubsidy.Signed
+        type: 'synchronized'
+      }
+}
+
+/** Retires an unlanded signed Solana attempt so its billing owner can prepare again. */
+export async function recoverExpiredSolanaSubsidy(
+  db: Db.Db,
+  options: recoverExpiredSolanaSubsidy.Options,
+): Promise<recoverExpiredSolanaSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    await RoutesSubsidies.lockOrganization(tx, options.orgId)
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.orgId !== options.orgId || current.status !== 'processing')
+      return { type: 'pending' }
+    const signed = SolanaTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (
+      !signed ||
+      signed.hash !== options.signed.hash ||
+      current.subsidyTransactionHash !== signed.hash
+    )
+      return { type: 'pending' }
+    if (
+      !SolanaTransferSubsidy.matchesTerms(signed, {
+        account: signed.account,
+        amount: BigInt(signed.amount),
+        chainId: current.snapshot.destinationChain.id,
+        recipient: current.snapshot.recipient,
+        token: current.snapshot.destinationToken.address,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const outcome = await RoutesTransferSubsidies.markExpiredIn(tx, {
+      signedHash: signed.hash,
+      signedTransaction: JSON.stringify(signed),
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+      transferId: current.id,
+    })
+    if (outcome.type === 'not_found') throw new SubsidyEvidenceError()
+    const settlement = outcome.settlement
+    if (
+      settlement.destinationChainId !== signed.chainId ||
+      settlement.recipient !== signed.recipient ||
+      settlement.tokenAddress !== signed.token
+    )
+      throw new SubsidyEvidenceError()
+    if (outcome.type === 'expired') {
+      const result = await transitionIn(tx, {
+        current,
+        expectedVersion: current.version,
+        id: current.id,
+        providerState: {
+          ...current.providerState,
+          solanaTransferSubsidyPrepared: null,
+          transferSubsidy: null,
+          transferSubsidyOwnerId: null,
+        },
+        subsidyTransactionHash: null,
+      })
+      if (result.type !== 'applied') throw new AtomicTransitionError()
+      return { record: result.record, references: result.references, type: 'recovered' }
+    }
+    if (settlement.status !== 'active') return { type: 'pending' }
+    const replacement = SolanaTransferSubsidy.readSigned(settlement.transaction)
+    if (!replacement || replacement.hash === signed.hash || replacement.amount !== signed.amount)
+      return { type: 'pending' }
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: {
+        ...current.providerState,
+        solanaTransferSubsidyPrepared: null,
+        transferSubsidy: JSON.stringify(replacement),
+        transferSubsidyOwnerId: settlement.transferId,
+      },
+      subsidyTransactionHash: replacement.hash,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { record: result.record, references: result.references, type: 'recovered' }
+  })
+}
+
+export declare namespace recoverExpiredSolanaSubsidy {
+  /** The current transfer and verified expired signed attempt. */
+  type Options = {
+    /** Route transfer identifier. */
+    id: string
+    /** Owning organization identifier. */
+    orgId: string
+    /** Signed transaction proven absent after finality. */
+    signed: SolanaTransferSubsidy.Signed
+  }
+
+  /** Recovery or a concurrent settlement change. */
+  type Result =
+    | { type: 'not_found' | 'pending' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        type: 'recovered'
+      }
+}
+
+/** Persists an unsigned Tron subsidy before contacting the signer. */
+export async function prepareTronSubsidy(
+  db: Db.Db,
+  options: prepareTronSubsidy.Options,
+): Promise<prepareTronSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    await RoutesSubsidies.lockOrganization(tx, options.orgId)
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.orgId !== options.orgId || current.status !== 'processing')
+      return { current, type: 'invalid' }
+    const signed = TronTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (signed) {
+      if (
+        !TronTransferSubsidy.matchesTerms(signed, {
+          account: options.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      return { record: current, signed, type: 'signed' }
+    }
+    const existing = TronTransferSubsidy.readPrepared(
+      current.providerState?.['tronTransferSubsidyPrepared'],
+    )
+    if (existing) {
+      if (
+        !TronTransferSubsidy.matchesTerms(existing, {
+          account: options.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      return { prepared: existing, record: current, type: 'prepared' }
+    }
+    if (
+      !current.subsidyCommitmentAmount ||
+      BigInt(options.subsidyAmount.baseUnits) > BigInt(current.subsidyCommitmentAmount.baseUnits)
+    )
+      throw new SubsidyCommitmentExceededError()
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const settlement = await RoutesTransferSubsidies.getForUpdateIn(tx, {
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+    })
+    if (settlement) {
+      const signed = TronTransferSubsidy.readSigned(settlement.transaction)
+      if (
+        !signed ||
+        settlement.destinationChainId !== options.chainId ||
+        settlement.recipient !== current.snapshot.recipient ||
+        settlement.tokenAddress !== options.tokenAddress ||
+        !TronTransferSubsidy.matchesTerms(signed, {
+          account: signed.account,
+          amount: BigInt(options.subsidyAmount.baseUnits),
+          chainId: options.chainId,
+          recipient: current.snapshot.recipient,
+          token: options.tokenAddress,
+        })
+      )
+        throw new SubsidyEvidenceError()
+      const result = await transitionIn(tx, {
+        current,
+        expectedVersion: current.version,
+        id: current.id,
+        // The database maps nested JSON keys to camelCase; preserve Tron raw_data for exact replay.
+        providerState: {
+          ...current.providerState,
+          transferSubsidy: JSON.stringify(signed),
+          transferSubsidyOwnerId: settlement.transferId,
+        },
+        subsidyAccount: signed.account,
+        subsidyAmount: null,
+        subsidyChainId: signed.chainId,
+        subsidyCommitmentAmount: null,
+        subsidyNativeAmount: null,
+        subsidyTokenAddress: settlement.tokenAddress,
+        subsidyTransactionHash: signed.hash,
+      })
+      if (result.type !== 'applied') throw new AtomicTransitionError()
+      return { record: result.record, references: result.references, signed, type: 'shared' }
+    }
+    await RoutesTransferSubsidyNonces.lockAvailableIn(tx, {
+      account: options.account,
+      chainId: options.chainId,
+    }).catch((cause) => {
+      if (cause instanceof RoutesTransferSubsidyNonces.BlockedError)
+        throw new SubsidySignerBlockedError()
+      throw cause
+    })
+    const reservations = await RoutesTransfers.subsidyReservations(tx, {
+      account: options.account,
+      chainId: options.chainId,
+      excludeId: current.id,
+      tokenAddress: options.tokenAddress,
+    })
+    const prepared = await options.prepare({ reservations })
+    if (
+      !TronTransferSubsidy.matchesTerms(prepared, {
+        account: options.account,
+        amount: BigInt(options.subsidyAmount.baseUnits),
+        chainId: options.chainId,
+        recipient: current.snapshot.recipient,
+        token: options.tokenAddress,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      // Keep the native transaction bytes and Horcrux request field names intact across database round trips.
+      providerState: {
+        ...current.providerState,
+        tronTransferSubsidyPrepared: JSON.stringify(prepared),
+      },
+      subsidyAccount: options.account,
+      subsidyAmount: options.subsidyAmount,
+      subsidyChainId: options.chainId,
+      subsidyNativeAmount: prepared.nativeAmount,
+      subsidyTokenAddress: options.tokenAddress,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return { prepared, record: result.record, references: result.references, type: 'prepared' }
+  })
+}
+
+export declare namespace prepareTronSubsidy {
+  /** Tron subsidy preparation under the organization and signer locks. */
+  type Options = {
+    /** Horcrux-managed Tron account. */
+    account: string
+    /** Destination chain identifier. */
+    chainId: string
+    /** Route transfer identifier. */
+    id: string
+    /** Owning organization identifier. */
+    orgId: string
+    /** Builds an unsigned transaction against reserved inventory. */
+    prepare: (options: {
+      reservations: RoutesTransfers.subsidyReservations.Result
+    }) => Promise<TronTransferSubsidy.Prepared>
+    /** Subsidy amount approved by policy. */
+    subsidyAmount: NonNullable<Snapshot['destinationAmountRequired']>
+    /** Tron USDT contract address. */
+    tokenAddress: string
+  }
+
+  /** Durable preparation or existing signed settlement. */
+  type Result =
+    | { current: RoutesTransfers.Record; type: 'invalid' }
+    | { type: 'not_found' }
+    | {
+        prepared: TronTransferSubsidy.Prepared
+        record: RoutesTransfers.Record
+        references?: readonly Webhooks.QueueReference[] | undefined
+        type: 'prepared'
+      }
+    | { record: RoutesTransfers.Record; signed: TronTransferSubsidy.Signed; type: 'signed' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        signed: TronTransferSubsidy.Signed
+        type: 'shared'
+      }
+}
+
+/** Persists a verified Tron signature before broadcasting the transaction. */
+export async function signTronSubsidy(
+  db: Db.Db,
+  options: signTronSubsidy.Options,
+): Promise<signTronSubsidy.Result> {
+  return db.transaction(async (tx) => {
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.status !== 'processing') return { current, type: 'invalid' }
+    const existing = TronTransferSubsidy.readSigned(current.providerState?.['transferSubsidy'])
+    if (existing) return { record: current, signed: existing, type: 'replayed' }
+    const prepared = TronTransferSubsidy.readPrepared(
+      current.providerState?.['tronTransferSubsidyPrepared'],
+    )
+    if (
+      !prepared ||
+      prepared.hash !== options.signed.hash ||
+      prepared.account !== options.signed.account ||
+      prepared.amount !== options.signed.amount ||
+      prepared.chainId !== options.signed.chainId ||
+      !TronTransferSubsidy.matchesTerms(options.signed, {
+        account: prepared.account,
+        amount: BigInt(prepared.amount),
+        chainId: prepared.chainId,
+        recipient: current.snapshot.recipient,
+        token: current.snapshot.destinationToken.address,
+      })
+    )
+      throw new SubsidyEvidenceError()
+    const transactionRef = current.snapshot.sourceTransactionHashes?.[0]
+    const source = transactionRef
+      ? await RoutesTransferTransactions.getSource(tx, {
+          chainId: current.snapshot.sourceChain.id,
+          transactionRef,
+          transferId: current.id,
+        })
+      : undefined
+    if (source?.transferId !== current.id) throw new SubsidyEvidenceError()
+    const settlement = await RoutesTransferSubsidies.getForUpdateIn(tx, {
+      sourceChainId: source.chainId,
+      transactionRef: source.transactionRef,
+    })
+    const signed = settlement
+      ? TronTransferSubsidy.readSigned(settlement.transaction)
+      : options.signed
+    if (
+      !signed ||
+      (settlement &&
+        (settlement.destinationChainId !== prepared.chainId ||
+          settlement.recipient !== current.snapshot.recipient ||
+          settlement.tokenAddress !== current.snapshot.destinationToken.address ||
+          signed.amount !== prepared.amount))
+    )
+      throw new SubsidyEvidenceError()
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      providerState: {
+        ...current.providerState,
+        transferSubsidy: JSON.stringify(signed),
+        ...(settlement ? { transferSubsidyOwnerId: settlement.transferId } : {}),
+      },
+      ...(settlement
+        ? { subsidyAmount: null, subsidyCommitmentAmount: null, subsidyNativeAmount: null }
+        : {}),
+      subsidyTransactionHash: signed.hash,
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return {
+      record: result.record,
+      references: result.references,
+      signed,
+      type: settlement ? 'shared' : 'signed',
+    }
+  })
+}
+
+export declare namespace signTronSubsidy {
+  /** Signed transaction and owning route transfer. */
+  type Options = { id: string; signed: TronTransferSubsidy.Signed }
+  /** Persisted signed settlement or a stale transfer. */
+  type Result =
+    | { current: RoutesTransfers.Record; type: 'invalid' }
+    | { type: 'not_found' }
+    | { record: RoutesTransfers.Record; signed: TronTransferSubsidy.Signed; type: 'replayed' }
+    | {
+        record: RoutesTransfers.Record
+        references: readonly Webhooks.QueueReference[]
+        signed: TronTransferSubsidy.Signed
+        type: 'shared' | 'signed'
+      }
+}
+
 /** Atomically records a verified destination transaction and completes a transfer. */
 export async function complete(db: Db.Db, options: complete.Options): Promise<complete.Result> {
   return db.transaction(async (tx) => {
@@ -966,7 +1759,8 @@ export async function complete(db: Db.Db, options: complete.Options): Promise<co
           (transaction) =>
             transaction.chainId === options.chainId &&
             transaction.role === 'destination' &&
-            transaction.transactionRef === transactionHash.toLowerCase(),
+            transaction.transactionRef ===
+              RoutesTransferTransactions.normalize(options.chainId, transactionHash),
         ),
       )
       return existing ? { record: current, type: 'replayed' } : { current, type: 'invalid' }
@@ -1024,6 +1818,59 @@ export declare namespace complete {
     | { type: 'not_found' }
 }
 
+/**
+ * Returns an `action-required` transfer to `processing` so reconciliation re-verifies it.
+ * Refuses transfers holding a prepared or signed subsidy, which need on-chain recovery first.
+ */
+export async function retry(db: Db.Db, options: retry.Options): Promise<retry.Result> {
+  return db.transaction(async (tx) => {
+    const current = await RoutesTransfers.getForUpdate(tx, options.id)
+    if (!current) return { type: 'not_found' }
+    if (current.version !== options.expectedVersion) return { current, type: 'stale' }
+    if (current.status !== 'action-required') return { current, type: 'invalid' }
+    // A prepared or signed subsidy may still land; reconciling again could prepare a replacement.
+    const state = current.providerState
+    if (
+      current.subsidyTransactionHash !== null ||
+      state?.['transferSubsidy'] ||
+      state?.['solanaTransferSubsidyPrepared'] ||
+      state?.['tronTransferSubsidyPrepared']
+    )
+      return { current, type: 'subsidy_pending' }
+    const result = await transitionIn(tx, {
+      current,
+      expectedVersion: current.version,
+      id: current.id,
+      status: 'processing',
+    })
+    if (result.type !== 'applied') throw new AtomicTransitionError()
+    return {
+      previous: current,
+      record: result.record,
+      references: result.references,
+      type: 'retried',
+    }
+  })
+}
+
+export declare namespace retry {
+  /** Transfer to retry. */
+  type Options = {
+    /** The version the operator reviewed. */
+    expectedVersion: number
+    /** Transfer id (`rtr_…`). */
+    id: string
+  }
+
+  /** Transfer retry outcome. */
+  type Result =
+    | (Staged & { previous: RoutesTransfers.Record; type: 'retried' })
+    | { current: RoutesTransfers.Record; type: 'invalid' }
+    | { current: RoutesTransfers.Record; type: 'stale' }
+    | { current: RoutesTransfers.Record; type: 'subsidy_pending' }
+    | { type: 'not_found' }
+}
+
 /**
  * Applies a version-guarded material change: a status transition, a snapshot
  * update, or both. The row update and its immutable event commit in one
@@ -1049,12 +1896,23 @@ async function transitionIn(
   if (status !== current.status && !canTransition(current.status, status))
     return { current, type: 'invalid' }
 
+  // Provider evidence can be replaced or cleared after a reorg; accepted
+  // financial terms remain immutable across every lifecycle transition.
+  const routePolicy = Policy.commitment(current.providerState)
+  let providerState =
+    options.providerState === undefined ? current.providerState : options.providerState
+  if (routePolicy)
+    providerState = {
+      ...providerState,
+      routePolicy,
+      routePolicyKey: Policy.commitmentKey(routePolicy),
+    }
+
   const updated = await RoutesTransfers.update(tx, {
     expectedVersion: options.expectedVersion,
     id: options.id,
     providerDeliveredAt: current.providerDeliveredAt,
-    providerState:
-      options.providerState === undefined ? current.providerState : options.providerState,
+    providerState,
     snapshot: options.snapshot === undefined ? current.snapshot : parseSnapshot(options.snapshot),
     status,
     statusReason: options.statusReason ?? (status === current.status ? current.statusReason : null),