Ethereum transaction
An EthereumTransaction
lets you execute a raw, RLP-encoded (type 0, 1, or 2) Ethereum transaction on the Hedera network. This enables developers familiar with EVM tooling to leverage their existing knowledge and infrastructure when interacting with the Hedera Smart Contract Service (HSCS).
Important
Hedera interprets HBAR decimals differently depending on the context:
The lowest denomination of HBAR when used within a the
value
field in theEthereumTransaction
isweibars
meaning with18
decimalsThe lowest denomination of hbar when used within
data
or the Hedera EVM istinybars
meaning with8
decimals.Gas Price information is in
weibars
denomination. Reference: HIP-410
Ethereum Data
An RLP-encoded (type 0, 1, or 2) Ethereum transaction to execute on the Hedera network. This enables developers to leverage existing EVM tooling and workflows with the Hedera Smart Contract Service (HSCS).
Call Data File ID
An optional field referencing a file on the Hedera File Service (HFS) containing the callData
. When set, the network ignores the callData
in ethereumData
during execution and instead loads the data from the referenced file. However, the full callData
must still be present in the originally signed ethereumData
for signature validation. In this case, ethereumData
will contain a placeholder where callData
normally resides, and the transaction must be "rehydrated" with the HFS content during validation.
Note: With HIP-1086, jumbo ethereumData
is the preferred approach for large payloads, but callDataFileId
remains supported for oversized payloads or legacy workflows.
Max Allowance
The maximum amount of HBAR (specified in tinybars) the payer is willing to cover for the gas consumed during transaction execution. This value acts as a ceiling if the actual gas cost (determined by gasLimit
in the RLP-encoded transaction and the network's gas price) exceeds this amount, the transaction fails.
Ordinarily, the account with the ECDSA alias extracted from the ethereumData
signature covers the execution fees. If insufficient fees are authorized by that account, the payer can be charged up to but not exceeding maxGasAllowance
. If the authorized fee is zero, the payer is charged the full amount.
Handling Large callData Payloads
HIP-1086 introduced support for jumbo Ethereum transactions, allowing ethereumData
to directly include callData
up to 24KB for contract creation and 128KB for contract calls. This removes the need to use callDataFileId
for many large payloads. The rest of the protobuf wrapper (signatures, node account ID, etc.) must still fit within 2KB.
Gas Calculation for callData
The gas cost for the callData
in jumbo EthereumTransaction is calculated as:
callData gas = 4 × zero bytes + 16 × non-zero bytes
This is added to base gas and execution gas. Developers must ensure both gasLimit
(in the RLP-encoded transaction) and maxGasAllowance
(in the wrapper) are set high enough.
📣 For detailed gas and fee calculation, refer to the Gas and Fees page.
Quick reference: Jumbo vs Standard Transactions
callData Size Limit
24KB (creation) / 128KB (call)
~6KB total transaction size
callDataFileId Needed?
Only if limits exceeded
Always for large payloads
Gas Calculation
Always for large payloads
Same
Batch Inclusion
Not supported
Supported
Network Throttling
Dedicated throttle bucket
Standard throttling
📣 See HIP-1086 and the Gas and Fees page for complete technical details.
Transaction Signing Requirements
The transaction must be signed by the key of the fee-paying account. For EthereumTransaction
, this is:
The account with the ECDSA alias derived from the public key in
ethereumData
, if sufficient gas and fees are authorized.If the authorized fee from the Ethereum sender is insufficient, the payer of the transaction is charged up to the
maxGasAllowance
.For jumbo transactions, ensure the payer’s key is included and
maxGasAllowance
is set high enough to cover potential gas and fees.
Transaction Fees
The total transaction cost includes:
Base transaction fee
Gas for
callData
, (calculated as:4 × zero bytes + 16 × non-zero bytes
)Execution gas determined by EVM smart contract logic
📣 See the transaction and query fees table and the smart contracts gas and fees page for details.
setEthereumData(<ethereumData>)
byte []
setCallDataFileId(<fileId>)
FileID
setMaxGasAllowanceHbar(<maxGasAllowanceHbar>)
Hbar
//Create the transaction
EthereumTransaction transaction = new EthereumTransaction()
.setEthereumData(ethereumData)
.setMaxGasAllowanceHbar(allowance);
//Sign with the client operator private key to pay for the transaction and submit the query to a Hedera network
TransactionResponse txResponse = transaction.execute(client);
//Request the receipt of the transaction
TransactionReceipt receipt = txResponse.getReceipt(client);
//Get the transaction consensus status
Status transactionStatus = receipt.status;
System.out.println("The transaction consensus status is " +transactionStatus);
//v2.14
Last updated
Was this helpful?