@anywalletkit/protocol-swap2-omniston 0.0.0-stage → 0.2.2

package/dist/provider.d.cts

@@ -0,0 +1,590 @@
+import { CrossChainProvider } from '@anywalletkit/protocol-swap2-core/types';
+
+/** Omniston's `SwapChunk.protocol` names and the layout each one builds. */
+declare const TON_SWAP_PROTOCOL_LAYOUTS: Readonly<Record<string, "stonfi-v1" | "stonfi-v2" | "dedust-v1" | "dedust-v2">>;
+/** A chain fact the payload depends on; checked by `validateTonSwapLeg`. A
+ *  jetton is named by its master address; `null` is native GRAM. */
+type TonSwapLeg = {
+    kind: "stonfi-router";
+    version: 1 | 2;
+    /** The router that executes this hop; null = the owner of `proxyTonWallet`. */
+    router: string | null;
+    /** Native input: the router's proxy-TON wallet the message pays into. */
+    proxyTonWallet?: string;
+    /** The router's wallet the hop asks for — must be the router's wallet of `outputJetton`
+     *  (of a proxy-TON master when the output is native). */
+    askWallet: string;
+    inputJetton: string | null;
+    outputJetton: string | null;
+} | {
+    kind: "dedust-pool";
+    version: 1 | 2;
+    pool: string;
+    inputJetton: string | null;
+    outputJetton: string | null;
+};
+interface TonSwapCheckInput {
+    /** The built message's body (BoC hex) and destination. */
+    payloadHex: string;
+    targetAddress: string;
+    /** Value attached to the message, nanoTON. */
+    sendAmount: bigint;
+    /** The trader's wallet (signs; refunds and excesses return to it). */
+    trader: string;
+    /** Where the output must land. */
+    dest: string;
+    /** Quote fields the body must honour. */
+    inputUnits: string;
+    minOutputAmount: string;
+    inputJetton: string | null;
+    outputJetton: string | null;
+    steps: readonly {
+        protocol: string;
+        inputJetton: string | null | undefined;
+        outputJetton: string | null | undefined;
+    }[];
+    /** The integrator the quote was requested with: the only referral a body may name. */
+    integratorAddress?: string | null;
+}
+interface TonSwapCheckResult {
+    layout: "stonfi-v1" | "stonfi-v2" | "dedust-v1" | "dedust-v2";
+    /** On-chain minimum of the final hop. */
+    minOut: bigint;
+    legs: TonSwapLeg[];
+}
+/** A refusal with a stable, loggable reason code (never carries secrets). */
+declare class TonSwapPayloadError extends Error {
+    readonly reason: string;
+    constructor(reason: string, detail?: string);
+}
+/**
+ * Decode and check a built TON same-chain swap message. Throws
+ * `TonSwapPayloadError` with a reason code on the first violated rule; returns
+ * the chain facts (`legs`) still to be confirmed by `validateTonSwapLeg`.
+ *
+ * Rules (all protocols): one route of single-protocol steps; the body's
+ * layout is the one the quoted protocol builds; the DEX call moves exactly the
+ * quoted input; the final receiver is the destination; refunds / excesses go
+ * to the trader; the final on-chain minimum is ≥ the quote's minOutputAmount;
+ * no referral other than the configured integrator; no trailing data.
+ */
+declare function checkTonSwapPayload(ctx: TonSwapCheckInput): TonSwapCheckResult;
+
+/**
+ * Persists HTLC secret preimages by quoteId between buildDeposit and the
+ * trackIntent poll that discloses them. Losing a secret does NOT lose funds —
+ * the escrow refunds after the HTLC timeout — but it does fail the swap.
+ */
+interface HtlcSecretStore {
+    save(quoteId: string, secretsHex: string[]): void | Promise<void>;
+    load(quoteId: string): string[] | undefined | Promise<string[] | undefined>;
+    clear(quoteId: string): void | Promise<void>;
+}
+/**
+ * Persists the quote/build context between getQuote, buildDeposit and
+ * registerSignedOrder. On SERVERLESS these run on different instances, so the
+ * default in-memory map strands executions ("quote expired") — inject a
+ * durable store there. Values are JSON-safe (byte fields base64-encoded).
+ */
+interface OmnistonQuoteStore {
+    save(quoteId: string, valueJson: string): void | Promise<void>;
+    load(quoteId: string): string | undefined | Promise<string | undefined>;
+    clear(quoteId: string): void | Promise<void>;
+}
+/** Default quote store — long-lived processes and tests only. */
+declare function inMemoryQuoteStore(): OmnistonQuoteStore;
+/** Default store — suitable for long-lived processes and tests only. */
+declare function inMemorySecretStore(): HtlcSecretStore;
+interface ObservableLike<T> {
+    subscribe(observer: {
+        next?: (value: T) => void;
+        error?: (err: unknown) => void;
+        complete?: () => void;
+    }): {
+        unsubscribe(): void;
+    };
+}
+/** Self-contained structural SDK types. Keeping these local prevents the
+ * optional Omniston peer from leaking into every consumer's declaration graph. */
+interface AssetId {
+    chain: {
+        $case: string;
+        value: string | {
+            kind?: {
+                $case: string;
+                value?: unknown;
+            };
+        };
+    };
+}
+interface ChainAddress {
+    chain: {
+        $case: string;
+        value: string;
+    };
+}
+interface QuoteRequest {
+    inputAsset: AssetId;
+    outputAsset: AssetId;
+    amount: {
+        $case: string;
+        value: string;
+    };
+    settlementParams: {
+        params: {
+            $case: string;
+            value: Record<string, unknown>;
+        };
+    }[];
+    integratorAddress?: ChainAddress;
+    integratorFeePips?: number;
+}
+interface OmnistonQuote {
+    rfqId: string;
+    quoteId: string;
+    inputAsset: AssetId;
+    outputAsset: AssetId;
+    inputUnits: string;
+    outputUnits: string;
+    protocolFeeUnits?: string;
+    integratorFeeUnits?: string;
+    integratorAddress?: ChainAddress;
+    quoteTimestamp: number;
+    /** Total TON the trade needs on top of the input (swap settlement); omitted for gasless quotes. */
+    gasBudget?: string | undefined;
+    /** Omniston's estimate of the gas the route actually burns (swap settlement); the rest of the budget returns. */
+    estimatedGasConsumption?: string | undefined;
+    settlementData: {
+        $case: "order";
+        value: OrderSettlement;
+    } | {
+        $case: "swap";
+        value: SwapSettlement;
+    };
+}
+/** Order settlement (HTLC / escrow) — the cross-chain branch. */
+interface OrderSettlement {
+    srcProtocolContractAddress: ChainAddress;
+    dstProtocolContractAddress?: ChainAddress;
+    srcInitialResolverAddress?: ChainAddress;
+    resolverSendsUnits: string;
+    srcHtlcSecurityDepositUnits?: string;
+    dstSecurityDepositUnits?: string;
+    tradeStartDeadline: number;
+    /**
+     * Seconds after the trader creates the position before a resolver must
+     * reserve it; after that the position is withdrawable by the trader (SDK
+     * docs). The TON escrow config carries it, so the payload validator binds
+     * the built escrow to the quoted value.
+     */
+    exclusivityTimeout?: number;
+    htlcHashingFunction?: string;
+    /** Fee profile the EVM order extension must mirror (EVM-source orders). */
+    protocolFeePips?: number;
+    integratorFeePips?: number;
+    /** Destination-chain wallet the protocol fee must be paid to (EVM-destination
+     *  orders); the EVM output validator binds the escrow's fee split to it. */
+    protocolFeeRecipientAddress?: ChainAddress;
+}
+/** Swap settlement — immediate DEX routes, the TON same-chain branch. */
+interface SwapSettlement {
+    routes: {
+        steps: {
+            inputAsset?: AssetId;
+            outputAsset?: AssetId;
+            chunks: {
+                protocol: string;
+                inputUnits: string;
+                outputUnits: string;
+            }[];
+        }[];
+    }[];
+    minOutputAmount: string;
+    recommendedMinOutputAmount?: string;
+    recommendedSlippagePips?: number;
+    priceImpactPips?: number | undefined;
+}
+type RfqEvent = {
+    $case: "ack";
+    value: {
+        rfqId: string;
+    };
+} | {
+    $case: "quoteUpdated";
+    rfqId?: string;
+    value: OmnistonQuote;
+} | {
+    $case: "noQuote";
+    rfqId?: string;
+    value: unknown;
+} | {
+    $case: string;
+    value?: unknown;
+};
+interface EscrowMessage {
+    targetAddress: string;
+    sendAmount: string;
+    payload: string;
+    jettonWalletStateInit?: string | undefined;
+}
+interface OrderExecution {
+    index: number;
+    inputUnits: string;
+    outputUnits: string;
+    resolverSendsUnits: string;
+    secretHash?: Uint8Array | undefined;
+    inputPositionPhase?: string | undefined;
+    inputPositionAddress?: ChainAddress | undefined;
+    outputPositionPhase?: string | undefined;
+    outputPositionAddress?: ChainAddress | undefined;
+}
+interface OrderSnapshot {
+    status: string;
+    executions: OrderExecution[];
+}
+type OrderEvent = {
+    $case: "order";
+    value: OrderSnapshot;
+} | {
+    $case: string;
+    value?: unknown;
+};
+type SwapTrackEvent = {
+    $case: "awaitingTransfer";
+    value?: unknown;
+} | {
+    $case: "progress";
+    value: {
+        status: string;
+        outgoingTxHash?: string;
+    };
+} | {
+    $case: string;
+    value?: unknown;
+};
+/** The slice of `Omniston` this provider uses — a real instance satisfies it. */
+interface OmnistonClientLike {
+    requestForQuote(request: QuoteRequest): ObservableLike<RfqEvent>;
+    tonBuildEscrowTransfer(request: {
+        quoteId: string;
+        ownerSrcAddress: ChainAddress;
+        transferSrcAddress: ChainAddress;
+        refundSrcAddress: ChainAddress;
+        gasExcessAddress: ChainAddress;
+        traderDstAddress: ChainAddress;
+        htlcSecrets: {
+            secretMode: {
+                $case: "provided";
+                value: {
+                    hashes: Uint8Array[];
+                };
+            };
+        };
+    }): Promise<{
+        messages: EscrowMessage[];
+    }>;
+    evmBuildOrderPayload(request: {
+        quoteId: string;
+        ownerSrcAddress: ChainAddress;
+        traderDstAddress?: ChainAddress;
+        htlcSecrets?: {
+            secretMode: {
+                $case: "provided";
+                value: {
+                    hashes: Uint8Array[];
+                };
+            };
+        };
+    }): Promise<{
+        typedData: string;
+        orderExtension: Uint8Array;
+        serializedOrderDetails?: Uint8Array | undefined;
+    }>;
+    orderRegisterSignedOrder(request: {
+        quoteId: string;
+        ownerSrcAddress: ChainAddress;
+        signedOrder: {
+            order: {
+                $case: "evmV1";
+                value: {
+                    encodedOrder: Uint8Array;
+                    signature: Uint8Array;
+                    orderExtension: Uint8Array;
+                };
+            };
+        };
+        serializedOrderDetails?: Uint8Array | undefined;
+    }): Promise<void>;
+    /** Swap settlement (TON↔TON). Optional so older injected clients keep working; without them same-chain swaps fail closed. */
+    tonBuildSwap?(request: {
+        quoteId: string;
+        transferSrcAddress: ChainAddress;
+        refundSrcAddress: ChainAddress;
+        gasExcessAddress: ChainAddress;
+        traderDstAddress: ChainAddress;
+        useRecommendedSlippage?: boolean;
+    }): Promise<{
+        messages: EscrowMessage[];
+    }>;
+    swapTrack?(request: {
+        quoteId: string;
+        traderAddress: ChainAddress;
+        outgoingTxQuery: string;
+    }): ObservableLike<SwapTrackEvent>;
+    orderTrack(request: {
+        quoteId: string;
+        traderAddress: ChainAddress;
+    }): ObservableLike<OrderEvent>;
+    orderDiscloseHtlcSecret(request: {
+        quoteId: string;
+        executionIndex: number;
+        secret: Uint8Array;
+    }): Promise<void>;
+    close?: () => void;
+    transport?: {
+        close(): void;
+    };
+}
+interface OmnistonProviderOptions {
+    /** Injected SDK client (tests); defaults to a lazy `new Omniston({apiUrl})`. */
+    client?: OmnistonClientLike;
+    /** WebSocket API URL; defaults to the public ston.fi endpoint. */
+    apiUrl?: string;
+    /** HTLC preimage persistence; defaults to in-memory (NOT serverless-safe). */
+    secretStore?: HtlcSecretStore;
+    /** Quote/build context persistence; defaults to in-memory (NOT serverless-safe). */
+    quoteStore?: OmnistonQuoteStore;
+    /** Maximum number of HTLC execution attempts covered by generated secrets. */
+    maxHtlcExecutions?: number;
+    /** Hard cap for resolver-requested TON gas/forward value (default: 2 TON). */
+    maxTonExecutionNano?: string;
+    /** Resolver competition window; primarily useful for deterministic tests. */
+    quoteSettleMs?: number;
+    /** Explicit constructor configuration; no deployment environment is read. */
+    enabled?: boolean;
+    /** Exact decimal USD cap; string form avoids binary-float rounding. */
+    maxUsd?: number | string;
+    integratorAddress?: string;
+    integratorFeePips?: number;
+    /** Independently trusted settlement contracts, keyed by CAIP-2 chain. */
+    trustedSettlementContracts?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Independently trusted EVM order protocols — the Omniston fork of the 1inch
+     * Limit Order Protocol an EVM-source order is signed against and that moves
+     * the input token on fill — keyed by CAIP-2 chain. Kept apart from
+     * `trustedSettlementContracts` because one address plays different roles on
+     * different chains (0xafCF… is the escrow factory on Ethereum and the order
+     * protocol on Polygon). EVM→TON is advertised only for chains listed here.
+     */
+    trustedEvmOrderProtocols?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * RPC-backed TON jetton-wallet verification. A TON-source order is rejected
+     * when this hook is absent or does not prove that `walletAddress` belongs to
+     * the quoted jetton master for `ownerAddress`.
+     */
+    validateTonJettonWallet?: (input: {
+        ownerAddress: string;
+        jettonMasterAddress: string;
+        walletAddress: string;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Independent semantic verifier for the Omniston TON escrow forward cell.
+     * The resolver-built BoC is never accepted through byte-search heuristics.
+     * A TON-source route is disabled unless this hook parses the documented
+     * contract schema and proves every expected field below in its exact slot.
+     */
+    /**
+     * TON↔TON swap settlement: independently confirm that the contract a swap
+     * message pays into — directly for native GRAM, as the jetton-transfer
+     * destination for jettons — is a DEX contract of a protocol the quote named
+     * (e.g. by its code interface on an indexer). Without it, same-chain TON
+     * swaps are not advertised.
+     */
+    validateTonSwapTarget?: (input: {
+        address: string;
+        protocols: readonly string[];
+    }) => Promise<boolean> | boolean;
+    /**
+     * TON↔TON swap settlement (scan F11): confirm one chain fact the decoded
+     * swap body depends on — that a STON.fi hop's ask wallet is its router's
+     * wallet of the quoted output (and, for native input, that the pTON wallet
+     * the message pays belongs to that router), or that a DeDust pool trades the
+     * quoted pair. `createOmnistonTonValidators` supplies it. When absent the
+     * decoded-body rules still apply and each skipped leg is traced as
+     * `ton-swap-payload legs-unverified`; STON.fi v1 native input (pTON v1) is
+     * refused without it.
+     */
+    validateTonSwapLeg?: (leg: TonSwapLeg) => Promise<boolean> | boolean;
+    /**
+     * TON↔TON swap settlement (scan F11): what a built swap body that fails the
+     * decoder (receiver ≠ destination, refund/excess ≠ trader, on-chain minimum
+     * below the quote, unknown layout, unverifiable leg) does. "enforce"
+     * (default) refuses the build; "report" traces `ton-swap-payload <reason>`
+     * and still builds — a rollout escape hatch, not a steady state.
+     */
+    tonSwapPayloadCheck?: "report" | "enforce";
+    validateTonEscrowPayload?: (input: {
+        payloadBocHex: string;
+        forwardPayloadBocHex: string;
+        quoteId: string;
+        inputUnits: string;
+        resolverSendsUnits: string;
+        srcHtlcSecurityDepositUnits: string;
+        protocolAddress: string;
+        ownerAddress: string;
+        destinationChain: string;
+        destinationAddress: string;
+        outputTokenAddress: string;
+        initialResolverAddress: string;
+        secretHashes: readonly Uint8Array[];
+        hashingFunction?: string;
+        /** The quote's `exclusivityTimeout` (seconds) the escrow config must carry. */
+        exclusivityTimeout: number;
+    }) => boolean | Promise<boolean>;
+    /**
+     * RPC-backed proof of the destination EVM escrow. The tracking feed is only
+     * a discovery hint: no HTLC preimage is disclosed until this hook proves the
+     * independently finalized on-chain position matches the signed quote.
+     */
+    validateEvmOutputPosition?: (input: {
+        chain: string;
+        positionAddress: string;
+        factoryAddress: string;
+        quoteTimestamp: number;
+        executionIndex: number;
+        recipientAddress: string;
+        outputTokenAddress: string;
+        inputUnits: string;
+        outputUnits: string;
+        resolverSendsUnits: string;
+        srcHtlcSecurityDepositUnits: string;
+        dstSecurityDepositUnits: string;
+        protocolFeeUnits: string;
+        integratorFeeUnits: string;
+        integratorAddress?: string;
+        /** The quote's `settlementData.protocolFeeRecipientAddress` (destination chain). */
+        protocolFeeRecipientAddress?: string;
+        secretHash: Uint8Array;
+    }) => boolean | Promise<boolean>;
+    /**
+     * RPC-backed proof of the finalized EVM source position (EVM→TON). The
+     * tracking feed only hints at the address; no secret is disclosed until this
+     * hook proves — from the trusted factory's own `SrcEscrowCreated` event, the
+     * deterministic escrow address and the escrow's balances — that the
+     * trader's FULL input is locked for this hashlock under the quoted terms
+     * (owner, token, amount, resolver, deposit, timelocks, TON output amount).
+     */
+    validateEvmInputPosition?: (input: {
+        chain: string;
+        positionAddress: string;
+        factoryAddress: string;
+        orderProtocolAddress: string;
+        ownerAddress: string;
+        resolverAddress: string;
+        inputTokenAddress: string;
+        inputUnits: string;
+        resolverSendsUnits: string;
+        srcHtlcSecurityDepositUnits: string;
+        quoteTimestamp: number;
+        secretHash: Uint8Array;
+        /** EVM destination only: the escrow event's destination complement must name this chain, token and deposit. */
+        destinationChainId?: number;
+        destinationTokenAddress?: string;
+        dstSecurityDepositUnits?: string;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Indexer/RPC-backed proof of the TON output position (EVM→TON): deployed by
+     * the trusted factory for THIS quote, pinned position/escrow code, hashlock,
+     * recipient, amount, security deposit, and a cancellation boundary still far
+     * enough away to complete. The tracking feed is only a discovery hint.
+     */
+    validateTonOutputPosition?: (input: {
+        positionAddress: string;
+        protocolAddress: string;
+        outputJettonMasterAddress: string;
+        recipientAddress: string;
+        quoteId: string;
+        quoteTimestamp: number;
+        inputUnits: string;
+        outputUnits: string;
+        resolverSendsUnits: string;
+        dstSecurityDepositUnits: string;
+        secretHash: Uint8Array;
+    }) => boolean | Promise<boolean>;
+    /**
+     * EVM destination: find the delivery transaction — the destination escrow's
+     * payout to the recipient — so a completed order carries `destTxHash`.
+     * Omniston's tracking feed names the escrow but not that transaction.
+     */
+    locateEvmDelivery?: (input: {
+        chain: string;
+        positionAddress: string;
+        recipientAddress: string;
+        tokenAddress: string;
+        minUnits: string;
+    }) => Promise<string | null>;
+    /**
+     * TON destination: find the delivery — the output position's jetton transfer
+     * to the recipient — so a completed EVM → TON order carries `destTxHash` in
+     * the form the TON history source uses (tonapi event id). Without it the
+     * wallet's feed cannot pair the TON receive with the swap.
+     */
+    locateTonDelivery?: (input: {
+        positionAddress: string;
+        recipientAddress: string;
+        jettonMasterAddress: string;
+        minUnits: string;
+    }) => Promise<string | null>;
+    /** Close an injected client when the provider closes (default: caller owns it). */
+    closeInjectedClient?: boolean;
+    /**
+     * Diagnostics: why a poll did not disclose (`disclosure-skipped` with the gate
+     * and its fields, `validator-refused`, `validator-threw`) and when it did
+     * (`secret-disclosed`). Never carries secrets. Wire it to your logger: a
+     * silent "pending" cost a live order its 2-minute window (2026-10-20).
+     */
+    trace?: (event: string, details?: Record<string, unknown>) => void;
+}
+/** EIP-712 typed data → the ABI-encoded order struct `SignedOrderEvmV1` wants.
+ *  Structs referenced in `types` become tuples, recursively. */
+declare function encodeTypedMessage(td: {
+    types: Record<string, {
+        name: string;
+        type: string;
+    }[]>;
+    primaryType: string;
+    message: unknown;
+}): Uint8Array;
+/**
+ * Strict decoder for the currently observed Omniston v1beta8 EVM→TON 1inch
+ * extension profile. It deliberately rejects unknown auction/fee/timelock
+ * profiles: signing a merely well-formed extension is not enough because the
+ * resolver-controlled tail contains the actual on-chain HTLC terms.
+ *
+ * This binds what the wallet signs to the quote; it does not by itself make
+ * the swap complete. Secret disclosure additionally needs the independently
+ * finalized EVM source-fill and TON output-position proofs (trackIntent).
+ * `dstSecurityDepositUnits` is the value the EVM deposits word carries — for a
+ * TON destination that word is 0 (the TON deposit is bound in the TON position).
+ */
+declare function validateEvmToTonOrderExtension(extension: Uint8Array, expected: {
+    quoteId: string;
+    quoteTimestamp: number;
+    tradeStartDeadline: number;
+    protocolFeePips: number;
+    integratorFeePips: number;
+    initialResolverAddress: string;
+    outputTokenAddress: string;
+    traderDstAddress: string;
+    takerAsset: string;
+    srcSecurityDepositUnits: string;
+    dstSecurityDepositUnits: string;
+    secretHash: Uint8Array;
+    trustedTarget: (address: string) => boolean;
+    /** EVM destination (EIP-155 id): ExtraDataArgs carry it and the destination
+     *  ERC-20 (`outputTokenAddress`, `traderDstAddress` are EVM then). Absent = TON. */
+    dstChainId?: number;
+}): Promise<void>;
+declare function omnistonProvider(opts?: OmnistonProviderOptions): CrossChainProvider;
+
+export { type HtlcSecretStore, type OmnistonClientLike, type OmnistonProviderOptions, type OmnistonQuoteStore, TON_SWAP_PROTOCOL_LAYOUTS, type TonSwapCheckInput, type TonSwapCheckResult, type TonSwapLeg, TonSwapPayloadError, checkTonSwapPayload, encodeTypedMessage, inMemoryQuoteStore, inMemorySecretStore, omnistonProvider, validateEvmToTonOrderExtension };