saucer-swap-plugin 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,16 @@ A plugin for the Hedera Agent Kit that enables SaucerSwap V2 DeFi operations on
 npm install saucer-swap-plugin
 ```
 
+## Prerequisites
+
+Before using this plugin, you need to set up the following environment variables:
+
+- `SAUCERSWAP_API_KEY` - API key for SaucerSwap REST API access
+- `ACCOUNT_ID` - Your Hedera account ID
+- `PRIVATE_KEY` - Your Hedera account private key (ECDSA format)
+
+See [SETUP.md](./SETUP.md) for detailed setup instructions.
+
 ## Usage
 
 ### With Hedera Agent Kit

package/dist/config.js

@@ -1,4 +1,4 @@
-import { LedgerId } from "@hashgraph/sdk";
+import { LedgerId } from "@hiero-ledger/sdk";
 export const saucerSwapConfig = {
     networks: {
         [LedgerId.MAINNET.toString()]: {

package/dist/errors.js

@@ -47,3 +47,13 @@ export class ConfigurationError extends SaucerSwapError {
         Object.setPrototypeOf(this, ConfigurationError.prototype);
     }
 }
+export class TokenNotAssociatedError extends SaucerSwapError {
+    constructor(accountId, tokenId, signerAccountId) {
+        const signerHint = signerAccountId
+            ? ` Cannot auto-associate because the recipient differs from the signer (${signerAccountId}). Have the recipient associate the token first.`
+            : ' Have the recipient associate the token first.';
+        super(`Recipient ${accountId} does not have token ${tokenId} associated.${signerHint}`, 'TOKEN_NOT_ASSOCIATED');
+        this.name = 'TokenNotAssociatedError';
+        Object.setPrototypeOf(this, TokenNotAssociatedError.prototype);
+    }
+}

package/dist/saucer-swap-v2-parameter-normaliser.js

@@ -1,4 +1,4 @@
-import { AccountResolver } from "hedera-agent-kit";
+import { AccountResolver } from "@hashgraph/hedera-agent-kit";
 import { getSwapQuoteV2Parameters, swapV2Parameters } from './saucer-swap.zod';
 import { ethers } from "ethers";
 import z from 'zod';

package/dist/service/saucer-swap-rest-pools-service.js

@@ -1,4 +1,4 @@
-import { LedgerId } from "@hashgraph/sdk";
+import { LedgerId } from "@hiero-ledger/sdk";
 const SAUCERSWAP_REST_BASE_URLS = {
     MAINNET: "https://api.saucerswap.finance",
     TESTNET: "https://test-api.saucerswap.finance",

package/dist/service/saucer-swap-v2-config-service.js

@@ -1,6 +1,6 @@
 // write a config service to get the config from the config file
 import { saucerSwapConfig } from "../config";
-import { ContractId, TokenId } from "@hashgraph/sdk";
+import { ContractId, TokenId } from "@hiero-ledger/sdk";
 export class SaucerSwapV2ConfigService {
     saucerSwapConfig;
     ledgerId;

package/dist/tools/get-swap-quote-v2.js

@@ -1,4 +1,4 @@
-import { PromptGenerator, getMirrornodeService } from "hedera-agent-kit";
+import { BaseTool, PromptGenerator, getMirrornodeService, untypedQueryOutputParser, } from "@hashgraph/hedera-agent-kit";
 import { getSwapQuoteV2Parameters } from "../saucer-swap.zod";
 import { SaucerSwapV2QueryServiceImpl } from "../service/saucer-swap-v2-query-service-impl";
 import SaucerSwapV2ParameterNormaliser from "../saucer-swap-v2-parameter-normaliser";
@@ -9,36 +9,54 @@ const getSwapQuoteV2Prompt = (context = {}) => {
     const contextSnippet = PromptGenerator.getContextSnippet(context);
     const usageInstructions = PromptGenerator.getParameterUsageInstructions();
     return `
