How to use instant confirmations

docs/building-on-etherlink/transactions.md

@@ -279,6 +279,102 @@ run();
 
 ```
 
+## Getting Instant Confirmations
+
+:::note
+
+Instant Confirmations are an experimental feature.
+
+:::
+
+Beginning with EVM node 0.48 and the version 6.0 upgrade, Etherlink supports Instant Confirmations.
+You can send a transaction to a node with the `eth_sendRawTransactionSync` method and receive an instant confirmation from the node that the sequencer intends to put the transaction in the next block.
+This confirmation includes a transaction receipt that provides information about the 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.
+
+:::note
+
+To receive Instant Confirmations with the lowest possible latency, use an Etherlink EVM node as close as possible to the sequencer, which is deployed to a data center in Tokyo, Japan.
+
+:::
+
+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 node 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 enqueues the transaction for the next block, it notifies the nodes of the transaction and the nodes return 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), the nodes wait 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
+
+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 [Subscribing to Instant Confirmations](/building-on-etherlink/websockets#subscribing-to-instant-confirmations).
+
+:::
+
 ## Transferring ERC-20 tokens
 
 To transfer ERC-20 tokens, you can use the standard `transfer` entrypoint, as in this example:

docs/building-on-etherlink/websockets.md

@@ -164,6 +164,136 @@ console.log("Listening for Transfer events...");
 
 See the documentation for your WebSocket client library for how to manage the connection, receive messages, and close the connection.
 
+## Subscribing to Instant Confirmations
+
+:::note
+
+Instant Confirmations are an experimental feature.
+
+:::
+
+You can subscribe to WebSockets to receive Instant Confirmations, which are notices that a transaction will appear in the next block.
+Using WebSockets for Instant Confirmations requires at least version 0.49 of the `octez-evm-node` binary.
+
+:::note
+
+The Ethers.js and Web3.js libraries do not support custom WebSocket events and therefore you cannot use them to subscribe to instant confirmation events.
+For JavaScript/TypeScript, use the built-in Node.JS WebSocket library as in the example below.
+
+:::
+
+Etherlink nodes provide two custom WebSocket events that you can subscribe to for notice of upcoming transactions:
+
+- `tez_newIncludedTransactions`: Provides confirmations for transactions that the sequencer intends to put in the next block **before they have been executed**.
+Returns a transaction object.
+
+- `tez_newPreconfirmedReceipts`: Provides confirmations for transactions that **have been executed** and will be in the next block.
+Returns a transaction receipt.
+
+For example, this JavaScript code subscribes to these events and prints information about them to the log:
+
+```javascript
+// Create a WebSocket connection to a local EVM node
+const socket = new WebSocket('ws://127.0.0.1:8545/ws');
+
+// When the connection is established, subscribe to events
+socket.addEventListener('open', _event => {
+  console.log('WebSocket connection established!');
+  const includedTxPayload = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "eth_subscribe",
+    params: ["tez_newIncludedTransactions"],
+  };
+  socket.send(JSON.stringify(includedTxPayload));
+  const preconfirmedTxPayload = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "eth_subscribe",
+    params: ["tez_newPreconfirmedReceipts"],
+  };
+  socket.send(JSON.stringify(preconfirmedTxPayload));
+});
+
+// Log when a message is received from the server.
+socket.addEventListener('message', event => {
+  console.log('Message from server: ', event.data);
+});
+
+// Executes when the connection is closed, providing the close code and reason.
+socket.addEventListener('close', event => {
+  console.log('WebSocket connection closed:', event.code, event.reason);
+});
+
+// Executes if an error occurs during the WebSocket communication.
+socket.addEventListener('error', error => {
+  console.error('WebSocket error:', error);
+});
+```
+
+The response to the `tez_newIncludedTransactions` event (a transaction object) includes basic information about the transaction including its hash but not the gas used (because the transaction has not been executed yet), as in this example:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "result": {
+      "type": "0x2",
+      "chainId": "0x1f308",
+      "hash": "0xfbb0025e811b8bf37034e508da4740c68164c33947089b1c22119be55258a3e1",
+      "nonce": "0x7",
+      "blockHash": null,
+      "blockNumber": null,
+      "transactionIndex": null,
+      "from": "0x45ff91b4bf16ac9907cf4a11436f9ce61be0650d",
+      "to": "0x46899d4fa5ba90e3ef3b7ae8aae053c662c1ca1d",
+      "value": "0x16345785d8a0000",
+      "gas": "0x98496",
+      "maxFeePerGas": "0x3b9aca00",
+      "maxPriorityFeePerGas": "0x0",
+      "gasPrice": "0x3b9aca00",
+      "accessList": [],
+      "input": "0x",
+      "v": "0x1",
+      "r": "0xe4d96c84fbf0ea73fb39ba5551acce44a41ba03b4502da1d93f1e4a02ce51a3e",
+      "s": "0x6bc2aaa1580b58213e6e6586ae7b38351c2304df370853c74812ae09f5e74275"
+    },
+    "subscription": "0x40f582349eeac9b85b9ba3d936de0ebb"
+  }
+}
+```
+
+The response to the `tez_newPreconfirmedReceipts` event (a transaction receipt) is similar but also includes the number of the block and the gas used, as in this example:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "eth_subscription",
+  "params": {
+    "result": {
+      "transactionHash": "0x2096d81abf605780b56c0db5f415e0bff29c82fbd73912348106ac8c61a808cc",
+      "transactionIndex": "0x1",
+      "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+      "blockNumber": "0x2e4da9",
+      "from": "0x45ff91b4bf16ac9907cf4a11436f9ce61be0650d",
+      "to": "0x46899d4fa5ba90e3ef3b7ae8aae053c662c1ca1d",
+      "cumulativeGasUsed": "0x5208",
+      "effectiveGasPrice": "0x3b9aca00",
+      "gasUsed": "0x5208",
+      "logs": [],
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "type": "0x2",
+      "status": "0x1",
+      "contractAddress": null
+    },
+    "subscription": "0x221fe712815043cf05255c8b568557c5"
+  }
+}
+```
+
+For more information about Instant Confirmations, see [Getting Instant Confirmations](/building-on-etherlink/transactions#getting-instant-confirmations)
+
 ## WebSocket subscriptions
 
 You can use WebSockets to subscribe to these Etherlink events:
@@ -179,4 +309,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 have been executed and will be 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

docs/network/architecture.md

@@ -86,7 +86,8 @@ The lifecycle of a typical operation under normal circumstances is as follows:
 1. The EVM node forwards the transaction to the sequencer when it is valid.
 If users submit multiple transactions that depend on each other (that is, they have nonces that are not yet valid), the EVM node stores them until they are valid.
 1. The sequencer puts the transaction in its pool.
-1. The sequencer puts the transaction into a block as soon as possible (less than 500ms after receiving it in a nominal scenario).
+1. The sequencer enqueues the transaction and sends an instant confirmation to the nodes that the transaction will be in the next block.
+1. The sequencer puts the enqueued transactions into a block as soon as possible (less than 500ms after receiving it in a nominal scenario).
 1. The sequencer publishes the block to the EVM nodes, which update their states based on the transactions in the block.
 1. The sequencer publishes the block to the Smart Rollup inbox on layer 1 via a Smart Rollup node running in operator or batcher mode.
 1. The Smart Rollup nodes tracking the state of Etherlink fetch the block from the Smart Rollup inbox, read its transactions, and update their states.
@@ -135,15 +136,21 @@ To submit a transaction to the delayed inbox, see [Sending transactions to the d
 
 Transactions are considered finalized when you can trust that they cannot be reversed.
 
-The source of truth of what Etherlink transactions are final is the state of the rollup, which Etherlink Smart Rollup nodes store and keep up to date.
+The source of truth of what Etherlink transactions are final is the state of the Smart Rollup, which Etherlink Smart Rollup nodes store and keep up to date.
 They catch any misbehavior by the sequencer or other actors, accept only valid transactions, and challenge questionable behavior.
 As described in [Refutation periods](https://docs.tezos.com/architecture/smart-rollups#refutation-periods) on docs.tezos.com, Smart Rollup nodes have two weeks to challenge commitments made about the state of a Smart Rollup, although they usually challenge any questionable state as soon as possible.
 
 Therefore, an Etherlink transaction is truly finalized two weeks after the block it is in has been published to Tezos layer 1.
 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:
+
+- **The sequencer provides Instant Confirmations within 50ms.**
+As described in [Getting Instant Confirmations](/building-on-etherlink/transactions#getting-instant-confirmations), the sequencer notifies the nodes of the transactions that it intends to include in the next block.
+The sequencer provides this notification as soon as it enqueues the transaction for the next block, before the transaction has been executed.
+Users can subscribe to these notifications via the `tez_newIncludedTransactions` event, as described in [Subscribing to Instant Confirmations](/building-on-etherlink/websockets#subscribing-to-instant-confirmations).
+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.

docs/progress/upgrades.md

@@ -101,8 +101,14 @@ 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)
 
-- 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 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.
+Instant Confirmations enable these features:
+
+  - 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 node when the transaction will be in the next block.
+  For more information, see [Getting Instant Confirmations](/building-on-etherlink/transactions#getting-instant-confirmations).
+
+  - Uses can subscribe to notifications via WebSockets to get information about transactions that the sequencer will put in the next block.
+  For more information, see [Subscribing to Instant Confirmations](/building-on-etherlink/websockets#subscribing-to-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.