ruby-manager-web3 0.2.3
A Python package for Ruby Web3 interactions with POA blockchain
License: MIT
Requires Python: >=3.8
Keywords: web3, blockchain, ruby, rubyscan

Here's the corrected README file with proper function call examples:

```markdown
# Ruby Manager Web3

A comprehensive Python package for Web3 interactions with Ruby, specifically designed for Ruby Chain.

## Features

- 💰 **Token Management**: Full RBC20 token support with balance checking and transfers
- 📊 **Event Listening**: Real-time blockchain event monitoring
- 🔐 **Wallet Management**: Create, recover, and manage wallets
- ⚡ **Gas Optimization**: Smart gas estimation and transaction management
- 🛡️ **Security**: Comprehensive input validation and error handling

## Installation

### From PyPI
```bash
pip install ruby-manager-web3
```

### From Source
```bash
git clone https://github.com/rubyscan/rubyweb3-python.git
cd ruby-manager-web3
pip install -e .
```

## Quick Start

### Basic Setup
```python
from ruby_manager_web3 import RubyWeb3Manager

# Initialize with Ruby Chain RPC
manager = RubyWeb3Manager(
    provider_url="https://bridge-rpc.rubyscan.io",
    chain_id=18359
)

# Check connection
if manager.is_connected:
    print("✅ Connected to Ruby Chain!")

# Get current block number
block_number = manager.get_block_number()
print(f"Current block: {block_number}")
```

### Wallet Management
```python
# Create a new wallet
wallet = manager.create_wallet()
print(f"New Address: {wallet['address']}")
print(f"Private Key: {wallet['private_key']}")

# Recover account from private key
recovered_wallet = manager.recover_account_from_private_key("your_private_key_here")
print(f"Recovered Address: {recovered_wallet['address']}")

# Set existing account for transactions
manager.set_account("your_private_key")
ruby_address = manager.get_ruby_address()
print(f"Your Address: {ruby_address}")

# Get balance
balance = manager.get_balance_ruby()
print(f"Balance: {balance} RUBY")
```

### Send Transactions
```python
# Send native coins (make sure account is set first)
manager.set_account("your_private_key")

tx_hash = manager.send_coin(
    to_address="RECIPIENT_ADDRESS_HERE",
    amount=1.5,  # 1.5 RUBY
    gas_limit=21000
)
print(f"Transaction sent: {tx_hash}")

# Wait for confirmation
receipt = manager.wait_for_transaction(tx_hash)
print(f"Transaction confirmed in block: {receipt['blockNumber']}")
```

## Core Components

### 1. RubyWeb3Manager - Main Manager
The main manager class for blockchain operations.

```python
from ruby_manager_web3 import RubyWeb3Manager

manager = RubyWeb3Manager("https://bridge-rpc.rubyscan.io")

# Network information
network_info = manager.get_network_info()
print(f"Chain ID: {network_info['chain_id']}")
print(f"Peer Count: {network_info['peer_count']}")

# Block operations
latest_block = manager.get_block_details('latest')
print(f"Block Hash: {latest_block['hash']}")

# Get multiple balances
addresses = ["0x742E6F70B975c0Dd51BcF91dE077E462a6E1882E", "0xANOTHER_ADDRESS"]
balances = manager.get_multiple_balances(addresses)
for address, balance in balances.items():
    print(f"{address}: {balance} RUBY")
```

### 2. Contract Interactions
```python
from ruby_manager_web3 import ContractManager

# Initialize contract manager
contract_manager = ContractManager(manager, contract_address="0xCONTRACT_ADDRESS", abi=contract_abi)

# Call contract view functions
result = contract_manager.call_function("balanceOf", "0xWALLET_ADDRESS")
print(f"Contract balance: {result}")

# Send contract transaction
tx_hash = contract_manager.send_transaction(
    "transfer", 
    "0xRECIPIENT", 
    1000000000000000000,  # 1 token in wei
    gas_limit=100000
)
print(f"Contract transaction: {tx_hash}")
```

### 3. Token Management
```python
from ruby_manager_web3 import TokenManager

