EtherSharpLib 1.0.0

EtherSharp

A complete and compact library for interacting with the Ethereum blockchain and its ecosystem.

EtherSharp is a .NET library inspired by ethers.js, designed to make it as easy as possible to build applications using Ethereum on the .NET platform.

Authors: agicodes and asajjad308@gmail.com

Features

• Complete: All functionality you need to interact with Ethereum
• Compact: Small bundle size with minimal dependencies
• Modular: Import only what you need
• Type Safe: Full TypeScript-like type safety with C# generics
• Well Tested: Comprehensive test suite
• Ethers.js Compatible: Familiar API for developers coming from JavaScript/TypeScript
• Production Ready: Used by many projects and teams

Installation

Prerequisites

• .NET 8.0 or later
• Visual Studio 2022, Visual Studio Code, or JetBrains Rider

Package Installation

dotnet add package EtherSharp

Or via Package Manager Console:

Install-Package EtherSharp

Project File

Add the package reference to your .csproj file:

<PackageReference Include="EtherSharp" Version="1.0.0" />

Quick Start

Import EtherSharp

using EtherSharp;
using EtherSharp.Common;
using EtherSharp.Interfaces;

Connect to Ethereum

The most common way to connect to Ethereum is using a Provider. EtherSharp comes with several built-in providers.

// Connect to Ethereum mainnet
var provider = EtherSharp.GetProvider("https://eth.llamarpc.com");

// Get the latest block number
var blockNumber = await provider.GetBlockNumberAsync();
Console.WriteLine($"Latest block: {blockNumber}");

