perp-cli 0.12.15 → 0.14.0

package/dist/relay-swap.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Relay cross-chain swaps (https://api.relay.link, docs https://docs.relay.link) with local
+ * verification of every quote before the master wallet signs anything.
+ *
+ * Flow: POST /quote (EXACT_INPUT, includeProtocolData) → verify → execute the EVM-origin steps
+ * (ERC-20 approve for the exact amount + depository deposit, signed by the OWS master) →
+ * poll GET /intents/status/v3 until success / failure (bounded; unknown → ORDER_PENDING with
+ * the request id).
+ *
+ * Verification follows Relay's "Input Validation" guide
+ * (docs.relay.link/references/api/api_core_concepts/input-validation):
+ *   1. the protocol order (`protocol.v2.orderData`) pays the expected recipient the expected
+ *      currency on the expected chain, takes exactly the requested input, has no extra calls,
+ *      refunds only to the sender / recipient and is not expired;
+ *   2. the order id is recomputed locally (EIP-712 struct hash of the order — a port of
+ *      `getOrderId` from @relay-protocol/settlement-sdk) and must equal `protocol.v2.orderId`;
+ *   3. the deposit transaction pays Relay's canonical depository — PINNED below per chain, never
+ *      taken from the quote — commits to that order id, credits the sender as depositor and moves
+ *      exactly the order's input; an approve step may only approve that depository for the exact
+ *      amount on the origin token. Any other step, target, spender, amount or chain id is refused.
+ *
+ * Mainnet only. Origin must be an EVM chain (the master EVM wallet signs); the destination may be
+ * EVM or Solana. The recipient is always the master wallet's own address — enforced by the CLI.
+ */
+import { type TxSigner } from "./evm-master-tx.js";
+import type { Network } from "./exchanges/venue-types.js";
+export declare const RELAY_API = "https://api.relay.link";
+export interface RelayAsset {
+    /** Token address; native = zero address (EVM) / system program (Solana), per Relay docs. */
+    address: string;
+    /** Pinned decimals — cross-checked against the quote and, for an ERC-20 origin, the chain. */
+    decimals: number;
+    /** USD stablecoin or the chain's native gas token. */
+    kind: "stable" | "native";
+}
+export interface RelayChainDef {
+    /** Relay chain id (EVM chain id; Solana = 792703809). */
+    chainId: number;
+    /** `protocol.v2.chainId` of the chain in Relay orders. */
+    protocolChainId: string;
+    vm: "evm" | "svm";
+    label: string;
+    /** Public JSON-RPC (EVM origins). */
+    rpcUrl: string | null;
+    /** Relay depository (EVM origins) — GET /chains `protocol.v2.depository`. */
+    depository: string | null;
+    assets: Readonly<Record<string, RelayAsset>>;
+}
+/**
+ * Chains + assets the CLI bridges with Relay. Chain ids, protocol chain ids, depository and token
+ * addresses verified 2026-10-05 against GET https://api.relay.link/chains (4663 "robinhood" with
+ * USDG, 792703809 "solana", 56 "bnb", 42161 "arbitrum", 8453 "base") and the token issuers'
+ * address lists (Circle USDC, Tether USDT, Paxos USDG on Robinhood Chain).
+ */
+export declare const RELAY_CHAINS: Readonly<Record<string, RelayChainDef>>;
+/** Default slippage floor for same-value pairs: expected out ≥ amount in × (1 − 3 %). */
+export declare const RELAY_MAX_SLIPPAGE_BPS = 300n;
+/**
+ * Floor on the protocol-GUARANTEED minimum (docs.relay.link: "Compare `minimumAmount`, not
+ * `expectedAmount`"): the order's minimum may be at most this far below the amount in.
+ */
+export declare const RELAY_MAX_GUARANTEED_LOSS_BPS = 600n;
+export declare const RELAY_STATUS_TIMEOUT_MS = 300000;
+export declare const RELAY_STATUS_POLL_MS = 3000;
+export declare function relayChain(name: string): RelayChainDef;
+export declare function relayAsset(chain: string, symbol: string): RelayAsset;
+interface RelayOrderData {
+    version: string;
+    solverChainId: string;
+    solver: string;
+    salt: string;
+    inputs: Array<{
+        payment: {
+            chainId: string;
+            currency: string;
+            amount: string;
+            weight: string;
+        };
+        refunds: Array<{
+            chainId: string;
+            recipient: string;
+            currency: string;
+            minimumAmount: string;
+            deadline: number;
+            extraData: string;
+        }>;
+    }>;
+    output: {
+        chainId: string;
+        deadline: number;
+        calls: string[];
+        extraData: string;
+        payments: Array<{
+            recipient: string;
+            currency: string;
+            minimumAmount: string;
+            expectedAmount: string;
+        }>;
+    };
+    fees: Array<{
+        recipientChainId: string;
+        recipient: string;
+        currencyChainId: string;
+        currency: string;
+        amount: string;
+    }>;
+}
+/** EIP-712 struct hash of a Relay v1 order — must equal `protocol.v2.orderId`. */
+export declare function relayOrderId(o: RelayOrderData): string;
+export interface RelaySwapRequest {
+    from: string;
+    to: string;
+    fromAsset: string;
+    toAsset: string;
+    /** Input amount in token units (decimal string). */
+    amount: string;
+    sender: string;
+    recipient: string;
+}
+/** One transaction of the quote, already checked against the order (see verifyRelaySteps). */
+export interface RelayTx {
+    kind: "approve" | "deposit";
+    to: string;
+    data: string;
+    value: bigint;
+    chainId: number;
+}
+export interface RelaySwapQuote {
+    provider: "relay";
+    requestId: string;
+    orderId: string;
+    from: string;
+    to: string;
+    fromAsset: string;
+    toAsset: string;
+    sender: string;
+    recipient: string;
+    amountIn: string;
+    amountInRaw: string;
+    /** Quoted estimate (order `expectedAmount`). */
+    expectedOut: string;
+    expectedOutRaw: string;
+    /** Floor the protocol enforces at settlement (order `minimumAmount`). */
+    minimumOut: string;
+    minimumOutRaw: string;
+    amountInUsd: string | null;
+    expectedOutUsd: string | null;
+    fees: {
+        originGasUsd: string | null;
+        relayerUsd: string;
+        relayerGasUsd: string | null;
+        relayerServiceUsd: string | null;
+        appUsd: string | null;
+    };
+    /** Relay's `details.totalImpact.percent` (negative = cost). */
+    totalImpactPercent: string | null;
+    timeEstimateSec: number | null;
+    /** Unix seconds after which the order can no longer fill. */
+    deadline: number;
+    /** Verified transactions to send, in order. */
+    txs: RelayTx[];
+}
+/**
+ * The quote's transactions, each checked: chain id = origin, `from` = sender, the approve targets
+ * the origin token and approves only the pinned depository for exactly the input, the deposit pays
+ * the pinned depository, commits to the verified order id, credits the sender and moves exactly
+ * the input. Anything else → POLICY_DENIED.
+ */
+export declare function verifyRelaySteps(steps: unknown, ctx: {
+    origin: RelayChainDef;
+    asset: RelayAsset;
+    amountInRaw: bigint;
+    sender: string;
+    orderId: string;
+}): RelayTx[];
+/** Verify a raw POST /quote response against the request; returns the typed, checked quote. */
+export declare function verifyRelayQuote(raw: unknown, req: RelaySwapRequest, nowSec: number): RelaySwapQuote;
+/** POST /quote (a read) + local verification. */
+export declare function quoteRelaySwap(req: RelaySwapRequest): Promise<RelaySwapQuote>;
+export interface RelayMinOutVerdict {
+    ok: boolean;
+    /** "explicit" = --min-out against the protocol-enforced minimum; "default" = the 3 % rule against the expected output. */
+    rule: "explicit" | "default" | "required";
+    floor: string | null;
+    reason: string;
+}
+/**
+ * Output protection:
+ *   --min-out given → the order's protocol-enforced `minimumAmount` must be ≥ it (Relay docs:
+ *     "Compare minimumAmount, not expectedAmount");
+ *   no --min-out, same-value pair (stable → stable, or the same native asset) → the expected
+ *     output must be ≥ amount in × (1 − 3 %);
+ *   no --min-out, any other pair (stable → native, …) → refused: an explicit --min-out is required.
+ */
+export declare function relayMinOutVerdict(q: RelaySwapQuote, minOut: string | null): RelayMinOutVerdict;
+/** Throws when the quote does not satisfy the output protection (nothing was sent). */
+export declare function assertRelayMinOut(q: RelaySwapQuote, minOut: string | null): RelayMinOutVerdict;
+export interface RelaySwapResult {
+    provider: "relay";
+    requestId: string;
+    status: "success";
+    approveTxHash: string | null;
+    depositTxHash: string;
+    /** Destination transaction hashes reported by Relay. */
+    destinationTxHashes: string[];
+    from: string;
+    to: string;
+    fromAsset: string;
+    toAsset: string;
+    amountIn: string;
+    expectedOut: string;
+    minimumOut: string;
+    recipient: string;
+}
+export interface RelayPollTiming {
+    timeoutMs: number;
+    pollMs: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+/**
+ * Poll GET /intents/status/v3 until the intent is terminal. success → destination tx hashes;
+ * failure / refund → ACTION_REJECTED (definite: Relay did not fill; a refund returns the input);
+ * anything else until the deadline → ORDER_PENDING with the request id and the deposit tx hash.
+ */
+export declare function awaitRelayFill(requestId: string, depositTxHash: string, timing: RelayPollTiming): Promise<string[]>;
+/**
+ * Execute a verified quote: read-only origin checks (chain id, on-chain decimals, balance), the
+ * approve (when the quote has one) and the deposit, then wait for the fill.
+ */
+export declare function executeRelaySwap(network: Network, q: RelaySwapQuote, sign: TxSigner, timing?: RelayPollTiming): Promise<RelaySwapResult>;
+export {};