@aboutcircles/sdk-utils 0.1.0

package/dist/circlesConverter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Conversions between demurrage and inflationary units in V2 – bit‑identical with the
+ * Solidity reference implementation (ABDK Math 64.64).
+ *
+ * All fixed‑point math uses ABDK’s 64.64 format encoded in `bigint`.
+ */
+export declare class CirclesConverter {
+    /** 1.0 in 64.64 representation */
+    static readonly ONE_64: bigint;
+    /** GAMMA = (0.93)^(1/365.25) * 2^64 */
+    static readonly GAMMA_64: bigint;
+    /** BETA = 1 / GAMMA * 2^64 */
+    static readonly BETA_64: bigint;
+    static readonly SECONDS_PER_DAY: bigint;
+    static readonly INFLATION_DAY_ZERO_UNIX: bigint;
+    static readonly ATTO_FACTOR: bigint;
+    static readonly FACTOR_1E12: bigint;
+    static readonly V1_ACCURACY: bigint;
+    static readonly V1_INFLATION_PCT_NUM: bigint;
+    static readonly V1_INFLATION_PCT_DEN: bigint;
+    static readonly PERIOD_SEC: bigint;
+    /**
+     * Multiplies two 64.64 factors and returns a 64.64 factor.
+     * (a * b) >> 64
+     */
+    private static mul64;
+    /**
+     * Multiplies a 64.64 factor with an unsigned integer (bigint) and truncates.
+     * Equivalent to ABDKMath64x64.mulu.
+     */
+    private static mulU;
+    /**
+     * Exponentiation by squaring for 64.64 factors.
+     * Equivalent to ABDKMath64x64.pow(base, exp).
+     */
+    private static pow64;
+    /** 1.0 in 1 × 10³⁶ representation. */
+    private static readonly ONE_36;
+    /** 0.93^(1 / 365.25) scaled to 1e36 (rounded half-up). */
+    private static readonly GAMMA_36;
+    /** 1 / GAMMA scaled to 1e36 (rounded half-up). */
+    private static readonly BETA_36;
+    /** (a · b) / 1e36 – stays inside the 1e36 domain. */
+    private static mul36;
+    /** Exponentiation for 1e36-scaled factors. */
+    private static pow36;
+    /** Atto‑circles (1e18) → UI circles as JS number (lossless until 2^53‑1). */
+    static attoCirclesToCircles(atto: bigint): number;
+    /** UI circles → atto‑circles (truncates to match Solidity’s rounding). */
+    static circlesToAttoCircles(circles: number): bigint;
+    /** Inflationary → demurraged for explicit day index. */
+    static inflationaryToDemurrage(inflationary: bigint, day: bigint): bigint;
+    /** Demurraged → inflationary for explicit day index. */
+    static demurrageToInflationary(demurraged: bigint, day: bigint): bigint;
+    /** UNIX timestamp (seconds) → Circles day index. */
+    static dayFromTimestamp(unixSeconds: bigint): bigint;
+    /** Demurraged → static circles for “today”. */
+    static attoCirclesToAttoStaticCircles(demurraged: bigint, nowUnixSeconds?: bigint): bigint;
+    /** Static circles → demurraged circles for “today”. */
+    static attoStaticCirclesToAttoCircles(staticCircles: bigint, nowUnixSeconds?: bigint): bigint;
+    /** Inflationary → demurraged (exact, reversible). */
+    static inflationaryToDemurrageExact(inflationary: bigint, day: bigint): bigint;
+    /** Demurraged → inflationary (inverse of the above, exact). */
+    static demurrageToInflationaryExact(demurraged: bigint, day: bigint): bigint;
+    /** Demurraged atto-circles → static atto-circles “today” (loss-less). */
+    static attoCirclesToAttoStaticCirclesExact(demurraged: bigint, nowUnixSeconds?: bigint): bigint;
+    /** Static atto-circles → demurraged atto-circles “today” (loss-less). */
+    static attoStaticCirclesToAttoCirclesExact(staticCircles: bigint, nowUnixSeconds?: bigint): bigint;
+    static truncateToInt64(wei: bigint): bigint;
+    static blowUpToBigInt(sixDecimals: bigint): bigint;
+    static truncateToSixDecimals(wei: bigint): bigint;
+    private static v1InflateFactor;
+    /** CRC → demurraged Circles for a given timestamp. */
+    static attoCrcToAttoCircles(v1Amount: bigint, blockTimestampUtc: bigint): bigint;
+    /** Demurraged Circles → CRC (inverse of the above). */
+    static attoCirclesToAttoCrc(demurraged: bigint, blockTimestampUtc: bigint): bigint;
+    /** Implements the on‑chain formula used during migration. */
+    private static v1ToDemurrage;
+}
+//# sourceMappingURL=circlesConverter.d.ts.map

