Skip to main content

Nethereum.Model

NuGet: Nethereum.Model | Source: src/Nethereum.Model/

Nethereum.Model

Core Ethereum data models representing transactions, blocks, accounts, and cryptographic signatures.

Overview​

Nethereum.Model is a foundational package that defines the core data structures used throughout the Ethereum protocol. These models represent:

  • Transaction Types: Support for Legacy, EIP-2930, EIP-1559, and EIP-7702 transactions
  • Block Headers: Ethereum block header structure with all consensus fields
  • Account State: Account nonce, balance, storage root, and code hash
  • Signatures: ECDSA signature components (R, S, V) for transaction verification
  • Event Logs: Smart contract event data structures

This package provides the canonical implementation of Ethereum data structures with built-in RLP encoding/decoding support.

Installation​

dotnet add package Nethereum.Model

Dependencies​

Nethereum Dependencies:

  • Nethereum.RLP - Recursive Length Prefix encoding/decoding
  • Nethereum.Util - Keccak-256 hashing, address utilities, unit conversion

Key Concepts​

Transaction Types​

Ethereum has evolved to support multiple transaction formats:

  • Legacy Transactions (LegacyTransaction): Original transaction format (pre-EIP-155)
  • Legacy with Chain ID (LegacyTransactionChainId): EIP-155 transactions preventing replay attacks
  • EIP-2930 (Transaction2930): Transactions with access lists for gas optimization
  • EIP-1559 (Transaction1559): Fee market transactions with base fee and priority fee
  • EIP-7702 (Transaction7702): Account abstraction with authorization lists

RLP Encoding​

All models implement RLP (Recursive Length Prefix) encoding, the serialization format used by Ethereum for:

  • Transmitting transactions over the network
  • Computing cryptographic hashes (transaction hash, block hash)
  • Storing data in the Ethereum state trie

Signatures​

Ethereum uses ECDSA signatures with three components:

  • R: X-coordinate of the random point on the elliptic curve
  • S: Signature proof value
  • V: Recovery identifier (allows deriving the public key from the signature)

Chain Identification​

The Chain enum provides constants for major Ethereum networks (MainNet, Sepolia, Polygon, Arbitrum, Optimism, Base, etc.) and is used with EIP-155 to prevent cross-chain replay attacks.

Quick Start​

using Nethereum.Model;
using System.Numerics;

// Create a simple EIP-1559 transaction
var transaction = new Transaction1559(
chainId: 1, // Ethereum Mainnet
nonce: 0,
maxPriorityFeePerGas: BigInteger.Parse("2000000000"), // 2 gwei
maxFeePerGas: BigInteger.Parse("100000000000"), // 100 gwei
gasLimit: 21000,
receiverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
amount: BigInteger.Parse("1000000000000000000"), // 1 ETH
data: "",
accessList: null
);

Usage Examples​

Example 1: Creating a Legacy Transaction​

using Nethereum.Model;
using System.Numerics;

// Create a legacy transaction (most common pre-2021)
var legacyTx = new LegacyTransaction(
to: "0x13978aee95f38490e9769c39b2773ed763d9cd5f",
amount: new BigInteger(10000000000000000L), // 0.01 ETH
nonce: 0,
gasPrice: new BigInteger(1000000000000L), // 1000 gwei
gasLimit: 10000
);

// Transaction is ready to be signed with Nethereum.Signer

Source: tests/Nethereum.Signer.UnitTests/TransactionTests.cs

Example 2: Decoding a Signed Transaction from RLP​

using Nethereum.Model;
using Nethereum.Hex.HexConvertors.Extensions;

// RLP-encoded signed transaction (typically from network or storage)
var rlpHex = "f86b8085e8d4a510008227109413978aee95f38490e9769c39b2773ed763d9cd5f872386f26fc10000801ba0eab47c1a49bf2fe5d40e01d313900e19ca485867d462fe06e139e3a536c6d4f4a014a569d327dcda4b29f74f93c0e9729d2f49ad726e703f9cd90dbb0fbf6649f1";

