feat: cosmos plugin - IBC swap action

characters/cosmosHelper.character.json

@@ -5,9 +5,6 @@
     "settings": {
         "voice": {
             "model": "en_US-male-medium"
-        },
-        "chains": {
-            "cosmos": ["axelar", "carbon", "mantrachaintestnet2"]
         }
     },
     "plugins": [],
@@ -26,14 +23,17 @@
         "Knows how Cosmos blockchain works",
         "Knows what actions should be called for token transfer, swapping or bridging",
         "Knows that users might want to do specific actions multiple times and should help them by doing it again.",
-        "Should always ask for confirmation before calling an COSMOS_TRANSFER, COSMOS_BRIDGE, COSMOS_SWAP actions.",
-        "Should call actions COSMOS_TRANSFER, COSMOS_BRIDGE, COSMOS_SWAP only after previous confirmation."
+        "Should always ask for confirmation before calling an COSMOS_TRANSFER, COSMOS_BRIDGE, COSMOS_IBC_SWAP actions.",
+        "Should ask for confirmation ONCE and perform action after getting it. If user wants to change sth in data for transfer, should do it and ask again for confirmation of new data.",
+        "Should call actions COSMOS_TRANSFER, COSMOS_BRIDGE, COSMOS_IBC_SWAP only after previous confirmation."
     ],
     "messageExamples": [
         [
             {
                 "user": "{{user1}}",
-                "content": { "text": "Show my balances of my wallet on {{mantrachaintestnet2}}" }
+                "content": {
+                    "text": "Show my balances of my wallet on {{mantrachaintestnet2}}"
+                }
             },
             {
                 "user": "CosmosHelper",
@@ -45,7 +45,9 @@
         [
             {
                 "user": "{{user1}}",
-                "content": { "text": "How does IBC work?" }
+                "content": {
+                    "text": "How does IBC work?"
+                }
             },
             {
                 "user": "CosmosHelper",
@@ -57,7 +59,9 @@
         [
             {
                 "user": "{{user1}}",
-                "content": { "text": "What is CosmWasm?" }
+                "content": {
+                    "text": "What is CosmWasm?"
+                }
             },
             {
                 "user": "CosmosHelper",
@@ -69,7 +73,9 @@
         [
             {
                 "user": "{{user1}}",
-                "content": { "text": "Can you help me transfer tokens?" }
+                "content": {
+                    "text": "Can you help me transfer tokens?"
+                }
             },
             {
                 "user": "CosmosHelper",
@@ -81,7 +87,9 @@
         [
             {
                 "user": "{{user1}}",
-                "content": { "text": "Make transfer 0.0001 OM to mantra13248w8dtnn07sxc3gq4l3ts4rvfyat6fks0ecj on mantrachaintestnet2" }
+                "content": {
+                    "text": "Make transfer 0.0001 OM to mantra13248w8dtnn07sxc3gq4l3ts4rvfyat6fks0ecj on mantrachaintestnet2"
+                }
             },
             {
                 "user": "CosmosHelper",

packages/plugin-cosmos/README.md

@@ -134,6 +134,78 @@ Yes
 
 ---
 
+### Token IBC Swap
+This action allows swapping tokens between chains. The implementation of swapping is based on the Skip API and uses the @skip-go/client library.
+To place transactions on chains, they must first be added to the env file. Specifically:
+```env
+COSMOS_AVAILABLE_CHAINS=osmosis,neutron,axelar,cosmoshub,terra2,pryzm
+```
+Keep in mind that most swaps require intermediate chains. These chains must also be included in the env file.
+
+You can check which chains are supported by the Skip API and this plugin here: [Skip API Documentation](https://docs.skip.build/).
+
+The list below contains all supported chains extracted from the Skip API:
+```env
+COSMOS_AVAILABLE_CHAINS=terra2,quicksilver,coreum,regen,mars,passage,dhealth,lumnetwork,provenance,chihuahua,pryzm,fetchhub,comdex,kyve,xpla,umee,celestia,osmosis,empowerchain,migaloo,dymension,kujira,self,humans,gitopia,agoric,doravota,int3face,quasar,gravitybridge,kava,sifchain,seda,shentu,decentr,cronos,carbon,stride,haqq,jackal,omniflixhub,noble,sentinel,nolus,odin,assetmantle,dydx,beezee,axelar,nois,mantrachain,elys,crescent,synternet,xion,source,akash,sei,canto,teritori,stargaze,titan,aura,evmos,archway,gateway,cheqd,milkyway,nibiru,cosmoshub,ununifi,nyx,bitsong,cryptoorgchain,neutron,penumbra,terra,shido,sommelier,saga,secretnetwork,chain4energy,juno,andromeda,planq,lava,oraichain,injective,persistence,composable
+```
+
+#### Example prompts:
+
+##### Default flow
+An example of the default flow of a swap request:
+
+1. User input:
+```
+    Swap 10 OSMO on osmosis to ATOM on cosmoshub
+```
+2. Agent asks for confirmation:
+```
+About to swap 10 OSMO on osmosis to ATAOM on cosmoshub. I would like to confirm the transaction details. Please confirm that you would like to proceed with the swap.
+```
+3. User confiramation:
+```
+confirming / yes
+```
+4. Agent calls action and responds after completing:
+```
+Successfuly swapped 10 OSMO tokens to ATOM on chain cosmoshub.
+Transaction Hash: E84F36D6EEFAA6D7B70827F34EDAB83258BB86EFE33AEA1F4559D00B30CD3B50
+```
+
+##### Special case handling
+An example of a flow when there is more than one token with the same symbol on the destination chain (e.g., multiple USDC tokens):
+1. User input:
+```
+Swap 10 OSMO on osmosis to ATOM on cosmoshub
+```
+2. Agent asks for confirmation:
+```
+About to swap 10 OSMO on osmosis to ATAOM on cosmoshub. I would like to confirm the transaction details. Please confirm that you would like to proceed with the swap.
+```
+3. User confirmation:
+```
+confirming / yes
+```
+4.  Model response:
+```
+I will now initiate the swap of 10 OSMO on the Osmosis chain to USDC on the Axelar chain. Please wait for the transaction to complete. If you need to swap more assets, feel free to let me know.
+
+Error occured. Swap was not performed. Please provide denom for coin: USDC, on Chain Name: axelar. It is necessary as the symbol USDC is not unique among coins on chain axelar. 
+Select one from found assets:
+Symbol: USDC Desc: Circle's stablecoin on Axelar Denom: uusdc,
+Symbol: USDC Desc: Circle's stablecoin from Polygon on Axelar Denom: polygon-uusdc,
+Symbol: USDC Desc: Circle's stablecoin from Avalanche on Axelar Denom: avalanche-uusdc
+```
+5.  User response:
+```
+Swap 10 OSMO on osmosis to USDC with denom uusdc on axelar
+```
+6. Action call and agent response:
+```
+Successfuly swapped 10 OSMO tokens to USDC uusdc on chain axelar.
+Transaction Hash: E84F36D6EEFAA6D7B70827F34EDAB83258BB86EFE33AEA1F4559D00B30CD3B50
+```
+
 ## Contribution
 
 The plugin includes comprehensive tests. Before submitting any pull requests, ensure all tests pass.

packages/plugin-cosmos/src/actions/ibc-swap/index.ts

@@ -0,0 +1,196 @@
+import {
+    composeContext,
+    generateObjectDeprecated,
+    HandlerCallback,
+    IAgentRuntime,
+    Memory,
+    ModelClass,
+    State,
+} from "@elizaos/core";
+
+import { initWalletChainsData } from "../../providers/wallet/utils";
+import { cosmosIBCSwapTemplate } from "../../templates";
+import type {
+    ICosmosPluginOptions,
+    ICosmosWalletChains,
+} from "../../shared/interfaces";
+import { IBCSwapActionParams } from "./types.ts";
+import { IBCSwapAction } from "./services/ibc-swap-action-service.ts";
+import { prepareAmbiguityErrorMessage } from "./services/ibc-swap-utils.ts";
+
+export const createIBCSwapAction = (pluginOptions: ICosmosPluginOptions) => ({
+    name: "COSMOS_IBC_SWAP",
+    description: "Swaps tokens on cosmos chains",
+    handler: async (
+        _runtime: IAgentRuntime,
+        _message: Memory,
+        state: State,
+        _options: { [key: string]: unknown },
+        _callback?: HandlerCallback
+    ) => {
+        const cosmosIBCSwapContext = composeContext({
+            state: state,
+            template: cosmosIBCSwapTemplate,
+            templatingEngine: "handlebars",
+        });
+
+        const cosmosIBCSwapContent = await generateObjectDeprecated({
+            runtime: _runtime,
+            context: cosmosIBCSwapContext,
+            modelClass: ModelClass.SMALL,
+        });
+
+        const paramOptions: IBCSwapActionParams = {
+            fromChainName: cosmosIBCSwapContent.fromChainName,
+            fromTokenSymbol: cosmosIBCSwapContent.fromTokenSymbol,
+            fromTokenAmount: cosmosIBCSwapContent.fromTokenAmount,
+            toTokenSymbol: cosmosIBCSwapContent.toTokenSymbol,
+            toChainName: cosmosIBCSwapContent.toChainName,
+            toTokenDenom: cosmosIBCSwapContent?.toTokenDenom || undefined,
+            fromTokenDenom: cosmosIBCSwapContent?.fromTokenDenom || undefined,
+        };
+
+        console.log(
+            "Parameters extracted from user prompt: ",
+            JSON.stringify(paramOptions, null, 2)
+        );
+
+        try {
+            const walletProvider: ICosmosWalletChains =
+                await initWalletChainsData(_runtime);
+
+            const action = new IBCSwapAction(walletProvider);
+
+            const customAssets = (pluginOptions?.customChainData ?? []).map(
+                (chainData) => chainData.assets
+            );
+
+            if (_callback) {
+
+                const swapResp = await action.execute(
+                    paramOptions,
+                    customAssets,
+                    _callback
+                );
+
+                const text =
+                    swapResp.status === "STATE_COMPLETED_SUCCESS"
+                        ? `Successfully swapped ${swapResp.fromTokenAmount} ${swapResp.fromTokenSymbol} tokens to ${swapResp.toTokenSymbol} on chain ${swapResp.toChainName}.\nTransaction Hash: ${swapResp.txHash}`
+                        : `Error occured swapping ${swapResp.fromTokenAmount} ${swapResp.fromTokenSymbol} tokens to ${swapResp.toTokenSymbol} on chain ${swapResp.toChainName}.\nTransaction Hash: ${swapResp.txHash}, try again`;
+                await _callback({
+                    text: text,
+                    content: {
+                        success:
+                            swapResp.status === "STATE_COMPLETED_SUCCESS",
+                        hash: swapResp.txHash,
+                        fromTokenAmount: paramOptions.fromTokenAmount,
+                        fromToken: paramOptions.fromTokenSymbol,
+                        toToken: paramOptions.toTokenSymbol,
+                        fromChain: paramOptions.fromChainName,
+                        toChain: paramOptions.toChainName,
+                    },
+                });
+            }
+            return true;
+        } catch (error) {
+            console.error("Error during ibc token swap:", error);
+
+            const regex =
+                /Ambiguity Error.*value:([^\s.]+)\s+chainName:([^\s.]+)/;
+            const match = error.message.match(regex);
+
+            if (match) {
+                const value = match[1];
+                const chainName = match[2];
+
+                if (_callback) {
+                    await _callback({
+                        text: prepareAmbiguityErrorMessage(value, chainName),
+                        content: { error: error.message },
+                    });
+                }
+            } else {
+                console.error("Unhandled error:", error);
+
+                if (_callback) {
+                    await _callback({
+                        text: `Error ibc swapping tokens: ${error.message}`,
+                        content: { error: error.message },
+                    });
+                }
+            }
+            return false;
+        }
+    },
+    template: cosmosIBCSwapTemplate,
+    validate: async (runtime: IAgentRuntime) => {
+        const mnemonic = runtime.getSetting("COSMOS_RECOVERY_PHRASE");
+        const availableChains = runtime.getSetting("COSMOS_AVAILABLE_CHAINS");
+        const availableChainsArray = availableChains?.split(",");
+
+        return !(mnemonic && availableChains && availableChainsArray.length);
+    },
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Swap {{0.0001 ATOM}} from {{cosmoshub}} to {{OM}} on {{mantrachain1}}",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user2}}",
+                content: {
+                    text: "Do you confirm the swap?",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Yes",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user2}}",
+                content: {
+                    text: "Starting swap transaction. Keep in mind that it might take couple of minutes",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+        ],
+        [
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Swap {{0.0001 OM}} from {{mantrachain}} to {{OSMO}} on {{osmosis}}",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user2}}",
+                content: {
+                    text: "Do you confirm the swap?",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user1}}",
+                content: {
+                    text: "Yes",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+            {
+                user: "{{user2}}",
+                content: {
+                    text: "Starting swap transaction. Keep in mind that it might take couple of minutes",
+                    action: "COSMOS_IBC_SWAP",
+                },
+            },
+        ],
+    ],
+    similes: ["COSMOS_SWAP", "COSMOS_SWAP_IBC"],
+});

packages/plugin-cosmos/src/actions/ibc-swap/schema.ts

@@ -0,0 +1,11 @@
+import {z} from "zod";
+
+export const IBCSwapParamsSchema = z.object({
+    fromChainName: z.string().min(1),
+    fromTokenSymbol: z.string().regex(/^[A-Z0-9]+$/),
+    fromTokenAmount: z.string().regex(/^\d+$/),
+    toTokenSymbol: z.string().regex(/^[A-Z0-9]+$/),
+    toChainName: z.string().min(1),
+    toTokenDenom: z.string().regex(/^ibc\/[A-F0-9]{64}$/),
+    fromTokenDenom: z.string().regex(/^ibc\/[A-F0-9]{64}$/),
+});