package/dist/circlesConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circlesConverter.d.ts","sourceRoot":"","sources":["../src/circlesConverter.ts"],"names":[],"mappings":"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"}

package/dist/circlesConverter.js

@@ -0,0 +1,181 @@
+/**
+ * Conversions between demurrage and inflationary units in V2 – bit‑identical with the
+ * Solidity reference implementation (ABDK Math 64.64).
+ *
+ * All fixed‑point math uses ABDK’s 64.64 format encoded in `bigint`.
+ */
+export class CirclesConverter {
+    // ───────────────────────────────── constants ─────────────────────────────────
+    /** 1.0 in 64.64 representation */
+    static ONE_64 = 1n << 64n;
+    /** GAMMA = (0.93)^(1/365.25) * 2^64 */
+    static GAMMA_64 = 18443079296116538654n;
+    /** BETA = 1 / GAMMA * 2^64 */
+    static BETA_64 = 18450409579521241655n;
+    static SECONDS_PER_DAY = 86400n;
+    static INFLATION_DAY_ZERO_UNIX = 1602720000n; // 2020‑10‑15 00:00:00 UTC
+    static ATTO_FACTOR = 1000000000000000000n; // 1e18
+    static FACTOR_1E12 = 1000000000000n; // 1e12
+    static V1_ACCURACY = 100000000n; // 1e8
+    static V1_INFLATION_PCT_NUM = 107n;
+    static V1_INFLATION_PCT_DEN = 100n;
+    static PERIOD_SEC = 31556952n; // 365.25 days
+    // ───────────────────────────── fixed‑point helpers ───────────────────────────
+    /**
+     * Multiplies two 64.64 factors and returns a 64.64 factor.
+     * (a * b) >> 64
+     */
+    static mul64(a, b) {
+        return (a * b) >> 64n;
+    }
+    /**
+     * Multiplies a 64.64 factor with an unsigned integer (bigint) and truncates.
+     * Equivalent to ABDKMath64x64.mulu.
+     */
+    static mulU(factor64x64, value) {
+        return (factor64x64 * value) >> 64n;
+    }
+    /**
+     * Exponentiation by squaring for 64.64 factors.
+     * Equivalent to ABDKMath64x64.pow(base, exp).
+     */
+    static pow64(base64x64, exp) {
+        let base = base64x64;
+        let exponent = exp;
+        let result = this.ONE_64;
+        while (exponent > 0n) {
+            if ((exponent & 1n) === 1n) {
+                result = this.mul64(result, base);
+            }
+            base = this.mul64(base, base);
+            exponent >>= 1n;
+        }
+        return result;
+    }
+    /** 1.0 in 1 × 10³⁶ representation. */
+    static ONE_36 = 1000000000000000000000000000000000000000n; // 1e36
+    /** 0.93^(1 / 365.25) scaled to 1e36 (rounded half-up). */
+    static GAMMA_36 = 999801332008598957430613406568191166n;
+    /** 1 / GAMMA scaled to 1e36 (rounded half-up). */
+    static BETA_36 = 1000198707468214629156271489013303962n;
+    /** (a · b) / 1e36 – stays inside the 1e36 domain. */
+    static mul36(a, b) {
+        return (a * b) / this.ONE_36;
+    }
+    /** Exponentiation for 1e36-scaled factors. */
+    static pow36(base36, exp) {
+        let result = this.ONE_36;
+        let base = base36;
+        let e = exp;
+        while (e > 0n) {
+            const isOdd = (e & 1n) === 1n;
+            if (isOdd) {
+                result = this.mul36(result, base);
+            }
+            base = this.mul36(base, base);
+            e >>= 1n;
+        }
+        return result;
+    }
+    // ───────────────────────────── API: human units ─────────────────────────────
+    /** Atto‑circles (1e18) → UI circles as JS number (lossless until 2^53‑1). */
+    static attoCirclesToCircles(atto) {
+        if (atto === 0n)
+            return 0;
+        // Split integer and fractional parts before casting to preserve precision.
+        const whole = atto / this.ATTO_FACTOR;
+        const frac = atto % this.ATTO_FACTOR;
+        const MAX_SAFE_INT = BigInt(Number.MAX_SAFE_INTEGER);
+        if (whole > MAX_SAFE_INT || whole < -MAX_SAFE_INT) {
+            throw new RangeError('Atto value’s integer component exceeds JS double precision.');
+        }
+        return Number(whole) + Number(frac) / Number(this.ATTO_FACTOR);
+    }
+    /** UI circles → atto‑circles (truncates to match Solidity’s rounding). */
+    static circlesToAttoCircles(circles) {
+        return BigInt(Math.trunc(circles * Number(this.ATTO_FACTOR)));
+    }
+    // ───────────────────────────── API: demurrage math ──────────────────────────
+    /** Inflationary → demurraged for explicit day index. */
+    static inflationaryToDemurrage(inflationary, day) {
+        return this.mulU(this.pow64(this.GAMMA_64, day), inflationary);
+    }
+    /** Demurraged → inflationary for explicit day index. */
+    static demurrageToInflationary(demurraged, day) {
+        return this.mulU(this.pow64(this.BETA_64, day), demurraged);
+    }
+    /** UNIX timestamp (seconds) → Circles day index. */
+    static dayFromTimestamp(unixSeconds) {
+        return (unixSeconds - this.INFLATION_DAY_ZERO_UNIX) / this.SECONDS_PER_DAY;
+    }
+    /** Demurraged → static circles for “today”. */
+    static attoCirclesToAttoStaticCircles(demurraged, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1000))) {
+        return this.demurrageToInflationary(demurraged, this.dayFromTimestamp(nowUnixSeconds));
+    }
+    /** Static circles → demurraged circles for “today”. */
+    static attoStaticCirclesToAttoCircles(staticCircles, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1000))) {
+        return this.inflationaryToDemurrage(staticCircles, this.dayFromTimestamp(nowUnixSeconds));
+    }
+    /** Inflationary → demurraged (exact, reversible). */
+    static inflationaryToDemurrageExact(inflationary, day) {
+        const factor = this.pow36(this.GAMMA_36, day);
+        return (inflationary * factor) / this.ONE_36;
+    }
+    /** Demurraged → inflationary (inverse of the above, exact). */
+    static demurrageToInflationaryExact(demurraged, day) {
+        const factor = this.pow36(this.BETA_36, day);
+        return (demurraged * factor) / this.ONE_36;
+    }
+    /** Demurraged atto-circles → static atto-circles “today” (loss-less). */
+    static attoCirclesToAttoStaticCirclesExact(demurraged, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1000))) {
+        const day = this.dayFromTimestamp(nowUnixSeconds);
+        return this.demurrageToInflationaryExact(demurraged, day);
+    }
+    /** Static atto-circles → demurraged atto-circles “today” (loss-less). */
+    static attoStaticCirclesToAttoCirclesExact(staticCircles, nowUnixSeconds = BigInt(Math.floor(Date.now() / 1000))) {
+        const day = this.dayFromTimestamp(nowUnixSeconds);
+        return this.inflationaryToDemurrageExact(staticCircles, day);
+    }
+    // ───────────────────── utilities for 6‑decimal truncation ───────────────────
+    static truncateToInt64(wei) {
+        const truncated = wei / this.FACTOR_1E12;
+        const MAX_INT64 = 9223372036854775807n;
+        return truncated > MAX_INT64 ? MAX_INT64 : truncated;
+    }
+    static blowUpToBigInt(sixDecimals) {
+        return sixDecimals * this.FACTOR_1E12;
+    }
+    static truncateToSixDecimals(wei) {
+        return this.blowUpToBigInt(this.truncateToInt64(wei));
+    }
+    // ───────────────────────── v1 → v2 migration helpers ─────────────────────────
+    static v1InflateFactor(periodIdx) {
+        if (periodIdx === 0n)
+            return this.V1_ACCURACY;
+        return (this.V1_ACCURACY * this.V1_INFLATION_PCT_NUM ** periodIdx) / (this.V1_INFLATION_PCT_DEN ** periodIdx);
+    }
+    /** CRC → demurraged Circles for a given timestamp. */
+    static attoCrcToAttoCircles(v1Amount, blockTimestampUtc) {
+        const secondsSinceEpoch = blockTimestampUtc - this.INFLATION_DAY_ZERO_UNIX;
+        const periodIdx = secondsSinceEpoch / this.PERIOD_SEC;
+        const secondsIntoPeriod = secondsSinceEpoch % this.PERIOD_SEC;
+        const factorCur = this.v1InflateFactor(periodIdx);
+        const factorNext = this.v1InflateFactor(periodIdx + 1n);
+        return this.v1ToDemurrage(v1Amount, factorCur, factorNext, secondsIntoPeriod, this.PERIOD_SEC);
+    }
+    /** Demurraged Circles → CRC (inverse of the above). */
+    static attoCirclesToAttoCrc(demurraged, blockTimestampUtc) {
+        const secondsSinceEpoch = blockTimestampUtc - this.INFLATION_DAY_ZERO_UNIX;
+        const periodIdx = secondsSinceEpoch / this.PERIOD_SEC;
+        const secondsIntoPeriod = secondsSinceEpoch % this.PERIOD_SEC;
+        const factorCur = this.v1InflateFactor(periodIdx);
+        const factorNext = this.v1InflateFactor(periodIdx + 1n);
+        const rP = factorCur * (this.PERIOD_SEC - secondsIntoPeriod) + factorNext * secondsIntoPeriod;
+        return (demurraged * 3n * this.V1_ACCURACY * this.PERIOD_SEC) / rP;
+    }
+    /** Implements the on‑chain formula used during migration. */
+    static v1ToDemurrage(v1Amount, factorCur, factorNext, secondsInto, periodSec) {
+        const rP = factorCur * (periodSec - secondsInto) + factorNext * secondsInto;
+        return (v1Amount * 3n * this.V1_ACCURACY * periodSec) / rP;
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+import type { Address } from '@aboutcircles/sdk-types';
+/**
+ * Common constants used across the SDK
+ */
+/**
+ * The zero address (0x0000000000000000000000000000000000000000)
+ */
+export declare const ZERO_ADDRESS: Address;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,OAAsD,CAAC"}

package/dist/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Common constants used across the SDK
+ */
+/**
+ * The zero address (0x0000000000000000000000000000000000000000)
+ */
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';

package/dist/contractErrors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Contract Error Parsing
+ * Utilities for parsing and decoding contract errors from transaction failures
+ */
+import type { Abi } from 'abitype';
+import type { DecodedContractError } from '@aboutcircles/sdk-types';
+import { CirclesError } from './errors';
+/**
+ * Parse contract error from a transaction error
+ *
+ * @param error - The error object from a failed transaction
+ * @param abi - The contract ABI to use for decoding
+ * @returns Decoded error information or null if cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await contract.someFunction();
+ * } catch (error) {
+ *   const decoded = parseContractError(error, hubV2Abi);
+ *   if (decoded) {
+ *     console.log(`Contract error: ${decoded.formattedMessage}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function parseContractError(error: any, abi: Abi): DecodedContractError | null;
+/**
+ * Contract error class for Circles SDK
+ * Extends CirclesError with contract-specific error information
+ */
+export declare class ContractError extends CirclesError<'CORE'> {
+    readonly decodedError?: DecodedContractError;
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+        context?: Record<string, any>;
+        decodedError?: DecodedContractError;
+    });
+    /**
+     * Create a ContractError from a transaction error
+     */
+    static fromTransactionError(error: any, abi: Abi, context?: Record<string, any>): ContractError;
+    /**
+     * Get formatted error message with details
+     */
+    toString(): string;
+}
+//# sourceMappingURL=contractErrors.d.ts.map

