@coinbase/agentkit 0.1.1 → 0.2.0

package/dist/action-providers/spl/index.d.ts

@@ -0,0 +1 @@
+export * from "./splActionProvider";

package/dist/action-providers/spl/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./splActionProvider"), exports);

package/dist/action-providers/spl/schemas.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Schema for transferring SPL tokens to another address.
+ */
+export declare const TransferTokenSchema: z.ZodObject<{
+    recipient: z.ZodString;
+    mintAddress: z.ZodString;
+    amount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    amount: number;
+    recipient: string;
+    mintAddress: string;
+}, {
+    amount: number;
+    recipient: string;
+    mintAddress: string;
+}>;

package/dist/action-providers/spl/schemas.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransferTokenSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Schema for transferring SPL tokens to another address.
+ */
+exports.TransferTokenSchema = zod_1.z
+    .object({
+    recipient: zod_1.z.string().describe("The recipient's Solana address"),
+    mintAddress: zod_1.z.string().describe("The SPL token's mint address"),
+    amount: zod_1.z.number().positive().describe("Amount of tokens to transfer"),
+})
+    .describe("Transfer SPL tokens to another Solana address");

package/dist/action-providers/spl/splActionProvider.d.ts

@@ -0,0 +1,37 @@
+import { ActionProvider } from "../actionProvider";
+import { Network } from "../../network";
+import { SvmWalletProvider } from "../../wallet-providers/svmWalletProvider";
+import { z } from "zod";
+import { TransferTokenSchema } from "./schemas";
+/**
+ * SplActionProvider serves as a provider for SPL token actions.
+ * It provides SPL token transfer functionality.
+ */
+export declare class SplActionProvider extends ActionProvider<SvmWalletProvider> {
+    /**
+     * Creates a new SplActionProvider instance.
+     */
+    constructor();
+    /**
+     * Transfer SPL tokens to another address.
+     *
+     * @param walletProvider - The wallet provider to use for the transfer
+     * @param args - Transfer parameters including recipient address, mint address, and amount
+     * @returns A message indicating success or failure with transaction details
+     */
+    transfer(walletProvider: SvmWalletProvider, args: z.infer<typeof TransferTokenSchema>): Promise<string>;
+    /**
+     * Checks if the action provider supports the given network.
+     * Only supports Solana networks.
+     *
+     * @param network - The network to check support for
+     * @returns True if the network is a Solana network
+     */
+    supportsNetwork(network: Network): boolean;
+}
+/**
+ * Factory function to create a new SplActionProvider instance.
+ *
+ * @returns A new SplActionProvider instance
+ */
+export declare const splActionProvider: () => SplActionProvider;

package/dist/action-providers/spl/splActionProvider.js

