rubyweb3.Web3TransactionLibrary 1.1.5

Here's the updated README.md file with comprehensive documentation for all the functions in your TransactionService.cs:

Web3TransactionLibrary Documentation

A comprehensive .NET library for Ruby blockchain interactions with Ruby-style address formatting support.

Installation

dotnet add package rubyweb3.Web3TransactionLibrary --version 1.1.3

Quick Start

1. Service Registration

using Microsoft.Extensions.DependencyInjection;
using Web3TransactionLibrary.Extensions;

// Basic registration
services.AddWeb3TransactionService("https://bridge-rpc.rubyscan.io", "rYOUR_PRIVATE_KEY");

// With custom logger
services.AddWeb3TransactionService(
    "https://bridge-rpc.rubyscan.io", 
    "rYOUR_PRIVATE_KEY", 
    logger);

// Register wallet services
services.AddRubyWeb3Services();

Core Features

Basic Transactions

Send Transaction

public async Task SendRUBY()
{
    // Send 0.1 RUBY to a Ruby-formatted address
    string transactionHash = await _transactionService.SendTransactionAsync(
        "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6", // Ruby format address
        1000000000000000000, // Amount in RUBY
        25 // Gas price in Gwei (optional, default: 20)
    );
    
    Console.WriteLine($"Transaction sent: {transactionHash}");
}

Get Balance

// Get simple balance
decimal balance = await _transactionService.GetBalanceAsync("r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6");
Console.WriteLine($"Balance: {balance} RUBY");

// Get detailed balance information
var detailedBalance = await _transactionService.GetBalanceDetailedAsync("r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6");
Console.WriteLine($"Address: {detailedBalance.Address}");
Console.WriteLine($"Balance: {detailedBalance.Balance} {detailedBalance.Unit}");
Console.WriteLine($"Retrieved at: {detailedBalance.RetrievedAt}");

Transaction Information

// Get transaction data
var transactionData = await _transactionService.GetTransactionDataAsync(
    "r9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6"
);
Console.WriteLine($"From: {transactionData.FromAddress}");
Console.WriteLine($"To: {transactionData.ToAddress}");
Console.WriteLine($"Value: {transactionData.Value} RUBY");
Console.WriteLine($"Status: {transactionData.Status}");
Console.WriteLine($"Block: {transactionData.BlockNumber}");

// Get raw transaction receipt
var receipt = await _transactionService.GetTransactionReceiptAsync(transactionHash);
Console.WriteLine($"Gas used: {receipt.GasUsed?.Value}");
Console.WriteLine($"Block hash: {receipt.BlockHash}");

Wait for Transaction Confirmation

var txHash = await _transactionService.SendTransactionAsync(toAddress, amount);
var receipt = await _transactionService.WaitForTransactionReceiptAsync(txHash, 60); // 60 second timeout
if (receipt.Status?.Value == 1)
{
    Console.WriteLine("Transaction confirmed successfully!");
}

Smart Contract Interactions

Contract Deployment

string bytecode = "0x606060..."; // Your contract bytecode
string abi = "[{...}]"; // Your contract ABI
string contractAddress = await _transactionService.DeployContractAsync(bytecode, abi);
Console.WriteLine($"Contract deployed at: {contractAddress}");

Reading from Contracts (View Functions)

Simple String Return

// Call functions that return strings (name, symbol, etc.)
string tokenName = await _transactionService.CallContractAsync(
    contractAddress, 
    abi, 
    "name"
);
Console.WriteLine($"Token Name: {tokenName}");

string tokenSymbol = await _transactionService.CallContractAsync(
    contractAddress, 
    abi, 
    "symbol"
);
Console.WriteLine($"Token Symbol: {tokenSymbol}");

Typed Return Values

using System.Numerics;

// For numeric returns (balance, totalSupply, etc.)
BigInteger totalSupply = await _transactionService.CallContractFunctionAsync<BigInteger>(
    contractAddress, 
    abi, 
    "totalSupply"
);
Console.WriteLine($"Total Supply: {totalSupply}");

// With parameters
BigInteger balance = await _transactionService.CallContractFunctionAsync<BigInteger>(
    contractAddress, 
    abi, 
    "balanceOf",
    "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6" // Ruby address
);
Console.WriteLine($"Balance: {balance}");

Enhanced Typed Calls

var callRequest = new ContractCallRequest
{
    ContractAddress = contractAddress,
    Abi = abi,
    FunctionName = "balanceOf",
    Parameters = new object[] { "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6" }
};

var response = await _transactionService.CallContractAsync<BigInteger>(callRequest);
Console.WriteLine($"Balance: {response.Result}");
Console.WriteLine($"Function: {response.FunctionName}");
Console.WriteLine($"Timestamp: {response.Timestamp}");

