Queries Overview

Wormhole Guardians, who run full nodes for various connected chains, facilitate a new cross-chain query service that allows for on-demand attested responses to queries, bypassing the inefficiencies of traditional transaction-based data retrieval. This method is faster and cost-effective, eliminating the need for gas payments and transaction finality wait times.

Note

Queries are currently in closed beta, though you can start developing today. Check out Use Queries and reach out to Join the beta.

Wormhole Queries offers on-demand access to Guardian-attested on-chain data. The current implementation provides integrators with a simple REST endpoint to initiate an off-chain request via a proxy. The proxy then forwards the request to the Guardians and gathers a quorum of responses. The result returns the encoded response, including the request details and the Guardian signatures. The request validation performed by the query module includes a three step process that involves verifying the signature to ensure it has the correct prefix, confirming that the signer is authorized to execute query requests, and validating the legitimacy of all per-chain requests contained in the query. You can read more about Queries in the white paper.

The Flow of a Query

The general overview of a query's flow is as follows: an off-chain process sends HTTPS query requests to a Query Proxy, which validates and forwards them to the Guardians; these Guardians independently validate, sign, and return the response, with the entire process typically taking less than a second.

The step-by-step flow of a query is as follows:

An off-chain process initiates a query request via HTTPS to the query proxy (or Query Server)
The query proxy validates the request and forwards it to the Guardians via a gossip network
The Guardians independently validate the request, make the requisite RPC calls, verify the results, sign, and gossip a response back to the Query Proxy
The Query Proxy aggregates the results and returns a response when it reaches a quorum of two-thirds or more of the current Guardian set - the exact quorum requirements as the core bridge
The off-chain process can then submit these requests to an on-chain contract which should verify the signatures and validate the request before processing the result

In this flow, the Query Proxy is a permissioned but trustless part of the protocol. In most cases, this entire process takes less than one second. If a request is invalid or cannot be processed by the Guardians, they will retry for up to one minute before timing out. Requests can be batched to have the Guardians make multiple calls to multiple networks. This can further reduce overhead for processing query responses on-chain. Up to 255 queries can be batched together, with certain types allowing for batching themselves.

Supported Query Types

There are currently five supported types of queries. See the white paper for more details on each.

eth_call

This query type is effectively an equivalent of eth_call against a block specified by number or hash.

Calls are batched to allow specifying multiple calls (even to multiple contracts) against the same block. These calls are included in a single batch RPC call, simplifying on-chain verification. Up to 255 calls may be batched in an single eth_call query.

The result contains the specified block number, hash, timestamp, and the call result.

eth_call By Timestamp

This query type is similar to eth_call but targets a timestamp instead of a specific block_id. This can be useful when forming requests based on uncorrelated data, such as requiring data from another chain based on the block timestamp of a given chain.

The result also contains the target and block details with the following enforced conditions: target_block.timestamp <= target_time < following_block.timestamp and following_block_num - 1 == target_block_num.

eth_call With Finality

This query type is similar to eth_call but ensures that the specified block has reached the specified finality before returning the query results. The finality may be finalized or safe. Note that if a chain doesn't natively support the safe tag, this will be equivalent to finalized.

sol_account

This query is used to read data for one or more accounts on Solana, akin to getMultipleAccounts.

sol_pda

This query is used to read data for one or more Program Derived Addresses(PDA) on Solana, akin to calling getMultipleAccounts on the result of PublicKey.findProgramAddressSync(seeds, programId). This query is helpful for times when you want to more generally read accounts owned by a program and verify the derivation on another chain, like how associated token accounts are all derived from the Associated Token Account Program.

Supported Chains

The following table provides expected support based on testing. However, the success of any given query is based on the success of the underlying call on each Guardian’s RPC node.

For example, many chains have implementations forked from Geth, which keeps 128 blocks of state in memory by default (without running in archive mode). While this is good for about 25 minutes of history on Ethereum MainNet, it is only about three minutes on Optimism. While Guardian nodes can be expected to have access to recent state, there are currently no guarantees of how far back in history they have access to.

MainNet

Chain	Wormhole Chain ID	eth_call	By Timestamp	With Finality	Expected History
Ethereum	2	✅	✅	✅	128 blocks
BSC	4	✅	✅	✅	128 blocks
Polygon	5	✅	✅	✅	128 blocks
Avalanche	6	✅	✅	✅	32 blocks
Oasis Emerald	7	✅	✅	✅	archive
Fantom	10	✅	✅	✅	16 blocks
Karura	11	✅	✅	✅	archive
Acala	12	✅	✅	✅	archive
Klaytn	13	✅	✅	✅	128 blocks
Celo	14	✅	ℹ️ hints required*	✅	128 blocks
Moonbeam	16	✅	ℹ️ hints required*	✅	256 blocks
Arbitrum One	23	✅	✅	✅	~6742 blocks
Optimism	24	✅	✅	❌	128 blocks
Base	30	✅	✅	✅	archive

*EthCallByTimestamp arguments for targetBlock and followingBlock are currently required for requests to be successful on these chains.

Next Steps

Remember that Wormhole Queries are currently in beta. You can register to join the beta to fully experiment with Wormhole Queries.

Be sure to check out the FAQs and the Use Queries guide.

You can also check out the following examples of applications that make use of Wormhole Queries: