@vultisig/rujira 1.0.0

package/dist/utils/format.js

@@ -0,0 +1,213 @@
+/**
+ * Formatting utilities for Rujira SDK
+ * @module utils/format
+ */
+import { findAssetByFormat } from '../assets/index.js';
+/**
+ * Convert human-readable amount to base units
+ *
+ * @param amount - Human readable amount (e.g., "1.5")
+ * @param decimals - Number of decimals
+ * @returns Base units as string
+ *
+ * @example
+ * ```typescript
+ * toBaseUnits("1.5", 8); // "150000000"
+ * toBaseUnits("0.001", 18); // "1000000000000000"
+ * ```
+ */
+export function toBaseUnits(amount, decimals) {
+    const amountStr = amount.toString();
+    const [whole, fraction = ''] = amountStr.split('.');
+    // Pad or truncate fraction to match decimals
+    const paddedFraction = fraction.padEnd(decimals, '0').slice(0, decimals);
+    // Combine and remove leading zeros
+    const result = `${whole}${paddedFraction}`.replace(/^0+/, '') || '0';
+    return result;
+}
+/**
+ * Convert base units to human-readable amount
+ *
+ * @param baseUnits - Amount in base units
+ * @param decimals - Number of decimals
+ * @returns Human readable amount
+ *
+ * @example
+ * ```typescript
+ * fromBaseUnits("150000000", 8); // "1.5"
+ * fromBaseUnits("1000000000000000", 18); // "0.001"
+ * ```
+ */
+export function fromBaseUnits(baseUnits, decimals) {
+    if (decimals === 0)
+        return baseUnits.toString();
+    const str = baseUnits.toString().padStart(decimals + 1, '0');
+    const whole = str.slice(0, -decimals) || '0';
+    const fraction = str.slice(-decimals).replace(/0+$/, '');
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+/**
+ * Format amount for display (truncates fractional digits).
+ * For fee displays where underestimation is harmful, use {@link formatFee} instead.
+ *
+ * @param baseUnits - Amount in base units
+ * @param asset - Asset identifier (any format recognized by the asset registry)
+ * @param maxDecimals - Maximum decimal places to show
+ */
+export function formatAmount(baseUnits, asset, maxDecimals = 6) {
+    const found = findAssetByFormat(asset);
+    if (!found) {
+        return baseUnits.toString();
+    }
+    const human = fromBaseUnits(baseUnits, found.decimals.fin);
+    const parts = human.split('.');
+    const whole = parts[0] || '0';
+    const fraction = parts[1] || '';
+    // Truncate to maxDecimals
+    const truncatedFraction = fraction.slice(0, maxDecimals);
+    // Add thousand separators to whole part
+    const formattedWhole = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    return truncatedFraction ? `${formattedWhole}.${truncatedFraction}` : formattedWhole;
+}
+/**
+ * Format fee amount for display (rounds UP to avoid underestimating costs).
+ * Use this for fee/gas displays where showing less than actual is misleading.
+ *
+ * @param baseUnits - Amount in base units
+ * @param asset - Asset identifier (any format recognized by the asset registry)
+ * @param maxDecimals - Maximum decimal places to show
+ */
+export function formatFee(baseUnits, asset, maxDecimals = 6) {
+    const found = findAssetByFormat(asset);
+    if (!found) {
+        return baseUnits.toString();
+    }
+    const human = fromBaseUnits(baseUnits, found.decimals.fin);
+    const parts = human.split('.');
+    const whole = parts[0] || '0';
+    const fraction = parts[1] || '';
+    if (fraction.length <= maxDecimals) {
+        const formattedWhole = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+        const trimmed = fraction.replace(/0+$/, '');
+        return trimmed ? `${formattedWhole}.${trimmed}` : formattedWhole;
+    }
+    // Round up: if any digit beyond maxDecimals is non-zero, increment last visible digit
+    const visible = fraction.slice(0, maxDecimals);
+    const remainder = fraction.slice(maxDecimals);
+    const hasRemainder = /[1-9]/.test(remainder);
+    if (!hasRemainder) {
+        const trimmed = visible.replace(/0+$/, '');
+        const formattedWhole = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+        return trimmed ? `${formattedWhole}.${trimmed}` : formattedWhole;
+    }
+    // Increment the visible fraction by 1 at the last position
+    const visibleNum = BigInt(visible) + 1n;
+    const roundedFraction = visibleNum.toString().padStart(maxDecimals, '0');
+    // Handle carry (e.g., 999 + 1 = 1000)
+    if (roundedFraction.length > maxDecimals) {
+        const carriedWhole = (BigInt(whole) + 1n).toString();
+        const formattedWhole = carriedWhole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+        return formattedWhole;
+    }
+    const trimmed = roundedFraction.replace(/0+$/, '');
+    const formattedWhole = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    return trimmed ? `${formattedWhole}.${trimmed}` : formattedWhole;
+}
+/**
+ * Calculate minimum return after slippage
+ *
+ * @param expectedOutput - Expected output in base units
+ * @param slippageBps - Slippage tolerance in basis points
+ * @returns Minimum acceptable output
+ */
+export function calculateMinReturn(expectedOutput, slippageBps) {
+    const expected = BigInt(expectedOutput);
+    const slippageAmount = (expected * BigInt(slippageBps)) / 10000n;
+    return (expected - slippageAmount).toString();
+}
+/**
+ * Calculate slippage percentage from expected vs actual
+ *
+ * @param expected - Expected amount
+ * @param actual - Actual amount received
+ * @returns Slippage percentage (negative if worse than expected)
+ */
+export function calculateSlippage(expected, actual) {
+    const exp = BigInt(expected);
+    const act = BigInt(actual);
+    if (exp === 0n)
+        return '0';
+    const diff = act - exp;
+    const percentage = (diff * 10000n) / exp;
+    return (Number(percentage) / 100).toFixed(2);
+}
+/**
+ * Generate a unique quote ID using cryptographic randomness.
+ */
+export function generateQuoteId() {
+    const timestamp = Date.now().toString(36);
+    let random;
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        random = globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 12);
+    }
+    else {
+        // Fallback for environments without crypto.randomUUID
+        random = Math.random().toString(36).slice(2, 10);
+    }
+    return `quote-${timestamp}-${random}`;
+}
+/**
+ * Build a swap message from parameters
+ *
+ * @param minReturn - Minimum return amount
+ * @param to - Destination address (optional)
+ */
+export function buildSwapMsg(minReturn, to) {
+    return {
+        swap: {
+            min: {
+                min_return: minReturn,
+                to,
+            },
+        },
+    };
+}
+/**
+ * Truncate string in the middle (for addresses)
+ *
+ * @param str - String to truncate
+ * @param startChars - Characters to show at start
+ * @param endChars - Characters to show at end
+ */
+export function truncateMiddle(str, startChars = 8, endChars = 6) {
+    if (str.length <= startChars + endChars) {
+        return str;
+    }
+    return `${str.slice(0, startChars)}...${str.slice(-endChars)}`;
+}
+/**
+ * Format percentage for display
+ *
+ * @param value - Decimal value (e.g., 0.015 for 1.5%)
+ * @param decimals - Decimal places to show
+ */
+export function formatPercentage(value, decimals = 2) {
+    const num = typeof value === 'string' ? parseFloat(value) : value;
+    return `${(num * 100).toFixed(decimals)}%`;
+}
+/**
+ * Format basis points as percentage
+ *
+ * @param bps - Basis points
+ */
+export function bpsToPercent(bps) {
+    return `${(bps / 100).toFixed(2)}%`;
+}
+/**
+ * Convert percentage to basis points
+ *
+ * @param percent - Percentage (e.g., 1.5 for 1.5%)
+ */
+export function percentToBps(percent) {
+    return Math.round(percent * 100);
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility exports
+ * @module utils
+ */
+export * from './cache.js';
+export * from './denom-conversion.js';
+export * from './format.js';
+export * from './memo.js';
+export * from './rate-limiter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA"}

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Utility exports
+ * @module utils
+ */
+export * from './cache.js';
+export * from './denom-conversion.js';
+export * from './format.js';
+export * from './memo.js';
+export * from './rate-limiter.js';

package/dist/utils/memo.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Memo utilities for THORChain transactions
+ * @module utils/memo
+ */
+/**
+ * Validate a memo component does not contain delimiter characters.
+ * THORChain memos use ':' as field separator - any ':' in user input
+ * would corrupt memo parsing and could enable injection attacks.
+ *
+ * @param value - The memo component to validate
+ * @param fieldName - Name of the field (for error messages)
+ * @throws Error if the value contains ':'
+ */
+export declare function validateMemoComponent(value: string, fieldName: string): void;
+/**
+ * Build a CosmWasm execution memo for Layer 1 deposits
+ *
+ * Format: x:{contract}:{base64_payload}
+ *
+ * @param contractAddress - CosmWasm contract address
+ * @param msg - Execute message to encode
+ * @returns Formatted memo string
+ *
+ * @example
+ * ```typescript
+ * const memo = buildExecuteMemo('thor1...fin...', {
+ *   swap: { min: { min_return: '1000000' } }
+ * });
+ * // Returns: "x:thor1...fin...:eyJzd2FwIjp7Im1pbiI6eyJtaW5fcmV0dXJuIjoiMTAwMDAwMCJ9fX0="
+ * ```
+ */
+export declare function buildExecuteMemo(contractAddress: string, msg: object): string;
+/**
+ * Parse a CosmWasm execution memo
+ *
+ * @param memo - Memo string to parse
+ * @returns Parsed memo or null if invalid
+ */
+export declare function parseExecuteMemo(memo: string): {
+    contract: string;
+    msg: object;
+} | null;
+/**
+ * Build a swap memo for Layer 1 deposits
+ *
+ * @param contractAddress - FIN contract address
+ * @param minReturn - Minimum return amount
+ * @param destination - Destination address (optional)
+ * @returns Formatted memo
+ */
+export declare function buildSwapMemo(contractAddress: string, minReturn: string, destination?: string): string;
+/**
+ * Build a standard THORChain swap memo
+ *
+ * Format: =:ASSET:DESTINATION:LIMIT:AFFILIATE:FEE
+ *
+ * @param asset - Destination asset (e.g., "BTC.BTC")
+ * @param destination - Destination address
+ * @param limit - Minimum output (optional)
+ * @param affiliate - Affiliate address (optional)
+ * @param affiliateFee - Affiliate fee in basis points (optional)
+ */
+export declare function buildThorSwapMemo(asset: string, destination: string, limit?: string, affiliate?: string, affiliateFee?: number): string;
+/**
+ * Build a secured asset mint memo
+ *
+ * Format: secure+:DESTINATION
+ *
+ * @param destination - THORChain address to receive secured asset
+ */
+export declare function buildSecureMintMemo(destination: string): string;
+/**
+ * Build a secured asset redeem memo
+ *
+ * Format: secure-:DESTINATION
+ *
+ * @param destination - L1 address to receive native asset
+ */
+export declare function buildSecureRedeemMemo(destination: string): string;
+/**
+ * Parse a THORChain memo to determine its type
+ */
+export declare function parseMemoType(memo: string): {
+    type: 'swap';
+    asset: string;
+    destination: string;
+} | {
+    type: 'execute';
+    contract: string;
+} | {
+    type: 'secure-mint';
+    destination: string;
+} | {
+    type: 'secure-redeem';
+    destination: string;
+} | {
+    type: 'unknown';
+};
+/**
+ * Validate memo length (THORChain has a limit)
+ */
+export declare function validateMemoLength(memo: string, maxLength?: number): boolean;
+/**
+ * Estimate memo length for a swap
+ */
+export declare function estimateSwapMemoLength(contractAddress: string, minReturn: string, destination?: string): number;
+//# sourceMappingURL=memo.d.ts.map

package/dist/utils/memo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../src/utils/memo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAI5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAS7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,IAAI,CAuBP;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAUtG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAsBR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,GAEV;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAiCtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/G"}

package/dist/utils/memo.js

@@ -0,0 +1,190 @@
+/**
+ * Memo utilities for THORChain transactions
+ * @module utils/memo
+ */
+import { base64Decode, base64Encode } from './encoding.js';
+/**
+ * Validate a memo component does not contain delimiter characters.
+ * THORChain memos use ':' as field separator - any ':' in user input
+ * would corrupt memo parsing and could enable injection attacks.
+ *
+ * @param value - The memo component to validate
+ * @param fieldName - Name of the field (for error messages)
+ * @throws Error if the value contains ':'
+ */
+export function validateMemoComponent(value, fieldName) {
+    if (value.includes(':')) {
+        throw new Error(`Invalid ${fieldName}: contains ':' which would corrupt memo parsing. Got: ${value}`);
+    }
+}
+/**
+ * Build a CosmWasm execution memo for Layer 1 deposits
+ *
+ * Format: x:{contract}:{base64_payload}
+ *
+ * @param contractAddress - CosmWasm contract address
+ * @param msg - Execute message to encode
+ * @returns Formatted memo string
+ *
+ * @example
+ * ```typescript
+ * const memo = buildExecuteMemo('thor1...fin...', {
+ *   swap: { min: { min_return: '1000000' } }
+ * });
+ * // Returns: "x:thor1...fin...:eyJzd2FwIjp7Im1pbiI6eyJtaW5fcmV0dXJuIjoiMTAwMDAwMCJ9fX0="
+ * ```
+ */
+export function buildExecuteMemo(contractAddress, msg) {
+    const msgBase64 = base64Encode(JSON.stringify(msg));
+    const memo = `x:${contractAddress}:${msgBase64}`;
+    if (!validateMemoLength(memo)) {
+        throw new Error(`Memo exceeds THORChain 250-char limit (${memo.length} chars). Simplify the message or use a shorter contract address.`);
+    }
+    return memo;
+}
+/**
+ * Parse a CosmWasm execution memo
+ *
+ * @param memo - Memo string to parse
+ * @returns Parsed memo or null if invalid
+ */
+export function parseExecuteMemo(memo) {
+    if (!memo.startsWith('x:')) {
+        return null;
+    }
+    const parts = memo.split(':');
+    if (parts.length !== 3) {
+        return null;
+    }
+    const contract = parts[1];
+    const msgBase64 = parts[2];
+    if (!contract || !msgBase64) {
+        return null;
+    }
+    try {
+        const msg = JSON.parse(base64Decode(msgBase64));
+        return { contract, msg };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a swap memo for Layer 1 deposits
+ *
+ * @param contractAddress - FIN contract address
+ * @param minReturn - Minimum return amount
+ * @param destination - Destination address (optional)
+ * @returns Formatted memo
+ */
+export function buildSwapMemo(contractAddress, minReturn, destination) {
+    const msg = {
+        swap: {
+            min: {
+                min_return: minReturn,
+                to: destination,
+            },
+        },
+    };
+    return buildExecuteMemo(contractAddress, msg);
+}
+/**
+ * Build a standard THORChain swap memo
+ *
+ * Format: =:ASSET:DESTINATION:LIMIT:AFFILIATE:FEE
+ *
+ * @param asset - Destination asset (e.g., "BTC.BTC")
+ * @param destination - Destination address
+ * @param limit - Minimum output (optional)
+ * @param affiliate - Affiliate address (optional)
+ * @param affiliateFee - Affiliate fee in basis points (optional)
+ */
+export function buildThorSwapMemo(asset, destination, limit, affiliate, affiliateFee) {
+    validateMemoComponent(asset, 'asset');
+    validateMemoComponent(destination, 'destination');
+    if (limit)
+        validateMemoComponent(limit, 'limit');
+    if (affiliate)
+        validateMemoComponent(affiliate, 'affiliate');
+    const parts = ['=', asset, destination];
+    if (limit) {
+        parts.push(limit);
+        if (affiliate && affiliateFee) {
+            parts.push(affiliate);
+            parts.push(affiliateFee.toString());
+        }
+    }
+    const memo = parts.join(':');
+    if (!validateMemoLength(memo)) {
+        throw new Error(`Memo exceeds THORChain 250-char limit (${memo.length} chars).`);
+    }
+    return memo;
+}
+/**
+ * Build a secured asset mint memo
+ *
+ * Format: secure+:DESTINATION
+ *
+ * @param destination - THORChain address to receive secured asset
+ */
+export function buildSecureMintMemo(destination) {
+    validateMemoComponent(destination, 'destination');
+    return `secure+:${destination}`;
+}
+/**
+ * Build a secured asset redeem memo
+ *
+ * Format: secure-:DESTINATION
+ *
+ * @param destination - L1 address to receive native asset
+ */
+export function buildSecureRedeemMemo(destination) {
+    validateMemoComponent(destination, 'destination');
+    return `secure-:${destination}`;
+}
+/**
+ * Parse a THORChain memo to determine its type
+ */
+export function parseMemoType(memo) {
+    if (memo.startsWith('=:')) {
+        const parts = memo.split(':');
+        return {
+            type: 'swap',
+            asset: parts[1] || '',
+            destination: parts[2] || '',
+        };
+    }
+    if (memo.startsWith('x:')) {
+        const parts = memo.split(':');
+        return {
+            type: 'execute',
+            contract: parts[1] || '',
+        };
+    }
+    if (memo.startsWith('secure+:')) {
+        return {
+            type: 'secure-mint',
+            destination: memo.slice('secure+:'.length),
+        };
+    }
+    if (memo.startsWith('secure-:')) {
+        return {
+            type: 'secure-redeem',
+            destination: memo.slice('secure-:'.length),
+        };
+    }
+    return { type: 'unknown' };
+}
+/**
+ * Validate memo length (THORChain has a limit)
+ */
+export function validateMemoLength(memo, maxLength = 250) {
+    return memo.length <= maxLength;
+}
+/**
+ * Estimate memo length for a swap
+ */
+export function estimateSwapMemoLength(contractAddress, minReturn, destination) {
+    const memo = buildSwapMemo(contractAddress, minReturn, destination);
+    return memo.length;
+}

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Token bucket rate limiter for THORNode API calls.
+ *
+ * THORChain quote endpoints are rate-limited to 1 request/second per IP.
+ * This limiter ensures all SDK HTTP calls to THORNode respect that limit.
+ *
+ * @module utils/rate-limiter
+ */
+export type RateLimiterOptions = {
+    /** Maximum requests per interval (default: 1) */
+    maxTokens?: number;
+    /** Interval in milliseconds to refill one token (default: 1000 = 1 req/sec) */
+    refillIntervalMs?: number;
+};
+export declare class RateLimiter {
+    private tokens;
+    private readonly maxTokens;
+    private readonly refillIntervalMs;
+    private lastRefill;
+    private queue;
+    constructor(options?: RateLimiterOptions);
+    private refill;
+    private processQueue;
+    /**
+     * Acquire a token. Resolves when a request slot is available.
+     * Use before each HTTP call to THORNode.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Wrap a fetch call with rate limiting.
+     */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** Number of pending requests in queue */
+    get pending(): number;
+}
+/** Shared rate limiter for all THORNode API calls (1 req/sec) */
+export declare const thornodeRateLimiter: RateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,KAAK,CAAwB;gBAEzB,OAAO,GAAE,kBAAuB;IAO5C,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,YAAY;IAapB;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B;;OAEG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAK/D,0CAA0C;IAC1C,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;AAED,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,aAA4D,CAAA"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,67 @@
+/**
+ * Token bucket rate limiter for THORNode API calls.
+ *
+ * THORChain quote endpoints are rate-limited to 1 request/second per IP.
+ * This limiter ensures all SDK HTTP calls to THORNode respect that limit.
+ *
+ * @module utils/rate-limiter
+ */
+export class RateLimiter {
+    constructor(options = {}) {
+        this.queue = [];
+        this.maxTokens = options.maxTokens ?? 1;
+        this.refillIntervalMs = options.refillIntervalMs ?? 1000;
+        this.tokens = this.maxTokens;
+        this.lastRefill = Date.now();
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const newTokens = Math.floor(elapsed / this.refillIntervalMs);
+        if (newTokens > 0) {
+            this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+            this.lastRefill = now;
+        }
+    }
+    processQueue() {
+        this.refill();
+        while (this.queue.length > 0 && this.tokens > 0) {
+            this.tokens--;
+            const resolve = this.queue.shift();
+            resolve();
+        }
+        if (this.queue.length > 0) {
+            setTimeout(() => this.processQueue(), this.refillIntervalMs);
+        }
+    }
+    /**
+     * Acquire a token. Resolves when a request slot is available.
+     * Use before each HTTP call to THORNode.
+     */
+    async acquire() {
+        this.refill();
+        if (this.tokens > 0) {
+            this.tokens--;
+            return;
+        }
+        return new Promise(resolve => {
+            this.queue.push(resolve);
+            if (this.queue.length === 1) {
+                setTimeout(() => this.processQueue(), this.refillIntervalMs);
+            }
+        });
+    }
+    /**
+     * Wrap a fetch call with rate limiting.
+     */
+    async fetch(url, init) {
+        await this.acquire();
+        return fetch(url, init);
+    }
+    /** Number of pending requests in queue */
+    get pending() {
+        return this.queue.length;
+    }
+}
+/** Shared rate limiter for all THORNode API calls (1 req/sec) */
+export const thornodeRateLimiter = new RateLimiter({ maxTokens: 1, refillIntervalMs: 1000 });

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,22 @@
+import type { Asset } from '../assets/index.js';
+/**
+ * Type guard to check if an object is a valid Asset with a secured FIN denom.
+ * Secured assets follow the `chain-symbol` pattern (e.g., `btc-btc`, `eth-usdc-0xa0b8...`).
+ * Native tokens (`rune`, `tcy`) and module tokens (`x/ruji`) are excluded.
+ * @internal
+ */
+export declare function isFinAsset(obj: unknown): obj is Asset & {
+    formats: {
+        fin: string;
+    };
+};
+/**
+ * Parse a THORChain asset string into chain and symbol components.
+ * @param asset - Asset string (e.g., "BTC.BTC", "ETH.USDC-0xA0b8...")
+ * @internal
+ */
+export declare function parseAsset(asset: string): {
+    chain: string;
+    symbol: string;
+};
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/utils/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../../src/utils/type-guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE/C;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,KAAK,GAAG;IAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CASpF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAM3E"}