intentkit 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

intentkit/skills/enso/route.py

@@ -0,0 +1,300 @@
+from typing import Type
+
+import httpx
+from langchain.tools.base import ToolException
+from langchain_core.runnables import RunnableConfig
+from pydantic import BaseModel, Field
+
+from intentkit.skills.base import SkillContext
+from intentkit.skills.enso.abi.route import ABI_ROUTE
+from intentkit.skills.enso.networks import EnsoGetNetworks
+from intentkit.utils.tx import EvmContractWrapper
+
+from .base import EnsoBaseTool, base_url, default_chain_id
+
+
+class EnsoRouteShortcutInput(BaseModel):
+    """
+    Input model for finding best route for swap or deposit.
+    """
+
+    broadcast_requested: bool = Field(
+        False,
+        description="Whether to broadcast the transaction or not, this is false by default.",
+    )
+    chainId: int = Field(
+        default_chain_id,
+        description="(Optional) Chain ID of the network to execute the transaction on. the default value is the chain_id extracted from networks according to tokenIn and tokenOut",
+    )
+    amountIn: list[int] = Field(
+        description="Amount of tokenIn to swap in wei, you should multiply user's requested value by token decimals."
+    )
+    tokenIn: list[str] = Field(
+        description="Ethereum address of the token to swap or enter into a position from (For ETH, use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)."
+    )
+    tokenOut: list[str] = Field(
+        description="Ethereum address of the token to swap or enter into a position to (For ETH, use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee)."
+    )
+    # Optional inputs
+    # routingStrategy: Literal["router", "delegate", "ensowallet", None] = Field(
+    #     None,
+    #     description="(Optional) Routing strategy to use. Options: 'ensowallet', 'router', 'delegate'.",
+    # )
+    # receiver: str | None = Field(
+    #     None, description="(Optional) Ethereum address of the receiver of the tokenOut."
+    # )
+    # spender: str | None = Field(
+    #     None, description="(Optional) Ethereum address of the spender of the tokenIn."
+    # )
+    # amountOut: list[str] | None = Field(
+    #     None, description="(Optional) Amount of tokenOut to receive."
+    # )
+    # minAmountOut: list[str] | None = Field(
+    #     None,
+    #     description="(Optional) Minimum amount out in wei. If specified, slippage should not be specified.",
+    # )
+    # slippage: str | None = Field(
+    #     None,
+    #     description="(Optional) Slippage in basis points (1/10000). If specified, minAmountOut should not be specified.",
+    # )
+    # fee: list[str] | None = Field(
+    #     None,
+    #     description="(Optional) Fee in basis points (1/10000) for each amountIn value.",
+    # )
+    # feeReceiver: str | None = Field(
+    #     None,
+    #     description="(Optional) Ethereum address that will receive the collected fee if fee was provided.",
+    # )
+    # disableRFQs: bool | None = Field(
+    #     None, description="(Optional) Exclude RFQ sources from routes."
+    # )
+    # ignoreAggregators: list[str] | None = Field(
+    #     None, description="(Optional) List of swap aggregators to ignore."
+    # )
+    # ignoreStandards: list[str] | None = Field(
+    #     None, description="(Optional) List of standards to ignore."
+    # )
+    # variableEstimates: dict | None = Field(
+    #     None, description="Variable estimates for the route."
+    # )
+
+
+class Route(BaseModel):
+    tokenIn: list[str] | None = Field(
+        None,
+        description="Ethereum address of the token to swap or enter into a position from.",
+    )
+    tokenOut: list[str] | None = Field(
+        None,
+        description="Ethereum address of the token to swap or enter into a position to.",
+    )
+    protocol: str | None = Field(None, description="Protocol used for finding route.")
+    action: str | None = Field(
+        None, description="Action has been done for route (e.g. swap)."
+    )
+    # internalRoutes: list[str] | None = Field(
+    #     None, description="Internal routes needed for the route."
+    # )
+
+
+class EnsoRouteShortcutOutput(BaseModel):
+    """
+    Output model for broadcasting a transaction.
+    """
+
+    network: str = Field(
+        "The network name of the transaction.",
+    )
+    amountOut: str | dict | None = Field(
+        None,
+        description="The final calculated amountOut as an object. you should multiply its value by tokenOut decimals.",
+    )
+    priceImpact: float | None = Field(
+        None,
+        description="Price impact in basis points, it is null if USD price is not found.",
+    )
+    txHash: str | None = Field(
+        None, description="The transaction hash of the broadcasted transaction."
+    )
+    # gas: str | None = Field(
+    #     None,
+    #     description="Estimated gas amount for the transaction.",
+    # )
+    # feeAmount: list[str] | None = Field(
+    #     None,
+    #     description="An array of the fee amounts collected for each tokenIn.",
+    # )
+    # createdAt: int | None = Field(
+    #     None, description="Block number the transaction was created on."
+    # )
+    # route: list[Route] | None = Field(
+    #     None, description="Route that the shortcut will use."
+    # )
+
+    # def __str__(self):
+    #     """
+    #     Returns the summary attribute as a string.
+    #     """
+    #     return f"network:{self.network}, amount out: {self.amountOut}, price impact: {self.priceImpact}, tx hash: {self.txHash}"
+
+
+class EnsoRouteShortcut(EnsoBaseTool):
+    """
+    This tool finds the optimal execution route path for swap or deposit across a multitude of DeFi protocols such as liquidity pools,
+    lending platforms, automated market makers, yield optimizers, and more. This allows for maximized capital efficiency
+    and yield optimization, taking into account return rates, gas costs, and slippage.
+
+    Important: the amountOut should be divided by tokenOut decimals before returning the result.
+
+    This tool is able to broadcast the transaction to the network if the user explicitly requests it. otherwise,
+    broadcast_requested is always false.
+
+    Deposit means to supply the underlying token to its parent token. (e.g. deposit USDC to receive aBasUSDC).
+
+    Attributes:
+        name (str): Name of the tool, specifically "enso_route_shortcut".
+        description (str): Comprehensive description of the tool's purpose and functionality.
+        args_schema (Type[BaseModel]): Schema for input arguments, specifying expected parameters.
+    """
+
+    name: str = "enso_route_shortcut"
+    description: str = "This tool is used specifically for broadcasting a route transaction calldata to the network. It should only be used when the user explicitly requests to broadcast a route transaction with routeId."
+    args_schema: Type[BaseModel] = EnsoRouteShortcutInput
+
+    async def _arun(
+        self,
+        amountIn: list[int],
+        tokenIn: list[str],
+        tokenOut: list[str],
+        config: RunnableConfig,
+        chainId: int = default_chain_id,
+        broadcast_requested: bool = False,
+        **kwargs,
+    ) -> EnsoRouteShortcutOutput:
+        """
+        Run the tool to get swap route information.
+
+        Args:
+            amountIn (list[int]): Amount of tokenIn to swap in wei, you should multiply user's requested value by token decimals.
+            tokenIn (list[str]): Ethereum address of the token to swap or enter into a position from (For ETH, use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).
+            tokenOut (list[str]): Ethereum address of the token to swap or enter into a position to (For ETH, use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).
+            chainId (int): The chain id of the network to be used for swap, deposit and routing.
+            broadcast_requested (bool): User should ask for broadcasting the transaction explicitly, otherwise it is always false.
+
+        Returns:
+            EnsoRouteShortcutOutput: The response containing route shortcut information.
+        """
+
+        context: SkillContext = self.context_from_config(config)
+        agent_id = context.agent.id
+        api_token = self.get_api_token(context)
+        chain_provider = self.get_chain_provider(context)
+        wallet = await self.get_wallet(context)
+
+        async with httpx.AsyncClient() as client:
+            try:
+                network_name = None
+                networks = await self.skill_store.get_agent_skill_data(
+                    agent_id, "enso_get_networks", "networks"
+                )
+
+                if networks:
+                    network_name = (
+                        networks.get(str(chainId)).get("name")
+                        if networks.get(str(chainId))
+                        else None
+                    )
+                if network_name is None:
+                    networks = await EnsoGetNetworks(
+                        skill_store=self.skill_store,
+                    ).arun(config)
+
+                    for network in networks.res:
+                        if network.id == chainId:
+                            network_name = network.name
+
+                if not network_name:
+                    raise ToolException(
+                        f"network name not found for chainId: {chainId}"
+                    )
+
+                headers = {
+                    "accept": "application/json",
+                    "Authorization": f"Bearer {api_token}",
+                }
+
+                token_decimals = await self.skill_store.get_agent_skill_data(
+                    agent_id,
+                    "enso_get_tokens",
+                    "decimals",
+                )
+
+                if not token_decimals:
+                    raise ToolException(
+                        "there is not enough information, enso_get_tokens should be called for data, at first."
+                    )
+
+                if not token_decimals.get(tokenOut[0]):
+                    raise ToolException(
+                        f"token decimals information for token {tokenOut[0]} not found"
+                    )
+
+                if not token_decimals.get(tokenIn[0]):
+                    raise ToolException(
+                        f"token decimals information for token {tokenIn[0]} not found"
+                    )
+
+                url = f"{base_url}/api/v1/shortcuts/route"
+
+                # Prepare query parameters
+                params = EnsoRouteShortcutInput(
+                    chainId=chainId,
+                    amountIn=amountIn,
+                    tokenIn=tokenIn,
+                    tokenOut=tokenOut,
+                ).model_dump(exclude_none=True)
+
+                params["fromAddress"] = wallet.addresses[0].address_id
+
+                response = await client.get(url, headers=headers, params=params)
+                response.raise_for_status()  # Raise HTTPError for non-2xx responses
+                json_dict = response.json()
+
+                res = EnsoRouteShortcutOutput(**json_dict)
+                res.network = network_name
+
+                res.amountOut = str(
+                    float(res.amountOut) / 10 ** token_decimals[tokenOut[0]]
+                )
+
+                if broadcast_requested:
+                    rpc_url = chain_provider.get_chain_config_by_id(chainId).rpc_url
+                    contract = EvmContractWrapper(
+                        rpc_url, ABI_ROUTE, json_dict.get("tx")
+                    )
+
+                    fn, fn_args = contract.fn_and_args
+
+                    fn_args["amountIn"] = str(fn_args["amountIn"])
+
+                    invocation = wallet.invoke_contract(
+                        contract_address=contract.dst_addr,
+                        method=fn.fn_name,
+                        abi=ABI_ROUTE,
+                        args=fn_args,
+                    ).wait()
+
+                    res.txHash = invocation.transaction.transaction_hash
+
+                return res
+
+            except httpx.RequestError as req_err:
+                raise ToolException(
+                    f"request error from Enso API: {req_err}"
+                ) from req_err
+            except httpx.HTTPStatusError as http_err:
+                raise ToolException(
+                    f"http error from Enso API: {http_err}"
+                ) from http_err
+            except Exception as e:
+                raise ToolException(f"error from Enso API: {e}") from e

