From 762b42bf201be340036f78a8b3b0c094bc3737c5 Mon Sep 17 00:00:00 2001 From: Yash Date: Mon, 29 Jun 2026 05:32:56 +0000 Subject: [PATCH 1/2] docs: clarify on-chain payload validation and revert behavior --- target_chains/ethereum/contracts/README.md | 42 +++++++++++++++++++ target_chains/ethereum/sdk/js/README.md | 27 ++++++++++++ target_chains/ethereum/sdk/solidity/README.md | 42 +++++++++++++++++++ 3 files changed, 111 insertions(+) diff --git a/target_chains/ethereum/contracts/README.md b/target_chains/ethereum/contracts/README.md index c23f1194a2..73bd0ee146 100644 --- a/target_chains/ethereum/contracts/README.md +++ b/target_chains/ethereum/contracts/README.md @@ -130,3 +130,45 @@ optimization with it. For more information, please refer to [Gas Snapshots docum Once you optimized the code, please share the snapshot difference (generated using `forge snapshot --diff `) in the PR too. This snapshot gas value also includes an initial transaction cost as well as reading from the contract storage itself. You can get the most accurate result by looking at the gas report or the gas shown in the call trace with `-vvvv` argument to `forge test`. + +## Important Integration Notes + +### On-Chain Payload Validation +> [!WARNING] +> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. +> +> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: +> - Wormhole VAA cryptographic integrity or structure +> - Data source / emitter identity correctness +> +> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. + +## Important Integration Notes + +### On-Chain Payload Validation + +> [!WARNING] +> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. +> +> Applications and SDKs forward the provided payload bytes and do not perform full validation of: +> - Wormhole VAA integrity or structure +> - Data source / emitter identity +> +> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the application or SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. +> +> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. + +## Important Integration Notes + +### On-Chain Payload Validation + +> [!WARNING] +> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. +> +> Applications and SDKs forward the provided payload bytes and do not perform full validation of: +> - Wormhole VAA integrity or structure +> - Data source / emitter identity +> +> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the application or SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. +> +> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. diff --git a/target_chains/ethereum/sdk/js/README.md b/target_chains/ethereum/sdk/js/README.md index 8d541be0a6..caf171a795 100644 --- a/target_chains/ethereum/sdk/js/README.md +++ b/target_chains/ethereum/sdk/js/README.md @@ -75,3 +75,30 @@ if (pythUpdate) { console.log("No Pyth data needed for this transaction"); } ``` + +## Important Integration Notes + +### On-Chain Payload Validation +> [!WARNING] +> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. +> +> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: +> - Wormhole VAA cryptographic integrity or structure +> - Data source / emitter identity correctness +> +> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. + +## Important Integration Notes + +### On-Chain Payload Validation + +> [!WARNING] +> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. +> +> Client SDKs forward the provided payload bytes and do not perform full validation of: +> - Wormhole VAA integrity or structure +> - Data source / emitter identity +> +> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. +> +> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. diff --git a/target_chains/ethereum/sdk/solidity/README.md b/target_chains/ethereum/sdk/solidity/README.md index 8546fda666..4ad141c40f 100644 --- a/target_chains/ethereum/sdk/solidity/README.md +++ b/target_chains/ethereum/sdk/solidity/README.md @@ -100,3 +100,45 @@ We use [Semantic Versioning](https://semver.org/) for our releases. In order to 1. Run `npm version --no-git-tag-version`. This command will update the version of the package. Then push your changes to github. 2. Once your change is merged into `main`, create a release with tag `v` like `v1.5.2`, and a github action will automatically publish the new version of this package to npm. + +## Important Integration Notes + +### On-Chain Payload Validation +> [!WARNING] +> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. +> +> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: +> - Wormhole VAA cryptographic integrity or structure +> - Data source / emitter identity correctness +> +> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. + +## Important Integration Notes + +### On-Chain Payload Validation + +> [!WARNING] +> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. +> +> Client SDKs forward the provided payload bytes and do not perform full validation of: +> - Wormhole VAA integrity or structure +> - Data source / emitter identity +> +> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. +> +> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. + +## Important Integration Notes + +### On-Chain Payload Validation + +> [!WARNING] +> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. +> +> Client SDKs forward the provided payload bytes and do not perform full validation of: +> - Wormhole VAA integrity or structure +> - Data source / emitter identity +> +> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. +> +> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. From 30f6407e1a5591c5932509745328ee7abe778d3e Mon Sep 17 00:00:00 2001 From: Yash Date: Mon, 29 Jun 2026 05:48:35 +0000 Subject: [PATCH 2/2] docs(ethereum): clarify on-chain validation of price update payloads --- target_chains/ethereum/contracts/README.md | 27 ------------------- target_chains/ethereum/sdk/js/README.md | 12 --------- target_chains/ethereum/sdk/solidity/README.md | 27 ------------------- 3 files changed, 66 deletions(-) diff --git a/target_chains/ethereum/contracts/README.md b/target_chains/ethereum/contracts/README.md index 73bd0ee146..a64625e68b 100644 --- a/target_chains/ethereum/contracts/README.md +++ b/target_chains/ethereum/contracts/README.md @@ -133,33 +133,6 @@ most accurate result by looking at the gas report or the gas shown in the call t ## Important Integration Notes -### On-Chain Payload Validation -> [!WARNING] -> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. -> -> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: -> - Wormhole VAA cryptographic integrity or structure -> - Data source / emitter identity correctness -> -> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. - -## Important Integration Notes - -### On-Chain Payload Validation - -> [!WARNING] -> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. -> -> Applications and SDKs forward the provided payload bytes and do not perform full validation of: -> - Wormhole VAA integrity or structure -> - Data source / emitter identity -> -> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the application or SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. -> -> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. - -## Important Integration Notes - ### On-Chain Payload Validation > [!WARNING] diff --git a/target_chains/ethereum/sdk/js/README.md b/target_chains/ethereum/sdk/js/README.md index caf171a795..894d0be1f3 100644 --- a/target_chains/ethereum/sdk/js/README.md +++ b/target_chains/ethereum/sdk/js/README.md @@ -78,18 +78,6 @@ if (pythUpdate) { ## Important Integration Notes -### On-Chain Payload Validation -> [!WARNING] -> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. -> -> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: -> - Wormhole VAA cryptographic integrity or structure -> - Data source / emitter identity correctness -> -> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. - -## Important Integration Notes - ### On-Chain Payload Validation > [!WARNING] diff --git a/target_chains/ethereum/sdk/solidity/README.md b/target_chains/ethereum/sdk/solidity/README.md index 4ad141c40f..c768f1e02d 100644 --- a/target_chains/ethereum/sdk/solidity/README.md +++ b/target_chains/ethereum/sdk/solidity/README.md @@ -103,33 +103,6 @@ We use [Semantic Versioning](https://semver.org/) for our releases. In order to ## Important Integration Notes -### On-Chain Payload Validation -> [!WARNING] -> Price update payloads (such as those retrieved from Hermes) undergo validation **strictly on-chain** at execution time. -> -> The client-side SDKs pass payload bytes transparently and do not perform pre-validation on: -> - Wormhole VAA cryptographic integrity or structure -> - Data source / emitter identity correctness -> -> If an invalid or malformed payload is passed to `updatePriceFeeds` (or equivalent methods), the client SDK will not throw an error. Instead, the transaction will proceed to the blockchain and revert on-chain with native contract errors like `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. - -## Important Integration Notes - -### On-Chain Payload Validation - -> [!WARNING] -> Price update payloads (for example, those retrieved from Hermes) are **authoritatively validated on-chain** during transaction execution. -> -> Client SDKs forward the provided payload bytes and do not perform full validation of: -> - Wormhole VAA integrity or structure -> - Data source / emitter identity -> -> If an invalid or malformed payload is supplied to `updatePriceFeeds` (or equivalent methods), the SDK will not reject it before submission. Instead, the transaction will revert on-chain with native contract errors such as `InvalidWormholeVaa()` or `InvalidUpdateDataSource()`. -> -> To minimize failed transactions, obtain payloads from trusted providers (such as Hermes) and consider simulating transactions before broadcasting. - -## Important Integration Notes - ### On-Chain Payload Validation > [!WARNING]