package/dist/contractErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contractErrors.d.ts","sourceRoot":"","sources":["../src/contractErrors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA6HxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,GACP,oBAAoB,GAAG,IAAI,CA4B7B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,MAAM,CAAC;IACrD,SAAgB,YAAY,CAAC,EAAE,oBAAoB,CAAC;gBAGlD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9B,YAAY,CAAC,EAAE,oBAAoB,CAAC;KACrC;IAMH;;OAEG;IACH,MAAM,CAAC,oBAAoB,CACzB,KAAK,EAAE,GAAG,EACV,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,aAAa;IA8BhB;;OAEG;IACH,QAAQ,IAAI,MAAM;CAcnB"}

package/dist/contractErrors.js

@@ -0,0 +1,198 @@
+/**
+ * Contract Error Parsing
+ * Utilities for parsing and decoding contract errors from transaction failures
+ */
+import { decodeErrorResult } from './abi';
+import { CirclesError } from './errors';
+/**
+ * Contract error codes mapping
+ * Maps error codes to human-readable messages
+ */
+const ERROR_CODE_MESSAGES = {
+    // CirclesErrorNoArgs codes
+    0x00: 'Avatar already registered',
+    0x01: 'Avatar must be registered before inviting',
+    0x02: 'Invalid invitation',
+    0x03: 'Avatar must be registered',
+    0x04: 'Only self can register',
+    0x05: 'Maximum value reached',
+    0x06: 'Inflationary supply already set',
+    0x07: 'Group has no collateral',
+    0xa1: 'Trust to zero address is not allowed', // This is the error from the example
+    // CirclesInvalidParameter codes
+    0x10: 'Invalid parameter',
+    // @todo Add more
+};
+/**
+ * Extract error data from various error types
+ * Handles viem errors, raw errors, and other formats
+ */
+function extractErrorData(error) {
+    // Check for viem-style error with data in details
+    if (error?.details && typeof error.details === 'string') {
+        const match = error.details.match(/err:\s*(0x[0-9a-fA-F]+)/);
+        if (match) {
+            return match[1];
+        }
+    }
+    // Check for raw data property
+    if (error?.data && typeof error.data === 'string' && error.data.startsWith('0x')) {
+        return error.data;
+    }
+    // Check for revert data in cause chain
+    let currentError = error;
+    while (currentError) {
+        if (currentError.data && typeof currentError.data === 'string') {
+            return currentError.data;
+        }
+        currentError = currentError.cause;
+    }
+    return null;
+}
+/**
+ * Format error message with decoded arguments using ABI information
+ */
+function formatErrorMessage(errorName, args, errorAbi) {
+    if (!args || args.length === 0) {
+        return errorName;
+    }
+    if (!errorAbi || !errorAbi.inputs) {
+        // Fallback if no ABI info
+        const formattedArgs = args.map(arg => {
+            if (typeof arg === 'bigint') {
+                return arg.toString();
+            }
+            return String(arg);
+        }).join(', ');
+        return `${errorName}(${formattedArgs})`;
+    }
+    // Find the "code" parameter if it exists
+    const codeIndex = errorAbi.inputs.findIndex((input) => input.name === 'code' || input.name === '' && input.type === 'uint8');
+    let baseMessage = errorName;
+    let detailsParts = [];
+    // If there's a code parameter, try to get human-readable message
+    if (codeIndex !== -1) {
+        const code = Number(args[codeIndex]);
+        const humanMessage = ERROR_CODE_MESSAGES[code];
+        if (humanMessage) {
+            baseMessage = humanMessage;
+        }
+    }
+    // Format all arguments with their names
+    errorAbi.inputs.forEach((input, index) => {
+        const arg = args[index];
+        const name = input.name || `arg${index}`;
+        // Skip empty-named code parameters as they're used for the base message
+        if (!input.name && input.type === 'uint8') {
+            return;
+        }
+        let formattedValue;
+        if (typeof arg === 'bigint') {
+            formattedValue = arg.toString();
+        }
+        else if (typeof arg === 'string' && arg.startsWith('0x')) {
+            formattedValue = arg; // Keep addresses and hex as-is
+        }
+        else {
+            formattedValue = String(arg);
+        }
+        // Add hex representation for numeric codes
+        if (name === 'code' || input.type === 'uint8') {
+            formattedValue = `0x${Number(arg).toString(16)}`;
+        }
+        detailsParts.push(`${name}: ${formattedValue}`);
+    });
+    // Combine base message with details
+    if (detailsParts.length > 0) {
+        return `${baseMessage} (${detailsParts.join(', ')})`;
+    }
+    return baseMessage;
+}
+/**
+ * Parse contract error from a transaction error
+ *
+ * @param error - The error object from a failed transaction
+ * @param abi - The contract ABI to use for decoding
+ * @returns Decoded error information or null if cannot be parsed
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await contract.someFunction();
+ * } catch (error) {
+ *   const decoded = parseContractError(error, hubV2Abi);
+ *   if (decoded) {
+ *     console.log(`Contract error: ${decoded.formattedMessage}`);
+ *   }
+ * }
+ * ```
+ */
+export function parseContractError(error, abi) {
+    const errorData = extractErrorData(error);
+    if (!errorData) {
+        return null;
+    }
+    const decoded = decodeErrorResult({ abi, data: errorData });
+    if (!decoded) {
+        return null;
+    }
+    // Find the error ABI definition
+    const errorAbi = abi.find(item => item.type === 'error' && item.name === decoded.errorName);
+    const selector = errorData.slice(0, 10);
+    const formattedMessage = formatErrorMessage(decoded.errorName, decoded.args, errorAbi);
+    return {
+        errorName: decoded.errorName,
+        args: decoded.args,
+        selector,
+        rawData: errorData,
+        formattedMessage,
+    };
+}
+/**
+ * Contract error class for Circles SDK
+ * Extends CirclesError with contract-specific error information
+ */
+export class ContractError extends CirclesError {
+    decodedError;
+    constructor(message, options) {
+        super('ContractError', message, { ...options, source: 'CORE' });
+        this.decodedError = options?.decodedError;
+    }
+    /**
+     * Create a ContractError from a transaction error
+     */
+    static fromTransactionError(error, abi, context) {
+        const decoded = parseContractError(error, abi);
+        if (decoded) {
+            return new ContractError(`Transaction failed: ${decoded.formattedMessage}`, {
+                code: decoded.selector,
+                cause: error,
+                context: {
+                    ...context,
+                    errorName: decoded.errorName,
+                    errorArgs: decoded.args,
+                },
+                decodedError: decoded,
+            });
+        }
+        // Fallback if we can't decode the error
+        const message = error?.message || String(error);
+        return new ContractError(`Transaction failed: ${message}`, {
+            cause: error,
+            context,
+        });
+    }
+    /**
+     * Get formatted error message with details
+     */
+    toString() {
+        let result = super.toString();
+        if (this.decodedError) {
+            result += `\nDecoded Error: ${this.decodedError.formattedMessage}`;
+            if (this.decodedError.args && this.decodedError.args.length > 0) {
+                result += `\nArguments: ${JSON.stringify(this.decodedError.args, (_, v) => typeof v === 'bigint' ? v.toString() : v)}`;
+            }
+        }
+        return result;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Circles SDK Error Handling
+ * Provides a structured error system for consistent error handling across the SDK
+ */
+/**
+ * Base error source type
+ * Each package exports its own specific ErrorSource
+ */
+export type BaseErrorSource = 'UTILS' | 'RPC' | 'SDK' | 'CORE' | 'RUNNER' | 'PROFILES' | 'TRANSFERS' | 'EVENTS' | 'PATHFINDER' | 'UNKNOWN';
+/**
+ * Utils package error source
+ */
+export type UtilsErrorSource = 'UTILS' | 'VALIDATION' | 'CONVERSION' | 'ENCODING';
+/**
+ * Base Circles SDK Error
+ * All SDK errors extend from this class
+ */
+export declare class CirclesError<TSource extends string = string> extends Error {
+    readonly name: string;
+    readonly code?: string | number;
+    readonly source: TSource;
+    readonly cause?: unknown;
+    readonly context?: Record<string, any>;
+    constructor(name: string, message: string, options?: {
+        code?: string | number;
+        source?: TSource;
+        cause?: unknown;
+        context?: Record<string, any>;
+    });
+    /**
+     * Convert error to JSON for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string | number | undefined;
+        source: TSource;
+        context: Record<string, any> | undefined;
+        cause: unknown;
+        stack: string | undefined;
+    };
+    /**
+     * Get formatted error message with context
+     */
+    toString(): string;
+}
+/**
+ * Validation errors
+ */
+export declare class ValidationError extends CirclesError<UtilsErrorSource> {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+        context?: Record<string, any>;
+    });
+    /**
+     * Create error for invalid address
+     */
+    static invalidAddress(address: string): ValidationError;
+    /**
+     * Create error for invalid amount
+     */
+    static invalidAmount(amount: any, reason?: string): ValidationError;
+    /**
+     * Create error for missing parameter
+     */
+    static missingParameter(paramName: string): ValidationError;
+    /**
+     * Create error for invalid parameter
+     */
+    static invalidParameter(paramName: string, value: any, reason?: string): ValidationError;
+}
+/**
+ * Encoding/Conversion errors for utils package
+ */
+export declare class EncodingError extends CirclesError<UtilsErrorSource> {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+        context?: Record<string, any>;
+    });
+    /**
+     * Create error for ABI encoding failures
+     */
+    static abiEncoding(functionName: string, cause?: unknown): EncodingError;
+    /**
+     * Create error for CID conversion failures
+     */
+    static cidConversion(cid: string, cause?: unknown): EncodingError;
+}
+/**
+ * Helper to wrap unknown errors into CirclesError
+ */
+export declare function wrapError(error: unknown, source?: string): CirclesError;
+/**
+ * Type guard to check if error is a CirclesError
+ */
+export declare function isCirclesError(error: unknown): error is CirclesError;
+/**
+ * Helper to extract error message safely
+ */
+export declare function getErrorMessage(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,KAAK,GACL,KAAK,GACL,MAAM,GACN,QAAQ,GACR,UAAU,GACV,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,CAAC;AAElF;;;GAGG;AACH,qBAAa,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IACtE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvC,SAAgB,MAAM,EAAE,OAAO,CAAC;IAChC,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAG5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAeH;;OAEG;IACH,MAAM;;;;;;;;;IAeN;;OAEG;IACH,QAAQ,IAAI,MAAM;CAUnB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,YAAY,CAAC,gBAAgB,CAAC;gBAE/D,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAMH;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe;IAOvD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe;IAUnE;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe;IAO3D;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe;CASzF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY,CAAC,gBAAgB,CAAC;gBAE7D,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B;IAKH;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa;IAQxE;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,aAAa;CAOlE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,MAAkB,GAAG,YAAY,CAwBlF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD"}