-  ${contextSnippet}
-  
-  This tool will get a quote for swapping from tokenIn to tokenOut. Provide either optional.amountIn (exact-in) or optional.amountOut (exact-out).
-  
-  Parameters:
-  - tokenIn (str, required): The input token address.
-  - tokenOut (str, required): The output token address.
-  - amountIn (number, required): The amount of input tokens to swap.
-  ${usageInstructions}
-  
-  Example: "Get quote for swapping 1000000000000000000 amountIn from 0x1234567890abcdef1234567890abcdef12345678 tokenIn to 0xabcdef1234567890abcdef1234567890abcdef12345678 tokenOut"
-  `;
+${contextSnippet}
+
+This tool will get a quote for swapping from tokenIn to tokenOut. Provide either optional.amountIn (exact-in) or optional.amountOut (exact-out).
+
+Parameters:
+- tokenIn (str, required): The input token address.
+- tokenOut (str, required): The output token address.
+- amountIn (number, required): The amount of input tokens to swap.
+${usageInstructions}
+
+Example: "Get quote for swapping 1000000000000000000 amountIn from 0x1234567890abcdef1234567890abcdef12345678 tokenIn to 0xabcdef1234567890abcdef1234567890abcdef12345678 tokenOut"
+`;
 };
-const postProcess = (quote, tokenAmountInBaseUnit, params) => {
-    return `Swapping ${tokenAmountInBaseUnit} token: ${params.tokenIn} to token: ${params.tokenOut} will result in ${quote} token: ${params.tokenOut}, the rate used is ${quote / tokenAmountInBaseUnit}`;
-};
-const getSwapQuoteV2 = async (client, context, params) => {
-    const mirrorNode = getMirrornodeService(context.mirrornodeService, client.ledgerId);
-    const saucerSwapV2ConfigService = new SaucerSwapV2ConfigService(client.ledgerId);
-    const saucerSwapV2QueryService = new SaucerSwapV2QueryServiceImpl(client.ledgerId, mirrorNode, saucerSwapV2ConfigService);
-    const saucerSwapApiService = new SaucerSwapApiServiceImpl(client.ledgerId, saucerSwapV2ConfigService.getSaucerSwapApiKey());
-    try {
-        const normalisedParams = await SaucerSwapV2ParameterNormaliser.normaliseGetSwapQuoteV2Params(params, context, saucerSwapApiService);
-        const quote = await saucerSwapV2QueryService.getSwapQuote(normalisedParams.tokenIn, normalisedParams.tokenOut, normalisedParams.amountIn, normalisedParams.poolFeesInHexFormat.toLowerCase());
+const postProcess = (quote, tokenAmountInBaseUnit, params) => `Swapping ${tokenAmountInBaseUnit} token: ${params.tokenIn} to token: ${params.tokenOut} will result in ${quote} token: ${params.tokenOut}, the rate used is ${quote / tokenAmountInBaseUnit}`;
+export const GET_SWAP_QUOTE_V2_TOOL = "get_swap_quote_v2_tool";
+export class GetSwapQuoteV2Tool extends BaseTool {
+    method = GET_SWAP_QUOTE_V2_TOOL;
+    name = "Get Quote (SaucerSwap V2)";
+    description;
+    parameters;
+    outputParser = untypedQueryOutputParser;
+    constructor(context) {
+        super();
+        this.description = getSwapQuoteV2Prompt(context);
+        this.parameters = getSwapQuoteV2Parameters();
+    }
+    async normalizeParams(params, context, client) {
+        const config = new SaucerSwapV2ConfigService(client.ledgerId);
+        const api = new SaucerSwapApiServiceImpl(client.ledgerId, config.getSaucerSwapApiKey());
+        return await SaucerSwapV2ParameterNormaliser.normaliseGetSwapQuoteV2Params(params, context, api);
+    }
+    async coreAction(normalisedParams, context, client) {
+        const mirrorNode = getMirrornodeService(context.mirrornodeService, client.ledgerId);
+        const config = new SaucerSwapV2ConfigService(client.ledgerId);
+        const queryService = new SaucerSwapV2QueryServiceImpl(client.ledgerId, mirrorNode, config);
+        const quote = await queryService.getSwapQuote(normalisedParams.tokenIn, normalisedParams.tokenOut, normalisedParams.amountIn, normalisedParams.poolFeesInHexFormat.toLowerCase());
         return {
             raw: { quote },
             humanMessage: postProcess(quote, normalisedParams.amountIn, normalisedParams),
         };
     }
-    catch (error) {
+    async shouldSecondaryAction(_coreActionResult, _context) {
+        return false;
+    }
+    async secondaryAction(_request, _client, _context) {
+        return null;
+    }
+    async handleError(error, _context) {
         const desc = 'Failed to get quote';
         let message;
         if (error instanceof SaucerSwapError) {
@@ -53,20 +71,6 @@ const getSwapQuoteV2 = async (client, context, params) => {
         console.error('[get_quote_tool]', message, error);
         return { raw: { error: message }, humanMessage: message };
     }
-};
-export const GET_SWAP_QUOTE_V2_TOOL = "get_swap_quote_v2_tool";
-const tool = (context) => ({
-    method: GET_SWAP_QUOTE_V2_TOOL,
-    name: "Get Quote (SaucerSwap V2)",
-    description: getSwapQuoteV2Prompt(context),
-    parameters: getSwapQuoteV2Parameters(),
-    execute: getSwapQuoteV2,
-    outputParser: (rawOutput) => {
-        const json = JSON.parse(rawOutput);
-        return {
-            raw: json,
-            humanMessage: json.quote,
-        };
-    },
-});
+}
+const tool = (context) => new GetSwapQuoteV2Tool(context);
 export default tool;

package/dist/tools/swap-v2.js

@@ -1,40 +1,108 @@
 import SaucerSwapV2ParameterNormaliser from "../saucer-swap-v2-parameter-normaliser";
 import { swapV2Parameters } from "../saucer-swap.zod";
-import { getMirrornodeService, handleTransaction, HederaBuilder, PromptGenerator } from "hedera-agent-kit";
-import { Status } from "@hashgraph/sdk";
+import { AccountResolver, AgentMode, BaseTool, getMirrornodeService, handleTransaction, HederaBuilder, HederaParameterNormaliser, PromptGenerator, transactionToolOutputParser, } from "@hashgraph/hedera-agent-kit";
+import { Status } from "@hiero-ledger/sdk";
 import { SaucerSwapV2ConfigService } from "../service/saucer-swap-v2-config-service";
 import { SaucerSwapApiServiceImpl } from "../service/saucer-swap-rest-pools-service";
-import { SaucerSwapError } from "../errors";
-const swapV2Prompt = (context = {}) => {
-    return `
-    ${PromptGenerator.getContextSnippet(context)}
+import { SaucerSwapError, TokenNotAssociatedError } from "../errors";
+import { getHederaTokenAddress, getHederaTokenEVMAddress, getTokenDecimals, toBaseUnit } from "../utils";
+import { isTokenAssociated } from "../utils/token-association";
+import { ensureTokenAllowance } from "../utils/token-allowance";
+import { PoolFinderService } from "../service/pool-finder-service";
+const swapV2Prompt = (context = {}) => `
+${PromptGenerator.getContextSnippet(context)}
 
-    This tool will swap tokens using the SaucerSwap V2 protocol.
+This tool will swap tokens using the SaucerSwap V2 protocol. If the recipient
+has not associated the output token, the tool will associate it first (only
+works when the recipient equals the signing account; otherwise the call fails
+with a clear error and the recipient must associate the token themselves).
+When tokenIn is not native HBAR / WHBAR, the tool also grants an
+AccountAllowance to the SwapRouter contract for amountIn before swapping.
 
-    Parameters:
-    - tokenIn (str, required): The input token address
-    - tokenOut (str, required): The output token address
-    - amountIn (number, required): The amount of input tokens to swap
-    - recipientAddress (str, required): The address to receive the output tokens
-    `;
+Parameters:
+- tokenIn (str, required): The input token address
+- tokenOut (str, required): The output token address
+- amountIn (number, required): The amount of input tokens to swap
+- recipientAddress (str, required): The address to receive the output tokens
+`;
+const postProcess = (response) => `Swap successful.\nTransaction ID: ${response.transactionId}`;
+const resolveSignerAccountId = (context, client) => {
+    if (context.mode === AgentMode.RETURN_BYTES) {
+        return context.accountId;
+    }
+    return client.operatorAccountId?.toString();
 };
-const postProcess = (response) => {
-    return `
-    Swap successful.
-    Transaction ID: ${response.transactionId}
-    `;
+const ensureTokenAssociated = async (recipientAccountId, tokenOutHederaId, context, client, mirrorNode) => {
+    if (await isTokenAssociated(recipientAccountId, tokenOutHederaId, mirrorNode))
+        return;
+    const signer = resolveSignerAccountId(context, client);
+    if (!signer || signer !== recipientAccountId) {
+        throw new TokenNotAssociatedError(recipientAccountId, tokenOutHederaId, signer);
+    }
+    const associateParams = HederaParameterNormaliser.normaliseAssociateTokenParams({ accountId: recipientAccountId, tokenIds: [tokenOutHederaId] }, context, client);
+    const associateTx = HederaBuilder.associateToken(associateParams);
+    await handleTransaction(associateTx, client, context, () => `Associated token ${tokenOutHederaId} with account ${recipientAccountId}`);
 };
-const swapV2 = async (client, context, params) => {
-    try {
+export const SWAP_V2_TOOL = 'swap_v2_tool';
+export class SwapV2Tool extends BaseTool {
+    method = SWAP_V2_TOOL;
+    name = 'Swap V2';
+    description;
+    parameters;
+    outputParser = transactionToolOutputParser;
+    constructor(context) {
+        super();
+        this.description = swapV2Prompt(context);
+        this.parameters = swapV2Parameters();
+    }
+    async normalizeParams(params, context, client) {
+        const mirrorNode = getMirrornodeService(context.mirrornodeService, client.ledgerId);
+        const config = new SaucerSwapV2ConfigService(client.ledgerId);
+        const api = new SaucerSwapApiServiceImpl(client.ledgerId, config.getSaucerSwapApiKey());
+        const recipientAccountId = AccountResolver.resolveAccount(params.recipientAddress, context, client);
+        const tokenInHederaId = getHederaTokenAddress(params.tokenIn);
+        const tokenOutHederaId = getHederaTokenAddress(params.tokenOut);
+        const tokenInEvm = getHederaTokenEVMAddress(params.tokenIn);
+        const wrappedHBarEvm = config.getWrappedHBarEvmAddress();
+        const isInputWrappedHBAR = tokenInEvm.toLowerCase() === wrappedHBarEvm.toLowerCase();
+        let amountInBase;
+        let spenderAccountId;
+        if (!isInputWrappedHBAR) {
+            const pool = await PoolFinderService.findPoolForTokens(tokenInHederaId, tokenOutHederaId, api);
+            const decimals = getTokenDecimals(pool, tokenInHederaId);
+            amountInBase = toBaseUnit(params.amountIn, decimals).toNumber();
+            spenderAccountId = config.getSwapRouterContractId().toString();
+        }
+        const swapParams = await SaucerSwapV2ParameterNormaliser.normaliseSwapV2Params(params, context, config, api, mirrorNode, client);
+        return {
+            swapParams,
+            prep: {
+                recipientAccountId,
+                tokenInHederaId,
+                tokenOutHederaId,
+                amountInBase,
+                spenderAccountId,
+                isInputWrappedHBAR,
+            },
+        };
+    }
+    async coreAction(normalisedParams, context, client) {
         const mirrorNode = getMirrornodeService(context.mirrornodeService, client.ledgerId);
-        const saucerSwapV2ConfigService = new SaucerSwapV2ConfigService(client.ledgerId);
-        const saucerSwapApiService = new SaucerSwapApiServiceImpl(client.ledgerId, saucerSwapV2ConfigService.getSaucerSwapApiKey());
-        const normalisedParams = await SaucerSwapV2ParameterNormaliser.normaliseSwapV2Params(params, context, saucerSwapV2ConfigService, saucerSwapApiService, mirrorNode, client);
-        const modifiedParams = { ...normalisedParams, gas: normalisedParams.gas };
-        const tx = HederaBuilder.executeTransaction(modifiedParams);
-        return handleTransaction(tx, client, context, postProcess);
+        const { swapParams, prep } = normalisedParams;
+        await ensureTokenAssociated(prep.recipientAccountId, prep.tokenOutHederaId, context, client, mirrorNode);
+        if (!prep.isInputWrappedHBAR) {
+            const ownerAccountId = resolveSignerAccountId(context, client);
+            if (!ownerAccountId) {
+                throw new SaucerSwapError('Cannot resolve owner account for token allowance', 'OWNER_UNRESOLVED');
+            }
+            await ensureTokenAllowance(ownerAccountId, prep.spenderAccountId, prep.tokenInHederaId, prep.amountInBase, context, client, mirrorNode);
+        }
+        return HederaBuilder.executeTransaction(swapParams);
+    }
+    async secondaryAction(transaction, client, context) {
+        return await handleTransaction(transaction, client, context, postProcess);
     }
-    catch (error) {
+    async handleError(error, _context) {
         const desc = 'Failed to swap tokens';
         let message;
         if (error instanceof SaucerSwapError) {
@@ -55,25 +123,11 @@ const swapV2 = async (client, context, params) => {
                 transactionId: '',
                 topicId: null,
                 scheduleId: null,
-                error: message
+                error: message,
             },
-            humanMessage: message
+            humanMessage: message,
         };
     }
-};
-export const SWAP_V2_TOOL = 'swap_v2_tool';
-const tool = (context) => ({
-    method: SWAP_V2_TOOL,
-    name: 'Swap V2',
-    description: swapV2Prompt(context),
-    parameters: swapV2Parameters(),
-    execute: swapV2,
-    outputParser: (rawOutput) => {
-        const json = JSON.parse(rawOutput);
-        return {
-            raw: json,
-            humanMessage: json.transactionId,
-        };
-    },
-});
+}
+const tool = (context) => new SwapV2Tool(context);
 export default tool;

package/dist/utils/token-allowance.js

@@ -0,0 +1,23 @@
+import { HederaBuilder, HederaParameterNormaliser, handleTransaction, } from "@hashgraph/hedera-agent-kit";
+export async function hasSufficientAllowance(ownerAccountId, spenderAccountId, tokenId, amount, mirrorNode) {
+    try {
+        const { allowances } = await mirrorNode.getTokenAllowances(ownerAccountId, spenderAccountId);
+        const existing = allowances.find(a => a.token_id === tokenId);
+        return !!existing && existing.amount >= amount;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureTokenAllowance(ownerAccountId, spenderAccountId, tokenId, amount, context, client, mirrorNode) {
+    if (await hasSufficientAllowance(ownerAccountId, spenderAccountId, tokenId, amount, mirrorNode)) {
+        return;
+    }
+    const approveParams = await HederaParameterNormaliser.normaliseApproveTokenAllowance({
+        ownerAccountId,
+        spenderAccountId,
+        tokenApprovals: [{ tokenId, amount }],
+    }, context, client, mirrorNode);
+    const approveTx = HederaBuilder.approveTokenAllowance(approveParams);
+    await handleTransaction(approveTx, client, context, () => `Approved ${amount} of token ${tokenId} for spender ${spenderAccountId}`);
+}

package/dist/utils/token-association.js

@@ -0,0 +1,4 @@
+export async function isTokenAssociated(accountId, tokenId, mirrorNode) {
+    const balances = await mirrorNode.getAccountTokenBalances(accountId, tokenId);
+    return balances.tokens.some(t => t.token_id === tokenId);
+}

package/dist/utils.js

@@ -1,6 +1,6 @@
-import { TokenId } from "@hashgraph/sdk";
+import { TokenId } from "@hiero-ledger/sdk";
 import BigNumber from 'bignumber.js';
-import { AccountResolver } from "hedera-agent-kit";
+import { AccountResolver } from "@hashgraph/hedera-agent-kit";
 /**
  * Handles response formatting for both autonomous and manual modes
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saucer-swap-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "SaucerSwap plugin for Hedera Agent Kit",
   "main": "dist/index.js",
@@ -25,10 +25,13 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "hedera-agent-kit": "^3.5.2",
     "tsup": "^8.5.0",
     "zod": "^3.0.0"
   },
+  "peerDependencies": {
+    "@hashgraph/hedera-agent-kit": "^4.0.0",
+    "@hiero-ledger/sdk": "^2.82.0"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -41,5 +44,9 @@
   "files": [
     "dist/**/*",
     "README.md"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saucerswaplabs/hedera-agent-kit-saucer-swap-plugin"
+  }
 }

package/dist/service/type.js

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

package/dist/service/utils.js

@@ -1,19 +0,0 @@
-export function hexToUint8Array(hex) {
-    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
-    if (cleanHex.length % 2 !== 0) {
-        throw new Error('Invalid hex string length');
-    }
-    const array = new Uint8Array(cleanHex.length / 2);
-    for (let i = 0; i < array.length; i++) {
-        array[i] = parseInt(cleanHex.substr(i * 2, 2), 16);
-    }
-    return array;
-}
-export function buildEncodedPath(inputToken, hexFee, outputToken) {
-    const clean = (s) => s.startsWith('0x') ? s.slice(2) : s;
-    const pathParts = [];
-    pathParts.push(clean(inputToken));
-    pathParts.push(clean(hexFee));
-    pathParts.push(clean(outputToken));
-    return hexToUint8Array(pathParts.join(''));
-}

package/dist/utils/hedera-mirrornode-utils.js

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