@andrewkimjoseph/celina-sdk 0.15.1 → 0.15.2

package/build/src/services/contract.service.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Generic contract reads and gas estimates — caller supplies the ABI.
+ */
+import { type Abi } from "viem";
+import type { CeloClientFactory } from "../clients/celo-client.js";
+/** Parameters for a read-only or gas-estimated contract call on Celo mainnet. */
+export interface ContractCallParams {
+    /** Target contract address. */
+    contractAddress: `0x${string}`;
+    /** ABI function name to invoke. */
+    functionName: string;
+    /** Contract ABI JSON (must include `functionName`). */
+    abi: Abi;
+    /** Positional arguments for the function (default `[]`). */
+    functionArgs?: unknown[];
+    /** Optional `msg.sender` for state-dependent view calls. */
+    fromAddress?: `0x${string}`;
+    /** Wei value as decimal string for payable calls (default `"0"`). */
+    value?: string;
+}
+/** Read-only and gas-estimation helpers for arbitrary contracts. */
+export declare class ContractService {
+    private readonly clientFactory;
+    constructor(clientFactory: CeloClientFactory);
+    /**
+     * Simulate a read-only contract call (`eth_call`).
+     * @param params - Contract address, ABI, function name, and optional args
+     * @returns Decoded result on success; `{ success: false, error }` on revert
+     */
+    callFunction(params: ContractCallParams): Promise<{
+        network: "mainnet";
+        contractAddress: `0x${string}`;
+        functionName: string;
+        result: unknown;
+        success: boolean;
+        error?: undefined;
+    } | {
+        network: "mainnet";
+        contractAddress: `0x${string}`;
+        functionName: string;
+        result: null;
+        success: boolean;
+        error: string;
+    }>;
+    /**
+     * Estimate gas for a contract call from `fromAddress`.
+     * @param params - Same as `callFunction` plus required `fromAddress`
+     * @returns Gas estimate, current gas price, and total cost in wei
+     */
+    estimateGas(params: ContractCallParams & {
+        fromAddress: `0x${string}`;
+    }): Promise<{
+        network: "mainnet";
+        contractAddress: `0x${string}`;
+        functionName: string;
+        gasEstimate: string;
+        gasPrice: string;
+        totalCost: string;
+        success: boolean;
+        error?: undefined;
+    } | {
+        network: "mainnet";
+        contractAddress: `0x${string}`;
+        functionName: string;
+        gasEstimate: string;
+        gasPrice: string;
+        totalCost: string;
+        success: boolean;
+        error: string;
+    }>;
+}
+/**
+ * Decode raw calldata result bytes using a single ABI function entry.
+ * @param abi - Contract ABI containing `functionName`
+ * @param functionName - Function whose return types define decoding
+ * @param data - Hex return data from `eth_call`
+ */
+export declare function decodeContractResult(abi: Abi, functionName: string, data: `0x${string}`): readonly unknown[];

package/build/src/services/contract.service.js

