ADD_COLLATERAL

Instructions

Implementation Reference

• src/tools/add-collateral.ts:28-79 (handler)

  The main handler/execute function for the ADD_COLLATERAL tool. It validates inputs, creates a WalletService and AddCollateralService, calls the service's execute method, and returns a formatted success/error message.

  export const addCollateralTool: Tool<
  	FastMCPSessionAuth,
  	typeof addCollateralToolParams
  > = {
  	name: "ADD_COLLATERAL",
  	description: "Add collateral to your BAMM position",
  	parameters: addCollateralToolParams,
  	execute: async (params, _context) => {
  		try {
  			if (!params.collateralToken && !params.collateralTokenSymbol) {
  				return "Error: Either collateralToken address or collateralTokenSymbol is required";
  			}
  
  			const privateKey = process.env.WALLET_PRIVATE_KEY;
  			if (!privateKey) {
  				return "Error: WALLET_PRIVATE_KEY environment variable is not set. Please set it with your wallet's private key (without 0x prefix).";
  			}
  
  			const walletService = new WalletService(privateKey);
  			const addCollateralService = new AddCollateralService(walletService);
  
  			const result = await addCollateralService.execute({
  				bammAddress: params.bammAddress as Address,
  				collateralToken: params.collateralToken as Address | undefined,
  				collateralTokenSymbol: params.collateralTokenSymbol,
  				amount: params.amount,
  			});
  
  			return dedent`
          ✅ Collateral Addition Successful
  
          🌐 BAMM Address: ${params.bammAddress}
          🔒 Amount: ${formatNumber(Number(params.amount))}
          💰 Token: ${params.collateralTokenSymbol ?? params.collateralToken}
          🔗 Transaction: ${result.txHash}
  
          Collateral has been added to your BAMM position.
        `;
  		} catch (error) {
  			if (error instanceof Error) {
  				return dedent`
            ❌ Collateral Addition Failed
  
            Error: ${error.message}
  
            Please verify your inputs and try again.
          `;
  			}
  			return "An unknown error occurred while adding collateral";
  		}
  	},
  };

• src/tools/add-collateral.ts:9-24 (schema)

  Zod schema for ADD_COLLATERAL tool parameters: bammAddress (regex 0x address), amount (string), collateralToken (optional regex 0x address), collateralTokenSymbol (optional string).

  const addCollateralToolParams = z.object({
  	bammAddress: z
  		.string()
  		.regex(/^0x[a-fA-F0-9]{40}$/)
  		.describe("The address of the BAMM contract"),
  	amount: z.string().min(1).describe("The amount of collateral to add"),
  	collateralToken: z
  		.string()
  		.regex(/^0x[a-fA-F0-9]{40}$/)
  		.optional()
  		.describe("The address of the collateral token"),
  	collateralTokenSymbol: z
  		.string()
  		.optional()
  		.describe("The symbol of the collateral token (e.g., 'IQT')"),
  });

• src/index.ts:19-19 (registration)

  Registration of the addCollateralTool on the FastMCP server instance via server.addTool(addCollateralTool).

  server.addTool(addCollateralTool);

• src/services/add-collateral.ts:1-98 (helper)

  The AddCollateralService class which contains the core business logic: resolves token address from symbol, validates token against BAMM, checks balance, ensures token approval, then calls executeActions on the BAMM contract.

  import type { Address } from "viem";
  import { BAMM_ABI } from "../lib/bamm.abi.js";
  import { getTokenAddressFromSymbol } from "../lib/symbol-to-address.js";
  import { checkTokenBalance, ensureTokenApproval } from "../lib/token-utils.js";
  import { validateTokenAgainstBAMM } from "../lib/token-validator.js";
  import type { WalletService } from "./wallet.js";
  
  export interface AddCollateralParams {
  	bammAddress: Address;
  	collateralToken?: Address;
  	collateralTokenSymbol?: string;
  	amount: string;
  }
  
  export class AddCollateralService {
  	constructor(private walletService: WalletService) {}
  
  	async execute(params: AddCollateralParams): Promise<{ txHash: string }> {
  		let { bammAddress, collateralToken, collateralTokenSymbol, amount } =
  			params;
  		if (!collateralToken && !collateralTokenSymbol) {
  			throw new Error(
  				"Either collateralToken or collateralTokenSymbol is required",
  			);
  		}
  		const publicClient = this.walletService.getPublicClient();
  		const walletClient = this.walletService.getWalletClient();
  
  		if (!walletClient || !walletClient.account) {
  			throw new Error("Wallet client is not initialized");
  		}
  
  		const userAddress = walletClient.account.address;
  		const amountInWei = BigInt(Number(amount) * 1e18);
  		try {
  			if (collateralTokenSymbol) {
  				collateralToken = await getTokenAddressFromSymbol(
  					collateralTokenSymbol,
  				);
  			}
  
  			if (!collateralToken) {
  				throw new Error("Could not resolve collateral token address");
  			}
  
  			const tokenValidation = await validateTokenAgainstBAMM(
  				bammAddress,
  				collateralToken,
  				publicClient,
  			);
  
  			await checkTokenBalance(
  				collateralToken,
  				userAddress,
  				amountInWei,
  				publicClient,
  			);
  			await ensureTokenApproval(
  				collateralToken,
  				bammAddress,
  				amountInWei,
  				publicClient,
  				walletClient,
  			);
  
  			const currentTime = Math.floor(Date.now() / 1000);
  			const deadline = BigInt(currentTime + 300);
  
  			const action = {
  				token0Amount: tokenValidation.isToken0 ? amountInWei : 0n,
  				token1Amount: tokenValidation.isToken1 ? amountInWei : 0n,
  				rent: 0n,
  				to: userAddress,
  				token0AmountMin: 0n,
  				token1AmountMin: 0n,
  				closePosition: false,
  				approveMax: false,
  				v: 0,
  				r: "0x0000000000000000000000000000000000000000000000000000000000000000" as `0x${string}`,
  				s: "0x0000000000000000000000000000000000000000000000000000000000000000" as `0x${string}`,
  				deadline,
  			};
  			const { request: executeRequest } = await publicClient.simulateContract({
  				address: bammAddress,
  				abi: BAMM_ABI,
  				functionName: "executeActions",
  				args: [action],
  				account: walletClient.account,
  			});
  			const txHash = await walletClient.writeContract(executeRequest);
  			await publicClient.waitForTransactionReceipt({ hash: txHash });
  			return { txHash };
  		} catch (error) {
  			console.error("Error in add collateral service:", error);
  			throw Error("Error in add collateral service");
  		}
  	}
  }

• src/lib/templates.ts:93-101 (helper)

  The ADD_COLLATERAL_TEMPLATE, a prompt template used for AI extraction of collateral addition parameters from user messages.

  export const ADD_COLLATERAL_TEMPLATE = TOKEN_OPERATION_TEMPLATE.replace(
  	/{{operation}}/g,
  	"collateral addition",
  ).replace(/{{tokenType}}/g, "collateralToken");
  
  export const REMOVE_COLLATERAL_TEMPLATE = TOKEN_OPERATION_TEMPLATE.replace(
  	/{{operation}}/g,
  	"collateral withdrawal",
  ).replace(/{{tokenType}}/g, "collateralToken");