prividium 0.20.0 → 0.21.0

package/dist/sdk/selective-disclosure/verify-disclosure.d.ts

@@ -12,29 +12,52 @@ export declare const DIAMOND_ABI: {
         readonly type: "bytes32";
     }];
 }[];
+export type CallDisclosureResult = {
+    success: true;
+} | {
+    success: false;
+    errorMsg: string;
+};
+type VerifyEthCallDisclosureParams = {
+    disclosure: EthCallDisclosureResult;
+    l1Client: PublicClient;
+    l2Client: PublicClient;
+    diamondAddress: Address;
+    contractBytecodes: Record<Address, Hex>;
+    batchNumber: number;
+    expectedTo?: Address;
+    expectedCallData?: Hex;
+};
 /**
  * Verifies an ethCall disclosure response end-to-end.
  *
  * Verification steps:
- * 1. Extracts Merkle roots from all storage proofs and checks they are consistent.
- * 2. Computes the state commitment from the tree root and preimage data.
- * 3. Encodes the batch info, hashes it, and compares against the L1 diamond proxy's `storedBatchHash`.
- * 4. Replays the original call on `l2Client` with state overrides (proven storage + bytecodes)
+ * 1. Checks the disclosure's `to` and `callData` match `expectedTo` / `expectedCallData` when provided.
+ * 2. Extracts Merkle roots from all storage proofs and checks they are consistent.
+ * 3. Computes the state commitment from the tree root and preimage data.
+ * 4. Encodes the batch info, hashes it, and compares against the L1 diamond proxy's `storedBatchHash`.
+ * 5. Replays the original call on `l2Client` with state overrides (proven storage + bytecodes)
  *    and checks the result matches the disclosed value.
  *
  * Throws if the disclosure data is internally inconsistent (e.g. no proofs, divergent roots,
  * or missing bytecode for a contract referenced in the proofs).
  *
- * Returns `true` if every check passes, `false` otherwise.
+ * Returns `{ success: true }` if every check passes, otherwise `{ success: false, errorMsg }`.
  *
- * @param disclosure - The response from `prividium_tokenSupplyDisclosure` or `prividium_tokenBalanceDisclosure`.
- * @param l1Client - A viem PublicClient connected to L1, used to read `storedBatchHash` from the diamond proxy.
- * @param l2Client - A viem PublicClient connected to a local L2 node trusted by the caller. Used to
+ * @param params - A single object holding all verification inputs:
+ * @param params.disclosure - The response from `prividium_tokenSupplyDisclosure` or `prividium_tokenBalanceDisclosure`.
+ * @param params.l1Client - A viem PublicClient connected to L1, used to read `storedBatchHash` from the diamond proxy.
+ * @param params.l2Client - A viem PublicClient connected to a local L2 node trusted by the caller. Used to
  *   replay the disclosed call with state overrides. This must be a node the caller trusts, not the
  *   Prividium proxy, so the replay cannot be manipulated.
- * @param diamondAddress - The address of the L1 diamond proxy contract that stores batch commitments.
- * @param contractBytecodes - A mapping from contract address to deployed bytecode (hex) for every
+ * @param params.diamondAddress - The address of the L1 diamond proxy contract that stores batch commitments.
+ * @param params.contractBytecodes - A mapping from contract address to deployed bytecode (hex) for every
  *   contract referenced in the disclosure proofs. Used for the call replay with state overrides.
- * @param batchNumber - The L1 batch number the disclosure was computed against.
+ * @param params.batchNumber - The L1 batch number the disclosure was computed against.
+ * @param params.expectedTo - Optional. The address the disclosed call was expected to target; when set,
+ *   verification fails if it does not match `disclosure.to` (case-insensitive).
+ * @param params.expectedCallData - Optional. The calldata the disclosed call was expected to use; when
+ *   set, verification fails if it does not match `disclosure.callData` (case-insensitive).
  */
-export declare function verifyEthCallDisclosure(disclosure: EthCallDisclosureResult, l1Client: PublicClient, l2Client: PublicClient, diamondAddress: Address, contractBytecodes: Record<Address, Hex>, batchNumber: number): Promise<boolean>;
+export declare function verifyEthCallDisclosure({ disclosure, l1Client, l2Client, diamondAddress, contractBytecodes, batchNumber, expectedTo, expectedCallData }: VerifyEthCallDisclosureParams): Promise<CallDisclosureResult>;
+export {};

