@stelis/say-ur-intent 0.0.0 → 0.0.2

package/dist/adapters/deepbook/deepbookTransactionMaterialProducer.js

@@ -0,0 +1,269 @@
+import { DeepBookClient, mainnetCoins } from "@mysten/deepbook-v3";
+import { Transaction } from "@mysten/sui/transactions";
+import { parseDeepbookRawU64 } from "../../core/read/deepbookReadHelpers.js";
+import { LocalTransactionMaterialStoreError } from "../../core/session/transactionMaterialStore.js";
+import { suiTransactionDigestSchema } from "../../core/suiAddress.js";
+import { failReviewCheck, passReviewCheck } from "../../core/review/reviewComputationResult.js";
+const DEEPBOOK_SWAP_GAS_BUDGET_MIST = 50000000n;
+const SUI_COIN_TYPE = "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI";
+export function deepbookSwapBalanceRequirements(input) {
+    if (input.sourceCoinType === SUI_COIN_TYPE) {
+        return [
+            {
+                symbol: input.sourceSymbol,
+                coinType: SUI_COIN_TYPE,
+                decimals: input.sourceDecimals,
+                requiredRaw: input.sourceAmountRaw + DEEPBOOK_SWAP_GAS_BUDGET_MIST
+            }
+        ];
+    }
+    return [
+        {
+            symbol: input.sourceSymbol,
+            coinType: input.sourceCoinType,
+            decimals: input.sourceDecimals,
+            requiredRaw: input.sourceAmountRaw
+        },
+        { symbol: "SUI", coinType: SUI_COIN_TYPE, decimals: 9, requiredRaw: DEEPBOOK_SWAP_GAS_BUDGET_MIST }
+    ];
+}
+function displayRaw(raw, decimals) {
+    const base = 10n ** BigInt(decimals);
+    const whole = raw / base;
+    const fraction = (raw % base).toString().padStart(decimals, "0").replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : whole.toString();
+}
+export function createDeepbookSwapTransactionMaterialProducer(options) {
+    return async (input) => {
+        if (options.network !== "mainnet" || options.chainIdentifier !== options.expectedChainIdentifier) {
+            return {
+                status: "blocked",
+                blockedReason: "network_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_network_mismatch", "Transaction material network", "DeepBook transaction material build requires a verified Sui mainnet gRPC endpoint and matching mainnet chain identifier.", "network")
+                ]
+            };
+        }
+        if (input.poolResolution.direction !== input.quotePolicy.direction || input.quote.direction !== input.quotePolicy.direction) {
+            return {
+                status: "blocked",
+                blockedReason: "amount_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_quote_direction_mismatch", "Transaction material quote policy", "DeepBook transaction material build requires pool direction, quote evidence, and quote policy to describe the same swap direction.", "adapter")
+                ]
+            };
+        }
+        const quoteExpiresAt = quotePolicyExpiresAt(input.quotePolicy);
+        if (quoteExpiresAt.getTime() <= input.now.getTime()) {
+            return {
+                status: "refresh_required",
+                refreshReason: "quote_stale",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_quote_expired", "Transaction material quote policy", "DeepBook transaction material was not built because the quote policy expired before build.", "quote")
+                ]
+            };
+        }
+        let sourceAmountRaw;
+        let minOutRaw;
+        let deepAmountRaw;
+        try {
+            sourceAmountRaw = parseDeepbookRawU64(input.quotePolicy.sourceAmountRaw, "sourceAmountRaw", { positive: true });
+            minOutRaw = parseDeepbookRawU64(input.quotePolicy.minOutRaw, "minOutRaw", { positive: true });
+            deepAmountRaw = parseDeepbookRawU64(input.quotePolicy.deepAmountRaw, "deepAmountRaw");
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: "amount_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_raw_amount_invalid", "Transaction material quote policy", error instanceof Error ? error.message : "DeepBook transaction material requires valid raw u64 quote policy amounts.", "quote")
+                ]
+            };
+        }
+        try {
+            const sourceQuoteAmount = input.quote.rawQuote.inputAmount;
+            const requirements = deepbookSwapBalanceRequirements({
+                sourceSymbol: sourceQuoteAmount.symbol,
+                sourceCoinType: sourceQuoteAmount.coinType,
+                sourceDecimals: sourceQuoteAmount.decimals,
+                sourceAmountRaw: sourceAmountRaw
+            });
+            for (const requirement of requirements) {
+                const balance = await options.client.core.getBalance({
+                    owner: input.account,
+                    coinType: requirement.coinType
+                });
+                const heldRaw = BigInt(balance.balance.balance);
+                if (heldRaw < requirement.requiredRaw) {
+                    const isGasOnly = requirement.coinType === SUI_COIN_TYPE && sourceQuoteAmount.coinType !== SUI_COIN_TYPE;
+                    return {
+                        status: "blocked",
+                        blockedReason: "insufficient_balance",
+                        checks: [
+                            failReviewCheck("deepbook_transaction_material_build_failed", "Transaction material build", `Insufficient balance: this swap needs ${displayRaw(requirement.requiredRaw, requirement.decimals)} ${requirement.symbol}${isGasOnly ? " for gas" : requirement.coinType === SUI_COIN_TYPE ? " (amount + gas)" : ""}, but the account holds ${displayRaw(heldRaw, requirement.decimals)} ${requirement.symbol}. Nothing was signed and no funds moved.`, "adapter")
+                        ]
+                    };
+                }
+            }
+            const deepbook = new DeepBookClient({
+                client: options.client,
+                address: input.account,
+                network: options.network
+            });
+            const transaction = new Transaction();
+            transaction.setSender(input.account);
+            // The DeepBook SDK reserves a 0.25 SUI gas budget by default, which
+            // blocks small wallets whose balance is close to the swap amount. A
+            // mainnet DeepBook swap costs well under this explicit 0.05 SUI budget.
+            transaction.setGasBudget(DEEPBOOK_SWAP_GAS_BUDGET_MIST);
+            // input_coin fee mode swaps with an explicit zero DEEP coin; the Move
+            // entry point then charges the taker fee in the source coin at the
+            // protocol penalty. The explicit zero coin avoids SDK coin selection,
+            // which cannot resolve a zero balance for accounts holding no DEEP.
+            const inputFeeMode = input.quotePolicy.feeMode === "input_coin";
+            const zeroDeepCoin = inputFeeMode
+                ? transaction.moveCall({
+                    target: "0x2::coin::zero",
+                    typeArguments: [mainnetCoins.DEEP.type]
+                })
+                : undefined;
+            const swapDeepAmountRaw = inputFeeMode ? 0n : deepAmountRaw;
+            const [baseCoinResult, quoteCoinResult, deepCoinResult] = input.quotePolicy.direction === "base_to_quote"
+                ? deepbook.deepBook.swapExactBaseForQuote({
+                    poolKey: input.poolResolution.poolKey,
+                    amount: sourceAmountRaw,
+                    minOut: minOutRaw,
+                    deepAmount: swapDeepAmountRaw,
+                    ...(zeroDeepCoin ? { deepCoin: zeroDeepCoin } : {})
+                })(transaction)
+                : deepbook.deepBook.swapExactQuoteForBase({
+                    poolKey: input.poolResolution.poolKey,
+                    amount: sourceAmountRaw,
+                    minOut: minOutRaw,
+                    deepAmount: swapDeepAmountRaw,
+                    ...(zeroDeepCoin ? { deepCoin: zeroDeepCoin } : {})
+                })(transaction);
+            transaction.transferObjects([baseCoinResult, quoteCoinResult, deepCoinResult], input.account);
+            const transactionBytes = await transaction.build({ client: options.client });
+            options.materialStore.deleteReviewSessionTransactionMaterials(input.reviewSessionId);
+            const handle = options.materialStore.recordTransactionMaterial({
+                reviewSessionId: input.reviewSessionId,
+                planId: input.plan.id,
+                account: input.account,
+                kind: "deepbook_swap_transaction_data",
+                source: "say_ur_intent_built",
+                transactionBytes,
+                expiresAt: quoteExpiresAt,
+                redactedDiagnostics: {
+                    protocol: input.plan.protocol,
+                    adapterId: input.plan.adapterId,
+                    actionKind: input.plan.actionKind,
+                    poolKey: input.poolResolution.poolKey,
+                    direction: input.quotePolicy.direction,
+                    quoteFetchedAt: input.quotePolicy.fetchedAt,
+                    quoteExpiresAt: quoteExpiresAt.toISOString(),
+                    sourceAmountRaw: input.quotePolicy.sourceAmountRaw,
+                    minOutRaw: input.quotePolicy.minOutRaw,
+                    deepAmountRaw: input.quotePolicy.deepAmountRaw
+                }
+            }, input.now);
+            return {
+                status: "completed",
+                evidence: handle,
+                checks: [
+                    passReviewCheck("deepbook_transaction_material_built", "Transaction material build", "Built account-bound DeepBook swap transaction material from Say Ur Intent quote policy and stored the unsigned transaction bytes only in the local material store until quote expiry. This is not wallet handoff, signing data, signing readiness, or execution readiness.", "adapter")
+                ]
+            };
+        }
+        catch (error) {
+            const blockedReason = blockedReasonForBuildError(error);
+            return {
+                status: "blocked",
+                blockedReason,
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_build_failed", "Transaction material build", buildFailureMessage(blockedReason), "adapter")
+                ]
+            };
+        }
+    };
+}
+export function createDeepbookSwapTransactionMaterialDigestProducer(options) {
+    return async (input) => {
+        const material = options.materialStore.getTransactionMaterial(input.materialHandle, input.now);
+        if (!material) {
+            return {
+                status: "refresh_required",
+                refreshReason: "quote_stale",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_unavailable", "Transaction material digest", "DeepBook transaction material digest was not computed because the stored local material was unavailable or expired; refresh the review evidence before continuing.", "adapter")
+                ]
+            };
+        }
+        let transactionDigest;
+        try {
+            transactionDigest = await Transaction.from(material.transactionBytes).getDigest();
+        }
+        catch {
+            return {
+                status: "blocked",
+                blockedReason: "object_resolution_failed",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_failed", "Transaction material digest", "DeepBook transaction material digest could not be derived from the stored local transaction bytes.", "adapter")
+                ]
+            };
+        }
+        const parsedDigest = suiTransactionDigestSchema.safeParse(transactionDigest);
+        if (!parsedDigest.success) {
+            return {
+                status: "blocked",
+                blockedReason: "object_resolution_failed",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_invalid", "Transaction material digest", "DeepBook transaction material digest did not match the pinned Sui SDK transaction digest format.", "adapter")
+                ]
+            };
+        }
+        return {
+            status: "completed",
+            evidence: {
+                materialId: material.materialId,
+                reviewSessionId: material.reviewSessionId,
+                planId: material.planId,
+                account: material.account,
+                kind: material.kind,
+                source: material.source,
+                digestKind: "sui_transaction_digest",
+                transactionDigest: parsedDigest.data,
+                computedAt: input.now.toISOString(),
+                expiresAt: material.expiresAt
+            },
+            checks: [
+                passReviewCheck("deepbook_transaction_material_digest_commitment", "Transaction material digest", "Derived a Sui transaction digest from the stored local unsigned transaction material. The digest and bytes remain internal until later review stages bind object ownership, human-readable review, and simulation evidence.", "adapter")
+            ]
+        };
+    };
+}
+function quotePolicyExpiresAt(policy) {
+    return new Date(Date.parse(policy.fetchedAt) + policy.staleAfterMs);
+}
+function blockedReasonForBuildError(error) {
+    if (error instanceof LocalTransactionMaterialStoreError) {
+        return "object_resolution_failed";
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/insufficient ?coin ?balance|insufficient balance/i.test(message)) {
+        return "insufficient_balance";
+    }
+    if (/gas/i.test(message) && /insufficient|no valid|payment|budget/i.test(message)) {
+        return "insufficient_gas";
+    }
+    return "object_resolution_failed";
+}
+function buildFailureMessage(blockedReason) {
+    if (blockedReason === "insufficient_balance") {
+        return "DeepBook transaction material build failed before wallet handoff because the account does not have enough source or fee assets.";
+    }
+    if (blockedReason === "insufficient_gas") {
+        return "DeepBook transaction material build failed before wallet handoff because a usable gas payment could not be resolved.";
+    }
+    return "DeepBook transaction material build failed before wallet handoff because required account-bound objects could not be resolved.";
+}

package/dist/adapters/flowx/flowxSwapHumanReviewProducer.js

@@ -0,0 +1,176 @@
+import { createSwapHumanReadableReviewEvidence } from "../../core/action/swapHumanReadableReviewProjection.js";
+import { failReviewCheck, passReviewCheck } from "../../core/review/reviewComputationResult.js";
+export function createFlowxSwapHumanReadableReviewProducer() {
+    return (input) => {
+        try {
+            assertFlowxHumanReviewSources(input);
+            const review = buildFlowxHumanReadableReview(input);
+            const evidence = createSwapHumanReadableReviewEvidence({
+                transactionMaterial: input.transactionMaterial,
+                transactionMaterialDigest: input.transactionMaterialDigest,
+                swapQuotePolicy: input.swapQuotePolicy,
+                transactionObjectOwnership: input.transactionObjectOwnership,
+                adapterId: input.plan.adapterId,
+                protocol: input.plan.protocol,
+                actionKind: input.plan.actionKind,
+                review,
+                derivedAt: input.now
+            });
+            return {
+                status: "completed",
+                evidence,
+                checks: [
+                    passReviewCheck("flowx_human_readable_review_evidence", "Human-readable review", "Prepared a human-readable account-bound swap review from material-bound quote policy and object ownership evidence. This is not wallet handoff, signing data, signing readiness, or execution readiness.", "adapter")
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: classifyHumanReviewFailure(error),
+                checks: [
+                    failReviewCheck("flowx_human_readable_review_failed", "Human-readable review", error instanceof Error ? error.message : "FlowX human-readable review evidence could not be produced.", "adapter")
+                ]
+            };
+        }
+    };
+}
+function buildFlowxHumanReadableReview(input) {
+    const sourceAmount = amountFromQuotePolicy("input", input.swapQuotePolicy.sourceAmount, {
+        displayAmount: input.requestedIntent.from.amountDisplay,
+        displayAmountSource: "user_display_intent_not_signing_input"
+    });
+    const expectedOutput = amountFromQuotePolicy("expected_output", input.swapQuotePolicy.expectedOutput);
+    const minimumOutput = amountFromQuotePolicy("minimum_output", input.swapQuotePolicy.minimumOutput);
+    const protocolFee = amountFromQuotePolicy("fee", input.swapQuotePolicy.protocolFee);
+    return {
+        kind: "swap_human_readable_review",
+        proposedAction: {
+            title: input.plan.title,
+            summary: input.plan.summary,
+            actionKind: input.plan.actionKind,
+            adapterId: input.plan.adapterId,
+            protocol: input.plan.protocol,
+            network: "sui:mainnet"
+        },
+        assetFlow: {
+            outgoing: [sourceAmount],
+            expectedIncoming: [expectedOutput],
+            minimumIncoming: [minimumOutput],
+            fees: [protocolFee]
+        },
+        recipients: [
+            { role: "connected_account", address: input.account },
+            { role: "output_recipient", address: input.account }
+        ],
+        targets: [
+            {
+                kind: "swap_output_asset",
+                symbol: input.swapQuotePolicy.expectedOutput.asset.symbol,
+                coinType: input.swapQuotePolicy.expectedOutput.asset.coinType,
+                protocol: input.plan.protocol,
+                poolKey: input.swapQuotePolicy.quoteSource.poolKey,
+                direction: input.swapQuotePolicy.quoteSource.direction
+            }
+        ],
+        evidenceUsed: [
+            {
+                id: "flowx_quote_policy",
+                label: "Quote policy",
+                source: "quote",
+                summary: "Quote policy evidence supplies the input, expected output, minimum output, and slippage policy shown in asset flow. The route was chosen by the FlowX router, not by this review; the review verified the routed pool against the pinned registry and the FlowX CLMM swap fee is charged inside the pool, already reflected in the expected output."
+            },
+            {
+                id: "transaction_material_digest",
+                label: "Transaction material digest",
+                source: "digest_commitment",
+                summary: "The review is bound internally to the stored local unsigned transaction material digest; the digest and transaction bytes are not public review output."
+            },
+            {
+                id: "transaction_object_ownership",
+                label: "Object ownership",
+                source: "wallet",
+                summary: "Object ownership evidence is derived from stored transaction data and Sui mainnet object reads."
+            }
+        ],
+        missingEvidence: [
+            {
+                id: "review_time_simulation",
+                label: "Review-time simulation",
+                reason: "The review has not simulated the stored transaction material with required effects, balance changes, object types, and transaction fields."
+            }
+        ],
+        requiredUserChoices: [
+            {
+                id: "wallet_authorization_later",
+                label: "Wallet authorization",
+                reason: "The wallet signature request happens on this review page after the digest-gated handoff; nothing is signed without your approval in the wallet."
+            }
+        ],
+        unsupportedClaims: [
+            {
+                id: "no_signing_readiness",
+                label: "No signing readiness",
+                reason: "Human-readable review evidence does not prove the action is ready to sign."
+            },
+            {
+                id: "no_execution_readiness",
+                label: "No execution readiness",
+                reason: "Review-time simulation, wallet handoff, signing, and execution receipt evidence are not complete."
+            },
+            {
+                id: "no_route_recommendation",
+                label: "No route recommendation",
+                reason: "The routed pool was selected by the FlowX router; this review verifies the resulting path and on-chain minimum output and does not rank venues or recommend routes."
+            }
+        ],
+        freshness: {
+            status: "current",
+            evaluatedAt: input.now.toISOString(),
+            expiresAt: input.transactionMaterial.expiresAt,
+            reason: "Human-readable review evidence expires with the stored local transaction material and quote policy."
+        },
+        blockingChecks: [
+            failReviewCheck("flowx_review_time_simulation_missing", "Review-time simulation", "Review-time simulation evidence is still required before any wallet handoff, signing, or execution.", "simulation")
+        ]
+    };
+}
+function assertFlowxHumanReviewSources(input) {
+    if (input.swapQuotePolicy.adapterId !== input.plan.adapterId ||
+        input.swapQuotePolicy.protocol !== input.plan.protocol ||
+        input.swapQuotePolicy.actionKind !== input.plan.actionKind) {
+        throw new Error("human-readable review quote policy identity must match the action plan");
+    }
+    if (input.swapQuotePolicy.quoteSource.poolKey !== input.routedPool.poolKey) {
+        throw new Error("human-readable review pool target must match swap quote policy poolKey");
+    }
+    const expectedDirection = input.quotePolicy.swapXToY ? "base_to_quote" : "quote_to_base";
+    if (input.swapQuotePolicy.quoteSource.direction !== expectedDirection) {
+        throw new Error("human-readable review target direction must match swap quote policy direction");
+    }
+}
+function classifyHumanReviewFailure(error) {
+    const message = error instanceof Error ? error.message : "";
+    if (/object ownership/i.test(message)) {
+        return "object_resolution_failed";
+    }
+    if (/asset|target|pool|direction|protocol|adapter/i.test(message)) {
+        return "asset_mismatch";
+    }
+    if (/amount|quote|slippage|min/i.test(message)) {
+        return "amount_mismatch";
+    }
+    return "unsupported_action";
+}
+function amountFromQuotePolicy(role, amount, display) {
+    return {
+        role,
+        symbol: amount.asset.symbol,
+        coinType: amount.asset.coinType,
+        decimals: amount.asset.decimals,
+        rawAmount: amount.raw,
+        rawAmountSource: "quote_policy_evidence",
+        ...(display?.displayAmount ? { displayAmount: display.displayAmount } : {}),
+        ...(display?.displayAmountSource ? { displayAmountSource: display.displayAmountSource } : {})
+    };
+}

package/dist/adapters/flowx/flowxSwapIntent.js

@@ -0,0 +1,79 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { accountBoundReviewRequiredCheck, signingViaLocalReviewOnlyCheck } from "../../core/review/reviewChecks.js";
+import { canonicalFlowxSymbol } from "../../core/read/flowxRegistry.js";
+export const FLOWX_SWAP_ACTION_KIND = "swap";
+export const FLOWX_SWAP_ADAPTER_ID = "flowx-swap";
+export const FLOWX_SWAP_PROTOCOL = "FlowXCLMM";
+export const flowxSwapIntentInputSchema = z.object({
+    type: z.literal(FLOWX_SWAP_ACTION_KIND),
+    from: z.object({
+        symbol: z.string().min(1),
+        amount: z.string().min(1)
+    }),
+    to: z.object({
+        symbol: z.string().min(1)
+    }),
+    maxSlippageBps: z.number().int().min(1).max(1000)
+});
+export const flowxSwapRequestedIntentSchema = z.object({
+    type: z.literal(FLOWX_SWAP_ACTION_KIND),
+    from: z.object({
+        symbol: z.string().min(1),
+        amountDisplay: z.string().min(1)
+    }),
+    to: z.object({
+        symbol: z.string().min(1)
+    }),
+    maxSlippageBps: z.number().int().min(1).max(1000)
+});
+export function createFlowxSwapActionPlan(intent, now) {
+    const requestedIntent = normalizeFlowxSwapRequestedIntent(intent);
+    return {
+        id: `plan_${randomUUID()}`,
+        actionKind: FLOWX_SWAP_ACTION_KIND,
+        adapterId: FLOWX_SWAP_ADAPTER_ID,
+        protocol: FLOWX_SWAP_PROTOCOL,
+        title: `Review ${requestedIntent.from.amountDisplay} ${requestedIntent.from.symbol} to ${requestedIntent.to.symbol}`,
+        summary: "Account-bound FlowX review evidence is computed after a wallet account is connected. The review URL displays the proposal and local review evidence; when every evidence stage completes, the review page offers user-controlled wallet signing through a digest-gated handoff. This MCP response contains no sign action, signing data, transaction bytes, or signing readiness.",
+        assetFlowPreview: {
+            outgoing: [
+                { symbol: requestedIntent.from.symbol, amount: requestedIntent.from.amountDisplay, amountKind: "display_intent" }
+            ],
+            expectedIncoming: [
+                { symbol: requestedIntent.to.symbol, amount: "unknown", amountKind: "display_intent", approx: true }
+            ]
+        },
+        adapterData: {
+            requestedIntent
+        },
+        createdAt: now.toISOString(),
+        preliminaryChecks: [accountBoundReviewRequiredCheck(), signingViaLocalReviewOnlyCheck()]
+    };
+}
+export const flowxSwapActionPlanDataSchema = z.object({
+    requestedIntent: flowxSwapRequestedIntentSchema
+});
+export const flowxSwapActionPlanIdentitySchema = z.object({
+    actionKind: z.literal(FLOWX_SWAP_ACTION_KIND),
+    adapterId: z.literal(FLOWX_SWAP_ADAPTER_ID),
+    protocol: z.literal(FLOWX_SWAP_PROTOCOL)
+}).passthrough();
+export function isFlowxSwapActionPlanIdentity(plan) {
+    return flowxSwapActionPlanIdentitySchema.safeParse(plan).success;
+}
+export function normalizeFlowxSwapRequestedIntent(input) {
+    const fromSymbol = canonicalFlowxSymbol(input.from.symbol)?.symbol ?? input.from.symbol.trim();
+    const toSymbol = canonicalFlowxSymbol(input.to.symbol)?.symbol ?? input.to.symbol.trim();
+    return {
+        type: FLOWX_SWAP_ACTION_KIND,
+        from: {
+            symbol: fromSymbol,
+            amountDisplay: input.from.amount
+        },
+        to: {
+            symbol: toSymbol
+        },
+        maxSlippageBps: input.maxSlippageBps
+    };
+}

package/dist/adapters/flowx/flowxSwapQuotePolicy.js

@@ -0,0 +1,104 @@
+import { parseDeepbookRawU64 } from "../../core/read/deepbookReadHelpers.js";
+export const FLOWX_REVIEW_QUOTE_STALE_AFTER_MS = 30_000;
+// Same-machine pipelines capture `now` before the network quote fetch, so the
+// fetch timestamp can land slightly "in the future". Treat skew within this
+// tolerance as a fresh quote; beyond it is a clock-integrity violation.
+export const FLOWX_QUOTE_FUTURE_SKEW_TOLERANCE_MS = 5_000;
+export const FLOWX_MAX_SLIPPAGE_BPS = 1000;
+export const FLOWX_MIN_SLIPPAGE_BPS = 1;
+const BPS_DENOMINATOR = 10000n;
+// The FlowX universal router expresses slippage on a 1e6 denominator; one
+// basis point is 100 router units.
+export const FLOWX_ROUTER_SLIPPAGE_UNITS_PER_BPS = 100;
+export function deriveFlowxSwapQuotePolicy(input) {
+    assertSlippageBps(input.maxSlippageBps);
+    const staleAfterMs = input.staleAfterMs ?? FLOWX_REVIEW_QUOTE_STALE_AFTER_MS;
+    if (!Number.isInteger(staleAfterMs) || staleAfterMs < 1) {
+        throw new Error("staleAfterMs must be a positive integer");
+    }
+    const fetchedAtMs = parseIsoUtcTimestampMs(input.fetchedAt, "fetchedAt");
+    const nowMs = parseValidDateMs(input.now, "now");
+    const rawQuoteAgeMs = nowMs - fetchedAtMs;
+    if (rawQuoteAgeMs < -FLOWX_QUOTE_FUTURE_SKEW_TOLERANCE_MS) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_timestamp_in_future",
+            swapXToY: input.swapXToY,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs: 0,
+            staleAfterMs,
+            clockSkewMs: -rawQuoteAgeMs
+        };
+    }
+    const clockSkewMs = rawQuoteAgeMs < 0 ? -rawQuoteAgeMs : undefined;
+    const quoteAgeMs = rawQuoteAgeMs < 0 ? 0 : rawQuoteAgeMs;
+    if (quoteAgeMs > staleAfterMs) {
+        return {
+            status: "refresh_required",
+            refreshReason: "quote_stale",
+            reason: "quote_stale",
+            swapXToY: input.swapXToY,
+            fetchedAt: input.fetchedAt,
+            quoteAgeMs,
+            staleAfterMs
+        };
+    }
+    const expectedOut = parseDeepbookRawU64(input.amountOutRaw, "amountOutRaw");
+    if (expectedOut === 0n) {
+        return unavailableQuote(input, quoteAgeMs, staleAfterMs, "zero_expected_output");
+    }
+    const minOut = (expectedOut * (BPS_DENOMINATOR - BigInt(input.maxSlippageBps))) / BPS_DENOMINATOR;
+    if (minOut === 0n) {
+        return unavailableQuote(input, quoteAgeMs, staleAfterMs, "zero_min_out");
+    }
+    return {
+        status: "ok",
+        swapXToY: input.swapXToY,
+        quoteFresh: true,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs,
+        ...(clockSkewMs !== undefined ? { clockSkewMs } : {}),
+        maxSlippageBps: input.maxSlippageBps,
+        routerSlippageUnits: input.maxSlippageBps * FLOWX_ROUTER_SLIPPAGE_UNITS_PER_BPS,
+        deadlineMsEpoch: fetchedAtMs + staleAfterMs,
+        sourceAmountRaw: parseDeepbookRawU64(input.amountInRaw, "amountInRaw", { positive: true }).toString(),
+        expectedOutRaw: expectedOut.toString(),
+        minOutRaw: minOut.toString()
+    };
+}
+function assertSlippageBps(value) {
+    if (!Number.isInteger(value) || value < FLOWX_MIN_SLIPPAGE_BPS || value > FLOWX_MAX_SLIPPAGE_BPS) {
+        throw new Error(`maxSlippageBps must be an integer from ${FLOWX_MIN_SLIPPAGE_BPS} to ${FLOWX_MAX_SLIPPAGE_BPS}`);
+    }
+}
+function parseIsoUtcTimestampMs(value, field) {
+    const parsed = new Date(value);
+    const timestampMs = parsed.getTime();
+    if (!Number.isFinite(timestampMs) || parsed.toISOString() !== value) {
+        throw new Error(`${field} must be an ISO 8601 UTC timestamp`);
+    }
+    return timestampMs;
+}
+function parseValidDateMs(value, field) {
+    if (!(value instanceof Date)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    const timestampMs = value.getTime();
+    if (!Number.isFinite(timestampMs)) {
+        throw new Error(`${field} must be a valid Date`);
+    }
+    return timestampMs;
+}
+function unavailableQuote(input, quoteAgeMs, staleAfterMs, reason) {
+    return {
+        status: "refresh_required",
+        refreshReason: "quote_unavailable",
+        reason,
+        swapXToY: input.swapXToY,
+        fetchedAt: input.fetchedAt,
+        quoteAgeMs,
+        staleAfterMs
+    };
+}