solver-multirpc 3.1.4__tar.gz

solver_multirpc-3.1.4/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.3
+Name: solver-multirpc
+Version: 3.1.4
+Summary: A robust Python library for interacting with Ethereum smart contracts via multiple RPC endpoints, ensuring reliability, availability, and load distribution with automatic retries on failure.
+License: MIT
+Author: rorschach
+Author-email: rorschach45001@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: eth-account (>=0.13.0)
+Requires-Dist: multicallable (>=6.0.0)
+Requires-Dist: web3 (>7.0.0)
+Description-Content-Type: text/markdown
+
+# solver-MultiRpc: Reliable Ethereum Interactions with Multiple RPCs
+
+`solver-MultiRpc` is a robust library designed to interact with Ethereum smart contracts
+using multiple RPC endpoints. This ensures reliability and availability
+by distributing the load across various endpoints and retrying operations on failure.
+The library provides both asynchronous (`AsyncMultiRpc`) and
+synchronous (`MultiRpc`) interfaces to suit different use cases.
+
+## Features
+
+- **Multiple RPC Support**: Seamlessly switch between different RPCs to ensure uninterrupted interactions.
+- **Gas Management**: Fetch gas prices from multiple sources to ensure transactions are sent with an appropriate fee.
+- **Robust Error Handling**: Designed to handle failures gracefully, increasing the reliability of your applications.
+- **Easy-to-use API**: Interact with Ethereum smart contracts using a simple and intuitive API.
+
+## Installation
+
+Install `solver-MultiRpc` using pip:
+
+```bash
+pip install solver-multiRPC
+```
+
+## Quick Start
+
+Here's a quick example to get you started:
+
+### Asynchronous Usage
+
+Below is an example of how to use the AsyncMultiRpc class for asynchronous operations:
+
+```python
+import asyncio
+import json
+from src.multirpc.utils import NestedDict
+from multirpc import AsyncMultiRpc
+
+
+async def main():
+    rpcs = NestedDict({
+        "view": {
+            1: ['https://1rpc.io/ftm', 'https://rpcapi.fantom.network', 'https://rpc3.fantom.network'],
+            2: ['https://rpc.fantom.network', 'https://rpc2.fantom.network', ],
+            3: ['https://rpc.ankr.com/fantom'],
+        },
+        "transaction": {
+            1: ['https://1rpc.io/ftm', 'https://rpcapi.fantom.network', 'https://rpc3.fantom.network'],
+            2: ['https://rpc.fantom.network', 'https://rpc2.fantom.network', ],
+            3: ['https://rpc.ankr.com/fantom'],
+        }
+    })
+    with open("abi.json", "r") as f:
+        abi = json.load(f)
+    multi_rpc = AsyncMultiRpc(rpcs, 'YOUR_CONTRACT_ADDRESS', contract_abi=abi, enable_estimate_gas_limit=True)
+    multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+
+    result = await multi_rpc.functions.YOUR_FUNCTION().call()
+    print(result)
+
+
+asyncio.run(main())
+```
+
+### Synchronous Usage
+
+Below is an example of how to use the MultiRpc class for synchronous operations:
+
+```python
+from multirpc import MultiRpc
+
+
+def main():
+    multi_rpc = MultiRpc(rpcs, 'YOUR_CONTRACT_ADDRESS', contract_abi=abi, enable_estimate_gas_limit=True)
+    multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+
+    result = multi_rpc.functions.YOUR_FUNCTION().call()
+    print(result)
+
+
+main()
+```
+
+Replace placeholders like `YOUR_CONTRACT_ADDRESS`, `YOUR_PUBLIC_ADDRESS`, `YOUR_PRIVATE_KEY`, and `YOUR_FUNCTION` with
+appropriate values.
+
+## Documentation
+
+### Initialization
+
+Initialize the `MultiRpc` class with your RPC URLs, contract address, and contract ABI:
+
+```python
+multi_rpc = MultiRpc(rpcs, contract_address='YOUR_CONTRACT_ADDRESS', contract_abi=abi)
+```
+- `enable_estimate_gas_limit=True` will check if tx can be done successfully without paying fee, 
+and also calculate gas limit for tx
+- You can pass a list of RPCs to `rpcs_supporting_tx_trace=[]` to identify which of the provided RPCs (`rpcs`) support `tx_trace`. 
+Then, when a transaction fails, you can retrieve the trace of the transaction.
+
+### Setting Account
+
+Set the Ethereum account details (address and private key) for sending transactions:
+
+```python
+multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+```
+
+### Calling Contract Functions
+
+Call a function from your contract:
+
+```python
+result = await multi_rpc.functions.YOUR_FUNCTION().call()
+```
+By default we return tx_receipt(wait for 90 second).
+if you don't want to return tx_receipt, pass `wait_for_receipt=0` to `call()` 
+
+### Calling Contract with another Private Key
+
+You can call a transaction function with a different private key by passing the
+`private_key`, `address` parameter to the `call()` method. Here’s an example:
+
+```python
+result = await multi_rpc.functions.YOUR_FUNCTION().call(address=PublicKey, private_key=PrivateKey)
+```
+
+### Using Block Identifier in Calls
+
+You can specify a block identifier when calling view functions to get the state of the
+contract at a specific block. Here's an example:
+
+_Note that the majority of free RPCs only support querying blocks up to 10 minutes earlier._
+
+```python
+# You can use 'latest', 'earliest', or a specific block number
+result = multi_rpc.functions.yourViewFunction().call(block_identifier='latest')  
+```
+
+### Using multicall for view function Calls
+
+you can also use `mutlicall()` for calling a view function multiple time with different parameters. Here's an example:
+
+```python
+results = multi_rpc.functions.yourViewFunction([(param1, params2), (param1, params2)]).multicall()  
+```
+
+### Passing View Policy
+
+You can specify a view policy to determine how view function calls are handled.
+The available view policies are `MostUpdated` and `FirstSuccess`. Here’s an example:
+
+```python
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, view_policy=ViewPolicy.FirstSuccess)
+```
+
+### Passing Gas Estimation to MultiRpc
+
+You can pass a `GasEstimation` object to the `MultiRpc` or `AsyncMultiRpc` class
+to configure how gas prices are estimated. Here is an example of how to do this:
+
+```python
+from multirpc import MultiRpc, GasEstimation, GasEstimationMethod
+
+gas_estimation = GasEstimation(
+    chain_id=1,  # Mainnet
+    providers=[],  # List of AsyncWeb3 providers
+    default_method=GasEstimationMethod.GAS_API_PROVIDER,
+    gas_api_provider='https://gasstation-mainnet.matic.network'  # Replace with your API provider
+)
+
+# Pass the GasEstimation object to MultiRpc
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, gas_estimation=gas_estimation)
+```
+
+The `GasEstimation` class allows you to implement a custom gas estimation method.
+You need to extend the `GasEstimation` class and override the _`custom_gas_estimation` method with your custom logic.
+Here is an example:
+
+```python
+from multirpc import GasEstimation, TxPriority, GasEstimationMethod
+from web3 import Web3
+from web3.types import Wei
+
+
+class CustomGasEstimation(GasEstimation):
+
+    async def _custom_gas_estimation(self, priority: TxPriority, gas_upper_bound: float) -> dict:
+        # Your custom gas estimation logic here
+        custom_gas_price = 50  # Replace with your custom logic
+        if custom_gas_price > gas_upper_bound:
+            raise OutOfRangeTransactionFee(f"Custom gas price {custom_gas_price} exceeds upper bound {gas_upper_bound}")
+        return {
+            "gasPrice": Web3.to_wei(custom_gas_price, 'gwei')
+        }
+
+
+# Create an instance of your custom gas estimation
+custom_gas_estimation = CustomGasEstimation(
+    chain_id=1,
+    providers=[],
+    default_method=GasEstimationMethod.CUSTOM,
+)
+
+# Use it with MultiRpc
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, gas_estimation=custom_gas_estimation)
+```
+
+You can specify which gas estimation method in `call()` method. Here's an example:
+
+```python
+tx_hash = multi_rpc.functions.yourTransactionFunction().call(
+    gas_estimation_method=GasEstimationMethod.RPC,  # Specify the gas estimation method
+)
+```
+
+By default, we check all possible ways(api, rpc, fixed, custom) to get `gasPrice`.
+but, if you pass method we only use passed method
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on our GitHub repository.
+