// Decode the transaction
var tx = new LegacyTransaction(rlpHex.HexToByteArray());

// Access transaction properties
var nonce = tx.Nonce.ToBigIntegerFromRLPDecoded();
var gasPrice = tx.GasPrice.ToBigIntegerFromRLPDecoded();
var value = tx.Value.ToBigIntegerFromRLPDecoded();
var to = tx.ReceiveAddress.ToHex();

// Access signature components
var v = tx.Signature.V[0]; // 27 or 28 for legacy transactions
var r = tx.Signature.R.ToHex();
var s = tx.Signature.S.ToHex();

Source: tests/Nethereum.Signer.UnitTests/TransactionTests.cs

Example 3: Using TransactionFactory to Decode Any Transaction Type​

using Nethereum.Model;

// TransactionFactory automatically detects transaction type
var rlpEncoded = GetTransactionFromNetwork(); // byte[] from RPC or P2P

ISignedTransaction transaction = TransactionFactory.CreateTransaction(rlpEncoded);

// Check the transaction type
switch (transaction.TransactionType)
{
case TransactionType.LegacyTransaction:
var legacy = (LegacyTransaction)transaction;
// Handle legacy transaction
break;

case TransactionType.EIP1559:
var eip1559 = (Transaction1559)transaction;
var maxFeePerGas = eip1559.MaxFeePerGas;
var maxPriorityFee = eip1559.MaxPriorityFeePerGas;
break;

case TransactionType.LegacyEIP2930:
var eip2930 = (Transaction2930)transaction;
var accessList = eip2930.AccessList;
break;

case TransactionType.EIP7702:
var eip7702 = (Transaction7702)transaction;
var authList = eip7702.AuthorisationList;
break;
}

Source: src/Nethereum.Model/TransactionFactory.cs

Example 4: Creating an EIP-1559 Transaction with Access List​

using Nethereum.Model;
using System.Numerics;
using System.Collections.Generic;

// Create an access list (EIP-2930) to reduce gas costs
var accessList = new List<AccessListItem>
{
new AccessListItem(
address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
storageKeys: new List<byte[]>
{
"0x0000000000000000000000000000000000000000000000000000000000000001".HexToByteArray()
}
)
};

// Create an EIP-1559 transaction
var tx1559 = new Transaction1559(
chainId: (BigInteger)Chain.MainNet,
nonce: 42,
maxPriorityFeePerGas: new BigInteger(2_000_000_000), // 2 gwei tip
maxFeePerGas: new BigInteger(100_000_000_000), // 100 gwei max
gasLimit: 100_000,
receiverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
amount: BigInteger.Parse("5000000000000000000"), // 5 ETH
data: "0x",
accessList: accessList
);

// Get RLP encoding for signing
var rlpForSigning = tx1559.GetRLPEncodedRaw();

Source: src/Nethereum.Model/Transaction1559.cs, src/Nethereum.Model/AccessListItem.cs

Example 5: Working with Ethereum Account State​

using Nethereum.Model;
using System.Numerics;

// Create an account state object (as stored in the Ethereum state trie)
var account = new Account
{
Nonce = 42, // Number of transactions sent from this address
Balance = BigInteger.Parse("5000000000000000000000"), // 5000 ETH in wei
StateRoot = stateRootHash, // Root of the account's storage trie
CodeHash = contractCodeHash // Keccak-256 hash of the contract bytecode
};

// For EOA (Externally Owned Accounts), defaults are used:
var eoa = new Account
{
Nonce = 0,
Balance = BigInteger.Parse("1000000000000000000"), // 1 ETH
StateRoot = DefaultValues.EMPTY_TRIE_HASH, // Empty storage
CodeHash = DefaultValues.EMPTY_DATA_HASH // No code
};

Source: src/Nethereum.Model/Account.cs

Example 6: Creating Event Logs​

using Nethereum.Model;
using Nethereum.Hex.HexConvertors.Extensions;

// Create an event log (emitted by smart contracts)
var eventData = "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000".HexToByteArray();
var topic1 = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef".HexToByteArray(); // Transfer event signature
var topic2 = "0x000000000000000000000000742d35cc6634c0532925a3b844bc9e7595f0beb".HexToByteArray(); // From address
var topic3 = "0x00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640".HexToByteArray(); // To address

