MarginZero Agent
The MarginZero integration provides advanced options and derivatives trading capabilities to the Ava Portfolio Manager. This component enables users to create, manage, and trade options contracts on various underlying assets, enhancing the platform's trading and risk management capabilities.
Overview
MarginZero is a decentralized options protocol that allows for the creation and trading of European-style options on a wide range of assets. The Ava Portfolio Manager integrates with MarginZero through the MarginZeroProvider, which provides a comprehensive interface for options trading operations.
Key Features
Options contract creation and trading
Position management for options positions
Advanced risk management tools
Options data analytics and pricing
Integration with the Sonic Agent for seamless operations
Architecture
The MarginZero integration consists of several key components:
MarginZeroProvider: The core provider class that handles all interactions with MarginZero contracts
Position Manager Interface: Manages interaction with the Position Manager contract
Option Market Interface: Handles operations on the Option Market contract
Type Definitions: Structured type definitions for options data and parameters
Core Components
MarginZeroProvider
The main class that provides methods for interacting with MarginZero contracts:
export class MarginZeroProvider {
private config: MarginZeroConfig;
private publicClient: ReturnType<typeof createPublicClient>;
private walletClient?: ReturnType<typeof createWalletClient>;
constructor(config: MarginZeroConfig) {
// Initialize the provider with configuration
}
// Position Manager methods
async isHandlerWhitelisted(handlerAddress: Address): Promise<boolean>;
async mintPosition(handlerAddress: Address, mintPositionData: `0x${string}`): Promise<bigint>;
async burnPosition(handlerAddress: Address, burnPositionData: `0x${string}`): Promise<bigint>;
async usePosition(handlerAddress: Address, usePositionData: `0x${string}`): Promise<{
tokens: Address[];
amounts: bigint[];
liquidityUsed: bigint;
}>;
async unusePosition(handlerAddress: Address, unusePositionData: `0x${string}`): Promise<{
amounts: bigint[];
liquidity: bigint;
}>;
async donateToPosition(handlerAddress: Address, donatePositionData: `0x${string}`): Promise<{
amounts: bigint[];
liquidity: bigint;
}>;
// Option Market methods
async getOptionData(tokenId: bigint): Promise<OptionData>;
async getOptionPrice(tokenId: bigint): Promise<bigint>;
async buyOption(params: BuyOptionParams): Promise<{
tokenId: bigint;
premium: bigint;
}>;
async exerciseOption(tokenId: bigint): Promise<bigint>;
}Configuration
The MarginZeroProvider requires specific configuration parameters:
export interface MarginZeroConfig {
chainId: CHAIN_IDS;
rpcUrl: string;
account?: Account;
positionManagerAddress: Address;
optionMarketAddress: Address;
}Data Types
Key data types for options operations:
export interface OptionData {
opTickArrayLen: bigint;
expiry: bigint;
tickLower: number;
tickUpper: number;
isCall: boolean;
}
export interface BuyOptionParams {
token0: Address;
token1: Address;
fee: number;
isCall: boolean;
expiry: bigint;
strike: number;
notionalAmount: bigint;
maxCost: bigint;
}Integration with Sonic Agent
The MarginZero Provider is primarily integrated with the Sonic Agent, enabling a seamless combination of spot trading and options strategies. The integration enables:
Access to options trading from the same interface as spot trading
Combined strategies involving both spot and options positions
Unified portfolio management across trading types
Consistent user experience for all trading activities
Usage
Initializing the Provider
const marginZeroConfig = {
chainId: CHAIN_IDS.ETHEREUM,
rpcUrl: 'https://ethereum.publicnode.com',
account: userAccount, // viem Account object
positionManagerAddress: '0x123...',
optionMarketAddress: '0x456...'
};
const marginZeroProvider = new MarginZeroProvider(marginZeroConfig);Checking Handler Whitelisting
const handlerAddress = '0x789...';
const isWhitelisted = await marginZeroProvider.isHandlerWhitelisted(handlerAddress);Getting Option Data
const tokenId = 12345n;
const optionData = await marginZeroProvider.getOptionData(tokenId);
console.log(`Option Expiry: ${new Date(Number(optionData.expiry) * 1000)}`);
console.log(`Option Type: ${optionData.isCall ? 'CALL' : 'PUT'}`);Buying an Option
const buyParams = {
token0: '0xabc...', // Base token (e.g., ETH)
token1: '0xdef...', // Quote token (e.g., USDC)
fee: 3000, // Pool fee tier (0.3%)
isCall: true, // CALL option
expiry: 1672531200n, // Expiry timestamp
strike: 2000, // Strike price in ticks
notionalAmount: parseUnits('1', 18), // 1 ETH notional
maxCost: parseUnits('0.1', 18) // Max premium 0.1 ETH
};
const result = await marginZeroProvider.buyOption(buyParams);
console.log(`Option purchased with ID: ${result.tokenId}`);
console.log(`Premium paid: ${formatUnits(result.premium, 18)} ETH`);Exercising an Option
const tokenId = 12345n;
const profit = await marginZeroProvider.exerciseOption(tokenId);
console.log(`Option exercised with profit: ${formatUnits(profit, 18)} ETH`);Position Management
The MarginZero integration provides comprehensive position management capabilities:
Minting a Position
const handlerAddress = '0x789...';
const mintPositionData = '0x...'; // ABI-encoded position data
const positionId = await marginZeroProvider.mintPosition(handlerAddress, mintPositionData);Using a Position
const handlerAddress = '0x789...';
const usePositionData = '0x...'; // ABI-encoded usage data
const result = await marginZeroProvider.usePosition(handlerAddress, usePositionData);
console.log(`Liquidity used: ${result.liquidityUsed}`);
console.log(`Tokens involved: ${result.tokens}`);
console.log(`Amounts: ${result.amounts}`);Error Handling
The MarginZero Provider implements robust error handling:
Contract-level errors are properly decoded and reported
RPC connection failures include retry mechanisms
Transaction simulation is performed before execution
Gas estimation failures provide clear error messages
Security Considerations
Private keys are never exposed in logs or responses
All parameters are validated before transactions
Transaction limits can be configured for risk management
Slippage protection is included for all transactions
Future Enhancements
Planned improvements to the MarginZero integration include:
Support for exotic option types
Advanced options strategies (spreads, straddles, etc.)
Portfolio hedging automation
Options analytics dashboard
Cross-chain options trading
Technical References
Last updated