solver_multirpc-3.1.4/README.md

@@ -0,0 +1,221 @@
+# solver-MultiRpc: Reliable Ethereum Interactions with Multiple RPCs
+
+`solver-MultiRpc` is a robust library designed to interact with Ethereum smart contracts
+using multiple RPC endpoints. This ensures reliability and availability
+by distributing the load across various endpoints and retrying operations on failure.
+The library provides both asynchronous (`AsyncMultiRpc`) and
+synchronous (`MultiRpc`) interfaces to suit different use cases.
+
+## Features
+
+- **Multiple RPC Support**: Seamlessly switch between different RPCs to ensure uninterrupted interactions.
+- **Gas Management**: Fetch gas prices from multiple sources to ensure transactions are sent with an appropriate fee.
+- **Robust Error Handling**: Designed to handle failures gracefully, increasing the reliability of your applications.
+- **Easy-to-use API**: Interact with Ethereum smart contracts using a simple and intuitive API.
+
+## Installation
+
+Install `solver-MultiRpc` using pip:
+
+```bash
+pip install solver-multiRPC
+```
+
+## Quick Start
+
+Here's a quick example to get you started:
+
+### Asynchronous Usage
+
+Below is an example of how to use the AsyncMultiRpc class for asynchronous operations:
+
+```python
+import asyncio
+import json
+from src.multirpc.utils import NestedDict
+from multirpc import AsyncMultiRpc
+
+
+async def main():
+    rpcs = NestedDict({
+        "view": {
+            1: ['https://1rpc.io/ftm', 'https://rpcapi.fantom.network', 'https://rpc3.fantom.network'],
+            2: ['https://rpc.fantom.network', 'https://rpc2.fantom.network', ],
+            3: ['https://rpc.ankr.com/fantom'],
+        },
+        "transaction": {
+            1: ['https://1rpc.io/ftm', 'https://rpcapi.fantom.network', 'https://rpc3.fantom.network'],
+            2: ['https://rpc.fantom.network', 'https://rpc2.fantom.network', ],
+            3: ['https://rpc.ankr.com/fantom'],
+        }
+    })
+    with open("abi.json", "r") as f:
+        abi = json.load(f)
+    multi_rpc = AsyncMultiRpc(rpcs, 'YOUR_CONTRACT_ADDRESS', contract_abi=abi, enable_estimate_gas_limit=True)
+    multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+
+    result = await multi_rpc.functions.YOUR_FUNCTION().call()
+    print(result)
+
+
+asyncio.run(main())
+```
+
+### Synchronous Usage
+
+Below is an example of how to use the MultiRpc class for synchronous operations:
+
+```python
+from multirpc import MultiRpc
+
+
+def main():
+    multi_rpc = MultiRpc(rpcs, 'YOUR_CONTRACT_ADDRESS', contract_abi=abi, enable_estimate_gas_limit=True)
+    multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+
+    result = multi_rpc.functions.YOUR_FUNCTION().call()
+    print(result)
+
+
+main()
+```
+
+Replace placeholders like `YOUR_CONTRACT_ADDRESS`, `YOUR_PUBLIC_ADDRESS`, `YOUR_PRIVATE_KEY`, and `YOUR_FUNCTION` with
+appropriate values.
+
+## Documentation
+
+### Initialization
+
+Initialize the `MultiRpc` class with your RPC URLs, contract address, and contract ABI:
+
+```python
+multi_rpc = MultiRpc(rpcs, contract_address='YOUR_CONTRACT_ADDRESS', contract_abi=abi)
+```
+- `enable_estimate_gas_limit=True` will check if tx can be done successfully without paying fee, 
+and also calculate gas limit for tx
+- You can pass a list of RPCs to `rpcs_supporting_tx_trace=[]` to identify which of the provided RPCs (`rpcs`) support `tx_trace`. 
+Then, when a transaction fails, you can retrieve the trace of the transaction.
+
+### Setting Account
+
+Set the Ethereum account details (address and private key) for sending transactions:
+
+```python
+multi_rpc.set_account("YOUR_PUBLIC_ADDRESS", "YOUR_PRIVATE_KEY")
+```
+
+### Calling Contract Functions
+
+Call a function from your contract:
+
+```python
+result = await multi_rpc.functions.YOUR_FUNCTION().call()
+```
+By default we return tx_receipt(wait for 90 second).
+if you don't want to return tx_receipt, pass `wait_for_receipt=0` to `call()` 
+
+### Calling Contract with another Private Key
+
+You can call a transaction function with a different private key by passing the
+`private_key`, `address` parameter to the `call()` method. Here’s an example:
+
+```python
+result = await multi_rpc.functions.YOUR_FUNCTION().call(address=PublicKey, private_key=PrivateKey)
+```
+
+### Using Block Identifier in Calls
+
+You can specify a block identifier when calling view functions to get the state of the
+contract at a specific block. Here's an example:
+
+_Note that the majority of free RPCs only support querying blocks up to 10 minutes earlier._
+
+```python
+# You can use 'latest', 'earliest', or a specific block number
+result = multi_rpc.functions.yourViewFunction().call(block_identifier='latest')  
+```
+
+### Using multicall for view function Calls
+
+you can also use `mutlicall()` for calling a view function multiple time with different parameters. Here's an example:
+
+```python
+results = multi_rpc.functions.yourViewFunction([(param1, params2), (param1, params2)]).multicall()  
+```
+
+### Passing View Policy
+
+You can specify a view policy to determine how view function calls are handled.
+The available view policies are `MostUpdated` and `FirstSuccess`. Here’s an example:
+
+```python
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, view_policy=ViewPolicy.FirstSuccess)
+```
+
+### Passing Gas Estimation to MultiRpc
+
+You can pass a `GasEstimation` object to the `MultiRpc` or `AsyncMultiRpc` class
+to configure how gas prices are estimated. Here is an example of how to do this:
+
+```python
+from multirpc import MultiRpc, GasEstimation, GasEstimationMethod
+
+gas_estimation = GasEstimation(
+    chain_id=1,  # Mainnet
+    providers=[],  # List of AsyncWeb3 providers
+    default_method=GasEstimationMethod.GAS_API_PROVIDER,
+    gas_api_provider='https://gasstation-mainnet.matic.network'  # Replace with your API provider
+)
+
+# Pass the GasEstimation object to MultiRpc
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, gas_estimation=gas_estimation)
+```
+
+The `GasEstimation` class allows you to implement a custom gas estimation method.
+You need to extend the `GasEstimation` class and override the _`custom_gas_estimation` method with your custom logic.
+Here is an example:
+
+```python
+from multirpc import GasEstimation, TxPriority, GasEstimationMethod
+from web3 import Web3
+from web3.types import Wei
+
+
+class CustomGasEstimation(GasEstimation):
+
+    async def _custom_gas_estimation(self, priority: TxPriority, gas_upper_bound: float) -> dict:
+        # Your custom gas estimation logic here
+        custom_gas_price = 50  # Replace with your custom logic
+        if custom_gas_price > gas_upper_bound:
+            raise OutOfRangeTransactionFee(f"Custom gas price {custom_gas_price} exceeds upper bound {gas_upper_bound}")
+        return {
+            "gasPrice": Web3.to_wei(custom_gas_price, 'gwei')
+        }
+
+
+# Create an instance of your custom gas estimation
+custom_gas_estimation = CustomGasEstimation(
+    chain_id=1,
+    providers=[],
+    default_method=GasEstimationMethod.CUSTOM,
+)
+
+# Use it with MultiRpc
+multi_rpc = MultiRpc(rpc_urls, contract_address, contract_abi, gas_estimation=custom_gas_estimation)
+```
+
+You can specify which gas estimation method in `call()` method. Here's an example:
+
+```python
+tx_hash = multi_rpc.functions.yourTransactionFunction().call(
+    gas_estimation_method=GasEstimationMethod.RPC,  # Specify the gas estimation method
+)
+```
+
+By default, we check all possible ways(api, rpc, fixed, custom) to get `gasPrice`.
+but, if you pass method we only use passed method
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on our GitHub repository.

solver_multirpc-3.1.4/pyproject.toml

@@ -0,0 +1,21 @@
+[tool.poetry]
+name = "solver-multirpc"
+version = "3.1.4"
+description = "A robust Python library for interacting with Ethereum smart contracts via multiple RPC endpoints, ensuring reliability, availability, and load distribution with automatic retries on failure."
+authors = ["rorschach <rorschach45001@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [
+  { include = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+web3 = ">7.0.0"
+multicallable = ">=6.0.0"
+eth-account = ">=0.13.0"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

solver_multirpc-3.1.4/src/multirpc/__init__.py

@@ -0,0 +1 @@
+from .base_multi_rpc_interface import BaseMultiRpc

solver_multirpc-3.1.4/src/multirpc/async_multi_rpc_interface.py

@@ -0,0 +1,125 @@
+import asyncio
+import logging
+from typing import Dict, List, Optional, Union
+
+from eth_typing import Address, ChecksumAddress
+from web3._utils.contracts import encode_transaction_data  # noqa
+from web3.types import BlockData, BlockIdentifier, TxReceipt
+
+from . import BaseMultiRpc
+from .base_multi_rpc_interface import BaseContractFunction
+from .constants import GasLimit, GasUpperBound, ViewPolicy
+from .exceptions import DontHaveThisRpcType, KwargsNotSupportedInMultiCall, TransactionTypeNotSupportedInMultiCall
+from .gas_estimation import GasEstimation, GasEstimationMethod
+from .utils import ContractFunctionType, NestedDict, TxPriority, thread_safe
+
+
+class AsyncMultiRpc(BaseMultiRpc):
+    """
+    This class is used to be more sure when running web3 view calls and sending transactions by using of multiple RPCs.
+    """
+
+    @thread_safe
+    def __init__(
+            self,
+            rpc_urls: NestedDict,
+            contract_address: Union[Address, ChecksumAddress, str],
+            contract_abi: Dict,
+            rpcs_supporting_tx_trace: Optional[List[str]] = None,
+            view_policy: ViewPolicy = ViewPolicy.MostUpdated,
+            gas_estimation: Optional[GasEstimation] = None,
+            gas_limit: int = GasLimit,
+            gas_upper_bound: int = GasUpperBound,
+            apm=None,
+            enable_estimate_gas_limit: bool = False,
+            is_proof_authority: bool = False,
+            multicall_custom_address: str = None,
+            log_level: logging = logging.WARN,
+            setup_on_init: bool = True
+    ):
+        super().__init__(rpc_urls, contract_address, contract_abi, rpcs_supporting_tx_trace,
+                         view_policy, gas_estimation, gas_limit,
+                         gas_upper_bound, apm, enable_estimate_gas_limit,
+                         is_proof_authority, multicall_custom_address, log_level)
+
+        for func_abi in self.contract_abi:
+            if func_abi.get("stateMutability") in ("view", "pure"):
+                function_type = ContractFunctionType.View
+            elif func_abi.get("type") == "function":
+                function_type = ContractFunctionType.Transaction
+            else:
+                continue
+            self.functions.__setattr__(
+                func_abi["name"],
+                self.ContractFunction(func_abi["name"], func_abi, self, function_type),
+            )
+        if setup_on_init:
+            asyncio.run(self.setup())
+
+    async def get_nonce(self, address: Union[Address, ChecksumAddress, str]) -> int:
+        return await super()._get_nonce(address)
+
+    async def get_tx_receipt(self, tx_hash) -> TxReceipt:
+        return await super().get_tx_receipt(tx_hash)
+
+    async def get_block(self, block_identifier: BlockIdentifier = 'latest',
+                        full_transactions: bool = False) -> BlockData:
+        return await super().get_block(block_identifier, full_transactions)
+
+    async def get_block_number(self) -> int:
+        return await super().get_block_number()
+
+    class ContractFunction(BaseContractFunction):
+        def __call__(self, *args, **kwargs):
+            cf = AsyncMultiRpc.ContractFunction(self.name, self.abi, self.mr, self.typ)
+            cf.args = args
+            cf.kwargs = kwargs
+            return cf
+
+        async def call(
+                self,
+                address: str = None,
+                private_key: str = None,
+                gas_limit: int = None,
+                gas_upper_bound: int = None,
+                wait_for_receipt: int = 90,
+                priority: TxPriority = TxPriority.Low,
+                gas_estimation_method: GasEstimationMethod = None,
+                block_identifier: Union[str, int] = 'latest',
+                enable_estimate_gas_limit: Optional[bool] = None,
+        ):
+            if self.mr.providers.get(self.typ) is None:
+                raise DontHaveThisRpcType(f"Doesn't have {self.typ} RPCs")
+            if self.typ == ContractFunctionType.View:
+                return await self.mr._call_view_function(
+                    self.name, block_identifier, False, *self.args, **self.kwargs,
+                )
+            elif self.typ == ContractFunctionType.Transaction:
+                return await self.mr._call_tx_function(
+                    func_name=self.name,
+                    func_args=self.args,
+                    func_kwargs=self.kwargs,
+                    address=address or self.mr.address,
+                    private_key=private_key or self.mr.private_key,
+                    gas_limit=gas_limit or self.mr.gas_limit,
+                    gas_upper_bound=gas_upper_bound or self.mr.gas_upper_bound,
+                    wait_for_receipt=wait_for_receipt,
+                    priority=priority,
+                    gas_estimation_method=gas_estimation_method,
+                    enable_estimate_gas_limit=enable_estimate_gas_limit
+                )
+
+        async def multicall(
+                self,
+                block_identifier: Union[str, int] = 'latest',
+        ):
+            if self.mr.providers.get(self.typ) is None:
+                raise DontHaveThisRpcType(f"Doesn't have {self.typ} RPCs")
+            if self.kwargs != {}:
+                raise KwargsNotSupportedInMultiCall
+            if self.typ == ContractFunctionType.View:
+                return await self.mr._call_view_function(
+                    self.name, block_identifier, True, *self.args, **self.kwargs,
+                )
+            elif self.typ == ContractFunctionType.Transaction:
+                raise TransactionTypeNotSupportedInMultiCall