@andrewkimjoseph/celina-sdk 0.1.0 → 0.2.0

package/build/services/staking.service.js

@@ -0,0 +1,410 @@
+import { isAddress } from "viem";
+import { accountsAbi } from "../abis/accounts.js";
+import { electionAbi } from "../abis/election.js";
+import { lockedGoldAbi } from "../abis/locked-gold.js";
+import { validatorsMinimalAbi } from "../abis/validators-minimal.js";
+import { CELO_CORE_CONTRACTS } from "../config/celo-core-contracts.js";
+import { formatAddress, formatCeloAmount, formatScorePercentage, } from "../utils/celo-format.js";
+const MAX_ELECTABLE_VALIDATORS = 110;
+function calculateGroupCapacity(groupMembers, totalLockedGold, totalValidators) {
+    if (totalValidators === 0)
+        return 0n;
+    const divisor = BigInt(Math.min(MAX_ELECTABLE_VALIDATORS, totalValidators));
+    return (totalLockedGold * BigInt(groupMembers + 1)) / divisor;
+}
+export class StakingService {
+    clientFactory;
+    constructor(clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+    getClient() {
+        return this.clientFactory.getClients().public;
+    }
+    async getStakingBalances(address) {
+        if (!isAddress(address)) {
+            throw new Error(`Invalid address: ${address}`);
+        }
+        const client = this.getClient();
+        const election = CELO_CORE_CONTRACTS.election;
+        const groupAddresses = (await client.readContract({
+            address: election,
+            abi: electionAbi,
+            functionName: "getGroupsVotedForByAccount",
+            args: [address],
+        }));
+        if (groupAddresses.length === 0) {
+            return {
+                network: "mainnet",
+                address,
+                active: "0",
+                pending: "0",
+                total: "0",
+                activeFormatted: formatCeloAmount(0n),
+                pendingFormatted: formatCeloAmount(0n),
+                totalFormatted: formatCeloAmount(0n),
+                groups: [],
+            };
+        }
+        const calls = groupAddresses.flatMap((group) => [
+            {
+                address: election,
+                abi: electionAbi,
+                functionName: "getPendingVotesForGroupByAccount",
+                args: [group, address],
+            },
+            {
+                address: election,
+                abi: electionAbi,
+                functionName: "getActiveVotesForGroupByAccount",
+                args: [group, address],
+            },
+        ]);
+        const results = await client.multicall({ contracts: calls, allowFailure: true });
+        let totalActive = 0n;
+        let totalPending = 0n;
+        const groups = groupAddresses.map((group, index) => {
+            const pendingResult = results[index * 2];
+            const activeResult = results[index * 2 + 1];
+            const pending = pendingResult.status === "success" ? pendingResult.result : 0n;
+            const active = activeResult.status === "success" ? activeResult.result : 0n;
+            totalActive += active;
+            totalPending += pending;
+            return {
+                groupAddress: group,
+                active: active.toString(),
+                pending: pending.toString(),
+                total: (active + pending).toString(),
+                activeFormatted: formatCeloAmount(active),
+                pendingFormatted: formatCeloAmount(pending),
+                totalFormatted: formatCeloAmount(active + pending),
+            };
+        });
+        const total = totalActive + totalPending;
+        return {
+            network: "mainnet",
+            address,
+            active: totalActive.toString(),
+            pending: totalPending.toString(),
+            total: total.toString(),
+            activeFormatted: formatCeloAmount(totalActive),
+            pendingFormatted: formatCeloAmount(totalPending),
+            totalFormatted: formatCeloAmount(total),
+            groups,
+        };
+    }
+    async getActivatableStakes(address) {
+        if (!isAddress(address)) {
+            throw new Error(`Invalid address: ${address}`);
+        }
+        const balances = await this.getStakingBalances(address);
+        const pendingGroups = balances.groups.filter((g) => g.pending !== "0");
+        if (pendingGroups.length === 0) {
+            return {
+                network: "mainnet",
+                address,
+                activatableGroups: [],
+                groupToIsActivatable: {},
+                summary: {
+                    totalActivatableGroups: 0,
+                    totalPendingGroups: 0,
+                    message: "No pending stakes found",
+                },
+            };
+        }
+        const client = this.getClient();
+        const election = CELO_CORE_CONTRACTS.election;
+        const calls = pendingGroups.map((g) => ({
+            address: election,
+            abi: electionAbi,
+            functionName: "hasActivatablePendingVotes",
+            args: [address, g.groupAddress],
+        }));
+        const results = await client.multicall({ contracts: calls, allowFailure: true });
+        const groupToIsActivatable = {};
+        const activatableGroups = [];
+        pendingGroups.forEach((group, index) => {
+            const result = results[index];
+            const isActivatable = result.status === "success" ? result.result : false;
+            groupToIsActivatable[group.groupAddress] = isActivatable;
+            if (isActivatable)
+                activatableGroups.push(group.groupAddress);
+        });
+        return {
+            network: "mainnet",
+            address,
+            activatableGroups,
+            groupToIsActivatable,
+            summary: {
+                totalActivatableGroups: activatableGroups.length,
+                totalPendingGroups: pendingGroups.length,
+                activatableGroupsFormatted: activatableGroups.map(formatAddress),
+                message: `${activatableGroups.length} of ${pendingGroups.length} groups have stakes ready to activate`,
+            },
+        };
+    }
+    async getValidatorGroups(options) {
+        const pageSize = Math.min(Math.max(options?.pageSize ?? 10, 1), 50);
+        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 client = this.getClient();
+        const election = CELO_CORE_CONTRACTS.election;
+        const validators = CELO_CORE_CONTRACTS.validators;
+        const accounts = CELO_CORE_CONTRACTS.accounts;
+        const lockedGold = CELO_CORE_CONTRACTS.lockedGold;
+        let groupAddresses;
+        let groupVotes = null;
+        try {
+            const eligible = (await client.readContract({
+                address: election,
+                abi: electionAbi,
+                functionName: "getTotalVotesForEligibleValidatorGroups",
+            }));
+            groupAddresses = eligible[0];
+            groupVotes = eligible[1];
+        }
+        catch {
+            groupAddresses = (await client.readContract({
+                address: election,
+                abi: electionAbi,
+                functionName: "getEligibleValidatorGroups",
+            }));
+        }
+        const [totalVotes, totalLockedGold, allValidators] = await Promise.all([
+            client.readContract({
+                address: election,
+                abi: electionAbi,
+                functionName: "getTotalVotes",
+            }),
+            client
+                .readContract({
+                address: lockedGold,
+                abi: lockedGoldAbi,
+                functionName: "getTotalLockedGold",
+            })
+                .catch(() => 0n),
+            client
+                .readContract({
+                address: validators,
+                abi: validatorsMinimalAbi,
+                functionName: "getRegisteredValidators",
+            })
+                .catch(() => []),
+        ]);
+        const totalValidators = allValidators.length || MAX_ELECTABLE_VALIDATORS;
+        const slice = groupAddresses.slice(offset, offset + limit);
+        const groupCalls = slice.flatMap((group) => [
+            {
+                address: validators,
+                abi: validatorsMinimalAbi,
+                functionName: "getValidatorGroup",
+                args: [group],
+            },
+            {
+                address: accounts,
+                abi: accountsAbi,
+                functionName: "getName",
+                args: [group],
+            },
+        ]);
+        const groupResults = await client.multicall({
+            contracts: groupCalls,
+            allowFailure: true,
+        });
+        const groups = await Promise.all(slice.map(async (groupAddress, index) => {
+            const groupInfoResult = groupResults[index * 2];
+            const nameResult = groupResults[index * 2 + 1];
+            const members = groupInfoResult.status === "success"
+                ? groupInfoResult.result[0]
+                : [];
+            const name = nameResult.status === "success"
+                ? nameResult.result
+                : `${groupAddress.slice(0, 10)}...`;
+            let votes = groupVotes?.[offset + index] ?? 0n;
+            if (groupVotes === null) {
+                votes = (await client.readContract({
+                    address: election,
+                    abi: electionAbi,
+                    functionName: "getActiveVotesForGroup",
+                    args: [groupAddress],
+                }));
+            }
+            const numMembers = members.length;
+            const capacity = calculateGroupCapacity(numMembers, totalLockedGold || totalVotes, totalValidators);
+            return {
+                address: groupAddress,
+                name,
+                votes: votes.toString(),
+                votesFormatted: formatCeloAmount(votes),
+                numMembers,
+                capacity: capacity.toString(),
+                capacityFormatted: formatCeloAmount(capacity),
+                addressFormatted: formatAddress(groupAddress),
+            };
+        }));
+        const total = groupAddresses.length;
+        const currentPage = options?.page ?? Math.floor(offset / pageSize) + 1;
+        return {
+            network: "mainnet",
+            groups,
+            totalVotes: totalVotes.toString(),
+            totalVotesFormatted: formatCeloAmount(totalVotes),
+            pagination: {
+                total,
+                page: currentPage,
+                pageSize,
+                totalPages: Math.max(Math.ceil(total / pageSize), 1),
+                offset,
+                limit,
+                hasMore: offset + limit < total,
+            },
+        };
+    }
+    async getValidatorGroupDetails(groupAddress) {
+        if (!isAddress(groupAddress)) {
+            throw new Error(`Invalid group address: ${groupAddress}`);
+        }
+        const client = this.getClient();
+        const election = CELO_CORE_CONTRACTS.election;
+        const validators = CELO_CORE_CONTRACTS.validators;
+        const accounts = CELO_CORE_CONTRACTS.accounts;
+        const lockedGold = CELO_CORE_CONTRACTS.lockedGold;
+        const [groupInfo, name, votes, eligibleGroups, totalLockedGold, allValidators] = await Promise.all([
+            client.readContract({
+                address: validators,
+                abi: validatorsMinimalAbi,
+                functionName: "getValidatorGroup",
+                args: [groupAddress],
+            }),
+            client
+                .readContract({
+                address: accounts,
+                abi: accountsAbi,
+                functionName: "getName",
+                args: [groupAddress],
+            })
+                .catch(() => `${groupAddress.slice(0, 10)}...`),
+            client.readContract({
+                address: election,
+                abi: electionAbi,
+                functionName: "getActiveVotesForGroup",
+                args: [groupAddress],
+            }),
+            client.readContract({
+                address: election,
+                abi: electionAbi,
+                functionName: "getEligibleValidatorGroups",
+            }),
+            client
+                .readContract({
+                address: lockedGold,
+                abi: lockedGoldAbi,
+                functionName: "getTotalLockedGold",
+            })
+                .catch(() => 0n),
+            client
+                .readContract({
+                address: validators,
+                abi: validatorsMinimalAbi,
+                functionName: "getRegisteredValidators",
+            })
+                .catch(() => []),
+        ]);
+        const members = groupInfo[0];
+        const lastSlashed = groupInfo[2] > 0n ? Number(groupInfo[2]) * 1000 : null;
+        const totalValidators = allValidators.length || MAX_ELECTABLE_VALIDATORS;
+        const capacity = calculateGroupCapacity(members.length, totalLockedGold || votes, totalValidators);
+        const memberCalls = members.flatMap((member) => [
+            {
+                address: validators,
+                abi: validatorsMinimalAbi,
+                functionName: "getValidator",
+                args: [member],
+            },
+            {
+                address: accounts,
+                abi: accountsAbi,
+                functionName: "getName",
+                args: [member],
+            },
+        ]);
+        const memberResults = await client.multicall({
+            contracts: memberCalls,
+            allowFailure: true,
+        });
+        const memberDetails = members.map((member, index) => {
+            const validatorResult = memberResults[index * 2];
+            const nameResult = memberResults[index * 2 + 1];
+            if (validatorResult.status !== "success") {
+                return {
+                    address: member,
+                    addressFormatted: formatAddress(member),
+                    name: `${member.slice(0, 10)}...`,
+                    score: "0",
+                    scoreFormatted: "0%",
+                    signer: null,
+                    status: votes > 0n ? "ELECTED" : "NOT_ELECTED",
+                };
+            }
+            const validatorInfo = validatorResult.result;
+            const memberName = nameResult.status === "success"
+                ? nameResult.result
+                : `${member.slice(0, 10)}...`;
+            return {
+                address: member,
+                addressFormatted: formatAddress(member),
+                name: memberName,
+                score: validatorInfo[3].toString(),
+                scoreFormatted: formatScorePercentage(validatorInfo[3]),
+                signer: validatorInfo[4],
+                status: votes > 0n ? "ELECTED" : "NOT_ELECTED",
+            };
+        });
+        const eligible = eligibleGroups.some((g) => g.toLowerCase() === groupAddress.toLowerCase());
+        return {
+            network: "mainnet",
+            address: groupAddress,
+            name,
+            votes: votes.toString(),
+            votesFormatted: formatCeloAmount(votes),
+            capacity: capacity.toString(),
+            capacityFormatted: formatCeloAmount(capacity),
+            lastSlashed,
+            eligible,
+            numMembers: members.length,
+            numElected: votes > 0n ? members.length : 0,
+            members: memberDetails,
+        };
+    }
+    async getTotalStakingInfo() {
+        const client = this.getClient();
+        const totalVotes = (await client.readContract({
+            address: CELO_CORE_CONTRACTS.election,
+            abi: electionAbi,
+            functionName: "getTotalVotes",
+        }));
+        return {
+            network: "mainnet",
+            totalVotes: totalVotes.toString(),
+            totalVotesCelo: Number(totalVotes / 10n ** 18n),
+            totalVotesFormatted: formatCeloAmount(totalVotes),
+            summary: {
+                networkParticipation: formatCeloAmount(totalVotes),
+                message: `Total network staking participation: ${formatCeloAmount(totalVotes)}`,
+            },
+        };
+    }
+}
+//# sourceMappingURL=staking.service.js.map

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

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

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

@@ -8,6 +8,7 @@ export declare class TokenService {
     private readonly clientFactory;
     constructor(clientFactory: CeloClientFactory);
     resolveToken(token: string): ResolvedToken;
+    /** Fetch ERC-20 metadata or native CELO info for a symbol or address. */
     getTokenInfo(token: string): Promise<{
         network: string;
         name: string;
@@ -15,6 +16,7 @@ export declare class TokenService {
         symbol: string;
         decimals: number;
     }>;
+    /** CELO and ERC-20 balances for specific tokens (defaults: CELO, USDm). */
     getBalances(address: `0x${string}`, tokens?: string[]): Promise<{
         network: string;
         address: `0x${string}`;
@@ -25,6 +27,7 @@ export declare class TokenService {
             formatted: string;
         }[];
     }>;
+    /** Scan registry stablecoins for an address; omits zero balances by default. */
     getStablecoinBalances(address: `0x${string}`, options?: {
         stablecoins?: string[];
         includeZero?: boolean;
@@ -50,5 +53,16 @@ export declare class TokenService {
             readError?: undefined;
         })[];
     }>;
+    /** ERC-20 balance for a specific token contract address. */
+    getTokenBalance(tokenAddress: `0x${string}`, accountAddress: `0x${string}`): Promise<{
+        network: "mainnet";
+        tokenAddress: `0x${string}`;
+        accountAddress: `0x${string}`;
+        name: string;
+        symbol: string;
+        decimals: number;
+        raw: string;
+        formatted: string;
+    }>;
     parseAmount(amount: string, decimals: number): bigint;
 }

package/build/services/token.service.js

@@ -1,4 +1,4 @@
-import { erc20Abi, formatUnits, isAddress, parseUnits } from "viem";
+import { erc20Abi, formatUnits, getAddress, isAddress, parseUnits } from "viem";
 import { findKnownToken, KNOWN_TOKEN_SYMBOLS, resolveStablecoins, } from "../config/chains.js";
 export class TokenService {
     clientFactory;
@@ -24,6 +24,7 @@ export class TokenService {
         }
         throw new Error(`Unknown token "${token}". Use ${KNOWN_TOKEN_SYMBOLS.join(", ")}, or a contract address.`);
     }
+    /** Fetch ERC-20 metadata or native CELO info for a symbol or address. */
     async getTokenInfo(token) {
         const resolved = this.resolveToken(token);
         if (resolved.address === "native") {
@@ -60,6 +61,7 @@ export class TokenService {
             decimals: Number(decimals),
         };
     }
+    /** CELO and ERC-20 balances for specific tokens (defaults: CELO, USDm). */
     async getBalances(address, tokens = ["CELO", "USDm"]) {
         const { public: client } = this.clientFactory.getClients();
         const balances = await Promise.all(tokens.map(async (tokenInput) => {
@@ -95,6 +97,7 @@ export class TokenService {
         }));
         return { network: "mainnet", address, balances };
     }
+    /** Scan registry stablecoins for an address; omits zero balances by default. */
     async getStablecoinBalances(address, options) {
         const coins = resolveStablecoins(options?.stablecoins);
         const { public: client } = this.clientFactory.getClients();
@@ -140,6 +143,53 @@ export class TokenService {
             stablecoins,
         };
     }
+    /** ERC-20 balance for a specific token contract address. */
+    async getTokenBalance(tokenAddress, accountAddress) {
+        let token;
+        let account;
+        try {
+            token = getAddress(tokenAddress);
+            account = getAddress(accountAddress);
+        }
+        catch {
+            throw new Error("Invalid token or account address");
+        }
+        const { public: client } = this.clientFactory.getClients();
+        const [name, symbol, decimals, balance] = await Promise.all([
+            client.readContract({
+                address: token,
+                abi: erc20Abi,
+                functionName: "name",
+            }),
+            client.readContract({
+                address: token,
+                abi: erc20Abi,
+                functionName: "symbol",
+            }),
+            client.readContract({
+                address: token,
+                abi: erc20Abi,
+                functionName: "decimals",
+            }),
+            client.readContract({
+                address: token,
+                abi: erc20Abi,
+                functionName: "balanceOf",
+                args: [account],
+            }),
+        ]);
+        const dec = Number(decimals);
+        return {
+            network: "mainnet",
+            tokenAddress: token,
+            accountAddress: account,
+            name,
+            symbol,
+            decimals: dec,
+            raw: balance.toString(),
+            formatted: formatUnits(balance, dec),
+        };
+    }
     parseAmount(amount, decimals) {
         return parseUnits(amount, decimals);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"token.service.js","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"token.service.js","sourceRoot":"","sources":["../../src/services/token.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAChF,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAS7B,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,aAAgC;QAAhC,kBAAa,GAAb,aAAa,CAAmB;IAAG,CAAC;IAEjE,YAAY,CAAC,KAAa;QACxB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAEhC,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC;QACJ,CAAC;QAED,IAAI,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,UAAU;gBACnB,MAAM,EAAE,UAAU;gBAClB,QAAQ,EAAE,EAAE;aACb,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,UAAU,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,0BAA0B,CAC1F,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,YAAY,CAAC,KAAa;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAE1C,IAAI,QAAQ,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAClC,OAAO;gBACL,GAAG,QAAQ;gBACX,OAAO,EAAE,SAAS;gBAClB,IAAI,EAAE,MAAM;aACb,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAC3D,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QAEjC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACjD,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO;gBACP,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,MAAM;aACrB,CAAC;YACF,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO;gBACP,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,QAAQ;aACvB,CAAC;YACF,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO;gBACP,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,UAAU;aACzB,CAAC;SACH,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,SAAS;YAClB,OAAO;YACP,IAAI;YACJ,MAAM;YACN,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;SAC3B,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,WAAW,CACf,OAAsB,EACtB,SAAmB,CAAC,MAAM,EAAE,MAAM,CAAC;QAEnC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAE3D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YAE5C,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC/B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;gBACrD,OAAO;oBACL,KAAK,EAAE,KAAK,CAAC,MAAM;oBACnB,OAAO,EAAE,QAAQ;oBACjB,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE;oBACvB,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;iBAChD,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC;gBACxC,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,WAAW;gBACzB,IAAI,EAAE,CAAC,OAAO,CAAC;aAChB,CAAC,CAAC;YAEH,MAAM,QAAQ,GACZ,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,OAAO;gBAC5B,CAAC,CAAC,MAAM,CACJ,MAAM,MAAM,CAAC,YAAY,CAAC;oBACxB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,GAAG,EAAE,QAAQ;oBACb,YAAY,EAAE,UAAU;iBACzB,CAAC,CACH;gBACH,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;YAErB,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,MAAM;gBACnB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE;gBACvB,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC;aAC1C,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IACnD,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,qBAAqB,CACzB,OAAsB,EACtB,OAGC;QAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACvD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAE3D,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC;YACrC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC9B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,WAAW;gBACzB,IAAI,EAAE,CAAC,OAAO,CAAC;aAChB,CAAC,CAAC;YACH,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACzC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAE9B,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAChC,OAAO;oBACL,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,GAAG,EAAE,GAAG;oBACR,SAAS,EAAE,GAAG;oBACd,SAAS,EAAE,IAAI;iBAChB,CAAC;YACJ,CAAC;YAED,MAAM,GAAG,GAAG,MAAM,CAAC,MAAgB,CAAC;YACpC,OAAO;gBACL,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE;gBACnB,SAAS,EAAE,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC;aAC3C,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW;YACtC,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;QAEtD,OAAO;YACL,OAAO,EAAE,SAAS;YAClB,OAAO;YACP,YAAY,EAAE,KAAK,CAAC,MAAM;YAC1B,WAAW;SACZ,CAAC;IACJ,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,eAAe,CACnB,YAA2B,EAC3B,cAA6B;QAE7B,IAAI,KAAoB,CAAC;QACzB,IAAI,OAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;YACjC,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,CAAC;QAE3D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC1D,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO,EAAE,KAAK;gBACd,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,MAAM;aACrB,CAAC;YACF,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO,EAAE,KAAK;gBACd,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,QAAQ;aACvB,CAAC;YACF,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO,EAAE,KAAK;gBACd,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,UAAU;aACzB,CAAC;YACF,MAAM,CAAC,YAAY,CAAC;gBAClB,OAAO,EAAE,KAAK;gBACd,GAAG,EAAE,QAAQ;gBACb,YAAY,EAAE,WAAW;gBACzB,IAAI,EAAE,CAAC,OAAO,CAAC;aAChB,CAAC;SACH,CAAC,CAAC;QAEH,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAE7B,OAAO;YACL,OAAO,EAAE,SAAkB;YAC3B,YAAY,EAAE,KAAK;YACnB,cAAc,EAAE,OAAO;YACvB,IAAI;YACJ,MAAM;YACN,QAAQ,EAAE,GAAG;YACb,GAAG,EAAE,OAAO,CAAC,QAAQ,EAAE;YACvB,SAAS,EAAE,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,WAAW,CAAC,MAAc,EAAE,QAAgB;QAC1C,OAAO,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;CACF"}

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

@@ -1,9 +1,15 @@
+/**
+ * Token sends: estimateSend simulates gas; prepareSend builds unsigned tx steps.
+ * Calldata is tagged with CELINA_DATA_SUFFIX for on-chain attribution.
+ */
+import { type Hex } from "viem";
 import type { CeloClientFactory } from "../clients/celo-client.js";
 import { type SerializedPreparedFlow } from "../types/prepared.js";
 export declare class TransactionService {
     private readonly clientFactory;
     private readonly tokenService;
     constructor(clientFactory: CeloClientFactory);
+    /** Simulate gas for a CELO or ERC-20 transfer from `from`. */
     estimateSend(from: `0x${string}`, to: `0x${string}`, token: string, amount: string): Promise<{
         network: "mainnet";
         from: `0x${string}`;
@@ -12,5 +18,36 @@ export declare class TransactionService {
         amount: string;
         gas: string;
     }>;
+    /**
+     * Build an unsigned send flow (native CELO or ERC-20 transfer).
+     * Returns `SerializedPreparedFlow` for wagmi `sendTransaction`.
+     */
     prepareSend(from: `0x${string}`, to: `0x${string}`, token: string, amount: string): Promise<SerializedPreparedFlow>;
+    /** Current gas fee data including EIP-1559 fees when supported. */
+    getGasFeeData(): Promise<{
+        network: "mainnet";
+        baseFeePerGas: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        gasPrice: string;
+        eip1559: boolean;
+    }>;
+    /** Generic transaction gas estimate (not token-transfer specific). */
+    estimateTransaction(params: {
+        from: `0x${string}`;
+        to: `0x${string}`;
+        value?: string;
+        data?: Hex;
+    }): Promise<{
+        network: "mainnet";
+        from: `0x${string}`;
+        to: `0x${string}`;
+        gasLimit: string;
+        gasPrice: string;
+        maxFeePerGas: string;
+        maxPriorityFeePerGas: string;
+        estimatedCost: string;
+        estimatedCostFormatted: string;
+        isEip1559: boolean;
+    }>;
 }