opencode-froggy 0.1.0 → 0.3.0

package/dist/tools/blockchain/etherscan-client.js

@@ -0,0 +1,156 @@
+/**
+ * Etherscan API client for Ethereum blockchain queries
+ */
+import { DEFAULT_TRANSACTION_LIMIT, DEFAULT_CHAIN_ID, } from "./types";
+const ETHERSCAN_BASE_URL = "https://api.etherscan.io/v2/api";
+export class EtherscanClientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EtherscanClientError";
+    }
+}
+export class EtherscanClient {
+    apiKey;
+    chainId;
+    baseUrl;
+    constructor(apiKey, chainId, baseUrl) {
+        const key = apiKey ?? process.env.ETHERSCAN_API_KEY;
+        if (!key) {
+            throw new EtherscanClientError("ETHERSCAN_API_KEY environment variable is required. " +
+                "Get a free API key at https://etherscan.io/apis");
+        }
+        this.apiKey = key;
+        this.chainId = chainId ?? DEFAULT_CHAIN_ID;
+        this.baseUrl = baseUrl ?? ETHERSCAN_BASE_URL;
+    }
+    async request(params) {
+        const url = new URL(this.baseUrl);
+        url.searchParams.set("apikey", this.apiKey);
+        url.searchParams.set("chainid", this.chainId);
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            throw new EtherscanClientError(`Etherscan API HTTP error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (data.status === "0" && data.message !== "No transactions found") {
+            throw new EtherscanClientError(`Etherscan API error: ${data.message} - ${data.result}`);
+        }
+        return data.result;
+    }
+    async getBalance(address) {
+        return this.request({
+            module: "account",
+            action: "balance",
+            address,
+            tag: "latest",
+        });
+    }
+    async getTransactions(address, limit = DEFAULT_TRANSACTION_LIMIT) {
+        const result = await this.request({
+            module: "account",
+            action: "txlist",
+            address,
+            startblock: "0",
+            endblock: "99999999",
+            page: "1",
+            offset: String(limit),
+            sort: "desc",
+        });
+        if (typeof result === "string") {
+            return [];
+        }
+        return result;
+    }
+    async getInternalTransactions(address, limit = DEFAULT_TRANSACTION_LIMIT) {
+        const result = await this.request({
+            module: "account",
+            action: "txlistinternal",
+            address,
+            startblock: "0",
+            endblock: "99999999",
+            page: "1",
+            offset: String(limit),
+            sort: "desc",
+        });
+        if (typeof result === "string") {
+            return [];
+        }
+        return result;
+    }
+    async getTokenTransfers(address, limit = DEFAULT_TRANSACTION_LIMIT) {
+        const result = await this.request({
+            module: "account",
+            action: "tokentx",
+            address,
+            startblock: "0",
+            endblock: "99999999",
+            page: "1",
+            offset: String(limit),
+            sort: "desc",
+        });
+        if (typeof result === "string") {
+            return [];
+        }
+        return result;
+    }
+    async getTransactionByHash(hash) {
+        const result = await this.request({
+            module: "account",
+            action: "txlistinternal",
+            txhash: hash,
+        });
+        if (typeof result === "string" || result.length === 0) {
+            const txList = await this.request({
+                module: "proxy",
+                action: "eth_getTransactionByHash",
+                txhash: hash,
+            });
+            if (!txList || typeof txList === "string") {
+                return null;
+            }
+            return txList;
+        }
+        return result[0];
+    }
+    async getTransactionReceipt(hash) {
+        const result = await this.request({
+            module: "proxy",
+            action: "eth_getTransactionReceipt",
+            txhash: hash,
+        });
+        return result;
+    }
+}
+export function weiToEth(wei) {
+    const weiBigInt = BigInt(wei);
+    const ethWhole = weiBigInt / BigInt(10 ** 18);
+    const ethFraction = weiBigInt % BigInt(10 ** 18);
+    const fractionStr = ethFraction.toString().padStart(18, "0");
+    const trimmedFraction = fractionStr.replace(/0+$/, "");
+    if (trimmedFraction === "") {
+        return ethWhole.toString();
+    }
+    return `${ethWhole}.${trimmedFraction}`;
+}
+export function formatTimestamp(timestamp) {
+    const date = new Date(parseInt(timestamp, 10) * 1000);
+    return date.toISOString();
+}
+export function shortenAddress(address) {
+    if (address.length < 12)
+        return address;
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+export function validateAddress(address) {
+    if (!address?.startsWith("0x") || address.length !== 42) {
+        throw new EtherscanClientError("Invalid Ethereum address format");
+    }
+}
+export function validateTxHash(hash) {
+    if (!hash?.startsWith("0x") || hash.length !== 66) {
+        throw new EtherscanClientError("Invalid transaction hash format");
+    }
+}

package/dist/tools/blockchain/etherscan-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/blockchain/etherscan-client.test.js

@@ -0,0 +1,211 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EtherscanClient, EtherscanClientError, weiToEth, formatTimestamp, shortenAddress } from "./etherscan-client";
+describe("EtherscanClient", () => {
+    const originalEnv = process.env.ETHERSCAN_API_KEY;
+    const mockFetch = vi.fn();
+    beforeEach(() => {
+        vi.resetAllMocks();
+        vi.stubGlobal("fetch", mockFetch);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        if (originalEnv) {
+            process.env.ETHERSCAN_API_KEY = originalEnv;
+        }
+        else {
+            delete process.env.ETHERSCAN_API_KEY;
+        }
+    });
+    describe("constructor", () => {
+        it("should throw error when API key is missing", () => {
+            delete process.env.ETHERSCAN_API_KEY;
+            expect(() => new EtherscanClient()).toThrow(EtherscanClientError);
+            expect(() => new EtherscanClient()).toThrow("ETHERSCAN_API_KEY environment variable is required");
+        });
+        it("should create client with API key from environment", () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const client = new EtherscanClient();
+            expect(client).toBeInstanceOf(EtherscanClient);
+        });
+        it("should create client with provided API key", () => {
+            delete process.env.ETHERSCAN_API_KEY;
+            const client = new EtherscanClient("provided-api-key");
+            expect(client).toBeInstanceOf(EtherscanClient);
+        });
+        it("should create client with custom chainId", () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const client = new EtherscanClient(undefined, "137");
+            expect(client).toBeInstanceOf(EtherscanClient);
+        });
+    });
+    describe("getBalance", () => {
+        it("should return balance for valid address", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockResponse = {
+                status: "1",
+                message: "OK",
+                result: "1000000000000000000",
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient();
+            const balance = await client.getBalance("0x1234567890123456789012345678901234567890");
+            expect(balance).toBe("1000000000000000000");
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            expect(callUrl).toContain("module=account");
+            expect(callUrl).toContain("action=balance");
+            expect(callUrl).toContain("chainid=1");
+            expect(callUrl).toContain("/v2/api");
+        });
+        it("should use custom chainId in requests", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockResponse = {
+                status: "1",
+                message: "OK",
+                result: "500000000000000000",
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient(undefined, "137");
+            await client.getBalance("0x1234567890123456789012345678901234567890");
+            const callUrl = mockFetch.mock.calls[0][0];
+            expect(callUrl).toContain("chainid=137");
+        });
+        it("should throw error on API failure", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockResponse = {
+                status: "0",
+                message: "NOTOK",
+                result: "Invalid address format",
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient();
+            await expect(client.getBalance("invalid-address")).rejects.toThrow(EtherscanClientError);
+        });
+        it("should throw error on HTTP failure", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+                statusText: "Internal Server Error",
+            });
+            const client = new EtherscanClient();
+            await expect(client.getBalance("0x1234567890123456789012345678901234567890")).rejects.toThrow("Etherscan API HTTP error: 500 Internal Server Error");
+        });
+    });
+    describe("getTransactions", () => {
+        it("should return transactions for valid address", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockTransactions = [
+                {
+                    hash: "0xabc123",
+                    from: "0x1111111111111111111111111111111111111111",
+                    to: "0x2222222222222222222222222222222222222222",
+                    value: "1000000000000000000",
+                    timeStamp: "1640000000",
+                    isError: "0",
+                },
+            ];
+            const mockResponse = {
+                status: "1",
+                message: "OK",
+                result: mockTransactions,
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient();
+            const transactions = await client.getTransactions("0x1234567890123456789012345678901234567890", 10);
+            expect(transactions).toHaveLength(1);
+            expect(transactions[0].hash).toBe("0xabc123");
+        });
+        it("should return empty array when no transactions found", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockResponse = {
+                status: "0",
+                message: "No transactions found",
+                result: "No transactions found",
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient();
+            const transactions = await client.getTransactions("0x1234567890123456789012345678901234567890");
+            expect(transactions).toEqual([]);
+        });
+    });
+    describe("getTokenTransfers", () => {
+        it("should return token transfers for valid address", async () => {
+            process.env.ETHERSCAN_API_KEY = "test-api-key";
+            const mockTransfers = [
+                {
+                    hash: "0xdef456",
+                    from: "0x1111111111111111111111111111111111111111",
+                    to: "0x2222222222222222222222222222222222222222",
+                    value: "1000000000000000000",
+                    tokenName: "Test Token",
+                    tokenSymbol: "TST",
+                    tokenDecimal: "18",
+                    contractAddress: "0x3333333333333333333333333333333333333333",
+                },
+            ];
+            const mockResponse = {
+                status: "1",
+                message: "OK",
+                result: mockTransfers,
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+            const client = new EtherscanClient();
+            const transfers = await client.getTokenTransfers("0x1234567890123456789012345678901234567890");
+            expect(transfers).toHaveLength(1);
+            expect(transfers[0].tokenSymbol).toBe("TST");
+        });
+    });
+});
+describe("weiToEth", () => {
+    it("should convert 1 ETH correctly", () => {
+        expect(weiToEth("1000000000000000000")).toBe("1");
+    });
+    it("should convert 0.5 ETH correctly", () => {
+        expect(weiToEth("500000000000000000")).toBe("0.5");
+    });
+    it("should convert 0 ETH correctly", () => {
+        expect(weiToEth("0")).toBe("0");
+    });
+    it("should handle large values", () => {
+        expect(weiToEth("123456789000000000000000000")).toBe("123456789");
+    });
+    it("should handle small fractional values", () => {
+        const result = weiToEth("1234567890123456789");
+        expect(result).toBe("1.234567890123456789");
+    });
+});
+describe("formatTimestamp", () => {
+    it("should format Unix timestamp to ISO string", () => {
+        const result = formatTimestamp("1640000000");
+        expect(result).toBe("2021-12-20T11:33:20.000Z");
+    });
+});
+describe("shortenAddress", () => {
+    it("should shorten long address", () => {
+        const address = "0x1234567890123456789012345678901234567890";
+        expect(shortenAddress(address)).toBe("0x1234...7890");
+    });
+    it("should return short address unchanged", () => {
+        const address = "0x12345";
+        expect(shortenAddress(address)).toBe("0x12345");
+    });
+});

package/dist/tools/blockchain/formatters.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formatting utilities for blockchain data
+ */
+import { type EthTransaction, type EthTokenTransfer } from "./types";
+export declare function formatTransactionReceipt(hash: string, receipt: Record<string, unknown>): string;
+export declare function formatTransaction(tx: EthTransaction, address: string): string;
+export declare function formatTransactionList(address: string, transactions: EthTransaction[]): string;
+export declare function formatBalance(address: string, balanceWei: string): string;
+export declare function formatTokenTransfer(transfer: EthTokenTransfer, address: string): string;
+export declare function formatTokenTransferList(address: string, transfers: EthTokenTransfer[]): string;

package/dist/tools/blockchain/formatters.js

@@ -0,0 +1,147 @@
+/**
+ * Formatting utilities for blockchain data
+ */
+import { weiToEth, formatTimestamp, shortenAddress } from "./etherscan-client";
+export function formatTransactionReceipt(hash, receipt) {
+    const status = receipt.status === "0x1" ? "Success" : "Failed";
+    const gasUsed = receipt.gasUsed ? parseInt(String(receipt.gasUsed), 16).toString() : "N/A";
+    const effectiveGasPrice = receipt.effectiveGasPrice
+        ? parseInt(String(receipt.effectiveGasPrice), 16).toString()
+        : "N/A";
+    const gasCostWei = receipt.gasUsed && receipt.effectiveGasPrice
+        ? (BigInt(String(receipt.gasUsed)) * BigInt(String(receipt.effectiveGasPrice))).toString()
+        : "0";
+    const lines = [
+        `## Transaction Details`,
+        ``,
+        `**Hash:** ${hash}`,
+        `**Status:** ${status}`,
+        `**Block:** ${receipt.blockNumber ? parseInt(String(receipt.blockNumber), 16) : "Pending"}`,
+        ``,
+        `### Addresses`,
+        `**From:** ${receipt.from}`,
+        `**To:** ${receipt.to ?? "Contract Creation"}`,
+        receipt.contractAddress ? `**Contract Created:** ${receipt.contractAddress}` : null,
+        ``,
+        `### Gas`,
+        `**Gas Used:** ${gasUsed}`,
+        `**Effective Gas Price:** ${effectiveGasPrice} wei`,
+        `**Transaction Cost:** ${weiToEth(gasCostWei)} ETH`,
+        ``,
+        `### Logs`,
+        `**Log Count:** ${Array.isArray(receipt.logs) ? receipt.logs.length : 0}`,
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function formatTransaction(tx, address) {
+    const isOutgoing = tx.from.toLowerCase() === address.toLowerCase();
+    const direction = isOutgoing ? "OUT" : "IN";
+    const counterparty = isOutgoing ? (tx.to ?? "Contract Creation") : tx.from;
+    const status = tx.isError === "0" ? "OK" : "FAIL";
+    const value = weiToEth(tx.value);
+    const date = formatTimestamp(tx.timeStamp);
+    return [
+        `[${direction}] ${date}`,
+        `  Hash: ${tx.hash}`,
+        `  ${isOutgoing ? "To" : "From"}: ${counterparty}`,
+        `  Value: ${value} ETH`,
+        `  Status: ${status}`,
+        tx.functionName ? `  Function: ${tx.functionName}` : null,
+    ].filter(Boolean).join("\n");
+}
+export function formatTransactionList(address, transactions) {
+    if (transactions.length === 0) {
+        return `No transactions found for address: ${address}`;
+    }
+    const addressLower = address.toLowerCase();
+    const inCount = transactions.filter(tx => tx.to?.toLowerCase() === addressLower).length;
+    const outCount = transactions.length - inCount;
+    const lines = [
+        `## Transactions for ${shortenAddress(address)}`,
+        ``,
+        `**Total:** ${transactions.length} (${inCount} incoming, ${outCount} outgoing)`,
+        `**Address:** ${address}`,
+        ``,
+        `### Recent Transactions`,
+        ``,
+        ...transactions.map(tx => formatTransaction(tx, address)),
+    ];
+    return lines.join("\n");
+}
+export function formatBalance(address, balanceWei) {
+    const balanceEth = weiToEth(balanceWei);
+    const lines = [
+        `## Balance for ${address}`,
+        ``,
+        `**ETH:** ${balanceEth}`,
+        `**Wei:** ${balanceWei}`,
+    ];
+    return lines.join("\n");
+}
+function formatTokenValue(value, decimals) {
+    const dec = parseInt(decimals, 10) || 18;
+    const valueBigInt = BigInt(value);
+    const divisor = BigInt(10 ** dec);
+    const wholePart = valueBigInt / divisor;
+    const fractionPart = valueBigInt % divisor;
+    const fractionStr = fractionPart.toString().padStart(dec, "0");
+    const trimmedFraction = fractionStr.replace(/0+$/, "").slice(0, 6);
+    if (trimmedFraction === "") {
+        return wholePart.toString();
+    }
+    return `${wholePart}.${trimmedFraction}`;
+}
+export function formatTokenTransfer(transfer, address) {
+    const isOutgoing = transfer.from.toLowerCase() === address.toLowerCase();
+    const direction = isOutgoing ? "OUT" : "IN";
+    const counterparty = isOutgoing ? (transfer.to ?? "Unknown") : transfer.from;
+    const value = formatTokenValue(transfer.value, transfer.tokenDecimal);
+    const date = formatTimestamp(transfer.timeStamp);
+    return [
+        `[${direction}] ${date}`,
+        `  Token: ${transfer.tokenName} (${transfer.tokenSymbol})`,
+        `  Hash: ${transfer.hash}`,
+        `  ${isOutgoing ? "To" : "From"}: ${counterparty}`,
+        `  Value: ${value} ${transfer.tokenSymbol}`,
+        `  Contract: ${transfer.contractAddress}`,
+    ].join("\n");
+}
+export function formatTokenTransferList(address, transfers) {
+    if (transfers.length === 0) {
+        return `No ERC-20 token transfers found for address: ${address}`;
+    }
+    const tokenSummary = new Map();
+    let inCount = 0;
+    let outCount = 0;
+    const addressLower = address.toLowerCase();
+    for (const transfer of transfers) {
+        const isOutgoing = transfer.from.toLowerCase() === addressLower;
+        if (!tokenSummary.has(transfer.contractAddress)) {
+            tokenSummary.set(transfer.contractAddress, { in: 0, out: 0, symbol: transfer.tokenSymbol });
+        }
+        const stats = tokenSummary.get(transfer.contractAddress);
+        if (isOutgoing) {
+            stats.out++;
+            outCount++;
+        }
+        else {
+            stats.in++;
+            inCount++;
+        }
+    }
+    const lines = [
+        `## ERC-20 Token Transfers for ${shortenAddress(address)}`,
+        ``,
+        `**Total:** ${transfers.length} transfers (${inCount} incoming, ${outCount} outgoing)`,
+        `**Address:** ${address}`,
+        `**Unique Tokens:** ${tokenSummary.size}`,
+        ``,
+        `### Token Summary`,
+        ...Array.from(tokenSummary.entries()).map(([contract, stats]) => `- ${stats.symbol}: ${stats.in} in, ${stats.out} out (${shortenAddress(contract)})`),
+        ``,
+        `### Recent Transfers`,
+        ``,
+        ...transfers.map(t => formatTokenTransfer(t, address)),
+    ];
+    return lines.join("\n");
+}

package/dist/tools/blockchain/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Blockchain tools for Ethereum transaction and address tracing
+ */
+export { EtherscanClient, EtherscanClientError, weiToEth, formatTimestamp, shortenAddress, } from "./etherscan-client";
+export { formatTransactionReceipt, formatTransactionList, formatBalance, formatTokenTransferList, } from "./formatters";
+export { ethTransactionTool, getTransactionDetails, type EthTransactionArgs, } from "./eth-transaction";
+export { ethAddressTxsTool, getAddressTransactions, type EthAddressTxsArgs, } from "./eth-address-txs";
+export { ethAddressBalanceTool, getAddressBalance, type EthAddressBalanceArgs, } from "./eth-address-balance";
+export { ethTokenTransfersTool, getTokenTransfers, type EthTokenTransfersArgs, } from "./eth-token-transfers";
+export * from "./types";

package/dist/tools/blockchain/index.js

@@ -0,0 +1,10 @@
+/**
+ * Blockchain tools for Ethereum transaction and address tracing
+ */
+export { EtherscanClient, EtherscanClientError, weiToEth, formatTimestamp, shortenAddress, } from "./etherscan-client";
+export { formatTransactionReceipt, formatTransactionList, formatBalance, formatTokenTransferList, } from "./formatters";
+export { ethTransactionTool, getTransactionDetails, } from "./eth-transaction";
+export { ethAddressTxsTool, getAddressTransactions, } from "./eth-address-txs";
+export { ethAddressBalanceTool, getAddressBalance, } from "./eth-address-balance";
+export { ethTokenTransfersTool, getTokenTransfers, } from "./eth-token-transfers";
+export * from "./types";

package/dist/tools/blockchain/tools.test.d.ts

@@ -0,0 +1 @@
+export {};