# ⚠️ Warning: Beta Version ⚠️
This SDK is currently in beta version and actively under development. It may contain bugs, incomplete features, and breaking changes. Use with caution. Feedback and contributions are welcome to help improve its stability and functionality.
# Limitations
- zkSync Sepolia testnet was deprecated and is not functional.
# RFX Python SDK
A Python-based SDK developed for interacting with RFX Exchange, offering tools and scripts for executing various operations, including trading and liquidity management.
## Table of Contents
- [Usage](#usage)
- [Local Installation](#local-installation)
- [Local Build](#local-build)
- [Running Tests](#running-tests)
- [Building Documentation](#building-documentation)
- [DOC: GET Classes](#get-classes)
- [DOC: Order Classes](#order-classes)
- [DOC: Utils](#utils)
## Usage
The SDK can be installed via pip:
```sh
pip install pyrfx
```
## Local Installation
The supported Python versions: >= 3.10 <4
To set up the project locally, follow these steps:
1) Install packages:
```sh
poetry install --with dev
```
2) If you are actively developing your project and need changes to the source code (src/pyrfx) to be immediately reflected without reinstalling the package every time, you can additionally use the editable install. This step allows you to make modifications in your code and see them reflected immediately.
```sh
poetry run pip install -e .
```
## Local build
```sh
mkdir dist/
cd ./dist
poetry build
```
## Running Tests
To execute tests:
```sh
poetry run pytest
```
## Building Documentation
To build HTML documentation:
```sh
poetry run pdoc src/pyrfx examples -o docs
```
## GET Classes
### AvailableLiquidity Class
The `AvailableLiquidity` class, inheriting from `Data`, is used to calculate and log available liquidity for long and short positions across multiple markets.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional flag (`use_local_datastore`) to specify local datastore usage, and a logging level (`log_level`).
- **Logging**: Uses a logger to provide detailed information on the liquidity computation process.
- **Data Processing**: Implements `_get_data_processing()` to process available liquidity for each market using Web3 contract calls and price data from Oracle.
- **Precision Calculation**: Uses `_get_precision_factors()` to calculate precision factors for long, short, and oracle prices.
- **Token Price Fetching**: The `_get_token_price()` method fetches the recent token prices with error handling.
- **Liquidity Calculation**: The `_log_liquidity()` method calculates and logs the available liquidity for long and short positions, providing insight into the market state.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
available_liquidity: dict = AvailableLiquidity(config=config).get_data()
```
### BorrowAPR Class
The `BorrowAPR` class, inheriting from `Data`, is used to retrieve and calculate the Borrow Annual Percentage Rate (APR) for long and short positions across multiple blockchain markets.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).
- **Logging**: Uses a logger to provide detailed information during APR data computation.
- **Data Processing**: Implements `_get_data_processing()` to generate and calculate long and short borrow APR for each market, utilizing parallel data processing for efficiency.
- **Threaded Processing**: The class uses `execute_threading()` to handle data retrieval concurrently, improving performance for large datasets.
- **APR Calculation**: The `_process_threaded_output()` method calculates and logs borrow APR values for long and short positions based on the threaded data.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
borrow_apr: dict = BorrowAPR(config=config).get_data()
```
### ClaimableFees Class
The `ClaimableFees` class, inheriting from `Data`, retrieves and calculates the total claimable fees (both long and short) across blockchain markets.
#### Key Features
- **Initialization**: Takes a `ConfigManager` object to handle chain configurations, and a logging level (`log_level`).
- **Logging**: Uses a logger to log detailed information during the fee calculation process.
- **Data Processing**: Implements `_get_data_processing()` to compute the total claimable fees for each market in USD.
- **Threaded Processing**: Uses `execute_threading()` to retrieve data in parallel for long and short claimable fees, boosting performance.
- **Oracle Price Fetching**: Fetches prices via the `OraclePrices` class for accurate USD valuation of fees.
- **Claimable Fee Calculation**: The `_calculate_total_fees()` method computes the total fees and logs the result, converting raw outputs into USD values.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
claimable_fees: dict = ClaimableFees(config=config).get_data()
```
### ContractBalance Class
The `ContractBalance` class, inheriting from `Data`, retrieves the USD balance of contracts in liquidity pools across multiple blockchain markets. It integrates smoothly into the SDK and supports blockchain data retrieval for pool liquidity analysis.
#### Key Features
- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).
- **Logging**: Uses a logger to log information about the pool balances during the data fetching and computation processes.
- **Oracle Price Integration**: Fetches oracle prices via the `OraclePrices` class for calculating the USD equivalent of token balances.
- **Pool Balance Calculation**: Implements `get_pool_balances()` to query token balances from available markets and compute the total value in liquidity pools.
- **Saving Data**: Optionally saves the pool balance data to a JSON file if the `ConfigManager` has `save_to_json` enabled.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
contract_balances: dict = ContractBalance(config=config).get_pool_balances()
```
### Data Base Class
The `Data` class serves as an abstract base class for retrieving and processing blockchain market data. It provides a foundation for handling token prices, managing market information, and saving data in various formats.
#### Key Features
- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Supports optional use of a local datastore and filtering of swap markets.
- **Logging**: Uses a logger to provide detailed logs during data processing.
- **Market Information Handling**: Includes methods to retrieve long and short token addresses for each market, as well as filtering out swap markets.
- **Data Saving**: Supports saving data in both JSON (`_save_to_json()`) and CSV (`_save_to_csv()`) formats, allowing for easy data export.
- **Oracle Prices Integration**: Fetches prices from `OraclePrices` to facilitate calculations.
- **PnL Calculation**: Includes a method (`_get_pnl()`) to retrieve the Profit and Loss (PnL) and Open Interest with PnL for a market.
- **Market Information Retrieval**: `_get_oracle_prices()` and `_get_token_addresses()` are used for gathering token price information from the reader contract and managing the data associated with markets.
- **Abstract Data Processing**: Defines an abstract `_get_data_processing()` method, intended to be implemented by subclasses for specific data processing logic.
#### Example Usage
As this is an abstract base class, you would use it by extending it in a subclass. Here is a simple example of how to do that:
### EstimateSwapOutput Class
The `EstimateSwapOutput` class is used to estimate the swap output between two tokens on a blockchain network. It utilizes market data, available liquidity, and oracle price information to provide an estimate of the output token amount and price impact.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a dictionary of markets. The logging level (`log_level`) can also be specified.
- **Logging**: Uses a logger to provide detailed information about the token swap process.
- **Swap Output Estimation**: Implements `get_swap_output()` to estimate the amount of output tokens for a given input token and amount, including resolving token addresses and calculating price impacts.
- **Swap Route Determination**: Utilizes `SwapRouter` to determine the optimal swap route based on the available markets.
- **Market Price Integration**: Fetches recent prices using the `OraclePrices` class to accurately calculate the swap output in USD.
- **Support for Multiple Tokens**: Can handle multiple tokens and dynamically resolves token addresses if not provided.
#### Example Usage
```sh
# Initialize parameters
parameters: dict[str, str | float] = {
"start_token_symbol": "WETH",
"out_token_symbol": "USDC",
"token_amount": 0.4,
}
config: ConfigManager = ConfigManager(...)
available_markets: dict[ChecksumAddress, dict[str, Any]] = Markets(config=config).get_available_markets()
eso: EstimateSwapOutput = EstimateSwapOutput(config=config, markets=available_markets)
swap_output: dict[str, float] = eso.get_swap_output(
start_token_symbol=parameters["start_token_symbol"],
out_token_symbol=parameters["out_token_symbol"],
token_amount=parameters["token_amount"],
)
```
### FundingAPR Class
The `FundingAPR` class is responsible for calculating funding APRs for long and short positions in RFX blockchain markets. It can retrieve data from a local datastore or directly from an API, perform multithreaded calculations, and log results.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, an optional flag (`use_local_datastore`) for data retrieval, and a logging level (`log_level`).
- **Data Loading**: Loads open interest data either from a local JSON file or from an API (`_load_open_interest_data()`).
- **Data Processing**: The `_get_data_processing()` method retrieves relevant market data, processes it in a multithreaded manner, and calculates funding APR.
- **Market Information Handling**: Gathers token addresses and oracle prices for each market (`_process_market_key()`).
- **Funding Fee Calculation**: Uses the `_process_threaded_output()` method to calculate funding APR fees for long and short positions based on oracle prices and interest values.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
funding_apr: dict = FundingAPR(config=config).get_data()
```
### Markets Class
The `Markets` class is responsible for retrieving and managing blockchain market data, including token addresses and metadata for different markets. It provides methods for accessing market-specific information and integrates seamlessly with the overall SDK.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, and a logging level (`log_level`).
- **Market Data Retrieval**: Retrieves and processes raw market data using a reader contract, organizing it into a structured dictionary (`_process_markets()`).
- **Token Address Access**: Provides methods to access long, short, and index token addresses for each market (`get_long_token_address()`, `get_short_token_address()`, `get_index_token_address()`).
- **Market Metadata**: Retrieves additional market-specific metadata, such as the market symbol, decimal factors, and whether a market is synthetic.
- **Market Filtering**: Filters out markets that are not in the signed prices API to ensure only live, valid markets are processed.
- **Swap Market Handling**: Handles both standard and swap markets, with logic to generate appropriate market symbols and metadata.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
available_markets: dict = Markets(config=config).get_available_markets()
```
### OpenInterest Class
The `OpenInterest` class retrieves and processes open interest data for long and short positions across RFX blockchain markets. It uses oracle price data and multi-threaded calculations to provide efficient and accurate data analysis.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).
- **Open Interest Calculation**: Uses the `_get_data_processing()` method to calculate open interest by fetching market data and using multi-threaded execution for efficiency.
- **Oracle Price Integration**: Retrieves oracle prices using the `OraclePrices` class to determine market pricing information.
- **Multi-threading Execution**: The `_execute_multithreading()` method is used to process multiple calculations concurrently, improving performance.
- **Precision Handling**: Determines precision factors for synthetic and non-synthetic markets (`_get_precision_factor()`) to accurately calculate open interest values.
- **Logging Results**: Logs the final calculated values for long and short open interest, providing a clear summary of the market data.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
open_interest: dict = OpenInterest(config=config).get_data()
```
### OpenPositions Class
The `OpenPositions` class is responsible for retrieving and processing open positions for a given blockchain address. It fetches open positions from a reader contract and processes them into a structured format, including detailed metrics like leverage and profit percentage.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional address for querying, and a logging level (`log_level`).
- **Open Position Retrieval**: Uses the `get_open_positions()` method to fetch and process all open positions for the given address.
- **Market Data Integration**: Integrates with available market data to provide context and symbols for each open position.
- **Leverage and Price Calculation**: Calculates key metrics for each open position, including entry price, leverage, mark price, and profit percentage (`_calculate_position_metrics()`).
- **Oracle Price Integration**: Uses the `OraclePrices` class to retrieve recent oracle prices for calculating the mark price of a position.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
open_positions: dict = OpenPositions(config=config).get_open_positions()
```
### OraclePrices Class
The `OraclePrices` class is responsible for fetching and processing the latest signed token prices from the RFX API for various blockchain networks. It integrates with the `ConfigManager` to configure the relevant API endpoint based on the blockchain network.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).
- **Price Retrieval**: Uses the `get_recent_prices()` method to make a GET request to the RFX Oracle API and retrieve signed token prices.
- **Request Handling**: Implements error handling for request failures (`_make_query()`) and validates the response format (`_process_output()`).
- **Logging**: Logs the progress of requests and the processing of token prices.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
prices: dict = OraclePrices(config=config).get_recent_prices()
```
### PoolTVL Class
The `PoolTVL` class retrieves and calculates the Total Value Locked (TVL) in USD across all pools for a given blockchain. It uses data from oracle prices and a data store contract to determine the value of tokens in each pool.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Also initializes oracle price data and data store contract.
- **TVL Calculation**: The `get_pool_balances()` method calculates the TVL for each pool by querying token balances and calculating their equivalent USD values.
- **Oracle Price Integration**: Uses the `OraclePrices` class to fetch the most recent prices of tokens, which are then used to calculate USD values.
- **Data Store Contract Integration**: Uses a Web3 contract to query the current token balances for both long and short positions in each pool.
- **Logging and Data Saving**: Logs detailed TVL information for each market and saves the TVL data to JSON and/or CSV formats, if configured to do so.
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
pool_tvl_data: dict = PoolTVL(config=config).get_pool_balances()
```
### RPPrices Class
The `RPPrices` class is responsible for calculating Reward Pool (RP) prices for various market actions, such as withdrawal, deposit, and trading, in the blockchain ecosystem. It extends the `Data` class to use common market and token retrieval functionalities and processes market prices using contract queries.
#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, a logging level (`log_level`), and initializes a reader contract to interact with the blockchain.
- **Market Actions**: Provides methods to calculate RP prices for different actions:
- `get_price_withdraw()`: Fetches RP prices for withdrawing from a liquidity pool.
- `get_price_deposit()`: Fetches RP prices for depositing into a liquidity pool.
- `get_price_traders()`: Fetches RP prices for traders.
- **Multithreading**: Implements threading for price calculations to improve performance when querying multiple markets concurrently.
- **Market Data Preparation**: Uses `_prepare_market_data()` to gather the relevant market addresses and token information needed for price queries.
- **Data Processing**: Uses `_process_output()` to convert the raw outputs into a more structured and human-readable format.
- **Data Saving**: Saves the processed RP prices to JSON or CSV formats if configured (`_save_output()`).
#### Example Usage
```sh
config: ConfigManager = ConfigManager(...)
rp_prices: dict = RPPrices(config=config).get_price_traders()
```
## Order Classes
### DecreaseOrder Class
The DecreaseOrder class is used to manage and execute decrease orders (sell or close positions) on the RFX Exchange.
#### Key Features
- **Initialization:** Configures parameters such as market address, collateral, position size, slippage, and optional swap paths.
- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract.
- **Order Execution:** Builds and submits a decrease order with execution fees, acceptable prices, and price impact checks.
- **Integration:** Utilizes market and oracle price data for accurate calculations.
#### Example Usage
```sh
order = DecreaseOrder(
config=config,
market_address=market_address,
collateral_address=collateral_address,
index_token_address=index_token_address,
is_long=False,
size_delta=100,
initial_collateral_delta=50,
slippage_percent=0.05,
debug_mode=True,
)
order.create_and_execute()
```
### IncreaseOrder Class
The IncreaseOrder class is used to manage and execute increase orders (buy or open positions) on the RFX Exchange.
#### Key Features
- **Initialization:** Configures parameters such as market address, collateral, position size, slippage, and optional swap paths.
- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract.
- **Order Execution:** Builds and submits an increase order with execution fees, acceptable prices, and price impact checks.
- **Integration:** Utilizes market and oracle price data for accurate calculations.
#### Example Usage
```sh
order = IncreaseOrder(
config=config,
market_address=market_address,
collateral_address=collateral_address,
index_token_address=index_token_address,
is_long=True,
size_delta=100,
initial_collateral_delta=50,
slippage_percent=0.05,
debug_mode=True,
)
order.create_and_execute()
```
### DepositOrder Class
The DepositOrder class is used to manage and execute deposit orders in the RFX Exchange.
#### Key Features
- **Initialization:** Configures parameters such as market address, token addresses, and amounts for both long and short deposits.
- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract for deposit operations.
- **Integration:** Extends the base Deposit class to handle deposit-specific logic and operations.
#### Example Usage
```sh
order = DepositOrder(
config=config,
market_address=market_address,
initial_long_token_address=long_token_address,
initial_short_token_address=short_token_address,
long_token_amount=1000,
short_token_amount=500,
debug_mode=True,
)
order.create_and_execute()
```
### WithdrawOrder Class
The WithdrawOrder class is used to create and manage withdrawal orders in the RFX Exchange.
#### Key Features
- **Initialization:** Configures parameters such as market address, token address for withdrawal, and the amount of RP tokens to withdraw.
- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract for withdrawal operations.
- **Integration:** Extends the base Withdraw class to handle withdrawal-specific logic and operations.
#### Example Usage
```sh
order = WithdrawOrder(
config=config,
market_address=market_address,
out_token=out_token_address,
rp_amount=1000,
debug_mode=True,
)
order.create_and_execute()
```
### SwapOrder Class
The SwapOrder class is used to create and manage token swap orders in the RFX Exchange.
#### Key Features
- **Initialization:** Configures parameters such as token addresses, market details, swap path, slippage, and optional execution fees.
- **Gas Limit Handling:** Determines appropriate gas limits for single or multiple swap operations using the datastore contract.
- **Swap Estimation:** Includes functionality to estimate swap output and price impact based on token amounts and market data.
- **Integration:** Extends the base Order class to handle swap-specific logic and operations.
#### Example Usage
```sh
order = SwapOrder(
config=config,
start_token_address=start_token,
out_token_address=out_token,
market_address=market_address,
collateral_address=collateral_address,
index_token_address=index_token_address,
initial_collateral_delta=1000,
slippage_percent=0.01,
swap_path=[start_token, out_token],
debug_mode=True,
)
order.create_and_execute()
```
## Utils
### ConfigManager Class
The ConfigManager class manages blockchain configuration settings, including RPC URLs, wallet addresses, chain information, and contract details.
#### Key Features
- **Initialization:** Sets up network configurations, user wallet details, and data storage options for a specified blockchain network.
- **Contract Management:** Loads contract addresses and ABIs for network-specific contracts.
- **Checksum Conversion:** Converts Ethereum addresses to checksum format for accuracy and compatibility.
- **Environment Integration:** Supports fetching wallet addresses and private keys from environment variables.
- **Data Saving Options:** Provides flags to enable saving output data to JSON or CSV formats.
#### Example Usage
```sh
config = ConfigManager(
chain="zkSync",
user_wallet_address="0xYourWalletAddress",
private_key="YourPrivateKey",
save_to_json=True,
output_data_folder="./data",
)
print(config)
```
### CustomErrorParser Class
The CustomErrorParser class is designed to parse Solidity errors returned from blockchain transactions. It supports decoding errors based on ABI definitions, Panic codes, and standard error strings.
#### Key Features
- **ABI-Based Error Parsing:** Matches error bytes against the ABI to identify custom errors and decode parameters.
- **Panic Code Decoding:** Parses Solidity Panic(uint256) errors and maps panic codes to descriptive messages.
- **Standard Error Parsing:** Decodes Solidity Error(string) messages.
- **Fallback Parsing:** Attempts to parse errors as generic strings when standard parsing fails.
#### Example Usage
```sh
parser = CustomErrorParser(config=config)
error_bytes = "0x12345678abcdef" # Replace with actual error bytes
parsed_error = parser.parse_error(error_bytes)
print(parsed_error)
```
Raw data
{
"_id": null,
"home_page": "https://rfx.exchange",
"name": "pyrfx",
"maintainer": "RFX Dev",
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": "dev@rfx.exchange",
"keywords": "SDK, RFX, blockchain, Python, DeFi, DEX, Exchange",
"author": "RFX Dev",
"author_email": "dev@rfx.exchange",
"download_url": "https://files.pythonhosted.org/packages/75/b0/ef7b955d49c7d7a91d24c6213f3128c8fb253a4d51cb007de0951c877cd6/pyrfx-0.1.12.tar.gz",
"platform": null,
"description": "# \u26a0\ufe0f Warning: Beta Version \u26a0\ufe0f\n\nThis SDK is currently in beta version and actively under development. It may contain bugs, incomplete features, and breaking changes. Use with caution. Feedback and contributions are welcome to help improve its stability and functionality.\n\n# Limitations\n- zkSync Sepolia testnet was deprecated and is not functional. \n\n# RFX Python SDK\n\nA Python-based SDK developed for interacting with RFX Exchange, offering tools and scripts for executing various operations, including trading and liquidity management.\n\n## Table of Contents\n- [Usage](#usage)\n- [Local Installation](#local-installation)\n- [Local Build](#local-build)\n- [Running Tests](#running-tests)\n- [Building Documentation](#building-documentation)\n- [DOC: GET Classes](#get-classes)\n- [DOC: Order Classes](#order-classes)\n- [DOC: Utils](#utils)\n\n\n## Usage\nThe SDK can be installed via pip:\n```sh\npip install pyrfx\n```\n\n## Local Installation\nThe supported Python versions: >= 3.10 <4\n\nTo set up the project locally, follow these steps:\n1) Install packages: \n```sh\n poetry install --with dev \n```\n2) If you are actively developing your project and need changes to the source code (src/pyrfx) to be immediately reflected without reinstalling the package every time, you can additionally use the editable install. This step allows you to make modifications in your code and see them reflected immediately.\n```sh\n poetry run pip install -e . \n```\n\n## Local build\n```sh\nmkdir dist/\ncd ./dist\npoetry build\n```\n\n## Running Tests\nTo execute tests:\n```sh\npoetry run pytest\n```\n\n## Building Documentation\nTo build HTML documentation:\n```sh\npoetry run pdoc src/pyrfx examples -o docs\n```\n\n\n## GET Classes\n\n### AvailableLiquidity Class\n\nThe `AvailableLiquidity` class, inheriting from `Data`, is used to calculate and log available liquidity for long and short positions across multiple markets.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional flag (`use_local_datastore`) to specify local datastore usage, and a logging level (`log_level`).\n- **Logging**: Uses a logger to provide detailed information on the liquidity computation process.\n- **Data Processing**: Implements `_get_data_processing()` to process available liquidity for each market using Web3 contract calls and price data from Oracle.\n- **Precision Calculation**: Uses `_get_precision_factors()` to calculate precision factors for long, short, and oracle prices.\n- **Token Price Fetching**: The `_get_token_price()` method fetches the recent token prices with error handling.\n- **Liquidity Calculation**: The `_log_liquidity()` method calculates and logs the available liquidity for long and short positions, providing insight into the market state.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\navailable_liquidity: dict = AvailableLiquidity(config=config).get_data()\n```\n\n### BorrowAPR Class\n\nThe `BorrowAPR` class, inheriting from `Data`, is used to retrieve and calculate the Borrow Annual Percentage Rate (APR) for long and short positions across multiple blockchain markets.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).\n- **Logging**: Uses a logger to provide detailed information during APR data computation.\n- **Data Processing**: Implements `_get_data_processing()` to generate and calculate long and short borrow APR for each market, utilizing parallel data processing for efficiency.\n- **Threaded Processing**: The class uses `execute_threading()` to handle data retrieval concurrently, improving performance for large datasets.\n- **APR Calculation**: The `_process_threaded_output()` method calculates and logs borrow APR values for long and short positions based on the threaded data.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nborrow_apr: dict = BorrowAPR(config=config).get_data()\n```\n\n### ClaimableFees Class\n\nThe `ClaimableFees` class, inheriting from `Data`, retrieves and calculates the total claimable fees (both long and short) across blockchain markets.\n\n#### Key Features\n- **Initialization**: Takes a `ConfigManager` object to handle chain configurations, and a logging level (`log_level`).\n- **Logging**: Uses a logger to log detailed information during the fee calculation process.\n- **Data Processing**: Implements `_get_data_processing()` to compute the total claimable fees for each market in USD.\n- **Threaded Processing**: Uses `execute_threading()` to retrieve data in parallel for long and short claimable fees, boosting performance.\n- **Oracle Price Fetching**: Fetches prices via the `OraclePrices` class for accurate USD valuation of fees.\n- **Claimable Fee Calculation**: The `_calculate_total_fees()` method computes the total fees and logs the result, converting raw outputs into USD values.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nclaimable_fees: dict = ClaimableFees(config=config).get_data()\n```\n\n### ContractBalance Class\n\nThe `ContractBalance` class, inheriting from `Data`, retrieves the USD balance of contracts in liquidity pools across multiple blockchain markets. It integrates smoothly into the SDK and supports blockchain data retrieval for pool liquidity analysis.\n\n#### Key Features\n- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).\n- **Logging**: Uses a logger to log information about the pool balances during the data fetching and computation processes.\n- **Oracle Price Integration**: Fetches oracle prices via the `OraclePrices` class for calculating the USD equivalent of token balances.\n- **Pool Balance Calculation**: Implements `get_pool_balances()` to query token balances from available markets and compute the total value in liquidity pools.\n- **Saving Data**: Optionally saves the pool balance data to a JSON file if the `ConfigManager` has `save_to_json` enabled.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\ncontract_balances: dict = ContractBalance(config=config).get_pool_balances()\n```\n\n### Data Base Class\n\nThe `Data` class serves as an abstract base class for retrieving and processing blockchain market data. It provides a foundation for handling token prices, managing market information, and saving data in various formats.\n\n#### Key Features\n- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Supports optional use of a local datastore and filtering of swap markets.\n- **Logging**: Uses a logger to provide detailed logs during data processing.\n- **Market Information Handling**: Includes methods to retrieve long and short token addresses for each market, as well as filtering out swap markets.\n- **Data Saving**: Supports saving data in both JSON (`_save_to_json()`) and CSV (`_save_to_csv()`) formats, allowing for easy data export.\n- **Oracle Prices Integration**: Fetches prices from `OraclePrices` to facilitate calculations.\n- **PnL Calculation**: Includes a method (`_get_pnl()`) to retrieve the Profit and Loss (PnL) and Open Interest with PnL for a market.\n- **Market Information Retrieval**: `_get_oracle_prices()` and `_get_token_addresses()` are used for gathering token price information from the reader contract and managing the data associated with markets.\n- **Abstract Data Processing**: Defines an abstract `_get_data_processing()` method, intended to be implemented by subclasses for specific data processing logic.\n\n#### Example Usage\nAs this is an abstract base class, you would use it by extending it in a subclass. Here is a simple example of how to do that:\n\n### EstimateSwapOutput Class\n\nThe `EstimateSwapOutput` class is used to estimate the swap output between two tokens on a blockchain network. It utilizes market data, available liquidity, and oracle price information to provide an estimate of the output token amount and price impact.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a dictionary of markets. The logging level (`log_level`) can also be specified.\n- **Logging**: Uses a logger to provide detailed information about the token swap process.\n- **Swap Output Estimation**: Implements `get_swap_output()` to estimate the amount of output tokens for a given input token and amount, including resolving token addresses and calculating price impacts.\n- **Swap Route Determination**: Utilizes `SwapRouter` to determine the optimal swap route based on the available markets.\n- **Market Price Integration**: Fetches recent prices using the `OraclePrices` class to accurately calculate the swap output in USD.\n- **Support for Multiple Tokens**: Can handle multiple tokens and dynamically resolves token addresses if not provided.\n\n#### Example Usage\n```sh\n# Initialize parameters\nparameters: dict[str, str | float] = {\n \"start_token_symbol\": \"WETH\",\n \"out_token_symbol\": \"USDC\",\n \"token_amount\": 0.4,\n}\nconfig: ConfigManager = ConfigManager(...)\navailable_markets: dict[ChecksumAddress, dict[str, Any]] = Markets(config=config).get_available_markets()\neso: EstimateSwapOutput = EstimateSwapOutput(config=config, markets=available_markets)\nswap_output: dict[str, float] = eso.get_swap_output(\n start_token_symbol=parameters[\"start_token_symbol\"],\n out_token_symbol=parameters[\"out_token_symbol\"],\n token_amount=parameters[\"token_amount\"],\n)\n```\n\n### FundingAPR Class\n\nThe `FundingAPR` class is responsible for calculating funding APRs for long and short positions in RFX blockchain markets. It can retrieve data from a local datastore or directly from an API, perform multithreaded calculations, and log results.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, an optional flag (`use_local_datastore`) for data retrieval, and a logging level (`log_level`).\n- **Data Loading**: Loads open interest data either from a local JSON file or from an API (`_load_open_interest_data()`).\n- **Data Processing**: The `_get_data_processing()` method retrieves relevant market data, processes it in a multithreaded manner, and calculates funding APR.\n- **Market Information Handling**: Gathers token addresses and oracle prices for each market (`_process_market_key()`).\n- **Funding Fee Calculation**: Uses the `_process_threaded_output()` method to calculate funding APR fees for long and short positions based on oracle prices and interest values.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nfunding_apr: dict = FundingAPR(config=config).get_data()\n```\n\n### Markets Class\n\nThe `Markets` class is responsible for retrieving and managing blockchain market data, including token addresses and metadata for different markets. It provides methods for accessing market-specific information and integrates seamlessly with the overall SDK.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, and a logging level (`log_level`).\n- **Market Data Retrieval**: Retrieves and processes raw market data using a reader contract, organizing it into a structured dictionary (`_process_markets()`).\n- **Token Address Access**: Provides methods to access long, short, and index token addresses for each market (`get_long_token_address()`, `get_short_token_address()`, `get_index_token_address()`).\n- **Market Metadata**: Retrieves additional market-specific metadata, such as the market symbol, decimal factors, and whether a market is synthetic.\n- **Market Filtering**: Filters out markets that are not in the signed prices API to ensure only live, valid markets are processed.\n- **Swap Market Handling**: Handles both standard and swap markets, with logic to generate appropriate market symbols and metadata.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\navailable_markets: dict = Markets(config=config).get_available_markets()\n```\n\n### OpenInterest Class\n\nThe `OpenInterest` class retrieves and processes open interest data for long and short positions across RFX blockchain markets. It uses oracle price data and multi-threaded calculations to provide efficient and accurate data analysis.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).\n- **Open Interest Calculation**: Uses the `_get_data_processing()` method to calculate open interest by fetching market data and using multi-threaded execution for efficiency.\n- **Oracle Price Integration**: Retrieves oracle prices using the `OraclePrices` class to determine market pricing information.\n- **Multi-threading Execution**: The `_execute_multithreading()` method is used to process multiple calculations concurrently, improving performance.\n- **Precision Handling**: Determines precision factors for synthetic and non-synthetic markets (`_get_precision_factor()`) to accurately calculate open interest values.\n- **Logging Results**: Logs the final calculated values for long and short open interest, providing a clear summary of the market data.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nopen_interest: dict = OpenInterest(config=config).get_data()\n```\n\n### OpenPositions Class\n\nThe `OpenPositions` class is responsible for retrieving and processing open positions for a given blockchain address. It fetches open positions from a reader contract and processes them into a structured format, including detailed metrics like leverage and profit percentage.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional address for querying, and a logging level (`log_level`).\n- **Open Position Retrieval**: Uses the `get_open_positions()` method to fetch and process all open positions for the given address.\n- **Market Data Integration**: Integrates with available market data to provide context and symbols for each open position.\n- **Leverage and Price Calculation**: Calculates key metrics for each open position, including entry price, leverage, mark price, and profit percentage (`_calculate_position_metrics()`).\n- **Oracle Price Integration**: Uses the `OraclePrices` class to retrieve recent oracle prices for calculating the mark price of a position.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nopen_positions: dict = OpenPositions(config=config).get_open_positions()\n```\n\n### OraclePrices Class\n\nThe `OraclePrices` class is responsible for fetching and processing the latest signed token prices from the RFX API for various blockchain networks. It integrates with the `ConfigManager` to configure the relevant API endpoint based on the blockchain network.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).\n- **Price Retrieval**: Uses the `get_recent_prices()` method to make a GET request to the RFX Oracle API and retrieve signed token prices.\n- **Request Handling**: Implements error handling for request failures (`_make_query()`) and validates the response format (`_process_output()`).\n- **Logging**: Logs the progress of requests and the processing of token prices.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nprices: dict = OraclePrices(config=config).get_recent_prices()\n```\n\n### PoolTVL Class\n\nThe `PoolTVL` class retrieves and calculates the Total Value Locked (TVL) in USD across all pools for a given blockchain. It uses data from oracle prices and a data store contract to determine the value of tokens in each pool.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Also initializes oracle price data and data store contract.\n- **TVL Calculation**: The `get_pool_balances()` method calculates the TVL for each pool by querying token balances and calculating their equivalent USD values.\n- **Oracle Price Integration**: Uses the `OraclePrices` class to fetch the most recent prices of tokens, which are then used to calculate USD values.\n- **Data Store Contract Integration**: Uses a Web3 contract to query the current token balances for both long and short positions in each pool.\n- **Logging and Data Saving**: Logs detailed TVL information for each market and saves the TVL data to JSON and/or CSV formats, if configured to do so.\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\npool_tvl_data: dict = PoolTVL(config=config).get_pool_balances()\n```\n\n### RPPrices Class\n\nThe `RPPrices` class is responsible for calculating Reward Pool (RP) prices for various market actions, such as withdrawal, deposit, and trading, in the blockchain ecosystem. It extends the `Data` class to use common market and token retrieval functionalities and processes market prices using contract queries.\n\n#### Key Features\n- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, a logging level (`log_level`), and initializes a reader contract to interact with the blockchain.\n- **Market Actions**: Provides methods to calculate RP prices for different actions:\n - `get_price_withdraw()`: Fetches RP prices for withdrawing from a liquidity pool.\n - `get_price_deposit()`: Fetches RP prices for depositing into a liquidity pool.\n - `get_price_traders()`: Fetches RP prices for traders.\n- **Multithreading**: Implements threading for price calculations to improve performance when querying multiple markets concurrently.\n- **Market Data Preparation**: Uses `_prepare_market_data()` to gather the relevant market addresses and token information needed for price queries.\n- **Data Processing**: Uses `_process_output()` to convert the raw outputs into a more structured and human-readable format.\n- **Data Saving**: Saves the processed RP prices to JSON or CSV formats if configured (`_save_output()`).\n\n#### Example Usage\n```sh\nconfig: ConfigManager = ConfigManager(...)\nrp_prices: dict = RPPrices(config=config).get_price_traders()\n```\n\n## Order Classes\n\n### DecreaseOrder Class\nThe DecreaseOrder class is used to manage and execute decrease orders (sell or close positions) on the RFX Exchange.\n\n#### Key Features\n- **Initialization:** Configures parameters such as market address, collateral, position size, slippage, and optional swap paths.\n- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract.\n- **Order Execution:** Builds and submits a decrease order with execution fees, acceptable prices, and price impact checks.\n- **Integration:** Utilizes market and oracle price data for accurate calculations.\n\n#### Example Usage\n```sh\norder = DecreaseOrder(\n config=config,\n market_address=market_address,\n collateral_address=collateral_address,\n index_token_address=index_token_address,\n is_long=False,\n size_delta=100,\n initial_collateral_delta=50,\n slippage_percent=0.05,\n debug_mode=True,\n)\norder.create_and_execute()\n```\n\n### IncreaseOrder Class\nThe IncreaseOrder class is used to manage and execute increase orders (buy or open positions) on the RFX Exchange.\n\n#### Key Features\n- **Initialization:** Configures parameters such as market address, collateral, position size, slippage, and optional swap paths.\n- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract.\n- **Order Execution:** Builds and submits an increase order with execution fees, acceptable prices, and price impact checks.\n- **Integration:** Utilizes market and oracle price data for accurate calculations.\n\n#### Example Usage\n```sh\norder = IncreaseOrder(\n config=config,\n market_address=market_address,\n collateral_address=collateral_address,\n index_token_address=index_token_address,\n is_long=True,\n size_delta=100,\n initial_collateral_delta=50,\n slippage_percent=0.05,\n debug_mode=True,\n)\norder.create_and_execute()\n```\n\n### DepositOrder Class\nThe DepositOrder class is used to manage and execute deposit orders in the RFX Exchange.\n\n#### Key Features\n- **Initialization:** Configures parameters such as market address, token addresses, and amounts for both long and short deposits.\n- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract for deposit operations.\n- **Integration:** Extends the base Deposit class to handle deposit-specific logic and operations.\n\n#### Example Usage\n```sh\norder = DepositOrder(\n config=config,\n market_address=market_address,\n initial_long_token_address=long_token_address,\n initial_short_token_address=short_token_address,\n long_token_amount=1000,\n short_token_amount=500,\n debug_mode=True,\n)\norder.create_and_execute()\n```\n\n\n### WithdrawOrder Class\nThe WithdrawOrder class is used to create and manage withdrawal orders in the RFX Exchange.\n\n#### Key Features\n- **Initialization:** Configures parameters such as market address, token address for withdrawal, and the amount of RP tokens to withdraw.\n- **Gas Limit Handling:** Determines appropriate gas limits using the datastore contract for withdrawal operations.\n- **Integration:** Extends the base Withdraw class to handle withdrawal-specific logic and operations.\n\n#### Example Usage\n```sh\norder = WithdrawOrder(\n config=config,\n market_address=market_address,\n out_token=out_token_address,\n rp_amount=1000,\n debug_mode=True,\n)\norder.create_and_execute()\n```\n\n### SwapOrder Class\nThe SwapOrder class is used to create and manage token swap orders in the RFX Exchange.\n\n#### Key Features\n- **Initialization:** Configures parameters such as token addresses, market details, swap path, slippage, and optional execution fees.\n- **Gas Limit Handling:** Determines appropriate gas limits for single or multiple swap operations using the datastore contract.\n- **Swap Estimation:** Includes functionality to estimate swap output and price impact based on token amounts and market data.\n- **Integration:** Extends the base Order class to handle swap-specific logic and operations.\n\n#### Example Usage\n```sh\norder = SwapOrder(\n config=config,\n start_token_address=start_token,\n out_token_address=out_token,\n market_address=market_address,\n collateral_address=collateral_address,\n index_token_address=index_token_address,\n initial_collateral_delta=1000,\n slippage_percent=0.01,\n swap_path=[start_token, out_token],\n debug_mode=True,\n)\norder.create_and_execute()\n```\n\n## Utils\n\n### ConfigManager Class\nThe ConfigManager class manages blockchain configuration settings, including RPC URLs, wallet addresses, chain information, and contract details.\n\n#### Key Features\n- **Initialization:** Sets up network configurations, user wallet details, and data storage options for a specified blockchain network.\n- **Contract Management:** Loads contract addresses and ABIs for network-specific contracts.\n- **Checksum Conversion:** Converts Ethereum addresses to checksum format for accuracy and compatibility.\n- **Environment Integration:** Supports fetching wallet addresses and private keys from environment variables.\n- **Data Saving Options:** Provides flags to enable saving output data to JSON or CSV formats.\n\n#### Example Usage\n```sh\nconfig = ConfigManager(\n chain=\"zkSync\",\n user_wallet_address=\"0xYourWalletAddress\",\n private_key=\"YourPrivateKey\",\n save_to_json=True,\n output_data_folder=\"./data\",\n)\nprint(config)\n```\n\n### CustomErrorParser Class\nThe CustomErrorParser class is designed to parse Solidity errors returned from blockchain transactions. It supports decoding errors based on ABI definitions, Panic codes, and standard error strings.\n\n#### Key Features\n- **ABI-Based Error Parsing:** Matches error bytes against the ABI to identify custom errors and decode parameters.\n- **Panic Code Decoding:** Parses Solidity Panic(uint256) errors and maps panic codes to descriptive messages.\n- **Standard Error Parsing:** Decodes Solidity Error(string) messages.\n- **Fallback Parsing:** Attempts to parse errors as generic strings when standard parsing fails.\n\n#### Example Usage\n```sh\nparser = CustomErrorParser(config=config)\nerror_bytes = \"0x12345678abcdef\" # Replace with actual error bytes\nparsed_error = parser.parse_error(error_bytes)\nprint(parsed_error)\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive Python SDK for interacting with RFX contracts and data.",
"version": "0.1.12",
"project_urls": {
"Documentation": "https://rfx.exchange",
"Homepage": "https://rfx.exchange",
"Repository": "https://github.com/relative-finance/pyrfx"
},
"split_keywords": [
"sdk",
" rfx",
" blockchain",
" python",
" defi",
" dex",
" exchange"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b200bc3ef2033f484609a99593da68cfa6ca89bfe3063c32faf4afcc0ab98c6",
"md5": "de89d64d1284fd2c85768a2f08a02567",
"sha256": "10d2d90b6b266be337869eaf9a3487d4063a4cf9c1a3363b2b8ce95496f541c0"
},
"downloads": -1,
"filename": "pyrfx-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de89d64d1284fd2c85768a2f08a02567",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 141799,
"upload_time": "2024-12-11T23:37:09",
"upload_time_iso_8601": "2024-12-11T23:37:09.794554Z",
"url": "https://files.pythonhosted.org/packages/5b/20/0bc3ef2033f484609a99593da68cfa6ca89bfe3063c32faf4afcc0ab98c6/pyrfx-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75b0ef7b955d49c7d7a91d24c6213f3128c8fb253a4d51cb007de0951c877cd6",
"md5": "586edb663861e51db876115fa162a66f",
"sha256": "b5b656d2bbb4237db6e8bcb833ea64ba4983382545770971a22f1600fa1fdeb9"
},
"downloads": -1,
"filename": "pyrfx-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "586edb663861e51db876115fa162a66f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 109218,
"upload_time": "2024-12-11T23:37:12",
"upload_time_iso_8601": "2024-12-11T23:37:12.643769Z",
"url": "https://files.pythonhosted.org/packages/75/b0/ef7b955d49c7d7a91d24c6213f3128c8fb253a4d51cb007de0951c877cd6/pyrfx-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-11 23:37:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "relative-finance",
"github_project": "pyrfx",
"github_not_found": true,
"lcname": "pyrfx"
}
JSON
