tapimo 0.13.0 → 0.15.0

package/dist/apps/routes/routes/transfers.js

@@ -0,0 +1,1140 @@
+import { Hono } from 'hono';
+import { etag } from 'hono/etag';
+import { AbiFunction, Hex } from 'ox';
+import { getAddress } from 'viem';
+import * as z from 'zod/mini';
+import * as Db from '../../../db/Db.js';
+import * as RoutesIdempotency from '../../../db/tables/routesIdempotency.js';
+import * as RoutesTransfers from '../../../db/tables/routesTransfers.js';
+import * as Auth from '../../../internal/Auth.js';
+import * as Cache from '../../../internal/Cache.js';
+import * as RoutesCatalog from '../../../internal/routes/Catalog.js';
+import * as RoutesObservability from '../../../internal/routes/Observability.js';
+import * as RoutesProvider from '../../../internal/routes/Provider.js';
+import * as RoutesSubsidy from '../../../internal/routes/Subsidy.js';
+import * as RoutesTransfer from '../../../internal/routes/Transfer.js';
+import * as RoutesTransferSubsidy from '../../../internal/routes/TransferSubsidy.js';
+import * as RoutesTransferReconciliation from '../../../internal/routes/TransferReconciliation.js';
+import * as Idempotency from '../../../internal/Idempotency.js';
+import * as OpenApi from '../../../internal/OpenApi.js';
+import * as Response from '../../../internal/Response.js';
+import * as Schema from '../../../internal/Schema.js';
+import * as Value from '../../../internal/Value.js';
+import * as Access from '../Access.js';
+const maximumSourceTransactionHashes = 10;
+const recipientExample = getAddress(`0x${'11'.repeat(20)}`);
+const senderExample = getAddress(`0x${'22'.repeat(20)}`);
+const stargatePoolExample = '0x8c76e2f6c5ceda9aa7772e7eff30280226c44392';
+const stargateApproveExample = AbiFunction.from('function approve(address spender, uint256 amount)');
+const stargateFeeTokenExample = '0x0cEb237E109eE22374a567c6b09F373C73FA4cBb';
+const stargateSendExample = AbiFunction.from('function send((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress)');
+const stargateWrapExample = AbiFunction.from('function wrap(address token, address to, uint256 amount)');
+/** Zod schemas owned by route transfer resources. */
+export var schema;
+(function (schema) {
+    /** A durable route transfer. Reads never include the executable `action`. */
+    schema.Transfer = RoutesTransfer.schema.RoutesTransfer;
+    /** Schemas for the listRoutesTransfers operation. */
+    let listRoutesTransfers;
+    (function (listRoutesTransfers) {
+        /** Query parameters for listing route transfers. */
+        listRoutesTransfers.Query = z
+            .object({
+            cursor: Schema.Cursor,
+            include: Schema.totalCountInclude,
+            limit: Schema.Limit,
+            status: z.optional(RoutesTransfer.schema.Status),
+        })
+            .check(z.describe('Query parameters for listing route transfers.'));
+        /** Paginated route transfer list. */
+        listRoutesTransfers.Response = OpenApi.component(z
+            .object({
+            data: z.array(schema.Transfer).check(z.describe('Route transfers on this page, newest first.')),
+            meta: z
+                .optional(Schema.CountMeta)
+                .check(z.describe('Extra response metadata requested with `include`.')),
+            nextCursor: Schema.NextCursor,
+        })
+            .check(z.describe('A page of route transfers.')), 'RoutesTransferList');
+    })(listRoutesTransfers = schema.listRoutesTransfers || (schema.listRoutesTransfers = {}));
+    /** Schemas for the createRoutesTransfer operation. */
+    let createRoutesTransfer;
+    (function (createRoutesTransfer) {
+        /** Route transfer creation request body. */
+        createRoutesTransfer.Body = RoutesTransfer.schema.CreateRequest;
+        /** Required headers for route transfer creation. */
+        createRoutesTransfer.Headers = z.object({
+            'idempotency-key': z
+                .string()
+                .check(z.minLength(1), z.describe('Opaque retry key scoped to the API key. Matching requests replay successful responses for 24 hours; changed input conflicts, in-flight requests block, and failed attempts release the key.'), z.meta({ examples: ['routes_01k1c5j8q8p0be6j5v9m6d1e4r'] })),
+        });
+        /** The created transfer with its one-time executable action. */
+        createRoutesTransfer.Response = RoutesTransfer.schema.CreatedRoutesTransfer;
+    })(createRoutesTransfer = schema.createRoutesTransfer || (schema.createRoutesTransfer = {}));
+    const destinationCreateFields = {
+        amount: RoutesTransfer.schema.CreateRequest.shape.amount,
+        mode: RoutesTransfer.schema.CreateRequest.shape.mode,
+        recipient: RoutesTransfer.schema.CreateRequest.shape.recipient,
+        sender: RoutesTransfer.schema.CreateRequest.shape.sender,
+        slippageBps: RoutesTransfer.schema.CreateRequest.shape.slippageBps,
+        sourceChain: RoutesTransfer.schema.CreateRequest.shape.sourceChain,
+        sourceToken: RoutesTransfer.schema.CreateRequest.shape.sourceToken,
+    };
+    /** Schemas for the createRoutesTransferVault operation. */
+    let createRoutesTransferVault;
+    (function (createRoutesTransferVault) {
+        /** Route transfer creation request for an Earn vault destination. */
+        createRoutesTransferVault.Body = OpenApi.component(z
+            .strictObject({
+            ...destinationCreateFields,
+            vaultAddress: z
+                .string()
+                .check(z.regex(/^0x[0-9a-fA-F]{40}$/), z.describe('Tempo Earn vault contract address.'), z.meta({ examples: [`0x${'f4'.repeat(20)}`] })),
+        })
+            .check(z.describe('Vault route transfer creation request.')), 'CreateRoutesTransferVaultRequest');
+        /** Required headers for vault route transfer creation. */
+        createRoutesTransferVault.Headers = createRoutesTransfer.Headers;
+    })(createRoutesTransferVault = schema.createRoutesTransferVault || (schema.createRoutesTransferVault = {}));
+    /** Schemas for the createRoutesTransferZone operation. */
+    let createRoutesTransferZone;
+    (function (createRoutesTransferZone) {
+        /** Route transfer creation request for a Zone destination. */
+        createRoutesTransferZone.Body = OpenApi.component(z
+            .strictObject({
+            amount: destinationCreateFields.amount,
+            destinationChain: z
+                .string()
+                .check(z.regex(/^eip155:\d+$/), z.describe('Configured Zone CAIP-2 id.'), z.meta({ examples: ['eip155:1424310003'] })),
+            destinationToken: RoutesTransfer.schema.CreateRequest.shape.destinationToken,
+            mode: destinationCreateFields.mode,
+            recipient: destinationCreateFields.recipient,
+            recipientFallback: z
+                .string()
+                .check(z.regex(/^0x[0-9a-fA-F]{40}$/), z.describe('Public Tempo recipient used if the Zone credit cannot complete.'), z.meta({ examples: [`0x${'22'.repeat(20)}`] })),
+            sender: destinationCreateFields.sender,
+            slippageBps: destinationCreateFields.slippageBps,
+            sourceChain: destinationCreateFields.sourceChain,
+            sourceToken: destinationCreateFields.sourceToken,
+        })
+            .check(z.describe('Zone route transfer creation request.')), 'CreateRoutesTransferZoneRequest');
+        /** Required headers for Zone route transfer creation. */
+        createRoutesTransferZone.Headers = createRoutesTransfer.Headers;
+    })(createRoutesTransferZone = schema.createRoutesTransferZone || (schema.createRoutesTransferZone = {}));
+    /** Schemas for the getRoutesTransfer operation. */
+    let getRoutesTransfer;
+    (function (getRoutesTransfer) {
+        /** Path parameters for a route transfer read. */
+        getRoutesTransfer.Params = z
+            .object({
+            id: z
+                .string()
+                .check(z.describe('Route transfer ID (`rtr_…`).'), z.meta({ examples: ['rtr_001785729600000_2ZPE2gvateYEQ0dQslgvkhjx'] })),
+        })
+            .check(z.describe('Path parameters for a route transfer request.'));
+        /** The route transfer resource, returned directly. */
+        getRoutesTransfer.Response = schema.Transfer;
+    })(getRoutesTransfer = schema.getRoutesTransfer || (schema.getRoutesTransfer = {}));
+    /** Schemas for the registerRoutesTransferSourceTransaction operation. */
+    let registerRoutesTransferSourceTransaction;
+    (function (registerRoutesTransferSourceTransaction) {
+        /** Source transaction registration request body. */
+        registerRoutesTransferSourceTransaction.Body = OpenApi.component(z
+            .union([
+            z.strictObject({
+                transactionHash: Schema.hash(`0x${'51'.repeat(32)}`),
+            }),
+            z.strictObject({
+                transactionHashes: z
+                    .array(Schema.hash(`0x${'52'.repeat(32)}`))
+                    .check(z.minLength(1), z.maxLength(maximumSourceTransactionHashes), z.describe('Source transactions produced by the prepared calls.')),
+            }),
+        ])
+            .check(z.describe('Source transactions to verify and register for the transfer.')), 'RegisterRoutesTransferSourceTransactionRequest');
+        /** Path parameters for source transaction registration. */
+        registerRoutesTransferSourceTransaction.Params = getRoutesTransfer.Params;
+        /** The transfer after source transaction registration. */
+        registerRoutesTransferSourceTransaction.Response = schema.Transfer;
+    })(registerRoutesTransferSourceTransaction = schema.registerRoutesTransferSourceTransaction || (schema.registerRoutesTransferSourceTransaction = {}));
+})(schema || (schema = {}));
+const baseChainExample = {
+    addressFormat: 'hex',
+    id: 'eip155:8453',
+    kind: 'evm',
+    name: 'Base',
+};
+const baseUsdcExample = {
+    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+    currency: 'USD',
+    decimals: 6,
+    name: 'USD Coin',
+    standard: 'ERC-20',
+    symbol: 'USDC',
+    tokenKey: 'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+    verified: true,
+};
+const tempoChainExample = {
+    addressFormat: 'hex',
+    id: 'eip155:4217',
+    kind: 'evm',
+    name: 'Tempo',
+};
+const tempoUsdcExample = {
+    address: '0x20c000000000000000000000b9537d11c60e8b50',
+    currency: 'USD',
+    decimals: 6,
+    name: 'Bridged USDC (Stargate)',
+    standard: 'TIP-20',
+    symbol: 'USDC.e',
+    tokenKey: 'eip155:4217/erc20:0x20c000000000000000000000b9537d11c60e8b50',
+    verified: true,
+};
+const tempoFeeExample = {
+    address: '0x20c0000000000000000000000000000000000000',
+    currency: 'USD',
+    decimals: 6,
+    name: 'pathUSD',
+    standard: 'TIP-20',
+    symbol: 'pathUSD',
+    tokenKey: 'eip155:4217/erc20:0x20c0000000000000000000000000000000000000',
+    verified: true,
+};
+const routesTransferExample = {
+    createdAt: '2026-01-01T00:00:00.000Z',
+    destinationAmount: Value.tokenAmount({ baseUnits: '979295', currency: 'USD', decimals: 6 }),
+    destinationAmountMin: Value.tokenAmount({ baseUnits: '974398', currency: 'USD', decimals: 6 }),
+    destinationAmountRequired: Value.tokenAmount({
+        baseUnits: '1000000',
+        currency: 'USD',
+        decimals: 6,
+    }),
+    destinationChain: baseChainExample,
+    destinationToken: baseUsdcExample,
+    fees: [
+        {
+            amount: Value.tokenAmount({ baseUnits: '10000', currency: 'USD', decimals: 6 }),
+            side: 'source',
+            token: tempoFeeExample,
+            type: 'provider',
+        },
+    ],
+    id: 'rtr_001767225600000_2ZPE2gvateYEQ0dQslgvkhjx',
+    method: 'transaction',
+    mode: 'exactSource',
+    provider: { id: 'stargate', name: 'Stargate' },
+    quote: {
+        expiresAt: '2026-01-01T00:01:00.000Z',
+        sampledAt: '2026-01-01T00:00:00.000Z',
+    },
+    recipient: recipientExample,
+    sender: senderExample,
+    sourceAmount: Value.tokenAmount({ baseUnits: '1000000', currency: 'USD', decimals: 6 }),
+    sourceChain: tempoChainExample,
+    sourceToken: tempoUsdcExample,
+    status: 'awaiting-source',
+    subsidize: true,
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    version: 1,
+};
+const registeredRoutesTransferExample = {
+    ...routesTransferExample,
+    sourceTransactionHashes: [`0x${'51'.repeat(32)}`],
+    status: 'processing',
+    updatedAt: '2026-01-01T00:00:20.000Z',
+    version: 2,
+};
+const listRoutesTransfersResponseExample = {
+    data: [routesTransferExample],
+    nextCursor: null,
+};
+const createdRoutesTransferExample = {
+    action: {
+        calls: [
+            {
+                data: AbiFunction.encodeData(stargateApproveExample, [stargatePoolExample, 1000000n]),
+                to: tempoUsdcExample.address,
+                value: '0x0',
+            },
+            {
+                data: AbiFunction.encodeData(stargateApproveExample, [stargateFeeTokenExample, 10000n]),
+                to: tempoFeeExample.address,
+                value: '0x0',
+            },
+            {
+                data: AbiFunction.encodeData(stargateWrapExample, [
+                    tempoFeeExample.address,
+                    senderExample,
+                    10000n,
+                ]),
+                to: stargateFeeTokenExample,
+                value: '0x0',
+            },
+            {
+                data: AbiFunction.encodeData(stargateApproveExample, [stargatePoolExample, 10000n]),
+                to: stargateFeeTokenExample,
+                value: '0x0',
+            },
+            {
+                data: AbiFunction.encodeData(stargateSendExample, [
+                    {
+                        amountLD: 1000000n,
+                        composeMsg: '0x',
+                        dstEid: 30_184,
+                        extraOptions: '0x',
+                        minAmountLD: 974398n,
+                        oftCmd: '0x',
+                        to: Hex.padLeft(recipientExample, 32),
+                    },
+                    { lzTokenFee: 0n, nativeFee: 10000n },
+                    senderExample,
+                ]),
+                to: stargatePoolExample,
+                value: '0x0',
+            },
+        ],
+        type: 'evm:calls',
+    },
+    ...routesTransferExample,
+};
+const unimplementedRoutesTransferResponses = (() => {
+    const responses = OpenApi.responses({
+        errors: {
+            400: { codes: ['body_invalid', 'idempotency_key_required'] },
+            501: {
+                codes: ['not_implemented'],
+                description: 'This route transfer destination is not implemented.',
+            },
+        },
+        success: {
+            description: 'Unused until this destination is implemented.',
+            schema: z.never(),
+        },
+    });
+    const { 200: success, 502: upstream, ...errors } = responses;
+    void success;
+    void upstream;
+    return errors;
+})();
+// Replay the exact successful creation response for 24 hours.
+const idempotencyReplayTtlMs = 86_400_000;
+// Pending claims only cover the bounded provider preparation window.
+const idempotencyPendingTtlMs = 60_000;
+const routesEtag = etag();
+const bodyValidation = {
+    code: 'body_invalid',
+    message: 'Check the request body and try again.',
+};
+const paramValidation = {
+    code: 'param_invalid',
+    message: 'Check the path parameters and try again.',
+};
+/** Mounts durable route transfer routes. */
+export function transfers(options = {}) {
+    return new Hono()
+        .get('/v1/routes/transfers', Auth.policy({ apiKey: { scopes: ['routes:read'] } }), OpenApi.validate('query', schema.listRoutesTransfers.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Lists transfers from newest to oldest.',
+        operationId: 'listRoutesTransfers',
+        responses: OpenApi.responses({
+            errors: {
+                400: { codes: ['query_invalid'] },
+            },
+            success: {
+                description: 'A page of route transfers.',
+                example: listRoutesTransfersResponseExample,
+                schema: schema.listRoutesTransfers.Response,
+            },
+        }),
+        summary: 'List transfers',
+        tags: ['Route Transfers'],
+    }), routesEtag, async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Check the query parameters and try again.',
+            });
+        const owner = Access.owner(c);
+        if (!owner)
+            return Access.unauthorized(c);
+        const db = Db.get(c.get('db'));
+        const { cursor, include, limit, status } = c.req.valid('query');
+        try {
+            // `totalCount` is opt-in and capped (a capped subquery shares the
+            // list filter); run it concurrently with the page list. Best-effort:
+            // a failure omits `meta` rather than failing the page.
+            const countPromise = include.includes('totalCount')
+                ? RoutesTransfers.count(db, owner, { cap: Schema.countCap, status }).catch(() => {
+                    c.set('routesTransferCountFailed', true);
+                    return undefined;
+                })
+                : undefined;
+            // Fetch one extra to detect a further page without a second round-trip.
+            const rows = await RoutesTransfers.listByOwner(db, owner, {
+                cursor,
+                limit: limit + 1,
+                status,
+            });
+            const hasMore = rows.length > limit;
+            const data = (hasMore ? rows.slice(0, limit) : rows).map(RoutesTransfer.toPublic);
+            const nextCursor = hasMore ? (data[data.length - 1]?.id ?? null) : null;
+            const count = countPromise ? await countPromise : undefined;
+            c.header('Cache-Control', Cache.policies.feed);
+            c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key');
+            return c.json(Response.validated(schema.listRoutesTransfers.Response, {
+                data,
+                ...(count !== undefined
+                    ? {
+                        meta: {
+                            totalCountCapped: count > Schema.countCap,
+                            totalCount: Math.min(count, Schema.countCap),
+                        },
+                    }
+                    : {}),
+                nextCursor,
+            }), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/v1/routes/transfers/:id{rtr_[A-Za-z0-9_-]+}', Auth.policy({ apiKey: { scopes: ['routes:read'] } }), OpenApi.validate('param', schema.getRoutesTransfer.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Returns a transfer by ID.',
+        operationId: 'getRoutesTransfer',
+        responses: OpenApi.responses({
+            errors: {
+                400: { codes: ['param_invalid'] },
+                404: {
+                    codes: ['routes_transfer_not_found'],
+                    description: 'No visible route transfer exists for the identifier.',
+                },
+            },
+            success: {
+                description: 'The requested route transfer.',
+                example: routesTransferExample,
+                schema: schema.getRoutesTransfer.Response,
+            },
+        }),
+        summary: 'Get transfer',
+        tags: ['Route Transfers'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'param_invalid',
+                message: 'Check the path parameters and try again.',
+            });
+        const owner = Access.owner(c);
+        if (!owner)
+            return Access.unauthorized(c);
+        const db = Db.get(c.get('db'));
+        const { id } = c.req.valid('param');
+        try {
+            // Ownership filters in SQL, so absent and foreign rows are the same 404.
+            const record = await RoutesTransfers.getOwned(db, owner, id);
+            if (!record)
+                return Response.error(c, {
+                    code: 'routes_transfer_not_found',
+                    message: 'Route transfer not found',
+                    status: 404,
+                });
+            c.header('Cache-Control', Cache.policies.noStore);
+            c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key');
+            return c.json(Response.validated(schema.getRoutesTransfer.Response, RoutesTransfer.toPublic(record)), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .post('/v1/routes/transfers/:id{rtr_[A-Za-z0-9_-]+}/source-transactions', Auth.policy({ apiKey: { scopes: ['routes:write'] } }), OpenApi.validate('param', schema.registerRoutesTransferSourceTransaction.Params, paramValidation), OpenApi.validate('json', schema.registerRoutesTransferSourceTransaction.Body, bodyValidation), OpenApi.describeRoute({
+        description: 'Registers verified source transactions once per organization, environment, and project.',
+        operationId: 'registerRoutesTransferSourceTransaction',
+        responses: OpenApi.responses({
+            errors: {
+                400: {
+                    codes: ['body_invalid', 'param_invalid', 'source_transaction_invalid'],
+                    description: 'The path, body, or submitted source transaction is invalid.',
+                },
+                404: {
+                    codes: ['routes_transfer_not_found'],
+                    description: 'No visible route transfer exists for the identifier.',
+                },
+                409: {
+                    codes: [
+                        'routes_transfer_not_awaiting_source',
+                        'source_transaction_conflict',
+                        'source_transaction_pending',
+                    ],
+                    description: 'The transfer or source transaction cannot be registered yet.',
+                },
+                501: {
+                    codes: ['not_implemented'],
+                    description: 'Source transaction reconciliation is not configured.',
+                },
+                502: {
+                    codes: ['upstream_error'],
+                    description: 'Source verification or reconciliation dispatch failed.',
+                },
+            },
+            success: {
+                description: 'The transfer with its verified source transactions.',
+                example: registeredRoutesTransferExample,
+                schema: schema.registerRoutesTransferSourceTransaction.Response,
+            },
+        }),
+        summary: 'Register source transaction',
+        tags: ['Route Transfers'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, paramValidation);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, bodyValidation);
+        const owner = Access.owner(c);
+        if (!owner)
+            return Access.unauthorized(c);
+        c.header('Cache-Control', Cache.policies.noStore);
+        c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key');
+        const dispatch = options.dispatchTransferReconciliation;
+        if (!dispatch)
+            return Response.error(c, {
+                code: 'not_implemented',
+                message: 'Source transaction reconciliation is not configured',
+                status: 501,
+            });
+        const db = Db.get(c.get('db'));
+        const { id } = c.req.valid('param');
+        const body = c.req.valid('json');
+        const transactionHashes = [
+            ...new Set('transactionHash' in body ? [body.transactionHash] : body.transactionHashes),
+        ];
+        try {
+            const record = await RoutesTransfers.getOwned(db, owner, id);
+            if (!record)
+                return Response.error(c, {
+                    code: 'routes_transfer_not_found',
+                    message: 'Route transfer not found',
+                    status: 404,
+                });
+            if (transactionHashes.every((transactionHash) => record.snapshot.sourceTransactionHashes?.some((candidate) => candidate.toLowerCase() === transactionHash))) {
+                return c.json(Response.validated(schema.registerRoutesTransferSourceTransaction.Response, RoutesTransfer.toPublic(record)), 200);
+            }
+            const provider = c
+                .get('providers')
+                .filter(RoutesProvider.is)
+                .find((candidate) => candidate.id === record.providerId);
+            if (!provider || !RoutesProvider.canVerifySourceTransaction(provider))
+                return Response.error(c, {
+                    code: 'routes_transfer_not_awaiting_source',
+                    message: 'Route transfer does not accept source transactions',
+                    status: 409,
+                });
+            if (record.status !== 'awaiting-source')
+                return Response.error(c, {
+                    code: 'routes_transfer_not_awaiting_source',
+                    message: 'Route transfer is not awaiting a source transaction',
+                    status: 409,
+                });
+            const catalog = await RoutesCatalog.snapshot(c);
+            const destinationChain = catalog.chainsByKey.get(record.snapshot.destinationChain.id);
+            const sourceChain = catalog.chainsByKey.get(record.snapshot.sourceChain.id);
+            const routeConfiguration = catalog.routesByProvider
+                .get(record.providerId)
+                ?.find((candidate) => candidate.route.source.chain.id === record.snapshot.sourceChain.id &&
+                candidate.route.source.address.toLowerCase() ===
+                    record.snapshot.sourceToken.address.toLowerCase() &&
+                candidate.route.destination.chain.id === record.snapshot.destinationChain.id &&
+                candidate.route.destination.address.toLowerCase() ===
+                    record.snapshot.destinationToken.address.toLowerCase())?.configuration;
+            if (!destinationChain || !sourceChain)
+                return Response.error(c, {
+                    code: 'routes_transfer_not_awaiting_source',
+                    message: 'Route transfer route chains are no longer configured',
+                    status: 409,
+                });
+            const attempts = [];
+            const verifications = transactionHashes.map(async (transactionHash) => ({
+                ...(await RoutesProvider.observe(provider, () => provider.verifySourceTransaction({
+                    destinationChain,
+                    providerState: record.providerState ?? undefined,
+                    routeConfiguration,
+                    sourceChain,
+                    transactionHash,
+                    transfer: record.snapshot,
+                }, c.req.raw.signal), {
+                    onAttempt: (attempt) => attempts.push(attempt),
+                    operation: 'verifySourceTransaction',
+                })),
+                transactionHash,
+            }));
+            const candidates = await Promise.all(verifications)
+                .catch(async (cause) => {
+                await Promise.allSettled(verifications);
+                throw cause;
+            })
+                .finally(() => {
+                if (attempts.length > 0)
+                    c.set('routesProviderAttempts', attempts);
+            });
+            const verified = candidates.filter((candidate) => candidate.type === 'verified');
+            if (candidates.some((candidate) => candidate.type === 'invalid'))
+                return Response.error(c, {
+                    code: 'source_transaction_invalid',
+                    message: 'Source transactions do not match the route transfer',
+                    status: 400,
+                });
+            if (candidates.some((candidate) => candidate.type === 'pending'))
+                return Response.error(c, {
+                    code: 'source_transaction_pending',
+                    message: 'A source transaction is not confirmed yet',
+                    status: 409,
+                });
+            const evidence = verified[0];
+            if (!evidence || verified.length !== 1)
+                return Response.error(c, {
+                    code: 'source_transaction_invalid',
+                    message: 'Source transactions do not match the route transfer',
+                    status: 400,
+                });
+            const registered = await RoutesTransfer.registerSourceTransactions(db, {
+                chainId: record.snapshot.sourceChain.id,
+                ...(evidence.destinationAmount
+                    ? {
+                        destinationAmount: Value.tokenAmount({
+                            baseUnits: evidence.destinationAmount,
+                            currency: record.snapshot.destinationToken.currency,
+                            decimals: record.snapshot.destinationToken.decimals,
+                        }),
+                    }
+                    : {}),
+                id: record.id,
+                providerState: evidence.providerState ?? {},
+                transactionHashes: [
+                    evidence.transactionHash,
+                    ...candidates
+                        .filter((candidate) => candidate.type === 'related')
+                        .map((candidate) => candidate.transactionHash),
+                ],
+            });
+            if (registered.type === 'not_found')
+                return Response.error(c, {
+                    code: 'routes_transfer_not_found',
+                    message: 'Route transfer not found',
+                    status: 404,
+                });
+            if (registered.type === 'conflict')
+                return Response.error(c, {
+                    code: 'source_transaction_conflict',
+                    message: 'Source transaction is already assigned to another route transfer',
+                    status: 409,
+                });
+            if (registered.type === 'invalid')
+                return Response.error(c, {
+                    code: 'routes_transfer_not_awaiting_source',
+                    message: 'Route transfer is not awaiting a source transaction',
+                    status: 409,
+                });
+            const sourceRoutes = (() => {
+                if (registered.type !== 'registered')
+                    return undefined;
+                RoutesObservability.recordTransfer(c.get('metrics'), {
+                    previous: record,
+                    record: registered.record,
+                });
+                return RoutesObservability.transferSourceRoutesInterval({
+                    record: registered.record,
+                });
+            })();
+            await Promise.all([
+                registered.type === 'registered'
+                    ? dispatch({ transferId: record.id, type: 'routes:transfer:reconcile' })
+                    : undefined,
+                sourceRoutes && options.recordLifecycleInterval
+                    ? options.recordLifecycleInterval(sourceRoutes)
+                    : undefined,
+                registered.type === 'registered' &&
+                    options.dispatchTransferUpdates &&
+                    registered.references.length > 0
+                    ? options.dispatchTransferUpdates(registered.references)
+                    : undefined,
+            ]);
+            return c.json(Response.validated(schema.registerRoutesTransferSourceTransaction.Response, RoutesTransfer.toPublic(registered.record)), 200);
+        }
+        catch (cause) {
+            return Response.upstream(c, cause);
+        }
+    })
+        .post('/v1/routes/transfers', Auth.policy({ apiKey: { scopes: ['routes:write'] } }), OpenApi.validate('header', schema.createRoutesTransfer.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+    }), OpenApi.validate('json', schema.createRoutesTransfer.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Creates a durable transfer between supported chains, including optional normalized destination subsidies.',
+        operationId: 'createRoutesTransfer',
+        responses: OpenApi.responses({
+            errors: {
+                400: { codes: ['body_invalid', 'idempotency_key_required'] },
+                403: {
+                    codes: [
+                        'billing_past_due',
+                        'billing_required',
+                        'routes_subsidy_limit_exceeded',
+                        'routes_subsidy_not_enabled',
+                    ],
+                    description: 'The requested normalized delivery subsidy is unavailable.',
+                },
+                404: {
+                    codes: ['quote_not_available'],
+                    description: 'No provider can prepare the requested route.',
+                },
+                409: {
+                    codes: ['idempotency_conflict', 'idempotency_in_progress'],
+                    description: 'The Idempotency-Key conflicts with an existing or in-flight request.',
+                },
+                501: {
+                    codes: ['not_implemented'],
+                    description: 'Destination subsidy settlement is not configured.',
+                },
+                502: {
+                    codes: ['upstream_error'],
+                    description: 'No provider succeeded and at least one failed unexpectedly.',
+                },
+                503: {
+                    codes: ['subsidy_inventory_unavailable', 'subsidy_signer_unavailable'],
+                    description: 'Destination subsidy capacity is temporarily unavailable.',
+                },
+            },
+            success: {
+                description: 'The created route transfer with its one-time executable action.',
+                example: createdRoutesTransferExample,
+                schema: schema.createRoutesTransfer.Response,
+            },
+        }),
+        summary: 'Create transfer',
+        tags: ['Route Transfers'],
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Check the request body and try again.',
+            });
+        const principal = Auth.getPrincipal(c);
+        const owner = Access.owner(c);
+        if (!owner || principal?.type !== 'api_key')
+            return Access.unauthorized(c);
+        c.header('Cache-Control', 'no-store');
+        const idempotencyKey = c.req.valid('header')['idempotency-key'];
+        const body = c.req.valid('json');
+        const subsidize = body.subsidize ?? false;
+        if (subsidize && body.mode !== 'exactSource')
+            return Response.error(c, {
+                code: 'body_invalid',
+                message: 'Normalized delivery subsidies require `exactSource` mode.',
+                status: 400,
+            });
+        const db = Db.get(c.get('db'));
+        const identity = {
+            apiKeyId: principal.id,
+            keyHash: Idempotency.inputHash(idempotencyKey),
+            requestHash: Idempotency.inputHash(body),
+        };
+        const claimed = await (async () => {
+            try {
+                return {
+                    claim: await RoutesIdempotency.claim(db, {
+                        ...identity,
+                        irrevocable: false,
+                        operation: RoutesIdempotency.operations.transfer,
+                        orgId: owner.orgId,
+                        ttlMs: idempotencyPendingTtlMs,
+                    }),
+                    type: 'success',
+                };
+            }
+            catch (cause) {
+                if (RoutesIdempotency.isOwnerFenceError(cause))
+                    return { type: 'ownerNotFound' };
+                throw cause;
+            }
+        })();
+        if (claimed.type === 'ownerNotFound')
+            return ownerNotFound(c);
+        const claim = claimed.claim;
+        if (claim.type === 'mismatch')
+            return Response.error(c, {
+                code: 'idempotency_conflict',
+                message: 'This Idempotency-Key was already used with different input.',
+                status: 409,
+            });
+        if (claim.type === 'pending')
+            return Response.error(c, {
+                code: 'idempotency_in_progress',
+                message: 'An equivalent route transfer creation is still running.',
+                status: 409,
+            });
+        if (claim.type === 'replay')
+            return c.json(Response.validated(schema.createRoutesTransfer.Response, JSON.parse(claim.response)), 200);
+        const release = async () => {
+            try {
+                await RoutesIdempotency.release(db, {
+                    apiKeyId: identity.apiKeyId,
+                    createdAt: claim.createdAt,
+                    keyHash: identity.keyHash,
+                });
+            }
+            catch {
+                // The pending claim expires on its own; the response stays authoritative.
+            }
+        };
+        try {
+            if (subsidize && !options.transferSubsidy) {
+                await release();
+                return Response.error(c, {
+                    code: 'not_implemented',
+                    message: 'Destination subsidy settlement is not configured.',
+                    status: 501,
+                });
+            }
+            const subsidyPolicy = subsidize
+                ? await RoutesSubsidy.check(db, {
+                    environment: owner.environment,
+                    orgId: owner.orgId,
+                })
+                : undefined;
+            if (subsidyPolicy?.type === 'denied') {
+                RoutesObservability.recordSubsidyRejection(c.get('metrics'), {
+                    reason: subsidyPolicy.reason,
+                    routesEnvironment: owner.environment,
+                });
+                await release();
+                return Response.error(c, {
+                    code: subsidyPolicy.reason,
+                    message: RoutesSubsidy.denialMessages[subsidyPolicy.reason],
+                    status: 403,
+                });
+            }
+            const attempts = [];
+            const catalog = await RoutesCatalog.snapshot(c);
+            const providers = c.get('providers').filter(RoutesProvider.is);
+            const selected = await RoutesProvider.prepareTransfer({
+                catalog,
+                destinationChain: body.destinationChain ?? `eip155:${c.get('chainId')}`,
+                destinationToken: body.destinationToken,
+                method: 'transaction',
+                mode: body.mode,
+                onAttempt: (attempt) => attempts.push(attempt),
+                provider: body.provider,
+                providers,
+                recipient: body.recipient,
+                sender: body.sender,
+                slippageBps: body.slippageBps,
+                sourceAmount: body.amount,
+                sourceChain: body.sourceChain,
+                sourceToken: body.sourceToken,
+            });
+            if (attempts.length > 0)
+                c.set('routesProviderAttempts', attempts.map(RoutesProvider.formatAttempt));
+            if (!selected) {
+                await release();
+                return quoteNotAvailable(c);
+            }
+            const { candidate, result } = selected;
+            const subsidyDestinationChain = subsidize
+                ? catalog.chainsByKey.get(candidate.destinationChain.id)
+                : undefined;
+            if (subsidize && !subsidyDestinationChain) {
+                await release();
+                return quoteNotAvailable(c);
+            }
+            if (subsidize &&
+                (candidate.sourceChain.id !== `eip155:${c.get('chainId')}` ||
+                    !['eip155:1', 'eip155:8453'].includes(candidate.destinationChain.id))) {
+                await release();
+                return Response.error(c, {
+                    code: 'body_invalid',
+                    message: 'Destination subsidies support Tempo transfers to Base or Ethereum.',
+                    status: 400,
+                });
+            }
+            const destinationAmountRequired = subsidize
+                ? RoutesTransferSubsidy.requiredAmount({
+                    destinationToken: candidate.destinationToken,
+                    sourceAmount: candidate.sourceAmount.amount,
+                    sourceToken: candidate.sourceToken,
+                })
+                : undefined;
+            const subsidyAmount = destinationAmountRequired !== undefined &&
+                destinationAmountRequired > BigInt(result.destinationAmountMin)
+                ? destinationAmountRequired - BigInt(result.destinationAmountMin)
+                : 0n;
+            if (destinationAmountRequired !== undefined &&
+                subsidyPolicy?.type === 'allowed' &&
+                (!RoutesSubsidy.supportsGap(subsidyPolicy, {
+                    amount: subsidyAmount,
+                    destinationToken: candidate.destinationToken,
+                }) ||
+                    (options.transferSubsidy !== undefined &&
+                        !RoutesSubsidy.supportsGap(options.transferSubsidy.policy, {
+                            amount: subsidyAmount,
+                            destinationToken: candidate.destinationToken,
+                        })))) {
+                await release();
+                return Response.error(c, {
+                    code: 'routes_subsidy_limit_exceeded',
+                    message: 'The required destination subsidy exceeds the configured limit.',
+                    status: 403,
+                });
+            }
+            const snapshot = {
+                destinationAmount: Value.tokenAmount({
+                    baseUnits: result.destinationAmount,
+                    currency: candidate.destinationToken.currency,
+                    decimals: candidate.destinationToken.decimals,
+                }),
+                destinationAmountMin: Value.tokenAmount({
+                    baseUnits: result.destinationAmountMin,
+                    currency: candidate.destinationToken.currency,
+                    decimals: candidate.destinationToken.decimals,
+                }),
+                ...(destinationAmountRequired === undefined
+                    ? {}
+                    : {
+                        destinationAmountRequired: Value.tokenAmount({
+                            baseUnits: destinationAmountRequired,
+                            currency: candidate.destinationToken.currency,
+                            decimals: candidate.destinationToken.decimals,
+                        }),
+                    }),
+                destinationChain: candidate.destinationChain,
+                destinationToken: candidate.destinationToken,
+                fees: result.fees.map((fee) => {
+                    const token = fee.token ??
+                        (fee.side === 'source' ? candidate.sourceToken : candidate.destinationToken);
+                    return {
+                        amount: Value.tokenAmount({
+                            baseUnits: fee.amount,
+                            currency: token.currency,
+                            decimals: token.decimals,
+                        }),
+                        side: fee.side,
+                        token,
+                        type: 'provider',
+                    };
+                }),
+                method: 'transaction',
+                mode: body.mode,
+                provider: candidate.provider,
+                quote: { expiresAt: result.expiresAt, sampledAt: result.sampledAt },
+                recipient: selected.recipient,
+                sender: selected.sender,
+                sourceAmount: Value.tokenAmount({
+                    baseUnits: candidate.sourceAmount.amount,
+                    currency: candidate.sourceToken.currency,
+                    decimals: candidate.sourceToken.decimals,
+                }),
+                sourceChain: candidate.sourceChain,
+                sourceToken: candidate.sourceToken,
+                subsidize,
+            };
+            // The transfer row, its version-1 event, and the replay body commit
+            // atomically so a crash cannot leave a claimed key without a replay.
+            const created = await db.transaction(async (tx) => {
+                const input = {
+                    apiKeyId: principal.id,
+                    environment: owner.environment,
+                    orgId: owner.orgId,
+                    projectId: owner.projectId,
+                    providerState: result.correlation || result.providerState
+                        ? {
+                            ...result.correlation,
+                            ...result.providerState,
+                        }
+                        : undefined,
+                    snapshot,
+                };
+                const { record, references } = subsidize && subsidyAmount > 0n && options.transferSubsidy
+                    ? await RoutesTransfer.reserveSubsidyCommitmentIn(tx, input, {
+                        account: options.transferSubsidy.account,
+                        chainId: candidate.destinationChain.id,
+                        check: ({ reservations }) => options.transferSubsidy.check({
+                            amount: subsidyAmount,
+                            chain: subsidyDestinationChain,
+                            recipient: getAddress(selected.recipient),
+                            reservations,
+                            token: getAddress(candidate.destinationToken.address),
+                        }),
+                        subsidyCommitmentAmount: Value.tokenAmount({
+                            baseUnits: subsidyAmount,
+                            currency: candidate.destinationToken.currency,
+                            decimals: candidate.destinationToken.decimals,
+                        }),
+                        tokenAddress: candidate.destinationToken.address,
+                    })
+                    : await RoutesTransfer.createIn(tx, input);
+                const validated = Response.validated(schema.createRoutesTransfer.Response, RoutesTransfer.toCreated(record, result.action));
+                const completion = await RoutesIdempotency.complete(tx, {
+                    apiKeyId: identity.apiKeyId,
+                    createdAt: claim.createdAt,
+                    keyHash: identity.keyHash,
+                    replayTtlMs: idempotencyReplayTtlMs,
+                    response: JSON.stringify(validated),
+                    transferId: record.id,
+                });
+                if (!completion)
+                    throw new IdempotencyLeaseLostError('Route transfer creation lease was lost.');
+                return { record, references, response: validated };
+            });
+            RoutesObservability.recordTransfer(c.get('metrics'), {
+                record: created.record,
+                ...(body.provider === undefined && selected.preparedCount > 1
+                    ? { selection: { bestDestinationAmount: selected.bestDestinationAmount } }
+                    : {}),
+            });
+            if (options.dispatchTransferUpdates && created.references.length > 0)
+                try {
+                    await options.dispatchTransferUpdates(created.references);
+                }
+                catch (cause) {
+                    return Response.upstream(c, cause);
+                }
+            return c.json(created.response, 200);
+        }
+        catch (cause) {
+            await release();
+            if (cause instanceof RoutesProvider.InvalidAmountError)
+                return Response.error(c, { code: 'body_invalid', message: 'Invalid `amount`.', status: 400 }); // prettier-ignore
+            if (cause instanceof RoutesProvider.InvalidRecipientAddressError)
+                return Response.error(c, { code: 'body_invalid', message: 'Invalid `recipient`.', status: 400 }); // prettier-ignore
+            if (cause instanceof RoutesProvider.InvalidSenderAddressError)
+                return Response.error(c, { code: 'body_invalid', message: 'Invalid `sender`.', status: 400 }); // prettier-ignore
+            if (cause instanceof RoutesProvider.UnsupportedProviderError)
+                return Response.error(c, { code: 'body_invalid', message: 'Unsupported `provider`.', status: 400 }); // prettier-ignore
+            if (cause instanceof RoutesTransferSubsidy.UnsupportedAmountError ||
+                cause instanceof RoutesTransferSubsidy.UnsupportedTokenError)
+                return Response.error(c, {
+                    code: 'body_invalid',
+                    message: 'Normalized delivery requires compatible USD token amounts.',
+                    status: 400,
+                });
+            if (cause instanceof RoutesProvider.UnsupportedDestinationChainError ||
+                cause instanceof RoutesProvider.UnsupportedSourceChainError)
+                return quoteNotAvailable(c);
+            if (cause instanceof RoutesTransfer.QuoteExpiredError)
+                return quoteNotAvailable(c);
+            if (cause instanceof RoutesProvider.ProviderQuoteError) {
+                if (cause.routesProviderAttempts.length > 0)
+                    c.set('routesProviderAttempts', cause.routesProviderAttempts);
+                if (cause.providerFailure)
+                    c.set('providerFailure', cause.providerFailure);
+                if (cause.providerFailures)
+                    c.set('providerFailures', cause.providerFailures);
+                return Response.error(c, {
+                    code: 'upstream_error',
+                    message: 'No route provider could prepare the transfer.',
+                    status: 502,
+                });
+            }
+            if (cause instanceof RoutesTransferSubsidy.BalanceUnavailableError)
+                return Response.error(c, {
+                    code: 'subsidy_inventory_unavailable',
+                    message: 'Tempo lacks enough destination token inventory or native gas.',
+                    status: 503,
+                });
+            if (cause instanceof RoutesTransferSubsidy.InventoryUpstreamError)
+                return Response.upstream(c, cause);
+            if (cause instanceof RoutesTransfer.OrganizationNotFoundError ||
+                RoutesIdempotency.isOwnerFenceError(cause))
+                return ownerNotFound(c);
+            if (cause instanceof RoutesTransfer.SubsidySignerBlockedError)
+                return Response.error(c, {
+                    code: 'subsidy_signer_unavailable',
+                    message: 'Destination subsidy settlement is temporarily unavailable.',
+                    status: 503,
+                });
+            throw cause;
+        }
+    })
+        .post('/v1/routes/transfers/vault', Auth.policy({ apiKey: { scopes: ['routes:write'] } }), OpenApi.validate('header', schema.createRoutesTransferVault.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+    }), OpenApi.validate('json', schema.createRoutesTransferVault.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Earn vault.',
+        operationId: 'createRoutesTransferVault',
+        responses: unimplementedRoutesTransferResponses,
+        summary: 'Create transfer into vault',
+        tags: ['Route Transfers'],
+    }), (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Check the request body and try again.',
+            });
+        c.header('Cache-Control', 'no-store');
+        return Response.error(c, {
+            code: 'not_implemented',
+            message: 'Vault route transfers are not implemented.',
+            status: 501,
+        });
+    })
+        .post('/v1/routes/transfers/zone', Auth.policy({ apiKey: { scopes: ['routes:write'] } }), OpenApi.validate('header', schema.createRoutesTransferZone.Headers, {
+        code: 'idempotency_key_required',
+        message: 'Route transfer creation requires an `Idempotency-Key` header.',
+    }), OpenApi.validate('json', schema.createRoutesTransferZone.Body, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+    }), OpenApi.describeRoute({
+        description: 'Creates a transfer into a Tempo Zone.',
+        operationId: 'createRoutesTransferZone',
+        responses: unimplementedRoutesTransferResponses,
+        summary: 'Create transfer into zone',
+        tags: ['Route Transfers'],
+    }), (c) => {
+        if (Auth.narrowAccess)
+            return Auth.accessError(c);
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'body_invalid',
+                message: 'Check the request body and try again.',
+            });
+        c.header('Cache-Control', 'no-store');
+        return Response.error(c, {
+            code: 'not_implemented',
+            message: 'Zone route transfers are not implemented.',
+            status: 501,
+        });
+    });
+}
+function quoteNotAvailable(c) {
+    return Response.error(c, {
+        code: 'quote_not_available',
+        message: 'No provider can prepare the requested provider route.',
+        status: 404,
+    });
+}
+function ownerNotFound(c) {
+    return Response.error(c, {
+        code: 'api_key_forbidden',
+        message: 'API key organization no longer exists.',
+        status: 403,
+    });
+}
+class IdempotencyLeaseLostError extends Error {
+    name = 'Routes.IdempotencyLeaseLostError';
+}
+//# sourceMappingURL=transfers.js.map