var log = Log.Create(
data: eventData,
address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // Contract address
topics: new[] { topic1, topic2, topic3 }
);

// Or create log without data
var logWithoutData = Log.Create(
address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
topics: topic1, topic2, topic3
);

Source: src/Nethereum.Model/Log.cs

Example 7: Working with Block Headers​

using Nethereum.Model;
using System.Numerics;

// Construct a block header
var blockHeader = new BlockHeader
{
ParentHash = parentBlockHash,
UnclesHash = unclesHash,
Coinbase = "0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326", // Miner address
StateRoot = stateRoot,
TransactionsHash = transactionsTrieRoot,
ReceiptHash = receiptsTrieRoot,
BlockNumber = 18_000_000,
LogsBloom = logsBloomFilter,
Difficulty = 0, // Post-merge (PoS) difficulty is always 0
Timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
GasLimit = 30_000_000,
GasUsed = 12_543_210,
MixHash = mixHash,
ExtraData = extraData,
Nonce = nonce,
BaseFee = new BigInteger(15_000_000_000) // EIP-1559 base fee
};

// Encode the block header for hashing
var encoded = BlockHeaderEncoder.Current.EncodeHeader(blockHeader);

Source: src/Nethereum.Model/BlockHeader.cs

Example 8: Creating Transactions for Different Networks​

using Nethereum.Model;
using Nethereum.Signer;
using System.Numerics;

// Ethereum Mainnet transaction
var mainnetTx = new Transaction1559(
chainId: (BigInteger)Chain.MainNet, // 1
nonce: 0,
maxPriorityFeePerGas: new BigInteger(2_000_000_000),
maxFeePerGas: new BigInteger(50_000_000_000),
gasLimit: 21000,
receiverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
amount: BigInteger.Parse("1000000000000000000"),
data: "",
accessList: null
);

// Polygon transaction (lower gas fees)
var polygonTx = new Transaction1559(
chainId: (BigInteger)Chain.Polygon, // 137
nonce: 0,
maxPriorityFeePerGas: new BigInteger(30_000_000_000), // 30 gwei
maxFeePerGas: new BigInteger(200_000_000_000), // 200 gwei
gasLimit: 21000,
receiverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
amount: BigInteger.Parse("1000000000000000000"),
data: "",
accessList: null
);

// Base L2 transaction
var baseTx = new Transaction1559(
chainId: (BigInteger)Chain.Base, // 8453
nonce: 0,
maxPriorityFeePerGas: new BigInteger(100_000), // Very low on L2
maxFeePerGas: new BigInteger(1_000_000),
gasLimit: 21000,
receiverAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
amount: BigInteger.Parse("1000000000000000000"),
data: "",
accessList: null
);

Source: Chain.cs enum values

Example 9: Account Storage Encoding​

using Nethereum.Model;
using Nethereum.Util.HashProviders;
using Nethereum.Hex.HexConvertors.Extensions;

var sha3Provider = new Sha3KeccackHashProvider();

// Encode a storage key for the state trie
var storageKey = "0x0000000000000000000000000000000000000000000000000000000000000001".HexToByteArray();
var encodedKey = AccountStorage.EncodeKeyForStorage(storageKey, sha3Provider);

// Encode a storage value
var storageValue = "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000".HexToByteArray();
var encodedValue = AccountStorage.EncodeValueForStorage(storageValue);

// These encoded values are used in the Patricia Merkle Trie

Source: src/Nethereum.Model/Account.cs

API Reference​

Transaction Types​

TransactionType Enum​

  • LegacyTransaction (-1): Pre-EIP-155 transactions
  • LegacyChainTransaction (-2): EIP-155 transactions with chain ID
  • LegacyEIP2930 (0x01): Transactions with access lists
  • EIP1559 (0x02): Fee market transactions
  • Blob (0x03): EIP-4844 blob transactions
  • EIP7702 (0x04): Account abstraction with authorization

LegacyTransaction​

Pre-EIP-155 transaction format with basic fields.

Key Properties:

  • byte[] Nonce: Transaction sequence number
  • byte[] GasPrice: Gas price in wei
  • byte[] GasLimit: Maximum gas units
  • byte[] ReceiveAddress: Recipient address
  • byte[] Value: Amount in wei
  • byte[] Data: Contract call data or deployment code
  • Signature Signature: Transaction signature (R, S, V)

Key Methods:

  • byte[] GetRLPEncoded(): Get signed transaction RLP encoding
  • EthECKey GetKey(): Recover signer's public key from signature

LegacyTransactionChainId​

EIP-155 transaction with chain ID to prevent replay attacks.

Inherits from LegacyTransaction with added chain ID in V signature component.

Transaction1559​

EIP-1559 fee market transaction.

Key Properties:

  • BigInteger ChainId: Network chain identifier
  • BigInteger? Nonce: Transaction sequence number
  • BigInteger? MaxPriorityFeePerGas: Miner tip
  • BigInteger? MaxFeePerGas: Maximum total fee per gas
  • BigInteger? GasLimit: Gas limit
  • string ReceiverAddress: Recipient
  • BigInteger? Amount: Value to transfer
  • string Data: Call data
  • List<AccessListItem> AccessList: Optional access list

Key Methods:

  • byte[] GetRLPEncoded(): Get complete RLP-encoded transaction
  • byte[] GetRLPEncodedRaw(): Get RLP encoding for signing (without signature)

Transaction2930​

EIP-2930 transaction with access list.

Similar structure to Transaction1559 but uses GasPrice instead of base/priority fees.

Transaction7702​

EIP-7702 transaction that allows EOAs to temporarily set account code for a single transaction via signed authorizations.

Key Properties:

  • BigInteger ChainId: Network chain identifier
  • BigInteger? Nonce: Transaction sequence number
  • BigInteger? MaxPriorityFeePerGas: Miner tip
  • BigInteger? MaxFeePerGas: Maximum total fee per gas
  • BigInteger? GasLimit: Gas limit
  • string ReceiverAddress: Recipient
  • BigInteger? Amount: Value to transfer
  • string Data: Call data
  • List<AccessListItem> AccessList: Optional access list
  • List<Authorisation7702Signed> AuthorisationList: Signed authorization tuples

Key Methods:

  • byte[] GetRLPEncoded(): Get complete RLP-encoded transaction
  • byte[] GetRLPEncodedRaw(): Get RLP encoding for signing (without signature)

Gas7702​

Gas cost constants for EIP-7702 authorization processing.

Constants:

  • PER_AUTH_BASE_COST = 12500: Base gas cost per authorization entry
  • PER_EMPTY_ACCOUNT_COST = 25000: Additional gas cost when the authorized account is empty

TransactionFactory​

Factory class for creating and decoding transactions.

Key Methods:

  • static ISignedTransaction CreateTransaction(byte[] rlp): Automatically detects and decodes any transaction type
  • static ISignedTransaction CreateTransaction(string rlpHex): Hex string overload
  • static ISignedTransaction Create1559Transaction(...): Create EIP-1559 transaction
  • static ISignedTransaction Create2930Transaction(...): Create EIP-2930 transaction
  • static ISignedTransaction Create7702Transaction(...): Create EIP-7702 transaction
  • static ISignedTransaction CreateLegacyTransaction(...): Create legacy transaction

Block Models​

BlockHeader​

Ethereum block header structure.

Properties:

  • byte[] ParentHash: Hash of parent block
  • byte[] UnclesHash: Hash of uncle blocks list
  • string Coinbase: Miner/validator address
  • byte[] StateRoot: State trie root hash
  • byte[] TransactionsHash: Transactions trie root hash
  • byte[] ReceiptHash: Receipts trie root hash
  • BigInteger BlockNumber: Block height
  • byte[] LogsBloom: Bloom filter for logs
  • BigInteger Difficulty: Mining difficulty (0 post-merge)
  • long Timestamp: Block timestamp (Unix seconds)
  • long GasLimit: Maximum gas for block
  • long GasUsed: Total gas used in block
  • byte[] MixHash: PoW mix hash (random post-merge)
  • byte[] ExtraData: Arbitrary extra data
  • byte[] Nonce: PoW nonce (0 post-merge)
  • BigInteger? BaseFee: EIP-1559 base fee per gas