token_manager = TokenManager(manager)

# Get token information
token_info = token_manager.get_token_info("0xTOKEN_CONTRACT_ADDRESS")
print(f"Token: {token_info.name} ({token_info.symbol})")
print(f"Decimals: {token_info.decimals}")

# Get token balance
balance = token_manager.get_token_balance(
    "0xTOKEN_CONTRACT_ADDRESS", 
    "0xYOUR_WALLET_ADDRESS"
)
print(f"Balance: {balance.readable_balance} {token_info.symbol}")

# Transfer tokens (account must be set first)
manager.set_account("your_private_key")
tx_hash = token_manager.transfer_token(
    token_address="0xTOKEN_CONTRACT_ADDRESS",
    to_address="0xRECIPIENT_ADDRESS",
    amount=100.0
)
print(f"Token transfer TX: {tx_hash}")
```

## Advanced Usage

### Contract Deployment
```python
# Deploy a new contract (account must be set first)
manager.set_account("your_private_key")

contract_abi = [...]  # Your contract ABI
contract_bytecode = "0x..."  # Your contract bytecode

tx_hash = manager.deploy_contract(
    abi=contract_abi,
    bytecode=contract_bytecode,
    args=[],  # Constructor arguments
    gas_limit=2000000
)

# Get deployed contract address
receipt = manager.wait_for_transaction(tx_hash)
contract_address = manager.get_contract_address_from_tx(tx_hash)
print(f"Contract deployed at: {contract_address}")
```

### Gas Management
```python
# Get gas estimate
gas_estimate = manager.get_gas_estimate(
    to_address="0xRECIPIENT_ADDRESS",
    value=1.0
)
print(f"Gas Limit: {gas_estimate.gas_limit}")
print(f"Gas Price: {gas_estimate.gas_price}")
print(f"Total Cost: {gas_estimate.total_cost_eth} RUBY")

# Cancel pending transaction
cancel_tx_hash = manager.cancel_transaction(nonce=5)
print(f"Cancel transaction: {cancel_tx_hash}")

# Speed up pending transaction
speed_tx_hash = manager.speed_up_transaction(nonce=5)
print(f"Speed up transaction: {speed_tx_hash}")
```

### Batch Operations
```python
# Send multiple transactions
manager.set_account("your_private_key")

transactions = [
    {'to': '0xADDRESS1', 'amount': 0.1},
    {'to': '0xADDRESS2', 'amount': 0.2},
    {'to': '0xADDRESS3', 'amount': 0.3}
]

tx_hashes = manager.send_batch_transactions(transactions)
for i, tx_hash in enumerate(tx_hashes):
    if tx_hash:
        print(f"Transaction {i+1}: {tx_hash}")
```

### Transaction History
```python
# Get transaction history for an address
transactions = manager.get_transaction_history(
    address="0xYOUR_ADDRESS",
    from_block=0,
    to_block='latest'
)

for tx in transactions:
    print(f"TX: {tx['hash']} - Block: {tx['blockNumber']} - Value: {tx.get('value', 0)}")
```

## Complete Example

```python
from ruby_manager_web3 import RubyWeb3Manager

def main():
    # Initialize manager
    manager = RubyWeb3Manager(
        provider_url="https://bridge-rpc.rubyscan.io",
        chain_id=18359
    )
    
    # Check connection
    if not manager.is_connected:
        print("❌ Not connected to Ruby Chain")
        return
    
    print("✅ Connected to Ruby Chain!")
    
    # Get network info
    network_info = manager.get_network_info()
    print(f"Chain ID: {network_info['chain_id']}")
    print(f"Block Number: {network_info['block_number']}")
    
    # Create a wallet
    wallet = manager.create_wallet()
    print(f"New wallet created:")
    print(f"  Address: {wallet['address']}")
    print(f"  Private Key: {wallet['private_key']}")
    
    # Recover wallet from private key
    recovered = manager.recover_account_from_private_key(wallet['private_key'])
    print(f"Recovered address: {recovered['address']}")
    
    # Get balance of an address
    balance = manager.get_balance_ruby("0x742E6F70B975c0Dd51BcF91dE077E462a6E1882E")
    print(f"Balance: {balance} RUBY")
    
    # Get latest block
    block = manager.get_block_details('latest')
    print(f"Latest block: {block['number']} with {len(block.get('transactions', []))} transactions")

