opencode-froggy 0.2.0 → 0.3.0

package/README.md

@@ -21,6 +21,11 @@ Plugin providing Claude Code–style hooks, specialized agents (doc-writer, code
   - [diff-summary](#diff-summary)
   - [prompt-session](#prompt-session)
   - [list-child-sessions](#list-child-sessions)
+  - [Blockchain](#blockchain)
+    - [eth-transaction](#eth-transaction)
+    - [eth-address-balance](#eth-address-balance)
+    - [eth-address-txs](#eth-address-txs)
+    - [eth-token-transfers](#eth-token-transfers)
 - [Hooks](#hooks)
   - [Configuration Locations](#configuration-locations)
   - [Configuration File Format](#configuration-file-format)
@@ -256,6 +261,126 @@ Child sessions (2):
 
 ---
 
+### Blockchain
+
+Tools for querying Ethereum and EVM-compatible blockchains via Etherscan APIs.
+
+All blockchain tools support multiple chains via the `chainId` parameter:
+
+| Chain ID | Network |
+|----------|---------|
+| `1` | Ethereum (default) |
+| `137` | Polygon |
+| `56` | BSC |
+| `42161` | Arbitrum |
+| `10` | Optimism |
+| `8453` | Base |
+| `43114` | Avalanche |
+| `250` | Fantom |
+| `324` | zkSync |
+
+#### eth-transaction
+
+Get Ethereum transaction details by transaction hash. Returns status, block, addresses, gas costs, and log count.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `hash` | `string` | Yes | - | Transaction hash (0x...) |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// Get transaction on Ethereum mainnet
+ethTransaction({ hash: "0x123abc..." })
+
+// Get transaction on Polygon
+ethTransaction({ 
+  hash: "0x123abc...",
+  chainId: "137"
+})
+```
+
+#### eth-address-balance
+
+Get the ETH balance of an Ethereum address. Returns balance in both ETH and Wei.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// Get balance on Ethereum mainnet
+ethAddressBalance({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// Get balance on Arbitrum
+ethAddressBalance({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  chainId: "42161"
+})
+```
+
+#### eth-address-txs
+
+List Ethereum transactions for an address. Shows incoming and outgoing transactions with values, timestamps, and status.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `limit` | `number` | No | `20` | Maximum number of transactions to return |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// List recent transactions on Ethereum mainnet
+ethAddressTxs({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// List last 50 transactions on Base
+ethAddressTxs({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  limit: 50,
+  chainId: "8453"
+})
+```
+
+#### eth-token-transfers
+
+List ERC-20 token transfers for an Ethereum address. Shows token names, symbols, values, and transaction details.
+
+##### Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `address` | `string` | Yes | - | Ethereum address (0x...) |
+| `limit` | `number` | No | `20` | Maximum number of transfers to return |
+| `chainId` | `string` | No | `"1"` | Chain ID (see table above) |
+
+##### Usage Examples
+
+```typescript
+// List recent token transfers on Ethereum mainnet
+ethTokenTransfers({ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" })
+
+// List last 100 token transfers on Optimism
+ethTokenTransfers({ 
+  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  limit: 100,
+  chainId: "10"
+})
+```
+
+---
+
 ## Hooks
 
 Hooks run actions on session events. Configuration is loaded from standard OpenCode configuration directories.

package/dist/index.js

@@ -5,7 +5,7 @@ import { getGlobalHookDir, getProjectHookDir } from "./config-paths";
 import { hasCodeExtension } from "./code-files";
 import { log } from "./logger";
 import { executeBashAction, DEFAULT_BASH_TIMEOUT, } from "./bash-executor";
-import { gitingestTool, createDiffSummaryTool, createPromptSessionTool, createListChildSessionsTool, } from "./tools";
+import { gitingestTool, createDiffSummaryTool, createPromptSessionTool, createListChildSessionsTool, ethTransactionTool, ethAddressTxsTool, ethAddressBalanceTool, ethTokenTransfersTool, } from "./tools";
 export { parseFrontmatter, loadAgents, loadCommands } from "./loaders";
 // ============================================================================
 // CONSTANTS
@@ -30,7 +30,14 @@ const SmartfrogPlugin = async (ctx) => {
         agents: Object.keys(agents),
         commands: Object.keys(commands),
         hooks: Array.from(hooks.keys()),
-        tools: ["gitingest", "diff-summary"],
+        tools: [
+            "gitingest",
+            "diff-summary",
+            "eth-transaction",
+            "eth-address-txs",
+            "eth-address-balance",
+            "eth-token-transfers",
+        ],
     });
     async function executeHookActions(hook, sessionID, extraLog, options) {
         const prefix = `[hook:${hook.event}]`;
@@ -179,6 +186,10 @@ const SmartfrogPlugin = async (ctx) => {
             "diff-summary": createDiffSummaryTool(ctx.directory),
             "prompt-session": createPromptSessionTool(ctx.client),
             "list-child-sessions": createListChildSessionsTool(ctx.client),
+            "eth-transaction": ethTransactionTool,
+            "eth-address-txs": ethAddressTxsTool,
+            "eth-address-balance": ethAddressBalanceTool,
+            "eth-token-transfers": ethTokenTransfersTool,
         },
         "tool.execute.before": async (input, output) => {
             const sessionID = input.sessionID;

package/dist/tools/blockchain/eth-address-balance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool to get Ethereum address balance
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthAddressBalanceArgs {
+    address: string;
+    chainId?: string;
+}
+export declare function getAddressBalance(address: string, chainId?: string): Promise<string>;
+export declare const ethAddressBalanceTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-address-balance.js

@@ -0,0 +1,37 @@
+/**
+ * Tool to get Ethereum address balance
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatBalance } from "./formatters";
+import { CHAIN_ID_DESCRIPTION } from "./types";
+export async function getAddressBalance(address, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const balanceWei = await client.getBalance(address);
+    return formatBalance(address, balanceWei);
+}
+export const ethAddressBalanceTool = tool({
+    description: "Get the ETH balance of an Ethereum address. " +
+        "Returns balance in both ETH and Wei.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getAddressBalance(args.address, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-address-txs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool to list Ethereum transactions for an address
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthAddressTxsArgs {
+    address: string;
+    limit?: number;
+    chainId?: string;
+}
+export declare function getAddressTransactions(address: string, limit?: number, chainId?: string): Promise<string>;
+export declare const ethAddressTxsTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        limit?: number | undefined;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-address-txs.js

@@ -0,0 +1,41 @@
+/**
+ * Tool to list Ethereum transactions for an address
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatTransactionList } from "./formatters";
+import { DEFAULT_TRANSACTION_LIMIT, CHAIN_ID_DESCRIPTION } from "./types";
+export async function getAddressTransactions(address, limit = DEFAULT_TRANSACTION_LIMIT, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const transactions = await client.getTransactions(address, limit);
+    return formatTransactionList(address, transactions);
+}
+export const ethAddressTxsTool = tool({
+    description: "List Ethereum transactions for an address. " +
+        "Shows incoming and outgoing transactions with values, timestamps, and status.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        limit: tool.schema
+            .number()
+            .optional()
+            .describe(`Maximum number of transactions to return (default: ${DEFAULT_TRANSACTION_LIMIT})`),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getAddressTransactions(args.address, args.limit, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-token-transfers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool to list ERC-20 token transfers for an address
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthTokenTransfersArgs {
+    address: string;
+    limit?: number;
+    chainId?: string;
+}
+export declare function getTokenTransfers(address: string, limit?: number, chainId?: string): Promise<string>;
+export declare const ethTokenTransfersTool: {
+    description: string;
+    args: {
+        address: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        address: string;
+        limit?: number | undefined;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-token-transfers.js

@@ -0,0 +1,41 @@
+/**
+ * Tool to list ERC-20 token transfers for an address
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateAddress } from "./etherscan-client";
+import { formatTokenTransferList } from "./formatters";
+import { DEFAULT_TRANSACTION_LIMIT, CHAIN_ID_DESCRIPTION } from "./types";
+export async function getTokenTransfers(address, limit = DEFAULT_TRANSACTION_LIMIT, chainId) {
+    validateAddress(address);
+    const client = new EtherscanClient(undefined, chainId);
+    const transfers = await client.getTokenTransfers(address, limit);
+    return formatTokenTransferList(address, transfers);
+}
+export const ethTokenTransfersTool = tool({
+    description: "List ERC-20 token transfers for an Ethereum address. " +
+        "Shows token names, symbols, values, and transaction details.",
+    args: {
+        address: tool.schema
+            .string()
+            .describe("Ethereum address (0x...)"),
+        limit: tool.schema
+            .number()
+            .optional()
+            .describe(`Maximum number of transfers to return (default: ${DEFAULT_TRANSACTION_LIMIT})`),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getTokenTransfers(args.address, args.limit, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/blockchain/eth-transaction.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool to get Ethereum transaction details by hash
+ */
+import { type ToolContext } from "@opencode-ai/plugin";
+export interface EthTransactionArgs {
+    hash: string;
+    chainId?: string;
+}
+export declare function getTransactionDetails(hash: string, chainId?: string): Promise<string>;
+export declare const ethTransactionTool: {
+    description: string;
+    args: {
+        hash: import("zod").ZodString;
+        chainId: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        hash: string;
+        chainId?: string | undefined;
+    }, context: ToolContext): Promise<string>;
+};

package/dist/tools/blockchain/eth-transaction.js

@@ -0,0 +1,40 @@
+/**
+ * Tool to get Ethereum transaction details by hash
+ */
+import { tool } from "@opencode-ai/plugin";
+import { EtherscanClient, EtherscanClientError, validateTxHash } from "./etherscan-client";
+import { formatTransactionReceipt } from "./formatters";
+import { CHAIN_ID_DESCRIPTION } from "./types";
+export async function getTransactionDetails(hash, chainId) {
+    validateTxHash(hash);
+    const client = new EtherscanClient(undefined, chainId);
+    const receipt = await client.getTransactionReceipt(hash);
+    if (!receipt) {
+        return `Transaction not found: ${hash}`;
+    }
+    return formatTransactionReceipt(hash, receipt);
+}
+export const ethTransactionTool = tool({
+    description: "Get Ethereum transaction details by transaction hash. " +
+        "Returns status, block, addresses, gas costs, and log count.",
+    args: {
+        hash: tool.schema
+            .string()
+            .describe("Transaction hash (0x...)"),
+        chainId: tool.schema
+            .string()
+            .optional()
+            .describe(CHAIN_ID_DESCRIPTION),
+    },
+    async execute(args, _context) {
+        try {
+            return await getTransactionDetails(args.hash, args.chainId);
+        }
+        catch (error) {
+            if (error instanceof EtherscanClientError) {
+                return `Error: ${error.message}`;
+            }
+            throw error;
+        }
+    },
+});

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

@@ -0,0 +1,25 @@
+/**
+ * Etherscan API client for Ethereum blockchain queries
+ */
+import { type EthTransaction, type EthTokenTransfer, type EthInternalTransaction } from "./types";
+export declare class EtherscanClientError extends Error {
+    constructor(message: string);
+}
+export declare class EtherscanClient {
+    private readonly apiKey;
+    private readonly chainId;
+    private readonly baseUrl;
+    constructor(apiKey?: string, chainId?: string, baseUrl?: string);
+    private request;
+    getBalance(address: string): Promise<string>;
+    getTransactions(address: string, limit?: number): Promise<EthTransaction[]>;
+    getInternalTransactions(address: string, limit?: number): Promise<EthInternalTransaction[]>;
+    getTokenTransfers(address: string, limit?: number): Promise<EthTokenTransfer[]>;
+    getTransactionByHash(hash: string): Promise<EthTransaction | null>;
+    getTransactionReceipt(hash: string): Promise<Record<string, unknown> | null>;
+}
+export declare function weiToEth(wei: string): string;
+export declare function formatTimestamp(timestamp: string): string;
+export declare function shortenAddress(address: string): string;
+export declare function validateAddress(address: string): void;
+export declare function validateTxHash(hash: string): void;

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 {};