From 1be6ca1804791cff828cc6ff06d8b62eb99bc3c1 Mon Sep 17 00:00:00 2001
From: Dmitrii <lost.ping@gmail.com>
Date: Wed, 17 Jun 2026 20:24:48 +0500
Subject: [PATCH] docs: document EIP-1898 blockHash/requireCanonical for
 readContract and multicall

---
 site/pages/docs/contract/multicall.md    | 62 ++++++++++++++++++++++++
 site/pages/docs/contract/readContract.md | 31 ++++++++++++
 2 files changed, 93 insertions(+)

diff --git a/site/pages/docs/contract/multicall.md b/site/pages/docs/contract/multicall.md
index b716f71b8b..00cf755105 100644
--- a/site/pages/docs/contract/multicall.md
+++ b/site/pages/docs/contract/multicall.md
@@ -249,6 +249,68 @@ const results = await publicClient.multicall({
 })
 ```
 
+### blockTag (optional)
+
+- **Type:** `'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`
+- **Default:** `'latest'`
+
+The block tag to perform the read against.
+
+```ts
+const results = await publicClient.multicall({
+  contracts: [
+    {
+      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+      abi: wagmiAbi,
+      functionName: 'totalSupply',
+    },
+    ...
+  ],
+  blockTag: 'safe', // [!code focus]
+})
+```
+
+### blockHash (optional)
+
+- **Type:** `Hash`
+
+The block hash to perform the read against. Implements [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898).
+
+```ts
+const results = await publicClient.multicall({
+  contracts: [
+    {
+      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+      abi: wagmiAbi,
+      functionName: 'totalSupply',
+    },
+    ...
+  ],
+  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d', // [!code focus]
+})
+```
+
+### requireCanonical (optional)
+
+- **Type:** `boolean`
+
+Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. Implements [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898).
+
+```ts
+const results = await publicClient.multicall({
+  contracts: [
+    {
+      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+      abi: wagmiAbi,
+      functionName: 'totalSupply',
+    },
+    ...
+  ],
+  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d',
+  requireCanonical: true, // [!code focus]
+})
+```
+
 ### deployless (optional)
 
 - **Type:** `boolean`
diff --git a/site/pages/docs/contract/readContract.md b/site/pages/docs/contract/readContract.md
index a15fd86d16..2164486059 100644
--- a/site/pages/docs/contract/readContract.md
+++ b/site/pages/docs/contract/readContract.md
@@ -309,6 +309,37 @@ const data = await publicClient.readContract({
 })
 ```
 
+### blockHash (optional)
+
+- **Type:** `Hash`
+
+The block hash to perform the read against. Implements [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898).
+
+```ts
+const data = await publicClient.readContract({
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'totalSupply',
+  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d', // [!code focus]
+})
+```
+
+### requireCanonical (optional)
+
+- **Type:** `boolean`
+
+Whether or not to throw an error if the block is not in the canonical chain. Only allowed in conjunction with `blockHash`. Implements [EIP-1898](https://eips.ethereum.org/EIPS/eip-1898).
+
+```ts
+const data = await publicClient.readContract({
+  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
+  abi: wagmiAbi,
+  functionName: 'totalSupply',
+  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d',
+  requireCanonical: true, // [!code focus]
+})
+```
+
 ### factory (optional)
 
 - **Type:**