diff --git a/docs.json b/docs.json index 392d16b0..0a122874 100644 --- a/docs.json +++ b/docs.json @@ -2264,6 +2264,7 @@ "evm/development/creating", "evm/development/compiling", "evm/development/deploying", + "evm/development/eoa-code-delegation", "evm/development/verifying", "evm/development/gas-fees", "evm/development/rent", diff --git a/evm/development/deploying.mdx b/evm/development/deploying.mdx index 73050c2b..e370ec59 100644 --- a/evm/development/deploying.mdx +++ b/evm/development/deploying.mdx @@ -3,11 +3,13 @@ title: "Deploying Smart Contracts" --- -After compiling your smart contract, you can deploy it to the Hedera network. The constructor's "*init code*" includes the contract's entire bytecode. When deploying, the EVM is expected to be supplied with both the smart contract [bytecode](/support/glossary#bytecode) and the gas required to execute and deploy the contract. Post-deployment, the constructor is removed, leaving only the `runtime_bytecode` for future contract interactions. +After compiling your smart contract, you can deploy it to the Hedera network. The deployment payload, or "*init code*", contains the constructor logic together with the contract's runtime bytecode. When deploying, the EVM is expected to be supplied with both the smart contract [bytecode](/support/glossary#bytecode) and the gas required to execute and deploy the contract. The constructor runs once during deployment and returns the `runtime_bytecode`, which is what's stored on-chain for future contract interactions. **➡** [**Hyperledger Besu EVM**](#hyperledger-besu-evm-on-hedera) -**➡** [**Cancun Hard Fork**](#cancun-hard-fork) +**➡** [**Pectra Hard Fork**](#pectra-hard-fork) + +**➡** [**Past Hard Forks**](#past-hard-forks) **➡** [**Solidity Variables and Opcodes**](#solidity-variables-and-opcodes) @@ -19,15 +21,17 @@ The [Ethereum Virtual Machine (EVM)](/support/glossary#ethereum-virtual-machine- On Hedera, users can interact with the EVM-compatible environment in several ways. They can submit `ContractCreate`, `EthereumTransaction`, or make `eth_sendRawTransaction` RPC calls with the contract bytecode directly. These various paths allow developers to deploy and manage smart contracts efficiently. -When the EVM receives the bytecode, it will be further broken down into operation codes ([opcodes](/support/glossary#opcodes)). The EVM opcodes represent the specific instructions it can perform. Each opcode is one byte and has its own gas cost associated with it. The cost per opcode for the Ethereum Cancun hard fork can be found [here](https://www.evm.codes/?fork=cancun). +When the EVM receives the bytecode, it will be further broken down into operation codes ([opcodes](/support/glossary#opcodes)). The EVM opcodes represent the specific instructions it can perform. Each opcode is one byte and has its own gas cost associated with it. The cost per opcode for the Ethereum Pectra hard fork (Prague EVM execution layer) can be found [here](https://www.evm.codes/?fork=prague). #### Smart Contract Opcode Example -```solidity + +```text wrap PUSH1 0x80 PUSH1 0x40 MSTORE CALLVALUE DUP1 ISZERO PUSH2 0x10 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x40 MLOAD PUSH2 0x558 CODESIZE SUB DUP1 PUSH2 0x558 DUP4 CODECOPY DUP2 DUP2 ADD PUSH1 0x40 MSTORE PUSH1 0x20 DUP2 LT ISZERO PUSH2 0x33 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP2 ADD SWAP1 DUP1 DUP1 MLOAD PUSH1 0x40 MLOAD SWAP4 SWAP3 SWAP2 SWAP1 DUP5 PUSH5 0x100000000 DUP3 GT ISZERO PUSH2 0x53 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP4 DUP3 ADD SWAP2 POP PUSH1 0x20 DUP3 ADD DUP6 DUP2 GT ISZERO PUSH2 0x69 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP3 MLOAD DUP7 PUSH1 0x1 DUP3 MUL DUP4 ADD GT PUSH5 0x100000000 DUP3 GT OR ISZERO PUSH2 0x86 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP1 DUP4 MSTORE PUSH1 0x20 DUP4 ADD SWAP3 POP POP POP SWAP1 DUP1 MLOAD SWAP1 PUSH1 0x20 ADD SWAP1 DUP1 DUP4 DUP4 PUSH1 0x0 JUMPDEST DUP4 DUP2 LT ISZERO PUSH2 0xBA JUMPI DUP1 DUP3 ADD MLOAD DUP2 DUP5 ADD MSTORE PUSH1 0x20 DUP2 ADD SWAP1 POP PUSH2 0x9F JUMP JUMPDEST POP POP POP POP SWAP1 POP SWAP1 DUP2 ADD SWAP1 PUSH1 0x1F AND DUP1 ISZERO PUSH2 0xE7 JUMPI DUP1 DUP3 SUB DUP1 MLOAD PUSH1 0x1 DUP4 PUSH1 0x20 SUB PUSH2 0x100 EXP SUB NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP JUMPDEST POP PUSH1 0x40 MSTORE POP POP POP CALLER PUSH1 0x0 DUP1 PUSH2 0x100 EXP DUP2 SLOAD DUP2 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MUL NOT AND SWAP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND MUL OR SWAP1 SSTORE POP DUP1 PUSH1 0x1 SWAP1 DUP1 MLOAD SWAP1 PUSH1 0x20 ADD SWAP1 PUSH2 0x144 SWAP3 SWAP2 SWAP1 PUSH2 0x14B JUMP JUMPDEST POP POP PUSH2 0x1E8 JUMP JUMPDEST DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 KECCAK256 SWAP1 PUSH1 0x1F ADD PUSH1 0x20 SWAP1 DIV DUP2 ADD SWAP3 DUP3 PUSH1 0x1F LT PUSH2 0x18C JUMPI DUP1 MLOAD PUSH1 0xFF NOT AND DUP4 DUP1 ADD OR DUP6 SSTORE PUSH2 0x1BA JUMP JUMPDEST DUP3 DUP1 ADD PUSH1 0x1 ADD DUP6 SSTORE DUP3 ISZERO PUSH2 0x1BA JUMPI SWAP2 DUP3 ADD JUMPDEST DUP3 DUP2 GT ISZERO PUSH2 0x1B9 JUMPI DUP3 MLOAD DUP3 SSTORE SWAP2 PUSH1 0x20 ADD SWAP2 SWAP1 PUSH1 0x1 ADD SWAP1 PUSH2 0x19E JUMP JUMPDEST JUMPDEST POP SWAP1 POP PUSH2 0x1C7 SWAP2 SWAP1 PUSH2 0x1CB JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST JUMPDEST DUP1 DUP3 GT ISZERO PUSH2 0x1E4 JUMPI PUSH1 0x0 DUP2 PUSH1 0x0 SWAP1 SSTORE POP PUSH1 0x1 ADD PUSH2 0x1CC JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST PUSH2 0x361 DUP1 PUSH2 0x1F7 PUSH1 0x0 CODECOPY PUSH1 0x0 RETURN INVALID PUSH1 0x80 PUSH1 0x40 MSTORE CALLVALUE DUP1 ISZERO PUSH2 0x10 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST POP PUSH1 0x4 CALLDATASIZE LT PUSH2 0x36 JUMPI PUSH1 0x0 CALLDATALOAD PUSH1 0xE0 SHR DUP1 PUSH4 0x2E982602 EQ PUSH2 0x3B JUMPI DUP1 PUSH4 0x32AF2EDB EQ PUSH2 0xF6 JUMPI JUMPDEST PUSH1 0x0 DUP1 REVERT JUMPDEST PUSH2 0xF4 PUSH1 0x4 DUP1 CALLDATASIZE SUB PUSH1 0x20 DUP2 LT ISZERO PUSH2 0x51 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP2 ADD SWAP1 DUP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 PUSH5 0x100000000 DUP2 GT ISZERO PUSH2 0x6E JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP3 ADD DUP4 PUSH1 0x20 DUP3 ADD GT ISZERO PUSH2 0x80 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP2 DUP5 PUSH1 0x1 DUP4 MUL DUP5 ADD GT PUSH5 0x100000000 DUP4 GT OR ISZERO PUSH2 0xA2 JUMPI PUSH1 0x0 DUP1 REVERT JUMPDEST SWAP2 SWAP1 DUP1 DUP1 PUSH1 0x1F ADD PUSH1 0x20 DUP1 SWAP2 DIV MUL PUSH1 0x20 ADD PUSH1 0x40 MLOAD SWAP1 DUP2 ADD PUSH1 0x40 MSTORE DUP1 SWAP4 SWAP3 SWAP2 SWAP1 DUP2 DUP2 MSTORE PUSH1 0x20 ADD DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY PUSH1 0x0 DUP2 DUP5 ADD MSTORE PUSH1 0x1F NOT PUSH1 0x1F DUP3 ADD AND SWAP1 POP DUP1 DUP4 ADD SWAP3 POP POP POP POP POP POP POP SWAP2 SWAP3 SWAP2 SWAP3 SWAP1 POP POP POP PUSH2 0x179 JUMP JUMPDEST STOP JUMPDEST PUSH2 0xFE PUSH2 0x1EC JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP1 PUSH1 0x20 ADD DUP3 DUP2 SUB DUP3 MSTORE DUP4 DUP2 DUP2 MLOAD DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP DUP1 MLOAD SWAP1 PUSH1 0x20 ADD SWAP1 DUP1 DUP4 DUP4 PUSH1 0x0 JUMPDEST DUP4 DUP2 LT ISZERO PUSH2 0x13E JUMPI DUP1 DUP3 ADD MLOAD DUP2 DUP5 ADD MSTORE PUSH1 0x20 DUP2 ADD SWAP1 POP PUSH2 0x123 JUMP JUMPDEST POP POP POP POP SWAP1 POP SWAP1 DUP2 ADD SWAP1 PUSH1 0x1F AND DUP1 ISZERO PUSH2 0x16B JUMPI DUP1 DUP3 SUB DUP1 MLOAD PUSH1 0x1 DUP4 PUSH1 0x20 SUB PUSH2 0x100 EXP SUB NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP JUMPDEST POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST PUSH1 0x0 DUP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND CALLER PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND EQ PUSH2 0x1D1 JUMPI PUSH2 0x1E9 JUMP JUMPDEST DUP1 PUSH1 0x1 SWAP1 DUP1 MLOAD SWAP1 PUSH1 0x20 ADD SWAP1 PUSH2 0x1E7 SWAP3 SWAP2 SWAP1 PUSH2 0x28E JUMP JUMPDEST POP JUMPDEST POP JUMP JUMPDEST PUSH1 0x60 PUSH1 0x1 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 PUSH1 0x1F ADD PUSH1 0x20 DUP1 SWAP2 DIV MUL PUSH1 0x20 ADD PUSH1 0x40 MLOAD SWAP1 DUP2 ADD PUSH1 0x40 MSTORE DUP1 SWAP3 SWAP2 SWAP1 DUP2 DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 ISZERO PUSH2 0x284 JUMPI DUP1 PUSH1 0x1F LT PUSH2 0x259 JUMPI PUSH2 0x100 DUP1 DUP4 SLOAD DIV MUL DUP4 MSTORE SWAP2 PUSH1 0x20 ADD SWAP2 PUSH2 0x284 JUMP JUMPDEST DUP3 ADD SWAP2 SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 KECCAK256 SWAP1 JUMPDEST DUP2 SLOAD DUP2 MSTORE SWAP1 PUSH1 0x1 ADD SWAP1 PUSH1 0x20 ADD DUP1 DUP4 GT PUSH2 0x267 JUMPI DUP3 SWAP1 SUB PUSH1 0x1F AND DUP3 ADD SWAP2 JUMPDEST POP POP POP POP POP SWAP1 POP SWAP1 JUMP JUMPDEST DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 KECCAK256 SWAP1 PUSH1 0x1F ADD PUSH1 0x20 SWAP1 DIV DUP2 ADD SWAP3 DUP3 PUSH1 0x1F LT PUSH2 0x2CF JUMPI DUP1 MLOAD PUSH1 0xFF NOT AND DUP4 DUP1 ADD OR DUP6 SSTORE PUSH2 0x2FD JUMP JUMPDEST DUP3 DUP1 ADD PUSH1 0x1 ADD DUP6 SSTORE DUP3 ISZERO PUSH2 0x2FD JUMPI SWAP2 DUP3 ADD JUMPDEST DUP3 DUP2 GT ISZERO PUSH2 0x2FC JUMPI DUP3 MLOAD DUP3 SSTORE SWAP2 PUSH1 0x20 ADD SWAP2 SWAP1 PUSH1 0x1 ADD SWAP1 PUSH2 0x2E1 JUMP JUMPDEST JUMPDEST POP SWAP1 POP PUSH2 0x30A SWAP2 SWAP1 PUSH2 0x30E JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST JUMPDEST DUP1 DUP3 GT ISZERO PUSH2 0x327 JUMPI PUSH1 0x0 DUP2 PUSH1 0x0 SWAP1 SSTORE POP PUSH1 0x1 ADD PUSH2 0x30F JUMP JUMPDEST POP SWAP1 JUMP INVALID LOG2 PUSH5 0x6970667358 0x22 SLT KECCAK256 AND DIFFICULTY CHAINID 0x5F 0x5F PUSH20 0xDFD73A518B57770F5ADB27F025842235980D7A0F 0x4E ISZERO 0xB1 0xAC 0xB1 DUP15 PUSH5 0x736F6C6343 STOP SMOD STOP STOP CALLER ``` + -Reference: https://ethervm.io/ +Reference: [ethervm.io](https://ethervm.io/) *** @@ -59,7 +63,7 @@ If you need to set any of the above properties for your contract, you will have ### Deploying Large Contracts -Hedera supports **jumbo Ethereum transactions (**[**HIP-1086**](https://hips.hedera.com/hip/hip-1086)**)** for large bytecode payloads. You can include up to **24KB for contract creation** and **128KB for contract calls** directly in `ethereumData`, without using the File Service (`callDataFileId`). +Hedera supports **jumbo Ethereum transactions (**[**HIP-1086**](https://hips.hedera.com/hip/hip-1086)**)** for large bytecode payloads, letting you include `callData` directly in `ethereumData` without using the File Service (`callDataFileId`). The exact ceilings are **network-configurable parameters**, not fixed protocol constants; current values are on the order of **~24KB for contract creation** (the [EIP-170](https://eips.ethereum.org/EIPS/eip-170) code-size limit) and **~128KB for contract calls**. Check the active network configuration for the precise limits. However, jumbo transactions: @@ -70,9 +74,8 @@ However, jumbo transactions: When deploying contracts, gas must cover both intrinsic gas and the cost of executing deployment code. Intrinsic gas includes a base fee (21,000) plus a per-byte cost for `callData`: -* Intrinsic gas includes a base fee (21,000) plus a per-byte cost for `callData`: - * 4 gas per zero byte - * 16 gas per non-zero byte +* 4 gas per zero byte +* 16 gas per non-zero byte #### Example @@ -82,43 +85,104 @@ If your contract bytecode is 10KB, with 20% (2KB) as zero bytes and 80% (8KB) as * **gas for non-zero bytes**: 16 × 8,192 = 131,072 * **total intrinsic gas** = 21,000 + 8,192 + 131,072 = 160,264 -Ensure you adjust `gasLimit` (RLP) and `maxGasAllowance` (wrapper) to cover this total gas. +Under Pectra, the transaction also has to satisfy the [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623) calldata floor: `21000 + 10 × (zero + 4 × non_zero)`. For this example that floor is `21,000 + 10 × (2,048 + 4 × 8,192) = 369,160` gas, well above the 160,264 intrinsic figure. The deployment pays whichever is greater: the intrinsic **plus execution** total, or the floor. In practice deployment execution includes the code-deposit charge (200 gas per byte of runtime bytecode, roughly 2M gas for a 10KB contract), which pushes the standard total far past the floor, so the floor mainly matters for calldata-heavy transactions with little execution work. -📣 Learn more on the [Gas and Fees page,](/evm/development/gas-fees) [EthereumTransaction SDK page](/native/smart-contracts/ethereum-transaction), and the [Understanding Hedera's EVM Differences and Compatibility page](/evm/differences). +Ensure you adjust `gasLimit` (RLP) and `maxGasAllowance` (wrapper) to cover this total gas. + + 📣 Learn more on the [Gas and Fees page,](/evm/development/gas-fees) [`EthereumTransaction` SDK page](/native/smart-contracts/ethereum-transaction), and the [Understanding Hedera's EVM Differences and Compatibility page](/evm/differences). + *** ## Hyperledger Besu EVM on Hedera The Hedera network nodes utilize the [HyperLedger Besu EVM ](/support/glossary#hyperledger-besu-evm)Client written in Java as an execution layer for Ethereum-type transactions. The codebase is up to date with the current Ethereum Mainnet hard forks. The Besu EVM client library is used without hooks for Ethereum's consensus, networking, and storage features. Instead, Hedera hooks into its own Hashgraph consensus, Gossip communication, and [Virtual Merkle Trees](/support/glossary#virtual-merkle-tree) components for greater fault tolerance, finality, and scalability. -As of the Hedera Mainnet release [`0.50.0`](/learn/release-notes/services#v0.50), the Besu EVM client is configured to support the Cancun hard fork of the Ethereum Mainnet, with some modifications. +The Besu EVM client is configured to support the **Pectra hard fork** of the Ethereum Mainnet (activated May 7, 2025), with some modifications. Pectra was originally introduced on Hedera under [HIP-1340](https://hips.hedera.com/hip/hip-1340) ([EOA Code Delegation](/evm/development/eoa-code-delegation)) and [HIP-1341](https://hips.hedera.com/hip/hip-1341) (Support for Ethereum Pectra Release). + +### **Pectra Hard Fork** + +The smart contract platform has been upgraded to support the visible EVM changes introduced in the [Pectra](https://eips.ethereum.org/EIPS/eip-7600) hard fork (Prague execution layer + Electra consensus layer). The applicable EIPs adopted on Hedera are: + +| EIP | Title | Summary | +| ---------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | +| [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) | BLS12-381 curve precompiles | Adds precompiles at addresses `0x0b`–`0x11` for efficient BLS signature/pairing operations. | +| [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623) | Increase calldata cost (floor) | Introduces a calldata gas floor: `21000 + 10 × (zero_bytes + 4 × non_zero_bytes)`. | +| [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | Set EOA account code | Adds a new transaction type (Type 4) allowing EOAs to delegate execution to a contract. See [EOA Code Delegation](/evm/development/eoa-code-delegation). | + +The following Pectra EIPs are **not applicable** to Hedera and are not adopted: EIP-7691, EIP-7840 (blob-related, Hedera does not support blobs), EIP-6110, EIP-7002, EIP-7251, EIP-7685 (Ethereum validator features, no Hedera equivalent), EIP-2935, EIP-7549 (Ethereum 2.0 features), EIP-7642 (informational). Per [HIP-1341](https://hips.hedera.com/hip/hip-1341). + +As of the Consensus Node [0.22](/learn/release-notes/services#v0.22) release ([HIP-185](https://hips.hedera.com/hip/hip-185)), gas and input data costs are charged. The amount of intrinsic gas consumed is a constant charge that occurs before any code executes. _The intrinsic gas cost is `21,000`_. The associated cost of input data is 16 gas for each byte of data that is not zero and 4 gas for each byte of data that is zero. Under Pectra (EIP-7623), an additional floor of `21000 + 10 × (zero + 4 × non_zero)` applies to calldata-heavy transactions. The amount of intrinsic gas consumed is charged in relation to the data supplied when making a contract call to the function parameters of external contracts. The gas schedule and the fees table can be found in the gas section of this documentation page. + +#### Supported Ethereum Transaction Types -### **Cancun Hard Fork** +`EthereumTransaction` accepts RLP-encoded payloads for all of the following types: -The smart contract platform has been upgraded to support the visible EVM changes introduced in the [Cancun](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md) hard fork. This includes adding new opcodes for transient storage and memory copy, semantic updates for opcodes introduced certain operations introduced in the [Shanghai](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/shanghai.md), [London](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/london.md), [Istanbul](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/istanbul.md), and [Berlin](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md) hard forks, except those with changes in block production, data serialization, and the double fee market. +| Type | Spec | Description | +| :--: | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `0` | Legacy ([EIP-155](https://eips.ethereum.org/EIPS/eip-155)) | Pre-Berlin legacy transactions. | +| `1` | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) | Optional `access_list` to pre-warm storage slots and addresses. | +| `2` | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) | `max_fee_per_gas` + `max_priority_fee_per_gas` (priority fee is ignored on Hedera; fees are fixed by the network). | +| `4` | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) (Pectra) | Adds an `authorization_list` for EOA code delegation. See [EOA Code Delegation](/evm/development/eoa-code-delegation). | -As of the Consensus Node [0.22](/learn/release-notes/services#v0.22) release, gas and input data costs are charged. The amount of intrinsic gas consumed is a constant charge that occurs before any code executes. The intrinsic gas cost is 21,000. The associated cost of input data is 16 gas for each byte of data that is not zero and 4 gas for each byte of data that is zero. The amount of intrinsic gas consumed is charged in relation to the data supplied when making a contract call to the function parameters of external contracts. The gas schedule and the fees table can be found in the gas section of this documentation page. +Type 3 (blob transactions per EIP-4844) is **not supported** on Hedera (see [HIP-866](https://hips.hedera.com/hip/hip-866)). -#### Proto-Danksharding +#### Blobs supported on Hedera? -As an interim solution to full sharding, introduced in the Cancun hard fork, the proto-danksharding offers some of the advantages of sharding with reduced complexity and infrastructure changes that are part of a sharding implementation. This, in turn, opens the gates for adding "blobs" of data to append to blocks to increase data availability further and allow more processing efficiency. +Hedera does not provide blobs under [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) (Cancun), nor under the Pectra blob-throughput EIPs ([EIP-7691](https://eips.ethereum.org/EIPS/eip-7691), [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840)). [HIP-866](https://hips.hedera.com/hip/hip-866) defines how Hedera behaves without blob support. To preserve compatibility and future design space, Hedera acts as if blobs are not being added. This allows existing contracts that depend on blob behavior to function without blobs. Blobs are prevented from entering the system by prohibiting "Type 3" transactions, which enable blobs. This keeps blobs out of the EVM's concern without affecting other desirable interactions on Hedera. With jumbo `EthereumTransaction` support ([HIP-1086](https://hips.hedera.com/hip/hip-1086)) on Hedera, large `callData` payloads are the preferred path for rollup-style data. -Blobs are big data objects within blocks. These can be utilized to store rollups (Layer 2 solutions) and different kinds of apps requiring big data objects to be stored in an efficient way. This is data off-chain for the validators and requires minimal processing on their part. It reduces the computational load on the network and hence reduces the transaction gas fee. +### **Past Hard Forks** -#### ❌ Blobs supported on Hedera? +Hedera tracks Ethereum mainnet hard forks and adopts the EIPs that apply to the Smart Contract Service. The table below summarizes recent forks and the practical differences between them on Hedera. -Hedera does not provide blobs under [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844). [HIP-866](https://hips.hedera.com/hip/hip-866) defines how Hedera behaves without blob support. To preserve compatibility and future design space, Hedera will act as if blobs are not being added. This allows existing contracts dependent on blob behavior to function without blobs. Blobs will be prevented from entering the system by prohibiting "Type 3" transactions, which enable blobs. This will keep blobs out of the EVM's concern without affecting other desirable interactions on Hedera. +| Fork (Ethereum activation) | First adopted on Hedera | Headline changes on Hedera | +| -------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Pectra** (May 7, 2025) | [HIP-1340](https://hips.hedera.com/hip/hip-1340), [HIP-1341](https://hips.hedera.com/hip/hip-1341) | • [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537): BLS12-381 precompiles (`0x0b`–`0x11`).
• [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623): calldata gas floor.
• [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702): new **Type 4** `EthereumTransaction` and `authorization_list` enabling EOA code delegation. | +| **Cancun** (Mar 13, 2024) | Mainnet release [`v0.50`](/learn/release-notes/services#v0.50) | • New opcodes `TLOAD`/`TSTORE` (transient storage), `MCOPY`, `BLOBHASH`, `BLOBBASEFEE`.
• `SELFDESTRUCT` semantics updated per [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780).
• Blob support (EIP-4844) **not** adopted; Type 3 transactions are rejected ([HIP-866](https://hips.hedera.com/hip/hip-866)). | +| **Shanghai** (Apr 12, 2023)| Mainnet release [`v0.38`](/learn/release-notes/services#v0.38) | • `PUSH0` opcode.
• Updated `INITCODE` cost for contract creation. | -### Solidity Variables and Opcodes +#### What changed from Cancun to Pectra? + +If you previously targeted Cancun, the practical differences on Hedera are: + +1. **New transaction type: Type 4.** The `EthereumTransaction` HAPI message now accepts RLP-encoded Type 4 payloads carrying an `authorization_list`. Each authorization sets a `delegation_address` on the signing EOA, causing future EVM calls to that EOA to execute the target contract's bytecode in the EOA's storage context (similar to `DELEGATECALL`). Full details in [EOA Code Delegation](/evm/development/eoa-code-delegation). +2. **EOA bytecode is no longer always empty.** Pre-Pectra, `eth_getCode(eoa)` always returned empty. After Pectra, an EOA with delegation set returns the **Delegation Indicator** `0xef0100 || <20-byte target address>`. EOAs may now also have non-empty storage slots and emit logs. +3. **Calldata floor (EIP-7623).** Calldata-heavy transactions must now pay at least `21000 + 10 × (zero_bytes + 4 × non_zero_bytes)`. Standard contract calls (where execution gas dominates) are unaffected. +4. **BLS12-381 precompiles (EIP-2537).** Seven new precompiles at addresses `0x0b`–`0x11` for G1/G2 add, multi-scalar multiplication, pairing check, and field-to-curve mapping. These make BLS aggregation, threshold signatures, and zk-friendly cryptography native (no Solidity gymnastics). +5. **HTS/HSS facade calls re-implemented as Delegation Indicators.** Token and Schedule "proxy" accounts now return a fixed Delegation Indicator pointing at the corresponding system contract instead of dynamic synthesized bytecode. User-visible behavior is unchanged, but tools that inspect the bytecode of these proxy accounts will now see a consistent `0xef0100...`-prefixed value rather than a custom `DELEGATECALL` shim. +6. **HAS precedence rules.** When an EOA has a code delegation set, calls whose 4-byte selector matches a [Hedera Account Service](/evm/hedera-services/system-contracts/account-service) facade function (`hbarAllowance`, `hbarApprove`, `setUnlimitedAutomaticAssociations`) are routed to HAS and take precedence over the user's delegation. Be aware of potential selector collisions when designing a smart-account delegate. -The table below defines the mapping of Solidity variables and operation codes to Hedera. The full list of supported Opcodes for the Cancun hard fork can be found [here](https://www.evm.codes/). +> Blobs (EIP-4844 / EIP-7691 / EIP-7840) remain unsupported on Hedera. Type 3 transactions are rejected. + +### Solidity Variables and Opcodes -
SolidityOpcodeHedera
addressThe address is a mapping of shard.realm.number (0.0.10) into a 20 byte Solidity address. The address can be a Hedera account ID or contract ID in Solidity format.
block.basefeeBASEFEEThe BASEFEE opcode will return zero. Hedera does not use the Fee Market mechanism this is designed to support.
block.chainIdCHAINIDThe CHAINID opcode will return 295(hex 0x0127) for mainnet, 296( hex 0x0128) for testnet, 297( hex 0x0129) for previewnet, and 298 (0x12A) for development networks.
block.coinbaseCOINBASEThe COINBASE operation will return the funding account (Hedera transaction fee collecting account 0.0.98).
block.numberThe index of the record file (not recommended, use block.timestamp).
block.timestampThe transaction consensus timestamp.
block.difficultyAlways zero.
block.gaslimitGASLIMITThe GASLIMIT operation will return the gasLimit of the transaction. The transaction gasLimit will be the lowest of the gas limit requested in the transaction or a global upper gas limit configured for all smart contracts.
msg.senderThe address of the Hedera contract ID or account ID in Solidity format that called this contract. For the root level or for delegate chains that go to the root, it is the account ID paying for the transaction.
msg.valueThe value associated to the transaction associated in tinybar.
tx.originThe account ID paying for the transaction, regardless of depth.
tx.gaspriceFixed (varies with the global fee schedule and exchange rate).

selfdestruct

(address payable recipient)

SELFDESTRUCTAddress will not be reusable due to Hedera’s account numbering policies. On SELFDESTRUCT the contracts HBAR and HTS tokens are transferred to the recipients. If the recipient does not exist or does not have an allowance for any of the HTS tokens, this opcode will fail.
<address>.codePrecompile contract addresses will report no code, including HTS System contract.
<address>.codehashPrecompile contract addresses will report the empty code hash.
PRNGSEEDThis opcode returns a random number based on the n-3 record running hash.
delegateCallContracts may no longer use delegateCall() to invoke system contracts. Contracts should instead use the call() method.
blobVersionedHashesAtIndexBLOBHASHThe BLOBHASH operation will return all zeros at all times.
blobBaseFeeBLOBBASEFEE

The BLOBBASEFEE operation will return

1 at all times.

+The table below defines the mapping of Solidity variables and operation codes to Hedera. The full list of supported Opcodes for the Pectra hard fork (Prague EVM execution layer) can be found [here](https://www.evm.codes/?fork=prague). + +| Solidity | Opcode | Hedera | +| :---: | :---: | --- | +| `address` | | The address is a mapping of shard.realm.number (0.0.10) into a 20 byte Solidity address. The address can be a Hedera account ID or contract ID in Solidity format. | +| `block.basefee` | `BASEFEE` | The `BASEFEE` opcode will return zero. Hedera does not use the Fee Market mechanism this is designed to support. | +| `block.chainid` | `CHAINID` | The `CHAINID` opcode will return 295(hex `0x0127`) for mainnet, 296( hex `0x0128`) for testnet, 297( hex `0x0129`) for previewnet, and 298 (`0x12A`) for development networks. | +| `block.coinbase` | `COINBASE` | The `COINBASE` operation will return the funding account (Hedera transaction fee collecting account `0.0.98`). | +| `block.number` | | The index of the record file (not recommended, use `block.timestamp`). | +| `block.timestamp` | | The transaction consensus timestamp. | +| `block.difficulty` | | Always zero. | +| `block.gaslimit` | `GASLIMIT` | The `GASLIMIT` operation will return the `gasLimit` of the transaction. The transaction `gasLimit` will be the lowest of the gas limit requested in the transaction or a global upper gas limit configured for all smart contracts. | +| `msg.sender` | | The address of the Hedera contract ID or account ID in Solidity format that called this contract. For the root level or for delegate chains that go to the root, it is the account ID paying for the transaction. | +| `msg.value` | | The value associated to the transaction associated in tinybar. | +| `tx.origin` | | The account ID paying for the transaction, regardless of depth. | +| `tx.gasprice` | | Fixed (varies with the global fee schedule and exchange rate). | +| `selfdestruct`
`(address payable recipient)` | `SELFDESTRUCT` | Address will not be reusable due to Hedera’s account numbering policies. On `SELFDESTRUCT` the contracts HBAR and HTS tokens are transferred to the recipients. If the recipient does not exist or does not have an allowance for any of the HTS tokens, this opcode will fail. | +| `
.code` | | Precompile and system-contract addresses (including the HTS system contract at `0x167`) report no code. Under Pectra ([HIP-1340](https://hips.hedera.com/hip/hip-1340)), HTS token and HSS schedule proxy addresses, and EOAs with a code delegation set, report a 23-byte `0xef0100…` Delegation Indicator instead of empty code. See [EOA Code Delegation](/evm/development/eoa-code-delegation). | +| `
.codehash` | | Precompile contract addresses will report the empty code hash. | +| | PRNG system contract (`0x169`) | There is no PRNG opcode. Per [HIP-351](https://hips.hedera.com/hip/hip-351), contracts call `getPseudorandomSeed()` on the PRNG system contract at `0x169`, which returns a 256-bit seed derived from the n-3 record running hash. | +| `delegateCall` | | Contracts may no longer use `delegateCall()` to invoke system contracts. Contracts should instead use the `call()` method. | +| `blobVersionedHashesAtIndex` | `BLOBHASH` | The `BLOBHASH` operation will return all zeros at all times. | +| `blobBaseFee` | `BLOBBASEFEE` | The `BLOBBASEFEE` operation will return
`1` at all times. | Reference: [HIP-866](https://hips.hedera.com/hip/hip-866), [HIP-868](https://hips.hedera.com/hip/hip-868) @@ -150,30 +214,30 @@ Understanding these differences is crucial for anyone developing smart contracts Yes, you can use Solidity functions directly with the Hedera EVM. However, refer to the [Solidity Variables and Opcodes](#solidity-variables-and-opcodes) table to understand any modifications to opcode descriptions that better reflect their behavior on the Hedera network. - -Yes, hedera supports jumbo ethereum transactions (HIP-1086), allowing up to **24kb for contract creation** and **128kb for contract calls**. this eliminates the need for uploading bytecode to the file service in most cases. [Learn more](/evm/differences#jumbo-ethereum-transactions). - - - -No, jumbo ethereum transactions cannot be included in a `TransactionList` (batch). each jumbo transaction must be submitted individually. + +Yes. Hedera supports jumbo Ethereum transactions ([HIP-1086](https://hips.hedera.com/hip/hip-1086)), which carry `callData` directly in `ethereumData` and remove the need to upload bytecode to the File Service in most cases. Note that jumbo transactions cannot be included in a `TransactionList` (batch); each one must be submitted individually. See [Deploying Large Contracts](#deploying-large-contracts) for the current size ceilings and throttling details. Gas covers intrinsic costs (base + per-byte of `callData`) and execution costs (opcodes run by the EVM). Ensure your `gasLimit` and `maxGasAllowance` cover the total. See the [gas and fees page](/evm/development/gas-fees) for details. - + Hedera does not trigger `fallback()` or `receive()` functions on HBAR transfers. Balances may change through native operations, so use explicit functions to handle HBAR. [Learn more](#limitation-on-fallback-receive-functions-in-hedera-smart-contracts). - + Yes, but Hardhat cannot set Hedera-native properties like admin key or token associations. For these, use the [Hedera SDK](/native/fundamentals). -If your contract relies on blob-related opcodes introduced in the Cancun hard fork, you can still deploy it on Hedera. The blob-related opcodes **will** **not** fail. They'll return default values as [specified by the EVM](https://www.evm.codes/?fork=cancun). +If your contract relies on blob-related opcodes introduced in the Cancun hard fork (`BLOBHASH`, `BLOBBASEFEE`), you can still deploy it on Hedera. The blob-related opcodes **will not** fail; they return default values (`0` and `1` respectively) as [specified by the EVM](https://www.evm.codes/?fork=prague). Blob transactions themselves (Type 3) remain unsupported. -Yes, while the Hedera EVM supports the updated opcodes from the Cancun hard fork, you should know the intrinsic gas costs and input data charges specific to Hedera. Refer to the [gas schedule and fees](/evm/development/gas-fees) table for more information. +Yes, while the Hedera EVM supports the updated opcodes from the Pectra hard fork (including Cancun-era `TLOAD`/`TSTORE`/`MCOPY` and Pectra-era BLS12-381 precompiles), you should know the intrinsic gas costs and input data charges specific to Hedera, including the EIP-7623 calldata floor. Refer to the [gas schedule and fees](/evm/development/gas-fees) table for more information. + + + +Yes. Hedera supports Type 4 `EthereumTransaction` payloads under [HIP-1340](https://hips.hedera.com/hip/hip-1340). You can also configure EOA code delegation via native `CryptoCreate` / `CryptoUpdate` transactions. See the [EOA Code Delegation](/evm/development/eoa-code-delegation) page for both paths and the HAS precedence rules. diff --git a/evm/development/eoa-code-delegation.mdx b/evm/development/eoa-code-delegation.mdx new file mode 100644 index 00000000..4c461591 --- /dev/null +++ b/evm/development/eoa-code-delegation.mdx @@ -0,0 +1,455 @@ +--- +title: "EOA Code Delegation" +description: "Set, execute, and clear code on an Externally Owned Account using EIP-7702 (EVM) or native CryptoUpdate (HAPI). Covers Hedera Account Service (HAS) precedence, smart-account patterns, and Hedera-specific gas rules." +--- + + +**EOA Code Delegation** lets an Externally Owned Account (EOA) point at a contract whose code will execute *in the EOA's own context* whenever the EOA is called, similar to how `DELEGATECALL` runs Contract B's code inside Contract A's storage frame. It is Hedera's adoption of Ethereum's [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702), defined for Hedera by [HIP-1340](https://hips.hedera.com/hip/hip-1340) and rolled out as part of the [Pectra hard fork](https://hips.hedera.com/hip/hip-1341). + +Delegation unlocks **smart-account** use cases (transaction batching, sponsored gas, session keys, privilege de-escalation) without migrating funds to a new contract wallet; the EOA's address, balance, NFTs, and tokens stay put. + +*** + +## How delegation is stored + +The `Account` entity gains a new optional 20-byte field, `delegation_address`. When set, calls to the EOA's address resolve to the code at `delegation_address`. + +For Ethereum-tool compatibility, the Smart Contract Service exposes the delegation as a **Delegation Indicator** in the EOA's `code` field: + +``` +delegation_indicator = 0xef0100 ‖ <20-byte delegation_address> +``` + +- Before Pectra, `eth_getCode(eoa)` always returned `0x`. +- After Pectra, an EOA with delegation set returns the 23-byte `0xef0100...` indicator. An EOA with no delegation still returns `0x`. +- Regular contract bytecode cannot start with `0xef` (per [EIP-3541](https://eips.ethereum.org/EIPS/eip-3541)), so the prefix is unambiguous. + +A `delegation_address` of `0x0000000000000000000000000000000000000000` **clears** the delegation (the field becomes empty). + +*** + +## Two paths to configure delegation + +You can set, change, or clear an EOA's delegation through either an Ethereum-compatible Type 4 transaction or a native HAPI `CryptoCreate` / `CryptoUpdate`. Both routes converge on the same `delegation_address` field on the account. + +``` + ┌──────────────────────────┐ + │ User / Wallet │ + └────────────┬─────────────┘ + │ + ┌──────────┴──────────┐ + │ │ + ▼ ▼ + ┌───────────────┐ ┌────────────────────┐ + │ EVM path │ │ HAPI path │ + │ EIP-7702 │ │ CryptoCreate / │ + │ Type 4 tx │ │ CryptoUpdate │ + └───────┬───────┘ └──────────┬─────────┘ + │ │ + └───────────┬────────────┘ + ▼ + Account.delegation_address +``` + +### Path A: EVM (Type 4 EthereumTransaction) + +A Type 4 transaction extends the standard RLP-encoded fields with an `authorization_list`: + +``` +transaction_payload = rlp([ + chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, + destination, value, data, access_list, authorization_list, + signature_y_parity, signature_r, signature_s +]) + +authorization_list = [ + [chain_id, address, nonce, y_parity, r, s], + ... +] +``` + +Each entry is an **independent intent**, signed by the EOA that wants delegation set. The signature is recovered with `ecrecover`, and the recovered account's `delegation_address` is set to the entry's `address`. A single Type 4 transaction can authorize delegations for many unrelated EOAs in one shot, and the transaction sender may be a third party (i.e., **sponsored** delegation setup, useful for onboarding flows). + +**Validity rules** (per EIP-7702, enforced by Hedera): + +- Signature must be valid `ecrecover` over `(MAGIC ‖ rlp([chain_id, address, nonce]))`. +- `chain_id` must be `0` (any chain) or match the network's chain ID (296 testnet, 295 mainnet). +- `nonce` must match the authorizing account's current nonce. +- If the authorization list is empty, the transaction is **invalid** and rejected. +- Invalid entries are silently skipped (no revert). +- If multiple valid entries target the same EOA, **only the last one** is applied. + +Each authorization spawns a child `CryptoCreate` (for a brand-new hollow account) or `CryptoUpdate` (for an existing account). These child records appear in the transaction's record stream regardless of whether the parent EVM call reverts; the delegation persists even if the subsequent code execution fails. + +#### JavaScript example (viem) + +There are two common flows: **self-submitted** (the EOA pays for and sends its own delegation transaction) and **sponsored** (a third party pays; the EOA only signs the authorization). + +**Self-submitted** (the EOA owns the gas): + +```javascript JavaScript +import { createWalletClient, http } from "viem"; +import { privateKeyToAccount } from "viem/accounts"; +import { hederaTestnet } from "viem/chains"; + +const eoa = privateKeyToAccount(process.env.EOA_PRIVATE_KEY); +const eoaClient = createWalletClient({ chain: hederaTestnet, transport: http(), account: eoa }); + +// `executor: 'self'` tells viem the EOA will also submit the transaction, +// so the authorization must be signed with the next nonce (current + 1). +const authorization = await eoaClient.signAuthorization({ + contractAddress: "0x", + executor: "self", +}); + +const hash = await eoaClient.sendTransaction({ + authorizationList: [authorization], + to: eoa.address, // can be the EOA itself, the zero address, or any target + data: "0x", // optional follow-up call data (executed after the auth is processed) +}); +``` + +**Sponsored** (a third party pays; the EOA only signs the authorization): + +```javascript JavaScript +import { createWalletClient, http } from "viem"; +import { privateKeyToAccount } from "viem/accounts"; +import { hederaTestnet } from "viem/chains"; + +const eoa = privateKeyToAccount(process.env.EOA_PRIVATE_KEY); +const sponsor = privateKeyToAccount(process.env.SPONSOR_PRIVATE_KEY); + +const eoaClient = createWalletClient({ chain: hederaTestnet, transport: http(), account: eoa }); +const sponsorClient = createWalletClient({ chain: hederaTestnet, transport: http(), account: sponsor }); + +// Omit `executor`; the sponsor submits the transaction, so the EOA's nonce +// is only consumed once (by the authorization itself). +const authorization = await eoaClient.signAuthorization({ + contractAddress: "0x", +}); + +const hash = await sponsorClient.sendTransaction({ + authorizationList: [authorization], + to: eoa.address, + data: "0x", +}); +``` + +After the transaction is mined, calls to `eoa.address` will execute the smart-account implementation's code in the EOA's storage context. To **revoke**, the EOA signs a new authorization with `contractAddress: "0x0000000000000000000000000000000000000000"`. + +#### Submitting via `EthereumTransaction` (Hedera SDK) + +If you have a fully-signed Type 4 RLP payload, you submit it the same way as any other Ethereum transaction: + +```javascript JavaScript +import { EthereumTransaction, Hbar } from "@hashgraph/sdk"; + +const tx = await new EthereumTransaction() + .setEthereumData(rawType4RlpBytes) // raw 0x04 || rlp(...) + .setMaxGasAllowanceHbar(new Hbar(2)) + .execute(client); + +const receipt = await tx.getReceipt(client); +console.log(receipt.status.toString()); +``` + +The SDK also models the Type 4 payload directly via `EthereumTransactionDataEip7702`, which carries the standard EIP-1559-style fields plus `accessList` and an `authorizationList` of `Authorization` entries (`chainId`, `address`, `nonce`, `yParity`, `r`, `s`). Calling `toBytes()` on it produces the raw payload to pass to `setEthereumData()`. + +### Path B: Native HAPI (CryptoCreate / CryptoUpdate) + +[HIP-1340](https://hips.hedera.com/hip/hip-1340) extends both `CryptoCreateTransactionBody` and `CryptoUpdateTransactionBody` with a `delegation_address` field (bytes, 20 raw EVM address bytes, **not** the `0xef0100`-prefixed indicator). The SDK lifts this onto `AccountCreateTransaction` and `AccountUpdateTransaction` as `setDelegationAddress()`, which accepts raw bytes, a hex string (with or without the `0x` prefix), or an `EvmAddress`. + +```javascript JavaScript +import { AccountUpdateTransaction, AccountId } from "@hashgraph/sdk"; + +// Point an existing EOA at a smart-account implementation +const tx = await new AccountUpdateTransaction() + .setAccountId(AccountId.fromString("0.0.4567")) + .setDelegationAddress("0x019b8ee526333d9cbbbc35fff0309794dfa73451") + .freezeWith(client) + .sign(eoaKey); // EOA must sign + +await (await tx.execute(client)).getReceipt(client); + +// Read it back via property access +console.log(`Delegation address: ${tx.delegationAddress?.toString()}`); +``` + +To **clear** the delegation, set it to the zero address (`0x0000000000000000000000000000000000000000`) or pass `null` on an `AccountUpdateTransaction`. + +> Native HAPI is the only path available to **ED25519 accounts** and **ECDSA accounts with a long-zero alias**, since those account types cannot sign EIP-7702 authorizations. See [Account-type applicability](#account-type-applicability). + +*** + +## What happens when a delegated EOA is called + +When the Smart Contract Service processes a call whose target is an EOA address: + +``` +1. Look up the target Account. +2. Inspect the call's 4-byte selector. + ├─ Matches a HAS facade selector? → route to Hedera Account Service. (HAS precedence) + ├─ Account has delegation_address set? → execute target's code in EOA's storage context. + └─ Otherwise → no-op (value transfer only, if any). +3. If the delegated code reverts, any value transfer also reverts. +``` + +The call applies uniformly whether it originated from: + +- A top-level transaction (`transaction.to == eoa`). +- An inner `CALL` / `STATICCALL` from another contract (`address(eoa).call(...)`). +- Any of the legacy transaction types (0, 1, 2), not just Type 4. + +### Code queries + +`EXTCODESIZE`, `EXTCODECOPY`, `EXTCODEHASH`, `eth_getCode`, and `ContractGetBytecodeQuery` against a delegated EOA all return the Delegation Indicator (`0xef0100 ‖ delegation_address`). For an undelegated EOA they return empty bytecode, as before. + +### Storage & logs + +A delegated EOA can now hold **mutable storage slots** and **emit EVM logs**, because the delegated code runs in its context. Tooling implications: + +- `eth_getStorageAt(eoa, slot)` returns the EOA's storage. +- `eth_getLogs` returns logs emitted from the EOA's address. +- Mirror Node `/api/v1/contracts/{eoa}/state`, `/results/logs`, `/call`, and friends now work on EOA addresses too. + +### Chains & loops + +If `delegation_address` points to another EOA that *itself* has a delegation, **only the first hop is resolved**. The bytecode at the second hop is interpreted literally, and since `0xef` is a banned opcode (EIP-3541), the call reverts. In practice this means **don't chain delegations**: always delegate directly to a real contract. + +### No-op targets + +Setting `delegation_address` to any of the following is allowed, but the resulting call to the EOA is a no-op (value transfer only, no code executes): + +- A non-existent account. +- A precompile address (`0x01`–`0x11`). +- A system contract (HTS at `0x167`, HAS at `0x16a`, HSS at `0x16b`, Exchange Rate at `0x168`, PRNG at `0x169`). +- A Hedera system account. +- Another EOA whose own code is empty. + +Direct delegation from a regular EOA to a system contract is therefore intentionally inert; the token-proxy / schedule-proxy accounts are the only entities permitted to "delegate" to a system contract address. + +*** + +## HAS facade precedence + +Calls that match a [Hedera Account Service](/evm/hedera-services/system-contracts/account-service) facade selector are **always routed to HAS**, even if the EOA has a delegation set. This preserves the user-facing behavior of pre-Pectra HAS calls. + +| HAS function | Selector | +| --------------------------------------------------------- | -------------- | +| `hbarAllowance(address spender)` | `0xbbee989e` | +| `hbarApprove(address spender, int256 amount)` | `0x86aff07c` | +| `setUnlimitedAutomaticAssociations(bool enabled)` | `0xf5677e99` | + +Processing order (per HIP-1340): + +1. **If the call selector matches a HAS facade function** → HAS handles it. The user's delegation is ignored for this call. +2. **Else if the EOA has a delegation** → run the delegate contract's code. +3. **Else** → no-op (with any attached value transfer). + +> ⚠️ **Selector-collision warning.** If your smart-account delegate defines a function whose selector happens to equal one of the HAS selectors above (e.g. you happen to write a `hbarApprove(address,int256)` method), that function will be **unreachable**; HAS will intercept the call first. Pick distinct signatures. + +*** + +## Account-type applicability + +Whether you can use the EVM path depends on the account's key type and alias scheme. + +| Account type | EVM path (Type 4) | HAPI path (CryptoCreate/Update) | +| ---------------------------------------------------------- | ----------------- | ------------------------------- | +| ED25519 account | ❌ | ✅ | +| ECDSA account, long-zero alias (`0x0000…`) | ❌ | ✅ | +| ECDSA account, public-key-derived alias | ✅ | ✅ | + +This isn't new behavior; it reflects the existing rule that only ECDSA-with-public-key-derived-alias accounts can submit Ethereum transactions on Hedera. Once delegation is configured, **execution semantics are uniform** across account types: a call to an ED25519 account with `delegation_address` set runs the delegate code just like for any other account. + +`CryptoTransfer` signature validation is unchanged. Hedera-native authorization (e.g., multi-sig threshold keys) continues to govern transfers initiated through HAPI. + +*** + +## Gas costs + +Per EIP-7702, every entry in an `authorization_list` costs gas, whether valid, invalid, or duplicate: + +| Authorization outcome | Gas charged | +| --------------------------------------------------------- | --------------------------------------------------------------------------- | +| Authorizes an **existing** account | 12,500 | +| Authorizes a **new** account (hollow account creation) | 25,000 + Hedera's hollow-account creation cost | +| Invalid signature / wrong chain ID / wrong nonce | 12,500 (consumed, then silently skipped) | +| Duplicate entry for an EOA already authorized in the list | 12,500 (consumed, then skipped) | + +The cap on hollow accounts created in one transaction is governed by the transaction's `gas_limit` and the network's [operations-per-second throttle](/evm/development/gas-fees#operational-based-throttling). For the calldata and execution sides of the gas calculation, see [Gas and Fees](/evm/development/gas-fees). + +> **Gas shortage on a valid authorization.** If an otherwise-valid authorization can't be processed because the transaction ran out of gas (for example, it would require creating a hollow account but the `gas_limit` is exhausted), Hedera still emits a child `CryptoCreate` / `CryptoUpdate` record with a **failed status** so the error surfaces in the record stream rather than being silently dropped. + +*** + +## Smart-account example (Solidity) + +A minimal smart-account delegate that supports batched calls and an owner-only check: + +```solidity Solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +/// @title MinimalSmartAccount +/// @notice Intended to be installed as an EOA delegation target via EIP-7702. +/// All state read/written here lives in the *EOA's* storage frame. +contract MinimalSmartAccount { + // EIP-7201 namespaced storage slot for "hedera.smart-account.v1". + // Derivation: keccak256(abi.encode(uint256(keccak256("hedera.smart-account.v1")) - 1)) & ~bytes32(uint256(0xff)) + // Reproduce with Foundry: `cast index-erc7201 "hedera.smart-account.v1"` + // If you change the namespace string, recompute this constant. + bytes32 private constant SLOT = + 0xf7bd8ee8b6b02e586c7a21c9ecc95fa2e26786f8e462f9f9103d541de5d4bf00; + + struct Layout { + uint256 nonce; + } + + function _s() private pure returns (Layout storage $) { + assembly { $.slot := SLOT } + } + + /// Only the EOA itself (i.e. address(this) == msg.sender after delegation) may call. + modifier onlyOwner() { + require(msg.sender == address(this), "not owner"); + _; + } + + struct Call { address to; uint256 value; bytes data; } + + /// Execute a batch of calls atomically from the EOA's address. + function executeBatch(Call[] calldata calls) external onlyOwner { + _s().nonce++; + for (uint256 i = 0; i < calls.length; i++) { + (bool ok, bytes memory ret) = calls[i].to.call{value: calls[i].value}(calls[i].data); + require(ok, _revertReason(ret)); + } + } + + function nonce() external view returns (uint256) { return _s().nonce; } + + receive() external payable {} + + function _revertReason(bytes memory ret) private pure returns (string memory) { + if (ret.length < 68) return "call reverted"; + assembly { ret := add(ret, 0x04) } + return abi.decode(ret, (string)); + } +} +``` + +**Deploy once** with a regular `ContractCreate`. Then **any number of EOAs can delegate** to that deployed address, and they each get smart-account behavior without re-deploying. + +> Use namespaced storage ([ERC-7201](https://eips.ethereum.org/EIPS/eip-7201)) in delegate contracts so the EOA can later switch delegates without colliding on storage slots written by the previous implementation. + +### Sponsored onboarding (batched approve + swap, gas paid by a sponsor) + +This is the flagship EIP-7702 use case: a new user with **zero HBAR** gets smart-account behavior and executes a multi-step action in one transaction, while a sponsor pays the gas. The single Type 4 transaction does two things at once: it sets the EOA's delegation *and* runs a batched call in the EOA's context. + +```javascript JavaScript +import { createWalletClient, http, encodeFunctionData, parseAbi } from "viem"; +import { privateKeyToAccount } from "viem/accounts"; +import { hederaTestnet } from "viem/chains"; + +const eoa = privateKeyToAccount(process.env.EOA_PRIVATE_KEY); // new user, no HBAR +const sponsor = privateKeyToAccount(process.env.SPONSOR_PRIVATE_KEY); // pays the gas + +const eoaClient = createWalletClient({ chain: hederaTestnet, transport: http(), account: eoa }); +const sponsorClient = createWalletClient({ chain: hederaTestnet, transport: http(), account: sponsor }); + +// 1. The EOA signs an authorization delegating to the deployed MinimalSmartAccount. +// No `executor` field, because the sponsor (not the EOA) submits the transaction. +const authorization = await eoaClient.signAuthorization({ + contractAddress: "0x", +}); + +// 2. Build the batched call: approve a router, then swap (both run in the EOA's context). +const smartAccountAbi = parseAbi([ + "struct Call { address to; uint256 value; bytes data; }", + "function executeBatch(Call[] calls)", +]); +const erc20Abi = parseAbi(["function approve(address spender, uint256 amount)"]); +const routerAbi = parseAbi(["function swapExactTokensForHBAR(uint256 amountIn, address token)"]); + +const batch = encodeFunctionData({ + abi: smartAccountAbi, + functionName: "executeBatch", + args: [[ + { to: "0x", value: 0n, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: ["0x", 1_000_000n] }) }, + { to: "0x", value: 0n, data: encodeFunctionData({ abi: routerAbi, functionName: "swapExactTokensForHBAR", args: [1_000_000n, "0x"] }) }, + ]], +}); + +// 3. Sponsor submits one Type 4 transaction: it sets the delegation AND invokes the batch. +const hash = await sponsorClient.sendTransaction({ + authorizationList: [authorization], // sets eoa.delegation_address + to: eoa.address, // call resolves to the delegate code, in the EOA's context + data: batch, // executeBatch([approve, swap]) +}); +``` + +The EOA never needed HBAR or a prior on-chain footprint. After this transaction, `eth_getCode(eoa.address)` returns the Delegation Indicator, and the approve + swap have executed from the EOA's own address. + + +The delegation set by the authorization **persists even if the batched call reverts** (authorizations are committed before EVM execution). If you want all-or-nothing onboarding, have the delegate contract revert on any sub-call failure (as `executeBatch` does via its `require`), and treat the delegation itself as a separate, durable state change. + + +*** + +## Mirror Node surface + +[HIP-1340](https://hips.hedera.com/hip/hip-1340) extends the Mirror Node REST API: + +- **Accounts endpoints** (`GET /api/v1/accounts`, `GET /api/v1/accounts/{idOrAliasOrEvmAddress}`) include a new `delegation_address` field per account. The value is `0x` when no delegation is set. +- **Contract-result endpoints** (`GET /api/v1/contracts/{id}/results/{timestamp}`, `GET /api/v1/contracts/results`, `GET /api/v1/contracts/results/{txOrHash}`) include a new `authorization_list` field for Type 4 transactions: + + ```json + { + "authorization_list": [ + { + "chain_id": "0x127", + "address": "0x1111111111111111111111111111111111111111", + "nonce": 5, + "y_parity": 1, + "r": "0x2222...", + "s": "0x3333..." + } + ] + } + ``` + +- **EOA contract APIs.** `/api/v1/contracts/{eoa}/state`, `/results/logs`, `/results`, `/results/{tx}/actions`, `/results/{tx}/opcodes`, and `/api/v1/contracts/call` now accept EOA addresses and return contract-style data when the EOA has a delegation set. + +JSON-RPC Relay updates: `eth_getCode`, `eth_getStorageAt`, and `eth_getLogs` work for delegated EOAs; the relay handles Type 4 transaction parsing and submission. + +*** + +## HTS / HSS proxy accounts + +[HIP-1340](https://hips.hedera.com/hip/hip-1340) also re-implements the long-standing HTS-token and HSS-schedule **facade calls** (HIP-218 / HIP-719 / HIP-755 / HIP-906) using the new Delegation Indicator format. Calls like `IERC20(tokenAddress).transfer(...)` continue to work exactly as before, but `ContractGetBytecode(tokenAddress)` now returns a stable `0xef0100 ‖ ` indicator instead of a runtime-synthesized `DELEGATECALL` stub. + +This is invisible to most users. Tools that **introspect** the bytecode of token-proxy or schedule-proxy accounts (e.g. block explorers, custom indexers) may need to update their parsing. + +*** + +## Caveats and edge cases + +- **An empty `authorization_list` makes a Type 4 transaction invalid.** Don't construct one and then drop entries client-side; either include at least one authorization or send a different type. +- **Authorizations persist even if the EVM execution reverts.** They are processed before EVM code runs and committed independently; this is a feature (so onboarding flows still succeed even if the follow-up call fails), but it does mean a "rolled back" transaction can still leave delegations in place. +- **Selector collisions with HAS** make those functions unreachable on a delegated EOA. Pick non-colliding signatures. +- **Storage migration.** Switching delegation targets does *not* migrate storage. Use [ERC-7201](https://eips.ethereum.org/EIPS/eip-7201) namespaces in your delegates to avoid collisions. +- **`msg.sender == tx.origin` invariant no longer holds in deeper frames.** Code historically used `msg.sender == tx.origin` as a "no contracts" check. With delegation, the topmost frame on a Type 4 transaction can be a delegated EOA, meaning `tx.origin` and `msg.sender` align in places they previously wouldn't. Treat this check as advisory, not a security boundary. +- **No impact on hooks.** A call to a delegated EOA inside a [hook](/learn/core-concepts/accounts/hiero-hooks) behaves the same as outside one. Hooks use a dedicated storage namespace, so delegate code writing to the EOA's storage slots cannot collide with hook storage. + +*** + +## References + +- [HIP-1340](https://hips.hedera.com/hip/hip-1340): EOA Code Delegation (Hedera adoption) +- [HIP-1341](https://hips.hedera.com/hip/hip-1341): Support for Ethereum Pectra Release +- [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702): Set EOA Account Code +- [EIP-3541](https://eips.ethereum.org/EIPS/eip-3541): Reject `0xef`-prefixed contract code +- [Hedera Account Service](/evm/hedera-services/system-contracts/account-service) +- [`EthereumTransaction`](/native/smart-contracts/ethereum-transaction) +- [Gas and Fees](/evm/development/gas-fees) diff --git a/evm/development/gas-fees.mdx b/evm/development/gas-fees.mdx index 9a5a7e95..c05bfe5c 100644 --- a/evm/development/gas-fees.mdx +++ b/evm/development/gas-fees.mdx @@ -1,235 +1,363 @@ ---- -title: "Gas and Fees" -description: "Understanding gas costs, throttling, and fee calculation for Hiero Contracts" -mode: "wide" ---- - -## Gas - -When executing smart contracts, the **EVM** requires the amount of work paid in **gas**. The "work" includes computation, state transitions, and storage. Gas is the unit of measurement used to charge a fee per opcode executed by the EVM. Each opcode has a defined gas cost. Gas reflects the cost necessary to pay for the computational resources used to process transactions. - - -Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, Hedera has implemented **operational-based throttling** and eliminated **minimum gas charges**, providing more predictable resource management and fairer billing for smart contract operations. - - -## Weibar - -Gas information for EVM operations is returned in **weibar** (introduced in [HIP-410](https://hips.hedera.com/hip/hip-410)). - -- `1 weibar = 10^-18 HBAR` -- `1 tinybar = 10^10 weibar` - -As noted in [HIP-410](https://hips.hedera.com/hip/hip-410), this maximizes compatibility with third-party tools that expect ether units to be operated on in fractions of `10^18`, also known as a **Wei**. - -## Gas Schedule and Fee Calculation - -Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use the standard [Fee Model](/learn/core-concepts/fee-model), a base fee plus extras for node, network, and service components, paid in HBAR. - -For gas-consuming transactions (`ContractCall`, `ContractCreate`, `EthereumTransaction`), gas is an "extra" in the service fee component. The gas extra covers EVM execution costs. All other fee components (node fee, network fee, and the non-gas portion of the service fee) follow the base-fee-plus-extras model. - -Gas fees for EVM transactions consist of: - -- **Intrinsic Gas**: The minimum amount of gas required to execute a transaction -- **EVM Opcode Gas**: The gas required to execute the defined opcodes for the smart contract call -- **Hedera System Contract Gas**: The required gas associated with Hedera-defined transactions, such as using the Hedera Token Service system contract - - - **High-volume contract creation.** `ContractCreateTransaction` supports the - `high_volume` flag ([HIP-1313](https://hips.hedera.com/hip/hip-1313)), which routes - the transaction through dedicated high-volume throttle capacity with variable-rate - pricing. This applies to **HAPI-based contract creation only** — contract deployments - via EVM `CREATE` / `CREATE2` opcodes are not included. See the - [High-Volume Entity Creation](/learn/core-concepts/high-volume-entity-creation) guide - for details. - - -### Intrinsic Gas - -A transaction submitted to the smart contract service must be sent with enough gas to cover **intrinsic gas**. With the **Cancun fork** of the EVM update, intrinsic gas is calculated as: - -```bash -21000 + 4 × (number of zero bytes) + 16 × (number of non-zero bytes) = intrinsic gas -``` - -- **21,000**: The base gas cost for any transaction -- **4 × (zero bytes)**: The cost of each zero byte in the transaction payload -- **16 × (non-zero bytes)**: The cost for each non-zero byte in the transaction payload - -If insufficient gas is submitted, the transaction will **fail during precheck** and no record will be created. - - -This applies to both standard transactions and **jumbo EthereumTransactions** introduced by **[HIP-1086](https://hips.hedera.com/hip/hip-1086)**, which allow larger `callData` payloads. - - -### EVM Opcode Gas - -Execution costs in the EVM include both **fixed** and **dynamic** costs: - -- **Fixed Cost**: Base cost per opcode execution -- **Dynamic Cost**: Varies by parameters (e.g., cold vs warm storage access) - -**Example**: For the `SLOAD` opcode, which loads data from storage: - -- **Fixed Cost**: `100 gas` units (base cost per execution) -- **Dynamic Cost (Cold Access)**: `2,100 gas` units (first-time access to the storage slot) -- **Dynamic Cost (Warm Access)**: `100 gas` units (subsequent access within the transaction) - -If `SLOAD` accesses a storage slot twice within the same transaction, the total gas cost would be calculated as follows: - -- **First Access (Cold)** = `100 + 2,100 = 2,200 gas` -- **Second Access (Warm)** = `100 + 100 = 200 gas` -- **Final Gas Cost Total** = `2,400 gas` - -📣 *Explore [opcodes in Cancun fork](https://www.evm.codes/).* - - -### Hedera System Contract Gas - -Hedera system contract gas fees apply only when using a native Hedera service. They are calculated by converting the transaction cost in **USD** to gas using a set conversion rate, then adding a **20% surcharge** for overhead and variations in gas usage. - -**Example**: For a **$0.10 transaction** with a conversion rate of `1,000,000 gas per USD`: - -- **Base Gas Cost** = `0.10 × 1,000,000 = 100,000 gas` -- **Total Gas Cost** = `100,000 × 1.2 = 120,000 gas` -- **Final gas cost total** = `120,000 gas` - - -Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, system contract operations also contribute to **operational throttling** through measured ops costs, providing layered resource protection alongside gas-based billing. - - -#### System Contract View Functions - -The gas requirements for **HTS view functions** can be calculated in a slightly modified manner. The transaction type of `getTokenInfo` can be used and a nominal price need not be calculated. This implies that converting the fee into HBAR is not necessary as the canonical price (`$0.0001`) can be directly converted into gas by using the conversion factor of **852 tinycents**. Add **20% markup**. Thus gas cost is: - -- **Base gas cost** = `(1000000 + 852000 - 1) × 1000 / 852000 = 2173 gas` -- **Total Gas Cost** = `2173 × 1.2 = 2607 gas` - -**Final gas cost total** = `2607 gas` - - -**Example System Contracts:** -- **[Hedera Token Service (HTS)](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/token-service/HederaTokenService.sol)** -- **[Pseudo Random Number Generator (PRNG)](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/prng/PrngSystemContract.sol)** -- **[Exchange Rate](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/exchange-rate/ExchangeRateSystemContract.sol)** - -**Learn More**: Our detailed gas calculation [reference](https://github.com/hashgraph/hedera-services/blob/develop/hedera-node/docs/design/services/smart-contract-service/system-contract-gas-calc.md#system-contracts) explains the precise steps for calculating gas fees on Hedera. - - - -## Gas for Jumbo Transactions - -**Jumbo EthereumTransactions** that include large `callData` under **[HIP-1086](https://hips.hedera.com/hip/hip-1086)** follow the same gas model as standard EVM transactions. This gas pricing applies only to [EthereumTransaction](/native/smart-contracts/ethereum-transaction) type; standard HAPI transactions are unaffected. - -### Formula - -The gas cost for `callData` is based on byte content: - -``` -callData gas = (4 × zero bytes) + (16 × non-zero bytes) -``` - -This is added to the base gas and execution gas to calculate the total gas required. - -*📣 [Learn more about Ethereum jumbo transactions](/native/smart-contracts/ethereum-transaction#handling-large-calldata-payloads)* - -### Example Calculation - -For **100KB of `callData`** with `10,000 zero bytes` and `90,000 non-zero bytes`: - -- **Zero byte gas**: `4 × 10,000 = 40,000` -- **Non-zero byte gas**: `16 × 90,000 = 1,440,000` -- **Total callData gas** = `1,480,000` - -Ensure both `gasLimit` (RLP) and `maxGasAllowance` (wrapper) are set high enough to cover the total. - - -🔹 **Size Caps**: Jumbo EthereumTransactions are capped at **24KB** (creation) and **128KB** (call). Larger payloads require `callDataFileId`.\ -🔹 **Throttling**: Jumbo transactions are subject to dedicated **operational throttling** based on transaction type and complexity. - - - -## Gas Limit - -The **gas limit** is the maximum amount of gas you are willing to pay for an operation. - -The current opcode gas fees are reflective as of the **[0.22 Hedera Service release](/learn/release-notes/services#v0.22)**. - -| Operation | Cancun Cost (Gas) | Current Hedera (Gas) | -| ------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------- | -| Code deposit | 200 \* bytes | 200 \* bytes | -|

BALANCE
(cold account)

| 2600 | 2600 | -|

BALANCE
(warm account)

| 100 | 100 | -| `EXP` | 10 + 50/byte | 10 + 50/byte | -|

EXTCODECOPY
(cold account)

| 2600 + Mem | 2600 + Mem | -|

EXTCODECOPY
(warm account)

| 100 + Mem | 100 + Mem | -|

EXTCODEHASH
(cold account)

| 2600 | 2600 | -|

EXTCODEHASH
(warm account)

| 100 | 100 | -|

EXTCODESIZE
(cold account)

| 2600 | 2600 | -|

EXTCODESIZE
(warm account)

| 100 | 100 | -|

LOG0, LOG1, LOG2,
LOG3, LOG4

|

375 + 375\*topics
+ data Mem

|

375 + 375\*topics
+ data Mem

| -|

SLOAD
(cold slot)

| 2100 | 2100 | -|

SLOAD
(warm slot)

| 100 | 100 | -|

SSTORE
(new slot)

| 22,100 | 22,100 | -|

SSTORE
(existing slot,
cold access)

| 2,900 | 2,900 | -|

SSTORE
(existing slot,
warm access)

| 100 | 100 | -|

SSTORE
refund

| As specified by the EVM | As specified by the EVM | -|

CALL et al.
(cold recipient)

| 2,600 | 2,600 | -|

CALL et al.
(warm recipient)

| 100 | 100 | -|

CALL et al.
HBAR/ETH Transfer Surcharge

| 9,000 | 9,000 | -|

SELFDESTRUCT
(cold beneficiary)

| 2600 | 2600 | -|

SELFDESTRUCT
(warm beneficiary)

| 0 | 0 | -| `TSTORE` | 100 | 100 | -| `TLOAD` | 100 | 100 | -| `MCOPY` | 3 + 3\*words_copied + memory_expansion_cost | 3 + 3\*words_copied + memory_expansion_cost | - - -The terms **'warm'** and **'cold'** in the above table correspond with whether the account or storage slot has been read or written to within the current smart contract transaction, even within a child call frame. - -**'CALL et al.'** includes with limitation: `CALL`, `CALLCODE`, `DELEGATECALL`, and `STATICCALL` - -Reference: [HIP-206](https://hips.hedera.com/hip/hip-206), [HIP-865](https://hips.hedera.com/hip/hip-865) - -## Operational-Based Throttling - -While most **EVM-compatible networks** use per-block gas limits for resource control, Hedera uses **time-based throttling**. Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, Hedera has transitioned from **gas-per-second** to **operations-per-second (ops/sec) throttling**, controlling network throughput based on actual computational demands rather than gas estimates. This potentially supports **significantly higher throughput** while maintaining EVM compatibility. - -**Ops costs** are derived from **nanosecond performance benchmarks** with safety margins, covering **EVM opcodes**, **precompiles**, and **system contracts**. Gas continues for user billing and per-transaction limits, separating cost calculation from throttling. - - -**Performance**: Real-world testing shows substantial improvements, with **Uniswap** achieving over **150 million gas/sec** compared to the previous **15 million gas/sec** limit. - - -### Transaction Execution Outcomes - -With **operational-based throttling**, transaction processing follows specific patterns based on resource availability: - -**Ops Throttle Exhausted**: When the operations-per-second throttle is exhausted either before execution begins or during execution, transactions fail with a `THROTTLED_AT_CONSENSUS` error and are charged only the **[intrinsic gas fee](/evm/development/gas-fees#intrinsic-gas)**. - -**Gas Limit Exhausted**: If a transaction's gas limit is exhausted before the ops throttle, it fails with an **out-of-gas error** and users are charged for the full gas used, with ops deducted for work completed. - -**Successful Execution**: For successful transactions, users are charged for the **exact gas used** and the corresponding ops units are deducted from the throttle bucket. - -## Gas Reservation and Unused Gas Refund - -Hedera throttles transactions **before consensus**, and nodes limit the number of transactions they can submit to the network. At **consensus time**, if the maximum number of transactions is exceeded, the excess transactions are not evaluated and are canceled with a **busy state**. Throttling by variable gas amounts provides challenges to this system, where the nodes only submit a share of their transaction limit. - -To address this, Hedera now uses **operational-based throttling** that applies only at **consensus**. The system operates with: - -- **Frontend (ingest/precheck)**: Uses **TPS limits** only with no gas-based throttling -- **Backend (consensus)**: Applies **operations-per-second (ops) throttling** based on actual computational work performed - -It is impossible to know the actual evaluated gas pre-consensus because the network state can directly impact the flow of the transaction, which is why pre-consensus uses the `gasLimit` field and will be referred to as the **gas reservation**. - -**Contract query requests** are unique and bypass the consensus stage altogether. These requests are executed solely on the local node that receives them and only influence that specific node's precheck throttle. - -To ensure transactions can execute properly, setting a **higher gas reservation** than will be used by execution is common. On **Ethereum mainnet**, the entire reservation is charged to the account before execution, and the unused portion is credited back. However, Ethereum utilizes a **[memory pool (mempool)](/support/glossary#mempool)** and does transaction ordering at block production time, allowing the block limit to be based only on used and not reserved gas. - -Users are charged only for the **actual gas used** during transaction execution, with **unused gas being fully refunded**. This aligns with Ethereum's billing model and eliminates the previous minimum charge requirements. - -## Maximum Gas Per Transaction - -Each transaction on Hedera is capped by a **per-transaction gas limit**. If a transaction's `gasLimit` exceeds this cap, it is rejected during precheck with the `INDIVIDUAL_TX_GAS_LIMIT_EXCEEDED` error and does not proceed to consensus. This gas metering approach ensures efficient resource use, preventing excessive consumption while allowing flexibility for larger, more complex smart contracts. - -Per-transaction gas limits remain unchanged (e.g., **15 million gas per transaction**), while network throughput is now managed through **operational-based throttling**. Refer to [HIP‑1249](https://hips.hedera.com/hip/hip-1249) for implementation details. - +--- +title: "Gas and Fees" +description: "Understanding gas costs, throttling, and fee calculation for Hiero Contracts" +mode: "wide" +--- + +## Gas + +When executing smart contracts, the **EVM** requires the amount of work paid in **gas**. The "work" includes computation, state transitions, and storage. Gas is the unit of measurement used to charge a fee per opcode executed by the EVM. Each opcode has a defined gas cost. Gas reflects the cost necessary to pay for the computational resources used to process transactions. + + +Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, Hedera has implemented **operational-based throttling** and eliminated **minimum gas charges**, providing more predictable resource management and fairer billing for smart contract operations. + + +## Weibar + +Gas information for EVM operations is returned in **weibar** (introduced in [HIP-410](https://hips.hedera.com/hip/hip-410)). + +- `1 weibar = 10^-18 HBAR` +- `1 tinybar = 10^10 weibar` + +As noted in [HIP-410](https://hips.hedera.com/hip/hip-410), this maximizes compatibility with third-party tools that expect ether units to be operated on in fractions of `10^18`, also known as a **Wei**. + +## Gas Schedule and Fee Calculation + +Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use the standard [Fee Model](/learn/core-concepts/fee-model), a base fee plus extras for node, network, and service components, paid in HBAR. + +For gas-consuming transactions (`ContractCall`, `ContractCreate`, `EthereumTransaction`), gas is an "extra" in the service fee component. The gas extra covers EVM execution costs. All other fee components (node fee, network fee, and the non-gas portion of the service fee) follow the base-fee-plus-extras model. + +Gas fees for EVM transactions consist of: + +- **Intrinsic Gas**: The minimum amount of gas required to execute a transaction +- **EVM Opcode Gas**: The gas required to execute the defined opcodes for the smart contract call +- **Hedera System Contract Gas**: The required gas associated with Hedera-defined transactions, such as using the Hedera Token Service system contract + + + **High-volume contract creation.** `ContractCreateTransaction` supports the + `high_volume` flag ([HIP-1313](https://hips.hedera.com/hip/hip-1313)), which routes + the transaction through dedicated high-volume throttle capacity with variable-rate + pricing. This applies to **HAPI-based contract creation only**; contract deployments + via EVM `CREATE` / `CREATE2` opcodes are not included. See the + [High-Volume Entity Creation](/learn/core-concepts/high-volume-entity-creation) guide + for details. + + +### Intrinsic Gas + +A transaction submitted to the smart contract service must be sent with enough gas to cover **intrinsic gas**. Under the **Pectra hard fork** (Prague EVM execution layer), intrinsic gas is calculated as: + +```bash +21000 + 4 × (number of zero bytes) + 16 × (number of non-zero bytes) = intrinsic gas +``` + +- **21,000**: The base gas cost for any transaction +- **4 × (zero bytes)**: The cost of each zero byte in the transaction payload +- **16 × (non-zero bytes)**: The cost for each non-zero byte in the transaction payload + +If insufficient gas is submitted, the transaction will **fail during precheck** and no record will be created. + + +**Pectra calldata floor ([EIP-7623](https://eips.ethereum.org/EIPS/eip-7623)).** Under Pectra, transactions must additionally satisfy a calldata floor: + +```bash +floor = 21000 + 10 × (zero bytes + 4 × non-zero bytes) +``` + +The transaction pays `MAX(standard intrinsic + execution gas, floor)`. The floor primarily affects calldata-heavy transactions with low execution cost; most contract calls are unaffected. See [HIP-1341](https://hips.hedera.com/hip/hip-1341) for Pectra adoption details on Hedera. + + + +This applies to both standard transactions and **jumbo EthereumTransactions** introduced by **[HIP-1086](https://hips.hedera.com/hip/hip-1086)**, which allow larger `callData` payloads. + + + +**Type 4 (EIP-7702) authorization gas.** Each entry in a Type 4 EthereumTransaction's `authorization_list` costs **25,000 gas** if it creates a new account, or **12,500 gas** if the authorizing account already exists. Hedera additionally charges its usual hollow-account creation cost for any newly created accounts. See the [EOA Code Delegation](/evm/development/eoa-code-delegation) page and [HIP-1340](https://hips.hedera.com/hip/hip-1340). + + +### EVM Opcode Gas + +Execution costs in the EVM include both **fixed** and **dynamic** costs: + +- **Fixed Cost**: Base cost per opcode execution +- **Dynamic Cost**: Varies by parameters (e.g., cold vs warm storage access) + +**Example**: For the `SLOAD` opcode, which loads data from storage: + +- **Fixed Cost**: `100 gas` units (base cost per execution) +- **Dynamic Cost (Cold Access)**: `2,100 gas` units (first-time access to the storage slot) +- **Dynamic Cost (Warm Access)**: `100 gas` units (subsequent access within the transaction) + +If `SLOAD` accesses a storage slot twice within the same transaction, the total gas cost would be calculated as follows: + +- **First Access (Cold)** = `100 + 2,100 = 2,200 gas` +- **Second Access (Warm)** = `100 + 100 = 200 gas` +- **Final Gas Cost Total** = `2,400 gas` + +📣 *Explore [opcodes in Pectra (Prague) fork](https://www.evm.codes/?fork=prague).* + + +### Hedera System Contract Gas + +Hedera system contract gas fees apply only when using a native Hedera service. They are calculated by converting the transaction cost in **USD** to gas using a set conversion rate, then adding a **20% surcharge** for overhead and variations in gas usage. + +**Example**: For a **$0.10 transaction** with a conversion rate of `1,000,000 gas per USD`: + +- **Base Gas Cost** = `0.10 × 1,000,000 = 100,000 gas` +- **Total Gas Cost** = `100,000 × 1.2 = 120,000 gas` +- **Final gas cost total** = `120,000 gas` + + +Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, system contract operations also contribute to **operational throttling** through measured ops costs, providing layered resource protection alongside gas-based billing. + + +#### System Contract View Functions + +The gas requirements for **HTS view functions** can be calculated in a slightly modified manner. The transaction type of `getTokenInfo` can be used and a nominal price need not be calculated. This implies that converting the fee into HBAR is not necessary as the canonical price (`$0.0001`) can be directly converted into gas by using the conversion factor of **852 tinycents**. Add **20% markup**. Thus gas cost is: + +- **Base gas cost** = `(1000000 + 852000 - 1) × 1000 / 852000 = 2173 gas` +- **Total Gas Cost** = `2173 × 1.2 = 2607 gas` + +**Final gas cost total** = `2607 gas` + + +**Example System Contracts:** +- **[Hedera Token Service (HTS)](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/token-service/HederaTokenService.sol)** +- **[Pseudo Random Number Generator (PRNG)](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/prng/PrngSystemContract.sol)** +- **[Exchange Rate](https://github.com/hiero-ledger/hiero-contracts/blob/main/contracts/exchange-rate/ExchangeRateSystemContract.sol)** + +**Learn More**: Our detailed gas calculation [reference](https://github.com/hashgraph/hedera-services/blob/develop/hedera-node/docs/design/services/smart-contract-service/system-contract-gas-calc.md#system-contracts) explains the precise steps for calculating gas fees on Hedera. + + + +## Gas for Jumbo Transactions + +**Jumbo EthereumTransactions** that include large `callData` under **[HIP-1086](https://hips.hedera.com/hip/hip-1086)** follow the same gas model as standard EVM transactions. This gas pricing applies only to [EthereumTransaction](/native/smart-contracts/ethereum-transaction) type; standard HAPI transactions are unaffected. + +### Formula + +The gas cost for `callData` is based on byte content: + +``` +callData gas = (4 × zero bytes) + (16 × non-zero bytes) +``` + +This is added to the base gas and execution gas to calculate the total gas required. + +*📣 [Learn more about Ethereum jumbo transactions](/native/smart-contracts/ethereum-transaction#handling-large-calldata-payloads)* + +### Example Calculation + +For **100KB of `callData`** with `10,000 zero bytes` and `90,000 non-zero bytes`: + +- **Zero byte gas**: `4 × 10,000 = 40,000` +- **Non-zero byte gas**: `16 × 90,000 = 1,440,000` +- **Total callData gas** = `1,480,000` + +Ensure both `gasLimit` (RLP) and `maxGasAllowance` (wrapper) are set high enough to cover the total. + + +🔹 **Size Caps**: Jumbo EthereumTransactions are capped at **24KB** (creation) and **128KB** (call). Larger payloads require `callDataFileId`.\ +🔹 **Throttling**: Jumbo transactions are subject to dedicated **operational throttling** based on transaction type and complexity. + + + +## Gas Limit + +The **gas limit** is the maximum amount of gas you are willing to pay for an operation. + +The current opcode gas fees are reflective as of the **[0.22 Hedera Service release](/learn/release-notes/services#v0.22)**. + +| Operation | Pectra Cost (Gas) | Current Hedera (Gas) | +| ------------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------- | +| Code deposit | 200 \* bytes | 200 \* bytes | +|

BALANCE
(cold account)

| 2600 | 2600 | +|

BALANCE
(warm account)

| 100 | 100 | +| `EXP` | 10 + 50/byte | 10 + 50/byte | +|

EXTCODECOPY
(cold account)

| 2600 + Mem | 2600 + Mem | +|

EXTCODECOPY
(warm account)

| 100 + Mem | 100 + Mem | +|

EXTCODEHASH
(cold account)

| 2600 | 2600 | +|

EXTCODEHASH
(warm account)

| 100 | 100 | +|

EXTCODESIZE
(cold account)

| 2600 | 2600 | +|

EXTCODESIZE
(warm account)

| 100 | 100 | +|

LOG0, LOG1, LOG2,
LOG3, LOG4

|

375 + 375\*topics
+ data Mem

|

375 + 375\*topics
+ data Mem

| +|

SLOAD
(cold slot)

| 2100 | 2100 | +|

SLOAD
(warm slot)

| 100 | 100 | +|

SSTORE
(new slot)

| 22,100 | 22,100 | +|

SSTORE
(existing slot,
cold access)

| 2,900 | 2,900 | +|

SSTORE
(existing slot,
warm access)

| 100 | 100 | +|

SSTORE
refund

| As specified by the EVM | As specified by the EVM | +|

CALL et al.
(cold recipient)

| 2,600 | 2,600 | +|

CALL et al.
(warm recipient)

| 100 | 100 | +|

CALL et al.
HBAR/ETH Transfer Surcharge

| 9,000 | 9,000 | +|

SELFDESTRUCT
(cold beneficiary)

| 2600 | 2600 | +|

SELFDESTRUCT
(warm beneficiary)

| 0 | 0 | +| `TSTORE` | 100 | 100 | +| `TLOAD` | 100 | 100 | +| `MCOPY` | 3 + 3\*words_copied + memory_expansion_cost | 3 + 3\*words_copied + memory_expansion_cost | + + +The terms **'warm'** and **'cold'** in the above table correspond with whether the account or storage slot has been read or written to within the current smart contract transaction, even within a child call frame. + +**'CALL et al.'** includes with limitation: `CALL`, `CALLCODE`, `DELEGATECALL`, and `STATICCALL` + +**BLS12-381 precompiles ([EIP-2537](https://eips.ethereum.org/EIPS/eip-2537))** are available under Pectra at the following addresses, callable via `call` / `staticcall`: + +| Function | Address | Input size (bytes) | Purpose | +| --------------------- | ------- | ------------------ | ------------------------------------------------------------------------ | +| `BLS12_G1ADD` | `0x0b` | 256 | Add two G1 points. | +| `BLS12_G1MSM` | `0x0c` | 160 × k slices | Multi-scalar multiplication on G1 (sum of `scalar[i] × point[i]`). | +| `BLS12_G2ADD` | `0x0d` | 512 | Add two G2 points. | +| `BLS12_G2MSM` | `0x0e` | 288 × k slices | Multi-scalar multiplication on G2. | +| `BLS12_PAIRING_CHECK` | `0x0f` | 384 × k slices | Verify `Π e(G1_i, G2_i) == 1`, the core check for BLS signature verification. | +| `BLS12_MAP_FP_TO_G1` | `0x10` | 64 | Map a field element (`Fp`) onto the G1 curve. | +| `BLS12_MAP_FP2_TO_G2` | `0x11` | 128 | Map a field element (`Fp2`) onto the G2 curve (used in hash-to-curve). | + +**Input encoding** (per EIP-2537): + +- `Fp` element: 64 bytes, a 48-byte field element left-padded to 64 bytes (16 bytes of leading zeros). +- `G1` point: 128 bytes, two `Fp` elements (`x`, `y`). +- `G2` point: 256 bytes, two `Fp2` elements, each `Fp2 = (c0, c1)` written as two `Fp` values. +- Scalar (for MSM): 32 bytes, big-endian, full 256-bit width. + +Each MSM input is `point ‖ scalar`, repeated `k` times. The pairing check input is `(G1_i ‖ G2_i)` tuples of 384 bytes each, repeated `k` times. + +### Example: BLS signature verification + +The most common use case is verifying a BLS signature against a public key and message hash. The pairing check verifies `e(signature, G2_generator) == e(H(m), public_key)`, which the precompile expresses as `Π e(G1, G2) == 1` by including the second pair with a negated G1 generator. + +```solidity Solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +/// @title BLSVerifier +/// @notice Verifies a single BLS signature using EIP-2537 precompiles on Hedera/Ethereum. +contract BLSVerifier { + /// Address of BLS12_PAIRING_CHECK precompile. + address constant BLS12_PAIRING_CHECK = address(0x0f); + + /// Address of BLS12_MAP_FP2_TO_G2 (used for hash-to-curve message encoding). + address constant BLS12_MAP_FP2_TO_G2 = address(0x11); + + /// Verifies that `signature` (G2 point, 256 bytes) was produced by the holder of + /// `publicKey` (G1 point, 128 bytes) over the G2-encoded message `messagePoint` + /// (256 bytes, typically produced by hash-to-curve onto G2 off-chain or via + /// BLS12_MAP_FP2_TO_G2 on-chain). + /// + /// Pairing check: e(-G1_generator, signature) · e(publicKey, messagePoint) == 1 + function verify( + bytes calldata publicKey, // 128 bytes, G1 point + bytes calldata messagePoint, // 256 bytes, G2 point + bytes calldata signature // 256 bytes, G2 point + ) external view returns (bool valid) { + require(publicKey.length == 128, "bad pubkey len"); + require(messagePoint.length == 256, "bad msg len"); + require(signature.length == 256, "bad sig len"); + + // Negated G1 generator (-G1) in EIP-2537's 128-byte encoding: the canonical + // BLS12-381 generator's x coordinate, then (p - y), each left-padded to 64 bytes. + // As with any cryptographic constant, exercise this contract against the + // EIP-2537 test vectors before production use. + bytes memory negG1 = hex"0000000000000000000000000000000017f1d3a73197d7942695638c4fa9ac0f" + hex"c3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb" + hex"00000000000000000000000000000000114d1d6855d545a8aa7d76c8cf2e21f2" + hex"67816aef1db507c96655b9d5caac42364e6f38ba0ecb751bad54dcd6b939c2ca"; + + // Build pairing input: (negG1 ‖ signature) ‖ (publicKey ‖ messagePoint) = 768 bytes + bytes memory input = bytes.concat(negG1, signature, publicKey, messagePoint); + + bytes memory output = new bytes(32); + bool ok; + assembly { + ok := staticcall( + gas(), + BLS12_PAIRING_CHECK, + add(input, 0x20), + 768, + add(output, 0x20), + 32 + ) + } + require(ok, "precompile failed"); + + // Pairing check returns 32 bytes: 0x00..01 = valid, 0x00..00 = invalid. + valid = (uint256(bytes32(output)) == 1); + } +} +``` + +### Example: aggregate two G1 public keys + +BLS aggregation is the canonical reason to want native curve precompiles. Adding two G1 public keys lets you combine signatures over the same message into a single signature that verifies against the sum of the keys. + +```solidity Solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.30; + +contract BLSAggregator { + address constant BLS12_G1ADD = address(0x0b); + + /// Adds two G1 points (each 128 bytes). Returns the 128-byte sum. + function aggregate(bytes calldata a, bytes calldata b) external view returns (bytes memory sum) { + require(a.length == 128 && b.length == 128, "bad point len"); + + bytes memory input = bytes.concat(a, b); // 256 bytes + sum = new bytes(128); + + bool ok; + assembly { + ok := staticcall(gas(), BLS12_G1ADD, add(input, 0x20), 256, add(sum, 0x20), 128) + } + require(ok, "G1ADD failed"); + } +} +``` + +> See the [EIP-2537 specification](https://eips.ethereum.org/EIPS/eip-2537) for the full input format of each precompile and the test vectors used to validate implementations. + +Reference: [HIP-206](https://hips.hedera.com/hip/hip-206), [HIP-865](https://hips.hedera.com/hip/hip-865), [HIP-1341](https://hips.hedera.com/hip/hip-1341) + +## Operational-Based Throttling + +While most **EVM-compatible networks** use per-block gas limits for resource control, Hedera uses **time-based throttling**. Following **[HIP-1249](https://hips.hedera.com/hip/hip-1249)**, Hedera has transitioned from **gas-per-second** to **operations-per-second (ops/sec) throttling**, controlling network throughput based on actual computational demands rather than gas estimates. This potentially supports **significantly higher throughput** while maintaining EVM compatibility. + +**Ops costs** are derived from **nanosecond performance benchmarks** with safety margins, covering **EVM opcodes**, **precompiles**, and **system contracts**. Gas continues for user billing and per-transaction limits, separating cost calculation from throttling. + + +**Performance**: Real-world testing shows substantial improvements, with **Uniswap** achieving over **150 million gas/sec** compared to the previous **15 million gas/sec** limit. + + +### Transaction Execution Outcomes + +With **operational-based throttling**, transaction processing follows specific patterns based on resource availability: + +**Ops Throttle Exhausted**: When the operations-per-second throttle is exhausted either before execution begins or during execution, transactions fail with a `THROTTLED_AT_CONSENSUS` error and are charged only the **[intrinsic gas fee](/evm/development/gas-fees#intrinsic-gas)**. + +**Gas Limit Exhausted**: If a transaction's gas limit is exhausted before the ops throttle, it fails with an **out-of-gas error** and users are charged for the full gas used, with ops deducted for work completed. + +**Successful Execution**: For successful transactions, users are charged for the **exact gas used** and the corresponding ops units are deducted from the throttle bucket. + +## Gas Reservation and Unused Gas Refund + +Hedera throttles transactions **before consensus**, and nodes limit the number of transactions they can submit to the network. At **consensus time**, if the maximum number of transactions is exceeded, the excess transactions are not evaluated and are canceled with a **busy state**. Throttling by variable gas amounts provides challenges to this system, where the nodes only submit a share of their transaction limit. + +To address this, Hedera now uses **operational-based throttling** that applies only at **consensus**. The system operates with: + +- **Frontend (ingest/precheck)**: Uses **TPS limits** only with no gas-based throttling +- **Backend (consensus)**: Applies **operations-per-second (ops) throttling** based on actual computational work performed + +It is impossible to know the actual evaluated gas pre-consensus because the network state can directly impact the flow of the transaction, which is why pre-consensus uses the `gasLimit` field and will be referred to as the **gas reservation**. + +**Contract query requests** are unique and bypass the consensus stage altogether. These requests are executed solely on the local node that receives them and only influence that specific node's precheck throttle. + +To ensure transactions can execute properly, setting a **higher gas reservation** than will be used by execution is common. On **Ethereum mainnet**, the entire reservation is charged to the account before execution, and the unused portion is credited back. However, Ethereum utilizes a **[memory pool (mempool)](/support/glossary#mempool)** and does transaction ordering at block production time, allowing the block limit to be based only on used and not reserved gas. + +Users are charged only for the **actual gas used** during transaction execution, with **unused gas being fully refunded**. This aligns with Ethereum's billing model and eliminates the previous minimum charge requirements. + +## Maximum Gas Per Transaction + +Each transaction on Hedera is capped by a **per-transaction gas limit**. If a transaction's `gasLimit` exceeds this cap, it is rejected during precheck with the `INDIVIDUAL_TX_GAS_LIMIT_EXCEEDED` error and does not proceed to consensus. This gas metering approach ensures efficient resource use, preventing excessive consumption while allowing flexibility for larger, more complex smart contracts. + +Per-transaction gas limits remain unchanged (e.g., **15 million gas per transaction**), while network throughput is now managed through **operational-based throttling**. Refer to [HIP‑1249](https://hips.hedera.com/hip/hip-1249) for implementation details. + **Reference**: [HIP-185](https://hips.hedera.com/hip/hip-185) \ No newline at end of file diff --git a/evm/development/json-rpc/index.mdx b/evm/development/json-rpc/index.mdx index 6cde8dca..b078c595 100644 --- a/evm/development/json-rpc/index.mdx +++ b/evm/development/json-rpc/index.mdx @@ -8,6 +8,43 @@ The [Hiero JSON-RPC Relay](https://github.com/hiero-ledger/hiero-json-rpc-relay) The Hiero JSON RPC Relay **`msg.value`** uses `18 decimals` when it returns HBAR. As a result, the **`gasPrice`** value returns 18 decimal places since it is only utilized from the JSON RPC Relay. Refer to the [HBAR page](/native/fundamentals/hbars) for a list of Hiero APIs and the decimal places they return. +## Pectra-era transaction & query support + +Under the [Pectra hard fork](/evm/development/deploying#pectra-hard-fork) ([HIP-1340](https://hips.hedera.com/hip/hip-1340), [HIP-1341](https://hips.hedera.com/hip/hip-1341)), the relay accepts the following transaction types via `eth_sendRawTransaction`: + +| Type | Spec | Notes | +| ---- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `0` | Legacy ([EIP-155](https://eips.ethereum.org/EIPS/eip-155)) | Pre-Berlin legacy transactions. | +| `1` | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) | Optional `accessList` to pre-warm storage slots and addresses. | +| `2` | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) | `maxFeePerGas` + `maxPriorityFeePerGas`. Priority fee is ignored; Hedera fees are network-determined. | +| `4` | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | Carries an `authorizationList` for EOA code delegation. See [EOA Code Delegation](/evm/development/eoa-code-delegation). | + +Type 3 (EIP-4844 blob transactions) is rejected. See [HIP-866](https://hips.hedera.com/hip/hip-866). + +### Intrinsic-gas calculation (EIP-7623) + +The relay computes intrinsic gas using the Pectra formula, including the calldata floor introduced by [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623): + +```plain wrap +intrinsic_gas = max( + 21000 + 4 × zero_bytes + 16 × non_zero_bytes, + 21000 + 10 × (zero_bytes + 4 × non_zero_bytes) // EIP-7623 floor +) +``` + +This affects `eth_estimateGas`, `eth_call`, and `eth_sendRawTransaction` pre-validation. Most contract calls (where execution gas dominates) are unaffected. + +### Delegated-EOA queries + +After [HIP-1340](https://hips.hedera.com/hip/hip-1340), all contract-style state and trace methods work on EOA addresses that have a `delegation_address` set: + +- **`eth_getCode(eoa)`** returns the 23-byte Delegation Indicator `0xef0100 ‖ delegation_address`, or `0x` for an undelegated EOA. +- **`eth_getStorageAt(eoa, slot, block)`** returns the EOA's storage at the given slot. Slots are mutable when the delegate contract writes to them. +- **`eth_getLogs({ address: eoa, ... })`** returns logs emitted by the delegate code running in the EOA's context. +- **`eth_call`**, **`eth_estimateGas`**, **`debug_traceTransaction`**, and **`debug_traceCall`** all accept EOA targets and resolve them through the delegation. + +HTS token and HSS schedule proxy accounts now also return a stable `0xef0100 ‖ ` Delegation Indicator from `eth_getCode` instead of a dynamically synthesized `DELEGATECALL` stub. Existing facade calls (`IERC20.transfer`, `IHRC.associate`, etc.) continue to work unchanged. + ## JSON RPC Relay Options for the Hedera Network When interacting with smart contracts on Hedera, developers have several options for setting up a JSON RPC Relay. Each choice comes with unique advantages and trade-offs based on your project's needs, scalability, and operational preferences. @@ -16,7 +53,7 @@ When interacting with smart contracts on Hedera, developers have several options 2. [**Self-hosted JSON RPC Relay**](https://github.com/hiero-ledger/hiero-json-rpc-relay/tree/main)**:** Running your own JSON RPC Relay offers complete control over configurations and network selection (testnet, previewnet, mainnet). It is best suited for projects requiring flexibility, high reliability, and scalability, especially in production environments. 3. [**Third-party JSON RPC Relay Services**](#community-hosted-json-rpc-relays)**:** Several third-party providers offer managed JSON RPC Relay services with different levels of reliability, service-level agreements (SLAs), and fee structures. These services remove infrastructure maintenance overhead, allowing teams to focus more on development (*you can find the list of supported services* [*below*](#community-hosted-json-rpc-relays)*).* -| Feature | Hiero Local Node | Self-hosted RPC Relay | Third-party RPC Relay | +| Feature | Hiero Local Node | Self-hosted Relay | Third-party RPC Relay | | ----------------------------- | :-------------------: | :-------------------: | :------------------------------------------: | | **Infrastructure Management** | Minimal | Required | None | | **Reliability and Stability** | High (local) | High | Variable by SLA | @@ -25,7 +62,7 @@ When interacting with smart contracts on Hedera, developers have several options | **Ideal Use Case** | Testing & Development | Testing & Production | Builders who prefer convenience & Production | -Read the [**JSON RPC Relay Comparison blog**](https://hedera.com/blog/selecting-a-json-rpc-relay-for-your-project) post to learn more about the different options! + Read the [**JSON RPC Relay Comparison blog**](https://hedera.com/blog/selecting-a-json-rpc-relay-for-your-project) post to learn more about the different options! ## Community Hosted JSON-RPC Relays @@ -34,7 +71,11 @@ Anyone in the community can set up their own JSON RPC relay that applications ca #### JSON-RPC Relay Endpoints -
NetworkChain IDHashio RPC URLthirdweb RPC URL
Mainnet295https://mainnet.hashio.io/apihttps://295.rpc.thirdweb.com
Testnet296https://testnet.hashio.io/apihttps://296.rpc.thirdweb.com
Previewnet297https://previewnet.hashio.io/api**https://297.rpc.thirdweb.com
+| Network | Chain ID | Hashio RPC URL | thirdweb RPC URL | +| --- | :---: | :---: | :---: | +| **Mainnet** | `295` | [https://mainnet.hashio.io/api](https://mainnet.hashio.io/api) | [https://295.rpc.thirdweb.com](https://295.rpc.thirdweb.com) | +| **Testnet** | `296` | [https://testnet.hashio.io/api](https://testnet.hashio.io/api) | [https://296.rpc.thirdweb.com](https://296.rpc.thirdweb.com) | +| **Previewnet** | `297` | [https://previewnet.hashio.io/api](https://previewnet.hashio.io/api) | [https://297.rpc.thirdweb.com](https://297.rpc.thirdweb.com) | ### 🚨 **PLEASE NOTE** diff --git a/evm/development/security.mdx b/evm/development/security.mdx index 24d64927..5200f2f1 100644 --- a/evm/development/security.mdx +++ b/evm/development/security.mdx @@ -3,7 +3,7 @@ title: "Smart Contract Security" --- -The [Hedera Smart Contract Service (HSCS)](/support/glossary#hedera-smart-contract-service-hscs) integrates the features of Hedera's third-generation native entity functionality—high throughput, fast finality, predictable and affordable fees, and fair transaction ordering—with a highly optimized and performant second-generation [Ethereum Virtual Machine (EVM)](/support/glossary#ethereum-virtual-machine-evm). We aim to offer comprehensive support for smart contracts originally written for other EVM-compatible chains and to enable their seamless deployment on Hedera. +The [Hedera Smart Contract Service (HSCS)](/support/glossary#hedera-smart-contract-service-hscs) integrates the features of Hedera's third-generation native entity functionality (high throughput, fast finality, predictable and affordable fees, and fair transaction ordering) with a highly optimized and performant second-generation [Ethereum Virtual Machine (EVM)](/support/glossary#ethereum-virtual-machine-evm). We aim to offer comprehensive support for smart contracts originally written for other EVM-compatible chains and to enable their seamless deployment on Hedera. *** @@ -36,14 +36,23 @@ To address this, the core Hedera engineers thoroughly analyzed the Smart Contrac In the new security model, account key signatures cannot provide authorization for contract actions. Its key characteristics include: -* Smart contracts can only change their own storage or the storage they were [delegate called](https://docs.soliditylang.org/en/v0.8.19/introduction-to-smart-contracts.html#delegatecall-and-libraries) with. +* Smart contracts can only change their own storage or the storage they were [delegate called](https://docs.soliditylang.org/en/v0.8.19/introduction-to-smart-contracts.html#delegatecall-and-libraries) with, **or if an EOA has set up a [Code Delegation](/evm/development/eoa-code-delegation) targeting that contract**. * System smart contracts may **not** be delegate called, except from the Token proxy/facade flow, e.g., [HIP 719](https://hips.hedera.com/hip/hip-719). In such cases, HTS tokens are represented as smart contracts (see [HIP 218](https://hips.hedera.com/hip/hip-218)) for common ERC methods. -* Smart contracts can change an EOAs storage only if the contract ID is contained in the EOAs key. +* Smart contracts can change an EOAs storage only if the contract ID is contained in the EOAs key, **or if the EOA has explicitly delegated execution to the contract under [HIP-1340](https://hips.hedera.com/hip/hip-1340)**. * Smart contracts can change an EOAs balance if approved for a token allowance for a specific token held by the EOA. + +**Pectra update ([HIP-1340](https://hips.hedera.com/hip/hip-1340)).** With EOA Code Delegation, an EOA owner can opt in to having a specific contract's code execute in their account's context, similar to how `DELEGATECALL` runs Contract B's code in Contract A's frame. Authorization comes from the EOA itself (signing an EIP-7702 authorization or a `CryptoUpdate`), so the v2 boundary is preserved: only the EOA owner can grant a delegate access to their state. Calls whose 4-byte selector matches a [Hedera Account Service](/evm/hedera-services/system-contracts/account-service) facade function (`hbarAllowance`, `hbarApprove`, `setUnlimitedAutomaticAssociations`) bypass any user-set delegation and always route to HAS. Direct delegation to system contracts from a regular EOA is forbidden, and those calls no-op. + + #### Boundary comparison table -
Boundary Specv1 Modelv2 ModelChange
Storage ChangesSmart Contracts could only change their own storage or the storage they were delegate called withSmart contracts can only change their own storage or the storage they were delegate called withN
System Contract Call TypesSystem smart contracts could be delegate called in order to carry out Hedera Token Service operations on behalf of another account (EOA) or contract.System smart contracts may not be delegate called, except from the Token facade flow, which presents HTS tokens as smart contracts for common ERC methods.Y
Permissioned Account Storage ChangesSmart Contracts could change an EOA’s storage with the appropriate signature in the transaction.Smart contracts can change an EOAs storage if the contract ID is contained in the EOAs key.Y
Permissioned Account Balance ChangesSmart Contracts could change an accounts (EOA or contract) balance with the appropriate signature in the transaction or with prior addition to an allowance approval listSmart contracts can change an EOAs balance if they have been approved a token allowance.Y
+| Boundary Spec | v1 Model | v2 Model | Change | +| --- | --- | --- | :---: | +| Storage Changes | Smart Contracts could only change their own storage or the storage they were delegate called with | Smart contracts can only change their own storage or the storage they were delegate called with | **N** | +| System Contract Call Types | System smart contracts could be delegate called in order to carry out Hedera Token Service operations on behalf of another account (EOA) or contract. | System smart contracts may not be delegate called, except from the Token facade flow, which presents HTS tokens as smart contracts for common ERC methods. | **Y** | +| Permissioned Account Storage Changes | Smart Contracts could change an EOA’s storage with the appropriate signature in the transaction. | Smart contracts can change an EOAs storage if the contract ID is contained in the EOAs key. | **Y** | +| Permissioned Account Balance Changes | Smart Contracts could change an accounts (EOA or contract) balance with the appropriate signature in the transaction or with prior addition to an allowance approval list | Smart contracts can change an EOAs balance if they have been approved a token allowance. | **Y** | In summary, HSCS utilizes a three-level security approach: @@ -96,13 +105,46 @@ In summary, a delegate call executes the calling contract's code in the context Applying this to the security model changes, the following table summarizes the authorization check changes. -
ScenarioAuthorization checkOld ModelNew Model
Smart contract A can change its own state using a callsender = Contract AYY
Smart contract A can change EOA’s state via callsender = EOANN
Smart contract B can change contract A’s state via callsender = ANN
Smart contract A can change EOA’s state via delegate callsender = EOAYY
Smart contract B can change contract A’s state via delegate callsender = Contract AYY
System smart contracts can change another accounts (EOA or contract A or contract B) state via callsender = accountNN
System smart contract can change another accounts EOA or contract A or contract B) state via delegate callsender = accountNN
System contracts can change an accounts (EOA or contact A or contract B) state via call with the appropriate signaturesignature map contains signature of accounts (EOA or contact A or contract B respectively)YN
System smart contract can change another accounts (EOA or contact A or contract B) state via delegate call with the appropriate signaturesignature map contains signature of accounts (EOA or contact A or contract B)YN
Contract A or B can call a system contract via a call-YY
Contract A or B can call a system contract via a delegate call-YN
+| Scenario | Authorization check | Old Model | New Model | +| --- | --- | :---: | :---: | +| Smart contract A can change its own state using a call | sender = Contract A | Y | Y | +| Smart contract A can change EOA’s state via call | sender = EOA | N | N | +| Smart contract B can change contract A’s state via call | sender = A | N | N | +| Smart contract A can change EOA’s state via delegate call **or if EOA has set up a Code Delegation to A** | sender = EOA (delegate call); EOA owner signed authorization (Code Delegation) | Y | Y | +| Smart contract B can change contract A’s state via delegate call | sender = Contract A | Y | Y | +| System smart contracts can change another accounts (EOA or contract A or contract B) state via call | sender = account | N | N | +| System smart contract can change another accounts EOA or contract A or contract B) state via delegate call | sender = account | N | N | +| **System contracts can change an accounts (EOA or contact A or contract B) state via call with the appropriate signature** | **signature map contains signature of accounts (EOA or contact A or contract B respectively)** | **Y** | **N** | +| **System smart contract can change another accounts (EOA or contact A or contract B) state via delegate call with the appropriate signature** | **signature map contains signature of accounts (EOA or contact A or contract B)** | **Y** | **N** | +| Contract A or B can call a system contract via a call | - | Y | Y | +| **Contract A or B can call a system contract via a delegate call** | **-** | **Y** | **N** | +| **Regular EOA can set Code Delegation directly to a system contract (HTS / HSS / HAS / Exchange Rate / PRNG)** | - | - | **N (no-op)** | At the time of the change, the [HTS system contract](https://github.com/hiero-ledger/hiero-contracts/tree/main/contracts/token-service) was the only pathway to expose Hedera API functionality through Smart Contracts. As such, it’s fair to consider the differences between pre and post-security model updates when observing HTS system contract state-changing functions. #### Existing HTS system contract impacts summary -
IHederaTokenService System Smart Contract Functionv1 Model Authorization Requirementsv2 Model Authorization RequirementsImpacts CodeSolution by Developers
approve, approveNFTsignature map contains accounts admin key signaturemsg.sender must be entity to be modifiedY

Upgrade contracts

or

Upgrade DApps to provide explicit user approval

*Additional secure pathways: HIP 376 IERC.approve()

associateTokensignature map contains account admin key signaturemsg.sender must be entity to be modifiedY

Upgrade contracts

or

Upgrade DApps to provide explicit user associate

*Additional secure pathways: HIP 719 IHRC.associate()

burnToken

signature map contains token burn key signature

or

Contract Id satisfies Token.supplyKey requirements

Contract Id satisfies Token.supplyKey requirementsYToken admin must set desired contract in Supply key
createFungibleToken, createFungibleTokenWithCustomFees, createNonFungibleToken, createNonFungibleTokenWithCustomFees

signature map contains affected account admin key signature(s) in treasury

or

autoRenew assignment case

msg.sender must be entity to be modified in treasury

or

autoRenew assignment case

Y-
cryptoTransfer

signature map contains sender admin key signature

or

Contract Id satisfies Entity.key requirements

msg.sender must be entity to be modified in treasury

or

autoRenew assignment case

YUpgrade DApps to provide explicit user approval.
deleteToken

signature map contains token admin key signature

or

Contract Id satisfies Token.adminKey requirements

Contract Id satisfies Token.adminKey requirementsYToken admin must set desired contract in admin key
dissociateToken, dissociateTokenssignature map contains admin key signaturemsg.sender must be entity to be modifiedY

Upgrade contracts

or

Upgrade DApps to provide explicit user dissociate

*Additional secure pathways: HIP 719 IHRC.associate()

freezeToken

signature map contains freeze key signature

or

Contract Id satisfies Token.freezeKey requirements

Contract Id satisfies Token.freezeKey requirementsYToken admin must set desired contract in freeze key
grantTokenKyc

signature map contains kyc key signature

or

Contract Id satisfies Token.freezeKey requirements

Contract Id satisfies Token.kycKey requirementsYToken admin must set desired contract in kyc key
mintToken

signature map contains appropriate signature

or

Contract Id satisfies Token.supplyKey requirements

Contract Id satisfies Token.supplyKey requirementsYToken admin must set desired contract in Supply key
pauseToken

signature map contains pause key signature

or

Contract Id satisfies Token.pauseKey requirements

Contract Id satisfies Token.pauseKey requirementsYToken admin must set desired contract in pause key
revokeTokenKyc

signature map contains kyc key signature

or

Contract Id satisfies Token.freezeKey requirements

Contract Id satisfies Token.kycKey requirementsYToken admin must set desired contract in kyc key
setApprovalForAllsignature map contains admin key signaturemsg.sender must be entity to be modifiedY

Upgrade contracts

or

Upgrade DApps to provide explicit user associate

*Additional secure pathways: HIP 376 IERC.setApprovalForAll()

transferFrom, transferFromNFT

signature map contains admin key signature

or

Spender must have been pre-approved an allowance

msg.sender must be entity to be modified in treasury

or

autoRenew assignment case

YUpgrade DApps to provide explicit user approval.
transferToken, transferTokens, transferNFT, transferNFTs

signature map contains admin key signature

or

Contract Id satisfies Entity.key requirements

or

Contract has been approved an allowance to spend by owner

msg.sender must be balance owner.

If not 1. Contract Id satisfies Entity.key requirements

or

2. Contract has been approved an allowance to spend by owner

YUpgrade DApps to provide explicit user approval.
updateTokenInfo, updateTokenExpiryInfo, updateTokenKeys

signature map contains token admin key signature

or

Contract Id satisfies Token.adminKey requirements

Contract Id satisfies Token.adminKey requirementsYToken admin must set desired contract in admin key
wipeTokenAccount, wipeTokenAccountNFT

signature map contains token wipe key signature

or

Contract Id satisfies Token.wipeKey requirements

Contract Id satisfies Token.wipeKey requirementsYToken admin must set desired contract in Wipe key
unfreezeToken

signature map contains token freeze key signature

or

Contract Id satisfies Token.freezeKey requirements

Contract Id satisfies Token.freezeKey requirementsYToken admin must set desired contract in freeze key
unpauseToken

signature map contains token pause key signature

or

Contract Id satisfies Token.pauseKey requirements

Contract Id satisfies Token.pauseKey requirementsYToken admin must set desired contract in pause key
+| IHederaTokenService System Smart Contract Function | v1 Model Authorization Requirements | v2 Model Authorization Requirements | Impacts Code | Solution by Developers | +| :---: | :---: | :---: | :---: | :---: | +| **approve, approveNFT** | signature map contains accounts admin key signature | `msg.sender` must be entity to be modified | Y | Upgrade contracts
or
Upgrade DApps to provide explicit user approval
*Additional secure pathways: [HIP 376](https://hips.hedera.com/hip/hip-376) IERC.approve() | +| **associateToken** | signature map contains account admin key signature | `msg.sender` must be entity to be modified | Y | Upgrade contracts
or
Upgrade DApps to provide explicit user associate
*Additional secure pathways: [HIP 719](https://hips.hedera.com/hip/hip-719) IHRC.associate() | +| **burnToken** | signature map contains token burn key signature
or
Contract Id satisfies Token.supplyKey requirements | Contract Id satisfies Token.supplyKey requirements | Y | Token admin must set desired contract in Supply key | +| **createFungibleToken, createFungibleTokenWithCustomFees, createNonFungibleToken, createNonFungibleTokenWithCustomFees** | signature map contains affected account admin key signature(s) in treasury
or
autoRenew assignment case | `msg.sender` must be entity to be modified in treasury
or
autoRenew assignment case | Y | - | +| **cryptoTransfer** | signature map contains sender admin key signature
or
Contract Id satisfies Entity.key requirements | `msg.sender` must be entity to be modified in treasury
or
autoRenew assignment case | Y | Upgrade DApps to provide explicit user approval. | +| **deleteToken** | signature map contains token admin key signature
or
Contract Id satisfies Token.adminKey requirements | Contract Id satisfies Token.adminKey requirements | Y | Token admin must set desired contract in admin key | +| **dissociateToken, dissociateTokens** | signature map contains admin key signature | `msg.sender` must be entity to be modified | Y | Upgrade contracts
or
Upgrade DApps to provide explicit user dissociate
*Additional secure pathways: [HIP 719](https://hips.hedera.com/hip/hip-719) IHRC.associate() | +| **freezeToken** | signature map contains freeze key signature
or
Contract Id satisfies Token.freezeKey requirements | Contract Id satisfies Token.freezeKey requirements | Y | Token admin must set desired contract in freeze key | +| **grantTokenKyc** | signature map contains kyc key signature
or
Contract Id satisfies Token.freezeKey requirements | Contract Id satisfies Token.kycKey requirements | Y | Token admin must set desired contract in kyc key | +| **mintToken** | signature map contains appropriate signature
or
Contract Id satisfies Token.supplyKey requirements | Contract Id satisfies Token.supplyKey requirements | Y | Token admin must set desired contract in Supply key | +| **pauseToken** | signature map contains pause key signature
or
Contract Id satisfies Token.pauseKey requirements | Contract Id satisfies Token.pauseKey requirements | Y | Token admin must set desired contract in pause key | +| **revokeTokenKyc** | signature map contains kyc key signature
or
Contract Id satisfies Token.freezeKey requirements | Contract Id satisfies Token.kycKey requirements | Y | Token admin must set desired contract in kyc key | +| **setApprovalForAll** | signature map contains admin key signature | `msg.sender` must be entity to be modified | Y | Upgrade contracts
or
Upgrade DApps to provide explicit user associate
*Additional secure pathways: [HIP 376](https://hips.hedera.com/hip/hip-376) IERC.setApprovalForAll() | +| **transferFrom, transferFromNFT** | signature map contains admin key signature
or
Spender must have been pre-approved an allowance | `msg.sender` must be entity to be modified in treasury
or
autoRenew assignment case | Y | Upgrade DApps to provide explicit user approval. | +| **transferToken, transferTokens, transferNFT, transferNFTs** | signature map contains admin key signature
or
Contract Id satisfies Entity.key requirements
or
Contract has been approved an allowance to spend by owner | `msg.sender` must be balance owner.
If not 1. Contract Id satisfies Entity.key requirements
or
2. Contract has been approved an allowance to spend by owner | Y | Upgrade DApps to provide explicit user approval. | +| **updateTokenInfo, updateTokenExpiryInfo, updateTokenKeys** | signature map contains token admin key signature
or
Contract Id satisfies Token.adminKey requirements | Contract Id satisfies Token.adminKey requirements | Y | Token admin must set desired contract in admin key | +| **wipeTokenAccount, wipeTokenAccountNFT** | signature map contains token wipe key signature
or
Contract Id satisfies Token.wipeKey requirements | Contract Id satisfies Token.wipeKey requirements | Y | Token admin must set desired contract in Wipe key | +| **unfreezeToken** | signature map contains token freeze key signature
or
Contract Id satisfies Token.freezeKey requirements | Contract Id satisfies Token.freezeKey requirements | Y | Token admin must set desired contract in freeze key | +| **unpauseToken** | signature map contains token pause key signature
or
Contract Id satisfies Token.pauseKey requirements | Contract Id satisfies Token.pauseKey requirements | Y | Token admin must set desired contract in pause key | **Note:** While the changes impact user experience, requiring more explicit steps, they more than proportionately increase user and network security across the board. The team continues to push diligently to provide the community with secure and scalable API solutions to enable them to build creative dApps and carve out their own shared world on the ledger. diff --git a/evm/differences/index.mdx b/evm/differences/index.mdx index de2988c6..ce81c430 100644 --- a/evm/differences/index.mdx +++ b/evm/differences/index.mdx @@ -34,6 +34,30 @@ Hedera supports jumbo Ethereum transactions (introduced in [HIP-1086](https://hi --- +## Pectra Compatibility + +Hedera adopts the applicable EIPs from Ethereum's Pectra upgrade under [HIP-1341](https://hips.hedera.com/hip/hip-1341), so Ethereum tooling that targets Pectra (Prague EVM execution layer) works on Hedera with no special handling: + +| Pectra capability | EVM-equivalent on Hedera | Notes | +| ---------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| **BLS12-381 precompiles** ([EIP-2537](https://eips.ethereum.org/EIPS/eip-2537)) | ✅ | Seven new precompiles at addresses `0x0b`–`0x11`. Callable via `call`/`staticcall` exactly as on Ethereum. See [Gas and Fees](/evm/development/gas-fees#hedera-system-contract-gas). | +| **Calldata gas floor** ([EIP-7623](https://eips.ethereum.org/EIPS/eip-7623)) | ✅ | Same formula: `21000 + 10 × (zero_bytes + 4 × non_zero_bytes)` floor. Most contract calls (where execution gas dominates) are unaffected. | +| **EOA Code Delegation** ([EIP-7702](https://eips.ethereum.org/EIPS/eip-7702)) | ✅ | Hedera accepts Type 4 `EthereumTransaction` payloads carrying an `authorization_list`. Account delegation can additionally be configured via native HAPI (`CryptoCreate` / `CryptoUpdate`). See [EOA Code Delegation](/evm/development/eoa-code-delegation) and [HIP-1340](https://hips.hedera.com/hip/hip-1340). | +| **Blob transactions** ([EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), [EIP-7691](https://eips.ethereum.org/EIPS/eip-7691)) | ❌ | Hedera does not support blobs ([HIP-866](https://hips.hedera.com/hip/hip-866)). Type 3 transactions are rejected. Use [jumbo EthereumTransactions](#jumbo-ethereum-transactions) for large payloads. | + +### Type 4 transactions and smart accounts + +Type 4 transactions enable **smart-account** patterns (transaction batching, sponsored gas, session keys, privilege de-escalation) without migrating funds to a new contract wallet. The EOA's address, balance, NFTs, and tokens stay put; only the *execution* is delegated to a contract's code running in the EOA's storage frame. + +Two important Hedera-specific behaviors apply: + +1. **HAS precedence.** When an EOA has a code delegation set, calls whose 4-byte selector matches a [Hedera Account Service](/evm/hedera-services/system-contracts/account-service) facade function (`hbarAllowance`, `hbarApprove`, `setUnlimitedAutomaticAssociations`) are routed to HAS and take precedence over the user's delegation. +2. **Account-type applicability.** Only ECDSA accounts with a public-key-derived alias can configure delegation via Type 4 transactions (same rule as for submitting any Ethereum transaction). ED25519 accounts and ECDSA accounts with a long-zero alias must use the native HAPI path (`CryptoCreate` / `CryptoUpdate`). + +*📣 See the full feature page:* [*EOA Code Delegation*](/evm/development/eoa-code-delegation)*.* + +--- + ## EVM Developers: What Changes on Hedera The following topics cover the most common differences when coming from Ethereum: diff --git a/evm/hedera-services/system-contracts/account-service.mdx b/evm/hedera-services/system-contracts/account-service.mdx index 00d6feb2..565d3b59 100644 --- a/evm/hedera-services/system-contracts/account-service.mdx +++ b/evm/hedera-services/system-contracts/account-service.mdx @@ -8,7 +8,7 @@ sidebarTitle: "Account Service" EVM developers should note that `ECRECOVER` natively supports ECDSA accounts on Hedera. Aliases for these accounts, derived using Keccak-256(publicKey), are fully compatible with Ethereum's `ECRECOVER` logic. This enables seamless interaction with ECDSA accounts on Hedera using `ECRECOVER`, just like standard Ethereum accounts. -To verify an ECDSA signature, developers can call `ECRECOVER(messageHash, r, s, v)` in Ethereum smart contracts. If the recovered address matches the alias of a Hedera account, the signer is confirmed to control the account. No special integration is needed—`ECRECOVER` functions as a standard EVM precompiled contract on Hedera +To verify an ECDSA signature, developers can call `ECRECOVER(messageHash, r, s, v)` in Ethereum smart contracts. If the recovered address matches the alias of a Hedera account, the signer is confirmed to control the account. No special integration is needed; `ECRECOVER` functions as a standard EVM precompiled contract on Hedera **Note**: This functionality is specific to ECDSA accounts with Keccak-256(publicKey) aliases. For ED25519 accounts, Hedera offers alternative authorization methods, such as `isAuthorized()` or `isAuthorizedRaw()`, to verify control of an account. For details, refer to the [Hedera Account Service System Contract](https://github.com/hiero-ledger/hiero-contracts/tree/main/contracts/account-service). See below for details on these two precompile functions. @@ -41,7 +41,12 @@ By addressing these use cases, HIP-632 provides a seamless way for developers to * Provides a way to confirm authorization based on Hedera’s advanced account-based key management. * Returns `true` if the signature is valid and linked to the account, otherwise `false`. -
ParameterDescription
addressA 20-byte identifier used to represent an account on the Hedera network or an EVM-compatible account.
messageThe original plaintext data or payload that the signature is derived from. This is the information that was signed to produce the signature.
messaHashA cryptographic hash of the message, calculated using an algorithm like SHA-256 or Keccak-256. This is typically what is signed instead of the raw message.
signatureBlobA concatenation of the digital signature components, typically including r, s, and v values for ECDSA, or the equivalent data for ED25519 signatures.
+| Parameter | Description | +| --- | --- | +| **address** | A 20-byte identifier used to represent an account on the Hedera network or an EVM-compatible account. | +| **message** | The original plaintext data or payload that the signature is derived from. This is the information that was signed to produce the signature. | +| **messaHash** | A cryptographic hash of the `message`, calculated using an algorithm like SHA-256 or Keccak-256. This is typically what is signed instead of the raw message. | +| **signatureBlob** | A concatenation of the digital signature components, typically including `r`, `s`, and `v` values for ECDSA, or the equivalent data for ED25519 signatures. | #### Behavior and Cost @@ -57,3 +62,31 @@ Gas fee schedule and calculation **Reference**: [HIP-632](https://hips.hedera.com/hip/hip-632) + +*** + +## HAS Facade Precedence Over EOA Code Delegation + +When [EOA Code Delegation](/evm/development/eoa-code-delegation) ([HIP-1340](https://hips.hedera.com/hip/hip-1340)) was introduced in the Pectra upgrade, EOAs gained the ability to redirect calls into a delegate contract's bytecode. To preserve the existing user-facing behavior of HAS facade calls, **HAS facade selectors take precedence** over any user-set delegation. + +When the Smart Contract Service receives a call whose target is an EOA, it inspects the first 4 bytes of `callData`: + +1. **If the selector matches a HAS facade function** → the call is routed to HAS. Any `delegation_address` configured on the EOA is ignored for this call. +2. **Else if the EOA has a code delegation set** → the delegate contract's code is executed in the EOA's storage context. +3. **Otherwise** → no-op (the call carries through any value transfer but executes no code). + +### Intercepted HAS facade selectors + +| Function signature | 4-byte selector | +| --------------------------------------------------------------- | --------------- | +| `hbarAllowance(address spender)` | `0xbbee989e` | +| `hbarApprove(address spender, int256 amount)` | `0x86aff07c` | +| `setUnlimitedAutomaticAssociations(bool enableAutoAssociations)`| `0xf5677e99` | + +> ⚠️ **Selector-collision warning.** If your smart-account delegate happens to define a function whose 4-byte selector equals any of the above, that function will be unreachable on a delegated EOA; HAS will intercept the call first. Pick distinct signatures when designing a delegate. + +### Direct EOA delegation to system contracts is forbidden + +Setting `delegation_address` on a regular EOA to a system-contract address (HTS `0x167`, HAS `0x16a`, HSS `0x16b`, Exchange Rate `0x168`, PRNG `0x169`, or any precompile `0x01`–`0x11`) is allowed at the protocol level, but **calls to such a delegated EOA are no-ops**. Only the network-owned Token Proxy and Schedule Proxy accounts may "delegate" to a system contract; they do so via fixed Delegation Indicators set at the protocol level for the facade mechanism. + +**Reference**: [HIP-1340](https://hips.hedera.com/hip/hip-1340) diff --git a/evm/hedera-services/system-contracts/hts.mdx b/evm/hedera-services/system-contracts/hts.mdx index 3e634b76..179fc240 100644 --- a/evm/hedera-services/system-contracts/hts.mdx +++ b/evm/hedera-services/system-contracts/hts.mdx @@ -8,15 +8,91 @@ Hedera enables the native creation of fungible and non-fungible tokens through i Some of the key functions defined in the Hedera Token Service System Contract include: -
Function NameConsensus Node Release VersionHIPMethod Interface
allowance0.26HIP 514allowance(address token, address owner, address spender)
approve0.26HIP 514approve(address token, address to, uint256 tokenId)
approveNFT0.28HIP 514approveNFT(address token, address to, uint256 tokenId)
associate0.38HIP 719associate()
associateToken0.22HIP 206associateToken(address account, address token)
associateTokens0.22HIP 206associateTokens(address account, address[] memory tokens)
burnToken0.32HIP 206burnToken(address token, int64 amount, int64[] memory serialNumbers)
createFungibleToken0.32HIP 358createFungibleToken(HederaToken memory token, int64 initialTotalSupply, int32 decimals)
createFungibleTokenWithCustomFees0.30HIP 358createFungibleTokenWithCustomFees(HederaToken memory token, int64 initialTotalSupply, int32 decimals, FixedFee[] memory fixedFees, FractionalFee[] memory fractionalFees)
createNonFungibleToken0.25HIP 358createNonFungibleToken(HederaToken memory token)
createNonFungibleTokenWithCustomFees0.32HIP 358createNonFungibleTokenWithCustomFees(HederaToken memory token, FixedFee[] memory fixedFees, RoyaltyFee[] memory royaltyFees)
cryptoTransferUnreleasedHIP 206cryptoTransfer(TransferList memory transferList, TokenTransferList[] memory tokenTransfers) external returns (int64 responseCode)
deleteToken0.29HIP 514deleteToken(address token)
dissociate0.38HIP 719dissociate()
dissociateToken0.22HIP 206dissociateToken(address account, address token)
dissociateTokens0.22HIP 206dissociateTokens(address account, address[] memory tokens)
freezeToken0.29HIP 514freezeToken(address token, address account)
getApproved0.26HIP 376getApproved(address token, uint256 tokenId)
getFungibleTokenInfo0.29HIP 514getFungibleTokenInfo(address token)
getNonFungibleTokenInfo0.29HIP 514getNonFungibleTokenInfo(address token, int64 serialNumber)
getTokenCustomFees0.29HIP 514getTokenCustomFees(address token)
getTokenDefaultFreezeStatus0.29HIP 514getTokenDefaultFreezeStatus(address token)
getTokenDefaultKycStatus0.29HIP 514getTokenDefaultKycStatus(address token)
getTokenExpiryInfo0.30HIP 514getTokenExpiryInfo(address token)
getTokenInfo0.29HIP 514getTokenInfo(address token)
getTokenKey0.30HIP 514getTokenKey(address token, uint256 keyType)
getTokenType0.30HIP 514getTokenType(address token)
grantTokenKyc0.29HIP 514grantTokenKyc(address token, address account)
isAssociated0.53HIP 719isAssociated()
isApprovedForAll0.26HIP 376isApprovedForAll(address token, address owner, address operator)
isFrozen0.29HIP 514isFrozen(address token, address account)
isKyc0.29HIP 514isKyc(address token, address account)
isToken0.30HIP 514isToken(address token)
mintToken0.32HIP 206mintToken(address token, int64 amount, bytes[] memory metadata)
redirectForToken0.30HIP 218redirectForToken(address token, bytes memory data)
revokeTokenKyc0.29HIP 514revokeTokenKyc(address token, address account)
setApprovalForAll0.26HIP 376setApprovalForAll(address token, address operator, bool approved)
transferFrom0.26HIP 376transferFrom(address token, address from, address to, uint256 tokenId)
transferFromNFT0.26HIP 376transferFromNFT(address token, address from, address to, uint256 serialNumber)
transferNFT0.22HIP 206transferNFT(address token, address sender, address recipient, int64 serialNum)
transferNFTs0.22HIP 206transferNFTs(address token, address[] memory sender, address[] memory receiver, int64[] memory serialNumber)
transferToken0.22HIP 206transferToken(address token, address sender, address recipient, int64 amount)
transferTokens0.22HIP 206transferTokens(address token, address[] memory accountId, int64[] memory amount)
unfreezeToken0.29HIP 514unfreezeToken(address token, address account)
unpauseToken0.29HIP 514unpauseToken(address token)
updateTokenExpiryInfo0.32HIP 514updateTokenExpiryInfo(address token, Expiry expiry)
updateTokenInfo0.32HIP 514updateTokenInfo(address token, HederaToken hederaToken)
updateTokenKeys0.30HIP 514updateTokenKeys(address token, Expiry expiry)
wipeTokenAccount0.32HIP 514wipeTokenAccount(address token, address account, int64 amount)
wipeTokenAccountNFT0.29HIP 514wipeTokenAccountNFT(address token, address account, int64[] serialNumbers)
+| Function Name | Consensus Node Release Version | HIP | Method Interface | +| --- | :---: | :---: | --- | +| `allowance` | [0.26](/learn/release-notes/services#v0.26) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `allowance(address token, address owner, address spender)` | +| `approve` | [0.26](/learn/release-notes/services#v0.26) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `approve(address token, address to, uint256 tokenId)` | +| `approveNFT` | [0.28](/learn/release-notes/services#v0.28) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `approveNFT(address token, address to, uint256 tokenId)` | +| `associate` | [0.38](/learn/release-notes/services#v0.38) | [HIP 719](https://hips.hedera.com/hip/hip-719) | `associate()` | +| `associateToken` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `associateToken(address account, address token)` | +| `associateTokens` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `associateTokens(address account, address[] memory tokens)` | +| `burnToken` | [0.32](/learn/release-notes/services#v0.32) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `burnToken(address token, int64 amount, int64[] memory serialNumbers)` | +| `createFungibleToken` | [0.32](/learn/release-notes/services#v0.32) | [HIP 358](https://hips.hedera.com/hip/hip-358) | `createFungibleToken(HederaToken memory token, int64 initialTotalSupply, int32 decimals)` | +| `createFungibleTokenWithCustomFees` | [0.30](/learn/release-notes/services#v0.30) | [HIP 358](https://hips.hedera.com/hip/hip-358) | `createFungibleTokenWithCustomFees(HederaToken memory token, int64 initialTotalSupply, int32 decimals, FixedFee[] memory fixedFees, FractionalFee[] memory fractionalFees)` | +| `createNonFungibleToken` | [0.25](/learn/release-notes/services#v0.25) | [HIP 358](https://hips.hedera.com/hip/hip-358) | `createNonFungibleToken(HederaToken memory token)` | +| `createNonFungibleTokenWithCustomFees` | [0.32](/learn/release-notes/services#v0.32) | [HIP 358](https://hips.hedera.com/hip/hip-358) | `createNonFungibleTokenWithCustomFees(HederaToken memory token, FixedFee[] memory fixedFees, RoyaltyFee[] memory royaltyFees)` | +| `cryptoTransfer` | Unreleased | [HIP 206](https://hips.hedera.com/hip/hip-206) | `cryptoTransfer(TransferList memory transferList, TokenTransferList[] memory tokenTransfers) external returns (int64 responseCode)` | +| `deleteToken` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `deleteToken(address token)` | +| `dissociate` | [0.38](/learn/release-notes/services#v0.38) | [HIP 719](https://hips.hedera.com/hip/hip-719) | `dissociate()` | +| `dissociateToken` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `dissociateToken(address account, address token)` | +| `dissociateTokens` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `dissociateTokens(address account, address[] memory tokens)` | +| `freezeToken` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `freezeToken(address token, address account)` | +| `getApproved` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `getApproved(address token, uint256 tokenId)` | +| `getFungibleTokenInfo` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getFungibleTokenInfo(address token)` | +| `getNonFungibleTokenInfo` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getNonFungibleTokenInfo(address token, int64 serialNumber)` | +| `getTokenCustomFees` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenCustomFees(address token)` | +| `getTokenDefaultFreezeStatus` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenDefaultFreezeStatus(address token)` | +| `getTokenDefaultKycStatus` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenDefaultKycStatus(address token)` | +| `getTokenExpiryInfo` | [0.30](/learn/release-notes/services#v0.30) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenExpiryInfo(address token)` | +| `getTokenInfo` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenInfo(address token)` | +| `getTokenKey` | [0.30](/learn/release-notes/services#v0.30) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenKey(address token, uint256 keyType)` | +| `getTokenType` | [0.30](/learn/release-notes/services#v0.30) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `getTokenType(address token)` | +| `grantTokenKyc` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `grantTokenKyc(address token, address account)` | +| `isAssociated` | [0.53](/learn/release-notes/services#v0.53) | [HIP 719](https://hips.hedera.com/hip/hip-719) | `isAssociated()` | +| `isApprovedForAll` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `isApprovedForAll(address token, address owner, address operator)` | +| `isFrozen` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `isFrozen(address token, address account)` | +| `isKyc` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `isKyc(address token, address account)` | +| `isToken` | [0.30](/learn/release-notes/services#v0.30) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `isToken(address token)` | +| `mintToken` | [0.32](/learn/release-notes/services#v0.32) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `mintToken(address token, int64 amount, bytes[] memory metadata)` | +| `redirectForToken` | [0.30](/learn/release-notes/services#v0.24) | [HIP 218](https://hips.hedera.com/hip/hip-218) | `redirectForToken(address token, bytes memory data)` | +| `revokeTokenKyc` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `revokeTokenKyc(address token, address account)` | +| `setApprovalForAll` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `setApprovalForAll(address token, address operator, bool approved)` | +| `transferFrom` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `transferFrom(address token, address from, address to, uint256 tokenId)` | +| `transferFromNFT` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `transferFromNFT(address token, address from, address to, uint256 serialNumber)` | +| `transferNFT` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `transferNFT(address token, address sender, address recipient, int64 serialNum)` | +| `transferNFTs` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `transferNFTs(address token, address[] memory sender, address[] memory receiver, int64[] memory serialNumber)` | +| `transferToken` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `transferToken(address token, address sender, address recipient, int64 amount)` | +| `transferTokens` | [0.22](/learn/release-notes/services#v0.22) | [HIP 206](https://hips.hedera.com/hip/hip-206) | `transferTokens(address token, address[] memory accountId, int64[] memory amount)` | +| `unfreezeToken` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `unfreezeToken(address token, address account)` | +| `unpauseToken` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `unpauseToken(address token)` | +| `updateTokenExpiryInfo` | [0.32](/learn/release-notes/services#v0.32) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `updateTokenExpiryInfo(address token, Expiry expiry)` | +| `updateTokenInfo` | [0.32](/learn/release-notes/services#v0.32) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `updateTokenInfo(address token, HederaToken hederaToken)` | +| `updateTokenKeys` | [0.30](/learn/release-notes/services#v0.30) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `updateTokenKeys(address token, Expiry expiry)` | +| `wipeTokenAccount` | [0.32](/learn/release-notes/services#v0.32) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `wipeTokenAccount(address token, address account, int64 amount)` | +| `wipeTokenAccountNFT` | [0.29](/learn/release-notes/services#v0.29) | [HIP 514](https://hips.hedera.com/hip/hip-514) | `wipeTokenAccountNFT(address token, address account, int64[] serialNumbers)` | Given your HTS token address, you can invoke these functions: -
Function NameConsensus Node Release VersionHIPMethod Interface
allowance0.26HIP 376allowance(address owner, address spender)
approve0.26HIP 376approve(address to, uint256 tokenId)
getApproved0.26HIP 376getApproved(uint256 tokenId)
isApprovedForAll0.26HIP 376isApprovedForAll(address token, address owner, address operator)
setApprovalForAll0.26HIP 376setApprovalForAll(address operator, bool approved)
transferFrom0.26HIP 376transferFrom(address from, address to, uint256 tokenId)
+| Function Name | Consensus Node Release Version | HIP | Method Interface | +| --- | :---: | :---: | --- | +| `allowance` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `allowance(address owner, address spender)` | +| `approve` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `approve(address to, uint256 tokenId)` | +| `getApproved` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `getApproved(uint256 tokenId)` | +| `isApprovedForAll` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `isApprovedForAll(address token, address owner, address operator)` | +| `setApprovalForAll` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `setApprovalForAll(address operator, bool approved)` | +| `transferFrom` | [0.26](/learn/release-notes/services#v0.26) | [HIP 376](https://hips.hedera.com/hip/hip-376) | `transferFrom(address from, address to, uint256 tokenId)` | #### Example +### Token-proxy bytecode under Pectra ([HIP-1340](https://hips.hedera.com/hip/hip-1340)) + +Every HTS token has an EVM address that behaves like a contract, so calling `IERC20(tokenAddress).transfer(...)` or `IERC721(tokenAddress).ownerOf(...)` routes the call into the HTS system contract via the facade mechanism originally defined by [HIP-218](https://hips.hedera.com/hip/hip-218) / [HIP-719](https://hips.hedera.com/hip/hip-719) / [HIP-755](https://hips.hedera.com/hip/hip-755) / [HIP-906](https://hips.hedera.com/hip/hip-906). + +Pre-Pectra, the bytecode returned for a token-proxy address was a runtime-synthesized stub that performed a `DELEGATECALL` into the HTS system contract at `0x167`. Under Pectra, the token-proxy mechanism is re-implemented using the EIP-7702 Delegation Indicator format. The same applies to HSS schedule-proxy addresses, which point at the Hedera Schedule Service system contract. + +| Query | Pre-Pectra return | Pectra return | +| ---------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- | +| `eth_getCode(tokenAddress)` | Custom synthesized `DELEGATECALL` stub | `0xef0100 ‖ 0x0000000000000000000000000000000000000167` (HTS Delegation Indicator) | +| `ContractGetBytecodeQuery(tokenId)` | Custom synthesized `DELEGATECALL` stub | Same Delegation Indicator | +| `EXTCODEHASH(tokenAddress)` / `EXTCODESIZE(tokenAddress)` | Hash/size of the synthesized stub | Hash/size of the 23-byte Delegation Indicator | + +**User-facing impact:** None. Facade calls (`IERC20`, `IHRC.associate()`, `IHRC.dissociate()`, etc.) continue to work exactly as before; the change is purely in how the proxy is *expressed* in bytecode. + +**Tooling impact:** Block explorers, indexers, custom bytecode introspection, and any contract logic that compares HTS-token bytecode against a known fixed value must be updated. The new value is the constant 23-byte Delegation Indicator above, which is **identical across all HTS token addresses**. + +> Direct EOA delegation to the HTS system contract (or any other system contract) from a regular account is forbidden, and those calls no-op. Only the network-owned token-proxy and schedule-proxy accounts are permitted to "delegate" to a system contract. + #### Additional References > npx hardhat run scripts/deploy.ts --network testnet Compiling your Solidity contracts... -Compiled 1 Solidity file with solc 0.8.28 (evm target: cancun) +Compiled 1 Solidity file with solc 0.8.30 (evm target: prague) Deploying contract with the account: 0xA98556A4deeB07f21f8a66093989078eF86faa30 Contract deployed at: 0x6035bA3BCa9595637B463Aa514c3a1cE3f67f3de diff --git a/evm/tools/hardhat/index.mdx b/evm/tools/hardhat/index.mdx index f39f7dd4..edb315cc 100644 --- a/evm/tools/hardhat/index.mdx +++ b/evm/tools/hardhat/index.mdx @@ -235,7 +235,7 @@ You can build the project using: npx hardhat build ``` -You can run all the tests in your project—both Solidity and TypeScript—using the `test` task: +You can run all the tests in your project (both Solidity and TypeScript) using the `test` task: ```bash npx hardhat test @@ -327,7 +327,7 @@ Now, let's go ahead and deploy the contract: ```bash ~/projects/tutorial-local-hardhat >> npx hardhat run scripts/deploy.ts Compiling your Solidity contracts... -Compiled 1 Solidity file with solc 0.8.28 (evm target: cancun) +Compiled 1 Solidity file with solc 0.8.30 (evm target: prague) Deploying contract with the account: 0x67D8d32E9Bf1a9968a5ff53B87d777Aa8EBBEe69 Contract deployed at: 0xB3e022eBC7D5C5B1f4ca50b3D4A55173b34ceD49 diff --git a/evm/tutorials/advanced/erc721-hardhat/part1-mint-burn.mdx b/evm/tutorials/advanced/erc721-hardhat/part1-mint-burn.mdx index 351754ed..657a805b 100644 --- a/evm/tutorials/advanced/erc721-hardhat/part1-mint-burn.mdx +++ b/evm/tutorials/advanced/erc721-hardhat/part1-mint-burn.mdx @@ -253,14 +253,14 @@ Deploy your contract by executing the script: npx hardhat run scripts/deploy.ts --network testnet ``` -Copy the deployed address—you'll need this in subsequent steps. +Copy the deployed address; you'll need this in subsequent steps. The output looks like this: ```bash ~/projects/hardhat-erc-721-mint-burn >> npx hardhat run scripts/deploy.ts --network testnet Compiling your Solidity contracts... -Compiled 1 Solidity file with solc 0.8.28 (evm target: cancun) +Compiled 1 Solidity file with solc 0.8.30 (evm target: prague) Deploying contract with the account: 0xA98556A4deeB07f21f8a66093989078eF86faa30 Contract deployed at: 0x6035bA3BCa9595637B463Aa514c3a1cE3f67f3de diff --git a/learn/core-concepts/accounts/account-creation.mdx b/learn/core-concepts/accounts/account-creation.mdx index e8bc7a88..907513a9 100644 --- a/learn/core-concepts/accounts/account-creation.mdx +++ b/learn/core-concepts/accounts/account-creation.mdx @@ -9,6 +9,12 @@ You will need access to an existing account with enough HBAR to cover the transa When an account is created, it is stored in the state on the Hedera network. The current state can be queried from the ledger and viewed in a [Network Explorer](/learn/networks/community-mirror-nodes). Each account has at least one public and private key pair. The private key(s) on the account is used to sign and authorize transactions that involve the account. To view the properties that can be set for an account, check out the "[Account Properties](/learn/core-concepts/accounts/account-properties)" section. + + **Recommended default for EVM compatibility:** Create accounts with an ECDSA key and set the **EVM Address from Public Key** at creation. This enables native compatibility with EVM wallets, JSON-RPC tooling, and smart-contract interactions. + + The EVM Address from Public Key is immutable and can only be set at creation. If keys are later rotated via `CryptoUpdateTransaction`, the address no longer matches the new public key. For recovery from compromised keys, create a new ECDSA account and migrate assets and state. See [Create an account](/native/accounts/create#setting-the-key-and-alias) for the SDK methods and full immutability/recovery guidance. + + An account can be created through any of the following methods. To create accounts using the SDKs, you will need access to an existing account to pay for the transaction fee to create a new account. diff --git a/learn/core-concepts/accounts/account-properties.mdx b/learn/core-concepts/accounts/account-properties.mdx index a8370914..67999f74 100644 --- a/learn/core-concepts/accounts/account-properties.mdx +++ b/learn/core-concepts/accounts/account-properties.mdx @@ -58,7 +58,9 @@ Each realm maintains a single counter for assigning entity numbers. This ensures Each Hedera account has a system-provided **account number** when the account is created. An account number is a non-negative number of 8 bytes. You can use the account number to specify the account in all Hedera transactions and query requests. Account numbers are unique and immutable. The account number for a newly created account is returned in the transaction receipt or transaction record for the transaction ID that created the account. The account number ID has the following format `..`. -
Account Number IDDescription
0.0.10The account number 10 in account number ID format.
+| Account Number ID | Description | +| --- | --- | +| `0.0.10` | The account number 10 in account number ID format. | #### Account Number Alias @@ -68,7 +70,9 @@ This account property is not stored in consensus node state. You will not see th The mirror node will calculate the account number alias from the account number. The account number alias is calculated and returned in account REST APIs only when the account does not have an existing account alias. For example, if the account was created through the [auto account creation](/learn/core-concepts/accounts/auto-account-creation) flow using an account alias the account number alias will not be populated. If the account was normally created then the account alias field will store the account number alias. -
Account IDAccount Number Alias Example
0.0.10The hex encoding value for 10 is "0a."

000000000000000000000000000000000000000a
+| Account ID | Account Number Alias Example | +| --- | --- | +| `0.0.10` | The hex encoding value for 10 is "0a."

`000000000000000000000000000000000000000a` | ### Account Alias @@ -170,6 +174,22 @@ Accounts on Hedera can submit `EthereumTransaction` types processed by the Ether Reference Hedera Improvement Proposal: [HIP-410](https://hips.hedera.com/hip/hip-410) +## Delegation Address + +Under the Pectra hard fork ([HIP-1340](https://hips.hedera.com/hip/hip-1340)), every account has an optional `delegation_address` field, a 20-byte EVM address. When set, any EVM call targeting the account executes the bytecode at that address in the account's storage context (similar to `DELEGATECALL`). When unset, calls behave as they always did (no-op for EOAs, regular execution for contracts). + +| Property | Value | +| -------------------------------- | ------------------------------------------------------------------------------------------------ | +| **Type** | 20-byte EVM address (or empty) | +| **Mutability** | Mutable. Update via `CryptoUpdate` (account key signs) or via a Type 4 EthereumTransaction (EIP-7702 authorization). | +| **Clearing** | Set to `0x0000000000000000000000000000000000000000` to clear the delegation. | +| **External representation** | Reported by `ContractGetBytecodeQuery` / `eth_getCode` as `0xef0100 ‖ delegation_address` (the EIP-7702 Delegation Indicator). | +| **Mirror Node field** | `delegation_address` on `/api/v1/accounts` and `/api/v1/accounts/{idOrAliasOrEvmAddress}`. | + +For the full feature description (configuration paths, execution semantics, HAS precedence rules, smart-account patterns), see [EOA Code Delegation](/evm/development/eoa-code-delegation). + +Reference Hedera Improvement Proposal: [HIP-1340](https://hips.hedera.com/hip/hip-1340) + ## Automatic Token Associations Hedera accounts must generally approve custom tokens before transferring them into the receiving account. The receiving account must sign the transaction that will associate the tokens, allowing the specified tokens to be deposited into their account. The automatic token association feature allows the account to bypass manually associating the custom token before transferring it into the account. @@ -180,7 +200,11 @@ Accounts can automatically approve up to 5,000 tokens without manually preauthor The property `maxAutoAssociations` defines how many tokens an account can automatically associate with. -
Property Value
0Automatic token associations or airdrops are not allowed; the account must manually associate each token.
-1Unlimited automatic token associations are allowed. this is the default for accounts created via auto account creation and for accounts that originated as hollow accounts (created from EVM aliases) and have since been completed. a value of -1 allows the account to receive new tokens without manually associating them
> 0the account can automatically associate up to that number of tokens. the sender covers the maxAutoAssociations fee and the first auto‑renewal rent for the association.
+| Property Value | | +| :---: | --- | +| `0` | Automatic token associations or airdrops are not allowed; the account must manually associate each token. | +| `-1` | Unlimited automatic token associations are allowed. this is the default for accounts created via **auto account creation** and for accounts that originated as hollow accounts (created from EVM aliases) and have since been completed. a value of `-1` allows the account to receive new tokens without manually associating them | +| `> 0` | the account can automatically associate up to that number of tokens. the sender covers the `maxAutoAssociations` fee and the first auto‑renewal rent for the association. | This feature is enabled on Hedera mainnet as part of frictionless airdrops (hip‑904). When tokens are sent to an account with available auto‑association slots, one slot is consumed and the account becomes associated automatically. @@ -211,7 +235,9 @@ Accounts can optionally have more than one key associated with them. These kinds /> -Warning: The private key(s) associated with the account is not to be shared with anyone as it will allow others to authorize transactions from your account on your behalf. Sharing your private key is like sharing your bank account password. Please make sure your private keys are stored in a secure wallet. + **Warning** + + The private key(s) associated with the account is not to be shared with anyone as it will allow others to authorize transactions from your account on your behalf. Sharing your private key is like sharing your bank account password. Please make sure your private keys are stored in a secure wallet. ## Receiver Signature Required @@ -223,7 +249,7 @@ Accounts can optionally require the account to sign any transactions depositing Staking in Hedera is taking an account and associating the HBAR balance to a node in the network. Custom fungible or non-fungible token balances an account holds do not contribute to staking on the network. The purpose of staking accounts to a node on the network is to strengthen the security of the network. To contribute to the security of the network, staked accounts can earn rewards in HBAR. Please see this [guide](/learn/core-concepts/staking) for additional information about the staking rewards program. Contracts can also stake their accounts to earn rewards. -An account can only stake to one node or one account at any given time. + An account can only stake to one node or one account at any given time. @@ -290,9 +316,9 @@ Reference Hedera Improvement Proposal: [HIP-406](https://hips.hedera.com/hip/hip ## Auto Renewals & **Expiration** - -Auto-renewals and expiration (rent) are currently not enabled. - + + Auto-renewals and expiration (rent) are currently not enabled. + Like the other Hedera entities, accounts take up network storage. To cover the cost of storing an account, a renewal fee will be charged for the storage utilized on the network. This feature is not enabled on the network today; however, in the future, when it is enabled, the account must have sufficient funds to pay for the renewal fees. diff --git a/native/accounts/create.mdx b/native/accounts/create.mdx index fce06b4d..2fd6cf58 100644 --- a/native/accounts/create.mdx +++ b/native/accounts/create.mdx @@ -41,8 +41,17 @@ For a complete list of account properties, see the [accounts overview](/native/a | `setDeclineStakingReward()` | boolean | Optional | | `setAccountMemo()` | String | Optional | | `setHighVolume()` | boolean | Optional | +| `setDelegationAddress()` | EvmAddress | Optional | | `setAutoRenewPeriod()` | Duration | Disabled | + +**`setDelegationAddress` ([HIP-1340](https://hips.hedera.com/hip/hip-1340))** + +Sets a 20-byte EVM `delegation_address` on the new account. When set, any EVM call to the account's address executes the bytecode at `delegationAddress` in the account's storage context (EOA Code Delegation per [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702)). The address must be exactly 20 bytes and can be provided as raw bytes, a hex string (with or without the `0x` prefix), or an `EvmAddress`; pass the raw EVM address, **not** the `0xef0100`-prefixed Delegation Indicator. Passing `0x0000000000000000000000000000000000000000` leaves the field unset. + +See [EOA Code Delegation](/evm/development/eoa-code-delegation) for the full feature description, including the HAS facade precedence rules and which account types can also configure delegation via Ethereum Type 4 transactions. + + ### EVM address from public key diff --git a/native/accounts/get-info.mdx b/native/accounts/get-info.mdx index f3a60890..89efd669 100644 --- a/native/accounts/get-info.mdx +++ b/native/accounts/get-info.mdx @@ -37,7 +37,31 @@ For obtaining account information and historical data, consider using the Mirror ### Methods -
MethodTypeRequirement
setAccountId(<accountId>)AccountIdRequired
<AccountInfo>.accountIdAccountIdOptional
<AccountInfo>.contractAccountIdStringOptional
<AccountInfo>.isDeletedbooleanOptional
<AccountInfo>.keyKeyOptional
<AccountInfo>.balanceHBAROptional
<AccountInfo>.isReceiverSignatureRequiredbooleanOptional
<AccountInfo>.ownedNftslongOptional
<AccountInfo>.maxAutomaticTokenAssociationsintOptional
<AccountInfo>.accountMemoStringOptional
<AccountInfo>.expirationTimeInstantOptional
<AccountInfo>.autoRenewPeriodDurationOptional
<AccountInfo>.ledgerIdLedgerIdOptional
<AccountInfo>.ethereumNoncelongOptional
<AccountInfo>.stakingInfoStakingInfoOptional
<AccountInfo>.tokenRelationshipsMap<TokenId, TokenRelationships>Optional
+| Method | Type | Requirement | +| --- | --- | --- | +| `setAccountId()` | AccountId | Required | +| `.accountId` | AccountId | Optional | +| `.contractAccountId` | String | Optional | +| `.isDeleted` | boolean | Optional | +| `.key` | Key | Optional | +| `.balance` | HBAR | Optional | +| `.isReceiverSignatureRequired` | boolean | Optional | +| `.ownedNfts` | long | Optional | +| `.maxAutomaticTokenAssociations` | int | Optional | +| `.accountMemo` | String | Optional | +| `.expirationTime` | Instant | Optional | +| `.autoRenewPeriod` | Duration | Optional | +| `.ledgerId` | LedgerId | Optional | +| `.ethereumNonce` | long | Optional | +| `.stakingInfo` | StakingInfo | Optional | +| `.tokenRelationships` | Map<TokenId, TokenRelationships> | Optional | +| `.delegationAddress` | EvmAddress | Optional | + + +**`delegationAddress` ([HIP-1340](https://hips.hedera.com/hip/hip-1340))** + +Returns the 20-byte EVM address (`EvmAddress`) the account is currently delegating execution to under EOA Code Delegation, or `null` if no delegation is configured. In JavaScript, read it as a property: `info.delegationAddress`. When set, EVM calls to the account's address execute the bytecode at this address in the account's storage context. See [EOA Code Delegation](/evm/development/eoa-code-delegation). + diff --git a/native/accounts/update.mdx b/native/accounts/update.mdx index 27a8925a..e951acc3 100644 --- a/native/accounts/update.mdx +++ b/native/accounts/update.mdx @@ -55,8 +55,49 @@ Reference: [HIP-904](https://hips.hedera.com/hip/hip-904) | `setStakedAccountId()` | AccountId | Optional | | `setStakedNodeId()` | long | Optional | | `setDeclineStakingReward()` | boolean | Optional | +| `setDelegationAddress()` | EvmAddress | Optional | | `setExpirationTime()` | Instant | Disabled | + +**`setDelegationAddress` ([HIP-1340](https://hips.hedera.com/hip/hip-1340))** + +Sets, changes, or clears the account's EOA Code Delegation. The address must be exactly 20 bytes and can be provided as raw bytes, a hex string (with or without the `0x` prefix), or an `EvmAddress`. Pass `0x0000000000000000000000000000000000000000` or `null` to clear an existing delegation. After update, any EVM call to the account's address executes the delegate's code in the account's storage context. + +For ECDSA accounts with a public-key-derived alias, you can alternatively configure delegation via an [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) Type 4 Ethereum transaction. ED25519 accounts and ECDSA accounts with a long-zero alias must use this HAPI path. See [EOA Code Delegation](/evm/development/eoa-code-delegation). + + +#### Example: set a delegation target + +```javascript JavaScript +import { AccountUpdateTransaction, AccountId } from "@hashgraph/sdk"; + +const tx = await new AccountUpdateTransaction() + .setAccountId(AccountId.fromString("0.0.4567")) + .setDelegationAddress("0x019b8ee526333d9cbbbc35fff0309794dfa73451") + .freezeWith(client) + .sign(accountKey); + +await (await tx.execute(client)).getReceipt(client); + +// Read it back via property access +console.log(`Delegation address: ${tx.delegationAddress?.toString()}`); +``` + +#### Example: clear an existing delegation + +```javascript JavaScript +import { AccountUpdateTransaction, AccountId } from "@hashgraph/sdk"; + +// Pass the zero address (or null) to clear +const tx = await new AccountUpdateTransaction() + .setAccountId(AccountId.fromString("0.0.4567")) + .setDelegationAddress("0x0000000000000000000000000000000000000000") + .freezeWith(client) + .sign(accountKey); + +await (await tx.execute(client)).getReceipt(client); +``` + ```java Java diff --git a/native/smart-contracts/ethereum-transaction.mdx b/native/smart-contracts/ethereum-transaction.mdx index 38836b80..2d79e143 100644 --- a/native/smart-contracts/ethereum-transaction.mdx +++ b/native/smart-contracts/ethereum-transaction.mdx @@ -1,11 +1,23 @@ --- title: "Ethereum transaction" +description: "Execute raw RLP-encoded EVM transactions on Hedera with `EthereumTransaction`, including call data via HFS file ID and max gas allowance settings." --- -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)](/evm/tutorials). +An `EthereumTransaction` lets you execute a raw, RLP-encoded EVM transaction (**type 0, 1, 2, or 4**) 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)](/evm/tutorials). - +## Supported transaction types + +| Type | Spec | Use it when… +| :---: | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `0` | Legacy ([EIP-155](https://eips.ethereum.org/EIPS/eip-155)) | You need maximum compatibility with older tooling. No `access_list`, no priority fee. | +| `1` | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) | You want to pre-warm storage slots / addresses via an [`access_list`](#access-lists-eip-2930) to reduce execution gas. | +| `2` | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) | The default for most modern wallets. Carries `max_fee_per_gas` + `max_priority_fee_per_gas` (priority fee is ignored; Hedera fees are network-determined). | +| `4` | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) (Pectra) | You're delegating EOA execution to a smart-contract implementation. Carries an `authorization_list`. See [EOA Code Delegation](/evm/development/eoa-code-delegation). | + | +Type 3 (blob transactions per [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844)) is **not supported** on Hedera. See [HIP-866](https://hips.hedera.com/hip/hip-866). For large `callData`, use [jumbo `EthereumTransaction` payloads](#handling-large-calldata-payloads) ([HIP-1086](https://hips.hedera.com/hip/hip-1086)) instead. + + #### **Important** Hedera interprets HBAR decimals differently depending on the context: @@ -17,7 +29,111 @@ Hedera interprets HBAR decimals differently depending on the context: Reference: [HIP-410](https://hips.hedera.com/hip/hip-410) -
FieldDescription
Ethereum DataAn 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 IDAn 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.

+| Field | Description | +| --- | --- | +| **Ethereum Data** | An RLP-encoded (type 0, 1, 2, or 4) 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*](https://hips.hedera.com/hip/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. | + +## Access Lists (EIP-2930) + +Type 1 and Type 2 transactions accept an optional `access_list`, a list of `{address, storageKeys[]}` tuples that the EVM "warms up" before execution. Slots and addresses on the list are charged at the warm rate (`100` gas) on first touch instead of the cold rate (`2,100` for storage, `2,600` for accounts). + +```plain wrap +access_list = [ + { address: "0x", storageKeys: ["0x", "0x", ...] }, + { address: "0x", storageKeys: [] }, + ... +] +``` + +**When access lists save gas:** + +- Cross-contract calls where the EVM doesn't already know about the target address. Listing it converts a 2,600-gas cold `CALL` into a 100-gas warm one. +- Reads of storage slots in another contract (a token balance lookup, a registry probe). Listing the slot converts a 2,100-gas cold `SLOAD` into a 100-gas warm one. + +**When they don't save gas:** + +- Slots in the contract that owns the transaction's `to` address are warm anyway (the contract's own storage is pre-warmed). +- Speculative listings of slots that never get read. You still pay the access-list overhead (`2,400` per address + `1,900` per slot) without recouping the cold-access discount. + +### Example: hand-built Type 1 transaction (ethers v6) + +```javascript wrap JavaScript +import { Wallet, JsonRpcProvider, Transaction } from "ethers"; + +const provider = new JsonRpcProvider("https://testnet.hashio.io/api"); +const wallet = new Wallet(process.env.OPERATOR_KEY, provider); + +const tx = new Transaction(); +tx.type = 1; // EIP-2930 +tx.chainId = 296n; // Hedera testnet +tx.to = "0x"; +tx.value = 0n; +tx.gasLimit = 200_000n; +tx.gasPrice = (await provider.getFeeData()).gasPrice; +tx.nonce = await provider.getTransactionCount(wallet.address); +tx.data = "0x"; +tx.accessList = [ + { + address: "0x", + storageKeys: [ + // balanceOf slot + "0x0000000000000000000000000000000000000000000000000000000000000003", + // allowance slot + "0x0000000000000000000000000000000000000000000000000000000000000004", + ], + }, +]; + +const signed = await wallet.signTransaction(tx); +const sent = await provider.broadcastTransaction(signed); +console.log("tx hash:", sent.hash); +``` + +The same payload can be submitted via `EthereumTransaction` directly by passing the raw signed RLP bytes as `ethereumData`. + +### Example: Type 2 with access list (viem) + +```javascript wrap JavaScript +import { createWalletClient, http, parseGwei } from "viem"; +import { privateKeyToAccount } from "viem/accounts"; +import { hederaTestnet } from "viem/chains"; + +const account = privateKeyToAccount(process.env.OPERATOR_KEY); +const client = createWalletClient({ chain: hederaTestnet, transport: http(), account }); + +const hash = await client.sendTransaction({ + type: "eip1559", + to: "0x", + data: "0x", + // example value; query eth_gasPrice for the live rate (Hedera's gas price is network-determined) + maxFeePerGas: parseGwei("710"), + // ignored on Hedera; fees are network-determined + maxPriorityFeePerGas: 0n, + accessList: [ + { + address: "0x", + storageKeys: [ + "0x0000000000000000000000000000000000000000000000000000000000000003", + ], + }, + ], +}); +``` + +> **Tip:** Most JSON-RPC providers expose `eth_createAccessList`; call it against a simulated transaction to get a near-optimal access list before signing. + +#### Hedera specifics + +A few things to know before you rely on access lists on Hedera: + +- **The warm/cold discount is honored.** Hedera applies the same EIP-2929/2930 gas accounting as Ethereum, so listed addresses and slots are charged at the warm rate on first touch. The exact cold/warm opcode costs are in the [gas schedule](/evm/development/gas-fees#evm-opcode-gas). +- **`access_list` also rides on Type 4 transactions.** The EIP-7702 payload carries both `access_list` and `authorization_list`, so you can pre-warm storage *and* set EOA code delegation in a single transaction. See [EOA Code Delegation](/evm/development/eoa-code-delegation). +- **Access-list bytes count toward the EIP-7623 calldata floor.** A large speculative access list increases `callData` size and can push a low-execution transaction into the [calldata floor](/evm/development/gas-fees#intrinsic-gas); list only slots you'll actually touch. +- **Submitting via the SDK.** Pass the raw signed RLP (Type 1 or Type 2) as `ethereumData` on an `EthereumTransaction`; Hedera preserves the access list during execution. No Hedera-native field mirrors `access_list`; it lives entirely inside the RLP payload. + +*** ## Handling Large callData Payloads @@ -37,7 +153,13 @@ This is added to base gas and execution gas. Developers must ensure both `gasLim #### **Quick reference: Jumbo vs Standard Transactions** -
FeatureJumbo Ethereum TransactionStandard Ethereum Transaction
callData Size Limit24KB (creation) / 128KB (call)~6KB total transaction size
callDataFileId Needed?Only if limits exceededAlways for large payloads
Gas CalculationAlways for large payloadsSame
Batch InclusionNot supportedSupported
Network ThrottlingDedicated throttle bucketStandard throttling
+| Feature | Jumbo Ethereum Transaction | Standard Ethereum Transaction | +| --- | --- | --- | +| **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*](https://hips.hedera.com/hip/hip-1086) *and the* [*Gas and Fees page*](/evm/development/gas-fees#gas-schedule-and-fee-calculation) *for complete technical details.* @@ -69,7 +191,7 @@ The total transaction cost includes: -```java Java +```java wrap Java //Create the transaction EthereumTransaction transaction = new EthereumTransaction() .setEthereumData(ethereumData) @@ -90,7 +212,7 @@ System.out.println("The transaction consensus status is " +transactionStatus); ``` -```javascript JavaScript +```javascript wrap JavaScript //Create the transaction const transaction = new EthereumTransaction() .setEthereumData(ethereumData) @@ -111,7 +233,7 @@ console.log("The transaction consensus status is " +transactionStatus); ``` -```go Go +```go wrap Go //Create the transaction transaction, err := hedera.NewEthereumTransaction(). SetEthereumData(ethereumData) diff --git a/reference/rest-api/accounts/index.mdx b/reference/rest-api/accounts/index.mdx index e4287a3c..42deefbf 100644 --- a/reference/rest-api/accounts/index.mdx +++ b/reference/rest-api/accounts/index.mdx @@ -32,3 +32,40 @@ Account IDs take the following format: **0.0.\**.‌ Example: 0.0.1000‌ Account IDs can also take the account number as an input value. For example, for account ID 0.0.1000, the number 1000 can be specified in the request. + +## EOA Code Delegation field (HIP-1340) + +Under the Pectra hard fork ([HIP-1340](https://hips.hedera.com/hip/hip-1340)), every account record returned by the Accounts API includes a new `delegation_address` field. The value is the 20-byte EVM address of the contract whose code executes when the account is called, or `0x` if no delegation is configured. + +This field appears in responses from both: + +- `GET /api/v1/accounts` +- `GET /api/v1/accounts/{idOrAliasOrEvmAddress}` + +### Example response (delegated account) + +```json +{ + "account": "0.0.7488058", + "alias": "LTKD3QWHBYS2FPYGSNYMRWCHBGCQNKWB", + "created_timestamp": "1766093540.161994001", + "decline_reward": false, + "delegation_address": "0x019b8ee526333d9cbbbc35fff0309794dfa73451", + "deleted": false +} +``` + +### Example response (no delegation) + +```json +{ + "account": "0.0.2", + "alias": null, + "created_timestamp": "1706812520.644859498", + "decline_reward": false, + "delegation_address": "0x", + "deleted": false +} +``` + +Externally, the corresponding EVM `eth_getCode(account)` returns either an empty value (`0x`) or a 23-byte EIP-7702 Delegation Indicator of the form `0xef0100 ‖ delegation_address`. See [EOA Code Delegation](/evm/development/eoa-code-delegation) for the full data model. diff --git a/reference/rest-api/contracts/index.mdx b/reference/rest-api/contracts/index.mdx index ae070534..4d9dbda7 100644 --- a/reference/rest-api/contracts/index.mdx +++ b/reference/rest-api/contracts/index.mdx @@ -25,3 +25,51 @@ The following endpoints are available for the Smart Contracts object: | `GET /api/v1/contracts/{id}/results/logs` | Fetches logs for a specific contract. | | `GET /api/v1/contracts/{id}/results/opcodes` | Get the opcode traces for historical transactions | | `POST /api/v1/contracts/call` | Invokes a smart contract method. | + +## Pectra updates (HIP-1340) + +Under the Pectra hard fork, all `/api/v1/contracts/*` endpoints accept **EOA addresses** in addition to contract IDs. When an EOA has [code delegation](/evm/development/eoa-code-delegation) configured, calls to its address execute the delegate contract's code in the EOA's storage context, so the EOA emits logs, holds storage slots, and produces traces that these endpoints surface. + +### New `authorization_list` field on contract results + +Contract-result endpoints include a new `authorization_list` field for Ethereum Type 4 ([EIP-7702](https://eips.ethereum.org/EIPS/eip-7702)) transactions: + +- `GET /api/v1/contracts/{contractIdOrAddress}/results/{timestamp}` +- `GET /api/v1/contracts/results/{transactionIdOrHash}` +- `GET /api/v1/contracts/results` + +#### Example response excerpt + +```json wrap +{ + "address": "0x4af07974dae3cb2daf46fb80e8544d45138ee54f", + "amount": 0, + "authorization_list": [ + { + "chain_id": "0x127", + "address": "0x1111111111111111111111111111111111111111", + "nonce": 5, + "y_parity": 1, + "r": "0x2222222222222222222222222222222222222222222222222222222222222222", + "s": "0x3333333333333333333333333333333333333333333333333333333333333333" + } + ], + "contract_id": "0.0.7488214" +} +``` + +For non-Type-4 transactions the field is either absent or returned as an empty array. The `chain_id` of an authorization entry is hex-encoded (e.g. `0x127` = 295 mainnet, `0x128` = 296 testnet, `0x129` = 297 previewnet, `0x12A` = 298 development networks). + +### Endpoints that now serve EOA addresses + +The following endpoints accept an EOA address (or its `0.0.x` account ID) without schema changes; they were previously contract-only: + +- `GET /api/v1/contracts/{contractIdOrAddress}/results` +- `GET /api/v1/contracts/{contractIdOrAddress}/results/logs` +- `GET /api/v1/contracts/{contractIdOrAddress}/state` +- `GET /api/v1/contracts/results/{transactionIdOrHash}/actions` +- `GET /api/v1/contracts/results/{transactionIdOrHash}/opcodes` +- `GET /api/v1/contracts/results/logs` +- `POST /api/v1/contracts/call` + +Reference: [HIP-1340](https://hips.hedera.com/hip/hip-1340), [HIP-1341](https://hips.hedera.com/hip/hip-1341) diff --git a/smart-contract-verification-api.yaml b/smart-contract-verification-api.yaml index 46f19879..32a59b59 100644 --- a/smart-contract-verification-api.yaml +++ b/smart-contract-verification-api.yaml @@ -113,7 +113,7 @@ paths: content: "\nnumber: public(uint256)\n\n@external\ndef __init__():\n self.number = 0\n\n@external\ndef setNumber(newNumber: uint256):\n self.number = newNumber\n\n@view\n@external\ndef getNumber() -> uint256:\n return self.number\n" settings: optimize: gas - evmVersion: cancun + evmVersion: prague compilerVersion: 0.3.10+commit.91361694 contractIdentifier: MyVyperContract.vy:MyVyperContract creationTransactionHash: '0xb6ee9d528b336942dd70d3b41e2811be10a473776352009fd73f85604f5ed206' @@ -125,7 +125,7 @@ paths: test.vy: content: "\na: public(uint256)\nb: public(uint256)\n\n@deploy\ndef __init__():\n self.a = 1\n self.b = 2\n" settings: - evmVersion: cancun + evmVersion: prague storage_layout_overrides: test.vy: a: