tapimo 0.7.1 → 0.7.2

package/dist/internal/funding/Deposit.d.ts

@@ -0,0 +1,366 @@
+import * as z from 'zod/mini';
+import type * as Db from '../../db/Db.js';
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js';
+import * as Schema from '../Schema.js';
+/**
+ * Public funding deposit statuses:
+ *
+ * - `action-required`: Automatic processing stopped and requires recovery or operator action.
+ * - `bridging`: The provider is moving the source funds to Tempo.
+ * - `completed`: The full required amount reached the recipient.
+ * - `detected`: The provider reported a source transfer that awaits chain verification.
+ * - `refunded`: A verified refund reached the configured refund address.
+ * - `refunding`: A refund started but is not yet verified.
+ * - `settling`: Tempo is completing the required destination amount after provider delivery.
+ */
+export declare const statuses: readonly ['action-required', 'bridging', 'completed', 'detected', 'refunded', 'refunding', 'settling'];
+/** Lifecycle status of a detected funding deposit. */
+export type Status = (typeof statuses)[number];
+/** Statuses that never change after verified chain evidence. */
+export declare const terminalStatuses: readonly ["completed", "refunded"];
+/**
+ * Customer-safe codes explaining a deposit that needs attention:
+ *
+ * - `delivery_failed`: The provider or Tempo could not complete destination delivery.
+ * - `delivery_liquidity_unavailable`: The selected strategy cannot obtain the required destination amount.
+ * - `manual_recovery_required`: Automatic processing cannot safely continue.
+ * - `refund_failed`: The provider could not refund the source funds.
+ * - `source_amount_not_supported`: The source amount is outside the supported limits.
+ * - `source_token_mismatch`: The transfer used a token other than the configured source token.
+ * - `subsidy_balance_unavailable`: Tempo lacks enough pathUSD for the required subsidy.
+ * - `subsidy_failed`: Tempo could not deliver the required subsidy.
+ */
+export declare const statusReasonCodes: readonly ['delivery_failed', 'delivery_liquidity_unavailable', 'manual_recovery_required', 'refund_failed', 'source_amount_not_supported', 'source_token_mismatch', 'subsidy_balance_unavailable', 'subsidy_failed'];
+/** Stable customer-safe deposit status reason code. */
+export type StatusReasonCode = (typeof statusReasonCodes)[number];
+/** Bounded private state used by deposit reconciliation. */
+export type PrivateState = Record<string, unknown>;
+/** Returns whether a deposit status is terminal. */
+export declare function isTerminal(status: Status): boolean;
+/** Returns whether the lifecycle allows moving between deposit statuses. */
+export declare function canTransition(from: Status, to: Status): boolean;
+/** Generates a funding deposit id (`fdp_…`, lexically time-ordered). */
+export declare function generateId(now?: Date): string;
+/** Zod schemas owned by the funding deposit resource. */
+export declare namespace schema {
+    /** Funding deposit lifecycle status. */
+    const Status: z.ZodMiniEnum<{
+        "action-required": "action-required";
+        bridging: "bridging";
+        completed: "completed";
+        detected: "detected";
+        refunded: "refunded";
+        refunding: "refunding";
+        settling: "settling";
+    }>;
+    /** Customer-safe explanation of a deposit status. */
+    const StatusReason: z.ZodMiniObject<{
+        code: z.ZodMiniEnum<{
+            delivery_failed: "delivery_failed";
+            delivery_liquidity_unavailable: "delivery_liquidity_unavailable";
+            manual_recovery_required: "manual_recovery_required";
+            refund_failed: "refund_failed";
+            source_amount_not_supported: "source_amount_not_supported";
+            source_token_mismatch: "source_token_mismatch";
+            subsidy_balance_unavailable: "subsidy_balance_unavailable";
+            subsidy_failed: "subsidy_failed";
+        }>;
+        message: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+    /** Public fields persisted as the deposit snapshot. */
+    const Snapshot: z.ZodMiniObject<{
+        depositAddressId: z.ZodMiniString<string>;
+        destinationAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        destinationAmountRequired: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        destinationChain: z.ZodMiniObject<{
+            addressFormat: z.ZodMiniEnum<{
+                base58: "base58";
+                base58check: "base58check";
+                hex: "hex";
+            }>;
+            id: z.ZodMiniString<string>;
+            kind: z.ZodMiniEnum<{
+                evm: "evm";
+                solana: "solana";
+                tron: "tron";
+            }>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        destinationToken: z.ZodMiniObject<{
+            address: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            name: z.ZodMiniString<string>;
+            standard: z.ZodMiniString<string>;
+            symbol: z.ZodMiniString<string>;
+            tokenKey: z.ZodMiniString<string>;
+            verified: z.ZodMiniBoolean<boolean>;
+        }, z.core.$strip>;
+        destinationTransactionHashes: z.ZodMiniOptional<z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>>;
+        provider: z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        recipient: z.ZodMiniString<string>;
+        refundAddress: z.ZodMiniString<string>;
+        refundAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        refundTransactionHashes: z.ZodMiniOptional<z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>>;
+        sender: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        sourceAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        sourceChain: z.ZodMiniObject<{
+            addressFormat: z.ZodMiniEnum<{
+                base58: "base58";
+                base58check: "base58check";
+                hex: "hex";
+            }>;
+            id: z.ZodMiniString<string>;
+            kind: z.ZodMiniEnum<{
+                evm: "evm";
+                solana: "solana";
+                tron: "tron";
+            }>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        sourceToken: z.ZodMiniObject<{
+            address: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            name: z.ZodMiniString<string>;
+            standard: z.ZodMiniString<string>;
+            symbol: z.ZodMiniString<string>;
+            tokenKey: z.ZodMiniString<string>;
+            verified: z.ZodMiniBoolean<boolean>;
+        }, z.core.$strip>;
+        sourceTransactionHashes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>;
+    }, z.core.$strip>;
+    /** One detected funding deposit. */
+    const FundingDeposit: z.ZodMiniObject<{
+        createdAt: z.ZodMiniString<string>;
+        depositAddressId: z.ZodMiniString<string>;
+        destinationAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        destinationAmountRequired: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        destinationChain: z.ZodMiniObject<{
+            addressFormat: z.ZodMiniEnum<{
+                base58: "base58";
+                base58check: "base58check";
+                hex: "hex";
+            }>;
+            id: z.ZodMiniString<string>;
+            kind: z.ZodMiniEnum<{
+                evm: "evm";
+                solana: "solana";
+                tron: "tron";
+            }>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        destinationToken: z.ZodMiniObject<{
+            address: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            name: z.ZodMiniString<string>;
+            standard: z.ZodMiniString<string>;
+            symbol: z.ZodMiniString<string>;
+            tokenKey: z.ZodMiniString<string>;
+            verified: z.ZodMiniBoolean<boolean>;
+        }, z.core.$strip>;
+        destinationTransactionHashes: z.ZodMiniOptional<z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>>;
+        id: z.ZodMiniString<string>;
+        provider: z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        recipient: z.ZodMiniString<string>;
+        refundAddress: z.ZodMiniString<string>;
+        refundAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        refundTransactionHashes: z.ZodMiniOptional<z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>>;
+        sender: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        sourceAmount: z.ZodMiniOptional<z.ZodMiniObject<{
+            baseUnits: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            formatted: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        sourceChain: z.ZodMiniObject<{
+            addressFormat: z.ZodMiniEnum<{
+                base58: "base58";
+                base58check: "base58check";
+                hex: "hex";
+            }>;
+            id: z.ZodMiniString<string>;
+            kind: z.ZodMiniEnum<{
+                evm: "evm";
+                solana: "solana";
+                tron: "tron";
+            }>;
+            name: z.ZodMiniString<string>;
+        }, z.core.$strip>;
+        sourceToken: z.ZodMiniObject<{
+            address: z.ZodMiniString<string>;
+            currency: z.ZodMiniString<string>;
+            decimals: z.ZodMiniNumber<number>;
+            name: z.ZodMiniString<string>;
+            standard: z.ZodMiniString<string>;
+            symbol: z.ZodMiniString<string>;
+            tokenKey: z.ZodMiniString<string>;
+            verified: z.ZodMiniBoolean<boolean>;
+        }, z.core.$strip>;
+        sourceTransactionHashes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniString<string>>>;
+        sourceTransferIndex: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+        status: z.ZodMiniEnum<{
+            "action-required": "action-required";
+            bridging: "bridging";
+            completed: "completed";
+            detected: "detected";
+            refunded: "refunded";
+            refunding: "refunding";
+            settling: "settling";
+        }>;
+        statusReason: z.ZodMiniOptional<z.ZodMiniObject<{
+            code: z.ZodMiniEnum<{
+                delivery_failed: "delivery_failed";
+                delivery_liquidity_unavailable: "delivery_liquidity_unavailable";
+                manual_recovery_required: "manual_recovery_required";
+                refund_failed: "refund_failed";
+                source_amount_not_supported: "source_amount_not_supported";
+                source_token_mismatch: "source_token_mismatch";
+                subsidy_balance_unavailable: "subsidy_balance_unavailable";
+                subsidy_failed: "subsidy_failed";
+            }>;
+            message: z.ZodMiniString<string>;
+        }, z.core.$strip>>;
+        updatedAt: z.ZodMiniString<string>;
+    }, z.core.$strip>;
+}
+/** Stored public snapshot of a funding deposit. */
+export type Snapshot = z.output<typeof schema.Snapshot>;
+/** Customer-safe funding deposit status reason. */
+export type StatusReason = z.output<typeof schema.StatusReason>;
+/** A funding deposit as returned by reads. */
+export type Public = z.output<typeof schema.FundingDeposit>;
+/** Creates a durable record for one provider-observed source transaction. */
+export declare function create(db: Db.Db, input: create.Input): Promise<FundingDeposits.Record>;
+export declare namespace create {
+    /** Fields required to persist a provider-observed deposit. */
+    type Input = {
+        /** Deposit id override for deterministic tests. */
+        id?: string | undefined;
+        /** Detection time override for deterministic tests. */
+        now?: Date | undefined;
+        /** Provider output amount confirmed on Tempo. */
+        providerOutputAmount?: z.output<typeof Schema.TokenAmount> | undefined;
+        /** Provider request that reported the source transaction. */
+        providerRequestId: string;
+        /** Private provider request identifiers. */
+        providerRequestIds?: readonly string[] | undefined;
+        /** Bounded private provider state. */
+        providerState?: PrivateState | undefined;
+        /** Provider-leg transaction references. */
+        providerTransactionHashes?: readonly string[] | undefined;
+        /** Deposit position within the provider request. */
+        providerTransferIndex?: number | undefined;
+        /** Bounded private retry state. */
+        retryState?: PrivateState | undefined;
+        /** Persisted settlement transaction bytes for exactly-once rebroadcast. */
+        settlementTransaction?: string | undefined;
+        /** Persisted settlement transaction hash. */
+        settlementTransactionHash?: string | undefined;
+        /** Public deposit snapshot. */
+        snapshot: Snapshot;
+        /** Source transaction containing the deposited transfer. */
+        sourceTransactionHash: string;
+        /** Verified transfer position within the source transaction. */
+        sourceTransferIndex?: number | undefined;
+        /** Destination token amount supplied by Tempo. */
+        subsidyAmount?: z.output<typeof Schema.TokenAmount> | undefined;
+        /** Tempo gas paid for settlement, in base units. */
+        tempoGasPaid?: string | undefined;
+    };
+}
+/** Applies a version-guarded material deposit change. */
+export declare function transition(db: Db.Db, options: transition.Options): Promise<transition.Result>;
+export declare namespace transition {
+    /** Fields describing a material deposit change. */
+    type Options = {
+        /** Version that the change was computed against. */
+        expectedVersion: number;
+        /** Funding deposit id (`fdp_…`). */
+        id: string;
+        /** Provider output amount confirmed on Tempo. */
+        providerOutputAmount?: z.output<typeof Schema.TokenAmount> | undefined;
+        /** Private provider request identifiers. */
+        providerRequestIds?: readonly string[] | undefined;
+        /** Bounded private provider state. */
+        providerState?: PrivateState | undefined;
+        /** Provider-leg transaction references. */
+        providerTransactionHashes?: readonly string[] | undefined;
+        /** Bounded private retry state. */
+        retryState?: PrivateState | undefined;
+        /** Persisted settlement transaction bytes for exactly-once rebroadcast. */
+        settlementTransaction?: string | undefined;
+        /** Persisted settlement transaction hash. */
+        settlementTransactionHash?: string | undefined;
+        /** Replacement public snapshot. */
+        snapshot?: Snapshot | undefined;
+        /** Verified transfer position within the source transaction. */
+        sourceTransferIndex?: number | undefined;
+        /** New lifecycle status. */
+        status?: Status | undefined;
+        /** Customer-safe reason attached to the current status. */
+        statusReason?: StatusReason | undefined;
+        /** Destination token amount supplied by Tempo. */
+        subsidyAmount?: z.output<typeof Schema.TokenAmount> | undefined;
+        /** Tempo gas paid for settlement, in base units. */
+        tempoGasPaid?: string | undefined;
+    };
+    /** Outcome of a guarded deposit transition. */
+    type Result = {
+        record: FundingDeposits.Record;
+        type: 'applied';
+    } | {
+        current: FundingDeposits.Record;
+        type: 'invalid';
+    } | {
+        current: FundingDeposits.Record;
+        type: 'stale';
+    } | {
+        type: 'not_found';
+    };
+}
+/** Serializes a stored deposit to the public read shape. */
+export declare function toPublic(record: FundingDeposits.Record): Public;
+//# sourceMappingURL=Deposit.d.ts.map

package/dist/internal/funding/Deposit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Deposit.d.ts","sourceRoot":"","sources":["../../../src/internal/funding/Deposit.ts"],"names":[],"mappings":"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"}

package/dist/internal/funding/Deposit.js

@@ -0,0 +1,286 @@
+import * as z from 'zod/mini';
+import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js';
+import * as FundingDeposits from '../../db/tables/fundingDeposits.js';
+import * as Id from '../Id.js';
+import * as Schema from '../Schema.js';
+import * as Provider from './Provider.js';
+/**
+ * Public funding deposit statuses:
+ *
+ * - `action-required`: Automatic processing stopped and requires recovery or operator action.
+ * - `bridging`: The provider is moving the source funds to Tempo.
+ * - `completed`: The full required amount reached the recipient.
+ * - `detected`: The provider reported a source transfer that awaits chain verification.
+ * - `refunded`: A verified refund reached the configured refund address.
+ * - `refunding`: A refund started but is not yet verified.
+ * - `settling`: Tempo is completing the required destination amount after provider delivery.
+ */
+export const statuses = [
+    'action-required',
+    'bridging',
+    'completed',
+    'detected',
+    'refunded',
+    'refunding',
+    'settling',
+];
+/** Statuses that never change after verified chain evidence. */
+export const terminalStatuses = ['completed', 'refunded'];
+/**
+ * Customer-safe codes explaining a deposit that needs attention:
+ *
+ * - `delivery_failed`: The provider or Tempo could not complete destination delivery.
+ * - `delivery_liquidity_unavailable`: The selected strategy cannot obtain the required destination amount.
+ * - `manual_recovery_required`: Automatic processing cannot safely continue.
+ * - `refund_failed`: The provider could not refund the source funds.
+ * - `source_amount_not_supported`: The source amount is outside the supported limits.
+ * - `source_token_mismatch`: The transfer used a token other than the configured source token.
+ * - `subsidy_balance_unavailable`: Tempo lacks enough pathUSD for the required subsidy.
+ * - `subsidy_failed`: Tempo could not deliver the required subsidy.
+ */
+export const statusReasonCodes = [
+    'delivery_failed',
+    'delivery_liquidity_unavailable',
+    'manual_recovery_required',
+    'refund_failed',
+    'source_amount_not_supported',
+    'source_token_mismatch',
+    'subsidy_balance_unavailable',
+    'subsidy_failed',
+];
+const transitions = {
+    'action-required': ['bridging', 'completed', 'refunded', 'refunding', 'settling'],
+    bridging: ['action-required', 'completed', 'refunding', 'settling'],
+    completed: [],
+    detected: ['action-required', 'bridging', 'completed', 'refunding', 'settling'],
+    refunded: [],
+    refunding: ['action-required', 'refunded'],
+    settling: ['action-required', 'completed', 'refunding'],
+};
+/** Returns whether a deposit status is terminal. */
+export function isTerminal(status) {
+    return terminalStatuses.includes(status);
+}
+/** Returns whether the lifecycle allows moving between deposit statuses. */
+export function canTransition(from, to) {
+    return transitions[from].includes(to);
+}
+/** Generates a funding deposit id (`fdp_…`, lexically time-ordered). */
+export function generateId(now = new Date()) {
+    return Id.generateSortable('fdp', now);
+}
+/** Zod schemas owned by the funding deposit resource. */
+export var schema;
+(function (schema) {
+    const transactionHashes = (description) => z
+        .readonly(z.array(z.string()))
+        .check(z.describe(description), z.meta({ examples: [[`0x${'aa'.repeat(32)}`]] }));
+    /** Funding deposit lifecycle status. */
+    schema.Status = z
+        .enum(statuses)
+        .check(z.describe('Current delivery status of the deposit.'), z.meta({ examples: ['detected'] }));
+    /** Customer-safe explanation of a deposit status. */
+    schema.StatusReason = z
+        .object({
+        code: z
+            .enum(statusReasonCodes)
+            .check(z.describe('Stable machine-readable reason code.'), z.meta({ examples: ['delivery_liquidity_unavailable'] })),
+        message: z
+            .string()
+            .check(z.describe('Human-readable explanation of the current status.'), z.meta({ examples: ['The required destination amount is not currently available.'] })),
+    })
+        .check(z.describe('Why a deposit needs attention or recovery.'));
+    /** Public fields persisted as the deposit snapshot. */
+    schema.Snapshot = z
+        .object({
+        depositAddressId: z
+            .string()
+            .check(z.regex(/^fda_[A-Za-z0-9_-]+$/), z.describe('Funding deposit address that detected the transfer.'), z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] })),
+        destinationAmount: z.optional(Schema.TokenAmount),
+        destinationAmountRequired: z
+            .optional(Schema.TokenAmount)
+            .check(z.describe('Destination amount required for completion, when known.')),
+        destinationChain: Provider.schema.ChainRef,
+        destinationToken: Provider.schema.TokenRef,
+        destinationTransactionHashes: z.optional(transactionHashes('Verified destination transaction references.')),
+        provider: Provider.schema.ProviderRef,
+        recipient: z
+            .string()
+            .check(z.regex(/^0x[0-9a-fA-F]{40}$/), z.describe('Tempo account that receives the completed deposit.'), z.meta({ examples: [`0x${'11'.repeat(20)}`] })),
+        refundAddress: z
+            .string()
+            .check(z.describe('Source-chain address that receives a refund.'), z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] })),
+        refundAmount: z.optional(Schema.TokenAmount),
+        refundTransactionHashes: z.optional(transactionHashes('Verified source-chain refund transaction references.')),
+        sender: z
+            .optional(z.string())
+            .check(z.describe('Observed source-chain sender, when available.'), z.meta({ examples: ['TJRabPrwbZy45sbavfcjinPJC18kjpRTv8'] })),
+        sourceAmount: z
+            .optional(Schema.TokenAmount)
+            .check(z.describe('Verified source amount, when source evidence is available.')),
+        sourceChain: Provider.schema.ChainRef,
+        sourceToken: Provider.schema.TokenRef,
+        sourceTransactionHashes: transactionHashes('Provider-observed source transaction references.'),
+    })
+        .check(z.describe('Public route, provider observations, and verified evidence for one deposit.'));
+    /** One detected funding deposit. */
+    schema.FundingDeposit = z
+        .object({
+        createdAt: z
+            .string()
+            .check(z.describe('When the deposit was first detected (ISO 8601).'), z.meta({ examples: ['2026-08-04T00:01:00.000Z'] })),
+        depositAddressId: schema.Snapshot.shape.depositAddressId,
+        destinationAmount: schema.Snapshot.shape.destinationAmount,
+        destinationAmountRequired: schema.Snapshot.shape.destinationAmountRequired,
+        destinationChain: schema.Snapshot.shape.destinationChain,
+        destinationToken: schema.Snapshot.shape.destinationToken,
+        destinationTransactionHashes: schema.Snapshot.shape.destinationTransactionHashes,
+        id: z
+            .string()
+            .check(z.regex(/^fdp_[A-Za-z0-9_-]+$/), z.describe('Funding deposit id (`fdp_…`).'), z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] })),
+        provider: schema.Snapshot.shape.provider,
+        recipient: schema.Snapshot.shape.recipient,
+        refundAddress: schema.Snapshot.shape.refundAddress,
+        refundAmount: schema.Snapshot.shape.refundAmount,
+        refundTransactionHashes: schema.Snapshot.shape.refundTransactionHashes,
+        sender: schema.Snapshot.shape.sender,
+        sourceAmount: schema.Snapshot.shape.sourceAmount,
+        sourceChain: schema.Snapshot.shape.sourceChain,
+        sourceToken: schema.Snapshot.shape.sourceToken,
+        sourceTransactionHashes: schema.Snapshot.shape.sourceTransactionHashes,
+        sourceTransferIndex: z
+            .optional(z.number().check(z.int(), z.minimum(0)))
+            .check(z.describe('Verified transfer position within the source transaction.'), z.meta({ examples: [0] })),
+        status: schema.Status,
+        statusReason: z.optional(schema.StatusReason),
+        updatedAt: z
+            .string()
+            .check(z.describe('When the deposit last materially changed (ISO 8601).'), z.meta({ examples: ['2026-08-04T00:02:00.000Z'] })),
+    })
+        .check(z.describe('One detected deposit and its delivery status.'));
+})(schema || (schema = {}));
+/** Creates a durable record for one provider-observed source transaction. */
+export async function create(db, input) {
+    const now = input.now ?? new Date();
+    const depositAddressId = schema.Snapshot.shape.depositAddressId.parse(input.snapshot.depositAddressId);
+    const address = await FundingDepositAddresses.get(db, depositAddressId);
+    if (!address)
+        throw new DepositAddressNotFoundError(depositAddressId);
+    const snapshot = schema.Snapshot.parse({
+        ...input.snapshot,
+        depositAddressId: address.id,
+        destinationChain: address.snapshot.destinationChain,
+        destinationToken: address.snapshot.destinationToken,
+        provider: address.snapshot.provider,
+        recipient: address.snapshot.recipient,
+        refundAddress: address.snapshot.refundAddress,
+        sourceChain: address.snapshot.sourceChain,
+        sourceToken: address.snapshot.sourceToken,
+        sourceTransactionHashes: [input.sourceTransactionHash],
+    });
+    return FundingDeposits.insert(db, {
+        createdAt: now.toISOString(),
+        depositAddressId: snapshot.depositAddressId,
+        environment: address.environment,
+        id: input.id ?? generateId(now),
+        orgId: address.orgId,
+        projectId: address.projectId,
+        providerOutputAmount: input.providerOutputAmount ?? null,
+        providerOutputToken: address.providerOutputToken,
+        providerRequestId: input.providerRequestId,
+        providerRequestIds: [
+            ...new Set([input.providerRequestId, ...(input.providerRequestIds ?? [])]),
+        ],
+        providerState: input.providerState ?? null,
+        providerTransactionHashes: input.providerTransactionHashes ?? [],
+        providerTransferIndex: input.providerTransferIndex ?? 0,
+        retryState: input.retryState ?? null,
+        settlementTransaction: input.settlementTransaction ?? null,
+        settlementTransactionHash: input.settlementTransactionHash ?? null,
+        snapshot,
+        sourceChainId: snapshot.sourceChain.id,
+        sourceTransactionHash: input.sourceTransactionHash,
+        sourceTransferIndex: input.sourceTransferIndex ?? null,
+        status: 'detected',
+        statusReason: null,
+        subsidyAmount: input.subsidyAmount ?? null,
+        tempoGasPaid: input.tempoGasPaid ?? null,
+        updatedAt: now.toISOString(),
+        version: 1,
+    });
+}
+/** Applies a version-guarded material deposit change. */
+export async function transition(db, options) {
+    const current = await FundingDeposits.get(db, options.id);
+    if (!current)
+        return { type: 'not_found' };
+    if (current.version !== options.expectedVersion)
+        return { current, type: 'stale' };
+    const status = options.status ?? current.status;
+    if (status !== current.status && !canTransition(current.status, status))
+        return { current, type: 'invalid' };
+    const snapshot = options.snapshot === undefined
+        ? current.snapshot
+        : schema.Snapshot.parse({
+            ...options.snapshot,
+            depositAddressId: current.snapshot.depositAddressId,
+            destinationAmountRequired: current.snapshot.destinationAmountRequired ??
+                options.snapshot.destinationAmountRequired,
+            destinationChain: current.snapshot.destinationChain,
+            destinationToken: current.snapshot.destinationToken,
+            provider: current.snapshot.provider,
+            recipient: current.snapshot.recipient,
+            refundAddress: current.snapshot.refundAddress,
+            sender: current.snapshot.sender ?? options.snapshot.sender,
+            sourceAmount: current.snapshot.sourceAmount ?? options.snapshot.sourceAmount,
+            sourceChain: current.snapshot.sourceChain,
+            sourceToken: current.snapshot.sourceToken,
+            sourceTransactionHashes: current.snapshot.sourceTransactionHashes,
+        });
+    const updated = await FundingDeposits.update(db, {
+        expectedVersion: options.expectedVersion,
+        id: options.id,
+        providerOutputAmount: options.providerOutputAmount ?? current.providerOutputAmount,
+        providerRequestId: current.providerRequestId,
+        providerRequestIds: options.providerRequestIds ?? current.providerRequestIds,
+        providerState: options.providerState ?? current.providerState,
+        providerTransactionHashes: options.providerTransactionHashes ?? current.providerTransactionHashes,
+        providerTransferIndex: current.providerTransferIndex,
+        retryState: options.retryState ?? current.retryState,
+        settlementTransaction: options.settlementTransaction ?? current.settlementTransaction,
+        settlementTransactionHash: options.settlementTransactionHash ?? current.settlementTransactionHash,
+        snapshot,
+        sourceTransferIndex: current.sourceTransferIndex ?? options.sourceTransferIndex ?? null,
+        status,
+        statusReason: options.statusReason ?? (status === current.status ? current.statusReason : null),
+        subsidyAmount: options.subsidyAmount ?? current.subsidyAmount,
+        tempoGasPaid: options.tempoGasPaid ?? current.tempoGasPaid,
+        updatedAt: new Date().toISOString(),
+        version: current.version + 1,
+    });
+    if (updated)
+        return { record: updated, type: 'applied' };
+    const latest = await FundingDeposits.get(db, options.id);
+    return latest ? { current: latest, type: 'stale' } : { type: 'not_found' };
+}
+/** Serializes a stored deposit to the public read shape. */
+export function toPublic(record) {
+    return schema.FundingDeposit.parse({
+        ...record.snapshot,
+        createdAt: record.createdAt,
+        id: record.id,
+        ...(record.sourceTransferIndex === null
+            ? {}
+            : { sourceTransferIndex: record.sourceTransferIndex }),
+        status: record.status,
+        ...(record.statusReason === null ? {} : { statusReason: record.statusReason }),
+        updatedAt: record.updatedAt,
+    });
+}
+class DepositAddressNotFoundError extends Error {
+    name = 'FundingDeposit.DepositAddressNotFoundError';
+    constructor(id) {
+        super(`Funding deposit address ${id} not found`);
+    }
+}
+//# sourceMappingURL=Deposit.js.map