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

package/dist/validators.d.ts

@@ -0,0 +1,199 @@
+import { OmnistonProviderOptions } from './provider.js';
+import '@anywalletkit/protocol-swap2-core/types';
+
+/** How far back (blocks) a factory event is searched, per chain — shared with the EVM input validator. */
+declare const OMNISTON_EVM_LOOKBACK_BLOCKS: Readonly<Record<string, bigint>>;
+/** Confirmations before a factory event counts as final, per chain. */
+declare const OMNISTON_EVM_MIN_CONFIRMATIONS: Readonly<Record<string, bigint>>;
+type OmnistonRpcRequest = (chain: string, method: string, params: unknown[]) => Promise<unknown>;
+/** CAIP-2 chain → JSON-RPC URLs, tried in order before the public fallbacks. */
+type OmnistonRpcUrls = Readonly<Record<string, readonly string[]>>;
+type RpcRequest = OmnistonRpcRequest;
+interface EvmOutputValidationInput {
+    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): the only address the escrow may pay a non-zero protocol fee to. */
+    protocolFeeRecipientAddress?: string;
+    secretHash: Uint8Array;
+}
+/** Diagnostics hook: every refusal names its check and the numbers it compared (never a secret). */
+type OmnistonEvmOutputRefusal = (reason: string, details?: Record<string, unknown>) => void;
+/** JSON-RPC over the caller's endpoints (`rpcUrls`) with public failover (reads only). */
+declare function omnistonEvmRpcRequest(chain: string, method: string, params: unknown[], rpcUrls?: OmnistonRpcUrls): Promise<unknown>;
+declare function createOmnistonEvmOutputValidator(options?: {
+    request?: RpcRequest;
+    rpcUrls?: OmnistonRpcUrls;
+    now?: () => number;
+    onRefusal?: OmnistonEvmOutputRefusal;
+}): (input: EvmOutputValidationInput) => Promise<boolean>;
+/**
+ * Finds an Omniston EVM delivery: the ERC-20 `Transfer` from the destination
+ * escrow to the recipient of at least `minUnits`, within the chain's lookback
+ * window. Feeds `omnistonProvider({locateEvmDelivery})` so a completed order
+ * reports the transaction that actually paid the recipient.
+ */
+declare function createOmnistonEvmDeliveryLocator(options?: {
+    request?: RpcRequest;
+    rpcUrls?: OmnistonRpcUrls;
+}): (input: {
+    chain: string;
+    positionAddress: string;
+    recipientAddress: string;
+    tokenAddress: string;
+    minUnits: string;
+}) => Promise<string | null>;
+
+/** keccak256 of the event signature with the structs expanded (live Base 2026-10-16: 0x1140dcf8…). */
+declare const SRC_ESCROW_CREATED_TOPIC: `0x${string}`;
+interface EvmInputValidationInput {
+    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 destination complement must name this chain, token and deposit. */
+    destinationChainId?: number;
+    destinationTokenAddress?: string;
+    dstSecurityDepositUnits?: string;
+}
+/** Diagnostics hook: every refusal names its check and the numbers it compared (never a secret). */
+type OmnistonValidatorRefusal = (reason: string, details?: Record<string, unknown>) => void;
+declare function createOmnistonEvmInputValidator(options?: {
+    request?: OmnistonRpcRequest;
+    rpcUrls?: OmnistonRpcUrls;
+    now?: () => number;
+    onRefusal?: OmnistonValidatorRefusal;
+}): (input: EvmInputValidationInput) => Promise<boolean>;
+
+/** Audited from the active mainnet Escrow builder on 2026-08-13. These are
+ * immutable TVM code cells, not resolver-controlled addresses. A contract
+ * upgrade must deliberately update these hashes after reviewing its schema.
+ *
+ * `authorityKeys` is the optional 256-bit public key in the escrow config: the
+ * escrow code checks `CHKSIGNU` against it for its signature-gated operations
+ * (disassembly of code 9e77cb9e…, 2026-10-11). It has been the same key since
+ * the August audit, so it stays pinned. */
+declare const DEFAULT_OMNISTON_TON_CODE_HASHES: {
+    readonly escrow: readonly ["9e77cb9e8fd7406d4e85e5f57378eb51e51b862424cf988306c783d50ade697a"];
+    readonly execution: readonly ["f6edbc76e6fbcd6bac573cb942401a3d9198ee9605f9403b0f5c8081259210e5"];
+    readonly authorityKeys: readonly ["ed210da12aa96ea42de4f2f61dc172bbaa3da86051a1b2a6f342f69a777d2770"];
+    /** EVM→TON output position: the contract the factory deploys for the
+     *  resolver's jetton lock (observed on every resolver-created position,
+     *  2026-10-15/16), and the escrow code cell it carries in its state. */
+    readonly position: readonly ["e4d5115a321ade7b827e38fb522c20d2f2cd46e4c6b0b5f7dd8b6b096792d77b"];
+    readonly outputEscrow: readonly ["d30423575384773abaad8d3c6f763898afa3d57a5693005904b7c61e95cee630"];
+};
+/** Upper bound on the exclusivity window the escrow config may carry. It is
+ * how long the trader's input stays locked when no resolver reserves the
+ * position (SDK: "at the end of this period trader's position becomes
+ * available for manual withdrawal"); the live value is 300 s. */
+declare const MAX_OMNISTON_EXCLUSIVITY_SECONDS = 3600;
+type PayloadInput = Omit<Parameters<NonNullable<OmnistonProviderOptions["validateTonEscrowPayload"]>>[0], "exclusivityTimeout"> & {
+    exclusivityTimeout?: number;
+};
+/** Code interfaces (tonapi's by-code-hash labels) a same-chain swap message
+ *  may pay into. The resolver picks the pool/vault per route, so the check is
+ *  "a STON.fi or DeDust contract by code", not a fixed address list — seen
+ *  live: native GRAM → DeDust CPMM v2 pool, jettons → STON.fi router v2. */
+declare const DEFAULT_OMNISTON_TON_SWAP_INTERFACES: readonly ["stonfi_router", "stonfi_router_v2", "stonfi_pool", "stonfi_pool_v2", "dedust_vault", "dedust_v2_cpmm", "dedust_pool"];
+/** Proxy-TON (pTON) jetton masters STON.fi routes native TON through. A
+ *  native-input swap pays the ROUTER'S pTON wallet — a plain `jetton_wallet`
+ *  to tonapi, no DEX code interface — so such a target is accepted only when
+ *  its jetton master is pTON AND its owner carries a DEX router interface.
+ *  Seen live 2026-09-05: GRAM → USDT on StonFiV2 targeted the router's pTON
+ *  v2 wallet and the code-interface check alone refused it. */
+declare const DEFAULT_OMNISTON_TON_PROXY_TON_MASTERS: readonly ["EQCM3B12QK1e4yZSf8GtBRT0aLMNyEsBc_DhVfRRtOEffLez", "EQBnGWMCf3-FZZq1W4IWcWiGAc3PHuZ0_H-7sad2oY00o83S"];
+interface OmnistonTonValidationOptions {
+    fetch?: typeof fetch;
+    /** Diagnostics hook: every refusal of validateTonOutputPosition names its check (never a secret). */
+    onRefusal?: (reason: string, details?: Record<string, unknown>) => void;
+    tonApiUrl?: string;
+    tonApiKey?: string;
+    /** Code interfaces accepted as swap targets (default: the STON.fi / DeDust set above). */
+    swapTargetInterfaces?: readonly string[];
+    /** Proxy-TON masters whose router-owned wallets may receive native input (default: pTON v1/v2). */
+    proxyTonMasters?: readonly string[];
+    escrowCodeHashes?: readonly string[];
+    executionCodeHashes?: readonly string[];
+    /** Pinned escrow authority public keys (hex, 32 bytes). */
+    authorityKeys?: readonly string[];
+    /** EVM→TON output position code hashes (default: the observed factory position). */
+    positionCodeHashes?: readonly string[];
+    /** Escrow code cells an output position may carry (default: the observed one). */
+    outputEscrowCodeHashes?: readonly string[];
+    now?: () => number;
+}
+type TonOutputPositionInput = Parameters<NonNullable<OmnistonProviderOptions["validateTonOutputPosition"]>>[0];
+declare function createOmnistonTonValidators(options?: OmnistonTonValidationOptions): Pick<OmnistonProviderOptions, "validateTonJettonWallet" | "validateTonSwapTarget" | "validateTonOutputPosition" | "validateTonSwapLeg"> & {
+    validateTonEscrowPayload: (input: PayloadInput) => boolean | Promise<boolean>;
+};
+interface OmnistonTonDeliveryLocatorOptions {
+    fetch?: typeof fetch;
+    tonApiUrl?: string;
+    tonApiKey?: string;
+    /** Recipient events scanned per call (newest first; the delivery is recent by construction). */
+    limit?: number;
+}
+interface OmnistonTonDeliveryInput {
+    /** The output position that paid out; when absent any sender of a matching transfer counts (backfills). */
+    positionAddress?: string;
+    recipientAddress: string;
+    jettonMasterAddress: string;
+    minUnits: string;
+    /** Unix seconds; events before it are not this delivery (backfills). With it set, the EARLIEST match wins — the one closest to the order, not a later swap's payout. */
+    afterTimestamp?: number;
+    /** Unix seconds; events after it are not this delivery (backfills: the row's completion time plus slack). */
+    beforeTimestamp?: number;
+}
+/**
+ * Finds an Omniston TON delivery: the jetton transfer from the output position
+ * to the recipient of at least `minUnits`, in the recipient's tonapi events.
+ * Returns tonapi's `event_id` — the hash `@anywalletkit/wallet-ton`'s history
+ * source gives the same event as a row, so a wallet can pair the TON receive
+ * with the swap. Feeds `omnistonProvider({locateTonDelivery})`; a server may
+ * also call it with no position to backfill rows completed before the locator
+ * existed. Never throws: null when nothing matched or tonapi did not answer.
+ */
+declare function createOmnistonTonDeliveryLocator(options?: OmnistonTonDeliveryLocatorOptions): (input: OmnistonTonDeliveryInput) => Promise<string | null>;
+
+/**
+ * Settlement contracts this deployment trusts for Omniston, per CAIP-2 chain.
+ * Audited public addresses — no secret — so both the server wiring and the
+ * browser-side provider import them from here.
+ * See how-to-project/OMNISTON-NETWORK-ONBOARDING.md before adding a network.
+ */
+declare const AUDITED_OMNISTON_SETTLEMENT_CONTRACTS: Record<string, string[]>;
+/**
+ * EVM order protocols (Omniston's fork of the 1inch Limit Order Protocol v4 —
+ * NOT the canonical 1inch deployment) an EVM→TON order is signed against. The
+ * wallet approves this contract for the input amount and signs an EIP-712
+ * order whose domain names it; on fill it moves the input into the escrow the
+ * factory above deploys. One address, different roles per chain (0xafCF… is
+ * the factory elsewhere and the order protocol on Polygon), so this table is
+ * separate from the factory table and CAIP-scoped. Runtime code hashes are in
+ * how-to-project/OMNISTON-NETWORK-ONBOARDING.md (snapshot 2026-10-16).
+ */
+declare const AUDITED_OMNISTON_EVM_ORDER_PROTOCOLS: Record<string, string[]>;
+
+export { AUDITED_OMNISTON_EVM_ORDER_PROTOCOLS, AUDITED_OMNISTON_SETTLEMENT_CONTRACTS, DEFAULT_OMNISTON_TON_CODE_HASHES, DEFAULT_OMNISTON_TON_PROXY_TON_MASTERS, DEFAULT_OMNISTON_TON_SWAP_INTERFACES, type EvmInputValidationInput, type EvmOutputValidationInput, MAX_OMNISTON_EXCLUSIVITY_SECONDS, OMNISTON_EVM_LOOKBACK_BLOCKS, OMNISTON_EVM_MIN_CONFIRMATIONS, type OmnistonEvmOutputRefusal, type OmnistonRpcRequest, type OmnistonRpcUrls, type OmnistonTonDeliveryInput, type OmnistonTonDeliveryLocatorOptions, type OmnistonTonValidationOptions, type OmnistonValidatorRefusal, SRC_ESCROW_CREATED_TOPIC, type TonOutputPositionInput, createOmnistonEvmDeliveryLocator, createOmnistonEvmInputValidator, createOmnistonEvmOutputValidator, createOmnistonTonDeliveryLocator, createOmnistonTonValidators, omnistonEvmRpcRequest };