Metadata-Version: 2.4
Name: fastpluggy-crypto-daemon-sync
Version: 0.1.18
Summary: Synchronizes blockchain data from a core daemon for Fastpluggy
Author: FastPluggy Team
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: loguru
Requires-Dist: fastpluggy-tasks-worker>=0.2.45

# Crypto Daemon Sync Plugin

## Overview

The Crypto Daemon Sync plugin is a FastPluggy plugin designed to synchronize blockchain data from a core daemon. It provides functionality to track blockchain status, sync blocks and transactions, monitor watched addresses, and store raw blockchain data.

This plugin serves as a bridge between your FastPluggy application and a blockchain node, allowing you to:

- Monitor blockchain status (current and maximum block heights)
- Sync and store block and transaction data
- Track balances for specific addresses
- Explore blockchain data through comprehensive user interfaces
- Monitor and manage watched addresses

## Features

- **Blockchain Status Tracking**: Monitor the current and maximum block heights
- **Block and Transaction Syncing**: Sync and store blockchain data
- **Address Monitoring**: Track balances for specific addresses
- **Raw Data Storage**: Option to store raw block and transaction data
- **UI Integration**: View blockchain data through the FastPluggy UI
- **Block Explorer**: Browse and search blockchain blocks with detailed information
- **Transaction Explorer**: View and search transactions with input/output details
- **Address Monitoring Dashboard**: Add, remove, and monitor addresses with transaction history
- **Sync Status Dashboard**: Visual representation of sync progress with control options

## Installation

### Prerequisites

- FastPluggy framework
- Access to a blockchain node (core daemon)
- Required dependencies: tasks_worker (>=0.2.0), crud_tools (>=0.1.1)

### Installation Steps

1. Ensure the plugin is in your FastPluggy plugins directory:
   ```
   src/fastpluggy_plugin/crypto_deamon_sync/
   ```

2. Install the plugin dependencies:
   ```bash
   pip install -e src/fastpluggy_plugin/crypto_deamon_sync/
   ```

3. Configure the plugin in your FastPluggy configuration:
   ```python
   # In your FastPluggy configuration
   PLUGINS = [
       # ... other plugins
       "crypto_deamon_sync",
   ]
   ```

## Configuration

The plugin is configured through the `CoreDaemonSettings` class. You can customize these settings in your environment variables or configuration file:

- `CORE_DAEMON_URL`: URL of the blockchain core daemon
- `CORE_DAEMON_USERNAME`: Username for authentication (if required)
- `CORE_DAEMON_PASSWORD`: Password for authentication (if required)
- `SYNC_ENABLED`: Enable/disable automatic blockchain syncing
- `SAVE_RAW_DATA`: Enable/disable saving raw block and transaction data

## Usage

### Accessing the Plugin UI

Once installed, the plugin adds a "Crypto Sync" menu item to your FastPluggy application. From there, you can access:

1. **Main Dashboard**: Overview of blockchain status and navigation to other screens
2. **Chain Information**: Detailed information about the blockchain
3. **Mempool Information**: Current pending transactions
4. **Block Explorer**: Browse and search blockchain blocks
5. **Transaction Explorer**: View and search transactions
6. **Address Monitoring**: Manage watched addresses and view their balances
7. **Sync Status Dashboard**: Monitor and control the sync process

### Block Explorer

The Block Explorer allows you to:
- View a paginated list of synced blocks
- Search for blocks by height or hash
- View detailed information for a specific block
- See transactions within a block

### Transaction Explorer

The Transaction Explorer allows you to:
- View a list of transactions with filtering options
- Search for transactions by hash
- View detailed information for a specific transaction
- Examine inputs and outputs for transactions

### Address Monitoring

The Address Monitoring screen allows you to:
- View a list of watched addresses
- Add new addresses to watch
- Remove addresses from watching
- View balance history for addresses
- View transactions for a specific address

### Sync Status Dashboard

The Sync Status Dashboard provides:
- Visual representation of sync progress
- Statistics on synced blocks and transactions
- Control panel to start/stop sync process
- Configuration options for sync settings

### Programmatic Usage

You can also use the plugin programmatically in your FastPluggy application:

```python
from fastpluggy_plugin.crypto_deamon_sync.src.models import BlockchainStatus, WatchedAddress
from fastpluggy_plugin.crypto_deamon_sync.src.tasks.balance_sync import task_update_address_balance

# Get blockchain status
def get_blockchain_info():
    with session_scope() as session:
        status = session.query(BlockchainStatus).first()
        return status

# Add an address to watch
def add_watched_address(address):
    with session_scope() as session:
        watched = WatchedAddress(address=address)
        session.add(watched)
        session.commit()

    # Update the balance for this address
    task_update_address_balance(address)
```

## Troubleshooting

Common issues and their solutions:

1. **Connection Issues**: Ensure your blockchain node is running and accessible
2. **Sync Performance**: For large blockchains, consider adjusting sync settings
3. **Database Size**: Monitor database size when storing raw blockchain data

## Documentation

Detailed documentation is available in the `doc/` directory:

- `README.md`: This overview document
- `architecture.md`: Detailed architecture of the plugin
- `api.md`: API documentation
- `models.md`: Data model documentation
- `tasks.md`: Background tasks documentation
- `implementation_plan.md`: Implementation plan for features

## Support

For issues, feature requests, or contributions, please:

1. Check the documentation in the `doc/` directory
2. Submit issues through the project's issue tracker
3. Contribute improvements via pull requests
