tapimo 0.15.0 → 0.18.0

package/dist/internal/routes/Transfer.js

@@ -10,9 +10,12 @@ import * as Id from '../Id.js';
 import * as OpenApi from '../OpenApi.js';
 import * as Schema from '../Schema.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 = [
     'awaiting-source',
@@ -242,14 +245,14 @@ export var schema;
             .number()
             .check(z.int(), z.gte(0), z.lte(10_000), z.describe('Maximum acceptable slippage in basis points.'), z.meta({ examples: [50] }))),
         sourceChain: z
-            .string()
-            .check(z.describe('Source chain CAIP-2 id, slug, or alias.'), z.meta({ examples: ['tempo', 'base', 'ethereum', 'eip155:4217'] })),
+            .optional(z.string())
+            .check(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
             .string()
             .check(z.minLength(1), z.describe('Source token symbol, contract address, or token key.'), z.meta({ examples: ['usdce', 'usdc'] })),
         subsidize: z
             .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.'), z.meta({ examples: [true] })),
+            .check(z.describe('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] })),
     })
         .check(z.describe('Route transfer creation request.')), 'CreateRoutesTransferRequest');
 })(schema || (schema = {}));
@@ -287,13 +290,21 @@ export async function createIn(tx, input) {
         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,
@@ -569,6 +580,585 @@ export async function blockSubsidy(db, options) {
         });
     });
 }
+/** Persists an unsigned Solana subsidy before contacting the signer. */
+export async function prepareSolanaSubsidy(db, options) {
+    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' };
+    });
+}
+/** Persists a verified Solana signature before broadcasting the transaction. */
+export async function signSolanaSubsidy(db, options) {
+    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',
+        };
+    });
+}
+/** Follows the canonical subsidy when another transfer owns the source payment. */
+export async function syncSharedSolanaSubsidy(db, options) {
+    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',
+        };
+    });
+}
+/** Retires an unlanded signed Solana attempt so its billing owner can prepare again. */
+export async function recoverExpiredSolanaSubsidy(db, options) {
+    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' };
+    });
+}
+/** Persists an unsigned Tron subsidy before contacting the signer. */
+export async function prepareTronSubsidy(db, options) {
+    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' };
+    });
+}
+/** Persists a verified Tron signature before broadcasting the transaction. */
+export async function signTronSubsidy(db, options) {
+    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',
+        };
+    });
+}
 /** Atomically records a verified destination transaction and completes a transfer. */
 export async function complete(db, options) {
     return db.transaction(async (tx) => {
@@ -579,7 +1169,8 @@ export async function complete(db, options) {
             const transactions = await RoutesTransferTransactions.listByTransfer(tx, current.id);
             const existing = options.transactionHashes.every((transactionHash) => transactions.some((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' };
         }
         if (current.status !== 'processing')
@@ -609,6 +1200,42 @@ export async function complete(db, options) {
         return { record: result.record, references: result.references, type: 'completed' };
     });
 }
+/**
+ * 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, options) {
+    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',
+        };
+    });
+}
 /**
  * Applies a version-guarded material change: a status transition, a snapshot
  * update, or both. The row update and its immutable event commit in one
@@ -628,11 +1255,21 @@ async function transitionIn(tx, options) {
     const status = options.status ?? current.status;
     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),