Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
130 changes: 97 additions & 33 deletions evm/development/deploying.mdx

Large diffs are not rendered by default.

455 changes: 455 additions & 0 deletions evm/development/eoa-code-delegation.mdx

Large diffs are not rendered by default.

596 changes: 362 additions & 234 deletions evm/development/gas-fees.mdx

Large diffs are not rendered by default.

47 changes: 44 additions & 3 deletions evm/development/json-rpc/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 ‖ <system-contract-address>` 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.
Expand All @@ -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 |
Expand All @@ -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 |

<Check>
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!
</Check>

## Community Hosted JSON-RPC Relays
Expand All @@ -34,7 +71,11 @@ Anyone in the community can set up their own JSON RPC relay that applications ca

#### JSON-RPC Relay Endpoints

<table><thead><tr><th>Network</th><th align="center">Chain ID</th><th align="center">Hashio RPC URL</th><th align="center">thirdweb RPC URL</th></tr></thead><tbody><tr><td><strong>Mainnet</strong></td><td align="center"><code>295</code></td><td align="center"><a href="https://mainnet.hashio.io/api">https://mainnet.hashio.io/api</a></td><td align="center"><a href="https://295.rpc.thirdweb.com">https://295.rpc.thirdweb.com</a></td></tr><tr><td><strong>Testnet</strong></td><td align="center"><code>296</code></td><td align="center"><a href="https://testnet.hashio.io/api">https://testnet.hashio.io/api</a></td><td align="center"><a href="https://296.rpc.thirdweb.com">https://296.rpc.thirdweb.com</a></td></tr><tr><td><strong>Previewnet</strong></td><td align="center"><code>297</code></td><td align="center"><a href="https://previewnet.hashio.io/api">https://previewnet.hashio.io/api</a>**</td><td align="center"><a href="https://297.rpc.thirdweb.com">https://297.rpc.thirdweb.com</a></td></tr></tbody></table>
| 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) |

<Check>
### 🚨 **PLEASE NOTE**
Expand Down
54 changes: 48 additions & 6 deletions evm/development/security.mdx

Large diffs are not rendered by default.

24 changes: 24 additions & 0 deletions evm/differences/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
37 changes: 35 additions & 2 deletions evm/hedera-services/system-contracts/account-service.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

<Info>
**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.
Expand Down Expand Up @@ -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`.

<table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>address</strong></td><td>A 20-byte identifier used to represent an account on the Hedera network or an EVM-compatible account.</td></tr><tr><td><strong>message</strong></td><td>The original plaintext data or payload that the signature is derived from. This is the information that was signed to produce the signature.</td></tr><tr><td><strong>messaHash</strong></td><td>A cryptographic hash of the <code>message</code>, calculated using an algorithm like SHA-256 or Keccak-256. This is typically what is signed instead of the raw message.</td></tr><tr><td><strong>signatureBlob</strong></td><td>A concatenation of the digital signature components, typically including <code>r</code>, <code>s</code>, and <code>v</code> values for ECDSA, or the equivalent data for ED25519 signatures.</td></tr></tbody></table>
| 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

Expand All @@ -57,3 +62,31 @@ Gas fee schedule and calculation
</Card>

**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)
Loading
Loading