Add Queries Section

.snippets/code/build/build-apps/queries/hands-on-with-queries/eth-call-initial-request.txt

@@ -0,0 +1 @@
+curl https://ethereum.publicnode.com -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2","data":"0x18160ddd"},"latest"],"id":1}'

.snippets/code/build/build-apps/queries/hands-on-with-queries/eth-call-initial-response.txt

@@ -0,0 +1,5 @@
+{
+  "jsonrpc":"2.0",
+  "id":1,
+  "result":"0x000000000000000000000000000000000000000000029fd3d129b582d7949e71"
+}

.snippets/code/build/build-apps/queries/hands-on-with-queries/query-demo.sol

@@ -0,0 +1,137 @@
+// contracts/query/QueryDemo.sol
+// SPDX-License-Identifier: Apache 2
+
+pragma solidity ^0.8.0;
+
+import "wormhole-solidity-sdk/libraries/BytesParsing.sol";
+import "wormhole-solidity-sdk/interfaces/IWormhole.sol";
+import "wormhole-solidity-sdk/QueryResponse.sol";
+
+error InvalidOwner();
+// @dev for the onlyOwner modifier
+error InvalidCaller();
+error InvalidCalldata();
+error InvalidForeignChainID();
+error ObsoleteUpdate();
+error StaleUpdate();
+error UnexpectedResultLength();
+error UnexpectedResultMismatch();
+
+/// @dev QueryDemo is an example of using the QueryResponse library to parse and verify Cross Chain Query (CCQ) responses.
+contract QueryDemo is QueryResponse {
+    using BytesParsing for bytes;
+
+    struct ChainEntry {
+        uint16 chainID;
+        address contractAddress;
+        uint256 counter;
+        uint256 blockNum;
+        uint256 blockTime;
+    }
+
+    address private immutable owner;
+    uint16 private immutable myChainID;
+    mapping(uint16 => ChainEntry) private counters;
+    uint16[] private foreignChainIDs;
+
+    bytes4 public GetMyCounter = bytes4(hex"916d5743");
+
+    constructor(address _owner, address _wormhole, uint16 _myChainID) QueryResponse(_wormhole) {
+        if (_owner == address(0)) {
+            revert InvalidOwner();
+        }
+        owner = _owner;
+
+        myChainID = _myChainID;
+        counters[_myChainID] = ChainEntry(_myChainID, address(this), 0, 0, 0);
+    }
+
+    // updateRegistration should be used to add the other chains and to set / update contract addresses.
+    function updateRegistration(uint16 _chainID, address _contractAddress) public onlyOwner {
+        if (counters[_chainID].chainID == 0) {
+            foreignChainIDs.push(_chainID);
+            counters[_chainID].chainID = _chainID;
+        }
+
+        counters[_chainID].contractAddress = _contractAddress;
+    }
+
+    // getMyCounter (call signature 916d5743) returns the counter value for this chain. It is meant to be used in a cross chain query.
+    function getMyCounter() public view returns (uint256) {
+        return counters[myChainID].counter;
+    }
+
+    // getState() returns this chain's view of all the counters. It is meant to be used in the front end.
+    function getState() public view returns (ChainEntry[] memory) {
+        ChainEntry[] memory ret = new ChainEntry[](foreignChainIDs.length + 1);
+        ret[0] = counters[myChainID];
+        uint256 length = foreignChainIDs.length;
+
+        for (uint256 i = 0; i < length;) {
+            ret[i + 1] = counters[foreignChainIDs[i]];
+            unchecked {
+                ++i;
+            }
+        }
+
+        return ret;
+    }
+
+    // @notice Takes the cross chain query response for the other counters, stores the results for the other chains, and updates the counter for this chain.
+    function updateCounters(bytes memory response, IWormhole.Signature[] memory signatures) public {
+        ParsedQueryResponse memory r = parseAndVerifyQueryResponse(response, signatures);
+        uint256 numResponses = r.responses.length;
+        if (numResponses != foreignChainIDs.length) {
+            revert UnexpectedResultLength();
+        }
+
+        for (uint256 i = 0; i < numResponses;) {
+            // Create a storage pointer for frequently read and updated data stored on the blockchain
+            ChainEntry storage chainEntry = counters[r.responses[i].chainId];
+            if (chainEntry.chainID != foreignChainIDs[i]) {
+                revert InvalidForeignChainID();
+            }
+
+            EthCallQueryResponse memory eqr = parseEthCallQueryResponse(r.responses[i]);
+
+            // Validate that update is not obsolete
+            validateBlockNum(eqr.blockNum, chainEntry.blockNum);
+
+            // Validate that update is not stale
+            validateBlockTime(eqr.blockTime, block.timestamp - 300);
+
+            if (eqr.result.length != 1) {
+                revert UnexpectedResultMismatch();
+            }
+
+            // Validate addresses and function signatures
+            address[] memory validAddresses = new address[](1);
+            bytes4[] memory validFunctionSignatures = new bytes4[](1);
+            validAddresses[0] = chainEntry.contractAddress;
+            validFunctionSignatures[0] = GetMyCounter;
+
+            validateMultipleEthCallData(eqr.result, validAddresses, validFunctionSignatures);
+
+            require(eqr.result[0].result.length == 32, "result is not a uint256");
+
+            chainEntry.blockNum = eqr.blockNum;
+            chainEntry.blockTime = eqr.blockTime / 1_000_000;
+            chainEntry.counter = abi.decode(eqr.result[0].result, (uint256));
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        counters[myChainID].blockNum = block.number;
+        counters[myChainID].blockTime = block.timestamp;
+        counters[myChainID].counter += 1;
+    }
+
+    modifier onlyOwner() {
+        if (owner != msg.sender) {
+            revert InvalidOwner();
+        }
+        _;
+    }
+}

.snippets/code/build/build-apps/queries/hands-on-with-queries/query-proxy-query-response.jsx

@@ -0,0 +1,4 @@
+const tx = await contract.updateCounters(
+  `0x${response.data.bytes}`,
+  signaturesToEvmStruct(response.data.signatures)
+);

.snippets/code/build/build-apps/queries/hands-on-with-queries/query-request-with-api-key.jsx

@@ -0,0 +1,8 @@
+const serialized = request.serialize();
+const proxyResponse = (await axios.post)<QueryProxyQueryResponse>(
+  QUERY_URL,
+  {
+    bytes: Buffer.from(serialized).toString('hex'),
+  },
+  { headers: { 'X-API-Key': YOUR_API_KEY } }
+);

.snippets/code/build/build-apps/queries/hands-on-with-queries/test-full.jsx

@@ -0,0 +1,65 @@
+import {
+  EthCallData,
+  EthCallQueryRequest,
+  EthCallQueryResponse,
+  PerChainQueryRequest,
+  QueryProxyMock,
+  QueryRequest,
+  QueryResponse,
+} from '@wormhole-foundation/wormhole-query-sdk';
+import axios from 'axios';
+
+const rpc = 'https://ethereum.publicnode.com';
+const callData: EthCallData = {
+  to: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
+  data: '0x18160ddd', // web3.eth.abi.encodeFunctionSignature("totalSupply()")
+};
+
+(async () => {
+  const latestBlock: string = (
+    await axios.post(rpc, {
+      method: 'eth_getBlockByNumber',
+      params: ['latest', false],
+      id: 1,
+      jsonrpc: '2.0',
+    })
+  ).data?.result?.number;
+  if (!latestBlock) {
+    console.error(`❌ Invalid block returned`);
+    return;
+  }
+  console.log('Latest Block:     ', latestBlock, `(${BigInt(latestBlock)})`);
+  const targetResponse = await axios.post(rpc, {
+    method: 'eth_call',
+    params: [callData, latestBlock],
+    id: 1,
+    jsonrpc: '2.0',
+  });
+  // console.log(finalizedResponse.data);
+  if (targetResponse.data.error) {
+    console.error(`❌ ${targetResponse.data.error.message}`);
+  }
+  const targetResult = targetResponse.data?.result;
+  console.log('Target Result:    ', targetResult, `(${BigInt(targetResult)})`);
+  // Form the query request
+  const request = new QueryRequest(
+    0, // Nonce
+    [
+      new PerChainQueryRequest(
+        2, // Ethereum Wormhole Chain ID
+        new EthCallQueryRequest(latestBlock, [callData])
+      ),
+    ]
+  );
+  console.log(JSON.stringify(request, undefined, 2));
+  const mock = new QueryProxyMock({ 2: rpc });
+  const mockData = await mock.mock(request);
+  console.log(mockData);
+  const mockQueryResponse = QueryResponse.from(mockData.bytes);
+  const mockQueryResult = (
+    mockQueryResponse.responses[0].response as EthCallQueryResponse
+  ).results[0];
+  console.log(
+    `Mock Query Result: ${mockQueryResult} (${BigInt(mockQueryResult)})`
+  );
+})();

build/build-apps/.pages

@@ -2,3 +2,4 @@ title: Build Multichain Apps
 nav:
  - index.md
  - 'Wormhole SDK': 'wormhole-sdk.md'
+ - queries

build/build-apps/queries/.pages

@@ -0,0 +1,6 @@
+title: Queries
+nav:
+ - index.md
+ - 'Overview': overview.md
+ - 'Hands on with Queries': hands-on-with-queries.md
+ - 'FAQs': faqs.md

build/build-apps/queries/faqs.md

@@ -0,0 +1,45 @@
+---
+title: FAQs about Queries
+description: Explore frequently asked questions about Wormhole Queries, which offer on-demand access to guardian-attested on-chain data via a REST API endpoint.
+---
+
+# FAQs about Queries
+
+## What Libraries Are Available to Handle Queries?
+
+- The [Query TypeScript SDK](https://npmjs.com/package/@wormhole-foundation/wormhole-query-sdk){target=\_blank} can be used to create query requests, mock query responses for testing, and parse query responses. The SDK also includes utilities for posting query responses
+
+- The [Solidity `QueryResponse` abstract contract](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/QueryResponse.sol){target=\_blank} can be used to parse and verify query responses on EVM chains. See the [Solana Stake Pool](https://github.com/wormholelabs-xyz/example-queries-solana-stake-pool){target=\_blank} repository as an example use case
+
+- [`QueryTest.sol`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/testing/helpers/QueryTest.sol){target=\_blank} can be used for mocking query requests and responses in Forge tests
+
+- The [Go query package](https://github.com/wormhole-foundation/wormhole/tree/main/node/pkg/query){target=\_blank} can also be used to create query requests and parse query responses
+
+!!! note
+    A Rust SDK for Solana is being actively investigated by the Wormhole contributors. See the [Solana Queries Verification](https://github.com/wormholelabs-xyz/example-queries-solana-verify){target=\_blank} repository as a proof of concept.
+
+## Are There Any Query Examples?
+
+Certainly. You can find a complete guide on the [Hands on with Queries page](/build/build-apps/queries/hands-on-with-queries). Additionally, you can find full code examples in available in the following repositories:
+
+- [Basic Example Query Demo](https://github.com/wormholelabs-xyz/example-queries-demo/){target=\_blank}
+- [Solana Stake Pool Example Query](https://github.com/wormholelabs-xyz/example-queries-solana-stake-pool){target=\_blank}
+- [Solana PDA / Token Account Balance Example Query](https://github.com/wormholelabs-xyz/example-queries-solana-pda){target=\_blank}
+- [Solana Queries Verification Example](https://github.com/wormholelabs-xyz/example-queries-solana-verify){target=\_blank}
+
+## What Is the Format of the Response Signature?
+
+The Guardian node calculates an ECDSA signature using [`Sign` function of the crypto package](https://pkg.go.dev/github.com/ethereum/go-ethereum@v1.10.21/crypto#Sign){target=\_blank} where the digest hash is:
+
+`keccak256("query_response_0000000000000000000|"+keccak256(responseBytes))` 
+
+See the [Guardian Key Usage](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0009_guardian_key.md){target=\_blank} white paper for more background. Once this signature is created, the Guardian's index in the Guardian set is appended to the end.
+
+!!! note
+    If you are used to `ecrecover` you will notice that the `v` byte is `0` or `1` as opposed to `27` or `28`. The `signaturesToEvmStruct` method in the [Query TypeScript SDK](https://npmjs.com/package/@wormhole-foundation/wormhole-query-sdk){target=\_blank} accounts for this as well as structuring the signatures into an `IWormhole.SignatureStruct[]`.
+
+## Can Anyone Run a Query Proxy Server?
+
+Permissions for Query Proxy are managed by the Guardians. The Guardian nodes are configured to only listen to a set of allow-listed proxies. However, it is possible that this restriction may be lifted in the future and/or more proxies could be added.
+
+It is also important to note that the proxies don't impact the verifiability of the request or result, i.e., their role in the process is trustless.