ruby-manager-web3 0.2.3

A Python package for Ruby Web3 interactions with POA blockchain

Here's the corrected README file with proper function call examples:

# 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

git clone https://github.com/rubyscan/rubyweb3-python.git
cd ruby-manager-web3
pip install -e .

Quick Start

Basic Setup

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

# 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

# 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.

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

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

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

# 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

# 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

# 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

# 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

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

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:

WEB3_PROVIDER_URL=https://bridge-rpc.rubyscan.io
PRIVATE_KEY=your_private_key_here
CHAIN_ID=18359

Custom Configuration

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
• 🐛 Issue Tracker
• 💬 Discussions

License

This project is licensed under the MIT License - see the 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.