From e5854e3196f13461730de316e711889ef2a69af7 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Fri, 21 Nov 2025 16:28:49 -0500 Subject: [PATCH 01/19] First draft of upgrade 6.0 info --- .../building-on-etherlink/endpoint-support.md | 2 +- docs/get-started/network-information.mdx | 8 ++++---- docs/network/fees.md | 2 +- docs/progress/upgrades.md | 20 +++++++++++++++++++ 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/building-on-etherlink/endpoint-support.md b/docs/building-on-etherlink/endpoint-support.md index 22bf88fc..ed5ba60e 100644 --- a/docs/building-on-etherlink/endpoint-support.md +++ b/docs/building-on-etherlink/endpoint-support.md @@ -480,7 +480,7 @@ For examples of using these ethers.js methods, see [Using ethers.js](/building-o EVM version - Prague + Osaka Whitelisting Fireblocks IP addresses diff --git a/docs/get-started/network-information.mdx b/docs/get-started/network-information.mdx index 0d899597..806c4600 100644 --- a/docs/get-started/network-information.mdx +++ b/docs/get-started/network-information.mdx @@ -37,7 +37,7 @@ or subscribe to a commercial [RPC provider](/tools/node-providers) plan which of EVM version - Prague + Osaka RPC Endpoint @@ -123,7 +123,7 @@ However, this test work will be decommissioned soon and the Etherlink Shadownet EVM version - Prague + Osaka RPC Endpoint @@ -203,7 +203,7 @@ This a new network that will become the primary test network for Etherlink, so u EVM version - Prague + Osaka RPC Endpoint @@ -269,7 +269,7 @@ This a new network that will become the primary test network for Etherlink, so u Feature | Details | --- | --- | Genesis date | 2nd May 2024 (Mainnet), 15th November 2023 (Ghostnet Testnet), 28th August 2025 (Shadownet Testnet) -EVM-compatible | Yes, up to version Prague +EVM-compatible | Yes, up to version Osaka Block speed | Variable; see [Architecture](/network/architecture) Docker image | https://hub.docker.com/r/tezos/tezos-bare images that start with `octez-evm-node` Debugging | Supported via standard [Ethereum endpoints](/building-on-etherlink/endpoint-support) diff --git a/docs/network/fees.md b/docs/network/fees.md index 6820b472..bcc21806 100644 --- a/docs/network/fees.md +++ b/docs/network/fees.md @@ -34,7 +34,7 @@ Etherlink measures throughput in terms of the amount of execution gas (that is, As demand increases and more execution gas is used in a shorter time, Etherlink increases the gas price to increase the execution fee. Etherlink has a target amount of execution gas to use per second, referred to as the _speed limit_ or _target_. -The speed limit is currently set to 7 million gas per second. +The speed limit is currently set to 13.5 million gas units per second, exactly half of Etherlink's capacity of 27 million gas units per second. To calculate the throughput, Etherlink records the total execution gas used and subtracts the speed limit every second. The remaining execution gas amount is known as the _backlog_. diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index a9f04b38..620f636a 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -89,6 +89,26 @@ For more information, see [Execution fee](/network/fees#execution-fee). For more information, see [Announcing Ebisu: A 5th Upgrade proposal for Etherlink Mainnet](https://medium.com/@etherlink/announcing-ebisu-a-5th-upgrade-proposal-for-etherlink-mainnet-4dfdd1c8819e). +## Etherlink 6.0 (Farfadet) + +The Etherlink 6.0 upgrade includes: + +- Support for EVM Osaka, including support for the count leading zeroes (CLZ) opcode (EIP-7939), the ecp256r1 Curve Support precompile (EIP-7951), and the increase in ModExp gas cost (EIP-7883) + +- Instant confirmations, which allow users to verify (within roughly 50ms) that their transactions will be in the next block. +Users can call the `eth_sendRawTransactionSync` endpoint that is available in the EVM node version 0.48 and later to submit a transaction and wait for an instant confirmation from the sequencer. + + +- The speed limit (also known as the target) is increased to 13.5 million gas units per second. +The speed limit decides when the gas price raises. +For more information, see [Execution fee](/network/fees#execution-fee). + +- A breaking change to the `QueuedDeposit` event that the FA bridge emits. +This event is now emitted by the FA bridging precompiled contract (`0xff0...0002`) and the first topic of the event is changed to match its ABI signature. +For more information about bridging events, see [How bridging FA tokens works](/bridging/bridging-fa-how). + +For more information, see [Announcing Farfadet: A 6th Upgrade Proposal for Etherlink Mainnet](https://medium.com/@etherlink/announcing-farfadet-a-6th-upgrade-proposal-for-etherlink-mainnet-6bc59793962d). + ## Changelog For full details about changes to Etherlink, see [Changelogs](/progress/changelogs). From 111fc2ce2a987a0842dca7c9b67b3fa8ad63bb1a Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 25 Nov 2025 09:45:46 -0500 Subject: [PATCH 02/19] First draft of instant confirmations --- docs/building-on-etherlink/transactions.md | 39 ++++++++++++++++++++++ docs/building-on-etherlink/websockets.md | 24 +++++++++++++ docs/progress/upgrades.md | 2 +- 3 files changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index 5ba3d4b2..eb0eb1a9 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -275,6 +275,45 @@ run(); ``` +## Getting instant confirmations + +Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports instant confirmations. +You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block, plus basic information about the completed transaction, such as its gas cost. + +Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter in the same way plus the optional `pending` value, as in this example: + +```bash +curl --request POST \ + --url https://node.shadownet.etherlink.com \ + --header 'accept: application/json' \ + --header 'content-type: application/json' \ + --data ' +{ + "id": 1, + "jsonrpc": "2.0", + "params": [ + "0x88a747dbc7f84e8416dc4be31ddef0", + "pending" + ], + "method": "eth_sendRawTransactionSync" +} +' +``` + +If you pass `latest` instead of `pending`, the sequencer waits until the transaction is in a block to send the confirmation. +Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` method, not on any other methods. + +The sequencer returns information about the transaction, such as its gas price and gas cost. +The `blockHash` field is always `0x000...` because the block has not been created yet. +You can take this response as a confirmation that the sequencer will put the transaction in the next block. + +The sequencer provides this confirmation as soon as it runs the transaction. +For even faster confirmations, you can use WebSockets to subscribe to the `tez_newIncludedTransactions` or `tez_newPreconfirmedReceipts` events. +These events provide confirmations of transactions that are ready and transactions that have been executed but not yet included in a block, respectively. +See [Getting updates with WebSockets](/building-on-etherlink/websockets). + + + ## Transferring ERC-20 tokens To transfer ERC-20 tokens, you can use the standard `transfer` entrypoint, as in this example: diff --git a/docs/building-on-etherlink/websockets.md b/docs/building-on-etherlink/websockets.md index efbccb2c..c729cbc4 100644 --- a/docs/building-on-etherlink/websockets.md +++ b/docs/building-on-etherlink/websockets.md @@ -109,6 +109,25 @@ newBlocksSubscription.on('data', blockhead => { }); ``` +This example listens for instant confirmations of upcoming transactions: + +```javascript +import Web3 from 'web3'; + +const web3Instance = new Web3(new Web3.providers.WebsocketProvider('ws://127.0.0.1:8545/ws')); + +// Subscribe to new instant confirmations +const newConfirmationsSubscription = await web3Instance.eth.subscribe('NewIncludedTransactions'); +newConfirmationsSubscription.on('error', error => { + console.log('Error when subscribing to new instant confirmations:', error); +}); + +newConfirmationsSubscription.on('data', data => { + // Print information about transactions in the next block + console.log(data); +}); +``` + This example subscribes to the event logs for an ERC-20 contract and logs information about each transfer event: ```javascript @@ -176,4 +195,9 @@ You can use WebSockets to subscribe to these Etherlink events: ::: +- `tez_newIncludedTransactions`: Provides confirmations for transactions that the sequencer intends to put in the next block before it has executed them. + +- `tez_newPreconfirmedReceipts`: Provides confirmations for transactions that the sequencer has executed and intends to put in the next block. +For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). + - `logs`: Returns the events emitted by smart contracts, including the address of the contract, the associated topics, and the data for the event diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index 620f636a..9bdb5dc7 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -97,7 +97,7 @@ The Etherlink 6.0 upgrade includes: - Instant confirmations, which allow users to verify (within roughly 50ms) that their transactions will be in the next block. Users can call the `eth_sendRawTransactionSync` endpoint that is available in the EVM node version 0.48 and later to submit a transaction and wait for an instant confirmation from the sequencer. - +For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). - The speed limit (also known as the target) is increased to 13.5 million gas units per second. The speed limit decides when the gas price raises. From 1f79dc492baf57da06b64b6039c500007e921e1c Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 25 Nov 2025 11:25:45 -0500 Subject: [PATCH 03/19] Precomiles no longer listed here --- docs/get-started/network-information.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/get-started/network-information.mdx b/docs/get-started/network-information.mdx index 806c4600..01ff7ec9 100644 --- a/docs/get-started/network-information.mdx +++ b/docs/get-started/network-information.mdx @@ -295,8 +295,6 @@ Therefore, you cannot compute Etherlink block hashes with tools such as Geth. ## Precompiled contracts -The precompiled contracts on Etherlink are listed in the [`mod.rs`](https://gitlab.com/tezos/tezos/-/blob/master/etherlink/kernel_latest/evm_execution/src/precompiles/mod.rs#L181) file. - These precompiled contracts are specific to Etherlink: From f542965a80682007965c64232a78392e7a2d374d Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 25 Nov 2025 11:29:21 -0500 Subject: [PATCH 04/19] WIP: new secp256r1 precompile --- docs/get-started/network-information.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/get-started/network-information.mdx b/docs/get-started/network-information.mdx index 01ff7ec9..472ea524 100644 --- a/docs/get-started/network-information.mdx +++ b/docs/get-started/network-information.mdx @@ -442,5 +442,11 @@ Etherlink also includes these [Ethereum precompiled contracts](https://www.evm.c + + + + + +
`secp256r1`
From 8f82033776fac438217b8868f50c301466177e98 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 25 Nov 2025 12:55:34 -0500 Subject: [PATCH 05/19] Address of secp256r1 precompile --- docs/get-started/network-information.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/get-started/network-information.mdx b/docs/get-started/network-information.mdx index 472ea524..a9d3ce3a 100644 --- a/docs/get-started/network-information.mdx +++ b/docs/get-started/network-information.mdx @@ -444,9 +444,9 @@ Etherlink also includes these [Ethereum precompiled contracts](https://www.evm.c `secp256r1` - - - + + + From a46dfe8b2d0fabdb24b6167dc00562df51c60e94 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:01:17 -0500 Subject: [PATCH 06/19] transaction receipt Co-authored-by: AurelienFT <32803821+AurelienFT@users.noreply.github.com> --- docs/building-on-etherlink/transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index eb0eb1a9..d07efb37 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -278,7 +278,7 @@ run(); ## Getting instant confirmations Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports instant confirmations. -You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block, plus basic information about the completed transaction, such as its gas cost. +You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block, plus his transaction receipt fully completed except block hash Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter in the same way plus the optional `pending` value, as in this example: From 1db76b949ab392fc1f3c08c92d89a755158995c3 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:09:44 -0500 Subject: [PATCH 07/19] Call them "receipts" --- docs/building-on-etherlink/transactions.md | 5 +++-- docs/progress/upgrades.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index d07efb37..0228ef63 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -278,7 +278,8 @@ run(); ## Getting instant confirmations Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports instant confirmations. -You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block, plus his transaction receipt fully completed except block hash +You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block. +This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status and gas used, but not information about the next block because it has not been created yet. Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter in the same way plus the optional `pending` value, as in this example: @@ -303,7 +304,7 @@ curl --request POST \ If you pass `latest` instead of `pending`, the sequencer waits until the transaction is in a block to send the confirmation. Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` method, not on any other methods. -The sequencer returns information about the transaction, such as its gas price and gas cost. +The sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. The `blockHash` field is always `0x000...` because the block has not been created yet. You can take this response as a confirmation that the sequencer will put the transaction in the next block. diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index 9bdb5dc7..ba4f1183 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -95,7 +95,7 @@ The Etherlink 6.0 upgrade includes: - Support for EVM Osaka, including support for the count leading zeroes (CLZ) opcode (EIP-7939), the ecp256r1 Curve Support precompile (EIP-7951), and the increase in ModExp gas cost (EIP-7883) -- Instant confirmations, which allow users to verify (within roughly 50ms) that their transactions will be in the next block. +- Instant confirmations, which allow users to verify (within roughly 50ms) that their transactions will be in the next block and provide receipts with information about the completed transaction. Users can call the `eth_sendRawTransactionSync` endpoint that is available in the EVM node version 0.48 and later to submit a transaction and wait for an instant confirmation from the sequencer. For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). From 45ba6a5142aea0d9466cfbca69c04c189c02c8ba Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:34:26 -0500 Subject: [PATCH 08/19] Clarify returned receipts --- docs/building-on-etherlink/transactions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index 0228ef63..731b5f0f 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -304,8 +304,9 @@ curl --request POST \ If you pass `latest` instead of `pending`, the sequencer waits until the transaction is in a block to send the confirmation. Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` method, not on any other methods. -The sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. -The `blockHash` field is always `0x000...` because the block has not been created yet. +When the sequencer executes the transaction and intends to put it in the next block, the sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. +This receipt matches the specification for the [`eth_getTransactionReceipt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) endpoint except that the `blockHash` field is always `0x000...` because the block has not been created yet. +The `blockNumber` field provides the correct level for the block that the transaction will be in. You can take this response as a confirmation that the sequencer will put the transaction in the next block. The sequencer provides this confirmation as soon as it runs the transaction. From c0b4daa17bd64e01644518378ee22bdbf9cc67a4 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:37:33 -0500 Subject: [PATCH 09/19] tez_newIncludedTransactions --- docs/building-on-etherlink/websockets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/websockets.md b/docs/building-on-etherlink/websockets.md index c729cbc4..122894f6 100644 --- a/docs/building-on-etherlink/websockets.md +++ b/docs/building-on-etherlink/websockets.md @@ -117,7 +117,7 @@ import Web3 from 'web3'; const web3Instance = new Web3(new Web3.providers.WebsocketProvider('ws://127.0.0.1:8545/ws')); // Subscribe to new instant confirmations -const newConfirmationsSubscription = await web3Instance.eth.subscribe('NewIncludedTransactions'); +const newConfirmationsSubscription = await web3Instance.eth.subscribe('tez_newIncludedTransactions'); newConfirmationsSubscription.on('error', error => { console.log('Error when subscribing to new instant confirmations:', error); }); From 3f99d27f2de21d95d2261baa78021ce0a45d762a Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:39:31 -0500 Subject: [PATCH 10/19] blockNumber field is not important enough --- docs/building-on-etherlink/transactions.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index 731b5f0f..c7fcd1ee 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -306,7 +306,6 @@ Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` When the sequencer executes the transaction and intends to put it in the next block, the sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. This receipt matches the specification for the [`eth_getTransactionReceipt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) endpoint except that the `blockHash` field is always `0x000...` because the block has not been created yet. -The `blockNumber` field provides the correct level for the block that the transaction will be in. You can take this response as a confirmation that the sequencer will put the transaction in the next block. The sequencer provides this confirmation as soon as it runs the transaction. From d91bf42d11e566733b6cc09e67a3aa58bab8a3f3 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:40:46 -0500 Subject: [PATCH 11/19] Simplify "in the same way" --- docs/building-on-etherlink/transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index c7fcd1ee..a31d85d5 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -281,7 +281,7 @@ Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports ins You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block. This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status and gas used, but not information about the next block because it has not been created yet. -Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter in the same way plus the optional `pending` value, as in this example: +Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter plus the optional `pending` value, as in this example: ```bash curl --request POST \ From 1ab9af7a667eacfc46099cfa6b0ef675cf207acc Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Wed, 26 Nov 2025 09:41:39 -0500 Subject: [PATCH 12/19] Allow users to know --- docs/progress/upgrades.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index ba4f1183..47a62382 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -95,7 +95,7 @@ The Etherlink 6.0 upgrade includes: - Support for EVM Osaka, including support for the count leading zeroes (CLZ) opcode (EIP-7939), the ecp256r1 Curve Support precompile (EIP-7951), and the increase in ModExp gas cost (EIP-7883) -- Instant confirmations, which allow users to verify (within roughly 50ms) that their transactions will be in the next block and provide receipts with information about the completed transaction. +- Instant confirmations, which allow users to know (within roughly 50ms) that their transactions will be in the next block and receive receipts with information about the completed transaction. Users can call the `eth_sendRawTransactionSync` endpoint that is available in the EVM node version 0.48 and later to submit a transaction and wait for an instant confirmation from the sequencer. For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). From 139da2f133c4ef19ccd1e6d8eb23dfef97cc0c3c Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 1 Dec 2025 08:26:43 -0500 Subject: [PATCH 13/19] same way as with Co-authored-by: NicNomadic <148877430+NicNomadic@users.noreply.github.com> --- docs/building-on-etherlink/transactions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index a31d85d5..fa75b487 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -281,7 +281,7 @@ Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports ins You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block. This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status and gas used, but not information about the next block because it has not been created yet. -Sending the transaction with the `eth_sendRawTransactionSync` method is the same as the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter plus the optional `pending` value, as in this example: +Sending the transaction with the `eth_sendRawTransactionSync` method is done the same way as with the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter plus the optional `pending` value, as in this example: ```bash curl --request POST \ From fbf941fedae7884dd70770a70a2e7ec751cb8b67 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 1 Dec 2025 09:25:51 -0500 Subject: [PATCH 14/19] Example confirmation receipt --- docs/building-on-etherlink/transactions.md | 45 +++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index fa75b487..28758004 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -308,12 +308,55 @@ When the sequencer executes the transaction and intends to put it in the next bl This receipt matches the specification for the [`eth_getTransactionReceipt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) endpoint except that the `blockHash` field is always `0x000...` because the block has not been created yet. You can take this response as a confirmation that the sequencer will put the transaction in the next block. +The following JSON code is an example response from the `eth_sendRawTransactionSync` for an ERC-20 token transfer: + +```json +{ + "jsonrpc": "2.0", + "result": { + "transactionHash": "0xa428415e77f1b5328023e1980ebd7474fc215acb0ec803b56f991866921ec6eb", + "transactionIndex": "0x1", + "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "blockNumber": "0x2c5349", + "from": "0x45ff91b4bf16ac9907cf4a11436f9ce61be0650d", + "to": "0x03ff3337af6d6ed88c72df7bef31162edddb51ba", + "cumulativeGasUsed": "0xb5e6", + "effectiveGasPrice": "0x3b9aca00", + "gasUsed": "0xb5e6", + "logs": [ + { + "address": "0x03ff3337af6d6ed88c72df7bef31162edddb51ba", + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x00000000000000000000000045ff91b4bf16ac9907cf4a11436f9ce61be0650d", + "0x00000000000000000000000046899d4fa5ba90e3ef3b7ae8aae053c662c1ca1d" + ], + "data": "0x0000000000000000000000000000000000000000000000000000000000000001", + "blockNumber": "0x2c5349", + "transactionHash": "0xa428415e77f1b5328023e1980ebd7474fc215acb0ec803b56f991866921ec6eb", + "transactionIndex": "0x1", + "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "logIndex": "0x1", + "removed": false + } + ], + "logsBloom": "0x00000000000000000020000000000000000000000000100000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000010000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000082000000000000000000000000000000000000002000000200000000008000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000", + "type": "0x2", + "status": "0x1", + "contractAddress": null + }, + "id": 1 +} +``` + +:::note + The sequencer provides this confirmation as soon as it runs the transaction. For even faster confirmations, you can use WebSockets to subscribe to the `tez_newIncludedTransactions` or `tez_newPreconfirmedReceipts` events. These events provide confirmations of transactions that are ready and transactions that have been executed but not yet included in a block, respectively. See [Getting updates with WebSockets](/building-on-etherlink/websockets). - +::: ## Transferring ERC-20 tokens From e7c3df4a6af666276302fefc9400166944b5b441 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 1 Dec 2025 09:46:23 -0500 Subject: [PATCH 15/19] Clarify what is in the receipt --- docs/building-on-etherlink/transactions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index 28758004..dd5bfaa4 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -279,7 +279,8 @@ run(); Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports instant confirmations. You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block. -This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status and gas used, but not information about the next block because it has not been created yet. +This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status, hash, gas used, and index of the transaction in the next block. +The only information missing from the receipt is the hash of the next block, because it has not been created yet. Sending the transaction with the `eth_sendRawTransactionSync` method is done the same way as with the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter plus the optional `pending` value, as in this example: From 45c87b9b526bc79a6d907ddd38d42129f72577b2 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 1 Dec 2025 09:47:14 -0500 Subject: [PATCH 16/19] Clarify when the sequencer provides the receipt --- docs/building-on-etherlink/transactions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index dd5bfaa4..1f6f1049 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -308,6 +308,7 @@ Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` When the sequencer executes the transaction and intends to put it in the next block, the sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. This receipt matches the specification for the [`eth_getTransactionReceipt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) endpoint except that the `blockHash` field is always `0x000...` because the block has not been created yet. You can take this response as a confirmation that the sequencer will put the transaction in the next block. +If the sequencer does not intend to put the transaction in the next block (such as if the block is nearly complete or the transaction volume is high), it waits to provide the receipt until the transaction will be in the next block. The following JSON code is an example response from the `eth_sendRawTransactionSync` for an ERC-20 token transfer: @@ -354,7 +355,7 @@ The following JSON code is an example response from the `eth_sendRawTransactionS The sequencer provides this confirmation as soon as it runs the transaction. For even faster confirmations, you can use WebSockets to subscribe to the `tez_newIncludedTransactions` or `tez_newPreconfirmedReceipts` events. -These events provide confirmations of transactions that are ready and transactions that have been executed but not yet included in a block, respectively. +These events provide confirmations of transactions that are ready to be executed and transactions that have been executed but not yet included in a block, respectively. See [Getting updates with WebSockets](/building-on-etherlink/websockets). ::: From c15675f28af84bc5f362726250a506022c67d64f Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 1 Dec 2025 10:22:00 -0500 Subject: [PATCH 17/19] Add info about instant confirmations to finality info --- docs/network/architecture.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/network/architecture.md b/docs/network/architecture.md index dae7a68a..dbbe5f82 100644 --- a/docs/network/architecture.md +++ b/docs/network/architecture.md @@ -143,7 +143,11 @@ Therefore, an Etherlink transaction is truly finalized two weeks after the block At this point, it is permanently part of the state of the Etherlink Smart Rollup and of Tezos. However, Etherlink is set up so users can be confident that transactions are irreversible much sooner than that. -Most users can assume that a transaction is irreversible and will be finalized after one of two milestones: +Most users can assume that a transaction is irreversible and will be finalized after one of these milestones: + +- **Transactions are executed on the Etherlink sequencer within 50ms.** +As described in [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations), the sequencer issues instant confirmations as soon as a transaction is executed and will be in the next block. +Users who trust the sequencer and these confirmations can take them as proof that the transaction will be in the next block. - **Transactions are confirmed on Etherlink within 500ms.** As described in [Sequencer](#sequencer), the sequencer puts transactions in blocks and distributes them to the EVM nodes. From 2459a8753ee06bed4a9c513af2d03318f3f4e9ba Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Tue, 2 Dec 2025 11:22:56 -0500 Subject: [PATCH 18/19] Instant confirmations not available at kernel update time --- docs/building-on-etherlink/transactions.md | 85 ---------------------- docs/building-on-etherlink/websockets.md | 24 ------ docs/network/architecture.md | 6 +- docs/progress/upgrades.md | 5 +- 4 files changed, 3 insertions(+), 117 deletions(-) diff --git a/docs/building-on-etherlink/transactions.md b/docs/building-on-etherlink/transactions.md index 1f6f1049..5ba3d4b2 100644 --- a/docs/building-on-etherlink/transactions.md +++ b/docs/building-on-etherlink/transactions.md @@ -275,91 +275,6 @@ run(); ``` -## Getting instant confirmations - -Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports instant confirmations. -You can send a transaction with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the sequencer that it intends to put the transaction in the next block. -This confirmation includes a transaction receipt that provides information about the completed transaction, such as the status, hash, gas used, and index of the transaction in the next block. -The only information missing from the receipt is the hash of the next block, because it has not been created yet. - -Sending the transaction with the `eth_sendRawTransactionSync` method is done the same way as with the `eth_sendRawTransaction` method: you sign the transaction and include it in the `data` parameter plus the optional `pending` value, as in this example: - -```bash -curl --request POST \ - --url https://node.shadownet.etherlink.com \ - --header 'accept: application/json' \ - --header 'content-type: application/json' \ - --data ' -{ - "id": 1, - "jsonrpc": "2.0", - "params": [ - "0x88a747dbc7f84e8416dc4be31ddef0", - "pending" - ], - "method": "eth_sendRawTransactionSync" -} -' -``` - -If you pass `latest` instead of `pending`, the sequencer waits until the transaction is in a block to send the confirmation. -Etherlink supports this `pending` value only on the `eth_sendRawTransactionSync` method, not on any other methods. - -When the sequencer executes the transaction and intends to put it in the next block, the sequencer returns a receipt for the transaction that includes information such as its gas price and gas cost. -This receipt matches the specification for the [`eth_getTransactionReceipt`](https://ethereum.org/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) endpoint except that the `blockHash` field is always `0x000...` because the block has not been created yet. -You can take this response as a confirmation that the sequencer will put the transaction in the next block. -If the sequencer does not intend to put the transaction in the next block (such as if the block is nearly complete or the transaction volume is high), it waits to provide the receipt until the transaction will be in the next block. - -The following JSON code is an example response from the `eth_sendRawTransactionSync` for an ERC-20 token transfer: - -```json -{ - "jsonrpc": "2.0", - "result": { - "transactionHash": "0xa428415e77f1b5328023e1980ebd7474fc215acb0ec803b56f991866921ec6eb", - "transactionIndex": "0x1", - "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "blockNumber": "0x2c5349", - "from": "0x45ff91b4bf16ac9907cf4a11436f9ce61be0650d", - "to": "0x03ff3337af6d6ed88c72df7bef31162edddb51ba", - "cumulativeGasUsed": "0xb5e6", - "effectiveGasPrice": "0x3b9aca00", - "gasUsed": "0xb5e6", - "logs": [ - { - "address": "0x03ff3337af6d6ed88c72df7bef31162edddb51ba", - "topics": [ - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", - "0x00000000000000000000000045ff91b4bf16ac9907cf4a11436f9ce61be0650d", - "0x00000000000000000000000046899d4fa5ba90e3ef3b7ae8aae053c662c1ca1d" - ], - "data": "0x0000000000000000000000000000000000000000000000000000000000000001", - "blockNumber": "0x2c5349", - "transactionHash": "0xa428415e77f1b5328023e1980ebd7474fc215acb0ec803b56f991866921ec6eb", - "transactionIndex": "0x1", - "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", - "logIndex": "0x1", - "removed": false - } - ], - "logsBloom": "0x00000000000000000020000000000000000000000000100000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000010000008000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000082000000000000000000000000000000000000002000000200000000008000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000", - "type": "0x2", - "status": "0x1", - "contractAddress": null - }, - "id": 1 -} -``` - -:::note - -The sequencer provides this confirmation as soon as it runs the transaction. -For even faster confirmations, you can use WebSockets to subscribe to the `tez_newIncludedTransactions` or `tez_newPreconfirmedReceipts` events. -These events provide confirmations of transactions that are ready to be executed and transactions that have been executed but not yet included in a block, respectively. -See [Getting updates with WebSockets](/building-on-etherlink/websockets). - -::: - ## Transferring ERC-20 tokens To transfer ERC-20 tokens, you can use the standard `transfer` entrypoint, as in this example: diff --git a/docs/building-on-etherlink/websockets.md b/docs/building-on-etherlink/websockets.md index 122894f6..efbccb2c 100644 --- a/docs/building-on-etherlink/websockets.md +++ b/docs/building-on-etherlink/websockets.md @@ -109,25 +109,6 @@ newBlocksSubscription.on('data', blockhead => { }); ``` -This example listens for instant confirmations of upcoming transactions: - -```javascript -import Web3 from 'web3'; - -const web3Instance = new Web3(new Web3.providers.WebsocketProvider('ws://127.0.0.1:8545/ws')); - -// Subscribe to new instant confirmations -const newConfirmationsSubscription = await web3Instance.eth.subscribe('tez_newIncludedTransactions'); -newConfirmationsSubscription.on('error', error => { - console.log('Error when subscribing to new instant confirmations:', error); -}); - -newConfirmationsSubscription.on('data', data => { - // Print information about transactions in the next block - console.log(data); -}); -``` - This example subscribes to the event logs for an ERC-20 contract and logs information about each transfer event: ```javascript @@ -195,9 +176,4 @@ You can use WebSockets to subscribe to these Etherlink events: ::: -- `tez_newIncludedTransactions`: Provides confirmations for transactions that the sequencer intends to put in the next block before it has executed them. - -- `tez_newPreconfirmedReceipts`: Provides confirmations for transactions that the sequencer has executed and intends to put in the next block. -For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). - - `logs`: Returns the events emitted by smart contracts, including the address of the contract, the associated topics, and the data for the event diff --git a/docs/network/architecture.md b/docs/network/architecture.md index dbbe5f82..dae7a68a 100644 --- a/docs/network/architecture.md +++ b/docs/network/architecture.md @@ -143,11 +143,7 @@ Therefore, an Etherlink transaction is truly finalized two weeks after the block At this point, it is permanently part of the state of the Etherlink Smart Rollup and of Tezos. However, Etherlink is set up so users can be confident that transactions are irreversible much sooner than that. -Most users can assume that a transaction is irreversible and will be finalized after one of these milestones: - -- **Transactions are executed on the Etherlink sequencer within 50ms.** -As described in [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations), the sequencer issues instant confirmations as soon as a transaction is executed and will be in the next block. -Users who trust the sequencer and these confirmations can take them as proof that the transaction will be in the next block. +Most users can assume that a transaction is irreversible and will be finalized after one of two milestones: - **Transactions are confirmed on Etherlink within 500ms.** As described in [Sequencer](#sequencer), the sequencer puts transactions in blocks and distributes them to the EVM nodes. diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index 47a62382..7051f157 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -95,9 +95,8 @@ The Etherlink 6.0 upgrade includes: - Support for EVM Osaka, including support for the count leading zeroes (CLZ) opcode (EIP-7939), the ecp256r1 Curve Support precompile (EIP-7951), and the increase in ModExp gas cost (EIP-7883) -- Instant confirmations, which allow users to know (within roughly 50ms) that their transactions will be in the next block and receive receipts with information about the completed transaction. -Users can call the `eth_sendRawTransactionSync` endpoint that is available in the EVM node version 0.48 and later to submit a transaction and wait for an instant confirmation from the sequencer. -For more information, see [Getting instant confirmations](/building-on-etherlink/transactions#getting-instant-confirmations). +- The ability to provide instant confirmations, which allow users to know (within roughly 50ms) that their transactions will be in the next block and receive receipts with information about the completed transaction. +This update puts the functionality for instant confirmations in the kernel, but they are not available to users until the EVM node enables the functionality. - The speed limit (also known as the target) is increased to 13.5 million gas units per second. The speed limit decides when the gas price raises. From 78f9c66be87b503f130e921e1503e5c08b6b7d98 Mon Sep 17 00:00:00 2001 From: Tim McMackin Date: Mon, 15 Dec 2025 12:22:07 -0500 Subject: [PATCH 19/19] 6.0 requires EVM node 0.48 --- docs/network/evm-nodes.mdx | 9 ++------- docs/progress/upgrades.md | 6 ++++++ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/network/evm-nodes.mdx b/docs/network/evm-nodes.mdx index e389eb36..ea5f4016 100644 --- a/docs/network/evm-nodes.mdx +++ b/docs/network/evm-nodes.mdx @@ -32,8 +32,7 @@ If you don't want to see all of the options and settings for the EVM node, you c 1. Download the latest release of the `octez-evm-node` binary from https://gitlab.com/tezos/tezos/-/releases. :::note - As of August 1st 2025, Etherlink Mainnet and Ghostnet Testnet require at least version 0.35 of the `octez-evm-node` binary. - Etherlink Shadownet Testnet requires at least version 0.44 of the `octez-evm-node` binary. + As of version 6.0, Etherlink requires at least version 0.48 of the `octez-evm-node` binary. ::: 1. Run the `octez-evm-node run observer` command to start the node as an observer: @@ -71,7 +70,7 @@ If you don't want to see all of the options and settings for the EVM node, you c - With version 0.44 of the EVM node or later, use this command for Etherlink Shadownet Testnet: + Use this command for Etherlink Shadownet Testnet: ```bash octez-evm-node run observer \ @@ -110,10 +109,6 @@ To switch modes, see [Switching history modes](#switching-history-modes). The easiest way to get the `octez-evm-node` binary is to download the binaries distributed as part of its latest release from https://gitlab.com/tezos/tezos/-/releases. The release page provides static binaries for Linux systems (for amd64 and arm64 architectures). -:::note -As of August 1st 2025, Etherlink Mainnet and Etherlink Ghostnet or Shadownet Testnet require at least version 0.35 of the `octez-evm-node` binary. -::: - As an alternative, you can use the minimal Docker image [tezos/tezos-bare](https://hub.docker.com/r/tezos/tezos-bare/tags?name=octez-evm-node) with a tag that includes `octez-evm-node`. These images contain the correct version of the binary. Docker examples below use `tezos/tezos-bare:octez-evm-node-latest` which will always be the most recent release. diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index 7051f157..348f5c35 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -91,6 +91,12 @@ For more information, see [Announcing Ebisu: A 5th Upgrade proposal for Etherlin ## Etherlink 6.0 (Farfadet) +:::note + +Etherlink 6.0 requires version 0.48 or later of the `octez-evm-node` binary. + +::: + The Etherlink 6.0 upgrade includes: - Support for EVM Osaka, including support for the count leading zeroes (CLZ) opcode (EIP-7939), the ecp256r1 Curve Support precompile (EIP-7951), and the increase in ModExp gas cost (EIP-7883)