if __name__ == "__main__":
    main()
```

## Error Handling

```python
from ruby_manager_web3 import RubyWeb3Error, TransactionError

try:
    tx_hash = manager.send_coin("0xINVALID_ADDRESS", 1.0)
except RubyWeb3Error as e:
    print(f"Error: {e}")
    
try:
    receipt = manager.wait_for_transaction("0xINVALID_HASH")
except TransactionError as e:
    print(f"Transaction error: {e}")

try:
    balance = manager.get_balance("0xINVALID_ADDRESS")
except Exception as e:
    print(f"Balance check failed: {e}")
```

## API Reference

### Core Methods

#### Wallet & Account
- `create_wallet()` - Create new wallet (returns address and private key)
- `set_account(private_key)` - Set account for transactions
- `recover_account_from_private_key(private_key)` - Recover address from private key
- `get_ruby_address()` - Get current account address in Ruby format

#### Blockchain Info
- `is_connected` - Check if connected to blockchain
- `get_block_number()` - Get current block number
- `get_network_info()` - Get comprehensive network information
- `get_block_details(block_identifier)` - Get block details
- `get_block_range(start_block, end_block)` - Get multiple blocks

#### Balance Operations
- `get_balance(address)` - Get balance in wei
- `get_balance_ruby(address)` - Get balance in RUBY
- `get_multiple_balances(addresses)` - Get balances for multiple addresses

#### Transaction Operations
- `send_coin(to_address, amount, gas_limit, gas_price, nonce, data)` - Send native coins
- `send_batch_transactions(transactions)` - Send multiple transactions
- `get_transaction_details(tx_hash)` - Get transaction details
- `get_transaction_receipt(tx_hash)` - Get transaction receipt
- `get_transaction_status(tx_hash)` - Get transaction status
- `wait_for_transaction(tx_hash)` - Wait for transaction confirmation
- `cancel_transaction(nonce)` - Cancel pending transaction
- `speed_up_transaction(nonce)` - Speed up pending transaction

#### Gas Operations
- `get_gas_price()` - Get current gas price
- `estimate_gas(to_address, value, data)` - Estimate gas for transaction
- `get_gas_estimate(to_address, value, data)` - Get comprehensive gas estimate

#### Contract Operations
- `deploy_contract(abi, bytecode, args, gas_limit, gas_price)` - Deploy new contract
- `get_contract_address_from_tx(tx_hash)` - Get contract address from deployment
- `get_code(address)` - Get contract code
- `is_contract_address(address)` - Check if address is a contract

## Configuration

### Environment Variables
Create a `.env` file:

```env
WEB3_PROVIDER_URL=https://bridge-rpc.rubyscan.io
PRIVATE_KEY=your_private_key_here
CHAIN_ID=18359
```

### Custom Configuration
```python
from ruby_manager_web3 import RubyWeb3Manager
import os
from dotenv import load_dotenv

load_dotenv()

manager = RubyWeb3Manager(
    provider_url=os.getenv('WEB3_PROVIDER_URL'),
    private_key=os.getenv('PRIVATE_KEY'),
    chain_id=int(os.getenv('CHAIN_ID', 18359)),
    timeout=30  # Request timeout in seconds
)
```

## Support

- 📚 [Documentation](https://github.com/rubyscan/rubyweb3-python/wiki)
- 🐛 [Issue Tracker](https://github.com/rubyscan/rubyweb3-python/issues)
- 💬 [Discussions](https://github.com/rubyscan/rubyweb3-python/discussions)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Note**: Always test with small amounts first and ensure you understand the transactions you're signing. Keep your private keys secure and never commit them to version control.
```