> =
coreProtocolClient.publishMessage(
whSignerAddress,
payload,
messageNonce,
consistencyLevel
);
// Sign and send the transactions
console.log(
'Signing and sending the message publication transaction(s)...'
);
const txIds: TransactionId[] = await signSendWait(
sourceChainContext,
unsignedTxs,
sdkSigner
);
if (!txIds || txIds.length === 0) {
throw new Error('No transaction IDs were returned from signSendWait.');
}
const primaryTxIdObject = txIds[txIds.length - 1];
const primaryTxid = primaryTxIdObject.txid;
console.log(`Primary transaction ID for parsing: ${primaryTxid}`);
console.log(
`View on Sepolia Etherscan: https://sepolia.etherscan.io/tx/${primaryTxid}`
);
console.log(
'\nWaiting a few seconds for transaction to propagate before parsing...'
);
await new Promise((resolve) => setTimeout(resolve, 8000));
// Retrieve VAA identifiers
console.log(
`Attempting to parse VAA identifiers from transaction: ${primaryTxid}...`
);
const messageIds: WormholeMessageId[] =
await sourceChainContext.parseTransaction(primaryTxid);
if (messageIds && messageIds.length > 0) {
const wormholeMessageId = messageIds[0];
console.log('--- VAA Identifiers (WormholeMessageId) ---');
console.log(' Emitter Chain:', wormholeMessageId.chain);
console.log(' Emitter Address:', wormholeMessageId.emitter.toString());
console.log(' Sequence:', wormholeMessageId.sequence.toString());
console.log('-----------------------------------------');
} else {
console.error(
`Could not parse Wormhole message IDs from transaction ${primaryTxid}.`
);
}
} catch (error) {
console.error(
'Error during message publishing or VAA identifier retrieval:',
error
);
if (error instanceof Error && error.stack) {
console.error('Stack Trace:', error.stack);
}
}
}
main().catch((e) => {
console.error('Critical error in main function (outer catch):', e);
if (e instanceof Error && e.stack) {
console.error('Stack Trace:', e.stack);
}
process.exit(1);
});
```
This script initializes the SDK, defines values for the source chain, creates an EVM signer, constructs the message, uses the core protocol to generate, sign, and send the transaction, and returns the VAA identifiers upon successful publication of the message.
2. Run the script using the following command:
```bash
npx tsx main.ts
```
You will see terminal output similar to the following:
npx tsx main.ts
Wormhole SDK Initialized.
Ethers.js Signer obtained for address: 0xCD8Bcd9A793a7381b3C66C763c3f463f70De4e12
Source chain context obtained for: Sepolia
Wormhole SDK Signer obtained for address: 0xCD8Bcd9A793a7381b3C66C763c3f463f70De4e12
Message to send: "HelloWormholeSDK-1748362375390"
Preparing to publish message from 0xCD8Bcd9A793a7381b3C66C763c3f463f70De4e12 on Sepolia...
Signing and sending the message publication transaction(s)...
Primary Transaction ID for parsing: 0xeb34f35f91c72e4e5198509071d24fd25d8a979aa93e2f168de075e3568e1508
View on Sepolia Etherscan: https://sepolia.etherscan.io/tx/0xeb34f35f91c72e4e5198509071d24fd25d8a979aa93e2f168de075e3568e1508
Waiting a few seconds for transaction to propagate before parsing...
Attempting to parse VAA identifiers from transaction:
0xeb34f35f91c72e4e5198509071d24fd25d8a979aa93e2f168de075e3568e1508...
--- VAA Identifiers (WormholeMessageId) ---
Emitter Chain: Sepolia
Emitter Address: 0x000000000000000000000000cd8bcd9a793a7381b3c66c763c3f463f70de4e12
Sequence: 1
-----------------------------------------
3. Make a note of the transaction ID and VAA identifier values. You can use the transaction ID to [view the transaction on Wormholescan](https://wormholescan.io/#/tx/0xeb34f35f91c72e4e5198509071d24fd25d8a979aa93e2f168de075e3568e1508?network=Testnet){target=\_blank}. The emitter chain, emitter address, and sequence values are used to retrieve and decode signed messages.
Congratulations! You've published your first multichain message using Wormhole's TypeScript SDK and core protocol functionality. Consider the following options to build upon what you've accomplished.
## Next Steps
- :octicons-tools-16:{ .lg .middle } **Get Started with WTT**
---
Follow this guide to start working with multichain token transfers using Wormhole Wrapped Token Transfers' lock and mint mechanism to send tokens across chains.
[:custom-arrow: Get Started](/docs/products/token-transfers/wrapped-token-transfers/get-started/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/){target=\_blank}
---
Page Title: Glossary
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-reference-glossary.md
- Canonical (HTML): https://wormhole.com/docs/products/reference/glossary/
- Summary: Explore a comprehensive glossary of technical terms and key concepts used in the Wormhole network, covering Chain ID, Guardian, VAA, and more.
- Word Count: 654; Token Estimate: 844
# Glossary
This glossary is an index of technical term definitions for words commonly used in Wormhole documentation.
## Chain ID
Wormhole assigns a unique `u16` integer chain ID to each supported blockchain. These chain IDs are specific to Wormhole and may differ from those used by blockchains to identify their networks.
You can find each chain ID documented on the [Wormhole Chain IDs](/docs/products/reference/chain-ids/){target=\_blank} page.
## Consistency Level
The level of finality (consistency) a transaction should meet before being signed by a Guardian. See the [Wormhole Finality](/docs/products/reference/consistency-levels/){target=\_blank} reference page for details.
## Delivery Provider
A Delivery Provider monitors for Executor delivery requests and delivers those requests to the intended target chain as instructed.
## Emitter
The emitter contract makes the call to the Wormhole Core Contract. The published message includes the emitter contract address, and a sequence number is tracked to provide a unique ID.
## Finality
The finality of a transaction depends on its blockchain properties. Once a transaction is considered final, you can assume the resulting state changes it caused will not be reverted.
## Guardian
A [Guardian](/docs/protocol/infrastructure/guardians/){target=\_blank} is one of the 19 parties running validators in the Guardian Network contributing to the VAA multisig.
## Guardian Network
Validators operating in a dedicated P2P network that serve as Wormhole's oracle layer. Guardians monitor on-chain activity and generate signed messages (VAAs) attesting to it.
For full Guardian Set chains, all 19 Guardians perform direct on-chain observation. For delegated chains, a delegated subset monitors and broadcasts signed delegate observations to the rest of the network. Canonical Guardians wait for a delegate quorum before signing. Regardless of the observation path, VAAs are always finalized as standard 13-of-19 multisignature attestations.
## Guardian Set
The Guardian Set is the canonical set of 19 Guardians responsible for producing VAAs. A supermajority of 13 signatures is required to generate a valid VAA.
For certain chains, governance may configure a delegated subset of the Guardian Set to perform direct on-chain observation with a smaller per-chain quorum. Canonical Guardians wait for a delegate quorum before signing, ensuring that the effective security threshold for a chain cannot fall below its configured level.
The composition of the Guardian Set may change through governance actions.
## Delegated Guardian
A Guardian configured to perform direct on-chain observation for a delegated chain. Delegated Guardians broadcast `SignedDelegateObservation` messages to the Guardian gossip network.
In contrast, a Canonical Guardian does not observe that chain directly, it waits for enough `DelegateObservation` messages (the delegate quorum) before contributing its signature to the VAA.
The key distinction: on a delegated chain, Delegated Guardians run full nodes and watch the chain themselves, while Canonical Guardians trust the delegate quorum before signing. The final VAA is still a standard 13-of-19 multisig regardless.
## Heartbeat
Each Guardian will issue a `heartbeat` on a 15-second interval to signal that it is still running and convey details about its identity, uptime, version, and the status of the connected nodes.
You can view the heartbeats on the [Wormhole dashboard](https://wormhole-foundation.github.io/wormhole-dashboard/#/?endpoint=Mainnet){target=\_blank}.
## Observation
An Observation is a data structure describing a message emitted by the Core Contract and noticed by the Guardian node.
## Relayer
A relayer is any process that delivers VAAs to a destination.
## Sequence
A nonce, strictly increasing, which is tracked by the Wormhole Core Contract and unique to the emitter chain and address.
## Spy
A Spy is a daemon that eavesdrops on the messages passed between Guardians, typically to track VAAs as they get signed.
## VAA
[Verifiable Action Approvals](/docs/protocol/infrastructure/vaas/){target=\_blank} (VAAs) are the base data structure in the Wormhole ecosystem. They contain emitted messages along with information such as what contract emitted the message.
## Validator
A daemon configured to monitor a blockchain node and observe messages emitted by the Wormhole contracts.
---
Page Title: Guardians
- Resolved Markdown: https://wormhole.com/docs/ai/pages/protocol-infrastructure-guardians.md
- Canonical (HTML): https://wormhole.com/docs/protocol/infrastructure/guardians/
- Summary: Explore Wormhole's Guardian Network, a decentralized system for secure, scalable cross-chain communication across various blockchain ecosystems.
- Word Count: 1598; Token Estimate: 2170
# Guardians
Wormhole relies on a set of 19 distributed nodes called Guardians that monitor the state on several blockchains. The current Guardian set can be seen in the [Dashboard](https://wormhole-foundation.github.io/wormhole-dashboard/#/?endpoint=Mainnet){target=\_blank}. Depending on the chain's operational configuration, messages may be observed directly by all Guardians or by a delegated subset of Guardians. Regardless of how observations are collected, all [Verifiable Action Approvals](/docs/protocol/infrastructure/vaas/){target=\_blank} (VAAs) are ultimately produced as standard 13-of-19 multisignature attestations, preserving full compatibility with existing contracts and integrators.
Guardians fulfill their role in the messaging protocol as follows:
1. Guardians observe messages and sign the corresponding payloads in isolation from the other Guardians.
- On chains where all Guardians perform direct on-chain observation, each Guardian independently observes events directly.
- On delegated chains, a subset performs direct observation and broadcasts a `DelegateObservation` to the rest of the network.
2. Once a sufficient delegate quorum is reached or once Guardians independently observe the event, signatures accumulate until the required 13-of-19 quorum is achieved.
3. This multisig represents proof that a majority of the Wormhole network has observed and agreed upon a state.
## Guardian Sets and Delegation
The Guardian network comprises 19 Guardians. However, some chains may utilize delegated subsets. Some chains (such as Ethereum and Solana) are secured by all 19 Guardians. Each Guardian runs a full node and independently observes on-chain events. Other chains may be secured by a delegated subset of Guardians based on chain activity. Chains that are not explicitly delegated, default to full Guardian Set observation, meaning all 19 Guardians observe directly.
For these chains:
- A configured delegated subset of the 19 Guardians performs direct on-chain observation.
- Delegated Guardians broadcast a `SignedDelegateObservation` gossip message.
- Canonical Guardians wait until a delegate quorum is reached before signing.
- A standard 13-of-19 VAA is ultimately produced.
This design provides operational flexibility while maintaining compatibility with the existing Wormhole contract stack.
### Delegated Observation Flow
The following flow shows how a subset of Guardians directly observes events on those chains and broadcasts a `SignedDelegateObservation` message over the Guardian gossip network. Canonical Guardians wait until the configured delegate quorum is reached before proceeding with the normal signing process. The final result is still a standard 13-of-19 VAA, fully compatible with existing smart contracts and integrations.
```mermaid
sequenceDiagram
participant CB as CoreBridge
participant DG as DelegatedGuardian
participant G as Gossip network
participant CG as CanonicalGuardian 1
participant CG2 as CanonicalGuardian 2
CB-->>DG: LogMessagePublished
DG->>DG: Watch & verify
alt DelegatedSet chain
DG-->>G: Broadcast SignedDelegateObservation
G-->>CG: Receive SignedDelegateObservation
G-->>CG2: Receive SignedDelegateObservation
loop Wait for delegate quorum
CG->>CG: Mark message valid
CG2->>CG2: Mark message valid
end
end
note over CG,CG2: Standard signing flow continues
```
### Delegate Quorum Safeguards
On delegated chains, Canonical Guardians will not sign a message until a delegate quorum has been reached. This prevents a minority of Delegated Guardians from lowering the effective security threshold of a chain. For example, if a chain is configured as 7-of-9 Delegated Guardians, Canonical Guardians will only sign after at least 7 delegate observations agree. Once a delegate quorum is satisfied, Canonical Guardians sign to produce a standard 13-of-19 VAA.
## Guardian Network
The Guardian Network functions as Wormhole's decentralized oracle, ensuring secure, cross-chain interoperability. Learning about this critical element of the Wormhole ecosystem will help you better understand the protocol.
The Guardian Network is designed to help Wormhole deliver on five key principles:
- **Decentralization**: Control of the network is distributed across many parties.
- **Modularity**: Independent components (e.g., oracle, relayer, applications) ensure flexibility and upgradeability.
- **Chain agnosticism**: Supports EVM, Solana, and other blockchains without relying on a single network.
- **Scalability**: Can handle large transaction volumes and high-value transfers.
- **Upgradeable**: Can change the implementation of its existing modules without breaking integrators to adapt to changes in decentralized computing.
The following sections explore each principle in detail.
### Decentralization
Decentralization remains the core concern for interoperability protocols. Earlier solutions were fully centralized, and even newer models often rely on a single entity or just one or two actors, creating low thresholds for collusion or failure.
Two common approaches to decentralization have notable limitations:
- **Proof-of-Stake (PoS)**: While PoS is often seen as a go-to model for decentralization, it is not well-suited for a network that verifies many blockchains and does not run its own smart contracts. Its security in this context is unproven, and it introduces complexities that make other design goals harder to achieve.
- **Zero-Knowledge Proofs (ZKPs)**: ZKPs offer a trustless and decentralized approach, but the technology is still early-stage. On-chain verification is often too computationally expensive—especially on less capable chains—so a multisig-based fallback is still required for practical deployment.
In the current DeFi landscape, most major blockchains are secured by a small group of validator companies. Only a limited number of companies worldwide have the expertise and capital to run high-performance validators.
If a protocol could unite many of these top validator companies into a purpose-built consensus mechanism designed for interoperability, it would likely offer better performance and security than a token-incentivized network. The key question is: how many of them could Wormhole realistically involve?
To answer that, consider these key constraints and design decisions:
- **Threshold signatures allow flexibility, but**: With threshold signatures, in theory, any number of validators could participate. However, threshold signatures are not yet widely supported across blockchains. Verifying them is expensive and complex, especially in a chain-agnostic system.
- **t-Schnorr multisig is more practical**: Wormhole uses [t-Schnorr multisig](https://en.wikipedia.org/wiki/Schnorr_signature){target=\_blank}, which is broadly supported and relatively inexpensive to verify. However, verification costs scale linearly with the number of signers, so the size of the validator set needs to be deliberately specified.
- **19 Guardians form the canonical set**: A set of 19 participants presents ample opportunity for both decentralization and efficiency. A quorum of 13 signatures is required to produce a valid VAA.
- **Per-chain delegated thresholds**: On delegated chains, a delegated subset of Guardians may be configured with an optimized observation threshold. Canonical Guardians wait for delegate quorum before contributing their signatures, ensuring that the effective security threshold for a chain cannot be reduced below its configured level.
- **Security through reputation, not tokens**: Wormhole relies on a network of established validator companies instead of token-based incentives. These 19 Guardians are among the most trusted operators in the industry — real entities with a track record, not anonymous participants.
This forms the foundation for a purpose-built Proof-of-Authority (PoA) consensus model, where each Guardian has an equal stake. As threshold signatures gain broader support, the set can expand. Once ZKPs become widely viable, the network can evolve into a fully trustless system.
### Modularity
Wormhole is designed with simple components that are very good at a single function. Separating security and consensus (Guardians) from message delivery ([Executor](/docs/protocol/infrastructure/relayers/executor-framework/){target=\_blank}) allows for the flexibility to change or upgrade one component without disrupting the others.
### Chain Agnosticism
Today, Wormhole supports a broader range of ecosystems than any other interoperability protocol because it uses simple tech (t-schnorr signatures), an adaptable, heterogeneous relayer model, and a robust validator network. Wormhole can expand to new ecosystems as quickly as a [Core Contract](/docs/protocol/infrastructure/core-contracts/){target=\_blank} can be developed for the smart contract runtime.
### Scalability
Wormhole scales well, as demonstrated by its ability to handle substantial total value locked (TVL) and transaction volume even during tumultuous events.
On chains where all Guardians perform direct on-chain observation, each Guardian runs a full node and independently observes events. This requirement can be computationally heavy to set up; however, once all the full nodes are running, the Guardian Network's actual computation needs become lightweight.
On delegated chains, only the delegated subset of Guardians runs full nodes. Canonical Guardians rely on delegate observations broadcast through the gossip network and wait for delegate quorum before signing.
This reduces operational overhead while preserving the security model of the network. Performance is generally limited by the speed of the underlying blockchains, not the Guardian Network itself.
### Upgradeable
Wormhole is designed to adapt and evolve in the following ways:
- **Per-chain security configuration**: The Delegated Guardian configuration is managed via governance through the `WormholeDelegatedGuardians` contract, allowing per-chain threshold adjustments without requiring upgrades to existing Core contracts.
- **Guardian Set expansion**: Future updates may introduce threshold signatures to allow for more Guardians in the set.
- **ZKP integration**: As Zero-Knowledge Proofs become more widely supported, the network can transition to a fully trustless model.
These principles combine to create a clear pathway towards a fully trustless interoperability layer that spans decentralized computing.
## Next Steps
- :octicons-book-16:{ .lg .middle } **Executor**
---
Learn about the Executor framework - a shared, permissionless system for executing cross-chain messages using standardized contracts and quotes.
[:custom-arrow: Learn About Executor](/docs/protocol/infrastructure/relayers/executor-framework/)
- :octicons-tools-16:{ .lg .middle } **Query Guardian Data**
---
Learn how to use Wormhole Queries to add real-time access to Guardian-attested on-chain data via a REST endpoint to your dApp, enabling secure cross-chain interactions and verifications.
[:custom-arrow: Build with Queries](/docs/products/queries/overview/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/ecosystem){target=\_blank}
---
Page Title: Integrate Connect into a React DApp Tutorial
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-connect-tutorials-react-dapp.md
- Canonical (HTML): https://wormhole.com/docs/products/connect/tutorials/react-dapp/
- Summary: Learn how to use Wormhole Connect to transfers tokens cross-chain seamlessly between Sui and Avalanche Fuji with this step-by-step guide.
- Word Count: 1340; Token Estimate: 2209
# Integrate Connect into a React DApp
:simple-github: [Source code on GitHub](https://github.com/wormhole-foundation/demo-basic-connect){target=\_blank}
In this tutorial, we'll explore how to integrate [Wormhole Connect](/docs/products/connect/overview/){target=\_blank} to enable cross-chain token transfers and interactions. Connect offers a simplified interface for developers to facilitate seamless token transfers between blockchains. Using Connect, you can easily bridge assets across multiple ecosystems without diving into the complex mechanics of cross-chain communication.
While this tutorial will guide you through the process using a specific blockchain as an example, the principles and steps outlined here can be applied to any [blockchain supported by Wormhole](/docs/products/connect/reference/support-matrix/){target=\_blank}. In this example, we'll work with Sui as our source blockchain and Avalanche Fuji as the destination blockchain.
## Prerequisites
To get started with Connect, we'll first need to set up a basic environment that allows for cross-chain token transfers.
Before starting this tutorial, ensure you have the following:
- [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm){target=\_blank} installed on your machine.
- A [Sui wallet](https://suiwallet.com/){target=\_blank} set up and ready for use.
- A [compatible wallet](https://support.avax.network/en/articles/5520938-what-are-the-official-avalanche-wallets){target=\_blank} for Avalanche Fuji, such as [MetaMask](https://metamask.io/){target=\_blank}.
- Testnet tokens for [Sui](https://docs.sui.io/guides/developer/getting-started/get-coins){target=\_blank} and [Fuji](https://core.app/tools/testnet-faucet/?subnet=c&token=c){target=\_blank} to cover gas fees.
## Set Up Connect for Sui Transfers
### Create a React Project
In this tutorial, we'll use [Next.js](https://nextjs.org/docs/app/getting-started){target=\_blank}, a popular framework built on top of React, to set up your app:
1. Open your terminal and run the following command to create a new React app:
```bash
npx create-next-app@latest connect-tutorial
```
We recommend enabling TypeScript and creating a `src/` directory during setup. Other options can be configured based on your preferences.
2. Navigate into the project directory:
```bash
cd connect-tutorial
```
### Install Connect
Next, install the Connect package as a dependency by running the following command inside your project directory. This tutorial uses the Connect version `5.1.1`:
```bash
npm install @wormhole-foundation/wormhole-connect@5.1.1
```
### Integrate Connect into the Application
Now, we need to modify the default `page.tsx` file to integrate Connect. We are going to use [version V1.0](/docs/products/connect/guides/upgrade/){target=\_blank} or later, make sure to check which version of Connect you are using. Open `src/app/page.tsx` and replace the content with the following code:
=== "JavaScript"
```js
'use client';
import WormholeConnect from '@wormhole-foundation/wormhole-connect';
const config = {
network: 'Testnet',
chains: ['Sui', 'Avalanche'],
};
const theme = {
mode: 'light',
primary: '#78c4b6',
};
export default function Home() {
return ;
}
```
=== "TypeScript"
```ts
'use client';
import WormholeConnect, {
type config,
WormholeConnectTheme,
} from '@wormhole-foundation/wormhole-connect';
export default function Home() {
const config: config.WormholeConnectConfig = {
network: 'Testnet',
chains: ['Sui', 'Avalanche'],
ui: {
title: 'SUI Connect TS Demo',
},
};
const theme: WormholeConnectTheme = {
mode: 'light',
primary: '#78c4b6',
};
return ;
}
```
- **Set `network` to `'Testnet'`**: This ensures that Connect uses the testnet environment.
- **Set `chains` to `['Sui', 'Avalanche']`**: Configures the app to allow transfers between Sui and Avalanche Fuji, the testnet for Avalanche.
### Customize Connect
To further customize Connect for your application, such as adjusting the UI, adding custom tokens, enabling Reown (formerly known as WalletConnect), or configuring specific chain settings, you can refer to the [Connect Configuration guide](/docs/products/connect/configuration/data/){target=\_blank}.
### Run the Application
Make sure you're in the root directory of your React app, and run the following command to start the application:
```bash
npm run dev
```
Now your React app should be up and running, and Connect should be visible on `http://localhost:3000/`. You should see the Connect component, which will include a UI for selecting networks and tokens for cross-chain transfers.
## Transfer Tokens from Sui to Fuji
Before transferring token ensure you have enough testnet SUI and Fuji tokens to cover the gas fees for the transfer.
To transfer tokens from Sui to Fuji in the Connect interface:
1. Select **Sui** as the source network, connect your Sui wallet, and choose **SUI** as the asset you wish to transfer.
2. Choose **Fuji** as the destination network and connect your wallet with the Fuji network.
3. Enter the amount of SUI tokens you wish to transfer.
{.half}
4. Choose to view other routes.
{.half}
5. Select the manual bridge option, which will require two transactions: one on the source chain (Sui) and one on the destination chain (Fuji).
!!! note
It is recommended to use the manual bridge option for this tutorial. The automatic bridge feature is currently undergoing improvements, while the manual bridge ensures that transfers complete successfully.
{.half}
6. Review and confirm the transfer on Sui. This will lock your tokens on the Sui chain.
{.half}
7. Follow the on-screen prompts to approve the transaction. You will be asked to sign with your Sui wallet.
{.half}
Once the transaction has been submitted, Connect will display the progress of the transfer. Monitor the status until you're prompted to complete the transaction on the destination chain. You can also track your transactions on [Wormholescan](https://wormholescan.io/#/?network=Testnet){target=\_blank}.
## Claim Tokens on Fuji
After the Sui transaction is complete, confirm the final transaction on Fuji by claiming the wrapped tokens. You will be asked to confirm the transaction with your Fuji wallet.
{.half}
Once confirmed, check your Fuji wallet to verify that the wrapped SUI tokens have been successfully received.
{.half}
## Resources
If you'd like to explore the complete project or need a reference while following this tutorial, you can find the entire codebase in the [Sui-Connect GitHub repository](https://github.com/wormhole-foundation/demo-basic-connect){target=\_blank}. The repository includes an integration of Connect in a React app for bridging tokens between the Sui and Fuji (Avalanche Testnet) networks.
## Conclusion
In this tutorial, you've gained hands-on experience with integrating Connect to enable cross-chain token transfers. You've learned to configure a React app for seamless interactions between Sui and Avalanche Fuji, providing users with the ability to bridge assets across chains with ease.
By following these steps, you've learned how to:
- Set up a React project tailored for cross-chain transfers.
- Install and configure Connect to support multiple blockchains.
- Implement a streamlined UI for selecting source and destination chains, connecting wallets, and initiating transfers.
- Execute a token transfer from Sui to Avalanche Fuji, monitoring each step and confirming the transaction on both networks.
With these tools and knowledge, you're now equipped to build powerful cross-chain applications using Connect, opening up possibilities for users to move assets across ecosystems securely and efficiently.
## Next Steps
- :octicons-tools-16:{ .lg .middle } **Build a Reimbursement App with Connect**
---
Master the core features of Connect by building a real-world reimbursement application on the Wormhole Dev Arena, a structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/courses/1bee7446-5ed5-814a-8177-e087a5d7a6bc){target=\_blank}
- :octicons-tools-16:{ .lg .middle } **Demo Tutorials Repository**
---
Looking for more hands-on tutorials? Check out the Wormhole Tutorial Demo repository on GitHub for additional examples.
[:custom-arrow: Explore the Demo Repository](https://github.com/wormhole-foundation/demo-tutorials){target=\_blank}
---
Page Title: Integrate Connect via CDN
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-connect-guides-hosted-version.md
- Canonical (HTML): https://wormhole.com/docs/products/connect/guides/hosted-version/
- Summary: Learn how to use Wormhole Connect via CDN in any JavaScript project using just a script tag with no React or backend setup required.
- Word Count: 342; Token Estimate: 621
# Integrate Connect via CDN
[Wormhole Connect](/docs/products/connect/overview/){target=\_blank} is a prebuilt UI component that makes it easy to transfer tokens across chains. You can integrate it into any website using either React or a hosted version served via [jsDelivr](https://www.jsdelivr.com/){target=\_blank}.
This guide focuses on using the hosted version—ideal for simpler setups or non-React environments. It includes everything you need to get started with just a few lines of code.
If you're using React, refer to the [Get Started with Connect](/docs/products/connect/get-started/){target=\_blank} guide.
## Install Connect
To install the [Connect npm package](https://www.npmjs.com/package/@wormhole-foundation/wormhole-connect){target=\_blank}, run the following command:
```bash
npm i @wormhole-foundation/wormhole-connect
```
## Add Connect to Your Project Using the Hosted Version
The hosted version uses pre-built packages (including React) served via jsDelivr from npm. To integrate it without using React directly, add the following to your JavaScript project:
```js
import { wormholeConnectHosted } from '@wormhole-foundation/wormhole-connect';
// Existing DOM element where you want to mount Connect
const container = document.getElementById('bridge-container');
if (!container) {
throw new Error("Element with id 'bridge-container' not found");
}
wormholeConnectHosted(container);
```
You can provide config and theme parameters in a second function argument:
```js
import { wormholeConnectHosted } from '@wormhole-foundation/wormhole-connect';
// Existing DOM element where you want to mount Connect
const container = document.getElementById('bridge-container');
if (!container) {
throw new Error("Element with id 'connect' not found");
}
wormholeConnectHosted(container, {
config: {
rpcs: {
// ...
},
},
theme: {
background: {
default: '#004547',
},
},
});
```
## Next Steps
Use the following guides to configure your Connect instance.
- :octicons-tools-16:{ .lg .middle } **Data Configuration**
---
Learn how to specify custom networks and RPC endpoints, integrate different bridging protocols, add new tokens, and more.
[:custom-arrow: View Data Configs](/docs/products/connect/configuration/data/)
- :octicons-tools-16:{ .lg .middle } **Theme Configuration**
---
Learn how to customize Connect's look and feel to match your application's branding.
[:custom-arrow: View Theme Configs](/docs/products/connect/configuration/theme/)
---
Page Title: Introduction to Wormhole
- Resolved Markdown: https://wormhole.com/docs/ai/pages/protocol-introduction.md
- Canonical (HTML): https://wormhole.com/docs/protocol/introduction/
- Summary: Wormhole is a protocol for seamless communication between blockchains, enabling cross-chain applications and integrations.
- Word Count: 885; Token Estimate: 1389
# Introduction to Wormhole
In the rapidly evolving landscape of blockchain technology, interoperability between different blockchains remains a significant challenge. Developers often face hurdles in creating applications that can seamlessly operate across multiple blockchains, limiting innovation and the potential of decentralized ecosystems.
Wormhole addresses this problem by providing a _generic message-passing_ protocol that enables secure and efficient communication between blockchains. By allowing data and asset transfers across various blockchain networks, Wormhole breaks down the walls that traditionally separate these ecosystems.
Wormhole is distinguished by its focus on robust security, scalability, and transparency. The protocol is supported by a decentralized network of validators that ensure the integrity of every cross-chain transaction. This, combined with Wormhole’s proven performance in real-world applications, gives developers a dependable platform to create and scale multichain applications confidently.
!!! note
The above is an oversimplified illustration of the protocol; details about the architecture and components are available on the [architecture page](/docs/protocol/architecture/){target=\_blank}.
Wormhole allows developers to leverage the strengths of multiple blockchain ecosystems without being confined to one. This means applications can benefit from the unique features of various networks—such as Solana's high throughput, Ethereum's security, and Cosmos's interoperability, while maintaining a unified, efficient user experience.
This page introduces the key concepts and components necessary to understand how Wormhole enables fast, secure, and scalable cross-chain communication.
## What Problems Does Wormhole Solve?
Interoperability is a critical challenge in the rapidly evolving blockchain landscape. Individual blockchains are often isolated, limiting the potential for integrated applications operating across multiple ecosystems. Wormhole solves this problem by enabling seamless communication between blockchains, allowing developers to create multichain applications that can leverage the unique features of each network.
Critical problems Wormhole addresses include:
- **Blockchain isolation**: Wormhole connects disparate blockchains, enabling the transfer of assets, data, and governance actions across networks.
- **Cross-chain complexity**: By abstracting the complexities of cross-chain communication, Wormhole makes it easier for developers to build and deploy cross-chain applications.
- **Security and decentralization**: Wormhole prioritizes security through a decentralized Guardian network that validates and signs messages, ensuring the integrity of cross-chain interactions.
## What Does Wormhole Offer?
Wormhole provides a suite of tools and protocols that support a wide range of use cases:
- **Cross-chain messaging**: Securely transfer arbitrary data between blockchains, enabling the development of cross-chain decentralized applications.
- **Asset transfers**: Facilitate the movement of tokens across supported chains with ease, powered by protocols built on Wormhole like [Portal](https://portalbridge.com/){target=\_blank}.
- **Developer tools**: Leverage Wormhole’s [TypeScript SDK](/docs/tools/typescript-sdk/get-started/){target=\_blank}, [Wormholescan](https://wormholescan.io/){target=\_blank}, and the [Wormholescan API](https://wormholescan.io/#/developers/api-doc){target=\_blank} and documentation to build and deploy cross-chain applications quickly and efficiently.
## What Isn't Wormhole?
- **Wormhole is _not_ a blockchain**: It acts as a communication layer that connects different blockchains, enabling them to interact without being a blockchain itself.
- **Wormhole is _not_ a token bridge**: While it facilitates token transfers, Wormhole also supports a wide range of cross-chain applications, making it much more versatile than a typical bridge.
## Use Cases of Wormhole
Consider the following examples of potential applications enabled by Wormhole:
- **Cross-chain exchange**: Using [Wormhole Connect](/docs/products/connect/overview/){target=\_blank}, developers can build exchanges that allow deposits from any Wormhole-connected chain, significantly increasing liquidity access.
- [**Cross-chain governance**](https://wormhole.com/blog/stake-for-governance-guide){target=\_blank}: Projects with communities spread across multiple blockchains can use Wormhole to relay votes from each chain to a designated governance chain, enabling unified decision-making through combined proposals.
- **Cross-chain game**: Games can be developed on a performant network like Solana, with rewards issued on another network, such as Ethereum.
## Explore
Discover more about the Wormhole ecosystem, components, and protocols:
- **[Architecture](/docs/protocol/architecture/){target=\_blank}**: Explore the components of the protocol.
- **[Protocol Specifications](https://github.com/wormhole-foundation/wormhole/tree/main/whitepapers){target=\_blank}**: Learn about the protocols built on top of Wormhole.
## Demos
Demos offer more realistic implementations than tutorials:
- **[Wormhole Scaffolding](https://github.com/wormhole-foundation/wormhole-scaffolding){target=\_blank}**: Quickly set up a project with the Scaffolding repository.
- **[Demo Tutorials](https://github.com/wormhole-foundation/demo-tutorials){target=\_blank}**: Explore various demos that showcase Wormhole's capabilities across different blockchains.
!!! note
Wormhole Integration Complete?
Let us know so we can list your project in our ecosystem directory and introduce you to our global, multichain community!
**[Reach out now!](https://forms.clickup.com/45049775/f/1aytxf-10244/JKYWRUQ70AUI99F32Q){target=\_blank}**
## Supported Networks by Product
Wormhole supports a growing number of blockchains. Check out the [Supported Networks by Product](/docs/products/reference/supported-networks/){target=\_blank} page to see which networks are supported for each Wormhole product.
## Next Steps
- :octicons-book-16:{ .lg .middle } **Architecture Overview**
---
Get an overview of Wormhole's architecture, detailing key on-chain and off-chain components like the Core Contract, Guardian Network, and relayers.
[:custom-arrow: Learn More](/docs/protocol/architecture/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/){target=\_blank}
---
Page Title: Messaging Overview
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-messaging-overview.md
- Canonical (HTML): https://wormhole.com/docs/products/messaging/overview/
- Summary: With Wormhole Messaging, you can enable secure, multichain communication, build multichain apps, sync data, and coordinate actions across blockchains.
- Word Count: 615; Token Estimate: 1238
# Messaging Overview
Wormhole Messaging is the core protocol of the Wormhole ecosystem—a generic, multichain message-passing layer that enables secure, fast communication between blockchains. It solves the critical problem of blockchain isolation by allowing data and assets to move freely across networks, empowering developers to build true multichain applications.
## Key Features
- **Multichain messaging**: Send arbitrary data between blockchains, enabling xDapps, governance actions, or coordination across ecosystems.
- **Decentralized validation**: A network of independent [Guardians](/docs/protocol/infrastructure/guardians/){target=\_blank} observes and signs multichain messages, producing [Verifiable Action Approvals (VAAs)](/docs/protocol/infrastructure/vaas/){target=\_blank} that ensure integrity.
- **Composable architecture**: Works with smart contracts, token bridges, or decentralized applications, providing a flexible foundation for multichain use cases.
## How It Works
The messaging flow consists of several core components:
1. **Source chain (emitter contract)**: A contract emits a message by calling the Wormhole [Core Contract](/docs/protocol/infrastructure/core-contracts/){target=\_blank} on the source chain.
2. **Guardian Network**: [Guardians](/docs/protocol/infrastructure/guardians/){target=\_blank} observe the message, validate it, and generate a signed [VAA](/docs/protocol/infrastructure/vaas/){target=\_blank}.
3. **Relayers (Executor)**: Off-chain or on-chain relayers transport the VAA to the destination chain. In Wormhole’s architecture, this role is fulfilled by the [**Executor**](/docs/products/messaging/concepts/executor-overview/){target=\_blank}, a permissionless, shared framework that standardizes message delivery across all supported chains.
4. **Target chain (recipient contract)**: The [Core Contract](/docs/protocol/infrastructure/core-contracts/){target=\_blank} on the destination chain verifies the VAA and triggers the specified application logic.
## Use Cases
Wormhole Messaging enables a wide range of multichain applications. Below are common use cases and the Wormhole stack components you can use to build them.
- **Borrowing and Lending Across Chains (e.g., [Folks Finance](https://wormhole.com/case-studies/folks-finance){target=\_blank})**
- **[Messaging](/docs/products/messaging/get-started/){target=\_blank}**: Coordinate actions across chains.
- **[Native Token Transfers](/docs/products/token-transfers/native-token-transfers/overview/){target=\_blank}**: Transfer collateral as native assets.
- **Oracle Networks (e.g., [Pyth](https://wormhole.com/case-studies/pyth){target=\_blank})**
- **[Messaging](/docs/products/messaging/get-started/){target=\_blank}**: Relay verified data.
- **Gas Abstraction**
- **[Messaging](/docs/products/messaging/get-started/){target=\_blank}**: Coordinate gas logic.
- **[Native Token Transfers](/docs/products/token-transfers/native-token-transfers/overview/){target=\_blank}**: Handle native token swaps.
- **Bridging Intent Library**
- **[Messaging](/docs/products/messaging/get-started/){target=\_blank}**: Dispatch and execute intents.
- **[Settlement](/docs/products/settlement/overview/){target=\_blank}**: Execute user-defined bridging intents.
- **Decentralized Social Platforms (e.g., [Chingari](https://chingari.io/){target=\_blank})**
- **[Messaging](/docs/products/messaging/get-started/){target=\_blank}**: Facilitate decentralized interactions.
- **[Wrapped Token Transfers](/docs/products/token-transfers/wrapped-token-transfers/overview/){target=\_blank}**: Enable tokenized rewards.
## Next Steps
Follow these steps to work with Wormhole Messaging:
- :octicons-tools-16:{ .lg .middle } **Get Started with Messaging**
---
Use the core protocol to publish a multichain message and return transaction info with VAA identifiers.
[:custom-arrow: Get Started](/docs/products/messaging/get-started/)
- :octicons-book-16:{ .lg .middle } **Executor Overview**
---
Learn how to use Executors to automate message handling and application logic across chains.
[:custom-arrow: Learn about Executors](/docs/protocol/infrastructure/relayers/executor-framework/)
- :octicons-tools-16:{ .lg .middle } **Solana Shim Programs**
---
For lower-cost, efficient integration with Core Bridge on Solana, consider using shim programs:
[:custom-arrow: Learn about Solana Shims](/docs/products/messaging/concepts/solana-shim/)
[:custom-arrow: Emit Messages with the Emission Shim](/docs/products/messaging/guides/solana-shims/sol-emission/)
[:custom-arrow: Verify VAAs with the Verification Shim](/docs/products/messaging/guides/solana-shims/sol-verification/)
---
Page Title: Relayers Overview
- Resolved Markdown: https://wormhole.com/docs/ai/pages/protocol-infrastructure-relayers-relayer.md
- Canonical (HTML): https://wormhole.com/docs/protocol/infrastructure/relayers/relayer/
- Summary: Discover the role of relayers in the Wormhole network, including client-side and automated relaying via the Executor framework, for secure cross-chain communication.
- Word Count: 810; Token Estimate: 1145
# Overview
!!!warning
The Wormhole Standard Relayer is being deprecated. Developers are strongly encouraged to [migrate to the Executor framework](/docs/protocol/infrastructure/relayers/executor-vs-sr/){target=\_blank}.
This page introduces relayers in the Wormhole network and explains their role, available approaches, and the trade-offs involved in delivering cross-chain messages.
Relayers are the entities responsible for submitting signed [Verified Action Approvals (VAAs)](/docs/protocol/infrastructure/vaas/){target=\_blank} to destination chains, providing message delivery and automation. At the same time, Guardian signatures and on-chain verification ensure that relayers cannot tamper with message contents and only influence when a VAA is delivered.
Wormhole supports both manual (client-side) and automated relaying. Automated relaying is implemented using the [Executor framework](/docs/protocol/infrastructure/relayers/executor-framework/){target=\_blank}, Wormhole's decentralized relayer infrastructure.
## Fundamentals
Relayers act as delivery mechanisms for cross-chain messages. Their responsibility is to observe signed VAAs and submit them to destination chain contracts for on-chain verification and execution. Guardian signatures and on-chain verification logic define what is executed, while relayers provide availability and automation by ensuring messages reach their destination.
- **Anyone can relay a message**: The Guardian Network broadcasts signed VAAs publicly, allowing any entity to submit them to destination chain contracts. Guardian signatures provide universal verifiability, ensuring relaying is permissionless. If one relayer is unavailable, another party can submit the same VAA to complete delivery.
- **Security is in the VAA**: Guardian signatures authenticate message contents and execution parameters. Contracts should rely only on signed VAAs and on-chain state, not on off-chain data supplied by relayers. As a result, relayers can affect delivery timing, but not message correctness or security, making relaying trustless.
- **User experience vs. infrastructure**: Relayers automate cross-chain delivery to improve user experience, but introduce considerations around fees. Developers can choose between client-side relaying or the Executor framework depending on their needs.
## Manual vs. Automated Relaying
When integrating Wormhole messaging, applications can use either manual (client-side) relaying or automated relaying. The difference lies in who is responsible for delivering the VAA to the destination chain.
- **Manual relaying (client-side)**: The user or client application (e.g., a dApp or wallet) is responsible for carrying out all cross-chain steps. After an action on the source chain produces a VAA, the user must fetch the VAA (e.g., via a Wormhole API or explorer) and submit it in a transaction on the destination chain. No backend infrastructure is required, and costs are limited to destination-chain transaction fees. However, this approach requires multiple user interactions and funds on each chain involved, making it best suited for testing, demos, and MVPs rather than production applications.
- **Automated relaying**: Cross-chain delivery is handled automatically by a relayer service or network instead of the end user. From the user's perspective, the message is delivered to the destination chain without manual intervention, enabling a smoother, one-step experience. With the [Executor framework](/docs/protocol/infrastructure/relayers/executor-framework/){target=\_blank}, applications can leverage Wormhole's decentralized relayer infrastructure to request automated delivery, without running a backend service. This reduces operational complexity at the cost of service fees, while significantly improving user experience.
Choosing between manual and automated relaying depends on the application's requirements. If the integrator prioritizes convenience, automated relaying provides a superior experience.
## Executor
The Executor is a permissionless, next-generation relaying framework that enables anyone to act as a relayer through a request-and-quote model, with support for multichain delivery and flexible pricing.
At a high level, the Executor consists of:
- A lightweight, stateless [Executor contract](/docs/protocol/infrastructure/relayers/executor-framework/#executor-contract){target=\_blank} deployed by Wormhole on supported chains
- A permissionless network of off-chain [relay providers](/docs/protocol/infrastructure/relayers/executor-framework/#relay-provider){target=\_blank} that fulfill delivery requests
Applications request automated delivery by submitting an execution request to the Executor contract, along with a signed fee quote obtained off-chain from a relay provider. Relay providers monitor these requests and deliver the corresponding VAAs to destination chains for on-chain execution, extending relaying functionality beyond EVM-only environments.
The Executor does not change Wormhole’s security model. Guardian signatures and on-chain verification enforce message integrity and execution correctness, while relay providers compete on pricing and availability. This creates a decentralized marketplace for relaying rather than a single relayer service.
## Next Steps
- :octicons-book-16:{ .lg .middle } **Migrate to Executor**
---
Understand the key differences between the Executor framework and the Standard Relayer, and find guidance for migrating existing integrations.
[:custom-arrow: Migrate to Executor](/docs/protocol/infrastructure/relayers/executor-vs-sr/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/ecosystem){target=\_blank}
---
Page Title: Replace Outdated Signatures in VAAs
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-messaging-tutorials-replace-signatures.md
- Canonical (HTML): https://wormhole.com/docs/products/messaging/tutorials/replace-signatures/
- Summary: Learn how to fetch, validate, and replace outdated signatures in Wormhole VAAs using Wormholescan and the Wormhole SDK to ensure seamless processing.
- Word Count: 4514; Token Estimate: 9168
# Replace Outdated Signatures in VAAs
:simple-github: [Source code on GitHub](https://github.com/wormhole-foundation/demo-vaa-signature-replacement){target=\_blank}
Cross-chain transactions in Wormhole rely on [Verifiable Action Approvals (VAAs)](/docs/protocol/infrastructure/vaas/){target=\_blank}, which contain signatures from a trusted set of validators called [Guardians](/docs/protocol/infrastructure/guardians/){target=\_blank}. These signatures prove that the network approved an action, such as a token transfer.
However, the set of Guardians changes over time. If a user generates a transaction and waits too long before redeeming it, the Guardian set may have already changed. This means the VAA will contain outdated signatures from Guardians, who are no longer part of the network, causing the transaction to fail.
Instead of discarding these VAAs, we can fetch updated signatures and replace the outdated ones to ensure smooth processing.
In this tutorial, you'll build a script from scratch to:
- Fetch a VAA from [Wormholescan](https://wormholescan.io/#/developers/api-doc){target=\_blank}.
- Validate its signatures against the latest Guardian set.
- Replace outdated signatures using the [Wormhole SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts){target=\_blank}.
- Output a valid VAA ready for submission.
By the end, you'll have a script that ensures VAAs remain valid and processable, avoiding transaction failures.
## Prerequisites
Before you begin, ensure you have the following:
- [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm){target=\_blank} installed on your machine.
- [TypeScript](https://www.typescriptlang.org/download/){target=\_blank} installed globally.
## Project Setup
In this section, you will create the directory, initialize a Node.js project, install dependencies, and configure TypeScript.
1. **Create the project**: Set up the directory and navigate into it.
```bash
mkdir wormhole-scan-api-demo
cd wormhole-scan-api-demo
```
2. **Initialize a Node.js project**: Generate a `package.json` file.
```bash
npm init -y
```
3. **Set up TypeScript**: Create a `tsconfig.json` file.
```bash
touch tsconfig.json
```
Then, add the following configuration:
```json title="tsconfig.json"
{
"compilerOptions": {
"target": "es2016",
"module": "commonjs",
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"strict": true,
"skipLibCheck": true
}
}
```
4. **Install dependencies**: Add the required packages. This tutorial uses the SDK version `4.14.1`.
```bash
npm install @wormhole-foundation/sdk@4.14.1 axios web3 tsx @types/node
```
- **`@wormhole-foundation/sdk`**: Handles VAAs and cross-chain interactions.
- **`axios`**: Makes HTTP requests to the Wormholescan API.
- **`web3`**: Interacts with Ethereum transactions and contracts.
- **`tsx`**: Executes TypeScript files without compilation.
- **`@types/node`**: Provides Node.js type definitions.
5. **Create the project structure**: Set up the required directories and files.
```bash
mkdir -p src/config && touch src/config/constants.ts src/config/layouts.ts
mkdir -p src/helpers && touch src/helpers/vaaHelper.ts
mkdir -p src/scripts && touch scripts/replaceSignatures.ts
```
- **`src/config/*`**: Stores public configuration variables and layouts for serializing and deserializing data structures.
- **`src/helpers/*`**: Contains utility functions.
- **`src/scripts/*`**: Contains scripts for fetching and replacing signatures.
6. **Set variables**: Define key constants in `src/config/constants.ts`.
```bash title="src/config/constants.ts"
export const RPC = 'https://ethereum-rpc.publicnode.com';
export const ETH_CORE =
'0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B'.toLowerCase();
export const WORMHOLESCAN_API = 'https://api.wormholescan.io/v1';
export const LOG_MESSAGE_PUBLISHED_TOPIC =
'0x6eb224fb001ed210e379b335e35efe88672a8ce935d981a6896b27ffdf52a3b2';
export const TXS = [
'0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367',
'0x3c989a6bb40dcd4719453fbe7bbac420f23962c900ae75793124fc9cc614368c',
];
```
- **`RPC`**: Endpoint for interacting with an Ethereum RPC node.
- **`ETH_CORE`**: [Wormhole's Core Contract address on Ethereum](/docs/products/reference/contract-addresses/#core-contracts){target=\_blank} responsible for verifying VAAs.
- **`WORMHOLESCAN_API`**: Base URL for querying the Wormholescan API to fetch VAA data and Guardian sets.
- **`LOG_MESSAGE_PUBLISHED_TOPIC`**: The event signature hash for `LogMessagePublished`, a Wormhole contract event that signals when a VAA has been emitted. This is used to identify relevant logs in transaction receipts.
- **`TXS`**: List of example transaction hashes that will be used for testing.
7. **Define data structure for working with VAAs**: Specify the ABI for the Wormhole Core Contract's `parseAndVerifyVM` function, which parses and verifies VAAs. Defining the data structure, also referred to as a [layout](/docs/tools/typescript-sdk/guides/sdk-layout/){target=\_blank}, for this function ensures accurate decoding and validation of VAAs.
```typescript title="src/config/layouts.ts"
export const PARSE_AND_VERIFY_VM_ABI = {
inputs: [{ internalType: 'bytes', name: 'encodedVM', type: 'bytes' }],
name: 'parseAndVerifyVM',
outputs: [
{
components: [
{ internalType: 'uint8', name: 'version', type: 'uint8' },
{ internalType: 'uint32', name: 'timestamp', type: 'uint32' },
{ internalType: 'uint32', name: 'nonce', type: 'uint32' },
{ internalType: 'uint16', name: 'emitterChainId', type: 'uint16' },
{ internalType: 'bytes32', name: 'emitterAddress', type: 'bytes32' },
{ internalType: 'uint64', name: 'sequence', type: 'uint64' },
{ internalType: 'uint8', name: 'consistencyLevel', type: 'uint8' },
{ internalType: 'bytes', name: 'payload', type: 'bytes' },
{ internalType: 'uint32', name: 'guardianSetIndex', type: 'uint32' },
{
components: [
{ internalType: 'bytes32', name: 'r', type: 'bytes32' },
{ internalType: 'bytes32', name: 's', type: 'bytes32' },
{ internalType: 'uint8', name: 'v', type: 'uint8' },
{ internalType: 'uint8', name: 'guardianIndex', type: 'uint8' },
],
internalType: 'struct Structs.Signature[]',
name: 'signatures',
type: 'tuple[]',
},
{ internalType: 'bytes32', name: 'hash', type: 'bytes32' },
],
internalType: 'struct Structs.VM',
name: 'vm',
type: 'tuple',
},
{ internalType: 'bool', name: 'valid', type: 'bool' },
{ internalType: 'string', name: 'reason', type: 'string' },
],
stateMutability: 'view',
type: 'function',
};
```
## Create VAA Handling Functions
In this section, we'll create a series of helper functions in the `src/helpers/vaaHelper.ts` file that will retrieve and verify VAAs and fetch and replace outdated Guardian signatures to generate a correctly signed VAA.
To get started, import the necessary dependencies:
```typescript title="src/helpers/vaaHelper.ts"
import axios from 'axios';
import { eth } from 'web3';
import {
deserialize,
serialize,
VAA,
Signature,
} from '@wormhole-foundation/sdk';
import {
RPC,
ETH_CORE,
LOG_MESSAGE_PUBLISHED_TOPIC,
WORMHOLESCAN_API,
} from '../config/constants';
import { PARSE_AND_VERIFY_VM_ABI } from '../config/layouts';
```
### Fetch a VAA ID from a Transaction
To retrieve a VAA, we first need to get its VAA ID from a transaction hash. This ID allows us to fetch the full VAA later.
The VAA ID is structured as follows:
```bash
chain/emitter/sequence
```
- **`chain`**: The [Wormhole chain ID](/docs/products/reference/chain-ids/){target=\_blank} (Ethereum is 2).
- **`emitter`**: The contract address that emitted the VAA.
- **`sequence`**: A unique identifier for the event.
We must assemble the ID correctly since this is the format the Wormholescan API expects when querying VAAs.
Follow the below steps to process the transaction logs and construct the VAA ID:
1. **Get the transaction receipt**: Iterate over the array of transaction hashes and fetch the receipt to access its logs.
2. **Find the Wormhole event**: Iterate over the transaction logs and check for events emitted by the Wormhole Core contract. Look specifically for `LogMessagePublished` events, which indicate a VAA was created.
3. **Extract the emitter and sequence number**: If a matching event is found, extract the emitter address from `log.topics[1]` and remove the `0x` prefix. Then, the sequence number from `log.data` is extracted, converting it from hex to an integer.
4. **Construct the VAA ID**: Format the extracted data in `chain/emitter/sequence` format.
```typescript title="src/helpers/vaaHelper.ts"
export async function fetchVaaId(txHashes: string[]): Promise {
const vaaIds: string[] = [];
for (const tx of txHashes) {
try {
const result = (
await axios.post(RPC, {
jsonrpc: '2.0',
id: 1,
method: 'eth_getTransactionReceipt',
params: [tx],
})
).data.result;
if (!result)
throw new Error(`Unable to fetch transaction receipt for ${tx}`);
for (const log of result.logs) {
if (
log.address === ETH_CORE &&
log.topics?.[0] === LOG_MESSAGE_PUBLISHED_TOPIC
) {
const emitter = log.topics[1].substring(2);
const seq = BigInt(log.data.substring(0, 66)).toString();
vaaIds.push(`2/${emitter}/${seq}`);
}
}
} catch (error) {
console.error(`Error processing ${tx}:`, error);
}
}
return vaaIds;
}
```
???- code "Try it out: VAA ID retrieval"
If you want to try out the function before moving forward, create a test file inside the `test` directory:
1. Create the directory and file:
```bash
mkdir -p test
touch test/fetchVaaId.run.ts
```
2. Add the function call:
```typescript title="test/fetchVaaId.run.ts"
import { fetchVaaId } from '../src/helpers/vaaHelper';
import { TXS } from '../src/config/constants';
const testFetchVaaId = async () => {
for (const tx of TXS) {
const vaaIds = await fetchVaaId([tx]);
if (vaaIds.length > 0) {
console.log(`Transaction: ${tx}`);
vaaIds.forEach((vaaId) => console.log(`VAA ID: ${vaaId}`));
} else {
console.log(`No VAA ID found for transaction: ${tx}`);
}
}
};
testFetchVaaId();
```
3. Run the script:
```bash
npx tsx test/fetchVaaId.run.ts
```
If successful, the output will be:
npx tsx test/fetchVaaId.run.ts
Transaction: 0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367
VAA ID: 2/0000000000000000000000003ee18b2214aff97000d974cf647e7c347e8fa585/164170
If no VAA ID is found, the script will log an error message.
### Fetch the Full VAA
Now that you have the VAA ID, we can use it to fetch the full VAA payload from the Wormholescan API. This payload contains the VAA bytes, which will later be used for signature validation.
Open `src/helpers/vaaHelper.ts` and create the `fetchVaa()` function to iterate through VAA IDs and extract the `vaaBytes` payload.
```typescript title="src/helpers/vaaHelper.ts"
export async function fetchVaa(
vaaIds: string[]
): Promise<{ id: string; vaaBytes: string }[]> {
const results: { id: string; vaaBytes: string }[] = [];
for (const id of vaaIds) {
try {
const response = await axios.get(`${WORMHOLESCAN_API}/signed_vaa/${id}`);
const vaaBytes = response.data.vaaBytes;
results.push({ id, vaaBytes });
} catch (error) {
console.error(`Error fetching VAA for ${id}:`, error);
}
}
return results;
}
```
???- code "Try it out: VAA retrieval"
If you want to try the function before moving forward, create a script inside the `test` directory
1. Create the script file:
```bash
touch test/fetchVaa.run.ts
```
2. Add the function call:
```typescript title="test/fetchVaa.run.ts"
import { fetchVaaId, fetchVaa } from '../src/helpers/vaaHelper';
import { TXS } from '../src/config/constants';
const testFetchVaa = async () => {
for (const tx of TXS) {
const vaaIds = await fetchVaaId([tx]);
if (vaaIds.length === 0) {
console.log(`No VAA ID found for transaction: ${tx}`);
continue;
}
for (const vaaId of vaaIds) {
const vaaBytes = await fetchVaa([vaaId]);
console.log(
`Transaction: ${tx}\nVAA ID: ${vaaId}\nVAA Bytes: ${
vaaBytes.length > 0 ? vaaBytes[0].vaaBytes : 'Not found'
}`
);
}
}
};
testFetchVaa();
```
3. Run the script:
```bash
npx tsx test/fetchVaa.run.ts
```
If successful, the output will be:
npx tsx test/fetchVaa.run.ts
Transaction: 0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367
VAA Bytes: AQAAAAMNANQSwD/HRPcKp7Yxypl1ON8dZeMBzgYJrd2KYz6l9Tq9K9fj72fYJgkMeMaB9h...
If no VAA is found, the script will log an error message.
### Validate VAA Signatures
Now, we need to verify its validity. A VAA is only considered valid if it contains signatures from currently active Guardians and is correctly verified by the Wormhole Core contract.
Open `src/helpers/vaaHelper.ts` and add the `checkVaaValidity()` function. This function verifies whether a VAA is valid by submitting it to an Ethereum RPC node and checking for outdated signatures.
Follow these steps to implement the function:
1. **Prepare the VAA for verification**: Construct the VAA payload in a format that can be sent to the Wormhole Core contract.
2. **Send an `eth_call` request**: Submit the VAA to an Ethereum RPC node, calling the `parseAndVerifyVM` function on the Wormhole Core contract.
3. **Decode the response**: Check whether the VAA is valid. If it contains outdated signatures, further action will be required to replace them.
```typescript title="src/helpers/vaaHelper.ts"
export async function checkVaaValidity(vaaBytes: string) {
try {
const vaa = Buffer.from(vaaBytes, 'base64');
vaa[4] = 4; // Set guardian set index to 4
const result = (
await axios.post(RPC, {
jsonrpc: '2.0',
id: 1,
method: 'eth_call',
params: [
{
from: null,
to: ETH_CORE,
data: eth.abi.encodeFunctionCall(PARSE_AND_VERIFY_VM_ABI, [
`0x${vaa.toString('hex')}`,
]),
},
'latest',
],
})
).data.result;
const decoded = eth.abi.decodeParameters(
PARSE_AND_VERIFY_VM_ABI.outputs,
result
);
console.log(
`${decoded.valid ? '✅' : '❌'} VAA Valid: ${decoded.valid}${
decoded.valid ? '' : `, Reason: ${decoded.reason}`
}`
);
return { valid: decoded.valid, reason: decoded.reason };
} catch (error) {
console.error(`Error checking VAA validity:`, error);
return { valid: false, reason: 'RPC error' };
}
}
```
???- code "Try it out: VAA Validity"
If you want to try the function before moving forward, create a script inside the `test` directory
1. Create the script file:
```bash
touch test/checkVaaValidity.run.ts
```
2. Add the function call:
```typescript title="test/checkVaaValidity.run.ts"
import {
fetchVaaId,
fetchVaa,
checkVaaValidity,
} from '../src/helpers/vaaHelper';
import { TXS } from '../src/config/constants';
const testCheckVaaValidity = async () => {
for (const tx of TXS) {
const vaaIds = await fetchVaaId([tx]);
if (vaaIds.length === 0) {
console.log(`No VAA ID found for transaction: ${tx}`);
continue;
}
for (const vaaId of vaaIds) {
const vaaData = await fetchVaa([vaaId]);
if (vaaData.length === 0 || !vaaData[0].vaaBytes) {
console.log(`VAA not found for ID: ${vaaId}`);
continue;
}
const result = await checkVaaValidity(vaaData[0].vaaBytes);
console.log(
`Transaction: ${tx}\nVAA ID: ${vaaId}\nVAA Validity:`,
result
);
}
}
};
testCheckVaaValidity();
```
3. Run the script:
```bash
npx tsx test/checkVaaValidity.run.ts
```
If the VAA is valid, the output will be:
npx tsx test/checkVaaValidity.run.ts
✅ VAA Valid: true
If invalid, the output will include the reason:
npx tsx test/checkVaaValidity.run.ts
❌ VAA Valid: false, Reason: VM signature invalid
Transaction: 0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367
### Fetch Observations (VAA Signatures)
Before replacing outdated signatures, we need to fetch the original VAA signatures from Wormholescan. This allows us to compare them with the latest Guardian set and determine which ones need updating.
Inside `src/helpers/vaaHelper.ts`, create the `fetchObservations()` function to query the Wormholescan API for observations related to a given VAA. Format the response by converting Guardian addresses to lowercase for consistency, and return an empty array if an error occurs.
```typescript title="src/helpers/vaaHelper.ts"
export async function fetchObservations(vaaId: string) {
try {
console.log(`Fetching observations`);
const response = await axios.get(
`https://api.wormholescan.io/api/v1/observations/${vaaId}`
);
return response.data.map((obs: any) => ({
guardianAddr: obs.guardianAddr.toLowerCase(),
signature: obs.signature,
}));
} catch (error) {
console.error(`Error fetching observations:`, error);
return [];
}
}
```
???- code "Try it out: Fetch Observations"
If you want to try the function before moving forward, create a script inside the `test` directory
1. Create the script file:
```bash
touch test/fetchObservations.run.ts
```
2. Add the function call:
```typescript title="test/fetchObservations.run.ts"
import { fetchVaaId, fetchObservations } from '../src/helpers/vaaHelper';
import { TXS } from '../src/config/constants';
const testFetchObservations = async () => {
for (const tx of TXS) {
const vaaIds = await fetchVaaId([tx]);
if (vaaIds.length === 0) {
console.log(`No VAA ID found for transaction: ${tx}`);
continue;
}
for (const vaaId of vaaIds) {
const observations = await fetchObservations(vaaId);
if (observations.length === 0) {
console.log(`No observations found for VAA ID: ${vaaId}`);
continue;
}
console.log(
`Transaction: ${tx}\nVAA ID: ${vaaId}\nObservations:`,
observations
);
}
}
};
testFetchObservations();
```
3. Run the script:
```bash
npx tsx test/fetchObservations.run.ts
```
If successful, the output will be:
npx tsx test/fetchObservations.run.ts
Fetching observations
Transaction: 0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367
Observations: [ { guardianAddr: '0xda798f6896a3331f64b48c12d1d57fd9cbe70811', signature:
'ZGFlMDYyOGNjZjFjMmE0ZTk5YzE2OThhZjAzMDM4NzZlYTM1OWMxMzczNDA3YzdlMDMxZTkyNzk0ODkwYjRiYjRiOWFmNzM3NjRiMzIyOTE0ZTQwYzNlMjllMWEzNmM2NTc3ZDc5ZTdhNTM2MzA5YjA4YjExZjE3YzE3MDViNWIwMQ=='
}, { guardianAddr: '0x74a3bf913953d695260d88bc1aa25a4eee363ef0', signature:
'MzAyOTU4OGU4MWU0ODc0OTAwNDU3N2EzMGZlM2UxMDJjOWYwMjM0NWVhY2VmZWQ0ZGJlNTFkNmI3YzRhZmQ5ZTNiODFjNTg3MDNmYzUzNmJiYWFiZjNlODc1YTY3OTQwMGE4MmE3ZjZhNGYzOGY3YmRmNDNhM2VhNGQyNWNlNGMwMA=='
},
...]
If no observations are found, the script will log an error message.
### Fetch the Latest Guardian Set
Now that we have the original VAA signatures, we must fetch the latest Guardian set from Wormholescan. This will allow us to compare the stored signatures with the current Guardians and determine which signatures need replacing.
Create the `fetchGuardianSet()` function inside `src/helpers/vaaHelper.ts` to fetch the latest Guardian set.
```typescript title="src/helpers/vaaHelper.ts"
export async function fetchGuardianSet() {
try {
console.log('Fetching current guardian set');
const response = await axios.get(`${WORMHOLESCAN_API}/guardianset/current`);
const guardians = response.data.guardianSet.addresses.map((addr: string) =>
addr.toLowerCase()
);
const guardianSet = response.data.guardianSet.index;
return [guardians, guardianSet];
} catch (error) {
console.error('Error fetching guardian set:', error);
return [];
}
}
```
???- code "Try it out: Fetch Guardian Set"
If you want to try the function before moving forward, create a script inside the `test` directory
1. Create the script file:
```bash
touch test/fetchGuardianSet.run.ts
```
2. Add the function call:
```typescript title="test/fetchGuardianSet.run.ts"
import { fetchGuardianSet } from '../src/helpers/vaaHelper';
const testFetchGuardianSet = async () => {
const [guardians, guardianSetIndex] = await fetchGuardianSet();
console.log('Current Guardian Set Index:', guardianSetIndex);
console.log('Guardian Addresses:', guardians);
};
testFetchGuardianSet();
```
3. Run the script:
```bash
npx tsx test/fetchGuardianSet.run.ts
```
If successful, the output will be:
npx tsx test/fetchGuardianSet.run.ts
Fetching current guardian set
Current Guardian Set Index: 4
Guardian Addresses: [
'0x5893b5a76c3f739645648885bdccc06cd70a3cd3',
'0xff6cb952589bde862c25ef4392132fb9d4a42157',
'0x114de8460193bdf3a2fcf81f86a09765f4762fd1',
'0x107a0086b32d7a0977926a205131d8731d39cbeb',
...]
If an error occurs while fetching the Guardian set, a `500` status error will be logged.
### Replace Outdated Signatures
With the full VAA, Guardian signatures, and the latest Guardian set, we can now update outdated signatures while maintaining the required signature count.
1. **Create the `replaceSignatures()` function**: Open `src/helpers/vaaHelper.ts` and add the function header. To catch and handle errors properly, all logic will be wrapped inside a `try` block.
```typescript title="src/helpers/vaaHelper.ts"
export async function replaceSignatures(
vaa: string | Uint8Array,
observations: { guardianAddr: string; signature: string }[],
currentGuardians: string[],
guardianSetIndex: number
) {
console.log('Replacing Signatures...');
try {
// Add logic in the following steps here
} catch (error) {
console.error('Unexpected error in replaceSignatures:', error);
}
}
```
- **`vaa`**: Original VAA bytes.
- **`observations`**: Observed signatures from the network.
- **`currentGuardians`**: Latest Guardian set.
- **`guardianSetIndex`**: Current Guardian set index.
2. **Validate input data**: Ensure all required parameters are present before proceeding. If any required input is missing, the function throws an error to prevent execution with incomplete data. The Guardian set should never be empty; if it is, this likely indicates an error in fetching the Guardian set in a previous step.
```typescript
if (!vaa) throw new Error('VAA is undefined or empty.');
if (currentGuardians.length === 0)
throw new Error('Guardian set is empty.');
if (observations.length === 0) throw new Error('No observations provided.');
```
3. **Filter valid signatures**: Remove signatures from inactive Guardians, keeping only valid ones. If there aren't enough valid signatures to replace the outdated ones, execution is halted to prevent an incomplete or invalid VAA.
```typescript
const validSigs = observations.filter((sig) =>
currentGuardians.includes(sig.guardianAddr)
);
if (validSigs.length === 0)
throw new Error('No valid signatures found. Cannot proceed.');
```
4. **Convert valid signatures**: Ensure signatures are correctly formatted for verification. Convert hex-encoded signatures if necessary and extract their components.
```typescript
const formattedSigs = validSigs
.map((sig) => {
try {
const sigBuffer = Buffer.from(sig.signature, 'base64');
// If it's 130 bytes, it's hex-encoded and needs conversion
const sigBuffer1 =
sigBuffer.length === 130
? Buffer.from(sigBuffer.toString(), 'hex')
: sigBuffer;
const r = BigInt('0x' + sigBuffer1.subarray(0, 32).toString('hex'));
const s = BigInt('0x' + sigBuffer1.subarray(32, 64).toString('hex'));
const vRaw = sigBuffer1[64];
const v = vRaw < 27 ? vRaw : vRaw - 27;
return {
guardianIndex: currentGuardians.indexOf(sig.guardianAddr),
signature: new Signature(r, s, v),
};
} catch (error) {
console.error(
`Failed to process signature for guardian: ${sig.guardianAddr}`,
error
);
return null;
}
})
.filter(
(sig): sig is { guardianIndex: number; signature: Signature } =>
sig !== null
); // Remove null values
```
5. **Deserialize the VAA**: Convert the raw VAA data into a structured format for further processing.
```typescript
let parsedVaa: VAA<'Uint8Array'>;
try {
parsedVaa = deserialize('Uint8Array', vaa);
} catch (error) {
throw new Error(`Error deserializing VAA: ${error}`);
}
```
6. **Identify outdated signatures**: Compare the current VAA signatures with the newly formatted ones to detect which signatures belong to outdated Guardians. Remove these outdated signatures to ensure only valid ones remain.
```typescript
const outdatedGuardianIndexes = parsedVaa.signatures
.filter(
(vaaSig) =>
!formattedSigs.some(
(sig) => sig.guardianIndex === vaaSig.guardianIndex
)
)
.map((sig) => sig.guardianIndex);
console.log('Outdated Guardian Indexes:', outdatedGuardianIndexes);
let updatedSignatures = parsedVaa.signatures.filter(
(sig) => !outdatedGuardianIndexes.includes(sig.guardianIndex)
);
```
7. **Replace outdated signatures**: Substitute outdated signatures with valid ones while maintaining the correct number of signatures. If there aren’t enough valid replacements, execution stops.
```typescript
const validReplacements = formattedSigs.filter(
(sig) =>
!updatedSignatures.some((s) => s.guardianIndex === sig.guardianIndex)
);
// Check if we have enough valid signatures to replace outdated ones**
if (outdatedGuardianIndexes.length > validReplacements.length) {
console.warn(
`Not enough valid replacement signatures! Need ${outdatedGuardianIndexes.length}, but only ${validReplacements.length} available.`
);
return;
}
updatedSignatures = [
...updatedSignatures,
...validReplacements.slice(0, outdatedGuardianIndexes.length),
];
updatedSignatures.sort((a, b) => a.guardianIndex - b.guardianIndex);
```
8. **Serialize the updated VAA**: Reconstruct the VAA with the updated signatures and convert it into a format suitable for submission.
```typescript
const updatedVaa: VAA<'Uint8Array'> = {
...parsedVaa,
guardianSet: guardianSetIndex,
signatures: updatedSignatures,
};
let patchedVaa: Uint8Array;
try {
patchedVaa = serialize(updatedVaa);
} catch (error) {
throw new Error(`Error serializing updated VAA: ${error}`);
}
```
9. **Send the updated VAA for verification and handle errors**: Submit the updated VAA to an Ethereum RPC node for validation, ensuring it can be proposed for Guardian approval. If an error occurs during submission or signature replacement, log the issue and prevent further execution.
```typescript
try {
if (!(patchedVaa instanceof Uint8Array))
throw new Error('Patched VAA is not a Uint8Array!');
const vaaHex = `0x${Buffer.from(patchedVaa).toString('hex')}`;
console.log('Sending updated VAA to RPC...');
const result = await axios.post(RPC, {
jsonrpc: '2.0',
id: 1,
method: 'eth_call',
params: [
{
from: null,
to: ETH_CORE,
data: eth.abi.encodeFunctionCall(PARSE_AND_VERIFY_VM_ABI, [vaaHex]),
},
'latest',
],
});
const verificationResult = result.data.result;
console.log('Updated VAA (hex):', vaaHex);
return verificationResult;
} catch (error) {
throw new Error(`Error sending updated VAA to RPC: ${error}`);
}
```
???- code "Complete Function"
```typescript
export async function replaceSignatures(
vaa: string | Uint8Array,
observations: { guardianAddr: string; signature: string }[],
currentGuardians: string[],
guardianSetIndex: number
) {
console.log('Replacing Signatures...');
try {
if (!vaa) throw new Error('VAA is undefined or empty.');
if (currentGuardians.length === 0)
throw new Error('Guardian set is empty.');
if (observations.length === 0) throw new Error('No observations provided.');
const validSigs = observations.filter((sig) =>
currentGuardians.includes(sig.guardianAddr)
);
if (validSigs.length === 0)
throw new Error('No valid signatures found. Cannot proceed.');
const formattedSigs = validSigs
.map((sig) => {
try {
const sigBuffer = Buffer.from(sig.signature, 'base64');
// If it's 130 bytes, it's hex-encoded and needs conversion
const sigBuffer1 =
sigBuffer.length === 130
? Buffer.from(sigBuffer.toString(), 'hex')
: sigBuffer;
const r = BigInt('0x' + sigBuffer1.subarray(0, 32).toString('hex'));
const s = BigInt('0x' + sigBuffer1.subarray(32, 64).toString('hex'));
const vRaw = sigBuffer1[64];
const v = vRaw < 27 ? vRaw : vRaw - 27;
return {
guardianIndex: currentGuardians.indexOf(sig.guardianAddr),
signature: new Signature(r, s, v),
};
} catch (error) {
console.error(
`Failed to process signature for guardian: ${sig.guardianAddr}`,
error
);
return null;
}
})
.filter(
(sig): sig is { guardianIndex: number; signature: Signature } =>
sig !== null
); // Remove null values
let parsedVaa: VAA<'Uint8Array'>;
try {
parsedVaa = deserialize('Uint8Array', vaa);
} catch (error) {
throw new Error(`Error deserializing VAA: ${error}`);
}
const outdatedGuardianIndexes = parsedVaa.signatures
.filter(
(vaaSig) =>
!formattedSigs.some(
(sig) => sig.guardianIndex === vaaSig.guardianIndex
)
)
.map((sig) => sig.guardianIndex);
console.log('Outdated Guardian Indexes:', outdatedGuardianIndexes);
let updatedSignatures = parsedVaa.signatures.filter(
(sig) => !outdatedGuardianIndexes.includes(sig.guardianIndex)
);
const validReplacements = formattedSigs.filter(
(sig) =>
!updatedSignatures.some((s) => s.guardianIndex === sig.guardianIndex)
);
// Check if we have enough valid signatures to replace outdated ones**
if (outdatedGuardianIndexes.length > validReplacements.length) {
console.warn(
`Not enough valid replacement signatures! Need ${outdatedGuardianIndexes.length}, but only ${validReplacements.length} available.`
);
return;
}
updatedSignatures = [
...updatedSignatures,
...validReplacements.slice(0, outdatedGuardianIndexes.length),
];
updatedSignatures.sort((a, b) => a.guardianIndex - b.guardianIndex);
const updatedVaa: VAA<'Uint8Array'> = {
...parsedVaa,
guardianSet: guardianSetIndex,
signatures: updatedSignatures,
};
let patchedVaa: Uint8Array;
try {
patchedVaa = serialize(updatedVaa);
} catch (error) {
throw new Error(`Error serializing updated VAA: ${error}`);
}
try {
if (!(patchedVaa instanceof Uint8Array))
throw new Error('Patched VAA is not a Uint8Array!');
const vaaHex = `0x${Buffer.from(patchedVaa).toString('hex')}`;
console.log('Sending updated VAA to RPC...');
const result = await axios.post(RPC, {
jsonrpc: '2.0',
id: 1,
method: 'eth_call',
params: [
{
from: null,
to: ETH_CORE,
data: eth.abi.encodeFunctionCall(PARSE_AND_VERIFY_VM_ABI, [vaaHex]),
},
'latest',
],
});
const verificationResult = result.data.result;
console.log('Updated VAA (hex):', vaaHex);
return verificationResult;
} catch (error) {
throw new Error(`Error sending updated VAA to RPC: ${error}`);
}
} catch (error) {
console.error('Unexpected error in replaceSignatures:', error);
}
}
```
## Create Script to Replace Outdated VAA Signatures
Now that we have all the necessary helper functions, we will create a script to automate replacing outdated VAA signatures. This script will retrieve a transaction’s VAA sequentially, check its validity, fetch the latest Guardian set, and update its signatures. By the end, it will output a correctly signed VAA that can be proposed for Guardian approval.
1. **Open the file**: Inside `src/scripts/replaceSignatures.ts`, import the required helper functions needed to process the VAAs.
```typescript title="src/scripts/replaceSignatures.ts"
import {
fetchVaaId,
fetchVaa,
checkVaaValidity,
fetchObservations,
fetchGuardianSet,
replaceSignatures,
} from '../helpers/vaaHelper';
import { TXS } from '../config/constants';
```
2. **Define the main execution function**: Add the following function inside `src/scripts/replaceSignatures.ts` to process each transaction in `TXS`, going step by step through the signature replacement process.
```typescript
async function main() {
try {
for (const tx of TXS) {
console.log(`\nProcessing TX: ${tx}\n`);
// 1. Fetch Transaction VAA IDs:
const vaaIds = await fetchVaaId([tx]);
if (!vaaIds.length) continue;
// 2. Fetch VAA Data:
const vaaData = await fetchVaa(vaaIds);
if (!vaaData.length) continue;
const vaaBytes = vaaData[0].vaaBytes;
if (!vaaBytes) continue;
// 3. Check VAA Validity:
const { valid } = await checkVaaValidity(vaaBytes);
if (valid) continue;
// 4. Fetch Observations (VAA signatures):
const observations = await fetchObservations(vaaIds[0]);
// 5. Fetch Current Guardian Set:
const [currentGuardians, guardianSetIndex] = await fetchGuardianSet();
// 6. Replace Signatures:
const response = await replaceSignatures(
Buffer.from(vaaBytes, 'base64'),
observations,
currentGuardians,
guardianSetIndex
);
if (!response) continue;
}
} catch (error) {
console.error('❌ Error in execution:', error);
process.exit(1);
}
}
```
3. **Make the script executable**: Ensure it runs when executed.
```typescript
main();
```
To run the script, use the following command:
```bash
npx tsx src/scripts/replaceSignatures.ts
```
npx tsx src/scripts/replaceSignatures.ts
Processing TX: 0x3ad91ec530187bb2ce3b394d587878cd1e9e037a97e51fbc34af89b2e0719367
❌ VAA Valid: false, Reason: VM signature invalid
Fetching observations
Fetching current guardian set
Replacing Signatures...
Outdated Guardian Indexes: [ 0 ]
Sending updated VAA to RPC...
Updated VAA (hex): 0x01000000040d010019447b72d51e33923a3d6b28496ccd3722d5f1e33e2...
The script logs each step, skipping valid VAAs, replacing outdated signatures for invalid VAAs, and logging any errors. It then completes with a valid VAA ready for submission.
## Resources
You can explore the complete project and find all necessary scripts and configurations in Wormhole's [demo GitHub repository](https://github.com/wormhole-foundation/demo-vaa-signature-replacement){target=\_blank}.
The demo repository includes a bonus script to check the VAA redemption status on Ethereum and Solana, allowing you to verify whether a transaction has already been redeemed on the destination chain.
## Conclusion
You've successfully built a script to fetch, validate, and replace outdated signatures in VAAs using Wormholescan and the Wormhole SDK.
It's important to note that this tutorial does not update VAAs in the Wormhole network. Before redeeming the VAA, you must propose it for Guardian approval to finalize the process.
Looking for more? Check out the [Wormhole Tutorial Demo repository](https://github.com/wormhole-foundation/demo-tutorials){target=\_blank} for additional examples.
---
Page Title: Routes
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-connect-concepts-routes.md
- Canonical (HTML): https://wormhole.com/docs/products/connect/concepts/routes/
- Summary: Explore Wormhole Connect's routing capabilities for asset transfers, featuring WTT, CCTP, NTT, and various blockchain-specific routes for optimal UX.
- Word Count: 1132; Token Estimate: 1602
## Routes Overview {: #routes-overview}
This page explains the concept of routes in Wormhole Connect. To configure routes for your widget, check the [Wormhole Connect Configuration](/docs/products/connect/configuration/data/){target=\_blank}.
Routes are methods by which the widget will transfer the assets. Wormhole Connect supports Wrapped Token Transfers (WTT) for transferring any arbitrary token, and for specific tokens, it also supports more advanced transfer methods that provide superior UX.
When you select the source chain, source token, and destination chain, Wormhole Connect will display the best routes available for that particular combination. In practice, if routes other than WTT are available, only those will be displayed. Check the [feature matrix](/docs/products/connect/reference/support-matrix/){target=\_blank} to see under which exact conditions the routes appear.
!!! note "Terminology"
The SDK and smart contracts use the name Token Bridge. In documentation, this product is referred to as Wrapped Token Transfers (WTT). Both terms describe the same protocol.
## WTT Routes {: #wtt-routes}
WTT locks assets on the source chain and mints Wormhole-wrapped "IOU" tokens on the destination chain. To transfer the assets back, the Wormhole-wrapped tokens are burned, unlocking the tokens on their original chain.
#### Manual Route {: #manual-route}
The manual route transfer method requires two transactions: one on the origin chain to lock the tokens (or burn the Wormhole-wrapped tokens) and one on the destination chain to mint the Wormhole-wrapped tokens (or unlock the original tokens). To offer this option, enable the `bridge` route in the configuration.
#### Automatic Route {: #automatic-route}
Trustless relayers can execute the second transaction on the user's behalf, so the user only needs to perform one transaction on the origin chain to have the tokens delivered to the destination automatically - for a small fee. Wormhole Connect automatically detects whether the relayer supports a token and will display the option if the `relay` route is enabled in the configuration.
## CCTP Routes (USDC) {: #cctp-routes-usdc}
[Circle](https://www.circle.com/){target=\_blank}, the issuer of USDC, provides a native way for native USDC to be transferred between [CCTP-enabled](https://www.circle.com/cross-chain-transfer-protocol){target=\_blank} chains. Wormhole Connect can facilitate such transfers.
Note that if native USDC is transferred from the CCTP-enabled chains to any other outside of this list, the transfer will be routed through WTT, and the resulting asset will be a Wormhole-wrapped token instead of native USDC.
#### Manual Route {: #manual-route-cctp}
This transfer method requires two transactions: one on the origin chain to burn the USDC and one on the destination chain to mint the USDC. The manual CCTP route relies on CCTP only and doesn't use Wormhole messaging in the background. Enable the `cctpManual` route in the configuration to offer this option.
#### Automatic Route {: #automatic-route-cctp}
Trustless relayers can execute the second transaction on the user's behalf. Therefore, the user only needs to perform one transaction on the origin chain to have the tokens delivered to the destination automatically—for a small fee. To offer this option, enable the `cctpRelay` route in the configuration.
## Native Token Transfers (NTT) Routes {: #native-token-transfers-ntt-routes}
[Wormhole's Native Token Transfer (NTT) framework](https://github.com/wormhole-foundation/native-token-transfers/){target=\_blank} enables token issuers to retain full ownership of their tokens across any number of chains, unlike WTT. The token issuer must deploy NTT contracts, and Wormhole Connect needs to be [configured](/docs/products/connect/configuration/data/){target=\_blank} with the appropriate `nttGroups` before such tokens are recognized as transferrable via NTT. Refer to the [documentation in the NTT repository](https://github.com/wormhole-foundation/native-token-transfers?tab=readme-ov-file#overview){target=\_blank} for more information about the contracts needed and the framework in general.
#### Manual Route {: #manual-route-ntt}
This transfer method requires two transactions: one on the origin chain to burn or lock the tokens and one on the destination chain to mint them. To offer this option, enable the `nttManual` route in the configuration.
#### Automatic Route {: #automatic-route-ntt}
Trustless relayers can execute the second transaction on the user's behalf, so the user only needs to perform one transaction on the origin chain to have the tokens delivered to the destination automatically—for a small fee. Wormhole Connect automatically detects whether the relayer supports a token and will display the option if the `nttRelay` route is enabled in the configuration.
## ETH Bridge Route for Native ETH and wstETH {: #eth-bridge-route-for-native-eth-and-wsteth}
[Powered by Uniswap liquidity pools](https://github.com/wormhole-foundation/example-uniswap-liquidity-layer){target=\_blank}, this route can transfer native ETH or wstETH between certain EVMs without going through the native bridges. For example, you can transfer native ETH from Arbitrum to Optimism and end up with Optimism ETH all in one go. Supported chains are Ethereum, Arbitrum, Optimism, Base, Polygon (canonical wETH), BSC (canonical wETH), and Avalanche (canonical wETH).
#### Automatic Route {: #automatic-route-eth}
Only the relayed route is available due to the complexity of the transaction that needs to be executed at the destination. To offer this option, enable the `ethBridge` and/or `wstETHBridge` route in the configuration.
## USDT Bridge Route {: #usdt-bridge-route}
Operating on the same technology as the ETH Bridge, this route can transfer USDT between certain EVMs without going through the native bridges. The resulting token will be the canonical USDT token on the destination instead of the Wormhole-wrapped variant. Supported chains are Ethereum, Polygon, Avalanche, Arbitrum, Optimism, BSC, and Base.
#### Automatic Route {: #automatic-route-usdt}
Only the relayed route is available due to the complexity of the transaction that needs to be executed on the destination. Enable the `usdtBridge` route in the configuration to offer this option.
## tBTC Route {: #tbtc-route}
You can bridge [Threshold's Bitcoin](https://www.threshold.network/){target=\_blank} via this hybrid solution that combines WTT and Threshold's contracts. Native tBTC is first locked in the Wormhole WTT, transferred to the destination in the form of Wormhole-wrapped tBTC, which is then immediately locked in Threshold's contract that mints native tBTC for it. The net result is that the user ends up with native tBTC on chains where this Threshold contract is deployed (e.g., Solana, Polygon, Arbitrum, Optimism, or Base).
Note that if native tBTC is transferred out of these chains to any other outside of this list, the transfer will be routed through WTT, and the resulting asset will be a Wormhole-wrapped token instead of native tBTC.
#### Manual Route {: #manual-route-tbtc}
This transfer method requires two transactions: one on the origin chain to burn or lock the tokens and one on the destination chain to mint them. To provide this option, enable the `tbtc` route in the configuration.
---
Page Title: Security
- Resolved Markdown: https://wormhole.com/docs/ai/pages/protocol-security.md
- Canonical (HTML): https://wormhole.com/docs/protocol/security/
- Summary: Explore Wormhole's security features, including the Guardian network, governance, monitoring, open-source development, and bug bounty programs.
- Word Count: 1268; Token Estimate: 1909
# Security
## Core Security Assumptions
At its core, Wormhole is secured by a network of [Guardian](/docs/protocol/infrastructure/guardians/){target=\_blank} nodes that validate and sign messages. If a super majority (e.g., 13 out of 19) of Guardians sign the same message, it can be considered valid. A smart contract on the target chain will verify the signatures and format of the message before approving any transaction.
- Wormhole's core security primitive is its signed messages (signed [VAAs](/docs/protocol/infrastructure/vaas/){target=\_blank}).
- The Guardian network is currently secured by a collection of 19 of the world's top [validator companies](https://wormhole-foundation.github.io/wormhole-dashboard/#/?endpoint=Mainnet){target=\_blank}.
- Guardians produce signed state attestations (signed VAAs) when requested by a Core Contract integrator.
- Every Guardian runs full nodes (rather than light nodes) of every blockchain in the Wormhole network, so if a blockchain suffers a consensus attack or hard fork, the blockchain will disconnect from the network rather than potentially produce invalid signed VAAs.
- Any Signed VAA can be verified as authentic by the Core Contract of any other chain.
- The [Executor](/docs/protocol/infrastructure/relayers/executor-framework/){target=\_blank} is considered untrusted in the Wormhole ecosystem. It can affect message availability (timing of delivery) but cannot alter or forge VAAs, as validity is enforced by Guardian signatures.
In summary:
- **Core integrators are not exposed to risk from chains and contracts they do not integrate with**.
- By default, you only trust Wormhole's signing process and the core contracts of the chains you're on.
- You can expand your contract and chain dependencies as you see fit.
Core assumptions aside, many other factors impact the real-world security of decentralized platforms. Here is more information on additional measures that have been put in place to ensure the security of Wormhole.
## Guardian Network
Wormhole is an evolving platform. While the canonical Guardian set consists of 19 members, not all chains require all 19 Guardians to perform direct on-chain observation. For delegated chains, a delegated subset of Guardians performs direct on-chain observation while the final VAA signature threshold remains 13-of-19.
Delegated Guardian Sets introduces a per-chain trust assumption: the delegate quorum threshold determines how many Delegated Guardians must independently agree before Canonical Guardians sign. This model does not weaken the final 13-of-19 VAA requirement, but it means the observation layer for that chain depends on fewer nodes. The `WormholeDelegatedGuardians` governance contract allows these thresholds to be adjusted as network requirements evolve.
### Governance
Governance is the process through which contract upgrades happen. Guardians manually vote on governance proposals that originate inside the Guardian Network and are then submitted to ecosystem contracts.
This means that governance actions are held to the same security standard as the rest of the system. A two-thirds supermajority of the Guardians is required to pass any governance action.
Governance messages can target any of the various wormhole modules, including the core contracts and all currently deployed Wrapped Token Transfers (WTT) contracts. When a Guardian signs such a message, its signature implies a vote on the action in question. Once more than two-thirds of the Guardians have signed, the message and governance action are considered valid.
All governance actions and contract upgrades have been managed via Wormhole's on-chain governance system.
Via governance, the Guardians can:
- Change the current Guardian set.
- Expand the Guardian set.
- Upgrade ecosystem contract implementations.
- Configure per-chain Delegated Guardian sets and security thresholds via the `WormholeDelegatedGuardians` contract.
The governance system is fully open source in the core repository. See the [Open Source section](#open-source){target=\_blank} for contract source.
## Monitoring
A key element of Wormhole's defense-in-depth strategy is that each Guardian is a highly competent validator company with its own in-house processes for running, monitoring, and securing blockchain operations. This heterogeneous approach to monitoring increases the likelihood that fraudulent activity is detected and reduces the number of single failure points in the system.
For full Guardian Set chains, all Guardians run full nodes and independently monitor block production and contract activity. For delegated chains, Delegated Guardians perform direct on-chain monitoring while Canonical Guardians monitor delegate observations and enforce quorum safeguards.
Guardians monitor:
- **Block production and consensus of each blockchain**: If a blockchain's consensus is violated, it will be disconnected from the network until the Guardians resolve the issue.
- **Smart contract level data**: Via processes like the Governor, Guardians constantly monitor the circulating supply and token movements across all supported blockchains.
- **Guardian level activity**: The Guardian Network functions as an autonomous decentralized computing network, ensuring independent security measures across its validators.
## Asset Layer Protections
One key strength of the Wormhole ecosystem is the Guardians' ability to validate and protect the integrity of assets across multiple blockchains.
To enforce the Wormhole Asset Layer's core protections, the Global Accountant tracks the total circulating supply of all Wormhole assets across all chains, preventing any blockchain from bridging assets that could violate the supply invariant.
For delegated chains, delegate quorum must be reached before Canonical Guardians contribute signatures, ensuring that per-chain delegate thresholds are respected without altering the Global Accountant's 13-of-19 security model.
In addition to the Global Accountant, Guardians may only sign transfers that do not violate the requirements of the Governor. The [Governor](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0007_governor.md){target=\_blank} tracks inflows and outflows of all blockchains and delays suspicious transfers that may indicate an exploit.
## Open Source
Wormhole builds in the open and is always open source.
- **[Wormhole core repository](https://github.com/wormhole-foundation/wormhole){target=\_blank}**
- **[Wormhole Foundation GitHub organization](https://github.com/wormhole-foundation){target=\_blank}**
- **[Wormhole contract deployments](/docs/protocol/infrastructure/core-contracts/){target=\_blank}**
## Audits
Wormhole has been heavily audited, with _29 third-party audits completed_ and more started. Audits have been performed by the following firms:
- [Trail of Bits](https://www.trailofbits.com/){target=\_blank}
- [Neodyme](https://neodyme.io/en/){target=\_blank}
- [Kudelski](https://kudelskisecurity.com/){target=\_blank}
- [OtterSec](https://osec.io/){target=\_blank}
- [Certik](https://www.certik.com/){target=\_blank}
- [Hacken](https://hacken.io/){target=\_blank}
- [Zellic](https://www.zellic.io/){target=\_blank}
- [Coinspect](https://www.coinspect.com/){target=\_blank}
- [Halborn](https://www.halborn.com/){target=\_blank}
- [Cantina](https://cantina.xyz/welcome){target=\_blank}
All audits and final reports can be found in [security page of the GitHub Repo](https://github.com/wormhole-foundation/wormhole/blob/main/SECURITY.md#3rd-party-security-audits){target=\_blank}.
## Bug Bounties
Wormhole has one of the largest bug bounty programs in software development and has repeatedly shown commitment to engaging with the white hat community.
Wormhole runs a bug bounty program through [Immunefi](https://immunefi.com/bug-bounty/wormhole/){target=\_blank} program, with a top payout of **5 million dollars**.
If you are interested in contributing to Wormhole security, please look at this section for [Getting Started as a White Hat](https://github.com/wormhole-foundation/wormhole/blob/main/SECURITY.md#white-hat-hacking){target=\_blank}, and follow the [Wormhole Contributor Guidelines](https://github.com/wormhole-foundation/wormhole/blob/main/CONTRIBUTING.md){target=\_blank}.
For more information about submitting to the bug bounty programs, refer to the [Wormhole Immunefi page](https://immunefi.com/bug-bounty/wormhole/){target=\_blank}.
## Next Steps
- :octicons-book-16:{ .lg .middle } **View Latest Security Policies**
---
The `SECURITY.md` from the official Wormhole repository on GitHub has the latest security policies and updates.
[:custom-arrow: See SECURITY.md](https://github.com/wormhole-foundation/wormhole/blob/main/SECURITY.md){target=\_blank}
---
Page Title: Solana Message Emission via Shim
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-messaging-guides-solana-shims-sol-emission.md
- Canonical (HTML): https://wormhole.com/docs/products/messaging/guides/solana-shims/sol-emission/
- Summary: Learn how to reduce rent costs when emitting Wormhole messages on Solana by using the emission shim instead of post_message.
- Word Count: 1220; Token Estimate: 2148
# Solana Message Emission via Shim
The emission shim is a lightweight Solana program that lets integrators emit Wormhole messages without creating a new rent-exempt account for every message. It passes an empty payload to the core bridge and emits the message data through transaction logs, reducing rent costs and avoiding state bloat while remaining fully compatible with Guardian observation.
Migrating from the legacy path is straightforward: no account resizing is needed, and programs can call the shim directly. The Wormhole fee is still paid through the `fee_collector`, with the same parallelization limits as before.
Guardians are configured to observe the canonical shim address, reading message data, emitter, and nonce from the transaction logs and CPI events, rather than on-chain accounts. They also ignore the empty core bridge payload to prevent duplicate VAAs. On mainnet, all 19 Guardians support shim emissions, and, as with all Wormhole messages, at least 13 attestations are required for a valid VAA.
!!!note
For on-chain programs that only call the shim via CPI, consider emitting a dummy/empty message after migration to avoid edge cases with initial CPI depth (Solana limits the depth of cross-program calls).
For more background, see [Emission Shim concept section](/docs/products/messaging/concepts/solana-shim/#emission-shim){target=\_blank}.
## Prerequisites
To interact with the emission shim, you'll need the following:
- [Rust and Solana CLI](https://solana.com/docs/intro/installation){target=\_blank} installed.
- [Anchor installed](https://www.anchor-lang.com/docs/installation){target=\_blank}.
- The canonical emission shim program already deployed at [`EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX`](https://explorer.solana.com/address/EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX){target=\_blank}.
- The shim’s [IDL](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/idls/wormhole_post_message_shim.json){target=\_blank} for wiring accounts.
- A payer (signer) funded with enough SOL to cover compute and message fees.
## Setup
To start, import the shim crate to call `wormhole_post_message_shim::cpi::post_message`. Then, pull the core bridge addresses needed to be passed along.
```rs
declare_program!(wormhole_post_message_shim);
use anchor_lang::prelude::*;
use wormhole_post_message_shim::{program::WormholePostMessageShim, types::Finality};
use wormhole_solana_consts::{
CORE_BRIDGE_CONFIG, CORE_BRIDGE_FEE_COLLECTOR, CORE_BRIDGE_PROGRAM_ID,
};
```
## Accounts
When calling the shim’s `post_message` instruction, you need to pass:
- **`bridge`**: Holds the Wormhole core bridge config.
- **`message`**: Represents the PDA derived from the emitter and is reused by the shim instead of generating new accounts.
- **`emitter`**: Serves as the emitter address (signer).
- **`sequence`**: Tracks the emitter's sequence account.
- **`payer`**: Pays compute and any rent needed on first use (signer).
- **`fee_collector`**: Collects the Wormhole message fee.
- **`clock`**: Provides the current Solana time from the sysvar.
- **`system_program`**: Supplies the standard Solana system program for account creation on first use.
- **`wormhole_program`**: Points to the Wormhole core bridge program.
- **`event_authority`**: Acts as the PDA used by the shim to emit log events (Anchor CPI events).
- **`program`**: Specifies the shim program itself.
The struct below defines the accounts required by your instruction and wires the shim to the core bridge, ensuring the emitter PDA can sign the CPI via seeds.
```rs
#[derive(Accounts)]
pub struct PostMessage<'info> {
#[account(mut)]
payer: Signer<'info>,
wormhole_post_message_shim: Program<'info, WormholePostMessageShim>,
#[account(mut, address = CORE_BRIDGE_CONFIG)]
/// CHECK: Wormhole bridge config. [`wormhole::post_message`] requires this account be mutable.
/// Address constraint added for IDL generation / convenience, it will be enforced by the core bridge.
pub bridge: UncheckedAccount<'info>,
#[account(mut, seeds = [&emitter.key.to_bytes()], bump, seeds::program = wormhole_post_message_shim::ID)]
/// CHECK: Wormhole Message. [`wormhole::post_message`] requires this account be signer and mutable.
/// Seeds constraint added for IDL generation / convenience, it will be enforced by the shim.
pub message: UncheckedAccount<'info>,
#[account(seeds = [b"emitter"], bump)]
/// CHECK: Our emitter
/// Seeds constraint added for IDL generation / convenience, it will be enforced to match the signer used in the CPI call.
pub emitter: UncheckedAccount<'info>,
#[account(mut)]
/// CHECK: Emitter's sequence account. [`wormhole::post_message`] requires this account be mutable.
/// Explicitly do not re-derive this account. The core bridge verifies the derivation anyway and
/// as of Anchor 0.30.1, auto-derivation for other programs' accounts via IDL doesn't work.
pub sequence: UncheckedAccount<'info>,
#[account(mut, address = CORE_BRIDGE_FEE_COLLECTOR)]
/// CHECK: Wormhole fee collector. [`wormhole::post_message`] requires this account be mutable.
/// Address constraint added for IDL generation / convenience, it will be enforced by the core bridge.
pub fee_collector: UncheckedAccount<'info>,
/// Clock sysvar.
/// Type added for IDL generation / convenience, it will be enforced by the core bridge.
pub clock: Sysvar<'info, Clock>,
/// System program.
/// Type for IDL generation / convenience, it will be enforced by the core bridge.
pub system_program: Program<'info, System>,
#[account(address = CORE_BRIDGE_PROGRAM_ID)]
/// CHECK: Wormhole program.
/// Address constraint added for IDL generation / convenience, it will be enforced by the shim.
pub wormhole_program: UncheckedAccount<'info>,
/// CHECK: Shim event authority
/// TODO: An address constraint could be included if this address was published to wormhole_solana_consts
/// Address will be enforced by the shim.
pub wormhole_post_message_shim_ea: UncheckedAccount<'info>,
}
```
This instruction reuses a single per-emitter message PDA (no per-message rent). When invoked, the shim emits your payload as an Anchor CPI event and, in the same transaction, calls the core bridge with an empty payload, allowing the core bridge to still assign the sequence and enforce fees/finality. Guardians read the Core call (sequence/finality) and the shim event (payload) from the transaction logs, producing a standard VAA without leaving a persistent message account.
## Call post_message
The `post_message` function builds a `CpiContext` and invokes the shim’s `post_message` instruction, forwarding the nonce, finality, and your payload. The Core Bridge enforces fee requirements and assigns the sequence, while the shim emits the payload as an event in the same transaction.
```rs
pub fn post_message(ctx: Context) -> Result<()> {
// wormhole::post_message may require that a fee be sent to the fee_collector account of the core bridge.
// The following code could be used to handle this via CPI call.
// However, this example handles this complexity on the client side using a `preInstruction`
//
// let fee = ctx.accounts.wormhole_bridge.fee();
// if fee > 0 {
// solana_program::program::invoke(
// &solana_program::system_instruction::transfer(
// &ctx.accounts.payer.key(),
// &ctx.accounts.fee_collector.key(),
// fee,
// ),
// &ctx.accounts.to_account_infos(),
// )?;
// }
wormhole_post_message_shim::cpi::post_message(
CpiContext::new_with_signer(
ctx.accounts.wormhole_post_message_shim.to_account_info(),
wormhole_post_message_shim::cpi::accounts::PostMessage {
payer: ctx.accounts.payer.to_account_info(),
bridge: ctx.accounts.bridge.to_account_info(),
message: ctx.accounts.message.to_account_info(),
emitter: ctx.accounts.emitter.to_account_info(),
sequence: ctx.accounts.sequence.to_account_info(),
fee_collector: ctx.accounts.fee_collector.to_account_info(),
clock: ctx.accounts.clock.to_account_info(),
system_program: ctx.accounts.system_program.to_account_info(),
wormhole_program: ctx.accounts.wormhole_program.to_account_info(),
program: ctx.accounts.wormhole_post_message_shim.to_account_info(),
event_authority: ctx.accounts.wormhole_post_message_shim_ea.to_account_info(),
},
&[&[b"emitter", &[ctx.bumps.emitter]]],
),
0,
Finality::Finalized,
b"your message goes here!".to_vec(),
)?;
Ok(())
}
```
## Limitations and Considerations
- **Rent**: No persistent account rent is paid for every emission; the cost is now dominated by compute and the emission fee.
- **Logs**: Since all observability is log-based, re-observation is only possible while Solana transaction history is available.
- **Parallelization**: Still limited by the `fee_collector` account being mutable.
- **CPI Depth**: The first shim call for an emitter adds one extra stack depth. This is only relevant if you are near the Solana CPI limit (4).
## Conclusion
By using the emission shim, you can dramatically reduce rent costs when emitting Wormhole messages from Solana, while ensuring compatibility with Guardian observation and core bridge sequencing.
For a complete, working reference, see the full example implementation in the Wormhole repo: [`post_message.rs`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/programs/wormhole-integrator-example/src/instructions/post_message.rs){target=\_blank}.
---
Page Title: Solana Shims
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-messaging-concepts-solana-shim.md
- Canonical (HTML): https://wormhole.com/docs/products/messaging/concepts/solana-shim/
- Summary: Understand how Wormhole uses shim programs on Solana to optimize message emission and VAA verification without modifying the Core Bridge.
- Word Count: 1769; Token Estimate: 2648
# Solana Shims
Wormhole shims on Solana are lightweight programs that enable cheaper and more flexible message emission and verification while preserving Guardian observation guarantees. They are designed for integrators who want to reduce Solana rent costs without sacrificing core protocol security or Guardian compatibility.
## The Core Bridge Account Problem
When you emit a message on Solana using the legacy [Wormhole core bridge](/docs/protocol/infrastructure/core-contracts/){target=\_blank}, it creates a new on-chain account, a Program Derived Address (PDA), for every message. Each of these accounts must hold enough SOL to be rent-exempt, locking up lamports that cannot be reclaimed since the core bridge does not allow these accounts to be closed. Over time, this results in two big problems:
- **Permanent On-Chain State**: Every message leaves behind a permanent account, increasing long-term storage needs on Solana.
- **Lost Lamports to Rent**: Integrators lose SOL for every message, as the lamports needed for rent exemption remain locked in the message accounts indefinitely.
Solana’s rent-exemption model isn't the fundamental limitation; the constraint lies in the legacy `post_message` function of the core bridge, which always creates a new, non-reclaimable account every time it’s called. Even after a message is consumed, these accounts can’t be closed or reused, resulting in unrecoverable rent costs.
Although the `post_message_unreliable` function allows account reuse, it comes with significant tradeoffs. Once a message is overwritten, it can no longer be recovered, making it no longer observable by Guardians. It also locks you into the original account size, as the feature predates Solana’s account resizing.
Verification has similar costs. The `post_vaa` instruction creates additional temporary accounts for signatures and VAA data, which, like the original accounts, require rent and aren’t automatically cleaned up. Over time, these add to both storage bloat and unrecoverable SOL.
This design ensures reliability, as message data is always available on-chain for Guardians to observe. However, it comes at a cost in both storage and lost SOL. To address these issues, Wormhole introduces Solana shims that fundamentally change the cost model for emissions and verification.
## What Are the Solana Shims?
To address the limitations of the core bridge, Wormhole deploys two specialized Solana programs called shims:
- **[Post Message Shim (`EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX`)](https://explorer.solana.com/address/EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX){target=\_blank}**: Emits Wormhole messages efficiently, without creating new message accounts for each emission, reducing rent costs.
- **[Verify VAA Shim (`EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at`)](https://explorer.solana.com/address/EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at){target=\_blank}**: Verifies VAAs on-chain without leaving permanent accounts.
Both act as lightweight wrappers around the existing core bridge. There are two different options, depending on whether you are emitting messages or verifying VAAs:
### Emission Shim
The [Emission Shim](/docs/products/messaging/guides/solana-shims/sol-emission/){target=\_blank} is a Solana program deployed at [`EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX`](https://explorer.solana.com/address/EtZMZM22ViKMo4r5y4Anovs3wKQ2owUmDpjygnMMcdEX){target=\_blank} which wraps the core bridge’s `post_message_unreliable` instruction. The Emission Shim emits message data as a log event rather than storing it in a rent-exempt message account, eliminating rent costs and preventing long-term state bloat. Guardians are configured to observe this canonical shim, allowing integrators to send messages through it without additional setup.
This shim works by calling the [`post_message`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/idls/wormhole_post_message_shim.json){target=\_blank} instruction on the Post Message Shim program. This instruction emits the Wormhole message as a log event instead of creating a rent-exempt message account.
The shim differs from the standard `post_message` approach in two key ways. First, it utilizes a Program Derived Address (PDA) per emitter for message accounts, eliminating the need to generate a new key pair for each emission. Second, instead of writing the message to a persistent, rent-exempt account, it emits the data via an Anchor CPI event that Guardians can observe directly. This design reduces rent costs and prevents unused accounts from being left behind.
The shim works through a few main components:
- **Shim Program**: Provides a `post_message` instruction modeled on the core bridge’s `post_message_unreliable`.
- **Sequence Handling**: The core bridge continues to manage sequence numbers. It reads the sequence number from the core bridge and emits it in a [CPI event](https://www.anchor-lang.com/docs/basics/cpi){target=\_blank}, along with the timestamp.
- **Message Account**: Calls `post_message_unreliable` on the core bridge, writing an empty payload, so no unique message is stored on-chain.
- **Guardian Role**: Guardians reconstruct the message from instruction data and the emitted event, not from a persistent account.
```mermaid
graph LR
A[Integrator Program]
B[Emission Shim]
C[Core Bridge]
D[Guardians]
A -- call post_message --> B
B -- emits event & calls core --> C
C -- instruction data & event --> D
```
The emission fee is still paid, and the core bridge continues to manage sequence numbers as before. The difference is that instead of creating a new message account for each emission, the shim emits a CPI event with the message data. All the information Guardians need is captured in the transaction logs, without leaving behind permanent accounts.
### Verification Shim
The [Verification Shim](/docs/products/messaging/guides/solana-shims/sol-verification/){target=\_blank} is a Solana program deployed at [`EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at`](https://explorer.solana.com/address/EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at){target=\_blank}. It provides a [`verify_hash`](https://github.com/wormhole-foundation/wormhole/blob/4656bd4a72cb99f4e94a771a802856c9451af844/svm/wormhole-core-shims/programs/verify-vaa/src/lib.rs#L195){target=\_blank} instruction that checks Guardian signatures against the active Guardian set for a VAA's digest. It ensures quorum, validates each signature in order, recovers the public keys, and matches them against the Guardian set. If all checks pass, the VAA is verified without creating persistent rent-exempt accounts. This verification method replaces the use of the core bridge’s `post_vaa`. Integrators can call the canonical shim, but existing programs may need to be modified to adopt this approach.
It works by first calling the [`post_signatures`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/idls/wormhole_verify_vaa_shim.json#L43){target=\_blank} on the Verification Shim to store Guardian signatures in a temporary account. Then, from within your program, call [`verify_hash`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/programs/verify-vaa/README.md#verify-hash-technical-details){target=\_blank} to check the VAA’s digest against Guardian signatures. In the same transaction, close the signatures account with [`close_signatures`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/idls/wormhole_verify_vaa_shim.json#L11){target=\_blank} to reclaim rent.
Instead of the core bridge instructions, such as `verify_signatures` and `post_vaa`, the verification shim provides its own flow using `post_signatures`, `verify_hash`, and `close_signatures`. The flow is a simpler sequence that avoids leaving permanent accounts on-chain:
1. **Call `post_signatures`**: Creates (or appends to) a temporary `GuardianSignatures` account that stores the collected Guardian signatures. This account is owned and managed by the verification shim.
2. **Call `verify_hash`**: Verifies the digest of the VAA against the active Guardian set and checks quorum by recovering and validating each Guardian signature. If verification succeeds, your program can continue its logic.
3. **Call `close_signatures`**: Immediately closes the `GuardianSignatures` account to reclaim the lamports paid for its creation.
```mermaid
graph LR
A[post_signatures] --> B[verify_hash]
B --> C[Process Logic]
C --> D[close_signatures]
```
This flow ensures verification is both rent-efficient and secure, no permanent accounts remain, and Guardians still enforce quorum and integrity guarantees.
## Guardian Observation Methods: Legacy vs. Shims
The following table compares how Guardians observe and verify messages on Solana before and after the introduction of the shims program.
| Observation Methods | Legacy Model | Shim Model |
|----------------------|------------------------|--------------------------|
| Message Storage | On-chain account | Transaction logs (CPI) |
| Data Permanence | Permanent | Until RPC history pruned |
| Guardian Observation | Reads account data | Reads transaction logs |
| Cost | High (rent + compute) | Low (compute only) |
| Closing Accounts | Not possible | Not needed |
With shims, the message’s existence depends on the transaction log, so cost drops, but indefinite on-chain visibility is no longer guaranteed. Sequence tracking remains the same as the legacy model, so integrators can switch between the two without disrupting sequence numbers.
## Transaction Costs
Solana charges for two primary resources when processing transactions:
- Compute units for execution.
- Rent for storing data on-chain.
Understanding how each contributes to the overall cost is key to seeing why shims are cheaper.
- **Compute Units (CU)**: Solana measures CPU resource usage per transaction as “compute units”. Each transaction has a CU limit (usually ~200,000 — which can be increased for a fee).
- **Rent**: One-time cost in SOL to keep an account on-chain. Most of the core bridge’s cost comes from rent, not CUs.
Even though the shim uses slightly more compute (extra logic for logging), it avoids account creation entirely. Since rent is the most significant cost, the total emission cost drops.
## Safety, Tradeoffs & Limitations
Shims preserve the same security guarantees as the core bridge, so that integrators can adopt them without weakening protocol safety. The only difference is where data lives: instead of being stored permanently in message accounts, it is emitted in transaction logs or held temporarily until verification completes. Guardians are explicitly configured to observe shim output, ensuring messages and VAAs remain verifiable across the network.
The main tradeoff is durability. In the legacy model, messages and VAAs were always available on-chain for re-observation. With shims, message data persists only as long as RPC providers retain transaction history. This timeframe is sufficient for Guardian observation, but doesn’t provide indefinite public access to raw message data. Applications that rely on long-term on-chain storage may still prefer the legacy path, while most integrators benefit from the reduced cost and state bloat.
Finally, adopting shims may require some integration changes. For emission, developers should route messages through the Post Message Shim rather than directly through the core bridge. For verification, programs must update their logic to call `verify_hash` and manage temporary accounts in the same transaction. These are lightweight adjustments, but they are necessary to realize the cost savings fully.
## Next Steps
To put these concepts into practice, explore the dedicated guides for emission and verification on Solana.
- :octicons-tools-16:{ .lg .middle } **Emit Messages**
---
Learn how to reduce rent costs when emitting Wormhole messages on Solana by using the emission shim.
[:custom-arrow: Use the Emission Shim](/docs/products/messaging/guides/solana-shims/sol-emission/)
- :octicons-tools-16:{ .lg .middle } **Verify VAAs**
---
Efficiently verify Wormhole VAAs on Solana using the verification shim, which avoids persistent rent-exempt accounts while keeping full security guarantees.
[:custom-arrow: Use the Verification Shim](/docs/products/messaging/guides/solana-shims/sol-verification/)
---
Page Title: Solana VAA Verification via Shim
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-messaging-guides-solana-shims-sol-verification.md
- Canonical (HTML): https://wormhole.com/docs/products/messaging/guides/solana-shims/sol-verification/
- Summary: Efficiently verify Wormhole VAAs on Solana using the Verification Shim, which avoids persistent rent-exempt accounts while keeping full security guarantees.
- Word Count: 709; Token Estimate: 1195
# Solana VAA Verification via Shim
Verifying VAAs on Solana with the legacy core bridge requires creating multiple rent-exempt accounts for signatures and posted VAAs. These accounts persist even after verification is complete, which increases costs and bloats the on-chain state.
The verification shim solves this by replacing the core bridge verification flow with its own instructions:
- `post_signatures`: Accumulates Guardian signatures into a temporary account.
- `verify_hash`: Validates the VAA by checking the signatures against the active Guardian set and ensuring quorum.
- `close_signatures`: Closes the temporary account to reclaim lamports.
Because the shim avoids leaving permanent accounts behind, verification becomes much cheaper while keeping the same security guarantees.
This page introduces the Verification Shim, explains how it works, and shows how integrators can adopt it in place of the core bridge’s `verify_signatures` and `post_vaa` functions.
For more background, see the [Verification Shim concept section](/docs/products/messaging/concepts/solana-shim/#verification-shim){target=\_blank}.
## Prerequisites
To interact with the verification shim, you'll need the following:
- [Rust and Solana CLI installed](https://solana.com/docs/intro/installation){target=\_blank}.
- [Anchor installed](https://www.anchor-lang.com/docs/installation){target=\_blank}.
- The canonical verification shim program already deployed at [`EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at`](https://explorer.solana.com/address/EFaNWErqAtVWufdNb7yofSHHfWFos843DFpu4JBw24at){target=\_blank}.
- The shim’s [IDL](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/idls/wormhole_verify_vaa_shim.json){target=\_blank} for wiring accounts.
- A payer (signer) funded for compute and temporary account rent (you’ll close and reclaim).
## Setup
To start, add the verification shim CPI and declare the external program so your instruction can CPI into it. This lets your program verify a VAA digest against the active Guardian set without creating persistent core bridge accounts.
```rs
declare_program!(wormhole_verify_vaa_shim);
use anchor_lang::{
prelude::*,
solana_program::{self, keccak},
};
use wormhole_verify_vaa_shim::cpi::accounts::VerifyHash;
use wormhole_verify_vaa_shim::program::WormholeVerifyVaaShim;
```
## Accounts
You’ll wire three accounts for verification:
- `guardian_set`: Core bridge `GuardianSet` PDA for the VAA’s `guardianSetIndex` (shim checks derivation).
- `guardian_signatures`: Temporary account created by `post_signatures` (shim checks ownership & discriminator).
- `wormhole_verify_vaa_shim`: The verification shim program.
```rs
#[derive(Accounts)]
pub struct ConsumeVaa<'info> {
/// CHECK: Guardian set used for signature verification by shim.
/// Derivation is checked by the shim.
guardian_set: UncheckedAccount<'info>,
/// CHECK: Stored guardian signatures to be verified by shim.
/// Ownership ownership and discriminator is checked by the shim.
guardian_signatures: UncheckedAccount<'info>,
wormhole_verify_vaa_shim: Program<'info, WormholeVerifyVaaShim>,
}
```
Here, `guardian_set` is a core bridge PDA, and `guardian_signatures` is created and owned by the verification shim. Derive `guardian_set = PDA(["GuardianSet", index_be_bytes], CORE_BRIDGE_PROGRAM_ID)` using the `guardianSetIndex` from the VAA header (big-endian), compute its bump, and pass that bump into your instruction.
## Verify the VAA
The `consume_vaa` function computes the digest, calls the shim’s `verify_hash`, and then proceeds with your logic. This step validates Guardian signatures and quorum against the active Guardian set for the VAA’s `guardianSetIndex`, then lets your program proceed without persisting a `PostedVAA`.
```rs
pub fn consume_vaa(
ctx: Context,
guardian_set_bump: u8,
vaa_body: Vec,
) -> Result<()> {
// Compute the message hash.
let message_hash = &solana_program::keccak::hashv(&[&vaa_body]).to_bytes();
let digest = keccak::hash(message_hash.as_slice()).to_bytes();
// Verify the hash against the signatures.
wormhole_verify_vaa_shim::cpi::verify_hash(
CpiContext::new(
ctx.accounts.wormhole_verify_vaa_shim.to_account_info(),
VerifyHash {
guardian_set: ctx.accounts.guardian_set.to_account_info(),
guardian_signatures: ctx.accounts.guardian_signatures.to_account_info(),
},
),
guardian_set_bump,
digest,
)?;
// Decode vaa_body, perform security checks, and do your thing.
Ok(())
}
```
## Limitations and Security Considerations
- You must be the payer and/or account owner to reclaim lamports from the `GuardianSignatures` account.
- The verification proof is not a permanent on-chain record unless you keep the account.
- Compute usage (CU) is higher for the rent-efficient pattern, but the total cost is dramatically lower than keeping permanent accounts.
- All validation guarantees remain as strong as with the legacy method.
- If you do not close accounts you create, rent will be lost as before.
- This approach assumes you do not need to later re-validate the VAA from an on-chain artifact.
## Conclusion
By following this flow, you can efficiently verify VAAs on Solana with minimal rent overhead, leaving no unnecessary state behind on-chain. For a complete, working reference, see the full example implementation in the Wormhole repo: [`consume_vaa.rs`](https://github.com/wormhole-foundation/wormhole/blob/main/svm/wormhole-core-shims/anchor/programs/wormhole-integrator-example/src/instructions/consume_vaa.rs){target=\_blank}.
---
Page Title: Spy
- Resolved Markdown: https://wormhole.com/docs/ai/pages/protocol-infrastructure-spy.md
- Canonical (HTML): https://wormhole.com/docs/protocol/infrastructure/spy/
- Summary: Discover Wormhole's Spy daemon, which subscribes to gossiped messages in the Guardian Network, including VAAs and Observations, with setup instructions.
- Word Count: 747; Token Estimate: 1153
# Spy
In Wormhole's ecosystem, the _Spy_ is a daemon, a continuously running background process that monitors messages within the Guardian Network. Unlike Guardians, a Spy doesn't perform validation; instead, it serves as an interface for observing the network's message traffic, enabling applications and users to access live data transmitted over Wormhole.
The primary purpose of a Spy is to subscribe to the gossiped messages across the Guardian Network, tracking key message types that allow integrators and applications to monitor real-time network activity without directly engaging in consensus operations.
This page provides a comprehensive guide to where the Spy fits within the Wormhole network, describing the key features and role in facilitating multichain processes.
## Key Features
- **Real-time monitoring of Wormhole messages**: The Spy allows users to observe Wormhole messages as they are published across supported chains in near real-time.
- **Filterable and observable message streams**: Users can filter message streams by chain, emitter, and other criteria, making it easier to track specific contracts or categories of interest.
- **Integration-friendly event streaming**: The Spy exposes gRPC and WebSocket interfaces, making it easy to integrate message observation into custom tooling, dashboards, or indexing services.
- **Support for multiple message protocols**: It can observe messages from different Wormhole messaging protocols (WTT, CCTP, NTT, etc.), providing broad coverage of cross-chain activity.
- **Lightweight and infrastructure-ready**: The Spy is designed to run as part of indexing or backend services, not requiring validator-level infrastructure.
## Integrator Use Case
The Spy provides a valuable mechanism for integrators to observe real-time network activity in the Guardian Network without directly engaging in validation or consensus. By running a Spy, integrators can track multichain events and message flows — such as VAAs, observations, and Guardian heartbeats — to monitor network activity essential to their applications.
This monitoring capability is especially beneficial for applications that need immediate insights into multichain data events. Integrators can run a Spy to ensure their applications are promptly informed of message approvals, observations, or Guardian liveness signals, supporting timely and responsive app behavior without additional overhead on network resources.
## Observable Message Categories
A Spy can access the following categories of messages shared over the gossip protocol:
- **[Verifiable Action Approvals (VAAs)](/docs/protocol/infrastructure/vaas/){target=\_blank}**: Packets of multichain data.
- The Spy can detect whether a VAA has been approved by the Guardian Network, making it a valuable tool for applications needing real-time multichain verification.
- **[Observations](/docs/products/reference/glossary/#observation){target=\_blank}**: Emitted by Wormhole's core contracts, observations are picked up by the Guardians and relayed across the network.
- A Spy allow users to monitor these messages, adding transparency and insight into blockchain events.
- **[Guardian heartbeats](/docs/products/reference/glossary/#heartbeat){target=\_blank}**: Heartbeat messages represent Guardian node status.
- By monitoring heartbeats, a Spy can signal the liveness and connectivity of Guardians in the network.
## Additional Resources
- :octicons-code-16:{ .lg .middle } **Spy Source Code**
---
To see the source code for the Go implementation of the Spy, visit the `wormhole` repository on GitHub.
[:custom-arrow: View the Source Code](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank}
- :octicons-code-16:{ .lg .middle } **Alternative Implementation**
---
Visit the `beacon` repository on GitHub to learn more about Beacon, an alternative highly available, reduced-latency version of the Wormhole Spy.
[:custom-arrow: Get Started with Pyth Beacon](https://github.com/pyth-network/beacon)
- :octicons-book-16:{ .lg .middle } **Discover Wormhole Queries**
---
For an alternative option to on-demand access to Guardian-attested multichain data, see the Wormhole Queries page. Queries provide a simple, REST endpoint style developer experience.
[:custom-arrow: Explore Queries](/docs/products/queries/overview/)
## Next Steps
- :octicons-code-16:{ .lg .middle } **Run a Spy**
---
Learn how to run the needed infrastructure to spin up a Spy daemon locally and subscribe to a stream of Verifiable Action Approvals (VAAs).
[:custom-arrow: Spin Up a Spy](/docs/protocol/infrastructure-guides/run-spy/)
- :octicons-code-16:{ .lg .middle } **Use Queries**
---
For access to real-time network data without infrastructure overhead, follow this guide and use Wormhole Query to construct a query, make a request, and verify the response.
[:custom-arrow: Get Started with Queries](/docs/products/queries/guides/use-queries/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/ecosystem){target=\_blank}
---
Page Title: Supported Networks
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-reference-supported-networks.md
- Canonical (HTML): https://wormhole.com/docs/products/reference/supported-networks/
- Summary: Learn about the networks each Wormhole product supports, and explore links to documentation, official websites, and block explorers.
- Word Count: 10869; Token Estimate: 29569
# Supported Networks
Wormhole supports many blockchains across mainnet, testnet, and devnets. You can use these tables to verify if your desired chains are supported by the Wormhole products you plan to include in your integration.
## Supported Networks by Product
### Connect
### NTT
### WTT
### CCTP
=== "CCTP v1"
=== "CCTP v2"
### EVM
### SVM
### AVM
### CosmWasm
### Move VM
### NEAR VM
### Sui Move VM
- :octicons-book-16:{ .lg .middle } **Guardians**
---
Explore Wormhole's Guardian Network, a decentralized system for secure, scalable cross-chain communication across various blockchain ecosystems.
[:custom-arrow: Learn About Guardians](/docs/protocol/infrastructure/guardians/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Dev Arena**
---
A structured learning hub with hands-on tutorials across the Wormhole ecosystem.
[:custom-arrow: Explore the Dev Arena](https://arena.wormhole.com/ecosystem){target=\_blank}
---
Page Title: Wormhole Connect
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-connect-overview.md
- Canonical (HTML): https://wormhole.com/docs/products/connect/overview/
- Summary: With Wormhole Connect, you can seamlessly bridge digital assets and data across a wide range of supported blockchain networks.
- Word Count: 515; Token Estimate: 875
# Connect Overview
With the Wormhole Connect widget, you can enable users to perform multichain asset transfers directly within your application. Connect simplifies the complexity of bridging, offering a single, intuitive point of interaction for moving assets across diverse blockchains. This empowers you to access liquidity and opportunities across any connected network seamlessly.
## Key Features
Connect's notable features include:
- **In-app multichain transfers**: Bridge assets without leaving your app.
- **Customizable features**: Specify chains and custom RPCs, manage tokens, and select bridging [routes](/docs/products/connect/concepts/routes/){target=\_blank} such as WTT, CCTP, or NTT.
- **Customizable UI**: Style the bridge interface to match your brand.
- **Optional destination gas**: Provide gas for initial transactions on the target chain.
- **Wrapped and native assets support**: Supports both wrapped and native tokens and integrates with Settlement.
Be sure to check the [Feature Support Matrix](/docs/products/connect/reference/support-matrix/#feature-support-matrix){target=\_blank} to find out which routes and features are supported for each chain.
## How It Works
When a user initiates a multichain transfer, Connect walks them through key steps and automates the transfer process behind the scenes, including:
1. **Initiating the transfer**: Connect your chosen wallet to the source chain, select asset and source chain for the transfer.
2. **Finalize transfer setup**: Connect the destination wallet, select the target chain and select a bridging route (manual or automatic).
3. **Transaction submission on source chain**: Confirms the transfer details to trigger the asset lock or deposit on the initial blockchain. Connect will guide you through the transaction process.
4. **VAA or attestation creation**: Wormhole [Guardians](/docs/protocol/infrastructure/guardians/){target=\_blank} observe the source transaction and produce a [Verifiable Action Approval (VAA)](/docs/protocol/infrastructure/vaas/){target=\_blank}.
5. **Relaying to destination**: The VAA or attestation is automatically relayed to the destination chain.
6. **Verification on destination**: Contracts on the target chain receive and verify the incoming VAA.
7. **Asset release/minting**: Upon successful verification, the equivalent assets are either released or minted on the target chain and delivered to your wallet.
!!! tip
If you want more hands on experience with Connect, checkout [Portal Bridge](https://portalbridge.com/){target=\_blank}.
## Use Cases
Here are some key use cases that highlight the power and versatility of Connect:
- **Cross-Chain Swaps and Liquidity Aggregation**
- **[Connect](/docs/products/connect/get-started/)**: Handles user-friendly asset transfers.
- **[Native Token Transfers](/docs/products/token-transfers/native-token-transfers/overview/)**: Moves native assets across chains.
- **[Queries](/docs/products/queries/overview/)**: Fetches real-time prices for optimal trade execution.
- **Cross-Chain Payment Widgets**
- **[Connect](/docs/products/connect/get-started/)**: Facilitates seamless payments in various tokens.
- **[Native Token Transfers](/docs/products/token-transfers/native-token-transfers/overview/)**: Ensures direct, native asset transfers.
- **Web3 Game Asset Transfers**
- **[Connect](/docs/products/connect/get-started/)**: Provide a user-friendly way to move game tokens across chains.
- **[Wrapped Token Transfers](/docs/products/token-transfers/wrapped-token-transfers/overview/)**: Handle the underlying lock-and-mint logic securely.
## Next Steps
Add Connect to your app with these key setup steps:
[timeline(docs/.snippets/text/products/connect/overview/connect-timeline.json)]
---
Page Title: Wormhole Connect Migration Guides
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-connect-guides-upgrade.md
- Canonical (HTML): https://wormhole.com/docs/products/connect/guides/upgrade/
- Summary: Step-by-step guidance for migrating between major versions of Wormhole Connect, including configuration changes and route updates.
- Word Count: 3270; Token Estimate: 6442
# Wormhole Connect Migration Guides
This page collects step-by-step migration guides for major versions of Wormhole Connect. Choose the section that matches the version you are upgrading from:
- [V5 → V6](#v5-to-v6) - Default automatic routes replaced by [Executor](/docs/products/messaging/guides/executor/)-powered routes.
- [V0/V1/V2 → V3](#v0-v1-v2-to-v3) - Configuration restructure (`networks` → `chains`, capitalized chain names, route plugin system, consolidated `ui` properties).
## V5 to V6 {: #v5-to-v6 }
Wormhole Connect v6 removes the legacy "automatic" routes in favor of [Executor](/docs/products/messaging/guides/executor/)-powered replacements. **Most integrators need no code changes** - default usage and `DEFAULT_ROUTES` are wired to the new routes automatically.
The breaking change was introduced in [PR #4025](https://github.com/wormhole-foundation/wormhole-connect/pull/4025){target=\_blank}. See the full [v6 release notes](https://github.com/wormhole-foundation/wormhole-connect/releases){target=\_blank} for additional context.
### Route Replacements
| Removed | Replacement |
|---|---|
| `AutomaticCCTPRoute` | `cctpV2FastExecutorRoute()`, `cctpV2StandardExecutorRoute()` |
| `AutomaticTokenBridgeRoute`, `TokenBridgeRoute` | `executorTokenBridgeRoute()` |
| `nttAutomaticRoute` | `nttExecutorRoute` |
Route name strings (used in `filterRoutes`, telemetry):
| Old | New |
|---|---|
| `AutomaticCCTP` | `CCTPV2FastExecutorRoute`, `CCTPV2StandardExecutorRoute` |
| `AutomaticTokenBridge` | `TokenBridgeExecutorRoute` |
| `AutomaticNtt` | `NttExecutorRoute` |
**Unchanged**: `CCTPRoute`, `TBTCRoute`, `nttManualRoute`, `nttExecutorRoute`, `nttRoutes`, and all Mayan and LiFi routes.
### When You Need to Change Code
You only need changes if you:
- Import any removed route by name.
- Build a custom `routes: [...]` array using a removed route.
- Compare against old route name strings (in `filterRoutes`, telemetry handlers, etc.).
Default usage (`` with no `routes` config) and `DEFAULT_ROUTES` are wired to the new routes automatically.
!!! tip "Note"
The new Executor routes are **factory functions** - invoke them with `()` when adding to a `routes` array. The legacy automatic routes were class constructors passed directly.
### Update the Connect Package
Install the v6 release:
```bash
npm install @wormhole-foundation/wormhole-connect@^6.0
```
### `DEFAULT_ROUTES` Has Been Updated
The default route set used when integrators don't specify a `routes` array now uses Executor-based routes:
=== "v5.x"
```typescript
DEFAULT_ROUTES = [
AutomaticCCTPRoute,
CCTPRoute,
AutomaticTokenBridgeRoute,
TokenBridgeRoute,
TBTCRoute,
];
```
=== "v6.x"
```typescript
DEFAULT_ROUTES = [
cctpV2FastExecutorRoute(),
cctpV2StandardExecutorRoute(),
CCTPRoute,
executorTokenBridgeRoute(),
TBTCRoute,
];
```
If you rely on `DEFAULT_ROUTES` without overriding it, no code changes are required.
### Update Custom `routes` Arrays
If you pass a custom `routes` array, replace removed routes with their Executor equivalents and remember to invoke the new factory functions with `()`:
=== "v5.x"
```typescript
import {
AutomaticCCTPRoute,
CCTPRoute,
AutomaticTokenBridgeRoute,
} from '@wormhole-foundation/wormhole-connect';
const config = {
routes: [AutomaticCCTPRoute, CCTPRoute, AutomaticTokenBridgeRoute],
};
```
=== "v6.x"
```typescript
import {
cctpV2FastExecutorRoute,
cctpV2StandardExecutorRoute,
CCTPRoute,
executorTokenBridgeRoute,
} from '@wormhole-foundation/wormhole-connect';
const config = {
routes: [
cctpV2FastExecutorRoute(),
cctpV2StandardExecutorRoute(),
CCTPRoute,
executorTokenBridgeRoute(),
],
};
```
### Update NTT Routes
If you use the `nttRoutes(...)` helper, no changes are needed. Otherwise, swap `nttAutomaticRoute` for `nttExecutorRoute`:
=== "v5.x"
```typescript
import { nttAutomaticRoute } from '@wormhole-foundation/wormhole-connect/ntt';
const config = {
routes: [nttAutomaticRoute(myNttConfig)],
};
```
=== "v6.x"
```typescript
import { nttExecutorRoute } from '@wormhole-foundation/wormhole-connect/ntt';
const config = {
routes: [nttExecutorRoute({ ntt: myNttConfig })],
};
```
## V0/V1/V2 to V3 {: #v0-v1-v2-to-v3 }
The Wormhole Connect feature has been updated to **version 3.0**, introducing a modernized design and improved routing for faster native-to-native token transfers. This stable release comes with several breaking changes in how to configure the application, requiring minor updates to your integration.
This guide will help you migrate to the new version in just a few simple steps. By following this migration guide, you'll learn how to:
- Update to the latest Connect package.
- Apply configuration changes to the `WormholeConnectConfig` object.
- Understand new routing capabilities and plugin options.
These updates ensure better performance and a smoother integration experience.
!!! tip "Note"
Connect versions v1.x and v2.x share the same configuration structure. This guide outlines a unified upgrade process to v3.x, regardless of whether you're using v0.x, v1.x, or v2.x.
## Update the Connect Package
To begin the migration process, update the Connect [**npm package**](https://www.npmjs.com/package/@wormhole-foundation/wormhole-connect){target=\_blank} to the latest version 3.0. Updating to the latest version provides access to the newest features and improvements, including the modernized design and enhanced routing capabilities.
Run the following command in your terminal:
```bash
npm install @wormhole-foundation/wormhole-connect@^3.0
```
This command installs the latest stable version of Wormhole Connect and prepares your environment for the new configuration changes.
## Update the `WormholeConnectConfig` Object
In version 3.0, the `config.WormholeConnectConfig` object underwent several breaking changes. Most of these changes are minor and can be applied quickly. Below is a summary of the key changes, followed by detailed examples.
### Summary of Breaking Changes
- Chain names are now capitalized. For example:`solana` → `Solana`.
- `env` renamed to `network` and is now capitalized. For example: `mainnet` → `Mainnet`.
- `networks` renamed to `chains`, with capitalized names.
- `routes` updated to use route plugins.
- `nttGroups` removed in favor of route plugin configuration.
- `tokensConfig` updated, with a new key `wrappedTokens` added.
- Many UI-related properties consolidated under a top-level `ui` key.
- `customTheme` and `mode` were removed, replaced by a top-level `theme` property.
These changes are explained in more detail below, with examples for easy reference.
### Capitalize Chain Names
In version 3.0, chain names are now consistent with the `Chain` type from the [Wormhole TypeScript SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts){target=\_blank}, and must be capitalized. This affects all config properties where a chain is referenced, including `rpcs`, `rest`, `graphql`, and `chains`.
=== "v0.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
rpcs: {
ethereum: 'INSERT_ETH_RPC_URL',
solana: 'INSERT_SOLANA_RPC_URL',
},
};
```
=== "v1.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
rpcs: {
Ethereum: 'INSERT_ETH_RPC_URL',
Solana: 'INSERT_SOLANA_RPC_URL',
},
};
```
=== "v3.x"
```typescript
import { type config } from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
rpcs: {
Ethereum: 'INSERT_ETH_RPC_URL',
Solana: 'INSERT_SOLANA_RPC_URL',
},
};
```
You can find the complete list of supported chain names in the [Wormhole TypeScript SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/main/core/base/src/constants/chains.ts#L6-L71){target=\_blank}.
### Rename `env` to `network`
The `env` property has been renamed to `network`, with capitalized values. This change affects how you configure Testnet and Mainnet environments.
=== "v0.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
env: 'testnet',
};
```
=== "v1.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
network: 'Testnet',
};
```
=== "v3.x"
```typescript
import { type config } from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
network: 'Testnet',
};
```
If you don’t explicitly set the `network` value, Connect will default to `Mainnet`.
```typescript
// Defaults to Mainnet
const config: config.WormholeConnectConfig = {};
```
For more information, refer to the [network constants list](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/main/core/base/src/constants/networks.ts){target=\_blank}.
### Rename `networks` to `chains`
The `networks` property, which allowed whitelisting chains, is now renamed `chains`, and the chain names are capitalized.
=== "v0.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
networks: ['solana', 'ethereum'],
};
```
=== "v1.x"
```typescript
import { WormholeConnectConfig } from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
chains: ['Solana', 'Ethereum'],
};
```
=== "v3.x"
```typescript
import { type config } from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
chains: ['Solana', 'Ethereum'],
};
```
### Update `routes` to Use Route Plugins
The `routes` property in Connect version 3.0 has significantly improved. Previously, `routes` was a simple array of strings. The latest version has been transformed into a flexible plugin system, allowing you to include specific routes for various protocols.
By default, if no `routes` property is set, Connect will provide routes for two core protocols:
- [Wrapped Token Transfers (WTT)](/docs/products/token-transfers/wrapped-token-transfers/overview/){target=\_blank}
- [CCTP](/docs/products/cctp-bridge/overview/){target=\_blank}
For most use cases, integrators require more than the default routes. The new `routes` property allows you to specify which protocols to include and exclude any routes unnecessary for your application, including both default and third-party routes.
#### Available `route` Plugins
The `@wormhole-foundation/wormhole-connect` package offers a variety of `route` plugins to give you flexibility in handling different protocols. You can choose from the following `route` exports for your integration:
???- tip "`route` Plugins"
- **`TokenBridgeRoute`**: Manually redeemed WTT route.
- **`AutomaticTokenBridgeRoute`**: Automatically redeemed (relayed) WTT route.
- **`CCTPRoute`**: Manually redeemed CCTP route.
- **`AutomaticCCTPRoute`**: Automatically redeemed (relayed) CCTP route.
- **`DEFAULT_ROUTES`**: Array containing the four preceding routes (TokenBridgeRoute, AutomaticTokenBridgeRoute, CCTPRoute, AutomaticCCTPRoute).
- **`nttAutomaticRoute(nttConfig)`**: Function that returns the automatically-redeemed (relayed) Native Token Transfer (NTT) route.
- **`nttManualRoute(nttConfig)`**: Function that returns the manually-redeemed NTT route.
- **`nttExecutorRoute(nttConfig)`**: Function that returns the Executor-powered NTT route for one-click transfers.
- **`MayanRoute`**: Route that offers multiple Mayan protocols.
- **`MayanRouteSWIFT`**: Route for Mayan’s Swift protocol only.
- **`MayanRouteMCTP`**: Route for Mayan’s MCTP protocol only.
- **`MayanRouteWH`**: Route for Mayan’s original Wormhole transfer protocol.
In addition to these routes, developers can create custom routes for their own Wormhole-based protocols. For examples, refer to the [NTT](https://github.com/wormhole-foundation/native-token-transfers/tree/main/sdk/route){target=\_blank} and the [Mayan](https://github.com/mayan-finance/wormhole-sdk-route){target=\_blank} example GitHub repositories.
For further details on the Route plugin interface, refer to the [Wormhole TypeScript SDK route code](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/main/connect/src/routes/route.ts){target=\_blank}.
Now that you know the available `route` plugins, let's explore some examples of configuring them.
#### Example: Offer Only CCTP Transfers
To configure Connect to offer only USDC transfers via the CCTP route, use the following configuration:
```typescript
import WormholeConnect, {
AutomaticCCTPRoute,
type config,
} from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
routes: [AutomaticCCTPRoute],
};
;
```
#### Example: Offer All Default Routes and Third-Party Plugins
In this example, Connect is configured with routes for both default protocols (WTT and CCTP), as well as third-party protocols like [Native Token Transfers (NTT)](/docs/products/token-transfers/native-token-transfers/overview/){target=\_blank} and [Mayan Swap](https://swap.mayan.finance/){target=\_blank}.
```typescript
import WormholeConnect, {
DEFAULT_ROUTES,
MayanRouteSWIFT,
type config,
} from '@wormhole-foundation/wormhole-connect';
import { nttExecutorRoute } from '@wormhole-foundation/wormhole-connect/ntt';
import { myNttConfig } from './consts'; // Custom NTT configuration
const config: config.WormholeConnectConfig = {
routes: [...DEFAULT_ROUTES, nttExecutorRoute({ ntt: myNttConfig }), MayanRouteSWIFT],
};
;
```
This flexible plugin allows you to combine default routes (such as WTT and CCTP) with third-party protocols, offering complete control over which routes are available in your application.
### Update the `tokensConfig` Structure
In Connect version 3.0, the `tokensConfig` property has been updated to simplify the structure and improve flexibility for token handling across chains. The previous configuration has been streamlined, and a new key, `wrappedTokens,` has been introduced to handle foreign assets more effectively.
Key Changes to `tokensConfig`:
- **Capitalized chain names**: All chain names, like `ethereum`, must now be capitalized, such as `Ethereum`, to maintain consistency with the rest of the Wormhole SDK.
- **`wrappedTokens`**: This new key replaces `foreignAssets` and defines the wrapped token addresses on foreign chains, making it easier to manage cross-chain transfers. It consolidates the wrapped token addresses into a cleaner structure. These addresses must be specified to enable token transfers to and from the foreign chain via WTT routes.
- **Simplified decimals**: Instead of using a map of decimal values for different chains, you now only need to provide a single decimals value for the token's native chain.
=== "v0.x"
In the old structure, the `foreignAssets` field defined the token’s presence on other chains, and `decimals` were mapped across multiple chains.
```typescript
import WormholeConnect, {
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
tokensConfig: {
WETH: {
key: 'WETH',
symbol: 'WETH',
nativeChain: 'ethereum',
icon: Icon.ETH,
tokenId: {
chain: 'ethereum',
address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
},
coinGeckoId: 'ethereum',
color: '#62688F',
decimals: { Ethereum: 18, default: 8 },
foreignAssets: {
Solana: {
address: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
decimals: 8,
},
},
},
},
};
```
=== "v1.x"
In v1.0, `foreignAssets` has been replaced with `wrappedTokens`, simplifying token transfers across chains by directly mapping wrapped token addresses. The `decimals` value is now a simple number representing the token’s decimals on its native chain.
```typescript
import WormholeConnect, {
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
tokensConfig: {
WETH: {
key: 'WETH',
symbol: 'WETH',
nativeChain: 'Ethereum', // Chain name now capitalized
icon: Icon.ETH,
tokenId: {
chain: 'Ethereum',
address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
},
coinGeckoId: 'ethereum',
color: '#62688F',
decimals: 18, // Simplified decimals field
},
},
wrappedTokens: {
WETH: {
Solana: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
/* additional chains */
},
},
};
```
=== "v3.x"
In v3.0, `foreignAssets` has been replaced with `wrappedTokens`, simplifying token transfers across chains by directly mapping wrapped token addresses. The `decimals` value is now a simple number representing the token’s decimals on its native chain.
```typescript
import WormholeConnect, {
type config,
} from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
tokensConfig: {
WETH: {
key: 'WETH',
symbol: 'WETH',
nativeChain: 'Ethereum', // Chain name now capitalized
icon: Icon.ETH,
tokenId: {
chain: 'Ethereum',
address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
},
coinGeckoId: 'ethereum',
color: '#62688F',
decimals: 18, // Simplified decimals field
},
},
wrappedTokens: {
WETH: {
Solana: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
/* additional chains */
},
},
};
```
### Update NTT Configuration
In Connect version 3.0, the `nttGroups` property, which was used to configure Native Token Transfers (NTT), has been removed. Instead, the NTT configuration is passed directly to the NTT route constructor. This update simplifies the setup and provides more flexibility for defining NTT routes.
Key changes:
- **Removed `nttGroups`**: The `nttGroups` property has been removed from the configuration and is now passed as an argument to the `nttExecutorRoute` function.
- **Direct NTT route configuration**: NTT routes are now defined more explicitly, allowing for a more organized structure when specifying tokens, chains, and managers.
This change simplifies the configuration process by providing a cleaner, more flexible way to handle NTT routes across different chains.
=== "v0.x"
In the previous version, `nttGroups` defined the NTT managers and transceivers for different tokens across multiple chains.
```typescript
import WormholeConnect, {
nttRoutes,
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
nttGroups: {
Lido_wstETH: {
nttManagers: [
{
chainName: 'ethereum',
address: '0xb948a93827d68a82F6513Ad178964Da487fe2BD9',
tokenKey: 'wstETH',
transceivers: [
{
address: '0xA1ACC1e6edaB281Febd91E3515093F1DE81F25c0',
type: 'wormhole',
},
],
},
{
chainName: 'bsc',
address: '0x6981F5621691CBfE3DdD524dE71076b79F0A0278',
tokenKey: 'wstETH',
transceivers: [
{
address: '0xbe3F7e06872E0dF6CD7FF35B7aa4Bb1446DC9986',
type: 'wormhole',
},
],
},
],
},
},
};
```
=== "v1.x"
In v1.0, `nttGroups` has been removed, and the configuration is passed to the NTT route constructor as an argument. The tokens and corresponding transceivers are now clearly defined within the `nttRoutes` configuration.
```typescript
import WormholeConnect, {
nttRoutes,
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
routes: [
...nttRoutes({
tokens: {
Lido_wstETH: [
{
chain: 'Ethereum',
manager: '0xb948a93827d68a82F6513Ad178964Da487fe2BD9',
token: '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0',
transceiver: [
{
address: '0xA1ACC1e6edaB281Febd91E3515093F1DE81F25c0',
type: 'wormhole',
},
],
},
{
chain: 'Bsc',
manager: '0x6981F5621691CBfE3DdD524dE71076b79F0A0278',
token: '0x26c5e01524d2E6280A48F2c50fF6De7e52E9611C',
transceiver: [
{
address: '0xbe3F7e06872E0dF6CD7FF35B7aa4Bb1446DC9986',
type: 'wormhole',
},
],
},
],
},
}),
/* other routes */
],
};
```
=== "v3.x"
In v3.0, `nttGroups` has been removed, and the configuration is passed to the NTT route constructor as an argument. The tokens and corresponding transceivers are now clearly defined within the `nttExecutorRoute` configuration.
```typescript
import WormholeConnect, {
type config,
} from '@wormhole-foundation/wormhole-connect';
import { nttExecutorRoute } from '@wormhole-foundation/wormhole-connect/ntt';
const config: config.WormholeConnectConfig = {
routes: [
nttExecutorRoute({
ntt: {
tokens: {
Lido_wstETH: [
{
chain: 'Ethereum',
manager: '0xb948a93827d68a82F6513Ad178964Da487fe2BD9',
token: '0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0',
transceiver: [
{
address: '0xA1ACC1e6edaB281Febd91E3515093F1DE81F25c0',
type: 'wormhole',
},
],
},
{
chain: 'Bsc',
manager: '0x6981F5621691CBfE3DdD524dE71076b79F0A0278',
token: '0x26c5e01524d2E6280A48F2c50fF6De7e52E9611C',
transceiver: [
{
address: '0xbe3F7e06872E0dF6CD7FF35B7aa4Bb1446DC9986',
type: 'wormhole',
},
],
},
],
},
},
}),
/* other routes */
],
};
```
In this new structure, NTT routes are passed directly through the `nttExecutorRoute` function, with the `token`, `chain`, `manager` and `transceiver` clearly defined for each supported asset.
### Update UI Configuration
In Connect version 3.0, the user interface configuration has been significantly updated. Several previously scattered UI properties have now been consolidated under a new `ui` key, making the UI configuration cleaner and easier to manage.
Key UI changes:
- **Consolidated UI properties**: Many UI-related properties moved under a new top-level ui key for better organization.
- **Removed `customTheme` and `mode`**: These properties have been removed in favor of a new top-level prop called `theme`, which simplifies theming and allows dynamic switching between themes.
#### UI Properties
The following properties that were previously defined at the root level of the configuration are now part of the `ui` key:
- **`explorer` → `ui.explorer`**: Specifies the explorer to use for viewing transactions.
- **`bridgeDefaults` → `ui.defaultInputs`**: Sets default input values for the bridge, such as the source and destination chains and token.
- **`pageHeader` → `ui.pageHeader`**: Sets the title and header for the page.
- **`menu` → `ui.menu`**: Defines the menu items displayed in the interface.
- **`searchTx` → `ui.searchTx`**: Configures the transaction search functionality.
- **`partnerLogo` → `ui.partnerLogo`**: Displays a partner's logo on the interface.
- **`walletConnectProjectId` → `ui.walletConnectProjectId`**: Integrates WalletConnect into the UI.
- **`showHamburgerMenu` → `ui.showHamburgerMenu`**: Enables or disables the hamburger menu for navigation.
Additionally, there are two new properties under `ui`:
- **`ui.title`**: Sets the title rendered in the top left corner of the UI. The default is "Wormhole Connect".
- **`ui.getHelpUrl`**: URL that Connect will render when an unknown error occurs, allowing users to seek help. This can link to a Discord server or any other support channel.
```typescript
import WormholeConnect, {
type config,
} from '@wormhole-foundation/wormhole-connect';
const config: config.WormholeConnectConfig = {
ui: {
title: 'My Custom Bridge Example',
getHelpUrl: 'https://examplehelp.com/',
menu: [
{
label: 'Support',
href: 'https://examplehelp.com/support',
target: '_blank',
order: 1, // Order of appearance in the menu
},
{
label: 'About',
href: 'https://examplehelp.com/about',
target: '_blank',
order: 2,
},
],
showHamburgerMenu: false,
},
};
```
#### UI Configuration
In the old structure, UI-related settings like `explorer` and `bridgeDefaults` were defined at the root level of the configuration. In version 3.0, these properties are now organized under the `ui` key, improving the configuration's readability and manageability.
=== "v0.x"
```typescript
const config: WormholeConnectConfig = {
bridgeDefaults: {
fromNetwork: 'solana',
toNetwork: 'ethereum',
tokenKey: 'USDC',
requiredNetwork: 'solana',
},
showHamburgerMenu: true,
};
```
=== "v1.x"
```typescript
const config: WormholeConnectConfig = {
ui: {
defaultInputs: {
fromChain: 'Solana', // Chain names now capitalized
toChain: 'Ethereum',
tokenKey: 'USDC',
requiredChain: 'Solana',
},
showHamburgerMenu: true,
},
};
```
=== "v3.x"
```typescript
const config: config.WormholeConnectConfig = {
ui: {
defaultInputs: {
fromChain: 'Solana', // Chain names now capitalized
toChain: 'Ethereum',
tokenKey: 'USDC',
requiredChain: 'Solana',
},
showHamburgerMenu: true,
},
};
```
#### Remove `customTheme` and `mode` Properties
In version 3.0, the `customTheme` and `mode` properties, which were previously used to set themes, have been removed. They have been replaced by a new top-level prop called `theme`, which allows for more flexibility and dynamic updates to themes.
Important details:
- The `theme` prop is not part of the `config` object and is passed separately to Connect.
- `config` cannot be modified after Connect has mounted, but the `theme` can be updated dynamically to support changes such as switching between light and dark modes or updating color schemes.
=== "v0.x"
```typescript
import WormholeConnect, {
WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';
const config: WormholeConnectConfig = {
customTheme: {
primaryColor: '#4266f5',
secondaryColor: '#ff5733',
},
mode: 'dark',
};
;
```
=== "^v1.x"
```typescript
import WormholeConnect, {
WormholeConnectTheme,
} from '@wormhole-foundation/wormhole-connect';
const theme: WormholeConnectTheme = {
mode: 'dark', // Can be dynamically changed
font: 'Arial',
button: {
primary: '#4266f5',
},
};
;
```
### Removed Configuration Properties
Several configuration properties have been removed in Connect version 3.0. These keys no longer have any effect, and providing values for them in the configuration will not result in any changes.
Removed config keys:
- `cta`
- `cctpWarning`
- `pageSubHeader`
- `moreTokens`
- `moreChains`
- `ethBridgeMaxAmount`
- `wstETHBridgeMaxAmount`
- `customTheme`
- `mode`
If your current setup includes any of these properties, you can safely remove them, as they are no longer supported in v3.0.
## Use the CDN-Hosted Version of Wormhole Connect
For those using the CDN-hosted version of Wormhole Connect, the package's installation and integration have been updated. You must install the Connect package from npm and use the new `wormholeConnectHosted` utility function.
### Install and Integrate the Hosted Version
1. Install the Connect package via npm:
```bash
npm install @wormhole-foundation/wormhole-connect@^3.0
```
2. After installing the package, you can embed Connect into your page by adding the following code:
```typescript
import { wormholeConnectHosted } from '@wormhole-foundation/wormhole-connect';
const container = document.getElementById('connect')!;
wormholeConnectHosted(container);
```
### Example: Custom Configuration for Hosted Version
The `wormholeConnectHosted` function accepts two parameters: `config` and `theme`. This allows you to customize the routes and apply a theme directly within the hosted version. Here’s an example of how you can pass a custom configuration:
```typescript
import {
wormholeConnectHosted,
MayanRoute,
} from '@wormhole-foundation/wormhole-connect';
const container = document.getElementById('connect')!;
wormholeConnectHosted(container, {
config: {
routes: [MayanRoute],
eventHandler: (e) => {
console.log('Connect event', e);
},
},
theme: {
background: {
default: '#004547',
},
},
});
```
In this example, the `config` object defines the routes (in this case, using the Mayan route), while the `theme` object allows customization of the Connect interface (e.g., background color).
---
Page Title: Wormhole Finality | Consistency Levels
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-reference-consistency-levels.md
- Canonical (HTML): https://wormhole.com/docs/products/reference/consistency-levels/
- Summary: This page documents how long to wait for finality before signing, based on each chain’s consistency (finality) level and consensus mechanism.
- Word Count: 2208; Token Estimate: 5327
# Wormhole Finality
Wormhole allows integrators to specify the finality level at which a VAA is verified. This determines how long the Guardians wait before attesting to a message.
These options provide different trade-offs between latency and re-org resistance:
- `instant` is sufficient when low latency is required and limited reorg risk is acceptable.
- `safe` provides additional protection while maintaining reasonable latency.
- `finalized` offers the strongest guarantees but increases confirmation time.
`finalized` provides the strongest protection against chain re-orgs. Selecting `instant`, `safe`, or a custom finality level increases exposure to re-org risk and should be evaluated carefully based on the application's risk profile.
!!! warning
Some Wormhole-supported EVM chains support setting a custom finality level. Wormhole Contributors recommend using this advanced feature with caution. Choosing a level of finality other than `finalized` — including `instant`, `safe`, or any custom configuration — on EVM chains exposes you to [re-org risk](https://www.alchemy.com/overviews/what-is-a-reorg){target=\_blank}. This is especially dangerous when moving assets cross-chain, because assets released or minted on the destination chain may not have been burned or locked on the source chain. This risk can extend to other types of cross-chain data, depending on your application.
Assumption of risk; no warranty; no liability. By selecting a Custom finality level, you acknowledge and accept all risk of chain re-orgs/rollbacks and any resulting loss, imbalance, or data inconsistency. Wormhole contributors, and their affiliates (“Wormhole Parties”) provide this feature “as is,” make no warranties of any kind, and will not be liable for any losses or damages arising from your selection or use of Custom finality. You are solely responsible for appropriate safeguards (e.g., caps, delays, monitoring, circuit breakers).
See the [Custom Consistency Levels](#custom-consistency-levels-advanced) section.
The following table documents each chain's `consistencyLevel` values (i.e., finality reached before signing). The consistency level defines how long the Guardians should wait before signing a VAA. The finalization time depends on the specific chain's consensus mechanism. The consistency level is a `u8`, so any single byte may be used. However, a small subset has particular meanings. If the `consistencyLevel` isn't one of those specific values, the `Otherwise` column describes how it's interpreted.
| Chain | Instant | Safe | Finalized | Custom | Otherwise | Time to Finalize | Details | | Ethereum | 200 | 201 | 202 | 203 | finalized | ~ 19min | Details |
| Solana | | 0 | 1 | N/A | | ~ 14s | Details |
| 0G (Zero Gravity) | | | 0 | N/A | | ~ 69min | |
| Algorand | | | 0 | N/A | | ~ 4s | Details |
| Aptos | | | 0 | N/A | | ~ 4s | Details |
| Arbitrum | 200 | 201 | | N/A | finalized | ~ 18min | Details |
| Avalanche | 200 | | | N/A | finalized | ~ 2s | Details |
| Base | 200 | 201 | | N/A | finalized | ~ 18min | |
| Berachain | 200 | | | N/A | finalized | ~ 4s | |
| BNB Smart Chain | 200 | 201 | | N/A | finalized | ~ 12s | Details |
| Celestia | | | 0 | N/A | | ~ 5s | |
| Celo | 200 | | | N/A | finalized | ~ 10s | |
| Converge | | | 0 | N/A | | ~ 7min | |
| Cosmos Hub | | | 0 | N/A | | ~ 5s | |
| CreditCoin | | | 0 | N/A | | ~ 60s | |
| Dymension | | | 0 | N/A | | ~ 5s | |
| Evmos | | | 0 | N/A | | ~ 2s | |
| Fantom | 200 | | | N/A | finalized | ~ 5s | |
| Fogo | | | 0 | N/A | | ~ 14s | |
| HyperEVM :material-alert:{ title='⚠️ The HyperEVM integration is experimental, as its node software is not open source. Use Wormhole messaging on HyperEVM with caution.' } | | | 0 | N/A | | ~ 2s | |
| Injective | | | 0 | N/A | | ~ 3s | |
| Ink | | | 0 | N/A | | ~ 9min | |
| Kaia | 200 | | | N/A | finalized | ~ 1s | |
| Kujira | | | 0 | N/A | | ~ 3s | |
| Mantle | 200 | 201 | | N/A | finalized | ~ 18min | |
| MegaETH | | | 0 | N/A | | ~ 69min | |
| Mezo | | | 0 | N/A | | ~ 8s | |
| Moca | | | 0 | N/A | | ~ 1s | |
| Monad | | | 0 | N/A | | ~ 2s | |
| Moonbeam | 200 | 201 | | N/A | finalized | ~ 24s | Details |
| NEAR | | | 0 | N/A | | ~ 2s | Details |
| Neutron | | | 0 | N/A | | ~ 5s | |
| Optimism | 200 | 201 | | N/A | finalized | ~ 18min | |
| Osmosis | | | 0 | N/A | | ~ 6s | |
| Plasma | | | 0 | N/A | | ~ 3s | |
| Plume | | | 0 | N/A | | ~ 18min | |
| Polygon | 200 | | | N/A | finalized | ~ 6s | Details |
| Scroll | 200 | | | N/A | finalized | ~ 50min | |
| Sei | | | 0 | N/A | | ~ 1s | |
| SeiEVM | | | 0 | N/A | | ~ 1s | |
| Sonic | | | 0 | N/A | | ~ 1s | |
| Stacks | | | 0 | N/A | | ~ 61min | |
| Stargaze | | | 0 | N/A | | ~ 5s | |
| Sui | | | 0 | N/A | | ~ 3s | Details |
| Unichain | 200 | 201 | | N/A | finalized | ~ 18min | |
| World Chain | | | 0 | N/A | | ~ 18min | |
| X Layer | 200 | 201 | | N/A | finalized | ~ 16min | |
| Xrpl | | | 0 | N/A | | ~ 4s | |
| XRPL-EVM | | | 0 | N/A | | ~ 10s | |
## Custom Consistency Levels (Advanced)
On supported EVM chains (currently Ethereum and Linea), integrators may specify a custom consistency level. See the [white paper](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0001_generic_message_passing.md#custom-handling){target=\_blank} to learn how this works.
!!!warning
**Custom finality is an advanced feature and Wormhole Contributors recommend to use this with caution.** Custom consistency should only be used when standard finality options do not meet the application’s requirements. Most integrations **do not** require custom consistency levels. Using custom finality exposes users to re-org risk. Lower finality levels increase the chance that a source-chain transaction may be reverted after assets are released or minted on the destination chain. Custom finality should be used only with a clear understanding of these risks.
How to select a Custom Finality Level:
- For L1s: Wormhole Contributors recommend referring to information on forked blocks in blockchain explorers such as [Etherscan](https://etherscan.io/blocks_forked?p=1){target=\_blank}, [Polygonscan](https://polygonscan.com/blocks_forked){target=\_blank}, and others, paying specific attention to the “ReorgDepth” column. Polygon, for instance, has been known to have reorgs with a depth of up to 128 blocks!
- For L2s: Wormhole Contributors recommend reviewing L2 block explorers as well as details around whether the sequencer is centralized and how the L2 RPC node treats finality. Typically, the risks one is exposed to when not waiting for full finality from an L2 are: (1) a centralized (or compromised) sequencer censoring transactions, (2) re-orgs if sequencing is not centralized, and (3) L1 reorg risk and the L2 sequencer not re-submitting the transaction batch to the L1.
### CCL Contract Addresses
Custom Consistency Level (CCL) enables advanced finality control for EVM chains. CCL is currently supported on select EVM chains. The contract addresses below are the on-chain contracts queried when 203 (Custom) is used.
=== "Mainnet"
| Chain Name | Contract Address |
|---|
| Ethereum | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
| Linea | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
=== "Testnet"
| Chain Name | Contract Address |
|---|
| Ethereum | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
| Sepolia | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
| Linea | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
=== "Devnet"
| Chain Name | Contract Address |
|---|
| Ethereum | 0x6A4B4A882F5F0a447078b4Fd0b4B571A82371ec2 |
---
Page Title: Wormhole Formatted Addresses
- Resolved Markdown: https://wormhole.com/docs/ai/pages/products-reference-wormhole-formatted-addresses.md
- Canonical (HTML): https://wormhole.com/docs/products/reference/wormhole-formatted-addresses/
- Summary: Explanation of Wormhole formatted 32-byte hex addresses, their conversion, and usage across different blockchain platforms.
- Word Count: 799; Token Estimate: 1437
# Wormhole Formatted Addresses
Wormhole formatted addresses are 32-byte hex representations of addresses from any supported blockchain. Whether an address originates from EVM, Solana, Cosmos, or another ecosystem, Wormhole standardizes all addresses into this format to ensure cross-chain compatibility.
This uniform format is essential for smooth interoperability in token transfers and messaging across chains. Wormhole uses formatted addresses throughout the [Wormhole SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts){target=\_blank}, especially in cross-chain transactions, such as transfer functions that utilize the `bytes32` representation for recipient addresses.
## Platform-Specific Address Formats
Each blockchain ecosystem Wormhole supports has its method for formatting native addresses. To enable cross-chain compatibility, Wormhole converts these native addresses into the standardized 32-byte hex format.
Here’s an overview of the native address formats and how they are normalized to the Wormhole format:
| Platform | Native Address Format | Wormhole Formatted Address |
|-----------------|----------------------------------|----------------------------|
| EVM | Hex (e.g., 0x...) | 32-byte Hex |
| Solana | Base58 | 32-byte Hex |
| CosmWasm | Bech32 | 32-byte Hex |
| Algorand | Algorand App ID | 32-byte Hex |
| Sui | Hex | 32-byte Hex |
| Aptos | Hex | 32-byte Hex |
| Near | SHA-256 | 32-byte Hex |
These conversions allow Wormhole to interact seamlessly with various chains using a uniform format for all addresses.
### Address Format Handling
The Wormhole SDK provides mappings that associate each platform with its native address format. You can find this mapping in the Wormhole SDK file [`platforms.ts`](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/007f61b27c650c1cf0fada2436f79940dfa4f211/core/base/src/constants/platforms.ts#L93-L102){target=\_blank}:
```typescript
const platformAddressFormatEntries = [
['Evm', 'hex'],
['Solana', 'base58'],
['Cosmwasm', 'bech32'],
['Algorand', 'algorandAppId'],
['Sui', 'hex'],
['Aptos', 'hex'],
['Near', 'sha256'],
];
```
These entries define how the [`UniversalAddress`](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/007f61b27c650c1cf0fada2436f79940dfa4f211/core/definitions/src/universalAddress.ts#L23){target=\_blank} class handles different address formats based on the platform.
## Universal Address Methods
The `UniversalAddress` class is essential for working with Wormhole formatted addresses. It converts native blockchain addresses into the standardized 32-byte hex format used across Wormhole operations.
Key functions:
- **`new UniversalAddress()`**: Use the `UniversalAddress` constructor to convert native addresses into the Wormhole format.
```typescript
const universalAddress = new UniversalAddress('0x123...', 'hex');
```
- **`toUniversalAddress()`**: Converts a platform-specific address into the Wormhole formatted 32-byte hex address.
```typescript
const ethAddress: NativeAddress<'Evm'> = toNative('Ethereum', '0x0C9...');
const universalAddress = ethAddress.toUniversalAddress().toString();
```
- **`toNative()`**: Converts the Wormhole formatted address back to a native address for a specific blockchain platform.
```typescript
const nativeAddress = universalAddress.toNative('Evm');
```
- **`toString()`**: Returns the Wormhole formatted address as a hex string, which can be used in various SDK operations.
```typescript
console.log(universalAddress.toString());
```
These methods allow developers to convert between native addresses and the Wormhole format, ensuring cross-chain compatibility.
## Convert Between Native and Wormhole Formatted Addresses
The Wormhole SDK allows developers to easily convert between native addresses and Wormhole formatted addresses when building cross-chain applications.
### Convert a Native Address to a Wormhole Formatted Address
Example conversions for EVM and Solana:
=== "EVM"
```typescript
import { toNative } from '@wormhole-foundation/sdk-core';
const ethAddress: NativeAddress<'Evm'> = toNative(
'Ethereum',
'0x0C99567DC6f8f1864cafb580797b4B56944EEd28'
);
const universalAddress = ethAddress.toUniversalAddress().toString();
console.log('Universal Address (EVM):', universalAddress);
```
=== "Solana"
```typescript
import { toNative } from '@wormhole-foundation/sdk-core';
const solAddress: NativeAddress<'Solana'> = toNative(
'Solana',
'6zZHv9EiqQYcdg52ueADRY6NbCXa37VKPngEHaokZq5J'
);
const universalAddressSol = solAddress.toUniversalAddress().toString();
console.log('Universal Address (Solana):', universalAddressSol);
```
The result is a standardized address format that is ready for cross-chain operations.
### Convert Back to Native Addresses
Below is how you can convert a Wormhole formatted address back to an EVM or Solana native address:
```typescript
const nativeAddressEvm = universalAddress.toNative('Evm');
console.log('EVM Native Address:', nativeAddressEvm);
const nativeAddressSolana = universalAddress.toNative('Solana');
console.log('Solana Native Address:', nativeAddressSolana);
```
These conversions ensure that your cross-chain applications can seamlessly handle addresses across different ecosystems.
## Use Cases for Wormhole Formatted Addresses
### Cross-chain Token Transfers
Cross-chain token transfers require addresses to be converted into a standard format. For example, when transferring tokens from Ethereum to Solana, the Ethereum address is converted into a Wormhole formatted address to ensure compatibility. After the transfer, the Wormhole formatted address is converted back into the Solana native format.
### Smart Contract Interactions
In smart contract interactions, especially when building dApps that communicate across multiple chains, Wormhole formatted addresses provide a uniform way to reference addresses. This ensures that addresses from different blockchains can interact seamlessly, whether you're sending messages or making cross-chain contract calls.
### DApp Development
For cross-chain dApp development, Wormhole formatted addresses simplify handling user wallet addresses across various blockchains. This allows developers to manage addresses consistently, regardless of whether they work with EVM, Solana, or another supported platform.
### Relayers and Infrastructure
Finally, relayers and infrastructure components, such as Wormhole Guardians, rely on the standardized format to efficiently process and relay cross-chain messages. A uniform address format simplifies operations, ensuring smooth interoperability across multiple blockchains.