// Get account balance
var address = EtherSharp.ParseAddress("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
var balance = await provider.GetBalanceAsync(address);
Console.WriteLine($"Balance: {EtherSharp.FormatEther(balance)} ETH");

Wallets

A Wallet is an abstraction of an Ethereum account that can be used to sign messages and transactions and send signed transactions to the Ethereum Network to execute state changing operations.

// Create a wallet from private key
var wallet = EtherSharp.CreateWallet("0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", provider);

// Get wallet address and balance
Console.WriteLine($"Address: {wallet.Address}");
var balance = await wallet.GetBalanceAsync();
Console.WriteLine($"Balance: {EtherSharp.FormatEther(balance)} ETH");

// Send a transaction
var transaction = new TransactionRequest
{
    To = EtherSharp.ParseAddress("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"),
    Value = EtherSharp.ParseEther("0.1")
};

var txResponse = await wallet.SendTransactionAsync(transaction);
Console.WriteLine($"Transaction hash: {txResponse.Hash}");

Contracts

A Contract is an abstraction of code that has been deployed to the blockchain, which exists at a specific address on the Ethereum blockchain.

// ERC-20 Token Contract ABI (simplified)
var erc20Abi = @"[
    {
        ""name"": ""balanceOf"",
        ""type"": ""function"",
        ""inputs"": [{""name"": ""account"", ""type"": ""address""}],
        ""outputs"": [{""name"": """", ""type"": ""uint256""}]
    },
    {
        ""name"": ""transfer"",
        ""type"": ""function"",
        ""inputs"": [
            {""name"": ""to"", ""type"": ""address""},
            {""name"": ""amount"", ""type"": ""uint256""}
        ],
        ""outputs"": [{""name"": """", ""type"": ""bool""}]
    }
]";

// Create contract instance
var contractAddress = EtherSharp.ParseAddress("0xA0b86a33E6441b8C4C8C0d4Cecc0f7B2f8f8f8f8");
var contract = EtherSharp.CreateContract(erc20Abi, contractAddress, provider);

// Call a read-only function
var balance = await contract.CallAsync<BigNumber>("balanceOf", "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
Console.WriteLine($"Token balance: {balance}");

// Send a transaction (requires wallet with funds)
var wallet = EtherSharp.CreateWallet("0x...", provider);
var txResponse = await contract.SendAsync("transfer", "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6", EtherSharp.ParseUnits("100", 18));
Console.WriteLine($"Transfer transaction: {txResponse.Hash}");

API Reference

EtherSharp (Static Class)

The main entry point for EtherSharp functionality.

Provider Creation

• GetProvider(url) - Creates a JsonRpcProvider with the specified URL
• GetDefaultProvider(url?) - Creates a JsonRpcProvider (defaults to localhost:8545)

Wallet Creation

• CreateWallet(privateKey, provider?) - Creates a wallet from private key
• CreateRandomWallet(provider?) - Creates a random wallet
• CreateWalletFromMnemonic(mnemonic, provider?, path?) - Creates wallet from mnemonic

Contract Creation

• CreateContract(abi, address, provider?) - Creates a contract instance
• CreateContract(abi, addressString, provider?) - Creates a contract instance from address string

Utility Functions

• ParseAddress(address) - Parses an address string to Address object
• ParseEther(ether) - Parses an ether amount string to BigNumber
• ParseUnits(value, decimals) - Parses a value with specified decimals to BigNumber
• FormatAddress(address) - Formats an Address object to string
• FormatEther(value) - Formats a BigNumber as ether string
• FormatGwei(value) - Formats a BigNumber as gwei string

IProvider Interface

Provides connection to the Ethereum network and blockchain data.

Blockchain Data

• GetBlockNumberAsync() - Gets the latest block number
• GetBlockAsync(blockNumber) - Gets a block by number
• GetBlockAsync(blockHash) - Gets a block by hash
• GetBlockAsync() - Gets the latest block
• GetTransactionAsync(hash) - Gets a transaction by hash
• GetBalanceAsync(address) - Gets account balance
• GetTransactionCountAsync(address) - Gets account nonce
• GetCodeAsync(address) - Gets contract code
• GetStorageAtAsync(address, position) - Gets storage value

Network Information

• GetGasPriceAsync() - Gets current gas price
• GetFeeDataAsync() - Gets fee data for EIP-1559 transactions
• GetNetworkAsync() - Gets network information

Transaction Operations

• EstimateGasAsync(transaction) - Estimates gas for transaction
• SendTransactionAsync(transaction) - Sends a transaction
• CallAsync(transaction) - Calls a contract method
• WaitForTransactionAsync(hash, confirmations?) - Waits for transaction confirmation

IWallet Interface

Represents an Ethereum account that can sign transactions and messages.

Properties

• Address - Wallet address
• Provider - Connected provider

Operations

• SignMessageAsync(message) - Signs a message
• SignTransactionAsync(transaction) - Signs a transaction
• SendTransactionAsync(transaction) - Sends a transaction
• GetBalanceAsync() - Gets wallet balance
• GetTransactionCountAsync() - Gets wallet nonce
• Connect(provider) - Connects to a provider

IContract Interface

Represents a smart contract deployed on the Ethereum blockchain.

Properties

• Address - Contract address
• Abi - Contract ABI
• Provider - Connected provider

Methods

• CallAsync<T>(methodName, parameters) - Calls a read-only method with typed return
• CallAsync(methodName, parameters) - Calls a read-only method
• SendAsync(methodName, parameters) - Sends a transaction to a contract method
• EstimateGasAsync(methodName, parameters) - Estimates gas for method call
• GetEventFilter(eventName) - Gets an event filter
• Connect(provider) - Connects to a provider

Data Types

Address

Represents an Ethereum address with validation and formatting.

var address = EtherSharp.ParseAddress("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6");
Console.WriteLine(address.ToString()); // "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"

BigNumber

Represents large numbers used in Ethereum (wei, gas, etc.) with arithmetic operations.

var ether = EtherSharp.ParseEther("1.5");
var gwei = ether.ToGwei();
var wei = ether.ToWei();

TransactionRequest

Represents a transaction to be sent to the network.

var transaction = new TransactionRequest
{
    To = EtherSharp.ParseAddress("0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"),
    Value = EtherSharp.ParseEther("0.1"),
    GasPrice = EtherSharp.ParseGwei("20"),
    GasLimit = BigNumber.ParseUnits("21000", 0)
};

TransactionResponse

Represents a transaction that has been sent to the network.

var txResponse = await wallet.SendTransactionAsync(transaction);
Console.WriteLine($"Hash: {txResponse.Hash}");
Console.WriteLine($"Block Number: {txResponse.BlockNumber}");
Console.WriteLine($"Gas Used: {txResponse.GasUsed}");

FeeData

Represents fee information for EIP-1559 transactions.

var feeData = await provider.GetFeeDataAsync();
Console.WriteLine($"Gas Price: {feeData.GasPrice}");
Console.WriteLine($"Max Fee Per Gas: {feeData.MaxFeePerGas}");
Console.WriteLine($"Max Priority Fee Per Gas: {feeData.MaxPriorityFeePerGas}");

Network

Represents network information.

var network = await provider.GetNetworkAsync();
Console.WriteLine($"Name: {network.Name}");
Console.WriteLine($"Chain ID: {network.ChainId}");
Console.WriteLine($"ENS Address: {network.EnsAddress}");

Examples

The examples/ directory contains comprehensive examples demonstrating various EtherSharp features:

Basic Usage (examples/BasicUsage.cs)

• Provider operations (getting blocks, balances, gas prices)
• Wallet operations (creating wallets, signing messages)
• Contract interactions (calling read-only functions)

Advanced Usage (examples/AdvancedUsage.cs)

• Custom gas transactions with EIP-1559 support
• Event filtering and log retrieval
• Batch operations for improved performance
• Comprehensive error handling patterns

Running Examples

# Navigate to the examples directory
cd examples

# Run basic usage example
dotnet run BasicUsage.cs

# Run advanced usage example
dotnet run AdvancedUsage.cs

Example: ERC-20 Token Interaction

using EtherSharp;
using EtherSharp.Common;

// Create provider and wallet
var provider = EtherSharp.GetProvider("https://eth.llamarpc.com");
var wallet = EtherSharp.CreateWallet("0x...", provider);

// ERC-20 ABI
var erc20Abi = @"[
    {
        ""name"": ""balanceOf"",
        ""type"": ""function"",
        ""inputs"": [{""name"": ""account"", ""type"": ""address""}],
        ""outputs"": [{""name"": """", ""type"": ""uint256""}]
    },
    {
        ""name"": ""transfer"",
        ""type"": ""function"",
        ""inputs"": [
            {""name"": ""to"", ""type"": ""address""},
            {""name"": ""amount"", ""type"": ""uint256""}
        ],
        ""outputs"": [{""name"": """", ""type"": ""bool""}]
    }
]";

// Create contract instance
var usdcContract = EtherSharp.CreateContract(erc20Abi, "0xA0b86a33E6441b8C4C8C0d4Cecc0f7B2f8f8f8f8", provider);

// Check balance
var balance = await usdcContract.CallAsync<BigNumber>("balanceOf", wallet.Address.ToString());
Console.WriteLine($"USDC Balance: {balance}");

// Transfer tokens
var txResponse = await usdcContract.SendAsync("transfer", "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6", EtherSharp.ParseUnits("100", 6));
Console.WriteLine($"Transfer transaction: {txResponse.Hash}");

Contributing

EtherSharp is an open source project and contributions are welcome! Here's how you can help:

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/EtherSharp.git
3. Create a feature branch: git checkout -b feature/your-feature-name
4. Make your changes and add tests
5. Run tests: dotnet test
6. Commit your changes: git commit -m "Add your feature"
7. Push to your fork: git push origin feature/your-feature-name
8. Create a Pull Request

Code Style

• Follow C# coding conventions
• Use PascalCase for public members
• Use camelCase for private members and parameters
• Add XML documentation for public APIs
• Write unit tests for new functionality
• Ensure all tests pass before submitting

Reporting Issues

• Use GitHub Issues to report bugs
• Provide detailed reproduction steps
• Include your .NET version and operating system
• Attach relevant logs or error messages

Support

Documentation

• API Reference: Complete API documentation is available in the code
• Examples: Check the examples/ directory for practical usage examples
• GitHub: EtherSharp Repository

Community

• GitHub Discussions: Ask questions and share ideas
• GitHub Issues: Report bugs and request features
• Discord: Join our community Discord server (coming soon)

Professional Support

For enterprise support, custom development, or consulting services, please contact us at support@ethersharp.dev.

License

EtherSharp is released under the MIT License. See the LICENSE file for details.

Acknowledgments

EtherSharp is inspired by and designed to be compatible with ethers.js, the excellent JavaScript library for Ethereum development. We thank the ethers.js team for their groundbreaking work and inspiration.