intentkit/skills/enso/schema.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Enso Finance",
+  "description": "Integration with Enso Finance API providing DeFi trading and portfolio management capabilities across multiple blockchain networks",
+  "x-icon": "https://ai.service.crestal.dev/skills/enso/enso.jpg",
+  "x-tags": [
+    "Blockchain"
+  ],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "title": "Enabled",
+      "description": "Whether this skill is enabled",
+      "default": false
+    },
+    "states": {
+      "type": "object",
+      "properties": {
+        "get_networks": {
+          "type": "string",
+          "title": "Get Networks",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Retrieve networks supported by the Enso API",
+          "default": "disabled"
+        },
+        "get_tokens": {
+          "type": "string",
+          "title": "Get Tokens",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Enso Finance Token Information Tool: Retrieves detailed token information from the Enso Finance API, including APY, symbol, address, protocol slug, token type, and underlying tokens.",
+          "default": "disabled"
+        },
+        "get_prices": {
+          "type": "string",
+          "title": "Get Prices",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Retrieve the price of a token by chain ID and contract address",
+          "default": "disabled"
+        },
+        "get_wallet_approvals": {
+          "type": "string",
+          "title": "Get Wallet Approvals",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Retrieve token spend approvals for a wallet on a specified blockchain network.",
+          "default": "disabled"
+        },
+        "get_wallet_balances": {
+          "type": "string",
+          "title": "Get Wallet Balances",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Retrieve token balances of a wallet on a specified blockchain network.",
+          "default": "disabled"
+        },
+        "wallet_approve": {
+          "type": "string",
+          "title": "Wallet Approve",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "This tool is used specifically for broadcasting a ERC20 token spending approval transaction to the network. It should only be used when the user explicitly requests to broadcast an approval transaction with a specific amount for a certain token.",
+          "default": "disabled"
+        },
+        "route_shortcut": {
+          "type": "string",
+          "title": "Route Shortcut",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "This tool is used specifically for broadcasting a route transaction calldata to the network. It should only be used when the user explicitly requests to broadcast a route transaction with routeId.",
+          "default": "disabled"
+        },
+        "get_best_yield": {
+          "type": "string",
+          "title": "Get Best Yield",
+          "enum": [
+            "disabled",
+            "public",
+            "private"
+          ],
+          "x-enum-title": [
+            "Disabled",
+            "Agent Owner + All Users",
+            "Agent Owner Only"
+          ],
+          "description": "Find the best yield options for a specific token (default: USDC) across all protocols on a blockchain network (default: Base). Results are sorted by APY in descending order.",
+          "default": "disabled"
+        }
+      },
+      "description": "States for each Enso skill (disabled, public, or private)"
+    },
+    "main_tokens": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of main tokens to use",
+      "default": [
+        "ETH",
+        "UDSC",
+        "USDT"
+      ]
+    },
+    "api_key_provider": {
+      "type": "string",
+      "title": "API Key Provider",
+      "description": "Provider of the API key",
+      "enum": [
+        "platform",
+        "agent_owner"
+      ],
+      "x-enum-title": [
+        "Nation Hosted",
+        "Owner Provided"
+      ],
+      "default": "platform"
+    }
+  },
+  "required": [
+    "states",
+    "main_tokens",
+    "enabled"
+  ],
+  "if": {
+    "properties": {
+      "api_key_provider": {
+        "const": "agent_owner"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "api_token": {
+        "type": "string",
+        "title": "API Token",
+        "description": "Enso API token for authentication"
+      }
+    },
+    "if": {
+      "properties": {
+        "enabled": {
+          "const": true
+        }
+      }
+    },
+    "then": {
+      "required": [
+        "api_token"
+      ]
+    }
+  },
+  "additionalProperties": true
+}