@andrewkimjoseph/celina-sdk 0.9.7 → 0.9.9

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

@@ -0,0 +1,29 @@
+/** CELO mainnet account snapshot for a wallet or contract address. */
+export class AccountService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    /**
+     * Fetch CELO balance, nonce, and whether the address has contract bytecode.
+     * @param address - Wallet or contract address on Celo mainnet
+     * @returns Balance in wei and CELO, current nonce, and `isContract` flag
+     */
+    async getAccount(address) {
+        const { public: client } = this.clientFactory.getClients();
+        const [balance, nonce, bytecode] = await Promise.all([
+            client.getBalance({ address }),
+            client.getTransactionCount({ address }),
+            client.getCode({ address }),
+        ]);
+        return {
+            address,
+            network: "mainnet",
+            balanceWei: balance.toString(),
+            balanceCelo: Number(balance) / 1e18,
+            nonce,
+            isContract: bytecode !== undefined && bytecode !== "0x",
+        };
+    }
+}
+//# sourceMappingURL=account.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"account.service.js","sourceRoot":"","sources":["../../../src/services/account.service.ts"],"names":[],"mappings":"AAKA,sEAAsE;AACtE,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,aAAgC;QAAhC,kBAAa,GAAb,aAAa,CAAmB;IAAG,CAAC;IAEjE;;;;OAIG;IACH,KAAK,CAAC,UAAU,CAAC,OAAsB;QACrC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAC3D,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACnD,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;YAC9B,MAAM,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,CAAC;YACvC,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;SAC5B,CAAC,CAAC;QAEH,OAAO;YACL,OAAO;YACP,OAAO,EAAE,SAAS;YAClB,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE;YAC9B,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI;YACnC,KAAK;YACL,UAAU,EAAE,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;SACxD,CAAC;IACJ,CAAC;CACF"}

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

@@ -0,0 +1,107 @@
+/**
+ * Chain reads: network status, blocks, and transaction lookups on Celo mainnet.
+ */
+import type { CeloClientFactory } from "../clients/celo-client.js";
+/** Celo mainnet block and transaction queries. */
+export declare class BlockchainService {
+    private readonly clientFactory;
+    constructor(clientFactory: CeloClientFactory);
+    /**
+     * Celo mainnet chain id, latest block number, and current gas price.
+     * @returns Network metadata including `chainId`, `blockNumber`, and `gasPriceWei`
+     */
+    getNetworkStatus(): Promise<{
+        network: string;
+        chainId: number;
+        blockNumber: string;
+        gasPriceWei: string;
+    }>;
+    /**
+     * Fetch a block by number, hash, or tag.
+     * @param blockId - Block number, hash, `latest`, or `pending`
+     * @param options.includeTransactions - When true, include full transaction objects
+     * @returns Block header fields and optional transaction list
+     * @throws When the block is not found
+     */
+    getBlock(blockId: number | string | "latest" | "pending", options?: {
+        includeTransactions?: boolean;
+    }): Promise<{
+        number: string | undefined;
+        hash: `0x${string}` | null;
+        timestamp: string;
+        parentHash: `0x${string}`;
+        gasUsed: string;
+        gasLimit: string;
+        gasUtilization: number;
+        miner: `0x${string}`;
+        transactionCount: number;
+        transactions: (`0x${string}` | {
+            hash: `0x${string}`;
+            from: `0x${string}`;
+            to: `0x${string}` | null;
+            value: string;
+            valueCelo: number;
+            nonce: number;
+            gas: string;
+            gasPrice: string | undefined;
+            gasPriceGwei: number | undefined;
+            input: `0x${string}`;
+            blockNumber: string | undefined;
+            transactionIndex: number | null | undefined;
+            type: string | undefined;
+        })[] | undefined;
+    }>;
+    /**
+     * List recent blocks ending at the chain tip (newest last in the array).
+     * @param count - Number of blocks to return (1–100, default 5)
+     * @param offset - Skip this many blocks from the tip before collecting
+     * @returns Summary fields per block (no full transaction payloads)
+     */
+    getLatestBlocks(count?: number, offset?: number): Promise<{
+        number: string;
+        hash: `0x${string}`;
+        timestamp: string;
+        transactionCount: number;
+        gasUsed: string;
+        gasLimit: string;
+        gasUtilization: number;
+    }[]>;
+    /**
+     * Fetch a transaction and its receipt by hash.
+     * @param hash - Transaction hash
+     * @returns Transaction fields, gas efficiency, and receipt status when mined
+     * @throws When the transaction is not found
+     */
+    getTransaction(hash: `0x${string}`): Promise<{
+        hash: `0x${string}`;
+        from: `0x${string}`;
+        to: `0x${string}` | null;
+        value: string;
+        valueCelo: number;
+        nonce: number;
+        gas: string;
+        gasPrice: string | undefined;
+        gasPriceGwei: number | undefined;
+        input: `0x${string}`;
+        blockNumber: string | undefined;
+        transactionIndex: number | null | undefined;
+        type: string | undefined;
+    } | {
+        status?: string | undefined;
+        gasUsed: string;
+        gasEfficiency: number;
+        hash: `0x${string}`;
+        from: `0x${string}`;
+        to: `0x${string}` | null;
+        value: string;
+        valueCelo: number;
+        nonce: number;
+        gas: string;
+        gasPrice: string | undefined;
+        gasPriceGwei: number | undefined;
+        input: `0x${string}`;
+        blockNumber: string | undefined;
+        transactionIndex: number | null | undefined;
+        type: string | undefined;
+    }>;
+}

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

@@ -0,0 +1,151 @@
+function serializeTransactionSummary(tx, extras) {
+    const base = {
+        hash: tx.hash,
+        from: tx.from,
+        to: tx.to,
+        value: tx.value.toString(),
+        valueCelo: Number(tx.value) / 1e18,
+        nonce: tx.nonce,
+        gas: tx.gas.toString(),
+        gasPrice: tx.gasPrice?.toString(),
+        gasPriceGwei: tx.gasPrice ? Number(tx.gasPrice) / 1e9 : undefined,
+        input: tx.input,
+        blockNumber: tx.blockNumber?.toString(),
+        transactionIndex: tx.transactionIndex,
+        type: tx.type,
+    };
+    if (!extras) {
+        return base;
+    }
+    const gasEfficiency = tx.gas > 0n
+        ? Number((extras.gasUsed * 10000n) / tx.gas) / 100
+        : 0;
+    return {
+        ...base,
+        gasUsed: extras.gasUsed.toString(),
+        gasEfficiency,
+        ...(extras.status !== undefined ? { status: extras.status } : {}),
+    };
+}
+/** Celo mainnet block and transaction queries. */
+export class BlockchainService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    /**
+     * Celo mainnet chain id, latest block number, and current gas price.
+     * @returns Network metadata including `chainId`, `blockNumber`, and `gasPriceWei`
+     */
+    async getNetworkStatus() {
+        const { public: client } = this.clientFactory.getClients();
+        const [chainId, blockNumber, gasPrice] = await Promise.all([
+            client.getChainId(),
+            client.getBlockNumber(),
+            client.getGasPrice(),
+        ]);
+        return {
+            network: "mainnet",
+            chainId,
+            blockNumber: blockNumber.toString(),
+            gasPriceWei: gasPrice.toString(),
+        };
+    }
+    /**
+     * Fetch a block by number, hash, or tag.
+     * @param blockId - Block number, hash, `latest`, or `pending`
+     * @param options.includeTransactions - When true, include full transaction objects
+     * @returns Block header fields and optional transaction list
+     * @throws When the block is not found
+     */
+    async getBlock(blockId, options) {
+        const { public: client } = this.clientFactory.getClients();
+        const includeTransactions = options?.includeTransactions ?? false;
+        const blockParams = typeof blockId === "number"
+            ? {
+                blockNumber: BigInt(blockId),
+                includeTransactions,
+            }
+            : blockId === "latest" || blockId === "pending"
+                ? {
+                    blockTag: blockId,
+                    includeTransactions,
+                }
+                : {
+                    blockHash: blockId,
+                    includeTransactions,
+                };
+        const block = await client.getBlock(blockParams);
+        if (!block) {
+            throw new Error(`Block not found: ${blockId}`);
+        }
+        const gasUtilization = block.gasLimit > 0n
+            ? Number((block.gasUsed * 10000n) / block.gasLimit) / 100
+            : 0;
+        return {
+            number: block.number?.toString(),
+            hash: block.hash,
+            timestamp: block.timestamp.toString(),
+            parentHash: block.parentHash,
+            gasUsed: block.gasUsed.toString(),
+            gasLimit: block.gasLimit.toString(),
+            gasUtilization,
+            miner: block.miner,
+            transactionCount: block.transactions.length,
+            transactions: includeTransactions
+                ? block.transactions.map((tx) => typeof tx === "string"
+                    ? tx
+                    : serializeTransactionSummary(tx))
+                : undefined,
+        };
+    }
+    /**
+     * List recent blocks ending at the chain tip (newest last in the array).
+     * @param count - Number of blocks to return (1–100, default 5)
+     * @param offset - Skip this many blocks from the tip before collecting
+     * @returns Summary fields per block (no full transaction payloads)
+     */
+    async getLatestBlocks(count = 5, offset = 0) {
+        const { public: client } = this.clientFactory.getClients();
+        const latest = await client.getBlockNumber();
+        const safeCount = Math.min(Math.max(count, 1), 100);
+        const safeOffset = Math.max(offset, 0);
+        const start = latest - BigInt(safeOffset + safeCount - 1);
+        const blocks = await Promise.all(Array.from({ length: safeCount }, (_, index) => client.getBlock({ blockNumber: start + BigInt(index) })));
+        return blocks.filter(Boolean).map((block) => {
+            const gasUtilization = block.gasLimit > 0n
+                ? Number((block.gasUsed * 10000n) / block.gasLimit) / 100
+                : 0;
+            return {
+                number: block.number?.toString(),
+                hash: block.hash,
+                timestamp: block.timestamp.toString(),
+                transactionCount: block.transactions.length,
+                gasUsed: block.gasUsed.toString(),
+                gasLimit: block.gasLimit.toString(),
+                gasUtilization,
+            };
+        });
+    }
+    /**
+     * Fetch a transaction and its receipt by hash.
+     * @param hash - Transaction hash
+     * @returns Transaction fields, gas efficiency, and receipt status when mined
+     * @throws When the transaction is not found
+     */
+    async getTransaction(hash) {
+        const { public: client } = this.clientFactory.getClients();
+        const [tx, receipt] = await Promise.all([
+            client.getTransaction({ hash }),
+            client.getTransactionReceipt({ hash }),
+        ]);
+        if (!tx) {
+            throw new Error(`Transaction not found: ${hash}`);
+        }
+        return serializeTransactionSummary(tx, {
+            gasUsed: receipt?.gasUsed ?? 0n,
+            status: receipt?.status,
+        });
+    }
+}
+//# sourceMappingURL=blockchain.service.js.map

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

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

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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"}