@@ -0,0 +1,112 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splActionProvider = exports.SplActionProvider = void 0;
+const actionProvider_1 = require("../actionProvider");
+const svmWalletProvider_1 = require("../../wallet-providers/svmWalletProvider");
+const zod_1 = require("zod");
+const actionDecorator_1 = require("../actionDecorator");
+const schemas_1 = require("./schemas");
+const web3_js_1 = require("@solana/web3.js");
+/**
+ * SplActionProvider serves as a provider for SPL token actions.
+ * It provides SPL token transfer functionality.
+ */
+class SplActionProvider extends actionProvider_1.ActionProvider {
+    /**
+     * Creates a new SplActionProvider instance.
+     */
+    constructor() {
+        super("spl", []);
+    }
+    /**
+     * Transfer SPL tokens to another address.
+     *
+     * @param walletProvider - The wallet provider to use for the transfer
+     * @param args - Transfer parameters including recipient address, mint address, and amount
+     * @returns A message indicating success or failure with transaction details
+     */
+    async transfer(walletProvider, args) {
+        try {
+            const connection = walletProvider.getConnection();
+            const fromPubkey = walletProvider.getPublicKey();
+            const toPubkey = new web3_js_1.PublicKey(args.recipient);
+            const mintPubkey = new web3_js_1.PublicKey(args.mintAddress);
+            const { getMint, getAssociatedTokenAddress, getAccount, createAssociatedTokenAccountInstruction, createTransferCheckedInstruction, } = await import("@solana/spl-token");
+            const mintInfo = await getMint(connection, mintPubkey);
+            const adjustedAmount = args.amount * Math.pow(10, mintInfo.decimals);
+            const sourceAta = await getAssociatedTokenAddress(mintPubkey, fromPubkey);
+            const destinationAta = await getAssociatedTokenAddress(mintPubkey, toPubkey);
+            const instructions = [];
+            const sourceAccount = await getAccount(connection, sourceAta);
+            if (sourceAccount.amount < BigInt(adjustedAmount)) {
+                throw new Error(`Insufficient token balance. Have ${sourceAccount.amount}, need ${adjustedAmount}`);
+            }
+            try {
+                await getAccount(connection, destinationAta);
+            }
+            catch {
+                instructions.push(createAssociatedTokenAccountInstruction(fromPubkey, destinationAta, toPubkey, mintPubkey));
+            }
+            instructions.push(createTransferCheckedInstruction(sourceAta, mintPubkey, destinationAta, fromPubkey, adjustedAmount, mintInfo.decimals));
+            const tx = new web3_js_1.VersionedTransaction(web3_js_1.MessageV0.compile({
+                payerKey: fromPubkey,
+                instructions: instructions,
+                recentBlockhash: (await connection.getLatestBlockhash()).blockhash,
+            }));
+            const signature = await walletProvider.signAndSendTransaction(tx);
+            await walletProvider.waitForSignatureResult(signature);
+            return [
+                `Successfully transferred ${args.amount} tokens to ${args.recipient}`,
+                `Token mint: ${args.mintAddress}`,
+                `Signature: ${signature}`,
+            ].join("\n");
+        }
+        catch (error) {
+            return `Error transferring SPL tokens: ${error}`;
+        }
+    }
+    /**
+     * Checks if the action provider supports the given network.
+     * Only supports Solana networks.
+     *
+     * @param network - The network to check support for
+     * @returns True if the network is a Solana network
+     */
+    supportsNetwork(network) {
+        return network.protocolFamily === "svm";
+    }
+}
+exports.SplActionProvider = SplActionProvider;
+__decorate([
+    (0, actionDecorator_1.CreateAction)({
+        name: "transfer",
+        description: `
+    This tool will transfer SPL tokens to another address.
+    - Amount should be specified in token units (not raw)
+    - Recipient must be a valid Solana address
+    - Mint address must be a valid SPL token mint
+    - Ensures sufficient token balance before transfer
+    - Returns transaction details
+    `,
+        schema: schemas_1.TransferTokenSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [svmWalletProvider_1.SvmWalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], SplActionProvider.prototype, "transfer", null);
+/**
+ * Factory function to create a new SplActionProvider instance.
+ *
+ * @returns A new SplActionProvider instance
+ */
+const splActionProvider = () => new SplActionProvider();
+exports.splActionProvider = splActionProvider;

package/dist/action-providers/spl/splActionProvider.test.d.ts

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

package/dist/action-providers/spl/splActionProvider.test.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const web3_js_1 = require("@solana/web3.js");
+const splActionProvider_1 = require("./splActionProvider");
+jest.mock("@solana/web3.js", () => ({
+    ...jest.requireActual("@solana/web3.js"),
+    Connection: jest.fn(),
+    SendTransactionError: jest.fn().mockReturnValue({
+        message: "Failed to send",
+        toString: () => "Failed to send",
+    }),
+    VersionedTransaction: jest.fn().mockReturnValue({
+        sign: jest.fn(),
+    }),
+    MessageV0: {
+        compile: jest.fn().mockReturnValue({}),
+    },
+}));
+jest.mock("@solana/spl-token", () => ({
+    getAssociatedTokenAddress: jest.fn(),
+    getMint: jest.fn(),
+    getAccount: jest.fn(),
+    createAssociatedTokenAccountInstruction: jest.fn(),
+    createTransferCheckedInstruction: jest.fn(),
+}));
+jest.mock("../../wallet-providers/svmWalletProvider");
+describe("SplActionProvider", () => {
+    let actionProvider;
+    let mockWallet;
+    let mockConnection;
+    let mockGetAssociatedTokenAddress;
+    let mockGetMint;
+    let mockGetAccount;
+    /**
+     * Set up test environment before each test.
+     * Initializes mocks and creates fresh instances of required objects.
+     */
+    beforeEach(() => {
+        jest.clearAllMocks();
+        const mocked = jest.requireMock("@solana/spl-token");
+        mockGetAssociatedTokenAddress = mocked.getAssociatedTokenAddress;
+        mockGetMint = mocked.getMint;
+        mockGetAccount = mocked.getAccount;
+        mockGetMint.mockResolvedValue({ decimals: 6 });
+        mockGetAccount.mockRejectedValue(new Error("getAccount mock not implemented for this test"));
+        actionProvider = new splActionProvider_1.SplActionProvider();
+        mockConnection = {
+            getLatestBlockhash: jest.fn().mockResolvedValue({ blockhash: "mockedBlockhash" }),
+        };
+        const MOCK_SIGNATURE = "mock-signature";
+        const mockSignatureReceipt = {
+            context: { slot: 1234 },
+            value: { err: null },
+        };
+        mockWallet = {
+            getConnection: jest.fn().mockReturnValue(mockConnection),
+            getPublicKey: jest.fn().mockReturnValue(new web3_js_1.PublicKey("11111111111111111111111111111111")),
+            signAndSendTransaction: jest.fn().mockResolvedValue(MOCK_SIGNATURE),
+            waitForSignatureResult: jest.fn().mockResolvedValue(mockSignatureReceipt),
+            getAddress: jest.fn().mockReturnValue("11111111111111111111111111111111"),
+            getNetwork: jest.fn().mockReturnValue({ protocolFamily: "svm", networkId: "mainnet" }),
+            getName: jest.fn().mockReturnValue("mock-wallet"),
+            getBalance: jest.fn().mockResolvedValue(BigInt(1000000000)),
+            nativeTransfer: jest.fn(),
+        };
+    });
+    describe("constructor", () => {
+        /**
+         * Test that the SPL action provider is created with the correct name.
+         */
+        it("should create a provider with correct name", () => {
+            expect(actionProvider["name"]).toBe("spl");
+        });
+    });
+    describe("supportsNetwork", () => {
+        /**
+         * Test that the provider correctly identifies Solana networks as supported.
+         */
+        it("should return true for Solana networks", () => {
+            const network = {
+                protocolFamily: "svm",
+                networkId: "solana-mainnet",
+            };
+            expect(actionProvider.supportsNetwork(network)).toBe(true);
+        });
+        /**
+         * Test that the provider correctly identifies non-Solana networks as unsupported.
+         */
+        it("should return false for non-Solana networks", () => {
+            const network = {
+                protocolFamily: "evm",
+                networkId: "ethereum-mainnet",
+            };
+            expect(actionProvider.supportsNetwork(network)).toBe(false);
+        });
+    });
+    describe("transfer", () => {
+        const MINT_ADDRESS = "So11111111111111111111111111111111111111112";
+        const RECIPIENT_ADDRESS = "DjXsn34uz8yCBQ8bevLrEPYYC1RvhHvjzuVF8opNc4K2";
+        const SENDER_ADDRESS = "11111111111111111111111111111111";
+        const MOCK_SIGNATURE = "mock-signature";
+        const transferArgs = {
+            recipient: RECIPIENT_ADDRESS,
+            mintAddress: MINT_ADDRESS,
+            amount: 100,
+        };
+        const mockTokenAccount = {
+            amount: BigInt(1000000000),
+            address: new web3_js_1.PublicKey(MINT_ADDRESS),
+            mint: new web3_js_1.PublicKey(MINT_ADDRESS),
+            owner: new web3_js_1.PublicKey(RECIPIENT_ADDRESS),
+            delegate: null,
+            delegatedAmount: BigInt(0),
+            closeAuthority: null,
+            isFrozen: false,
+            isNative: false,
+            rentExemptReserve: null,
+            isInitialized: true,
+            tlvData: new Map(),
+        };
+        const mockSignatureReceipt = {
+            context: { slot: 1234 },
+            value: { err: null },
+        };
+        beforeEach(() => {
+            mockWallet.getPublicKey.mockReturnValue(new web3_js_1.PublicKey(SENDER_ADDRESS));
+            mockWallet.getAddress.mockReturnValue(SENDER_ADDRESS);
+            mockWallet.signAndSendTransaction.mockResolvedValue(MOCK_SIGNATURE);
+            mockWallet.waitForSignatureResult.mockResolvedValue(mockSignatureReceipt);
+        });
+        /**
+         * Test successful SPL token transfer with all required steps:
+         * - Account validation
+         * - Instruction creation
+         * - Signing
+         * - Sending
+         * - Receipt confirmation
+         */
+        it("should successfully transfer SPL tokens", async () => {
+            mockGetAccount.mockResolvedValue(mockTokenAccount);
+            const result = await actionProvider.transfer(mockWallet, transferArgs);
+            expect(mockGetAssociatedTokenAddress).toHaveBeenNthCalledWith(1, new web3_js_1.PublicKey(transferArgs.mintAddress), new web3_js_1.PublicKey(SENDER_ADDRESS));
+            expect(mockGetAssociatedTokenAddress).toHaveBeenNthCalledWith(2, new web3_js_1.PublicKey(transferArgs.mintAddress), new web3_js_1.PublicKey(transferArgs.recipient));
+            expect(mockGetMint).toHaveBeenCalledWith(mockConnection, new web3_js_1.PublicKey(transferArgs.mintAddress));
+            expect(mockGetAccount).toHaveBeenCalled();
+            expect(mockWallet.signAndSendTransaction).toHaveBeenCalled();
+            expect(mockWallet.waitForSignatureResult).toHaveBeenCalledWith(MOCK_SIGNATURE);
+            expect(result).toContain(`Successfully transferred ${transferArgs.amount} tokens`);
+            expect(result).toContain(`to ${transferArgs.recipient}`);
+            expect(result).toContain(`Token mint: ${transferArgs.mintAddress}`);
+            expect(result).toContain(`Signature: ${MOCK_SIGNATURE}`);
+        });
+        /**
+         * Test handling of insufficient balance.
+         * Verifies that the provider properly checks token balances and prevents transfers when funds are insufficient.
+         */
+        it("should handle insufficient balance", async () => {
+            mockGetAccount.mockResolvedValue({
+                ...mockTokenAccount,
+                amount: BigInt(10000000),
+            });
+            const result = await actionProvider.transfer(mockWallet, transferArgs);
+            expect(result).toBe("Error transferring SPL tokens: Error: Insufficient token balance. Have 10000000, need 100000000");
+        });
+        /**
+         * Test handling of Solana-specific send errors.
+         * Verifies that the provider properly handles and reports SendTransactionError instances.
+         */
+        it("should handle SendTransactionError", async () => {
+            mockGetAccount.mockResolvedValue(mockTokenAccount);
+            const error = new web3_js_1.SendTransactionError({
+                logs: [],
+                action: "send",
+                signature: "mock-signature",
+                transactionMessage: "Failed to send",
+            });
+            mockWallet.signAndSendTransaction.mockRejectedValue(error);
+            const result = await actionProvider.transfer(mockWallet, transferArgs);
+            expect(result).toBe("Error transferring SPL tokens: Failed to send");
+        });
+        /**
+         * Test handling of general errors during transfer.
+         * Verifies that the provider properly handles and reports unexpected errors.
+         */
+        it("should handle regular errors", async () => {
+            mockGetAccount.mockResolvedValue(mockTokenAccount);
+            const error = new Error("Regular error message");
+            mockWallet.signAndSendTransaction.mockRejectedValue(error);
+            const result = await actionProvider.transfer(mockWallet, transferArgs);
+            expect(result).toBe("Error transferring SPL tokens: Error: Regular error message");
+        });
+        /**
+         * Test that ATA is created by default when missing
+         */
+        it("should create ATA by default when missing", async () => {
+            mockGetAccount
+                .mockResolvedValueOnce(mockTokenAccount)
+                .mockRejectedValueOnce(new Error("Account does not exist"))
+                .mockResolvedValue(mockTokenAccount);
+            const result = await actionProvider.transfer(mockWallet, transferArgs);
+            const { createAssociatedTokenAccountInstruction } = jest.requireMock("@solana/spl-token");
+            expect(createAssociatedTokenAccountInstruction).toHaveBeenCalled();
+            expect(result).toContain(`Successfully transferred ${transferArgs.amount} tokens`);
+        });
+    });
+});

package/dist/action-providers/wallet/walletActionProvider.d.ts

@@ -20,7 +20,7 @@ export declare class WalletActionProvider extends ActionProvider {
      */
     getWalletDetails(walletProvider: WalletProvider, _: z.infer<typeof GetWalletDetailsSchema>): Promise<string>;
     /**
-     * Transfers a specified amount of an asset to a destination onchain.
+     * Transfers a specified amount of native currency to a destination onchain.
      *
      * @param walletProvider - The wallet provider to transfer from.
      * @param args - The input arguments for the action.

package/dist/action-providers/wallet/walletActionProvider.js

@@ -10,12 +10,16 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.walletActionProvider = exports.WalletActionProvider = void 0;
-const decimal_js_1 = require("decimal.js");
 const zod_1 = require("zod");
 const actionDecorator_1 = require("../actionDecorator");
 const actionProvider_1 = require("../actionProvider");
 const wallet_providers_1 = require("../../wallet-providers");
 const schemas_1 = require("./schemas");
+const PROTOCOL_FAMILY_TO_TERMINOLOGY = {
+    evm: { unit: "WEI", displayUnit: "ETH", type: "Transaction hash", verb: "transaction" },
+    svm: { unit: "LAMPORTS", displayUnit: "SOL", type: "Signature", verb: "transfer" },
+};
+const DEFAULT_TERMINOLOGY = { unit: "", displayUnit: "", type: "Hash", verb: "transfer" };
 /**
  * WalletActionProvider provides actions for getting basic wallet information.
  */
@@ -47,24 +51,24 @@ class WalletActionProvider extends actionProvider_1.ActionProvider {
             const network = walletProvider.getNetwork();
             const balance = await walletProvider.getBalance();
             const name = walletProvider.getName();
-            // Convert balance from Wei to ETH using Decimal for precision
-            const ethBalance = new decimal_js_1.Decimal(balance.toString()).div(new decimal_js_1.Decimal(10).pow(18));
-            return `Wallet Details:
-- Provider: ${name}
-- Address: ${address}
-- Network: 
-  * Protocol Family: ${network.protocolFamily}
-  * Network ID: ${network.networkId || "N/A"}
-  * Chain ID: ${network.chainId || "N/A"}
-- ETH Balance: ${ethBalance.toFixed(6)} ETH
-- Native Balance: ${balance.toString()} WEI`;
+            const terminology = PROTOCOL_FAMILY_TO_TERMINOLOGY[network.protocolFamily] || DEFAULT_TERMINOLOGY;
+            return [
+                "Wallet Details:",
+                `- Provider: ${name}`,
+                `- Address: ${address}`,
+                "- Network:",
+                `  * Protocol Family: ${network.protocolFamily}`,
+                `  * Network ID: ${network.networkId || "N/A"}`,
+                `  * Chain ID: ${network.chainId || "N/A"}`,
+                `- Native Balance: ${balance.toString()} ${terminology.unit}`,
+            ].join("\n");
         }
         catch (error) {
             return `Error getting wallet details: ${error}`;
         }
     }
     /**
-     * Transfers a specified amount of an asset to a destination onchain.
+     * Transfers a specified amount of native currency to a destination onchain.
      *
      * @param walletProvider - The wallet provider to transfer from.
      * @param args - The input arguments for the action.
@@ -72,11 +76,21 @@ class WalletActionProvider extends actionProvider_1.ActionProvider {
      */
     async nativeTransfer(walletProvider, args) {
         try {
+            const { protocolFamily } = walletProvider.getNetwork();
+            const terminology = PROTOCOL_FAMILY_TO_TERMINOLOGY[protocolFamily] || DEFAULT_TERMINOLOGY;
+            if (protocolFamily === "evm" && !args.to.startsWith("0x")) {
+                args.to = `0x${args.to}`;
+            }
             const result = await walletProvider.nativeTransfer(args.to, args.value);
-            return `Transferred ${args.value} ETH to ${args.to}.\nTransaction hash: ${result}`;
+            return [
+                `Transferred ${args.value} ${terminology.displayUnit} to ${args.to}`,
+                `${terminology.type}: ${result}`,
+            ].join("\n");
         }
         catch (error) {
-            return `Error transferring the asset: ${error}`;
+            const { protocolFamily } = walletProvider.getNetwork();
+            const terminology = PROTOCOL_FAMILY_TO_TERMINOLOGY[protocolFamily] || DEFAULT_TERMINOLOGY;
+            return `Error during ${terminology.verb}: ${error}`;
         }
     }
 }
@@ -88,8 +102,7 @@ __decorate([
     This tool will return the details of the connected wallet including:
     - Wallet address
     - Network information (protocol family, network ID, chain ID)
-    - ETH token balance
-    - Native token balance
+    - Native token balance (ETH for EVM networks, SOL for Solana networks)
     - Wallet provider name
     `,
         schema: schemas_1.GetWalletDetailsSchema,
@@ -105,7 +118,7 @@ __decorate([
 This tool will transfer native tokens from the wallet to another onchain address.
 
 It takes the following inputs:
-- amount: The amount to transfer in whole units e.g. 1 ETH or 0.00001 ETH
+- amount: The amount to transfer in whole units (e.g. 1 ETH, 0.1 SOL)
 - destination: The address to receive the funds
 
 Important notes: