Metadata-Version: 2.1
Name: abstract_bots
Version: 0.0.0.82
Summary: This suite of modules not only simplifies the complexities associated with blockchain application development but also ensures high levels of performance and security. By providing tools for detailed data handling, transaction analysis, and secure blockchain interactions, these modules form a comprehensive solution ideal for developers looking to build or maintain advanced Solana-based applications.
Home-page: https://github.com/AbstractEndeavors/abstract_ai
Author: putkoff
Author-email: partners@abstractendeavors.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: solders
Requires-Dist: solana
Requires-Dist: base58
Requires-Dist: sqlalchemy
Requires-Dist: abstract-security
Requires-Dist: python-dotenv
Requires-Dist: abstract-utilities

## Abstract Bots

The `abstract_bots.py` module provides a set of tools for managing file operations, JSON data handling, and various utility functions aimed at facilitating automation tasks, particularly in contexts that involve handling and manipulating data structures. Here’s a breakdown of its functionalities and how they can be utilized:

### Key Features of `abstract_bots.py`:

1. **JSON Utilities**:
   - `safe_json_loads`: Safely parse JSON data, with error handling to manage JSON decode errors.
   - `load_json_data`: Load JSON data from a file, with built-in error reporting for issues encountered during the read operation.

2. **Directory and File Management**:
   - `move_file`: Move files from one directory to another, with logging of the operation.
   - `secure_delete`: Safely delete files, with error handling and logging to ensure files are properly removed or warnings are issued if the file does not exist.
   - `make_directory`: Create directories as needed, ensuring they exist before proceeding with file operations.

3. **Data Retrieval and Transformation**:
   - `safe_get` and `safe_list`: Safely retrieve data from nested dictionaries and lists, reducing the risk of key errors and index errors.
   - `get_all_keys`: Recursively retrieve all keys from a nested dictionary, useful for debugging or data inspection.
   - `get_data`: Load data from a JSON file, utilizing `safe_read_from_json` to handle potential read errors.

4. **Data Normalization and Address Handling**:
   - `normalize_address`: Normalize blockchain addresses by removing common prefixes.
   - `serialize_all_addresses`: Serialize addresses using a custom function, potentially useful for preparing addresses for API calls or storage.

5. **Mathematical and Array Operations**:
   - `get_amount_dict`: Convert complex data structures into a simplified dictionary format, particularly useful for financial calculations where precision and decimal handling are crucial.
   - Various mathematical utilities (`exponential`, `divide_it`, `multiply_it`, etc.) to handle calculations with dynamic precision requirements.

### Usage Example:

Below is a simple example demonstrating how to use some of the functionalities in `abstract_bots.py` to load JSON data, perform file operations, and utilize utility functions:

```python
from abstract_bots import safe_json_loads, move_file, make_directory, get_percentage

# Load JSON data from a file
data = load_json_data('path_to_your_file.json')

# Perform a safe data retrieval
value = safe_get(data, ['key1', 'key2'])

# Move a file to a new directory
move_file('path_to_source_file', 'path_to_destination_directory')

# Ensure a directory exists
make_directory('path_to_new_directory')

# Calculate percentage
percentage = get_percentage(100, 200)
print(f"Percentage: {percentage}%")
```

### Best Practices:
- Utilize logging extensively to monitor the flow and errors, which is crucial for debugging and maintaining bots in production environments.
- Handle exceptions and errors gracefully to ensure that the bot's operations do not abruptly terminate, but rather handle errors and continue operation or shutdown gracefully.

This module serves as a foundation for building more complex automation and data management tasks, particularly in environments where robust error handling and file management are required.

---

## Abstract RPCs

The `abstract_rpcs.py` module contains a comprehensive collection of functions for handling remote procedure calls (RPCs), particularly focusing on blockchain technologies like Solana. It manages directories for storing API calls, fetches and caches responses, and processes asynchronous requests efficiently using threading.

### Key Features

1. **Singleton Pattern Implementation**:
   - `SingletonMeta`: A metaclass that ensures only one instance of a class is created, making it ideal for managing resources such as API connections or configurations.
   - `directoryStart`: Initializes directories for various data categories such as RPC calls, pool info, and blockchain data.

2. **RPC Call Management**:
   - `rpcCallManager`: Manages RPC calls, utilizing custom or client RPC endpoints. It handles JSON responses, formats requests, and retries failed requests with exponential backoff.

3. **Asynchronous and Concurrent Requests**:
   - Utilizes threading to handle concurrent API requests efficiently, reducing wait times and managing rate limits.

4. **Directory and File Management**:
   - Manages directories for different types of data, ensuring that responses and logs are organized and easily accessible.

5. **Error Handling and Logging**:
   - Robust error handling mechanisms to gracefully manage and log exceptions, ensuring the stability of the system.

6. **Utility Functions**:
   - Functions such as `get_all_signatures`, `get_account_info`, and `get_token_supply` to interact with the blockchain and fetch data as needed.

### Usage Example

Here's an example of how you might use the `rpcCallManager` to fetch transaction information for a specific blockchain signature:

```python
from abstract_rpcs import rpcCallManager

# Initialize RPC Manager with default settings
rpc_manager = rpcCallManager()

# Fetch transaction data using a Solana signature
signature = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpHGjqyt2k5zkj"
transaction_data = rpc_manager.get_transaction(signature)

# Output the fetched data
print(transaction_data)
```

### Advanced Usage

For handling high-throughput environments, such as trading platforms or data analysis tools, you can leverage the asynchronous features:

```python
from abstract_rpcs import assetRequestManager

# Initialize the asset request manager
asset_manager = assetRequestManager()

# Define a URL for the API endpoint
url = "https://api.dexscreener.com/latest/dex/tokens/solana"

# Perform an API call to fetch token data
token_data = asset_manager.dexscreener_api_call(url)

# Process and print the fetched token data
print(token_data)
```

### Conclusion

The `abstract_rpcs.py` module is well-equipped for developers needing robust and efficient tools to interact with blockchain networks, particularly those needing high reliability and performance for their applications. It combines advanced Python techniques with practical blockchain interaction requirements, providing a strong foundation for building sophisticated decentralized applications or data analysis tools.

---

## TX Functions

The `tx_functions.py` module in your project is designed for transaction-related functionalities, particularly for handling Solana blockchain transactions. This module provides a set of utilities for processing and analyzing transaction data, extracting balances, and managing changes in token balances. It is particularly useful for applications that require detailed transactional insights, such as wallets, exchanges, or financial tracking systems.

### Key Features of `tx_functions.py`

1. **Transaction Analysis**:
   - `get_solana_balances`: Extracts Solana token balances before and after transactions, calculating the change and organizing this data in a structured format.
   - `create_token_txns`: Analyzes token transactions to construct a detailed summary of token changes, including the addresses involved, the balance before and after the transaction, and the specific tokens changed.

2. **Utility Functions**:
   - `search_for_account_index` and `get_acct_index`: Retrieve specific transaction data by account index, useful for pinpointing information in transaction arrays.
   - `get_amount_dict`: Converts token amounts from raw transaction data into a more readable dictionary format, factoring in the token's decimal places for accurate representation.
   - `calculate_change`: Computes the difference in token amounts before and after transactions, essential for tracking transaction impacts.

3. **Data Extraction and Parsing**:
   - `get_account_keys`: Extracts account keys from transaction signatures, which is crucial for identifying transaction participants.
   - `parse_pool_data`: Parses log messages related to liquidity pools, extracting initialization parameters and other critical data for DeFi applications.

### Usage Example

Here’s how you might use the `get_solana_balances` function to fetch and print balance changes from a Solana transaction:

```python
from tx_functions import get_solana_balances

# Example transaction signature data
signature_data = {
    "preBalances": [100, 150, 200],
    "postBalances": [50, 175, 190],
    "accountKeys": ['address1', 'address2', 'address3']
}

# Fetch balance changes
balance_changes = get_solana_balances(signature_data)

# Print the balance changes
for txn in balance_changes['Address']:
    print(f"Address: {txn}")
    print(f"Balance Before: {balance_changes['Balance Before']}")
    print(f"Balance After: {balance_changes['Balance After']}")
    print(f"Change: {balance_changes['Change']}")
```

### Advanced Use Case

For financial tracking or audit systems, you can integrate these functions to monitor and report on token flows within the application, ensuring all transactions are recorded and analyzed for discrepancies or significant events.

```python
from tx_functions import get_all_txns

# Simulate receiving a complex signature data object
signature_data_complex = {
    # assuming complex structured data
}

# Process all transactions within the provided data
transaction_summary = get_all_txns(signature_data_complex)

# Output the processed transaction data for reporting or further analysis
print(transaction_summary)
```

### Conclusion

The `tx_functions.py` module is a powerful tool for developers working with blockchain technologies, providing essential functionalities for transaction data processing and analysis. This module is adaptable for use in a variety of applications, from simple wallet balance tracking to comprehensive financial analysis in DeFi platforms.

---

## Solana Client Manager

The `solana_client_manager.py` script provides a robust set of functionalities for interacting with the Solana blockchain, managing cryptographic keys, and performing transactions. This module leverages both the Solana Python client and the Solder library for cryptographic functions, enhancing security and efficiency. Below is an overview of the module's capabilities and how they integrate with blockchain operations.

### Key Features:

1. **Client Initialization**:
   - `get_client_rpc

` and `get_custom_rpc`: Configure RPC endpoints for interacting with the Solana blockchain, supporting both custom and default settings.
   - `get_custom_wss`: Sets up WebSocket endpoints for real-time blockchain data updates.

2. **Data Deserialization**:
   - `deserialize_data` and `deserialize_base64_data`: Functions to handle and decode data from base58 and base64 formats, respectively, crucial for transaction and block data processing.

3. **Keypair and Public Key Management**:
   - `load_from_private_key` and `load_keypair_from_file`: Load Solana keypairs for transaction signing and other blockchain operations.
   - `get_pub_key` and `pubkey_type`: Utility functions to handle and verify public keys, ensuring they are correctly formatted and valid.

4. **Token and Account Utilities**:
   - `get_token_balance_lamports_from_account` and `get_token_account_balance`: Fetch the balance of tokens in a specified account, important for financial operations and wallet management.
   - `get_mint_from_account`: Retrieves the mint address associated with a specific token account, useful for identifying and interacting with different tokens.

5. **Transaction Management**:
   - `send_transaction`: Asynchronously send transactions to the Solana network, handling all aspects of transaction preparation, signing, and submission.
   - `get_recent_blockhash`: Fetches the most recent blockhash, a necessary component for transaction validity on the Solana network.

6. **Query and RPC Operations**:
   - `get_accounts`, `get_token_supply`, and `get_owner`: Perform various RPC queries to retrieve detailed information about accounts, token supplies, and account ownership.

### Example Usage:

This example demonstrates how to initialize a Solana RPC client and fetch the balance of a token account:

```python
from solana_client_manager import get_client_rpc, get_token_account_balance

# Initialize the Solana RPC client
client = get_client_rpc(net_type="main")

# Define the public key of the token account
account_pubkey = "EnterTokenAccountPublicKeyHere"

# Fetch the balance of the specified token account
token_balance = get_token_account_balance(account_pubkey, client)
print(f"Token Balance: {token_balance} lamports")
```

### Advanced Use Case:

Integrating the module to handle a transaction on the Solana network could look like this:

```python
from solana_client_manager import get_client_rpc, send_transaction, load_keypair_from_file

# Load a keypair from a file
keypair = load_keypair_from_file('path_to_keypair_file.json')

# Initialize the client
client = get_client_rpc()

# Create a transaction instruction (not shown here for brevity)
transaction = create_transaction_instruction(keypair.pubkey(), "RecipientPublicKeyHere", amount)

# Send the transaction
response = await send_transaction(transaction, [keypair], client)
print(f"Transaction response: {response}")
```

### Conclusion:

`solana_client_manager.py` is a critical module for applications that require direct interaction with the Solana blockchain. It provides all necessary tools to securely manage accounts, perform transactions, and retrieve blockchain data, making it ideal for developers building Solana-based applications or services.

---

## Comprehensive Overview of Solana Management Modules

The suite of Solana management modules—`abstract_bots.py`, `abstract_rpcs.py`, `tx_functions.py`, and `solana_client_manager.py`—provides a robust framework for blockchain application development, focusing on automation, data handling, transaction processing, and blockchain interaction. These modules are designed to facilitate seamless integration with the Solana blockchain, enhancing both the efficiency and security of operations.

### Key Functionalities Across Modules

1. **Blockchain Interaction and RPC Handling (`abstract_rpcs.py` & `solana_client_manager.py`)**:
   - Configure and manage RPC endpoints for real-time data fetching and transaction submissions.
   - Handle asynchronous requests and manage threading for concurrent operations to improve performance and response times.
   - Detailed logging and error handling to ensure robust application behavior and easier troubleshooting.

2. **Data Handling and Transaction Processing (`abstract_bots.py` & `tx_functions.py`)**:
   - Extensive JSON utilities for data parsing and error handling, crucial for processing blockchain transaction data.
   - Advanced file and directory management tools to organize logs, transactions data, and API responses.
   - Transaction analysis tools to extract, compute, and manage changes in token balances from transaction data.

3. **Cryptography and Security (`solana_client_manager.py`)**:
   - Manage cryptographic keys for secure transaction signing.
   - Utilities for validating and processing public keys and addresses, ensuring secure and accurate blockchain operations.

4. **Utility and Helper Functions (`abstract_bots.py` & `tx_functions.py`)**:
   - Generic utilities to normalize blockchain addresses, serialize data, and perform mathematical calculations.
   - Functions to fetch account information, token supplies, and manage account balances, providing a comprehensive toolkit for Solana-based financial applications.

### Example Usage Scenario

Below is an integrated example showing how these modules can work together to perform a typical blockchain operation—fetching and processing transaction data, and submitting a transaction on the Solana blockchain:

```python
from abstract_rpcs import rpcCallManager
from tx_functions import get_solana_balances
from solana_client_manager import get_client_rpc, send_transaction, load_keypair_from_file

# Initialize RPC Manager and Solana Client
rpc_manager = rpcCallManager()
client = get_client_rpc(net_type="main")

# Example: Fetch transaction data using a Solana signature
signature = "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpHGjqyt2k5zkj"
transaction_data = rpc_manager.get_transaction(signature)

# Process the fetched transaction data to analyze token balances
balance_changes = get_solana_balances(transaction_data)

# Load a keypair for transaction signing and send a new transaction
keypair = load_keypair_from_file('path_to_keypair_file.json')
transaction = create_transaction_instruction(keypair.pubkey(), "RecipientPublicKeyHere", amount)
response = await send_transaction(transaction, [keypair], client)

# Output processed data and transaction response
print(balance_changes)
print(f"Transaction response: {response}")
```

### Conclusion

This suite of modules not only simplifies the complexities associated with blockchain application development but also ensures high levels of performance and security. By providing tools for detailed data handling, transaction analysis, and secure blockchain interactions, these modules form a comprehensive solution ideal for developers looking to build or maintain advanced Solana-based applications.
