@andrewkimjoseph/celina-sdk 0.1.0 → 0.2.0

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

@@ -0,0 +1,52 @@
+import { type Abi } from "viem";
+import type { CeloClientFactory } from "../clients/celo-client.js";
+export interface ContractCallParams {
+    contractAddress: `0x${string}`;
+    functionName: string;
+    abi: Abi;
+    functionArgs?: unknown[];
+    fromAddress?: `0x${string}`;
+    value?: string;
+}
+export declare class ContractService {
+    private readonly clientFactory;
+    constructor(clientFactory: CeloClientFactory);
+    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;
+    }>;
+    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 — exported for tests. */
+export declare function decodeContractResult(abi: Abi, functionName: string, data: `0x${string}`): readonly unknown[];

package/build/services/contract.service.js

@@ -0,0 +1,102 @@
+import { decodeFunctionResult, encodeFunctionData, isAddress, } from "viem";
+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;
+}
+export class ContractService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    async callFunction(params) {
+        if (!isAddress(params.contractAddress)) {
+            throw new Error(`Invalid contract address: ${params.contractAddress}`);
+        }
+        const { public: client } = this.clientFactory.getClients();
+        const args = params.functionArgs ?? [];
+        try {
+            const result = await client.readContract({
+                address: params.contractAddress,
+                abi: params.abi,
+                functionName: params.functionName,
+                args: args,
+                ...(params.fromAddress
+                    ? { account: params.fromAddress }
+                    : {}),
+            });
+            return {
+                network: "mainnet",
+                contractAddress: params.contractAddress,
+                functionName: params.functionName,
+                result,
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                network: "mainnet",
+                contractAddress: params.contractAddress,
+                functionName: params.functionName,
+                result: null,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async estimateGas(params) {
+        if (!isAddress(params.contractAddress)) {
+            throw new Error(`Invalid contract address: ${params.contractAddress}`);
+        }
+        if (!isAddress(params.fromAddress)) {
+            throw new Error(`Invalid from address: ${params.fromAddress}`);
+        }
+        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: params.fromAddress,
+                to: params.contractAddress,
+                data,
+                value,
+            });
+            const gasPrice = await client.getGasPrice();
+            const totalCost = gasEstimate * gasPrice;
+            return {
+                network: "mainnet",
+                contractAddress: params.contractAddress,
+                functionName: params.functionName,
+                gasEstimate: gasEstimate.toString(),
+                gasPrice: gasPrice.toString(),
+                totalCost: totalCost.toString(),
+                success: true,
+            };
+        }
+        catch (error) {
+            return {
+                network: "mainnet",
+                contractAddress: params.contractAddress,
+                functionName: params.functionName,
+                gasEstimate: "0",
+                gasPrice: "0",
+                totalCost: "0",
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+/** Decode raw calldata result — exported for tests. */
+export function decodeContractResult(abi, functionName, data) {
+    const fn = findAbiFunction(abi, functionName);
+    return decodeFunctionResult({ abi: [fn], functionName, data });
+}
+//# sourceMappingURL=contract.service.js.map

package/build/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/services/ens.service.d.ts

@@ -11,6 +11,7 @@ export type ResolvedRecipient = {
 export declare class EnsService {
     private readonly ensClientFactory;
     constructor(ensClientFactory: EnsClientFactory);
+    /** Resolve an ENS name on Celo or Ethereum to an address. */
     resolveEns(name: string, chain?: EnsResolveChain): Promise<{
         name: string;
         normalizedName: string;
@@ -26,5 +27,6 @@ export declare class EnsService {
         chain: "celo";
         resolvedVia: "celo" | "ethereum";
     }>;
+    /** Accept a raw `0x` address or ENS name; returns address plus optional ENS metadata. */
     resolveAddressOrEns(input: string): Promise<ResolvedRecipient>;
 }

package/build/services/ens.service.js

@@ -8,6 +8,7 @@ export class EnsService {
     constructor(ensClientFactory) {
         this.ensClientFactory = ensClientFactory;
     }
+    /** Resolve an ENS name on Celo or Ethereum to an address. */
     async resolveEns(name, chain = "celo") {
         const trimmedName = name.trim();
         const normalizedName = normalize(trimmedName);
@@ -57,6 +58,7 @@ export class EnsService {
             resolvedVia,
         };
     }
+    /** Accept a raw `0x` address or ENS name; returns address plus optional ENS metadata. */
     async resolveAddressOrEns(input) {
         const trimmed = input.trim();
         if (ADDRESS_PATTERN.test(trimmed)) {

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

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

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

@@ -2,6 +2,7 @@ import type { CeloClientFactory } from "../clients/celo-client.js";
 export declare class GoodDollarService {
     private readonly clientFactory;
     constructor(clientFactory: CeloClientFactory);
+    /** GoodDollar IdentityV4 whitelist status and reverification progress. */
     getWhitelistingInfo(address: `0x${string}`): Promise<{
         address: `0x${string}`;
         contract: "0xC361A6E67822a0EDc17D899227dd9FC50BD62F42";

package/build/services/gooddollar.service.js

@@ -17,6 +17,7 @@ export class GoodDollarService {
     constructor(clientFactory) {
         this.clientFactory = clientFactory;
     }
+    /** GoodDollar IdentityV4 whitelist status and reverification progress. */
     async getWhitelistingInfo(address) {
         const { public: client } = this.clientFactory.getClients();
         const contract = GOODDOLLAR_IDENTITY_ADDRESS;

package/build/services/gooddollar.service.js.map

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

package/build/services/governance.service.d.ts

@@ -0,0 +1,78 @@
+import type { CeloClientFactory } from "../clients/celo-client.js";
+export interface GovernanceProposalsOptions {
+    includeInactive?: boolean;
+    includeMetadata?: boolean;
+    page?: number;
+    pageSize?: number;
+    offset?: number;
+    limit?: number;
+}
+export declare class GovernanceService {
+    private readonly clientFactory;
+    constructor(clientFactory: CeloClientFactory);
+    private getClient;
+    private fetchProposal;
+    private listProposalIds;
+    getGovernanceProposals(options?: GovernanceProposalsOptions): Promise<{
+        network: "mainnet";
+        proposals: {
+            stageName: "Approval" | "None" | "Queued" | "Referendum" | "Execution" | "Executed" | "Expiration" | "Rejected" | "Withdrawn";
+            metadata: Record<string, unknown> | null;
+            id: number;
+            stage: number;
+            timestamp: number;
+            expiryTimestamp: number | null;
+            url: string;
+            proposer: string;
+            deposit: string;
+            numTransactions: number;
+            networkWeight: string;
+            isApproved: boolean;
+            upvotes: number;
+            votes: {
+                yes: string;
+                no: string;
+                abstain: string;
+            };
+        }[];
+        pagination: {
+            total: number;
+            page: number;
+            pageSize: number;
+            totalPages: number;
+            offset: number;
+            limit: number;
+            hasMore: boolean;
+        };
+    }>;
+    getProposalDetails(proposalId: number): Promise<{
+        network: "mainnet";
+        proposal: null;
+        content: null;
+        error: string;
+    } | {
+        network: "mainnet";
+        proposal: {
+            stageName: "Approval" | "None" | "Queued" | "Referendum" | "Execution" | "Executed" | "Expiration" | "Rejected" | "Withdrawn";
+            metadata: Record<string, unknown> | null;
+            id: number;
+            stage: number;
+            timestamp: number;
+            expiryTimestamp: number | null;
+            url: string;
+            proposer: string;
+            deposit: string;
+            numTransactions: number;
+            networkWeight: string;
+            isApproved: boolean;
+            upvotes: number;
+            votes: {
+                yes: string;
+                no: string;
+                abstain: string;
+            };
+        };
+        content: string | null;
+        error: null;
+    }>;
+}

package/build/services/governance.service.js

@@ -0,0 +1,241 @@
+import { CELO_CORE_CONTRACTS } from "../config/celo-core-contracts.js";
+import { governanceAbi, proposalStageName, } from "../abis/governance.js";
+const STAGE_EXPIRY_MS = {
+    Queued: 4 * 24 * 60 * 60 * 1000,
+    Approval: 24 * 60 * 60 * 1000,
+    Referendum: 4 * 24 * 60 * 60 * 1000,
+    Execution: 24 * 60 * 60 * 1000,
+};
+function extractCgpFromUrl(url) {
+    const match = url.match(/cgp-(\d+)/i);
+    return match ? Number(match[1]) : null;
+}
+function parseCgpFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    const yaml = match[1];
+    const result = {};
+    for (const line of yaml.split("\n")) {
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        let value = line.slice(idx + 1).trim();
+        if (typeof value === "string") {
+            value = value.replace(/^["']|["']$/g, "");
+        }
+        result[key] = value;
+    }
+    return result;
+}
+async function fetchCgpMetadata(cgpNumber) {
+    const url = `https://raw.githubusercontent.com/celo-org/governance/main/CGPs/cgp-${String(cgpNumber).padStart(4, "0")}.md`;
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            return null;
+        const raw = await response.text();
+        const frontmatter = parseCgpFrontmatter(raw);
+        const content = raw.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "");
+        return { frontmatter, content };
+    }
+    catch {
+        return null;
+    }
+}
+function getExpiryTimestamp(stage, timestampMs) {
+    const expiry = STAGE_EXPIRY_MS[stage];
+    return expiry ? timestampMs + expiry : null;
+}
+export class GovernanceService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    getClient() {
+        return this.clientFactory.getClients().public;
+    }
+    async fetchProposal(proposalId, upvotes = 0, includeVotes = true) {
+        const client = this.getClient();
+        const address = CELO_CORE_CONTRACTS.governance;
+        try {
+            const [proposalData, stage, voteTotals] = await Promise.all([
+                client.readContract({
+                    address,
+                    abi: governanceAbi,
+                    functionName: "getProposal",
+                    args: [BigInt(proposalId)],
+                }),
+                client.readContract({
+                    address,
+                    abi: governanceAbi,
+                    functionName: "getProposalStage",
+                    args: [BigInt(proposalId)],
+                }),
+                includeVotes
+                    ? client.readContract({
+                        address,
+                        abi: governanceAbi,
+                        functionName: "getVoteTotals",
+                        args: [BigInt(proposalId)],
+                    })
+                    : Promise.resolve([0n, 0n, 0n]),
+            ]);
+            const [proposer, deposit, timestampSec, numTransactions, url, networkWeight, isApproved,] = proposalData;
+            if (proposer === "0x0000000000000000000000000000000000000000" &&
+                deposit === 0n &&
+                timestampSec === 0n) {
+                return null;
+            }
+            const timestamp = Number(timestampSec) * 1000;
+            const stageName = proposalStageName(Number(stage));
+            return {
+                id: proposalId,
+                stage: Number(stage),
+                timestamp,
+                expiryTimestamp: getExpiryTimestamp(stageName, timestamp),
+                url,
+                proposer,
+                deposit: deposit.toString(),
+                numTransactions: Number(numTransactions),
+                networkWeight: networkWeight.toString(),
+                isApproved,
+                upvotes,
+                votes: {
+                    yes: voteTotals[0].toString(),
+                    no: voteTotals[1].toString(),
+                    abstain: voteTotals[2].toString(),
+                },
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async listProposalIds() {
+        const client = this.getClient();
+        const address = CELO_CORE_CONTRACTS.governance;
+        const [queued, dequeued] = await Promise.all([
+            client.readContract({
+                address,
+                abi: governanceAbi,
+                functionName: "getQueue",
+            }),
+            client.readContract({
+                address,
+                abi: governanceAbi,
+                functionName: "getDequeue",
+            }),
+        ]);
+        const [queuedIds, queuedUpvotes] = queued;
+        const entries = [];
+        queuedIds.forEach((id, index) => {
+            if (id !== 0n) {
+                entries.push({
+                    id: Number(id),
+                    upvotes: Number(queuedUpvotes[index] ?? 0n),
+                });
+            }
+        });
+        for (const id of dequeued) {
+            if (id !== 0n) {
+                entries.push({ id: Number(id), upvotes: 0 });
+            }
+        }
+        entries.sort((a, b) => b.id - a.id);
+        return entries;
+    }
+    async getGovernanceProposals(options = {}) {
+        const includeInactive = options.includeInactive ?? true;
+        const includeMetadata = options.includeMetadata ?? true;
+        const pageSize = Math.min(Math.max(options.pageSize ?? 10, 1), 20);
+        let offset;
+        let limit;
+        if (options.page !== undefined) {
+            const page = Math.max(options.page, 1);
+            offset = (page - 1) * pageSize;
+            limit = pageSize;
+        }
+        else if (options.offset !== undefined) {
+            offset = Math.max(options.offset, 0);
+            limit = Math.min(options.limit ?? pageSize, 100);
+        }
+        else {
+            offset = 0;
+            limit = Math.min(options.limit ?? pageSize, 100);
+        }
+        const allIds = await this.listProposalIds();
+        const slice = allIds.slice(offset, offset + limit);
+        const proposals = (await Promise.all(slice.map(({ id, upvotes }) => this.fetchProposal(id, upvotes, !includeMetadata)))).filter((p) => p !== null);
+        const filtered = includeInactive
+            ? proposals
+            : proposals.filter((p) => {
+                const stage = proposalStageName(p.stage);
+                return !["Expiration", "Rejected", "Withdrawn"].includes(stage);
+            });
+        let enriched = filtered.map((p) => ({
+            ...p,
+            stageName: proposalStageName(p.stage),
+            metadata: null,
+        }));
+        if (includeMetadata) {
+            enriched = await Promise.all(enriched.map(async (proposal) => {
+                const cgp = extractCgpFromUrl(proposal.url);
+                if (!cgp)
+                    return proposal;
+                const cgpData = await fetchCgpMetadata(cgp);
+                return {
+                    ...proposal,
+                    metadata: cgpData?.frontmatter ?? null,
+                };
+            }));
+        }
+        const total = allIds.length;
+        const currentPage = options.page ?? Math.floor(offset / pageSize) + 1;
+        const totalPages = Math.max(Math.ceil(total / pageSize), 1);
+        return {
+            network: "mainnet",
+            proposals: enriched,
+            pagination: {
+                total,
+                page: currentPage,
+                pageSize,
+                totalPages,
+                offset,
+                limit,
+                hasMore: offset + limit < total,
+            },
+        };
+    }
+    async getProposalDetails(proposalId) {
+        const proposal = await this.fetchProposal(proposalId, 0, true);
+        if (!proposal) {
+            return {
+                network: "mainnet",
+                proposal: null,
+                content: null,
+                error: `Proposal ${proposalId} not found`,
+            };
+        }
+        const cgp = extractCgpFromUrl(proposal.url);
+        let metadata = null;
+        let content = null;
+        if (cgp) {
+            const cgpData = await fetchCgpMetadata(cgp);
+            metadata = cgpData?.frontmatter ?? null;
+            content = cgpData?.content ?? null;
+        }
+        return {
+            network: "mainnet",
+            proposal: {
+                ...proposal,
+                stageName: proposalStageName(proposal.stage),
+                metadata,
+            },
+            content,
+            error: null,
+        };
+    }
+}
+//# sourceMappingURL=governance.service.js.map

package/build/services/governance.service.js.map

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

package/build/services/mento-fx.service.d.ts

@@ -17,6 +17,7 @@ export declare class MentoFxService {
     private estimateCallGas;
     private estimateSwapGasWithAllowance;
     private baseQuoteFields;
+    /** Expected Mento FX output for a token pair — no wallet required. */
     getFxQuote(tokenIn: string, tokenOut: string, amount: string): Promise<{
         protocol: "mento_fx";
         network: "mainnet";
@@ -26,6 +27,7 @@ export declare class MentoFxService {
         expectedOut: string;
         routeHops: number;
     }>;
+    /** Simulate gas for a Mento FX swap from `from`, including approval if needed. */
     estimateFx(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: MentoFxParams): Promise<{
         from: `0x${string}`;
         recipient: `0x${string}`;
@@ -44,5 +46,9 @@ export declare class MentoFxService {
         expectedOut: string;
         routeHops: number;
     }>;
+    /**
+     * Build unsigned Mento FX steps (approve + swap when needed).
+     * Returns `SerializedPreparedFlow` for sequential wallet signing.
+     */
     prepareFx(from: `0x${string}`, tokenIn: string, tokenOut: string, amount: string, params?: MentoFxParams): Promise<SerializedPreparedFlow>;
 }

package/build/services/mento-fx.service.js

@@ -1,3 +1,7 @@
+/**
+ * Mento FX: getFxQuote is read-only; prepareFx builds approve + swap steps when needed.
+ * Uses @mento-protocol/mento-sdk for routing and simulates allowance via state overrides.
+ */
 import { concat, decodeFunctionData, erc20Abi, formatUnits, } from "viem";
 import { ChainId, deadlineFromMinutes, Mento, RouteNotFoundError, FXMarketClosedError, } from "../clients/mento-sdk.js";
 import { CELINA_DATA_SUFFIX } from "../config/celina-tag.js";
@@ -165,6 +169,7 @@ export class MentoFxService {
             routeHops,
         };
     }
+    /** Expected Mento FX output for a token pair — no wallet required. */
     async getFxQuote(tokenIn, tokenOut, amount) {
         const { public: client } = this.clientFactory.getClients();
         const { resolvedIn, resolvedOut, mentoIn, mentoOut } = this.resolveMentoPair(tokenIn, tokenOut);
@@ -181,6 +186,7 @@ export class MentoFxService {
             this.formatFxError(error, resolvedIn.symbol, resolvedOut.symbol);
         }
     }
+    /** Simulate gas for a Mento FX swap from `from`, including approval if needed. */
     async estimateFx(from, tokenIn, tokenOut, amount, params) {
         try {
             const built = await this.buildFxSwap(from, tokenIn, tokenOut, amount, params);
@@ -209,6 +215,10 @@ export class MentoFxService {
             this.formatFxError(error, tokenIn, tokenOut);
         }
     }
+    /**
+     * Build unsigned Mento FX steps (approve + swap when needed).
+     * Returns `SerializedPreparedFlow` for sequential wallet signing.
+     */
     async prepareFx(from, tokenIn, tokenOut, amount, params) {
         try {
             const built = await this.buildFxSwap(from, tokenIn, tokenOut, amount, params);