BlockHeaderEncoder​

RLP encoder/decoder for block headers.

Methods:

  • byte[] EncodeHeader(BlockHeader header): Encode block header to RLP
  • BlockHeader DecodeHeader(byte[] rlp): Decode RLP to block header

Account Models​

Account​

Ethereum account state.

Properties:

  • BigInteger Nonce: Transaction count or contract creation count
  • BigInteger Balance: Account balance in wei
  • byte[] StateRoot: Storage trie root (default: empty trie hash)
  • byte[] CodeHash: Contract code hash (default: empty data hash)

AccountStorage​

Utilities for encoding account storage.

Methods:

  • static byte[] EncodeKeyForStorage(byte[] key, Sha3KeccackHashProvider): Encode storage key
  • static byte[] EncodeValueForStorage(byte[] value): Encode storage value

Signature Models​

Signature : ISignature​

ECDSA signature components.

Properties:

  • byte[] R: Signature R component
  • byte[] S: Signature S component
  • byte[] V: Recovery identifier

Constructors:

  • Signature(): Default constructor
  • Signature(byte[] r, byte[] s, byte[] v): Create with components

SignatureExtensions​

Extension methods for signature operations.

Key Methods:

  • bool IsVSignedForChain(this Signature): Check if V indicates chain-specific signature
  • BigInteger GetChainFromVChain(BigInteger v): Extract chain ID from V

Event Log Models​

Log​

Smart contract event log.

Properties:

  • string Address: Contract address that emitted the log
  • byte[] Data: Non-indexed event data
  • List<byte[]> Topics: Indexed event topics (event signature + indexed parameters)

Static Methods:

  • static Log Create(byte[] data, string address, params byte[][] topics): Create log with data
  • static Log Create(string address, params byte[][] topics): Create log without data

LogBloomFilter​

Bloom filter for efficient log filtering.

Access List Models​

AccessListItem​

EIP-2930 access list entry.

Properties:

  • string Address: Contract address
  • List<byte[]> StorageKeys: Storage slots to pre-warm

Constructors:

  • AccessListItem(): Default constructor
  • AccessListItem(string address, List<byte[]> storageKeys): Create with values

AccessListRLPEncoderDecoder​

RLP encoder/decoder for access lists.

Authorization Models (EIP-7702)​

Authorisation7702​

Unsigned authorization tuple specifying which contract code an EOA delegates to.

Properties:

  • BigInteger ChainId: Chain ID the authorization is valid for
  • string Address: Contract address whose code the EOA will execute
  • BigInteger Nonce: Nonce of the authorizing account at time of signing

Authorisation7702Signed​

Signed authorization extending Authorisation7702 with ECDSA signature components. Implements ISignature.

Properties (inherited from Authorisation7702):

  • BigInteger ChainId: Chain ID the authorization is valid for
  • string Address: Contract address whose code the EOA will execute
  • BigInteger Nonce: Nonce of the authorizing account

Properties (signature):

  • byte[] V: YParity value
  • byte[] R: Signature R component
  • byte[] S: Signature S component

Constructors:

  • Authorisation7702Signed(): Default constructor
  • Authorisation7702Signed(BigInteger chainId, string address, BigInteger nonce, byte[] r, byte[] s, byte[] v): Create with all fields
  • Authorisation7702Signed(Authorisation7702 authorisation, Signature signature): Create from unsigned authorization and signature
  • Authorisation7702Signed(Authorisation7702 authorisation, byte[] r, byte[] s, byte[] v): Create from unsigned authorization and raw signature bytes

AuthorisationListRLPEncoderDecoder​

RLP encoder/decoder for authorization lists.

Enumerations​

Chain​

Well-known Ethereum network chain IDs.

