# f(x) Protocol SDK Features

**Creator:** Christopher Stampar (@cstampar)  
**Date:** December 20, 2025

This document tracks the unique features and capabilities of the f(x) Protocol Python SDK.

## Core SDK Features

- **Class-Based Architecture**: Centralized `ProtocolClient` manages Web3 connections, account signing, and contract orchestration.
- **Secure Multi-Source Authentication**: Production-ready credential management with automatic discovery from multiple secure sources:
  - **Environment Variables**: `FX_PROTOCOL_PRIVATE_KEY` for production deployments
  - **`.env` Files**: Automatic loading for local development (with `.gitignore` protection)
  - **Google Colab Secrets**: Native integration with Colab's `userdata` API
  - **Browser Wallet Support**: Connect to MetaMask and other browser extensions via `use_browser_wallet=True`
  - **Read-Only Mode**: Full protocol querying capabilities without any credentials
  - **Priority-Based Discovery**: Automatically checks sources in security-optimal order
- **High-Precision Data Normalization**: 
  - Automatic `Wei-to-Decimal` and `Decimal-to-Wei` conversion for all inputs and outputs.
  - Uses Python's `Decimal` type to prevent floating-point precision errors in financial calculations.
- **Integrated Logging**: Production-grade logging via the standard `logging` library for transparent operation tracking and debugging.
- **Robust Error Handling**: Custom exception hierarchy (`FXProtocolError`, `TransactionFailedError`, `InsufficientBalanceError`, etc.) for clear, actionable error reporting.
- **Graceful ABI Loading**: Advanced contract loader that handles missing or empty ABI files, allowing the client to operate in "partial" mode while the `/abis` directory is being populated.
- **Modular Design**: Clear separation between "Read" (call) and "Write" (send) operations.

## Protocol Coverage

### V2 Core & Extensions
- **fxUSD Ecosystem**:
  - Full support for `fxUSD` balance and total supply tracking.
  - Integration with the `fxUSD_BasePool` for asset and supply metrics.
- **xPOSITION Ecosystem**:
  - Direct management of leveraged positions via the Pool Manager (`operate`, `rebalance`, `liquidate`).
  - Native support for primary collateral: `stETH`, `wstETH`, `frxETH`, `sfrxETH`.
  - Advanced position and peg discovery via `get_position_info` and `get_peg_keeper_info`.
- **Savings & Stability**:
  - `fxSAVE` (Saving fxUSD): Balance tracking, APR fetching, and deposit/redeem logic.
  - `fxSP` (Stability Pool): Staking and withdrawal management for the fxUSD stability layer.

### V1 Legacy Support
- **Full Asset Portability**:
  - Native support for legacy tokens: `fETH`, `rUSD`, `btcUSD`, `cvxUSD`, and `arUSD`.
  - Complete xToken coverage: `xETH`, `xCVX`, `xWBTC`, `xeETH`, `xezETH`, `xstETH`, `xfrxETH`.
- **Market Insights**: NAV (Net Asset Value) and Collateral Ratio metrics for V1 markets.
- **Rebalance Pool Management**: Dynamic discovery of V1 rebalance pools via the `RebalancePoolRegistry`, with full support for staking (`deposit`), unlocking, and reward claiming.

### Governance & Utility
- **veFXN Staking**: Logic for locking FXN into veFXN to gain voting power, including expiration tracking.
- **Gauge Ecosystem**: 
  - Fetching gauge weights from the `GaugeController`.
  - Voting for gauge weight allocations.
  - Claimable reward tracking and global reward claiming from any `LiquidityGauge`.
- **Vesting Claims**: Specialized methods for claiming vested `FXN`, `fETH`, and `fxUSD`.

## Infrastructure & Analytics
- **V2 Pool Manager**: Comprehensive control over V2 positions, including `operate`, `rebalance`, and `liquidate` methods.
- **Reserve Pool & Treasury**: Interface with protocol reserves and V1 stETH Treasury for NAV tracking and bonus requests.
- **Oracle Integration**: Direct price fetching from the `stETH_PriceOracle`.
- **Advanced Routing**: Support for complex token swaps using the `MultiPathConverter`.
- **Gateway Interactions**: Streamlined ETH/stETH deposits via the `stETH_Gateway` using `mint_f_token_via_gateway` and `mint_x_token_via_gateway`.
- **Flash Loan Support**: Native ERC-3156 flash loan integration via the Pool Manager.

## Developer Tools

- **Address Registry**: Centralized `constants.py` with verified addresses for all protocol contracts (V1 and V2).
- **Comprehensive Balance Aggregator**: `get_all_balances()` and `get_all_gauge_balances()` methods to fetch human-readable snapshots of all protocol-related assets in a single call. Supports 13+ protocol tokens including all x tokens (xETH, xCVX, xWBTC, xeETH, xezETH, xstETH, xfrxETH).
- **Production-Grade Testing**: Fully mocked unit tests in `tests.py` covering infrastructure, tuple parsing, and complex transaction flows.
- **Pythonic Interface**: Type hinting (Python 3.9+) and Google-style docstrings for superior IDE support and autocompletion.
- **Security-First Design**: Built-in `.gitignore` templates and authentication best practices to prevent accidental credential exposure in version control.