Writing to Contracts (State-Changing Functions)

Execute Contract Function

using System.Numerics;

// ERC20 Token Transfer
var txHash = await _transactionService.ExecuteContractFunctionAsync(
    contractAddress,        // Ruby format contract address
    abi,                    // Contract ABI
    "transfer",             // Function name
    0,                      // ETH value to send (0 for token transfers)
    20,                     // Gas price in Gwei
    "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6",  // Recipient (Ruby address)
    new BigInteger(1000000000000000000)  // Amount in wei (1 token with 18 decimals)
);

Console.WriteLine($"Transfer transaction sent: {txHash}");

Execute with Custom Gas Limit

var txHash = await _transactionService.ExecuteContractFunctionWithGasLimitAsync(
    contractAddress,
    abi,
    "approve",
    0,                      // ETH value
    new BigInteger(50000),  // Custom gas limit
    20,                     // Gas price
    "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6",  // Spender
    new BigInteger(1000000000000000000)  // Amount
);

Enhanced Transaction Execution

var transactionRequest = new ContractTransactionRequest
{
    ContractAddress = contractAddress,
    Abi = abi,
    FunctionName = "transfer",
    Parameters = new object[] 
    { 
        "r742d45d5f2e6f9e5a1d3a8b7c6e5f4a3b2c1d0e9f8a7b6", 
        new BigInteger(1000000000000000000) 
    },
    ValueInEth = 0,
    GasPriceGwei = 20,
    GasLimit = 50000
};

var response = await _transactionService.ExecuteContractTransactionAsync(transactionRequest);
Console.WriteLine($"Transaction Hash: {response.TransactionHash}");
Console.WriteLine($"Function: {response.FunctionName}");
Console.WriteLine($"Value Sent: {response.ValueSent} ETH");
Console.WriteLine($"Timestamp: {response.Timestamp}");

Complete ERC20 Token Example

using System.Numerics;

class Program
{
    static async Task Main(string[] args)
    {
        var services = new ServiceCollection();
        services.AddWeb3TransactionService(
            "https://bridge-rpc.rubyscan.io",
            "r45a4ad4e4ab8dee45da7e46db797121347b274e3b4f0850305868f8e47b106be"
        );
        
        var serviceProvider = services.BuildServiceProvider();
        var txService = serviceProvider.GetRequiredService<ITransactionService>();
        
        var contractAddress = "r17a788748e934d3e9365f0bf2e5e5a7b73ae8464";
        var abi = @"[{
            ""inputs"": [],
            ""name"": ""name"",
            ""outputs"": [{""internalType"": ""string"", ""name"": """", ""type"": ""string""}],
            ""stateMutability"": ""view"",
            ""type"": ""function""
        },
        {
            ""inputs"": [],
            ""name"": ""symbol"",
            ""outputs"": [{""internalType"": ""string"", ""name"": """", ""type"": ""string""}],
            ""stateMutability"": ""view"",
            ""type"": ""function""
        },
        {
            ""inputs"": [],
            ""name"": ""decimals"",
            ""outputs"": [{""internalType"": ""uint8"", ""name"": """", ""type"": ""uint8""}],
            ""stateMutability"": ""view"",
            ""type"": ""function""
        },
        {
            ""inputs"": [],
            ""name"": ""totalSupply"",
            ""outputs"": [{""internalType"": ""uint256"", ""name"": """", ""type"": ""uint256""}],
            ""stateMutability"": ""view"",
            ""type"": ""function""
        },
        {
            ""inputs"": [{""internalType"": ""address"", ""name"": ""account"", ""type"": ""address""}],
            ""name"": ""balanceOf"",
            ""outputs"": [{""internalType"": ""uint256"", ""name"": """", ""type"": ""uint256""}],
            ""stateMutability"": ""view"",
            ""type"": ""function""
        },
        {
            ""inputs"": [
                {""internalType"": ""address"", ""name"": ""recipient"", ""type"": ""address""},
                {""internalType"": ""uint256"", ""name"": ""amount"", ""type"": ""uint256""}
            ],
            ""name"": ""transfer"",
            ""outputs"": [{""internalType"": ""bool"", ""name"": """", ""type"": ""bool""}],
            ""stateMutability"": ""nonpayable"",
            ""type"": ""function""
        },
        {
            ""inputs"": [
                {""internalType"": ""address"", ""name"": ""spender"", ""type"": ""address""},
                {""internalType"": ""uint256"", ""name"": ""amount"", ""type"": ""uint256""}
            ],
            ""name"": ""approve"",
            ""outputs"": [{""internalType"": ""bool"", ""name"": """", ""type"": ""bool""}],
            ""stateMutability"": ""nonpayable"",
            ""type"": ""function""
        }]";
        
        try
        {
            // 1. Read token info
            var name = await txService.CallContractAsync(contractAddress, abi, "name");
            var symbol = await txService.CallContractAsync(contractAddress, abi, "symbol");
            var decimals = await txService.CallContractFunctionAsync<BigInteger>(contractAddress, abi, "decimals");
            var totalSupply = await txService.CallContractFunctionAsync<BigInteger>(contractAddress, abi, "totalSupply");
            
            Console.WriteLine($"Token: {name} ({symbol})");
            Console.WriteLine($"Decimals: {decimals}");
            Console.WriteLine($"Total Supply: {totalSupply}");
            
            // 2. Check balance
            var addressToCheck = "r024889737062807ad1b83028f7d0ee986486e799";
            var balance = await txService.CallContractFunctionAsync<BigInteger>(
                contractAddress, 
                abi, 
                "balanceOf", 
                addressToCheck
            );
            Console.WriteLine($"Balance of {addressToCheck}: {balance}");
            
            // 3. Transfer tokens
            var recipient = "rANOTHER_ADDRESS_HERE";
            var amount = new BigInteger(1000000000000000000); // 1 token (18 decimals)
            
            Console.WriteLine($"Transferring {amount} {symbol} to {recipient}...");
            
            var txHash = await txService.ExecuteContractFunctionAsync(
                contractAddress,
                abi,
                "transfer",
                0,      // No ETH value needed for token transfers
                20,     // Gas price
                recipient,
                amount
            );
            
            Console.WriteLine($"Transaction sent: {txHash}");
            
            // 4. Wait for confirmation
            var receipt = await txService.WaitForTransactionReceiptAsync(txHash);
            if (receipt.Status?.Value == 1)
            {
                Console.WriteLine("Transfer successful!");
            }
            
            // 5. Approve tokens for spending (e.g., for DEX)
            var spender = "rDEX_CONTRACT_ADDRESS";
            var approveAmount = new BigInteger(5000000000000000000); // 5 tokens
            
            var approveTxHash = await txService.ExecuteContractFunctionAsync(
                contractAddress,
                abi,
                "approve",
                0,
                20,
                spender,
                approveAmount
            );
            
            Console.WriteLine($"Approval transaction: {approveTxHash}");
            
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

Parameter Types

When calling contract functions, use these .NET types:

• address: string (Ruby format: r...)
• uint256: BigInteger
• string: string
• bool: bool
• uint8: BigInteger or byte

Best Practices

1. Always Use Try-Catch

try
{
    var result = await _transactionService.ExecuteContractFunctionAsync(...);
}
catch (ApplicationException ex)
{
    // Blockchain-specific errors
    Console.WriteLine($"Contract error: {ex.Message}");
}
catch (Exception ex)
{
    // General errors
    Console.WriteLine($"Error: {ex.Message}");
}

2. Check ETH Balance for Gas

var ethBalance = await _transactionService.GetBalanceAsync(yourAddress);
if (ethBalance < 0.01m) // Less than 0.01 ETH
{
    Console.WriteLine("Warning: Low ETH balance for gas fees");
}

3. Wait for Confirmations

var txHash = await _transactionService.ExecuteContractFunctionAsync(...);
var receipt = await _transactionService.WaitForTransactionReceiptAsync(txHash, 120); // 2 minute timeout
if (receipt.Status?.Value == 1)
{
    Console.WriteLine("Transaction confirmed!");
}

4. Use BigInteger for Token Amounts

// Correct: Use BigInteger for token amounts
BigInteger amount = new BigInteger(1000000000000000000); // 1 token with 18 decimals

// Incorrect: Don't use decimal for token transfers
// decimal amount = 1.0m; // WRONG!

Error Handling

Common errors and solutions:

1. "transfer amount exceeds balance": Sender doesn't have enough tokens
2. "Reverted": Contract execution failed
3. "insufficient funds for gas": Not enough ETH for gas fees
4. "invalid address": Invalid Ruby address format
5. "invalid ABI": ABI JSON is malformed

Dependencies

• .NET 8.0, .NET Standard 2.0
• Nethereum 4.25.0
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging.Abstractions

Support

For issues:

1. Check that Ruby addresses are correctly formatted
2. Verify you have sufficient ETH for gas fees
3. Ensure contract ABI is valid JSON
4. Use BigInteger for token amounts
5. Check transaction receipts for detailed error messages

License

MIT License - See LICENSE file for details.