ADD_COLLATERAL

Instructions

Implementation Reference

• src/tools/add-collateral.ts:35-78 (handler)

  The execute function of the ADD_COLLATERAL tool, which validates inputs, initializes services, calls the AddCollateralService, and returns formatted success or error messages.

  execute: async (params) => {
  	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 defining the input parameters for the ADD_COLLATERAL tool: bammAddress, amount, optional collateralToken or collateralTokenSymbol.

  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 in the FastMCP server instance.

  server.addTool(addCollateralTool);

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

  AddCollateralService class that handles the core logic: resolves token, validates, checks balance/approval, and executes the BAMM contract's executeActions for adding collateral.

  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");
  		}
  	}
  }