package/dist/sdk/selective-disclosure/verify-disclosure.js

@@ -1,6 +1,7 @@
 import { keccak256, pad, parseAbiItem } from 'viem';
 import { encodeBatchInfo } from './batch-info.js';
 import { computeStateCommitment } from './state-commitment.js';
+import { areHexEqual } from './utils.js';
 import { calculateStateMerkleRoot } from './verifiy-proofs.js';
 export const DIAMOND_ABI = [
     parseAbiItem('function storedBatchHash(uint256 _batchNumber) external view returns (bytes32)')
@@ -35,29 +36,46 @@ const tracerStr = `{
  * Verifies an ethCall disclosure response end-to-end.
  *
  * Verification steps:
- * 1. Extracts Merkle roots from all storage proofs and checks they are consistent.
- * 2. Computes the state commitment from the tree root and preimage data.
- * 3. Encodes the batch info, hashes it, and compares against the L1 diamond proxy's `storedBatchHash`.
- * 4. Replays the original call on `l2Client` with state overrides (proven storage + bytecodes)
+ * 1. Checks the disclosure's `to` and `callData` match `expectedTo` / `expectedCallData` when provided.
+ * 2. Extracts Merkle roots from all storage proofs and checks they are consistent.
+ * 3. Computes the state commitment from the tree root and preimage data.
+ * 4. Encodes the batch info, hashes it, and compares against the L1 diamond proxy's `storedBatchHash`.
+ * 5. Replays the original call on `l2Client` with state overrides (proven storage + bytecodes)
  *    and checks the result matches the disclosed value.
  *
  * Throws if the disclosure data is internally inconsistent (e.g. no proofs, divergent roots,
  * or missing bytecode for a contract referenced in the proofs).
  *
- * Returns `true` if every check passes, `false` otherwise.
+ * Returns `{ success: true }` if every check passes, otherwise `{ success: false, errorMsg }`.
  *
- * @param disclosure - The response from `prividium_tokenSupplyDisclosure` or `prividium_tokenBalanceDisclosure`.
- * @param l1Client - A viem PublicClient connected to L1, used to read `storedBatchHash` from the diamond proxy.
- * @param l2Client - A viem PublicClient connected to a local L2 node trusted by the caller. Used to
+ * @param params - A single object holding all verification inputs:
+ * @param params.disclosure - The response from `prividium_tokenSupplyDisclosure` or `prividium_tokenBalanceDisclosure`.
+ * @param params.l1Client - A viem PublicClient connected to L1, used to read `storedBatchHash` from the diamond proxy.
+ * @param params.l2Client - A viem PublicClient connected to a local L2 node trusted by the caller. Used to
  *   replay the disclosed call with state overrides. This must be a node the caller trusts, not the
  *   Prividium proxy, so the replay cannot be manipulated.
- * @param diamondAddress - The address of the L1 diamond proxy contract that stores batch commitments.
- * @param contractBytecodes - A mapping from contract address to deployed bytecode (hex) for every
+ * @param params.diamondAddress - The address of the L1 diamond proxy contract that stores batch commitments.
+ * @param params.contractBytecodes - A mapping from contract address to deployed bytecode (hex) for every
  *   contract referenced in the disclosure proofs. Used for the call replay with state overrides.
- * @param batchNumber - The L1 batch number the disclosure was computed against.
+ * @param params.batchNumber - The L1 batch number the disclosure was computed against.
+ * @param params.expectedTo - Optional. The address the disclosed call was expected to target; when set,
+ *   verification fails if it does not match `disclosure.to` (case-insensitive).
+ * @param params.expectedCallData - Optional. The calldata the disclosed call was expected to use; when
+ *   set, verification fails if it does not match `disclosure.callData` (case-insensitive).
  */
-export async function verifyEthCallDisclosure(disclosure, l1Client, l2Client, diamondAddress, contractBytecodes, batchNumber) {
-    // Step 1: Extract Merkle roots from all storage proofs and verify they're consistent.
+export async function verifyEthCallDisclosure({ disclosure, l1Client, l2Client, diamondAddress, contractBytecodes, batchNumber, expectedTo, expectedCallData }) {
+    const normalizedBytecodes = Object.entries(contractBytecodes).reduce((obj, [key, value]) => {
+        obj[key.toLowerCase()] = value;
+        return obj;
+    }, {});
+    // Step 1: Verify expected data match
+    if (expectedTo !== undefined && !areHexEqual(expectedTo, disclosure.to)) {
+        return { success: false, errorMsg: '"to" field doesn\'t match with expected value' };
+    }
+    if (expectedCallData !== undefined && !areHexEqual(expectedCallData, disclosure.callData)) {
+        return { success: false, errorMsg: '"callData" field doesn\'t match with expected value' };
+    }
+    // Step 2: Extract Merkle roots from all storage proofs and verify they're consistent.
     const roots = [];
     for (const proof of disclosure.proofs) {
         for (const storageProof of proof.storageProofs) {
@@ -71,26 +89,32 @@ export async function verifyEthCallDisclosure(disclosure, l1Client, l2Client, di
     if (new Set(roots).size !== 1) {
         throw new Error('Inconsistent data: multiple roots for same batch');
     }
-    // Step 2: Compute state commitment from the tree root + preimage data.
+    // Step 3: Compute state commitment from the tree root + preimage data.
     const stateCommitment = computeStateCommitment(roots[0], BigInt(disclosure.stateCommitmentPreimage.nextFreeSlot), BigInt(disclosure.stateCommitmentPreimage.blockNumber), disclosure.stateCommitmentPreimage.last256BlockHashesBlake, BigInt(disclosure.stateCommitmentPreimage.lastBlockTimestamp));
-    // Step 3: Encode batch info and keccak256 hash it.
+    // Step 4: Encode batch info and keccak256 hash it.
     const batchInfoHex = encodeBatchInfo(BigInt(batchNumber), stateCommitment, BigInt(disclosure.l1VerificationData.numberOfLayer1Txs), disclosure.l1VerificationData.priorityOperationsHash, disclosure.l1VerificationData.l2ToL1LogsRootHash, disclosure.l1VerificationData.commitment);
     const batchInfoHash = keccak256(batchInfoHex);
-    // Step 4: Verify against L1 diamond proxy.
-    const storedBatchHash = await l1Client.readContract({
+    // Step 5: Verify against L1 diamond proxy.
+    const storedBatchHash = await l1Client
+        .readContract({
         address: diamondAddress,
         abi: DIAMOND_ABI,
         functionName: 'storedBatchHash',
         args: [BigInt(batchNumber)]
+    })
+        .catch((e) => {
+        throw new Error('Error reading l1 diamond', { cause: e });
     });
-    if (batchInfoHash !== storedBatchHash) {
-        return false;
+    if (!areHexEqual(batchInfoHash, storedBatchHash)) {
+        return { success: false, errorMsg: 'L1 batch commitment does not match the proof data' };
     }
+    // Step 6: Replay the call on L2 with state overrides to verify the proven
+    // and debug capabilities storage values produce the expected result using the same slots.
     const contractAddress = disclosure.to;
     const stateOverride = {};
     for (const proof of disclosure.proofs) {
         const address = proof.address.toLowerCase();
-        const code = contractBytecodes[address];
+        const code = normalizedBytecodes[address];
         if (!code) {
             throw new Error(`Missing bytecode for contract ${address}`);
         }
@@ -119,18 +143,29 @@ export async function verifyEthCallDisclosure(disclosure, l1Client, l2Client, di
         ]
     });
     if (!debugResult.success) {
-        return false;
+        return { success: false, errorMsg: 'Error during simulated call' };
     }
+    // 7. Check that no slot reads were outside the expected proven slots.
     for (const address in debugResult.reads) {
         for (const slot of debugResult.reads[address]) {
             const realSlot = `0x${slot}`;
-            const exists = disclosure.proofs.find((p) => p.address.toLowerCase() === address.toLowerCase() &&
+            const exists = disclosure.proofs.find((p) => areHexEqual(p.address, address) &&
                 p.storageProofs.some((sp) => BigInt(sp.key) === BigInt(realSlot)));
             if (!exists) {
-                return false;
+                return {
+                    success: false,
+                    errorMsg: `Missing slot in provided proofs: ${realSlot}`
+                };
             }
         }
     }
-    const callResult = debugResult.value;
-    return BigInt(callResult) === BigInt(disclosure.result);
+    if (BigInt(debugResult.value) === BigInt(disclosure.result)) {
+        return { success: true };
+    }
+    else {
+        return {
+            success: false,
+            errorMsg: `Simulated call did not match with expected value. Expected: ${disclosure.result}, received: ${debugResult.value}`
+        };
+    }
 }