Common Values:

  • MainNet = 1: Ethereum Mainnet
  • Sepolia = 11155111: Sepolia testnet
  • Polygon = 137: Polygon PoS
  • Arbitrum = 42161: Arbitrum One
  • Optimism = 10: Optimism
  • Base = 8453: Base L2
  • Avalanche = 43114: Avalanche C-Chain
  • Binance = 56: BNB Chain

See Chain.cs for the complete list of 100+ networks

Utility Classes​

DefaultValues​

Default constant values used throughout the package.

Constants:

  • EMPTY_BYTE_ARRAY: Empty byte array
  • EMPTY_TRIE_HASH: Keccak-256 of empty trie
  • EMPTY_DATA_HASH: Keccak-256 of empty data

VRecoveryAndChainCalculations​

Utilities for signature V value and chain ID calculations.

Methods:

  • static BigInteger GetChainFromVChain(BigInteger vChain): Extract chain ID from V
  • V value encoding/decoding for EIP-155

Used By (Consumers)​

  • Nethereum.Signer - Signs transactions using the transaction models defined here
  • Nethereum.RPC - RPC methods return block headers, transactions, and logs
  • Nethereum.Contracts - Contract deployment and interaction uses transaction models
  • Nethereum.Accounts - Account management uses transaction types for sending
  • Nethereum.BlockchainProcessing - Processes blocks, transactions, and logs

Dependencies​

  • Nethereum.RLP - All models use RLP encoding for serialization
  • Nethereum.Util - Uses Keccak-256 hashing, address validation, and byte conversions

Important Notes​

Transaction Type Detection​

When decoding transactions from RLP:

  • The first byte determines if it's a typed transaction (0x00-0x7F) or legacy (≥0xC0)
  • TransactionFactory.CreateTransaction() automatically detects the type
  • Legacy transactions are identified by their RLP list structure

V Signature Component​

The V value in signatures serves dual purposes:

  • Recovery ID: Allows deriving the public key (and address) from the signature
  • Chain ID (EIP-155): For legacy transactions, V encodes chain ID as V = CHAIN_ID * 2 + 35 + {0,1}
  • For typed transactions (EIP-2930, EIP-1559, EIP-7702), V is simply 0 or 1

Gas Pricing Models​

Different transaction types use different gas pricing:

  • Legacy & EIP-2930: Single gasPrice (user pays gasPrice × gasUsed)
  • EIP-1559+: maxFeePerGas and maxPriorityFeePerGas
    • Actual fee = min(maxFeePerGas, baseFee + maxPriorityFeePerGas) × gasUsed
    • BaseFee is burned, priority fee goes to validator

Chain ID Usage​

Always specify the correct chain ID to prevent:

  • Replay attacks: Same transaction valid on multiple chains (e.g., mainnet and testnet)
  • Lost funds: Sending to wrong network addresses

RLP Encoding for Signing vs. Transmission​

Transactions have two RLP encodings:

  • Raw encoding (GetRLPEncodedRaw()): Unsigned, used for signing
  • Full encoding (GetRLPEncoded()): Includes signature, used for transmission

Block Header Post-Merge Changes​

After Ethereum's transition to Proof-of-Stake (The Merge):

  • Difficulty is always 0
  • Nonce is 0 (no longer used for mining)
  • MixHash contains randomness from the beacon chain
  • Coinbase is the fee recipient (validator or pool)

Account State Storage​

Account state is stored in a Patricia Merkle Trie:

  • StateRoot: Root hash of the account's storage trie
  • CodeHash: Keccak-256 of contract bytecode (empty hash for EOAs)
  • These hashes allow verification without storing full state

Additional Resources​

Ethereum Improvement Proposals (EIPs)​

  • EIP-155: Simple replay attack protection (chain ID)
  • EIP-2718: Typed transaction envelope
  • EIP-2930: Optional access lists
  • EIP-1559: Fee market change (base fee + priority fee)
  • EIP-4844: Shard blob transactions
  • EIP-7702: Set EOA account code for one transaction

Ethereum Protocol​

Nethereum Documentation​