MarginZero
This document provides an overview of how the Ava Portfolio Manager AI Agent integrates with the MarginZero protocol, focusing on its capabilities for options trading and liquidity provision.
Overview
MarginZero is a decentralized options protocol that allows users to create, trade, and manage options positions on-chain. The protocol is built on liquidity provider tokens (LP tokens) from decentralized exchanges like Uniswap V3.
Ava integrates with MarginZero to provide users with the ability to:
View options data and prices
Create and manage options positions
Exercise options
Interact with LP tokens
Key Components
The MarginZero integration consists of the following key components:
MarginZeroProvider: A plugin that handles all interactions with the MarginZero smart contracts
Sonic Agent MarginZero Extensions: Methods in the Sonic Agent that utilize the MarginZero Provider
Smart Contract Interfaces: Type definitions and ABIs for interacting with MarginZero contracts
Architecture
┌────────────────┐ ┌─────────────────┐ ┌────────────────────┐
│ │ │ │ │ │
│ User Input ├────►│ Eliza Agent ├────►│ Task Manager │
│ │ │ │ │ │
└────────────────┘ └─────────────────┘ └──────────┬─────────┘
│
▼
┌────────────────┐ ┌─────────────────┐ ┌────────────────────┐
│ MarginZero │◄────┤ │◄────┤ │
│ Contracts │ │ Sonic Agent │ │ Event Bus │
│ │ │ │ │ │
└────────────────┘ └─────────────────┘ └────────────────────┘
│
▼
┌─────────────────┐
│ MarginZero │
│ Provider │
│ │
└─────────────────┘MarginZero Provider
The MarginZeroProvider is a TypeScript class that facilitates interactions with the MarginZero protocol's smart contracts. It provides methods for accessing information and executing transactions against the protocol.
Configuration
To use the MarginZero Provider, you need to configure it with the following parameters:
interface MarginZeroConfig {
chainId: number;
rpcUrl: string;
account?: {
address: string;
privateKey: string;
};
positionManagerAddress: string;
optionMarketAddress: string;
}Key Methods
The provider includes the following key methods:
Handler Operations
// Check if a handler is whitelisted
async isHandlerWhitelisted(handlerAddress: string): Promise<boolean>
// Mint a new position
async mintPosition(
handlerAddress: string,
tokenId: number,
recipient: string
): Promise<string>
// Burn a position
async burnPosition(
handlerAddress: string,
tokenId: number,
recipient: string
): Promise<string>
// Use a position
async usePosition(
handlerAddress: string,
tokenId: number
): Promise<string>
// Unuse a position
async unusePosition(
handlerAddress: string,
tokenId: number
): Promise<string>
// Donate to a position
async donateToPosition(
handlerAddress: string,
tokenId: number,
amount0: string,
amount1: string
): Promise<string>Option Operations
// Get option data
async getOptionData(optionTokenId: number): Promise<OptionData>
// Get option price
async getOptionPrice(
isCall: boolean,
isPut: boolean,
spotPrice: string,
strikePrice: string,
timeToMaturity: number,
volatility: string
): Promise<string>
// Buy an option
async buyOption(params: BuyOptionParams): Promise<string>
// Exercise an option
async exerciseOption(
optionTokenId: number
): Promise<string>Sonic Agent Integration
The Sonic Agent has been extended to include methods that interact with the MarginZero Provider. These methods include:
// Check if a handler is whitelisted
async isHandlerWhitelisted(handlerAddress: string): Promise<boolean>
// Mint a new position
async mintPosition(
handlerAddress: string,
tokenId: number,
recipient: string
): Promise<string>
// Burn a position
async burnPosition(
handlerAddress: string,
tokenId: number,
recipient: string
): Promise<string>
// ... additional methods for all MarginZero operationsUsage Examples
Checking Handler Status
const handlerAddress = "0x1234...";
const isWhitelisted = await sonicAgent.isHandlerWhitelisted(handlerAddress);
console.log(`Handler ${handlerAddress} is whitelisted: ${isWhitelisted}`);Buying an Option
const optionParams = {
isCall: true,
isPut: false,
strikePrice: "2000000000", // in wei format
maturity: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 1 week from now
priceTolerance: "50", // 5%
maxCost: "100000000000000000", // 0.1 ETH in wei
handler: "0xabcd...",
underlying: "0xefgh..."
};
const txHash = await sonicAgent.buyOption(optionParams);
console.log(`Option purchased, transaction: ${txHash}`);Exercising an Option
const optionTokenId = 123;
const txHash = await sonicAgent.exerciseOption(optionTokenId);
console.log(`Option exercised, transaction: ${txHash}`);Error Handling
The MarginZero Provider and Sonic Agent extensions include robust error handling for common issues:
try {
await sonicAgent.buyOption(optionParams);
} catch (error) {
if (error.message.includes("insufficient funds")) {
console.error("Not enough funds to buy this option");
} else if (error.message.includes("price slippage")) {
console.error("Option price has changed beyond the tolerance level");
} else {
console.error("Unknown error:", error);
}
}MarginZero Contract ABIs
The integration includes TypeScript definitions for the MarginZero contract ABIs:
Position Manager ABI
export const POSITION_MANAGER_ABI = [
// Core functions
"function mintPosition(address handler, uint256 tokenId, address recipient) external returns (bytes memory result)",
"function burnPosition(address handler, uint256 tokenId, address recipient) external returns (bytes memory result)",
"function usePosition(address handler, uint256 tokenId) external returns (bytes memory result)",
"function unusePosition(address handler, uint256 tokenId) external returns (bytes memory result)",
"function donateToPosition(address handler, uint256 tokenId, uint256 amount0, uint256 amount1) external returns (bytes memory result)",
// View functions
"function isHandlerWhitelisted(address handler) external view returns (bool)",
// Events
"event PositionMinted(address indexed handler, uint256 indexed tokenId, address recipient)",
"event PositionBurned(address indexed handler, uint256 indexed tokenId, address recipient)",
"event PositionUsed(address indexed handler, uint256 indexed tokenId)",
"event PositionUnused(address indexed handler, uint256 indexed tokenId)",
"event PositionDonated(address indexed handler, uint256 indexed tokenId, uint256 amount0, uint256 amount1)"
];Option Market ABI
export const OPTION_MARKET_ABI = [
// Option functions
"function buyOption(bool isCall, bool isPut, uint256 strikePrice, uint256 maturity, uint256 priceTolerance, uint256 maxCost, address handler, address underlying) external returns (uint256 optionTokenId)",
"function exerciseOption(uint256 optionTokenId) external returns (uint256 profit)",
// View functions
"function getOptionData(uint256 optionTokenId) external view returns (tuple(bool isCall, bool isPut, uint256 strikePrice, uint256 maturity, address handler, address underlying))",
"function getOptionPrice(bool isCall, bool isPut, uint256 spotPrice, uint256 strikePrice, uint256 timeToMaturity, uint256 volatility) external pure returns (uint256)",
// Events
"event OptionBought(uint256 indexed optionTokenId, address indexed buyer)",
"event OptionExercised(uint256 indexed optionTokenId, address indexed exerciser, uint256 profit)"
];Advanced Features
Batch Operations
For advanced users, the MarginZero Provider supports batch operations:
async batchMintPositions(
operations: Array<{
handlerAddress: string;
tokenId: number;
recipient: string;
}>
): Promise<string>Custom Gas Settings
The provider allows for custom gas settings to be passed for transactions:
async exerciseOption(
optionTokenId: number,
gasSettings?: {
gasPrice?: string;
gasLimit?: string;
}
): Promise<string>Security Considerations
When integrating with MarginZero, be aware of the following security considerations:
Price Oracle Risk: Options pricing relies on price oracles which may be manipulated
Slippage Protection: Always use price tolerance parameters to protect against excessive slippage
Gas Estimation: Exercise caution with gas estimation, especially during high network congestion
Permission Management: Carefully manage permissions for minting and burning positions
Troubleshooting
Common Issues
Transaction Reverted: Check that you have sufficient funds and correct permissions
Option Data Not Available: Confirm that the option token ID exists and belongs to the correct market
Handler Not Whitelisted: Verify that the handler address is correctly whitelisted in the position manager
Debugging
The MarginZero Provider includes detailed logging that can be enabled:
// Enable debug logging
marginZeroProvider.setDebugLogging(true);
// Transaction with detailed logging
const result = await marginZeroProvider.mintPosition(...);Future Enhancements
The MarginZero integration roadmap includes:
Portfolio Management: Advanced portfolio tracking for options positions
Risk Analysis: Real-time risk metrics for options positions
Strategy Templates: Pre-built options strategies like covered calls and protective puts
Multi-chain Support: Expansion to additional EVM-compatible blockchains
References
Last updated