@vultisig/rujira 12.0.0 → 12.1.0

package/dist/modules/range.js

@@ -0,0 +1,467 @@
+import { RujiraError, RujiraErrorCode, wrapError } from '../errors.js';
+import { base64Encode } from '../utils/encoding.js';
+import { validateThorAddress } from '../validation/address-validator.js';
+const RUJIRA_GRAPHQL_URL = 'https://api.vultisig.com/ruji/api/graphql';
+const GRAPHQL_TIMEOUT_MS = 15_000;
+/** Scale of MOIC and DPI fields in analytics (divide raw bigint by this). */
+export const RANGE_MOIC_SCALE = 1e12;
+/** Scale of APR field in analytics (divide raw bigint by this). */
+export const RANGE_APR_SCALE = 1e10;
+/** Fractional digits used by config Decimal fields (high/low/spread/skew/fee). */
+export const RANGE_CONFIG_DECIMALS = 12;
+/** Fractional digits used by the withdraw share parameter. */
+export const RANGE_WITHDRAW_SHARE_DECIMALS = 4;
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const DECIMAL_12_RE = /^-?\d+(\.\d{1,12})?$/;
+const DECIMAL_4_RE = /^\d+(\.\d{1,4})?$/;
+const IDX_RE = /^\d+$/;
+function assertDecimal12(label, v) {
+    if (typeof v !== 'string' || !DECIMAL_12_RE.test(v)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `${label} must be a Decimal string with up to 12 fractional digits (got ${JSON.stringify(v)})`);
+    }
+}
+function assertDecimal4(label, v) {
+    if (typeof v !== 'string' || !DECIMAL_4_RE.test(v)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `${label} must be a Decimal string with up to 4 fractional digits (got ${JSON.stringify(v)})`);
+    }
+}
+function assertIdx(v) {
+    if (typeof v !== 'string' || !IDX_RE.test(v)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `idx must be a non-negative integer string (got ${JSON.stringify(v)})`);
+    }
+}
+function assertCoin(label, c) {
+    if (!c || typeof c.denom !== 'string' || !c.denom || typeof c.amount !== 'string' || !/^\d+$/.test(c.amount)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `${label} must be a Coin with string denom and integer-string amount`);
+    }
+}
+const RANGE_CONFIG_SCALE = 10n ** BigInt(RANGE_CONFIG_DECIMALS);
+const RANGE_WITHDRAW_SHARE_SCALE = 10n ** BigInt(RANGE_WITHDRAW_SHARE_DECIMALS);
+// Scale a validated Decimal-string (matched by DECIMAL_12_RE / DECIMAL_4_RE) to a BigInt
+// with `decimals` fractional digits. Avoids parseFloat to preserve precision.
+function decimalToScaled(v, decimals) {
+    const scale = 10n ** BigInt(decimals);
+    const sign = v.startsWith('-') ? -1n : 1n;
+    const unsigned = v.startsWith('-') ? v.slice(1) : v;
+    const [whole, fraction = ''] = unsigned.split('.');
+    const paddedFraction = fraction.padEnd(decimals, '0').slice(0, decimals);
+    return sign * (BigInt(whole || '0') * scale + BigInt(paddedFraction || '0'));
+}
+function assertShare(v) {
+    assertDecimal4('share', v);
+    // 0 < share <= 1, compared in scaled BigInt space (reject 0 and >1).
+    const scaled = decimalToScaled(v, RANGE_WITHDRAW_SHARE_DECIMALS);
+    if (!(scaled > 0n && scaled <= RANGE_WITHDRAW_SHARE_SCALE)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `share must be in (0, 1] (got ${v})`);
+    }
+}
+function assertPairAddress(a) {
+    if (typeof a !== 'string') {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `pairAddress must be a bech32 thor1... contract address (got ${JSON.stringify(a)})`);
+    }
+    try {
+        validateThorAddress(a);
+    }
+    catch {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `pairAddress must be a bech32 thor1... contract address (got ${JSON.stringify(a)})`);
+    }
+}
+function assertConfig(c) {
+    assertDecimal12('config.high', c.high);
+    assertDecimal12('config.low', c.low);
+    assertDecimal12('config.spread', c.spread);
+    assertDecimal12('config.skew', c.skew);
+    assertDecimal12('config.fee', c.fee);
+    // Scaled BigInt comparisons — avoids parseFloat so 12dp precision is preserved.
+    const high = decimalToScaled(c.high, RANGE_CONFIG_DECIMALS);
+    const low = decimalToScaled(c.low, RANGE_CONFIG_DECIMALS);
+    const spread = decimalToScaled(c.spread, RANGE_CONFIG_DECIMALS);
+    const fee = decimalToScaled(c.fee, RANGE_CONFIG_DECIMALS);
+    if (low <= 0n) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `config.low (${c.low}) must be > 0`);
+    }
+    if (high <= low) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `config.high (${c.high}) must be > config.low (${c.low})`);
+    }
+    // Spread reasonability: 0 < spread < 1 (contract likely enforces, but catch early).
+    if (!(spread > 0n && spread < RANGE_CONFIG_SCALE)) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `config.spread must be in (0, 1) (got ${c.spread})`);
+    }
+    // Fee must not exceed spread.
+    if (fee < 0n || fee > spread) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `config.fee must be in [0, spread] (got ${c.fee} vs spread ${c.spread})`);
+    }
+}
+async function gqlFetch(query, variables) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), GRAPHQL_TIMEOUT_MS);
+    // Wrap the ENTIRE fetch + body read in one try block so the timeout
+    // covers both phases. Previously `clearTimeout` ran in `finally` right
+    // after `fetch` resolved (headers only), leaving `response.json()` with
+    // no deadline. A slow body stream past GRAPHQL_TIMEOUT_MS would hang
+    // indefinitely — defeating the guard on the exact case we were trying
+    // to protect against.
+    try {
+        const response = await fetch(RUJIRA_GRAPHQL_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, variables }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new RujiraError(RujiraErrorCode.NETWORK_ERROR, `GraphQL request failed: ${response.status}`);
+        }
+        const json = (await response.json());
+        if (json.errors?.length) {
+            throw new RujiraError(RujiraErrorCode.NETWORK_ERROR, `GraphQL errors: ${json.errors[0].message}`);
+        }
+        // Review finding: a malformed backend response (200 OK, no `errors`,
+        // no `data`) would return undefined and downstream callers would
+        // collapse it to "no positions" / "no pair" via their `?? []` / `??
+        // null` fallbacks — masking a real backend/schema break as a silent
+        // empty result. Users would make fund-moving decisions on false
+        // negatives. Reject at the transport boundary instead.
+        if (json.data === undefined || json.data === null) {
+            throw new RujiraError(RujiraErrorCode.NETWORK_ERROR, 'GraphQL response missing `data` field (backend or schema error)');
+        }
+        return json.data;
+    }
+    catch (error) {
+        // AbortError from the timeout above would otherwise fall through to wrapError's
+        // default NETWORK_ERROR branch (its "timeout"/"timed out" string match misses
+        // the "The operation was aborted." message). Translate it to a proper TIMEOUT.
+        // Now covers both `fetch` and `response.json()` abort paths.
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new RujiraError(RujiraErrorCode.TIMEOUT, `GraphQL request timed out after ${GRAPHQL_TIMEOUT_MS}ms`, error, true);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// Query shapes — keep narrow, only fields we surface.
+// NOTE: FinRange + FinPair schema is taken from rujira-ui `TradeSubscriptions`.
+// If upstream schema changes, these queries must be updated in lockstep.
+// Queries follow the schema at api.vultisig.com/ruji/api/graphql as of
+// 2026-04-21. Paths verified via __type introspection:
+//   Account.fin.ranges → FinRangeConnection (Relay edges/node)
+//   FinRange.{idx,base,quote,feesBase,feesQuote,principalUsd,yieldUsd,
+//             high,low,spread,skew,fee,price,valueUsd,pair,analytics}
+// Config fields are FLAT on FinRange (not under a nested config object).
+const POSITIONS_QUERY = `
+  query RangePositions($id: ID!) {
+    node(id: $id) {
+      ... on Account {
+        fin {
+          ranges(first: 100) {
+            edges {
+              node {
+                id idx base quote
+                feesBase feesQuote
+                principalUsd yieldUsd
+                high low spread skew fee price
+                pair { id address }
+                analytics { moic dpi apr firstDepositDate status }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+const POSITION_QUERY = `
+  query RangePosition($id: ID!) {
+    node(id: $id) {
+      ... on FinRange {
+        id idx base quote
+        feesBase feesQuote
+        principalUsd yieldUsd
+        high low spread skew fee price
+        pair { id address }
+        analytics { moic dpi apr firstDepositDate status }
+      }
+    }
+  }
+`;
+// Pair lookup goes through finV3.pairs sorted by volume. We fetch the top N
+// and do (base, quote) matching client-side on symbols AND denoms — tolerating
+// LLM-mangled inputs like "xruji" (stripped "x/ruji") or "thorrune"
+// (stripped "thor.rune") by normalising separators on both sides.
+const PAIR_QUERY = `
+  query FinPairsAll {
+    finV3 {
+      pairs(first: 200, sortBy: VOLUME, sortDir: DESC) {
+        edges {
+          node {
+            address
+            assetBase  { metadata { symbol } variants { native { denom } } }
+            assetQuote { metadata { symbol } variants { native { denom } } }
+          }
+        }
+      }
+    }
+  }
+`;
+function mapRange(r) {
+    if (!r.pair?.address) {
+        throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `FinRange ${r.idx} is missing pair.address (partial/error GraphQL response?)`);
+    }
+    const config = r.high && r.low && r.spread && r.skew !== undefined && r.fee !== undefined
+        ? { high: r.high, low: r.low, spread: r.spread, skew: r.skew, fee: r.fee }
+        : undefined;
+    return {
+        idx: r.idx,
+        pairAddress: r.pair.address,
+        base: r.base,
+        quote: r.quote,
+        feesBase: r.feesBase,
+        feesQuote: r.feesQuote,
+        principalUsd: r.principalUsd,
+        yieldUsd: r.yieldUsd,
+        config,
+        analytics: r.analytics,
+    };
+}
+// ---------------------------------------------------------------------------
+// RujiraRange
+// ---------------------------------------------------------------------------
+/**
+ * Builders + queries for RUJI Trade CCL range positions.
+ *
+ * ExecuteMsg shapes (keep in sync with `rujira-ui` Range.tsx / RangeManage.tsx):
+ *
+ * - create:   `{ range: { create:   { config: { high, low, spread, skew, fee } } } }`
+ * - deposit:  `{ range: { deposit:  { idx } } }`
+ * - withdraw: `{ range: { withdraw: { idx, amount } } }`  (amount is the share Decimal 4dp)
+ * - claim:    `{ range: { claim:    { idx } } }`
+ * - transfer: `{ range: { transfer: { idx, to } } }`
+ */
+export class RujiraRange {
+    constructor(client) {
+        this.client = client;
+    }
+    // ------------------- Builders -------------------
+    buildCreatePosition(params) {
+        assertPairAddress(params.pairAddress);
+        assertConfig(params.config);
+        assertCoin('base', params.base);
+        assertCoin('quote', params.quote);
+        return {
+            contractAddress: params.pairAddress,
+            executeMsg: {
+                range: {
+                    create: {
+                        config: {
+                            high: params.config.high,
+                            low: params.config.low,
+                            spread: params.config.spread,
+                            skew: params.config.skew,
+                            fee: params.config.fee,
+                        },
+                    },
+                },
+            },
+            funds: [params.base, params.quote].sort((a, b) => (a.denom < b.denom ? -1 : 1)),
+        };
+    }
+    buildDeposit(params) {
+        assertPairAddress(params.pairAddress);
+        assertIdx(params.idx);
+        assertCoin('base', params.base);
+        assertCoin('quote', params.quote);
+        return {
+            contractAddress: params.pairAddress,
+            executeMsg: { range: { deposit: { idx: params.idx } } },
+            funds: [params.base, params.quote].sort((a, b) => (a.denom < b.denom ? -1 : 1)),
+        };
+    }
+    buildWithdraw(params) {
+        assertPairAddress(params.pairAddress);
+        assertIdx(params.idx);
+        assertShare(params.share);
+        return {
+            contractAddress: params.pairAddress,
+            executeMsg: { range: { withdraw: { idx: params.idx, amount: params.share } } },
+            funds: [],
+        };
+    }
+    buildClaim(params) {
+        assertPairAddress(params.pairAddress);
+        assertIdx(params.idx);
+        return {
+            contractAddress: params.pairAddress,
+            executeMsg: { range: { claim: { idx: params.idx } } },
+            funds: [],
+        };
+    }
+    buildTransfer(params) {
+        assertPairAddress(params.pairAddress);
+        assertIdx(params.idx);
+        validateThorAddress(params.to);
+        return {
+            contractAddress: params.pairAddress,
+            executeMsg: { range: { transfer: { idx: params.idx, to: params.to } } },
+            funds: [],
+        };
+    }
+    /**
+     * Atomic close: claim fees + withdraw 100%. Emits two MsgExecuteContract
+     * payloads that MUST be signed + broadcast in a single cosmos tx. The order
+     * matters — claim first, then withdraw — to guarantee fees are harvested.
+     */
+    buildWithdrawAll(params) {
+        assertPairAddress(params.pairAddress);
+        assertIdx(params.idx);
+        return {
+            msgs: [
+                {
+                    contractAddress: params.pairAddress,
+                    executeMsg: { range: { claim: { idx: params.idx } } },
+                    funds: [],
+                },
+                {
+                    contractAddress: params.pairAddress,
+                    executeMsg: { range: { withdraw: { idx: params.idx, amount: '1' } } },
+                    funds: [],
+                },
+            ],
+        };
+    }
+    // ------------------- Queries -------------------
+    /**
+     * List open range positions for a THORChain address.
+     * Returns [] when the account has no positions.
+     */
+    async getPositions(owner) {
+        validateThorAddress(owner);
+        try {
+            const nodeId = base64Encode(`Account:${owner}`);
+            const data = await gqlFetch(POSITIONS_QUERY, { id: nodeId });
+            const edges = data?.node?.fin?.ranges?.edges ?? [];
+            // Filter out partial/malformed rows before mapping — mapRange throws on missing pair.address.
+            return edges.filter(e => !!e.node?.pair?.address).map(e => mapRange(e.node));
+        }
+        catch (error) {
+            throw wrapError(error);
+        }
+    }
+    /**
+     * Fetch a single range position by (pairAddress, idx).
+     * Returns null when the position doesn't exist.
+     */
+    async getPosition(pairAddress, idx) {
+        assertPairAddress(pairAddress);
+        assertIdx(idx);
+        try {
+            const nodeId = base64Encode(`FinRange:${pairAddress}:${idx}`);
+            const data = await gqlFetch(POSITION_QUERY, { id: nodeId });
+            if (!data?.node || !data.node.pair?.address)
+                return null;
+            return mapRange(data.node);
+        }
+        catch (error) {
+            throw wrapError(error);
+        }
+    }
+    /**
+     * Resolve a FIN pair contract address from base + quote asset identifiers
+     * (denom or THORChain ticker). Returns null when the pair doesn't exist.
+     */
+    async getPairAddress(base, quote) {
+        if (!base || !quote) {
+            throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, 'base and quote are required');
+        }
+        try {
+            const data = await gqlFetch(PAIR_QUERY, {});
+            const edges = data?.finV3?.pairs?.edges ?? [];
+            // Accept tickers, bank denoms, FIN-pair denoms ("thor.rune"), and
+            // LLM-mangled forms ("xruji" from "x/ruji", "thorrune" from "thor.rune")
+            // by normalising separators out and matching with suffix tolerance
+            // (normalised "thorrune" ends with normalised "rune" → match).
+            const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+            // Three-tier match: exact > prefix > suffix. Exact takes precedence
+            // so ambiguous inputs like "ETH" don't silently match a WETH pair
+            // just because `weth.endsWith("eth")`. We also reject multi-hit
+            // fuzzy ambiguity — if two different pairs would pass the fuzzy
+            // tier, the caller must disambiguate.
+            const matchTier = (input, candidate) => {
+                if (!input || !candidate)
+                    return null;
+                const a = norm(input);
+                const b = norm(candidate);
+                if (a === b)
+                    return 'exact';
+                if (a.endsWith(b) || b.endsWith(a))
+                    return 'fuzzy';
+                return null;
+            };
+            const scoreNode = (n) => {
+                const bs = n.assetBase.metadata?.symbol ?? '';
+                const qs = n.assetQuote.metadata?.symbol ?? '';
+                const bd = n.assetBase.variants?.native?.denom ?? '';
+                const qd = n.assetQuote.variants?.native?.denom ?? '';
+                const baseTier = (() => {
+                    const s = matchTier(base, bs);
+                    const d = matchTier(base, bd);
+                    if (s === 'exact' || d === 'exact')
+                        return 'exact';
+                    if (s === 'fuzzy' || d === 'fuzzy')
+                        return 'fuzzy';
+                    return null;
+                })();
+                const quoteTier = (() => {
+                    const s = matchTier(quote, qs);
+                    const d = matchTier(quote, qd);
+                    if (s === 'exact' || d === 'exact')
+                        return 'exact';
+                    if (s === 'fuzzy' || d === 'fuzzy')
+                        return 'fuzzy';
+                    return null;
+                })();
+                if (!baseTier || !quoteTier)
+                    return null;
+                // Pair is as weak as its weakest side.
+                return baseTier === 'exact' && quoteTier === 'exact' ? 'exact' : 'fuzzy';
+            };
+            const scored = edges.map(e => e.node).map(n => ({ node: n, tier: scoreNode(n) }));
+            const exact = scored.filter(s => s.tier === 'exact').map(s => s.node);
+            const fuzzy = scored.filter(s => s.tier === 'fuzzy').map(s => s.node);
+            let match;
+            if (exact.length === 1) {
+                match = exact[0];
+            }
+            else if (exact.length > 1) {
+                // Multiple exact-match pairs (shouldn't happen on a sane pair
+                // list, but reject rather than pick-first to avoid routing to
+                // the wrong pair).
+                throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `ambiguous pair: ${base}/${quote} matches ${exact.length} pairs exactly`);
+            }
+            else if (fuzzy.length === 1) {
+                match = fuzzy[0];
+            }
+            else if (fuzzy.length > 1) {
+                throw new RujiraError(RujiraErrorCode.INVALID_PARAMS, `ambiguous pair: ${base}/${quote} matches ${fuzzy.length} pairs fuzzily — use exact denoms or tickers`);
+            }
+            if (!match)
+                return null;
+            return {
+                address: match.address,
+                base: {
+                    symbol: match.assetBase.metadata?.symbol ?? base,
+                    denom: match.assetBase.variants?.native?.denom ?? '',
+                },
+                quote: {
+                    symbol: match.assetQuote.metadata?.symbol ?? quote,
+                    denom: match.assetQuote.variants?.native?.denom ?? '',
+                },
+            };
+        }
+        catch (error) {
+            throw wrapError(error);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vultisig/rujira",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "type": "module",
   "description": "Rujira DEX integration for Vultisig SDK - Modular TypeScript SDK for swaps and limit orders on THORChain",
   "main": "./dist/index.js",
@@ -30,6 +30,14 @@
       "import": "./dist/modules/perps.js",
       "types": "./dist/modules/perps.d.ts"
     },
+    "./range": {
+      "import": "./dist/modules/range.js",
+      "types": "./dist/modules/range.d.ts"
+    },
+    "./ccl": {
+      "import": "./dist/ccl/index.js",
+      "types": "./dist/ccl/index.d.ts"
+    },
     "./signer": {
       "import": "./dist/signer/vultisig-provider.js",
       "types": "./dist/signer/vultisig-provider.d.ts"
@@ -67,12 +75,12 @@
   "devDependencies": {
     "@types/big.js": "^6.2.2",
     "@types/node": "^25.5.0",
-    "@vultisig/sdk": "0.17.0",
+    "@vultisig/sdk": "0.17.1",
     "typescript": "^5.9.3",
     "vitest": "^3.0.9"
   },
   "peerDependencies": {
-    "@vultisig/sdk": ">=0.17.0"
+    "@vultisig/sdk": ">=0.17.1"
   },
   "peerDependenciesMeta": {
     "@vultisig/sdk": {