@@ -0,0 +1,117 @@
+/**
+ * Generic contract reads and gas estimates — caller supplies the ABI.
+ */
+import { decodeFunctionResult, encodeFunctionData, } from "viem";
+import { normalizeAddress } from "../utils/normalize-address.js";
+function findAbiFunction(abi, functionName) {
+    const fn = abi.find((item) => item.type === "function" && item.name === functionName);
+    if (!fn) {
+        throw new Error(`Function "${functionName}" not found in ABI`);
+    }
+    return fn;
+}
+/** Read-only and gas-estimation helpers for arbitrary contracts. */
+export class ContractService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    /**
+     * Simulate a read-only contract call (`eth_call`).
+     * @param params - Contract address, ABI, function name, and optional args
+     * @returns Decoded result on success; `{ success: false, error }` on revert
+     */
+    async callFunction(params) {
+        const contractAddress = normalizeAddress(params.contractAddress, "contract address");
+        const fromAddress = params.fromAddress
+            ? normalizeAddress(params.fromAddress, "from address")
+            : undefined;
+        const { public: client } = this.clientFactory.getClients();
+        const args = params.functionArgs ?? [];
+        try {
+            const result = await client.readContract({
+                address: contractAddress,
+                abi: params.abi,
+                functionName: params.functionName,
+                args: args,
+                ...(fromAddress ? { account: fromAddress } : {}),
+            });
+            return {
+                network: "mainnet",
+                contractAddress,
+                functionName: params.functionName,
+                result,
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                network: "mainnet",
+                contractAddress,
+                functionName: params.functionName,
+                result: null,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Estimate gas for a contract call from `fromAddress`.
+     * @param params - Same as `callFunction` plus required `fromAddress`
+     * @returns Gas estimate, current gas price, and total cost in wei
+     */
+    async estimateGas(params) {
+        const contractAddress = normalizeAddress(params.contractAddress, "contract address");
+        const fromAddress = normalizeAddress(params.fromAddress, "from address");
+        const { public: client } = this.clientFactory.getClients();
+        const args = params.functionArgs ?? [];
+        const value = params.value ? BigInt(params.value) : 0n;
+        try {
+            const data = encodeFunctionData({
+                abi: params.abi,
+                functionName: params.functionName,
+                args: args,
+            });
+            const gasEstimate = await client.estimateGas({
+                account: fromAddress,
+                to: contractAddress,
+                data,
+                value,
+            });
+            const gasPrice = await client.getGasPrice();
+            const totalCost = gasEstimate * gasPrice;
+            return {
+                network: "mainnet",
+                contractAddress,
+                functionName: params.functionName,
+                gasEstimate: gasEstimate.toString(),
+                gasPrice: gasPrice.toString(),
+                totalCost: totalCost.toString(),
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                network: "mainnet",
+                contractAddress,
+                functionName: params.functionName,
+                gasEstimate: "0",
+                gasPrice: "0",
+                totalCost: "0",
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+/**
+ * Decode raw calldata result bytes using a single ABI function entry.
+ * @param abi - Contract ABI containing `functionName`
+ * @param functionName - Function whose return types define decoding
+ * @param data - Hex return data from `eth_call`
+ */
+export function decodeContractResult(abi, functionName, data) {
+    const fn = findAbiFunction(abi, functionName);
+    return decodeFunctionResult({ abi: [fn], functionName, data });
+}
+//# sourceMappingURL=contract.service.js.map

package/build/src/services/contract.service.js.map

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

package/build/src/services/ens.service.d.ts

@@ -0,0 +1,44 @@
+import { type EnsClientFactory } from "../clients/ens-client.js";
+/** Chain used for ENS resolution. */
+export type EnsResolveChain = "celo" | "ethereum";
+/** Address with optional ENS metadata when input was a name. */
+export type ResolvedRecipient = {
+    address: `0x${string}`;
+    ens?: {
+        name: string;
+        normalizedName: string;
+        /** Present when resolved on Celo (may fall back to Ethereum records). */
+        resolvedVia?: "celo" | "ethereum";
+    };
+};
+/** ENS name and address resolution for send/swap recipients. */
+export declare class EnsService {
+    private readonly ensClientFactory;
+    constructor(ensClientFactory: EnsClientFactory);
+    /**
+     * Resolve an ENS name on Celo or Ethereum to an address.
+     * @param name - ENS name (e.g. `andrewkimjoseph.celo.eth`)
+     * @param chain - `"celo"` tries Celo coin type first, then Ethereum; `"ethereum"` uses ETH only
+     * @throws When no address record exists for the name
+     */
+    resolveEns(name: string, chain?: EnsResolveChain): Promise<{
+        name: string;
+        normalizedName: string;
+        address: `0x${string}`;
+        coinType: string;
+        chain: "ethereum";
+        resolvedVia?: undefined;
+    } | {
+        name: string;
+        normalizedName: string;
+        address: `0x${string}`;
+        coinType: string;
+        chain: "celo";
+        resolvedVia: "celo" | "ethereum";
+    }>;
+    /**
+     * Accept a raw `0x` address or ENS name; returns address plus optional ENS metadata.
+     * @param input - Hex address or ENS name
+     */
+    resolveAddressOrEns(input: string): Promise<ResolvedRecipient>;
+}

package/build/src/services/ens.service.js

@@ -0,0 +1,92 @@
+/**
+ * ENS resolution on Celo (coin type 42220) and Ethereum mainnet.
+ */
+import { toCoinType } from "viem";
+import { celo } from "viem/chains";
+import { getEnsAddress, normalize } from "viem/ens";
+import { ENS_CCIP_GATEWAY, } from "../clients/ens-client.js";
+const ADDRESS_PATTERN = /^0x[a-fA-F0-9]{40}$/;
+/** ENS name and address resolution for send/swap recipients. */
+export class EnsService {
+    ensClientFactory;
+    constructor(ensClientFactory) {
+        this.ensClientFactory = ensClientFactory;
+    }
+    /**
+     * Resolve an ENS name on Celo or Ethereum to an address.
+     * @param name - ENS name (e.g. `andrewkimjoseph.celo.eth`)
+     * @param chain - `"celo"` tries Celo coin type first, then Ethereum; `"ethereum"` uses ETH only
+     * @throws When no address record exists for the name
+     */
+    async resolveEns(name, chain = "celo") {
+        const trimmedName = name.trim();
+        const normalizedName = normalize(trimmedName);
+        const client = this.ensClientFactory.getClient();
+        const gatewayUrls = [ENS_CCIP_GATEWAY];
+        if (chain === "ethereum") {
+            const address = await getEnsAddress(client, {
+                name: normalizedName,
+                gatewayUrls,
+            });
+            if (!address) {
+                throw new Error(`ENS name "${trimmedName}" has no Ethereum address record`);
+            }
+            return {
+                name: trimmedName,
+                normalizedName,
+                address,
+                coinType: "60",
+                chain: "ethereum",
+            };
+        }
+        const celoCoinType = toCoinType(celo.id);
+        let address = await getEnsAddress(client, {
+            name: normalizedName,
+            coinType: celoCoinType,
+            gatewayUrls,
+        });
+        let coinType = celoCoinType.toString();
+        let resolvedVia = "celo";
+        if (!address) {
+            address = await getEnsAddress(client, {
+                name: normalizedName,
+                gatewayUrls,
+            });
+            coinType = "60";
+            resolvedVia = "ethereum";
+        }
+        if (!address) {
+            throw new Error(`ENS name "${trimmedName}" could not be resolved to an address`);
+        }
+        return {
+            name: trimmedName,
+            normalizedName,
+            address,
+            coinType,
+            chain: "celo",
+            resolvedVia,
+        };
+    }
+    /**
+     * Accept a raw `0x` address or ENS name; returns address plus optional ENS metadata.
+     * @param input - Hex address or ENS name
+     */
+    async resolveAddressOrEns(input) {
+        const trimmed = input.trim();
+        if (ADDRESS_PATTERN.test(trimmed)) {
+            return { address: trimmed };
+        }
+        const resolved = await this.resolveEns(trimmed);
+        return {
+            address: resolved.address,
+            ens: {
+                name: resolved.name,
+                normalizedName: resolved.normalizedName,
+                ...(resolved.chain === "celo"
+                    ? { resolvedVia: resolved.resolvedVia }
+                    : {}),
+            },
+        };
+    }
+}
+//# sourceMappingURL=ens.service.js.map

package/build/src/services/ens.service.js.map

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

package/build/src/services/gooddollar.service.d.ts

@@ -0,0 +1,184 @@
+import type { CeloClientFactory } from "../clients/celo-client.js";
+import { type SerializedPreparedFlow } from "../types/prepared.js";
+export type GoodDollarReserveAmountSide = "in" | "out";
+/** Optional parameters for GoodDollar reserve swap prepares. */
+export interface GoodDollarReserveSwapParams {
+    /** Max slippage tolerance in percent (default `0.5`). */
+    slippageTolerance?: number;
+    /** Address receiving output tokens (default: `from`). */
+    recipient?: `0x${string}`;
+    /**
+     * `in` (default): `amount` is token_in spend. `out`: `amount` is desired token_out;
+     * SDK resolves required token_in via MentoBroker `getAmountIn`.
+     */
+    amountSide?: GoodDollarReserveAmountSide;
+}
+export interface GoodDollarReserveQuoteOptions {
+    /** @deprecated Ignored; balance checks run on prepare/estimate only. */
+    from?: `0x${string}`;
+    amountSide?: GoodDollarReserveAmountSide;
+}
+/** GoodDollar IdentityV4 whitelist, reverification, daily UBI claim, and reserve swap preparation. */
+export declare class GoodDollarService {
+    private readonly clientFactory;
+    private readonly tokenService;
+    private readonly attributionTags?;
+    constructor(clientFactory: CeloClientFactory);
+    private getPublicClient;
+    private resolveWhitelistedRoot;
+    private fetchWhitelistingData;
+    /**
+     * How a wallet links to GoodDollar IdentityV4 (root vs connected account).
+     * @param address - Wallet to inspect
+     */
+    getIdentityLink(address: `0x${string}`): Promise<{
+        address: `0x${string}`;
+        contract: "0xC361A6E67822a0EDc17D899227dd9FC50BD62F42";
+        whitelistedRoot: `0x${string}` | null;
+        isConnectedWallet: boolean;
+        isWhitelistedRoot: boolean;
+        connectedTo: `0x${string}` | null;
+        checkedAddress: `0x${string}`;
+        isWhitelisted: boolean;
+    }>;
+    /**
+     * GoodDollar IdentityV4 whitelist status and reverification progress for a wallet.
+     * Resolves connected wallets via Identity `getWhitelistedRoot`.
+     * @param address - Wallet to check against IdentityV4
+     * @returns On-chain status, whitelist dates, field descriptions, and reverification timeline
+     */
+    getWhitelistingInfo(address: `0x${string}`): Promise<{
+        contract: "0xC361A6E67822a0EDc17D899227dd9FC50BD62F42";
+        isWhitelisted: boolean;
+        status: number;
+        statusLabel: string;
+        whitelistedOn: string | null;
+        lastAuthenticatedOn: string | null;
+        fieldDescriptions: {
+            whitelistedOn: string;
+            lastAuthenticatedOn: string;
+        };
+        reverification: {
+            daysSinceLastAuthentication: number;
+            currentReverificationPeriodDays: number;
+            maxReverificationPeriodDays: number;
+            daysUntilReverificationRequired: number;
+            reverificationRequiredOn: string;
+            reverificationProgressPercent: number;
+            isReverificationOverdue: boolean;
+        } | null;
+        identity: {
+            dateAuthenticated: number;
+            dateAdded: number;
+            did: string;
+            whitelistedOnChainId: number;
+            status: number;
+            authCount: number;
+        };
+        address: `0x${string}`;
+        whitelistedRoot: `0x${string}` | null;
+        isConnectedWallet: boolean;
+        checkedAddress: `0x${string}`;
+    }>;
+    /**
+     * Daily UBI claim eligibility for a wallet against UBISchemeV2 on Celo.
+     * Resolves connected wallets via Identity `getWhitelistedRoot`.
+     */
+    getUbiClaimEligibility(address: `0x${string}`): Promise<{
+        address: `0x${string}`;
+        contract: "0x43d72Ff17701B2DA814620735C39C620Ce0ea4A1";
+        whitelistedRoot: `0x${string}` | null;
+        isConnectedWallet: boolean;
+        isEligibleToClaim: boolean;
+        claimableAmount: string;
+        claimableAmountFormatted: string;
+        alreadyClaimedToday: boolean;
+        inClaimCooldown: boolean;
+        lastClaimedAt: string | null;
+        nextClaimAvailableAt: string;
+        secondsUntilNextClaim: string;
+        nextClaimAvailableIn: string;
+        ubiPeriodDay: string;
+        schemePaused: boolean;
+        schemeStarted: boolean;
+        estimatedDailyUbi: string;
+        estimatedDailyUbiFormatted: string;
+        currentDailyUbi: string;
+        currentDailyUbiFormatted: string;
+        reasons: string[];
+        identity: {
+            checkedAddress: `0x${string}`;
+            isWhitelisted: boolean;
+            statusLabel: string;
+            reverification: {
+                daysSinceLastAuthentication: number;
+                currentReverificationPeriodDays: number;
+                maxReverificationPeriodDays: number;
+                daysUntilReverificationRequired: number;
+                reverificationRequiredOn: string;
+                reverificationProgressPercent: number;
+                isReverificationOverdue: boolean;
+            } | null;
+        };
+    }>;
+    /**
+     * Build an unsigned UBISchemeV2 `claim()` transaction for daily G$ UBI.
+     * Validates whitelist, entitlement, and simulates gas before returning steps.
+     */
+    prepareClaimUbi(from: `0x${string}`): Promise<SerializedPreparedFlow>;
+    private resolveReservePair;
+    private reserveOptions;
+    private baseReserveQuoteFields;
+    private resolveReserveAmount;
+    /**
+     * Expected GoodDollar reserve output for G$ ↔ USDm — no wallet required.
+     * Balance checks run on prepare/estimate only.
+     */
+    getReserveQuote(tokenIn: string, tokenOut: string, amount: string, options?: GoodDollarReserveQuoteOptions): Promise<{
+        protocol: "gooddollar_reserve";
+        network: "mainnet";
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        expectedOut: string;
+        amountSide: GoodDollarReserveAmountSide;
+        routeHops: number;
+        broker: "0x88de45906D4F5a57315c133620cfa484cB297541";
+        exchangeProvider: "0x2fFBB49055d487DdBBb0C052Cd7c2a02A7971e41";
+        exchangeId: "0xba77f5c7bb3317643c6d81d1ef3f9913561741d92095f88efa402faf2cbe9124";
+    }>;
+    private buildReserveSwap;
+    private buildReserveApprovalData;
+    private estimateReserveSwapGas;
+    /**
+     * Simulate gas for a GoodDollar reserve swap from `from`, including approval if needed.
+     */
+    estimateReserveSwap(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: GoodDollarReserveSwapParams): Promise<{
+        from: `0x${string}`;
+        recipient: `0x${string}`;
+        amountOutMin: string;
+        approvalNeeded: boolean;
+        approvalGas: string | undefined;
+        swapGas: string;
+        totalGas: string;
+        slippageTolerance: number;
+        protocol: "gooddollar_reserve";
+        network: "mainnet";
+        tokenIn: string;
+        tokenOut: string;
+        amountIn: string;
+        expectedOut: string;
+        amountSide: GoodDollarReserveAmountSide;
+        routeHops: number;
+        broker: "0x88de45906D4F5a57315c133620cfa484cB297541";
+        exchangeProvider: "0x2fFBB49055d487DdBBb0C052Cd7c2a02A7971e41";
+        exchangeId: "0xba77f5c7bb3317643c6d81d1ef3f9913561741d92095f88efa402faf2cbe9124";
+    }>;
+    /**
+     * Build unsigned GoodDollar reserve swap steps (approve + swapIn when needed).
+     */
+    prepareReserveSwap(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: GoodDollarReserveSwapParams): Promise<SerializedPreparedFlow>;
+    private effectiveAuthCount;
+    private fetchReverifyDaysOptions;
+    private buildReverificationProgress;
+}