# Wormhole Developer Documentation (LLMS Format)
This file contains documentation for Wormhole (https://wormhole.com). A cross-chain messaging protocol used to move data and assets between blockchains.
It is intended for use with large language models (LLMs) to support developers working with Wormhole. The content includes selected pages from the official docs, organized by product category and section.
This file includes documentation related to the product: NTT
## AI Prompt Template
You are an AI developer assistant for Wormhole (https://wormhole.com). Your task is to assist developers in understanding and using the product described in this file.
- Provide accurate answers based on the included documentation.
- Do not assume undocumented features, behaviors, or APIs.
- If unsure, respond with “Not specified in the documentation.
## List of doc pages:
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/learn/transfers/native-token-transfers.md [type: learn]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/learn/transfers/native-token-transfers/architecture.md [type: learn]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/learn/transfers/native-token-transfers/deployment.md [type: learn]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/learn/transfers/native-token-transfers/overview.md [type: learn]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/learn/transfers/native-token-transfers/security.md [type: learn]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/cli-commands.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/configuration.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/configuration/access-control.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/configuration/rate-limiting.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/deploy-to-evm.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/deploy-to-solana.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/evm-launchpad.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/installation.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/post-deployment.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/deployment-process/troubleshooting.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/faqs.md [type: build]
Doc-Page: https://raw.githubusercontent.com/wormhole-foundation/wormhole-docs/refs/heads/main/build/transfers/native-token-transfers/managers-transceivers.md [type: build]
## Full content for each doc page
Doc-Content: https://wormhole.com/docs/learn/transfers/native-token-transfers/
--- BEGIN CONTENT ---
---
title: A Quick Look at Native Token Transfers
description: This section covers Wormhole's Native Token Transfers (NTT), an open source, flexible, and composable framework for transferring tokens across blockchains.
categories: NTT, Transfer
---
# Native Token Transfers
## Get Started
This section covers Wormhole's Native Token Transfers (NTT), an open source, flexible, and composable framework for transferring tokens across blockchains.
- :octicons-question-16:{ .lg .middle } **Overview**
---
Dive into an introduction to NTT and discover what NTT is, what its key features are, and the available integration paths.
[:custom-arrow: Learn more about NTT](/docs/learn/transfers/native-token-transfers/overview/)
- :octicons-question-16:{ .lg .middle } **Architecture**
---
Explore NTT's architecture to understand its core components and how they work together to manage cross-chain communication.
[:custom-arrow: Discover how NTT works](/docs/learn/transfers/native-token-transfers/architecture/)
- :octicons-book-16:{ .lg .middle } **Deployment Models**
---
The NTT framework offers two deployment models for different token management needs: the hub-and-spoke and burn-and-mint models.
[:custom-arrow: Check out the deployment models](/docs/learn/transfers/native-token-transfers/deployment/)
- :octicons-shield-lock-16:{ .lg .middle } **Security**
---
Explore NTT's security measures, including the Global Accountant and governance strategies for seamless token safety.
[:custom-arrow: Review the security measures](/docs/learn/transfers/native-token-transfers/security/)
## Next Steps
Ready to dive in and start building? Check out the following resources to begin the deployment process and make the most of your deployment.
- :octicons-rocket-16:{ .lg .middle } **Deploy NTT**
---
Explore detailed guides that walk you through the entire deployment process, from installing the NTT CLI to deploying NTT across supported chains.
[:custom-arrow: Deploy now using the NTT CLI](/docs/build/transfers/native-token-transfers/deployment-process/)
- :octicons-checklist-16:{ .lg .middle } **Post Deployment Recommendations**
---
Already deployed your NTT project? Check out these post deployment recommendations and integration demos to get the most out of your deployment.
[:custom-arrow: Get the most of out your NTT deployment](/docs/build/transfers/native-token-transfers/deployment-process/post-deployment/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/transfers/native-token-transfers/architecture/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Architecture
description: Explore Wormhole's Native Token Transfers architecture, which covers components, message flow, rate limiting, and custom transceivers.
categories: NTT, Transfer
---
## Introduction
The Native Token Transfers (NTT) architecture within the Wormhole ecosystem offers a robust framework for secure and efficient token transfers across multiple blockchains. This architecture relies on the manager and transceiver core components that work together to manage cross-chain communication and token operations complexities.
For the technical implementations of the functions, refer to the [Managers and Transceivers](/docs/build/transfers/native-token-transfers/managers-transceivers/){target=\_blank} page.
## System Components
The NTT framework is composed of managers, which oversee the transfer process, and transceivers, which handle cross-chain messaging, ensuring smooth and reliable token transfers.
### Managers
_Managers_ are responsible for handling the flow of token transfers between different blockchains and ensuring that tokens are locked or burned on the source chain before being minted or unlocked on the destination chain. The main tasks of managers include rate-limiting transactions, verifying message authenticity (message attestation), and managing the interaction between multiple transceivers, who are responsible for cross-chain communications.
Each manager is assigned to a specific token but can operate across multiple chains. Their key responsibility is to ensure that tokens are securely locked or burned on the source chain before being minted or unlocked on the destination chain. This provides the integrity of token transfers and prevents double-spending.
A manager is responsible for:
- **Handling token transfer flow** - upon a transfer request, `NttManager` either locks or burns tokens depending on the configuration, emits a `TransferSent` event, and ensures tokens can’t be accessed on the source chain before leasing them on the destination chain. This process safeguards against double-spending and maintains a secure transfer
- **Rate-limiting** - the `NttManager` contract includes rate-limiting functionality to prevent overloading the network or flooding the target chain. The `NttManager` applies rate limits to manage transfer flow and prevent network congestion. Limits apply to both outgoing and incoming transfers
- **Outbound** - transfers exceeding the outbound limit are queued (if `shouldQueue` is true) or reverted
- **Inbound** - similar limits apply on the destination chain, delaying transfers if capacity is exceeded
Rate limit duration and queuing are customizable per chain, and events notify users when transfers hit the limit
- **Message authenticity verification** - the `NttManager` ensures transfer security by verifying message authenticity through multiple attestations from transceivers. For each transfer, a threshold number of attestation signatures must be gathered from transceivers. Once verified, `NttManager` releases tokens on the destination chain, ensuring only authenticated transfers are processed
- **Interaction with transceivers** - `NttManager` collaborates with transceivers, forwarding transfer messages between chains and handling message verification. Transceivers route messages with transfer details to the destination chain, coordinating with `NttManager` to verify that tokens are locked or burned before releasing them on the other side. Transceivers can be customized to work with different security protocols, adding flexibility
### Transceivers
_Transceivers_ facilitate cross-chain token transfers by ensuring the accurate transmission of messages between different blockchains. They work in conjunction with managers to route token transfers from the source chain to the recipient chain. Their primary function is to ensure that messages regarding the transfer process are delivered correctly, and that tokens are safely transferred across chains.
While transceivers operate closely with Wormhole's ecosystem, they can also be configured independently of Wormhole's core system, allowing for flexibility. This adaptability allows them to be integrated with various verification backends to accommodate different security needs or platform-specific requirements.
Transceivers are entrusted with several responsibilities:
- **Message transmission** - transceivers handle the routing of transfer messages between chains. When a transfer is initiated, the transceiver sends the message (including transfer details like recipient and amount) to the destination chain’s manager for verification and processing
- **Manager coordination** - transceivers work with managers to ensure tokens are locked or burned on the source chain before issuance on the destination chain, reinforcing the security of each transfer
- **Custom verification support** - transceivers can integrate with custom verification backends, allowing flexibility to adapt to different security protocols or chain requirements. This customization enables protocols to use different attestation standards as needed
How it works:
1. The transceiver receives instructions from the manager to send messages across chains
2. It quotes delivery fees, handles cross-chain message relaying, and verifies delivery to ensure tokens are safely transferred
3. For each message, the transceiver coordinates with managers, ensuring only authorized transfers are processed on the destination chain
!!! note
[Learn more](/docs/learn/transfers/native-token-transfers/architecture/#lifecycle-of-a-message){target=\_blank} about the architecture of Native Token Transfers message lifecycles.
#### Custom Transceivers
The NTT framework supports advanced features such as custom transceivers for specialized message verification, enhancing security and adaptability. The architecture includes detailed processes for initiating transfers, managing rate limits, and finalizing token operations, with specific instructions and events outlined for EVM-compatible chains and Solana.
NTT has the flexibility to support custom message verification in addition to Wormhole Guardian message verification. Custom verifiers are implemented as transceiver contracts and can be protocol-specific or provided by other third-party attesters. Protocols can also configure the threshold of attestations required to mark a token transfer as valid — for example, 2/2, 2/3, 3/5.
The verifier performs checks based on predefined criteria and issues approval for transactions that meet these requirements. This approval is incorporated into the Wormhole message, ensuring that only transactions verified by both the Wormhole Guardian Network and the additional verifier are processed. The model includes an extra verifier in the bridging process, enhancing security and providing an added assurance of transaction integrity.
For more details, to collaborate, or to see examples of custom transceivers, [contact](https://discord.com/invite/wormholecrypto){target=\_blank} Wormhole contributors.
## Lifecycle of a Message
The lifecycle of a message in the Wormhole ecosystem for Native Token Transfers (NTT) involves multiple steps to ensure secure and accurate cross-chain token transfers. This lifecycle can vary depending on the blockchain being used, and the following explanations focus on the EVM and Solana implementations. The key stages include initiating the transfer, handling rate limits, sending and receiving messages, and finally, minting or unlocking tokens on the destination chain.
### Transfer
The process begins when a client initiates a transfer. For EVM, this is done using the `transfer` function, whereas in Solana, the client uses either the `transfer_lock` or `transfer_burn` instruction, depending on whether the program is in locking or burning mode. The client specifies the transfer amount, recipient chain ID, recipient address, and a flag (`should_queue` on both EVM and Solana) to decide whether the transfer should be queued if it hits the rate limit.
In both cases:
- If the source chain is in locking mode, the tokens are locked on the source chain to be unlocked on the destination chain
- If the source chain is in burning mode, the tokens are burned on the source chain, and new tokens are minted on the destination chain
Once initiated, an event (such as `TransferSent` on EVM or a corresponding log on Solana) is emitted to signal that the transfer process has started.
### Rate Limit
Both EVM and Solana implement rate-limiting for transfers to prevent abuse or network overload. Rate limits apply to both the source and destination chains. If transfers exceed the current capacity, depending on whether the `shouldQueue` flag is set to true, they can be queued.
- On EVM, the transfer is added to an outbound queue if it hits the rate limit, with a delay corresponding to the configured rate limit duration. If `shouldQueue` is set to false, the transfer is reverted with an error
- On Solana, the transfer is added to an **Outbox** via the `insert_into_outbox method`, and if the rate limit is hit, the transfer is queued with a `release_timestamp`. If `shouldQueue` is false, the transfer is reverted with a `TransferExceedsRateLimit` error
Both chains emit events or logs when transfers are rate-limited or queued.
### Send
After being forwarded to the Transceiver, the message is transmitted across the chain. Transceivers are responsible for delivering the message containing the token transfer details. Depending on the Transceiver's implementation, messages may be routed through different systems, such as Wormhole relayers or other custom relaying solutions. Once the message is transmitted, an event is emitted to signal successful transmission.
- In EVM, the message is sent using the `sendMessage` function, which handles the transmission based on the Transceiver's implementation. The Transceiver may use Wormhole relayers or custom relaying solutions to forward the message
- In Solana, the transfer message is placed in an Outbox and released via the `release_outbound` instruction. The Solana transceiver, such as the Wormhole Transceiver, may send the message using the `post_message` instruction, which Wormhole Guardians observe for verification
In both cases, an event or log (e.g., `SendTransceiverMessage` on EVM or a similar log on Solana) is emitted to signal that the message has been transmitted.
### Receive
Upon receiving the message on the destination chain, an off-chain relayer forwards the message to the destination Transceiver for verification.
- In EVM, the message is received by the `NttManager` on the destination chain, which verifies the message's authenticity. Depending on the M of N threshold set for the attestation process, the message may require attestations from multiple transceivers
- In Solana, the message is received via the `receive_message` instruction in the Wormhole Transceiver program. The message is verified and stored in a `VerifiedTransceiverMessage` account, after which it is placed in an Inbox for further processing
In both chains, replay protection mechanisms ensure that a message cannot be executed more than once. Events or logs are emitted (e.g., `ReceivedMessage` on EVM or `ReceiveMessage` on Solana) to notify that the message has been successfully received.
### Mint or Unlock
Finally, after the message is verified and attested to, the tokens can be either minted (if they were burned on the source chain) or unlocked (if they were locked). The tokens are then transferred to the recipient on the destination chain, completing the cross-chain token transfer process.
- On EVM, tokens are either minted (if burned on the source chain) or unlocked (if locked on the source chain). The `TransferRedeemed` event signals that the tokens have been successfully transferred
- On Solana, the tokens are unlocked or minted depending on whether the program is in locking or burning mode. The `release_inbound_unlock` or `release_inbound_mint` instruction is used to complete the transfer, and a corresponding log is produced
In both cases, once the tokens have been released, the transfer process is complete, and the recipient receives the tokens. Events are emitted to indicate that the transfer has been fully redeemed.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/transfers/native-token-transfers/deployment/
--- BEGIN CONTENT ---
---
title: Native Token Transfers - Deployment Models
description: Explore Wormhole's Native Token Transfers deployment models——hub-and-spoke, burn-and-mint——for seamless cross-chain token transfers.
categories: NTT, Transfer
---
# Deployment Models
The Wormhole framework offers two deployment models, each catering to different token management needs: the hub-and-spoke model and the burn-and-mint model. These models provide flexible solutions for both existing token deployments and new projects looking to enable secure and seamless multichain token transfers.
## Hub-and-Spoke
The hub-and-spoke model involves locking tokens on a central hub chain and minting them on destination spoke chains. This model maintains the total supply on the hub chain and is backward-compatible with any existing token deployment.
This model is ideal for existing token deployments that don't want to alter existing token contracts. It maintains the canonical balance on a hub chain while allowing for secure native deployment to new blockchains.
- **Hub chain** - tokens are locked when initiating a transfer
- **Spoke chains** - Equivalent tokens are minted on the destination chain
When transferring tokens back to the original hub chain, the tokens on the source spoke chain are burned, and the previously locked tokens on the hub chain are unlocked. However, when transferring tokens directly between spoke chains, the tokens are burned on the source spoke chain and minted on the destination spoke chain.
## Burn-and-Mint
The burn-and-mint model involves burning tokens on the source chain and minting them on the destination chain. This results in a simplified multichain transfer process that distributes the total supply across multiple chains and produces a native multichain token.
This model best suits new token deployments or projects willing to upgrade existing contracts.
- **Source chain** - tokens are burned when initiating a transfer
- **Destination chain** - equivalent tokens are minted on the destination chain
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/transfers/native-token-transfers/overview/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Overview
description: Explore Wormhole's Native Token Transfers for flexible cross-chain transfers with full control over token behavior, security, and integration features.
categories: NTT, Transfer
---
# Native Token Transfers
!!!tip "Looking to deploy NTT?"
If you're ready to deploy NTT or access the CLI, follow the detailed [NTT Deployment Section](/docs/build/transfers/native-token-transfers/deployment-process/){target=\_blank}.
- For deployment steps on EVM, visit the [Deploy to EVM page](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/){target=\_blank}
- For deployment steps on Solana, visit the [Deploy to Solana page](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/){target=\_blank}
## Introduction
Wormhole's Native Token Transfers (NTT) is an open source, flexible, and composable framework for transferring tokens across blockchains. By eliminating wrapped assets, NTT preserves each token’s native properties across chains, letting you maintain complete control over metadata, ownership, upgrade authority, and other custom features.
The framework offers two modes of operation for existing token deployments. In locking mode, the original token supply is preserved on a single chain. In contrast, the burning mode enables the deployment of multichain tokens, distributing the supply across various chains.
## Key Features
Wormhole's Native Token Transfers (NTT) framework offers a comprehensive and flexible solution for seamless token transfers across blockchains. Below are some of the key features that make this framework stand out:
- **No wrapped tokens** – tokens remain native on every chain where NTT is deployed. All token properties and metadata remain consistent, avoiding any confusion or overhead introduced by wrapped tokens
- **Unified user experience** - tokens retain their properties on each chain, remaining completely fungible and ensuring a consistent user experience
- **No liquidity pools** - transfer tokens without the need for liquidity pools, avoiding fees, slippage, and MEV risk
- **Integrator flexibility** - retained ownership, upgrade authority, and complete customizability over token contracts
- **Advanced rate limiting** - inbound and outbound rate limits are configurable per chain and over arbitrary periods, preventing abuse while managing network congestion and allowing for controlled deployments to new chains
- **Global Accountant** - ensures accounting integrity across chains by checking that the number of tokens burned and transferred out of a chain never exceeds the number of tokens minted
- **Access control** - to prevent unauthorized calls to administrative functions, protocols can choose to assign specific functions, such as the Pauser role, to a separate address from the owner
- **Maximum composability** - open source and extensible for widespread adoption and integration with other protocols
- **Custom attestation** - optionally add external verifiers and configure custom message attestation thresholds
## Integration Paths
Integrators looking to deploy their token to connected chains can use the NTT framework or the Token Bridge. Both options carry a distinct integration path and feature set depending on your requirements, as outlined in the following sections.
### Native Token Transfers Framework
The Native Token Transfers Framework is highly customizable and ideal for applications such as a DeFi governance token deployed across multiple chains, which seeks to achieve fungible multichain liquidity and direct integration into governance processes.
- **Mechanism** - can entirely utilize a burn-and-mint mechanism or can be paired for a hub-and-spoke model
- **Security** - fully configurable rate limiting, pausing, access control, and threshold attestations. Integrated with the Global Accountant
- **Contract ownership** - retain ownership and upgrade authority of token contracts on each chain
- **Token contracts** - native contracts owned by your protocol governance
- **Integration** - streamlined, customizable framework allows for more sophisticated and bespoke deployments
The following example projects demonstrate the use of the Wormhole NTT framework through Wormhole Connect and the TypeScript SDK:
- [NTT Connect](https://github.com/wormhole-foundation/demo-ntt-connect){target=\_blank}
- [NTT TS SDK](https://github.com/wormhole-foundation/demo-ntt-ts-sdk){target=\_blank}
### Token Bridge
The Token Bridge offers a secure, low-effort integration suitable for applications like a Web3 game that wants to make its token tradable across multiple chains.
- **Mechanism** - solely utilizes a lock and mint model. Unlike NTT, the Token Bridge issues a wrapped asset on the destination chain, rather than preserving the original token contract
- **Security** - preconfigured rate limiting and integrated Global Accountant
- **Contract ownership** - Token Bridge contracts are upgradeable via [Wormhole Governance](/docs/learn/security/){target=\_blank}
- **Token contracts** - wrapped asset contract owned by the Wormhole Token Bridge contract, upgradeable via a 13/19 Guardian governance process
- **Integration** - straightforward and permissionless method to deploy on multiple chains
!!! note
[Learn more](/docs/learn/infrastructure/vaas/){target=\_blank} about the core messaging primitives in the Wormhole network.
## Supported Token Standards
Native Token Transfers (NTT) in Wormhole primarily support **ERC-20 tokens**, the most widely used standard for fungible tokens on the Ethereum network and other EVM-compatible blockchains. The NttManager contract leverages the IERC20 interface and SafeERC20 utility from OpenZeppelin to ensure secure and efficient token transfers. Additionally, it supports ERC-20 Burnable tokens, allowing tokens to be burned on the source chain when needed for cross-chain transfers. At this time, NTT focuses on ERC-20 tokens, and other token standards, such as ERC-721 (non-fungible tokens) or ERC-1155 (multi-token standard), are not natively supported.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/transfers/native-token-transfers/security/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Security
description: Explore the security measures of Native Token Transfers, including the Global Accountant and governance strategies for seamless token safety.
categories: NTT, Transfer
---
# Security
## Global Accountant
The Global Accountant is a defense-in-depth security feature that checks the integrity of every token transfer. It ensures that chain balances remain isolated and more tokens cannot be burned and transferred out of a chain than were ever minted.
This feature ensures native asset fungibility remains in 1:1 parity. At no time will assets coming from a spoke chain exceed the number of native assets sent to that spoke chain. The Guardians, with their role in enforcing accounting transparency, provide a reassuring layer of security, attesting to a Native Token Transfer (NTT) only if it passes integrity checks.
[Contact](https://discord.com/invite/wormholecrypto){target=\_blank} Wormhole contributors if you are interested in configuring the Global Accountant for your multichain deployment.
## Governance and Upgradeability
Integrators should implement governance mechanisms to manage the addition and removal of transceivers and to upgrade contracts using proxy patterns, as demonstrated in the upgrade functions in the `NttManager` contracts. These processes can also set thresholds and rules for attestation and message approval.
The registry component of the NTT system is crucial for maintaining a trusted list of transceivers and managing their status. Governance processes for the following actions can be submitted directly to the corresponding contract on-chain, whether it is one or multiple of the bridging contracts or one of the token contracts:
- Adding or removing a transceiver address from the registry
- Setting the token contract address on a bridging contract
- Setting the Wormhole Core Contract address on a bridging contract
- Setting the registered bridging contract address on the token contract
This governance model ensures that the system remains secure while being adaptable to new requirements in any environment where it is deployed.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/
--- BEGIN CONTENT ---
---
title: Native Token Transfers (NTT)
description: This section provides comprehensive guidance on configuring, deploying, and managing your Native Token Transfers (NTT) integration.
categories: NTT, Transfer
---
# Native Token Transfers
Native Token Transfers (NTT) simplifies and enables seamless, flexible token transfers across blockchains. This section provides comprehensive guidance on configuring, deploying, and managing your NTT integration. It includes information relevant to both new token deployments and existing token management.
Visit the [Use Cases](/docs/build/start-building/use-cases/){target=\_blank} and [Product Comparison](/docs/build/start-building/products/){target=\_blank} pages for help determining if NTT will meet the needs of your project.
## Quickstart
If needed, you can generate test tokens for development with the [`example-ntt-token`](https://github.com/wormhole-foundation/example-ntt-token){target=\_blank} GitHub repository by following the README instructions.
The process for creating, deploying, and monitoring NTTs is as follows. Select the title of each step to view the associated guide:
[timeline left(wormhole-docs/.snippets/text/build/transfers/ntt/ntt-deployment-process-timeline.json)]
## Deploy NTTs with Launchpad
If you are deploying to EVM blockchains, the [Native Token Transfers (NTT) Launchpad](https://ntt.wormhole.com/){target=\_blank} is a Wormhole-managed UI application that provides a step-by-step interface for deploying NTT. NTT Launchpad replaces manually deploying contracts or configuring relayers for each supported EVM chain.
Follow the [Deploy NTT with Launchpad](/docs/build/transfers/native-token-transfers/deployment-process/evm-launchpad/){target=\_blank} guide to create new multichain tokens or integrate existing tokens with just a few clicks.
## Additional Resources
- :octicons-gear-16:{ .lg .middle } **NTT CLI Commands**
---
The NTT CLI tool provides a comprehensive set of commands for creating, configuring, deploying, and monitoring NTTs. This page provides a comprehensive list of available NTT CLI commands, their descriptions, and examples to help you interact effectively with the NTT system.
[:custom-arrow: NTT CLI Commands](/docs/build/transfers/native-token-transfers/cli-commands/)
- :octicons-question-16:{ .lg .middle } **NTT FAQs**
---
Frequently asked questions about Wormhole Native Token Transfers, including cross-chain lending, SDK usage, custom RPCs, and integration challenges.
[:custom-arrow: Check out the FAQs](/docs/build/transfers/native-token-transfers/faqs/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/cli-commands/
--- BEGIN CONTENT ---
---
title: NTT CLI Commands
description: A comprehensive guide to the Native Token Transfers (NTT) CLI, detailing commands for managing token transfers across chains within the Wormhole ecosystem.
categories: NTT, Transfer
---
# NTT CLI Commands
## Introduction
The NTT Command-Line Interface (CLI) is a powerful tool for managing native token transfers across multiple blockchain networks within the Wormhole ecosystem. This page provides a comprehensive list of available commands, their descriptions, and examples to help you interact with and configure the NTT system effectively. Whether initializing deployments, updating configurations, or working with specific chains, the NTT CLI simplifies these operations through its intuitive commands.
If you haven't installed the NTT CLI yet, follow the [NTT Installation Guide](/docs/build/transfers/native-token-transfers/deployment-process/installation/#installation){target=\_blank} to set it up before proceeding.
## Table of Commands
The following table lists the available NTT CLI commands, descriptions, and examples.
To explore detailed information about any NTT CLI command, including its options and examples, you can append `--help` to the command. This will display a comprehensive guide for the specific command.
### General Commands
| Command | Description | Examples |
|-----------------------------------------|-------------------------------------------------------|--------------------------|
| `ntt update` | update the NTT CLI | `ntt update` |
| `ntt new ` | create a new NTT project | `ntt new my-ntt-project` |
| `ntt add-chain ` | add a chain to the deployment file | `ntt add-chain Ethereum --token 0x1234... --mode burning --latest`|
| `ntt upgrade ` | upgrade the contract on a specific chain | `ntt upgrade Solana --ver 1.1.0`|
| `ntt clone ` | initialize a deployment file from an existing contract| `ntt clone Mainnet Solana Sol5678...`|
| `ntt init ` | initialize a deployment file | `ntt init devnet` |
| `ntt pull` | pull the remote configuration | `ntt pull` |
| `ntt push` | push the local configuration | `ntt push` |
| `ntt status` | check the status of the deployment | `ntt status` |
### Configuration Commands
| Command | Description | Examples |
|---------------------------------------------|----------------------------------------|-------------------------------------|
| `ntt config set-chain `| set a configuration value for a chain | `ntt config set-chain Ethereum scan_api_key`|
| `ntt config unset-chain ` | unset a configuration value for a chain| `ntt config unset-chain Ethereum scan_api_key`|
| `ntt config get-chain ` | get a configuration value for a chain | `ntt config get-chain Ethereum scan_api_key`|
### Solana Commands
| Command | Description | Examples |
|-----------------------------------------------|---------------------------------------------------------|------------------|
| `ntt solana key-base58 ` | print private key in base58 | `ntt solana key-base58 /path/to/keypair.json`|
| `ntt solana token-authority ` | print the token authority address for a given program ID| `ntt solana token-authority Sol1234...`|
| `ntt solana ata `| print the token authority address for a given program ID| `ntt solana ata Mint123... Owner123... token22`|
## Where to Go Next
- :octicons-gear-16:{ .lg .middle } **Configure NTT**
---
Find information on configuring NTT, including guidance on setting Owner and Pauser access control roles and management of rate-limiting.
[:custom-arrow: Configure your NTT deployment](/docs/build/transfers/native-token-transfers/configuration/)
- :octicons-question-16:{ .lg .middle } **NTT FAQs**
---
Frequently asked questions about Wormhole Native Token Transfers, including cross-chain lending, SDK usage, custom RPCs, and integration challenges.
[:custom-arrow: Check out the FAQs](/docs/build/transfers/native-token-transfers/faqs/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/configuration/
--- BEGIN CONTENT ---
---
title: Native Token Transfers (NTT) - Configuration
description: This section contains information on configuring Native Token Transfers (NTT), including guidance on setting Owner and Pauser access control roles and management of rate-limiting.
categories: NTT, Transfer
---
# Configure Native Token Transfers (NTT)
## Get Started
This section contains information on configuring Native Token Transfers (NTT), including guidance on setting Owner and Pauser access control roles and management of rate-limiting.
- :octicons-clock-16:{ .lg .middle } **Rate Limiting**
---
Discover options for configuring rate limits and how queueing effects transaction flow.
[:custom-arrow: Explore rate limit options](/docs/build/transfers/native-token-transfers/configuration/rate-limiting/)
- :octicons-unlock-16:{ .lg .middle } **Access Control**
---
Learn more about access control, including why you should consider setting a separate Pauser address as part of your development security plan.
[:custom-arrow: Explore access control roles](/docs/build/transfers/native-token-transfers/configuration/access-control/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/configuration/access-control/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Access Control
description: Learn about the owner and pauser access roles for the NTT manager contract, which can be used to pause and un-pause token transfers.
categories: NTT, Transfer
---
## Owner and Pauser Roles
Pausing the Native Toke Transfer (NTT) Manager Contract will disallow initiating new token transfers. While the contract is paused, in-flight transfers can still be redeemed (subject to rate limits if configured).
NTT can be paused on a particular chain by updating the `paused` parameter on the deployment to `true` via the NTT CLI, then performing `ntt push` to sync the local configuration with the on-chain deployment.
- **Owner** - full control over NTT contracts, can perform administrative functions. Has the ability to un-pause contracts if they have been paused
- **Pauser** - can pause NTT contracts to halt token transfers temporarily. This role is crucial for responding quickly to adverse events without a prolonged governance process. Cannot un-pause contracts
You may verify the current owner, pauser, and paused status of the NTT Manager contract on the `deployment.json` file in your NTT project directory.
```json
{
"network": "Testnet",
"chains": {
"Sepolia": {
"version": "1.1.0",
"mode": "burning",
"paused": true, // set to true to pause the contract
"owner": "0x0088DFAC40029f266e0FF62B82E47A07467A0345",
"manager": "0x5592809cf5352a882Ad5E9d435C6B7355B716357",
//...
"pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
}
}
}
```
!!! note
While the `Pauser` can pause contracts, the ability to un-pause contracts is callable only by the `Owner`.
The `Owner` and the `Pauser` addresses can each pause the contract. Since the contract `Owner` address is typically a multisig or a more complex DAO governance contract, and pausing the contract only affects the availability of token transfers, protocols can choose to set the `Pauser` address to be a different address. Creating a separate `Pauser` helps protocols respond quickly to potential risks without going through a drawn-out process.
Consider separating `Owner` and `Pauser` roles for your multichain deployment. `Owner` and `Pauser` roles are defined directly on the `NttManager` contract.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/configuration/rate-limiting/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Rate Limiting
description: Learn about rate limits in Wormhole NTT by configuring send/receive limits, queuing, and canceling flows to manage multichain token transfers efficiently.
categories: NTT, Transfer
---
## Introduction
The Native Token Transfer (NTT) framework provides configurable per-chain rate limits for sending and receiving token transfers. Integrators can manage these limits via their own governance processes to quickly adapt to on-chain activity.
If a transfer is rate-limited on the source chain and queueing is enabled via `shouldQueue = true`, the transfer is placed into an outbound queue and can be released after the rate limit expires.
You can configure the following limits on every chain where NTT is deployed directly using the manager:
- **Sending limit** - a single outbound limit for sending tokens from the chain
- **Per-chain receiving limits** - the maximum receiving limit, which can be configured on a per-chain basis. For example, allowing 100 tokens to be received from Ethereum but only 50 tokens to be received from Arbitrum
Rate limits are replenished every second over a fixed duration. While the default duration is 24 hours, the value is configurable at contract creation. Rate-limited transfers on the destination chain are added to an inbound queue with a similar release delay.
## Update Rate Limits
To configure or update the sending and receiving rate limits, follow these steps:
1. **Locate the deployment file** - open the `deployment.json` file in your NTT project directory. This file contains the configuration for your deployed contracts
2. **Modify the limits section** - for each chain, locate the limits field and update the outbound and inbound values as needed
```json
"limits": {
"outbound": "1000.000000000000000000",
"inbound": {
"Ethereum": "100.000000000000000000",
"Arbitrum": "50.000000000000000000"
}
}
```
- **`outbound`** - sets the maximum tokens allowed to leave the chain
- **`inbound`** - configures per-chain receiving limits for tokens arriving from specific chains
3. **Push the configuration** - use the NTT CLI to synchronize the updated configuration with the blockchain
```bash
ntt push
```
4. **Verify the changes** - after pushing, confirm the new rate limits by checking the deployment status
```bash
ntt status
```
???- note "`deployment.json` example"
```json
{
"network": "Testnet",
"chains": {
"Sepolia": {
"version": "1.1.0",
"mode": "burning",
"paused": false,
"owner": "0x0088DFAC40029f266e0FF62B82E47A07467A0345",
"manager": "0x5592809cf5352a882Ad5E9d435C6B7355B716357",
"token": "0x5CF5D6f366eEa7123BeECec1B7c44B2493569995",
"transceivers": {
"threshold": 1,
"wormhole": {
"address": "0x91D4E9629545129D427Fd416860696a9659AD6a1",
"pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
}
},
"limits": {
"outbound": "184467440737.095516150000000000",
"inbound": {
"ArbitrumSepolia": "500.000000000000000000"
}
},
"pauser": "0x0088DFAC40029f266e0FF62B82E47A07467A0345"
}
}
}
```
## Queuing Mechanism
When a transfer exceeds the rate limit, it is held in a queue and can be released after the set rate limit duration has expired. The sending and receiving queuing behavior is as follows:
- **Sending** - if an outbound transfer violates rate limits, users can either revert and try again later or queue their transfer. Users must return after the queue duration has expired to complete sending their transfer
- **Receiving** - if an inbound transfer violates rate limits, it is in a queue. Users or relayers must return after the queue duration has expired to complete receiving their transfer on the destination chain
Queuing is configured dynamically during each transfer by passing the `shouldQueue` parameter to the [`transfer` function](https://github.com/wormhole-foundation/native-token-transfers/blob/5e7ceaef9a5e7eaa13e823a67c611dc684cc0c1d/evm/src/NttManager/NttManager.sol#L171-L182){target=\_blank} in the `NttManager` contract.
## Cancel Flows
If users bridge frequently between a given source chain and destination chain, the capacity could be exhausted quickly. Loss of capacity can leave other users rate-limited, potentially delaying their transfers. The outbound transfer cancels the inbound rate limit on the source chain to avoid unintentional delays. This allows for refilling the inbound rate limit by an amount equal to the outbound transfer amount and vice-versa, with the inbound transfer canceling the outbound rate limit on the destination chain and refilling the outbound rate limit with an amount.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/
--- BEGIN CONTENT ---
---
title: Native Token Transfers (NTT) - Deployment
description: This section provides information on installing Wormhole's Native Token Transfer framework, deployment to EVM and Solana, and post deployment NTT maintenance.
categories: NTT, Transfer
---
# Deploy Native Token Transfers (NTT)
## Get Started
This section provides information on installing Wormhole's Native Token Transfer framework, deployment to EVM and Solana, and post deployment NTT maintenance.
- :octicons-download-16:{ .lg .middle } **Installation**
---
Prerequisites and commands for installing the NTT CLI and working with the NTT framework.
[:custom-arrow: Install the NTT CLI](/docs/build/transfers/native-token-transfers/deployment-process/installation/)
- :octicons-rocket-16:{ .lg .middle } **Deploy to EVM**
---
Find information on preparing for NTT deployment to EVM, including an example NTT token repository.
[:custom-arrow: Deploy token and NTT contracts](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/)
- :octicons-rocket-16:{ .lg .middle } **Deploy to EVM Chains via Launchpad**
---
Deploy a new token or extend an existing one across multiple chains with the NTT Launchpad. Manage transfers, supply, and settings—all from a single platform.
[:custom-arrow: Deploy via Launchpad](/docs/build/transfers/native-token-transfers/deployment-process/evm-launchpad/)
- :octicons-rocket-16:{ .lg .middle } **Deploy to Solana**
---
Your guide to NTT deployment to Solana, including setup, token compatibility, mint/burn modes, and CLI usage.
[:custom-arrow: Deploy token and NTT contracts](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/)
- :octicons-search-16:{ .lg .middle } **Post Deployment**
---
Learn how to best monitor and maintain your NTT deployment to get the most out of your Wormhole integration while providing security for users.
[:custom-arrow: Explore next steps](/docs/build/transfers/native-token-transfers/deployment-process/post-deployment/)
- :octicons-alert-16:{ .lg .middle } **Troubleshooting**
---
Explore solutions and detailed guidance in our troubleshooting guide to resolve issues with NTT deployment.
[:custom-arrow: Get help](/docs/build/transfers/native-token-transfers/deployment-process/troubleshooting/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/
--- BEGIN CONTENT ---
---
title: Native Token Transfers EVM Deployment
description: Deploy and configure Wormhole’s Native Token Transfers (NTT) for EVM chains, including setup, token compatibility, mint/burn modes, and CLI usage.
categories: NTT, Transfer
---
# Native Token Transfers (NTT) EVM Development
## Deploy Your Token and Ensure Compatibility
If you still need to do so, deploy the token contract to the destination or spoke chains.
### Requirements for Token Deployment
Wormhole’s NTT is an open framework that supports various deployment modes. The NTT CLI currently supports two deployment modes: burn-and-mint and hub-and-spoke. These modes differ in how tokens are managed across chains.
#### Burn-and-Mint Mode
Tokens integrated with `NttManager` in `burning` mode require the following two functions to be present:
- `burn(uint256 amount)`
- `mint(address account, uint256 amount)`
These functions aren't part of the standard ERC-20 interface. The [`INttToken` interface](https://github.com/wormhole-foundation/native-token-transfers/blob/main/evm/src/interfaces/INttToken.sol){target=\_blank} documents the required functions and convenience methods, errors, and events.
??? code "View the complete `INttToken` Interface`"
```solidity
// SPDX-License-Identifier: Apache 2
pragma solidity >=0.8.8 <0.9.0;
interface INttToken {
/// @notice Error when the caller is not the minter.
/// @dev Selector 0x5fb5729e.
/// @param caller The caller of the function.
error CallerNotMinter(address caller);
/// @notice Error when the minter is the zero address.
/// @dev Selector 0x04a208c7.
error InvalidMinterZeroAddress();
/// @notice Error when insufficient balance to burn the amount.
/// @dev Selector 0xcf479181.
/// @param balance The balance of the account.
/// @param amount The amount to burn.
error InsufficientBalance(uint256 balance, uint256 amount);
/// @notice The minter has been changed.
/// @dev Topic0
/// 0x0b5e7be615a67a819aff3f47c967d1535cead1b98db60fafdcbf22dcaa8fa5a9.
/// @param newMinter The new minter.
event NewMinter(address previousMinter, address newMinter);
// NOTE: the `mint` method is not present in the standard ERC20 interface.
function mint(address account, uint256 amount) external;
// NOTE: the `setMinter` method is not present in the standard ERC20 interface.
function setMinter(address newMinter) external;
// NOTE: NttTokens in `burn` mode require the `burn` method to be present.
// This method is not present in the standard ERC20 interface, but is
// found in the `ERC20Burnable` interface.
function burn(uint256 amount) external;
}
```
Later, you set mint authority to the corresponding `NttManager` contract. You can also follow the scripts in the [example NTT token](https://github.com/wormhole-foundation/example-ntt-token){target=\_blank} repository to deploy a token contract.
#### Hub-and-Spoke Mode
A central hub chain (e.g., Ethereum) manages the total token supply in hub-and-spoke mode. Other chains (spokes) mint or burn tokens during cross-chain transfers, ensuring consistency with the locked tokens on the hub chain.
- **Hub chain** - tokens are locked on the hub chain when transferring to spoke chains
- **Spoke chains** - tokens are native to the spoke chains and are either minted or burned during cross-chain transfers
!!! note
The only requirement for using the NTT framework is an ERC20 token, which can be newly deployed or existing. Steps like setting mint authority apply only to spoke chains.
For example, when transferring tokens from Ethereum (hub) to Polygon (spoke), the NTT Manager locks tokens on Ethereum, and the corresponding amount is minted on Polygon. Similarly, transferring tokens back from Polygon to Ethereum burns the tokens on Polygon and unlocks the equivalent tokens on Ethereum.
This process ensures that the total token supply remains consistent across all chains, with the hub chain acting as the source of truth.
For more detailed information, see the [Deployment Models](/docs/learn/transfers/native-token-transfers/deployment/){target=\_blank} page.
### Key Differences Between Modes
- **Burn-and-mint** - tokens must implement custom `mint` and `burn` functions, allowing each chain to manage token issuance independently
- **Hub-and-spoke** - tokens only need to be ERC20 compliant, with the hub chain acting as the source of truth for supply consistency
## Deploy NTT
Create a new NTT project:
```bash
ntt new my-ntt-deployment
cd my-ntt-deployment
```
Initialize a new `deployment.json` file specifying the network:
=== "Testnet"
```bash
ntt init Testnet
```
=== "Mainnet"
```bash
ntt init Mainnet
```
Ensure you have set up your environment correctly:
```bash
export ETH_PRIVATE_KEY=INSERT_PRIVATE_KEY
```
Add each chain you'll be deploying to. The following example demonstrates configuring NTT in burn-and-mint mode on Ethereum Sepolia and Arbitrum Sepolia:
```bash
# Set scanner API Keys as environment variables
export SEPOLIA_SCAN_API_KEY=INSERT_ETHERSCAN_SEPOLIA_API_KEY
export ARBITRUMSEPOLIA_SCAN_API_KEY=INSERT_ARBISCAN_SEPOLIA_API_KEY
# Add each chain
# The contracts will be automatically verified using the scanner API keys above
ntt add-chain Sepolia --latest --mode burning --token INSERT_YOUR_TOKEN_ADDRESS
ntt add-chain ArbitrumSepolia --latest --mode burning --token INSERT_YOUR_TOKEN_ADDRESS
```
While not recommended, you can pass the `-skip-verify` flag to the `ntt add-chain` command if you want to skip contract verification.
The `ntt add-chain` command takes the following parameters:
- Name of each chain
- Version of NTT to deploy (use `--latest` for the latest contract versions)
- Mode (either `burning` or `locking`)
- Your token contract address
The NTT CLI prints detailed logs and transaction hashes, so you can see exactly what's happening under the hood.
## Configure NTT
The NTT CLI takes inspiration from [git](https://git-scm.com/){target=\_blank}. You can run:
- `ntt status` - checks whether your `deployment.json` file is consistent with what is on-chain
- `ntt pull` - syncs your `deployment.json` file with the on-chain configuration and set up rate limits with the appropriate number of decimals, depending on the specific chain. For example:
For Solana, the limits are set with 9 decimal places:
```json
"inbound": {
"Sepolia": "1000.000000000" // inbound limit from Sepolia to Solana
}
```
For Sepolia (Ethereum Testnet), the limits are set with 18 decimal places:
```json
"inbound": {
"Solana": "1000.000000000000000000" // inbound limit from Solana to Sepolia
}
```
This initial configuration ensures that the rate limits are correctly represented for each chain's token precision
- `ntt push` - syncs the on-chain configuration with local changes made to your `deployment.json` file
After you deploy the NTT contracts, ensure that the deployment is properly configured and your local representation is consistent with the actual on-chain state by running `ntt status` and following the instructions shown on the screen.
## Set Token Minter to NTT Manager
The final step in the deployment process is to set the NTT Manager as a minter of your token on all chains you have deployed to in `burning` mode. When performing a hub-and-spoke deployment, it is only necessary to set the NTT Manager as a minter of the token on each spoke chain.
!!! note
The required NTT Manager address can be found in the `deployment.json` file.
- If you followed the [`INttToken`](https://github.com/wormhole-foundation/native-token-transfers/blob/main/evm/src/interfaces/INttToken.sol){target=\_blank} interface, you can execute the `setMinter(address newMinter)` function
```json
cast send $TOKEN_ADDRESS "setMinter(address)" $NTT_MANAGER_ADDRESS --private-key $ETH_PRIVATE_KEY --rpc-url $YOUR_RPC_URL
```
- If you have a custom process to manage token minters, you should now follow that process to add the corresponding NTT Manager as a minter
By default, NTT transfers to EVM blockchains support automatic relaying via the Wormhole relayer, which doesn't require the user to perform a transaction on the destination chain to complete the transfer.
!!!important
To proceed with testing and find integration examples, check out the [NTT Post Deployment](/docs/build/transfers/native-token-transfers/deployment-process/post-deployment/){target=\_blank} page.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Solana Deployment
description: Deploy and configure Wormhole's Native Token Transfers (NTT) for Solana, including setup, token compatibility, mint/burn modes, and CLI usage.
categories: NTT, Transfer
---
# Deploy Native Token Transfers on Solana
[Native Token Transfers (NTT)](/docs/learn/transfers/native-token-transfers/overview/){target=\_blank} enable seamless multichain transfers of SPL tokens on Solana using Wormhole's messaging protocol. Instead of creating wrapped tokens, NTT allows native assets to move across chains while maintaining their original properties.
This guide walks you through deploying NTT on Solana, including setting up dependencies, configuring token compatibility, and using the NTT CLI to deploy in hub-and-spoke or burn-and-mint mode.
By the end, a fully deployed NTT will be set up, allowing your token to transfer between Solana and other supported chains.
## Prerequisites
Before deploying NTT on Solana, ensure you have the following:
- [Rust](https://www.rust-lang.org/tools/install){target=\_blank}
- [Solana](https://docs.solanalabs.com/cli/install){target=\_blank} **`{{ ntt.solana_cli_version }}`**
- [Anchor](https://www.anchor-lang.com/docs/installation){target=\_blank} **`{{ ntt.anchor_version }}`**
Use the Solana and Anchor versions listed above to avoid compatibility issues while following this guide.
## Overview of the Deployment Process
Deploying NTT with the CLI on Solana follows a structured process:
1. **Choose your token setup**:
- **Use an existing SPL token** - if your token is already deployed on Solana, you can skip token creation and move directly to the [Set Up NTT](#set-up-ntt) section
- **Create a new SPL token** - if you don't already have an SPL token deployed, you'll need to deploy and configure it on Solana before integrating with Wormhole's NTT
???- interface "Create and Mint SPL Tokens"
This section walks you through generating a Solana wallet, deploying an SPL token, creating a token account, and minting tokens.
1. **Generate a Solana key pair** - run the following command to create a new wallet:
```bash
solana-keygen grind --starts-with w:1 --ignore-case
```
2. **Set Solana configuration** - configure the Solana CLI to use the generated key pair using the following command:
```bash
solana config set --keypair INSERT_PATH_TO_KEYPAIR_JSON
```
3. **Select an RPC URL** - configure Solana to use the appropriate network using one of the following commands:
=== "Mainnet"
```bash
solana config set -um
```
=== "Testnet"
```bash
solana config set -ut
```
=== "Devnet"
```bash
solana config set -ud
```
4. **Fund your wallet** - ensure you have enough SOL to create a token. If deploying on devnet, request an airdrop with the following commands:
```bash
solana airdrop 2
solana balance
```
5. **Install SPL Token CLI** - install or update the required [CLI tool](https://spl.solana.com/token){target=\_blank}
```bash
cargo install spl-token-cli
```
6. **Create a new SPL token** - initialize the token on Solana
```bash
spl-token create-token
```
7. **Create a token account** - generate an account to hold the token
```bash
spl-token create-account INSERT_TOKEN_ADDRESS
```
8. **Mint tokens** - send 1000 tokens to the created account
```bash
spl-token mint INSERT_TOKEN_ADDRESS 1000
```
!!! note
NTT versions `>=v2.0.0+solana` support SPL tokens with [transfer hooks](https://spl.solana.com/transfer-hook-interface){target=\_blank}.
2. **Choose your [deployment model](/docs/learn/transfers/native-token-transfers/deployment/){target=\_blank}**:
- **Hub-and-spoke** - tokens are locked on a hub chain and minted on destination spoke chains. Since the token supply remains controlled by the hub chain, no changes to the minting authority are required
- **Burn-and-mint** - tokens are burned on the source chain and minted on the destination chain. This requires transferring the SPL token's minting authority to the Program Derived Address (PDA) controlled by the NTT program
3. **Deploy and configure NTT** - use the NTT CLI to initialize and deploy the NTT program, specifying your SPL token and deployment mode
Following this process, your token will fully integrate with NTT, enabling seamless transfers between Solana and other chains.
By default, NTT transfers to Solana require manual [relaying](/docs/learn/infrastructure/relayer/){target=\_blank}, meaning users must complete a transaction on Solana to finalize the transfer. For automatic relaying, where transactions are completed without user intervention, additional setup is required. [Contact Wormhole contributors](https://forms.clickup.com/45049775/f/1aytxf-10244/JKYWRUQ70AUI99F32Q){target=\_blank} to enable automatic relaying support for your deployment.
## Set Up NTT
To integrate your token with NTT on Solana, you must initialize the deployment and configure its parameters. This process sets up the required contracts and may generate key pairs if they don't exist. These key pairs are used to sign transactions and authorize actions within the NTT deployment.
The [NTT CLI](/docs/build/transfers/native-token-transfers/deployment-process/installation/){target=\_blank} manages deployments, configures settings, and interacts with the NTT system. Follow these steps to set up NTT using the CLI tool:
1. **Create a new NTT project** - set up a deployment workspace
```bash
ntt new INSERT_PROJECT_NAME
cd INSERT_PROJECT_NAME
```
2. **Initialize the deployment** - generate a `deployment.json` file with your deployment settings
=== "Mainnet"
```bash
ntt init Mainnet
```
=== "Testnet"
```bash
ntt init Testnet
```
!!! note
Testnet deployment settings work for both Solana Testnet and Devnet networks.
### Set Mint Authority
If you use burn-and-mint mode, follow these steps to enable the NTT program to mint tokens on Solana. This involves deriving the PDA as the token authority and updating the SPL token's minting permissions.
If you want to use hub-and-spoke, skip this section and proceed to [Deploy and Configure NTT](#deploy-and-configure-ntt).
Before updating the mint authority, you must create metadata for your SPL token. You can visit this repository to see an example of [how to create metadata for your SPL token](https://github.com/wormhole-foundation/demo-metaplex-metadata/blob/main/src/token-metadata.ts){target=\_blank}.
Follow these steps to set the mint authority using the NTT CLI:
1. **Generate an NTT program key pair** - create a unique key pair for the NTT program. The key pair must start with "ntt" to identify it as belonging to the NTT deployment
```bash
solana-keygen grind --starts-with ntt:1 --ignore-case
```
2. **Derive the token authority** - generate the PDA, which will manage token minting
```bash
ntt solana token-authority INSERT_YOUR_NTT_PROGRAM_KEY_PAIR
```
3. **Set SPL token mint authority** - delegate minting control to the derived PDA
```bash
spl-token authorize INSERT_TOKEN_ADDRESS mint INSERT_DERIVED_PDA
```
## Deploy and Configure NTT
After setting up your deployment, finalize the configuration and deploy the NTT program on Solana by following these steps:
1. **Deploy NTT to Solana** - run the appropriate command based on your deployment mode:
=== "Burn-and-Mint"
```bash
ntt add-chain Solana --latest --mode burning --token INSERT_TOKEN_ADDRESS --payer INSERT_YOUR_KEYPAIR_JSON --program-key INSERT_YOUR_NTT_PROGRAM_KEYPAIR_JSON
```
=== "Hub-and-Spoke"
```bash
ntt add-chain Solana --latest --mode locking --token INSERT_TOKEN_ADDRESS --payer INSERT_YOUR_KEYPAIR_JSON --program-key INSERT_YOUR_NTT_PROGRAM_KEYPAIR_JSON
```
!!! tip
The `add-chain` command accepts an optional `--solana-priority-fee` flag, which sets the priority fee in microlamports. The default is `50000`.
2. **Verify deployment status** - after deployment, check if your `deployment.json` file matches the on-chain configuration using the following command:
```bash
ntt status
```
If needed, sync your local configuration with the on-chain state:
```bash
ntt pull
```
3. **Configure inbound and outbound rate limits** - by default, the inbound and outbound limits are set to `0` and must be updated before deployment. For EVM chains, values must be set using 18 decimals, while Solana uses nine decimals.
Open your `deployment.json` file and adjust the values based on your use case:
```json
"inbound": {
"Sepolia": "1000.000000000" // inbound limit from Sepolia to Solana
},
"outbound": {
"Sepolia": "1000.000000000" // outbound limit from Solana to Sepolia
}
```
4. **Push the final deployment** - once rate limits are set, push the deployment to Solana using the specified key pair to cover gas fees
```bash
ntt push --payer INSERT_YOUR_KEYPAIR_JSON
```
### Troubleshoot Deployment Issues
If your deployment fails, it may be due to leftover program buffer accounts taking up storage on Solana. These temporary accounts are created during deployment but may persist if interrupted. Refer to the [Solana program deployment guide](https://solana.com/docs/programs/deploying#program-buffer-accounts){target=\_blank} for instructions on finding and closing these buffer accounts to free up space and allow redeployment.
## Where to Go Next
- :octicons-globe-16:{ .lg .middle } **Deploy NTT on EVM Chains**
---
After deploying NTT on Solana, deploy and integrate it on EVM chains to enable seamless multichain transfers.
[:custom-arrow: Deploy NTT on EVM](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/){target=\_blank}
- :octicons-tools-16:{ .lg .middle } **Test Your Deployment**
---
Follow the NTT Post Deployment Guide for integration examples and testing instructions.
[:custom-arrow: Test Your NTT deployment](/docs/build/transfers/native-token-transfers/deployment-process/post-deployment/){target=\_blank}
- :octicons-tools-16:{ .lg .middle } **Add NTT to Your dApp**
---
Configure Wormhole Connect, a plug-and-play bridging UI, to enable multichain transfers for your token.
[:custom-arrow: Use Connect to Integrate NTT](/docs/build/transfers/connect/){target=\_blank}
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/evm-launchpad/
--- BEGIN CONTENT ---
---
title: Deploy Native Token Transfers with Launchpad
description: Deploy a new token or extend an existing one across multiple chains with the NTT Launchpad. Manage transfers, supply, and settings—all from a single platform.
categories: NTT, Transfer
---
# Deploy Native Token Transfers with Launchpad
## Introduction
The [Native Token Transfers (NTT) Launchpad](https://ntt.wormhole.com/){target=\_blank} is a Wormhole-managed UI application that provides a step-by-step interface for deploying NTT across multiple blockchains.
Instead of manually deploying contracts on each chain, configuring relayers, and managing cross-chain communication, you can quickly launch or expand tokens with just a few clicks.
The Launchpad automates deployment, reducing complexity and saving time.
This guide covers:
- Launching a new cross-chain token
- Expanding an existing token for NTT
- Managing tokens via the dashboard and settings
## Prerequisites
- An EVM-compatible wallet (e.g., [MetaMask](https://metamask.io/){target=\_blank}, [Phantom](https://phantom.com/){target=\_blank}, etc.)
- Minimum ETH (or equivalent) for gas fees per deployment
## Supported Blockchains
The NTT Launchpad currently supports deployments on the following mainnet chains:
- Ethereum
- Arbitrum One
- Base
- Berachain
- Blast
- BNB Smart Chain
- Ink
- Optimism Mainnet
- Polygon
## Choose Your Path
Once ready, choose an option to proceed:
- [**Launch a Cross-Chain Token**](#launch-a-cross-chain-token) - deploy a brand-new token that is NTT-ready from day one, enabling seamless transfers across multiple blockchains
- [**Expand Your Existing Token**](#expand-your-existing-token) - if you already have a token deployed on different chains, integrate it with NTT to enable NTT without modifying its original contract
## Launch a Cross-Chain Token
Deploy a new NTT-compatible token that can be transferred across multiple chains. This process sets up your token on a home network and deploys it to additional blockchains. Follow the below steps to get started:
1. Open the [NTT Launchpad](https://ntt.wormhole.com/){target=\_blank}, connect your wallet, and click **Get Started**
2. Select **Launch a Cross-Chain Token**
3. Set the token details:
1. Select the **home network** from the dropdown menu
2. Enter the **name** for the token
3. Enter the **symbol** of the token
4. Provide the **initial supply**
5. To the token details, click **Next**
4. Select the deployment chains:
1. The home network where your token will be deployed will be populated (e.g., Optimism)
2. Choose any additional chains to deploy your token to (e.g., Base)
3. To continue, click **Next**
5. To deploy on the first chain (Optimism), click on **Deploy**; if prompted, switch your wallet to the correct network and confirm the transaction
6. Once deployed, you can view the transaction in a block explorer and add the token to your wallet
7. Repeat the previous step to deploy the token on the second chain (Base). The supply of tokens on Base will be zero since the tokens were all minted on Optimism in the previous step
8. Once both deployments are completed, proceed to the [**Dashboard**](#explore-the-launchpad-dashboard) to manage your token.
## Expand Your Existing Token
Expand an existing token to support NTT across multiple chains. This process integrates your deployed token with NTT without modifying its original contract. Follow the steps below to get started:
1. Open the [NTT Launchpad](https://ntt.wormhole.com/){target=\_blank}, connect your wallet, and click **Get Started**
2. Select **Expand Your Existing Token**
3. Enter the token details:
1. Choose the home network where your token is already deployed (e.g., Optimism)
2. Choose any additional chains to deploy your token to (e.g., Base)
3. To continue, click **Next**
4. Select the chains to deploy your token to:
1. The home network where your token is already deployed will be populated (e.g., Optimism)
2. Choose any additional chains to deploy your token to (e.g., Base)
1. Click **Next**
5. To deploy on the first chain (Optimism), click on **Deploy**; if prompted, switch your wallet to the correct network and confirm the transaction
6. Once deployed, you can view the transaction in a block explorer and add the token to your wallet
7. Repeat the previous step to deploy the token on the second chain (Base). The supply of tokens on Base will be zero since the tokens were all minted on Optimism in the previous step
8. Now that your token has been deployed on multiple chains click [**Dashboard**](#explore-the-launchpad-dashboard) to review its details
## Explore the Launchpad Dashboard
To access the **Dashboard** from the [Launchpad home page](https://ntt.wormhole.com/){target=\_blank}, click on **Manage Deployment**. Here, you can view deployment status, monitor supply across chains, and configure transfer settings.
The dashboard provides a high-level view of your token across all deployed chains, including:
- Token addresses for each chain
- Supply distribution visualization
- List of deployed chains, including inbound and outbound transfer limits, which can be modified in [**Settings**](#settings)
## Settings
The **Settings** page allows you to configure security parameters, role management, and transfer limits for your deployed token. You can switch between chains to manage these settings independently for each deployment.
### Chain Management
Use the drop-down menu at the top to select the chain you want to configure. The available options correspond to the chains where your token has already been deployed. Once selected, the page displays token details specific to that chain.
From this section, you can also:
- **Pause the token** – temporarily turn off transfers on the selected chain
- **Deploy to a new chain** – expand your token by deploying it to an additional chain
### Role Management
This section displays key [roles](/docs/build/transfers/native-token-transfers/configuration/access-control/){target=\_blank} involved in token governance. You can view and modify these roles by selecting a new address and confirming the update.
- **Manager’s Owner** – the owner through the `NTTOwner` proxy
- **Pauser** – the address authorized to pause transfers
### Security Threshold
Determine and update how transceivers interact with the token. [Transceivers](/docs/build/transfers/native-token-transfers/managers-transceivers/#transceivers){target=\_blank} route NTT transfers between blockchains, ensuring tokens are correctly sent and received across networks.
A higher transceiver threshold increases security by requiring more approvals before processing a transfer, but it may also slow down transactions. A lower threshold allows faster transfers but reduces redundancy in message verification.
- **Registered Transceivers** – displays the number of registered transceivers and their addresses
- **Transceivers Threshold** – a configurable value that must be less than or equal to the number of transceivers
### Peer Chains Limits
Define the transfer restrictions for each connected network. You can adjust:
- **Sending Limits** – the maximum amount of tokens that can be sent from the home chain
- **Receiving Limits** – the maximum amount of tokens that can be received for each of the supported peer chains
Enter a new value to adjust limits and click **Update**. The changes will take effect immediately.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/installation/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Installation
description: Learn how to Install Wormhole’s Native Token Transfers (NTT) framework, a flexible and composable framework for transferring tokens across blockchains.
categories: NTT, Transfer
---
# Install the Native Token Transfers CLI
In this video, the Wormhole team walks you through installing the [Native Token Transfers (NTT) CLI](https://github.com/wormhole-foundation/native-token-transfers/tree/main/cli){target=\_blank}. You’ll see a practical demonstration of running commands, verifying your installation, and addressing common issues that might arise. If you prefer to follow written instructions or want a quick reference for each step, scroll down for the detailed installation guide.
To start using the NTT CLI, you can generate test tokens for development with the [`example-ntt-token`](https://github.com/wormhole-foundation/example-ntt-token){target=\_blank} GitHub repository by following the README instructions.
## Install NTT CLI
The fastest way to deploy Native Token Transfers (NTT) is using the NTT CLI. As prerequisites, ensure you have the following installed:
- Install [Bun](https://bun.sh/docs/installation){target=\_blank}
Follow these steps to install the NTT CLI:
1. Run the installation command in your terminal:
```bash
curl -fsSL https://raw.githubusercontent.com/wormhole-foundation/native-token-transfers/main/cli/install.sh | bash
```
2. Verify the NTT CLI is installed:
```bash
ntt --version
```
3. Once installed, check out the available [NTT CLI Commands](/docs/build/transfers/native-token-transfers/cli-commands/){target=\_blank} to start using the CLI
## Update NTT CLI
To update an existing NTT CLI installation, run the following command in your terminal:
```bash
ntt update
```
NTT CLI installations and updates will always pick up the latest tag with name vX.Y.Z+cli and verify that the underlying commit is included in main.
For local development, you can update your CLI version from a specific branch or install from a local path.
To install from a specific branch, run:
```bash
ntt update --branch foo
```
To install locally, run:
```bash
ntt update --path path/to/ntt/repo
```
Git branch and local installations enable a fast iteration loop as changes to the CLI code will immediately be reflected in the running binary without having to run any build steps.
## Where to Go Next
- :octicons-tools-16:{ .lg .middle } **Deploy to EVM Chains**
---
Deploy and configure Wormhole’s Native Token Transfers (NTT) for EVM chains, including setup, token compatibility, mint/burn modes, and CLI usage.
[:custom-arrow: Deploy NTT to EVM chains](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/)
- :octicons-tools-16:{ .lg .middle } **Deploy to Solana**
---
Deploy and configure Wormhole's Native Token Transfers (NTT) for Solana, including setup, token compatibility, mint/burn modes, and CLI usage.
[:custom-arrow: Deploy NTT to Solana](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/post-deployment/
--- BEGIN CONTENT ---
---
title: Native Token Transfers Post Deployment
description: Learn post-deployment guidelines for optimizing Wormhole NTT, which include testing, security, frontend integration, ecosystem coordination, and monitoring.
categories: NTT, Transfer
---
# Native Token Transfers Post Deployment
To offer the best user experience and ensure the most robust deployment, Wormhole contributors recommend the following after you have deployed Native Token Transfers (NTT):
- Implement a robust testing plan for your multichain token before launching
- Ensure comprehensive, documented security measures are followed for custody of contract ownership, control of keys, and access control roles. Check the [NTT configuration](/docs/build/transfers/native-token-transfers/configuration/){target=\_blank} for more details on ownership and rate limits
- Consider a streamlined, customizable frontend such as [Wormhole Connect](/docs/build/transfers/connect/){target=\_blank} for an optimized user experience
- Alternatively, the [Wormhole TypeScript SDK](/docs/build/toolkit/typescript-sdk/){target=\_blank} allows for a direct integration into your infrastructure
- Ensure ecosystem actors such as block explorers, automated security tools (such as BlockAid and Blowfish), and wallets (such as MetaMask, Backpack, and Phantom) are aware of your multichain deployment and that it is labeled appropriately
- Monitor and maintain your multichain deployment
## Manual Relaying for Solana Transfers
By default, NTT transfers to Solana require manual relaying, meaning that after initiating a cross-chain transfer, the recipient must submit an on-chain transaction to claim the tokens.
This step ensures that tokens are properly minted or unlocked on Solana and prevents unauthorized claims.
[Wormhole Connect](/docs/build/applications/connect/){target=\_blank} support this process automatically.
## Where to Go Next
- :octicons-code-16:{ .lg .middle } **Wormhole NTT Connect Demo**
---
Check out an example project that uses a Vite-React TypeScript application and integrates it with Wormhole Connect, a customizable widget for cross-chain asset transfers.
[:custom-arrow: Explore the NTT Connect demo](https://github.com/wormhole-foundation/demo-ntt-connect)
- :octicons-code-16:{ .lg .middle } **Wormhole NTT TypeScript SDK Demo**
---
Reference an example project that uses the Wormhole TypeScript SDK to facilitate token transfers between different blockchain networks after deploying the NTT framework.
[:custom-arrow: Explore the NTT TypeScript SDK demo](https://github.com/wormhole-foundation/demo-ntt-ts-sdk)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/deployment-process/troubleshooting/
--- BEGIN CONTENT ---
---
title: Troubleshooting NTT Deployment
description: Resolve common issues in NTT deployment with this troubleshooting guide covering Solana, EVM, mint authority, decimals, and rate limits.
categories: NTT, Transfer
---
# Troubleshooting NTT Deployment
If you encounter issues during the NTT deployment process, check the following common points:
- **Solana and Anchor versions** - ensure you are using the expected versions of Solana and Anchor as outlined in the [deployment page](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/#install-dependencies){target=\_blank}
- [Solana](https://docs.solanalabs.com/cli/install){target=\_blank} **`{{ ntt.solana_cli_version }}`**
- [Anchor](https://www.anchor-lang.com/docs/installation){target=\_blank} **`{{ ntt.anchor_version }}`**
- **Token compliance on EVM** - verify that your token is an ERC20 token on the EVM chain
- **Mint authority transfer**
- **For burn or spoke tokens on Solana** - ensure the token mint authority was transferred as described in the [set SPL Token Mint Authority](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/#set-spl-token-mint-authority){target=\_blank} section
- **For EVM tokens** - confirm the token minter was set to the NTT Manager. Refer to the [set Token Minter to NTT Manager](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/#set-token-minter-to-ntt-manager){target=\_blank} section for details
- **Decimal configuration** - run `ntt pull` to correctly configure the decimals in your `deployment.json` file. More details in the [configure NTT](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-solana/#configure-ntt){target=\_blank} section
- **Rate limit configuration** - increase your rate limits to a value greater than zero. A rate limit of zero can cause transactions to get stuck. Learn more on how to [configure rate limits](/docs/build/transfers/native-token-transfers/deployment-process/deploy-to-evm/#configure-ntt){target=\_blank}
- **Docker environment based on Ubuntu 20.04 with all dependencies required for Wormhole NTT CLI development** - run `docker compose up -d` to start the container in your terminal from the directory containing the `docker-compose.yml` file
???- interface "Dockerfile"
```Dockerfile
FROM ubuntu:20.04
# Set environment variables to prevent interactive prompts during installation
ENV DEBIAN_FRONTEND=noninteractive
# Update and install necessary dependencies
RUN apt-get update && apt-get install -y \
curl \
wget \
git \
build-essential \
libssl-dev \
libudev-dev \
pkg-config \
python3 \
python3-pip \
software-properties-common \
ca-certificates \
unzip \
clang \
cmake \
protobuf-compiler \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:$PATH"
# Install Solana CLI ({{ntt.solana_cli_version}})
RUN sh -c "$(curl -sSfL https://release.solana.com/{{ntt.solana_cli_version}}/install)"
ENV PATH="/root/.local/share/solana/install/active_release/bin:$PATH"
# Install Anchor using avm
RUN cargo install --git https://github.com/coral-xyz/anchor avm --locked --force \
&& avm install 0.29.0 \
&& avm use 0.29.0
ENV PATH="/root/.avm/bin:$PATH"
ENV NVM_DIR=/root/.nvm
RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash \
&& . "$NVM_DIR/nvm.sh" \
&& nvm install 22 \
&& nvm use 22 \
&& nvm alias default 22
ENV PATH="$NVM_DIR/versions/node/v22.12.0/bin:$PATH"
# Install Bun
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:$PATH"
# Install Foundry
RUN curl -L https://foundry.paradigm.xyz | bash
ENV PATH="/root/.foundry/bin:${PATH}"
RUN /bin/bash -c "source /root/.bashrc && foundryup"
# Install Wormhole NTT CLI
RUN curl -fsSL https://raw.githubusercontent.com/wormhole-foundation/native-token-transfers/main/cli/install.sh | bash
# Add a default working directory
WORKDIR /app
# Expose port for development if needed
EXPOSE 8899
# Entry point for the container
CMD ["bash"]
```
???- interface "docker-compose.yml"
```yml
services:
portal-ntt:
build:
context: .
dockerfile: Dockerfile
platform: linux/amd64
volumes:
- ./src:/app
working_dir: /app
tty: true
```
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/faqs/
--- BEGIN CONTENT ---
---
title: Native Token Transfers FAQs
description: Frequently asked questions about Wormhole Native Token Transfers, including cross-chain lending, SDK usage, custom RPCs, and integration challenges.
categories: NTT, Transfer
---
# Wormhole NTT FAQs
## Do you have an example of how cross-chain lending can be implemented using Wormhole?
Yes, we have an example of cross-chain lending that leverages [Wormhole’s Token Bridge](/docs/learn/transfers/token-bridge/){target=\_blank}. In this example, collateral deposits (such as ETH on Ethereum) are bridged to a hub chain. Once the collateral is deposited, the borrowed assets, like wrapped BNB, are bridged to Binance Smart Chain. You can explore the full implementation in the [Wormhole Lending Examples repository](https://github.com/wormhole-foundation/example-wormhole-lending){target=_blank} on GitHub.
Alternatively, you can also implement cross-chain lending using [Wormhole’s core messaging](/docs/learn/transfers/native-token-transfers/){target=\_blank} instead of the Token Bridge, which avoids the limitations imposed by governor limits. ETH would be custodied on Ethereum, and BNB on the Binance spoke during this setup. When a user deposits ETH on Ethereum, a core bridge message is sent to the hub for accounting purposes. The hub then emits a message that can be redeemed on Binance to release the BNB. This approach allows for more direct asset control across chains while reducing reliance on Token Bridge limits.
## What causes the "No protocols registered for Evm" error in Wormhole SDK?
This error typically occurs when the [Wormhole SDK](https://github.com/wormhole-foundation/wormhole-sdk-ts){target=\_blank} cannot recognize or register the necessary EVM protocols, which are required for interacting with Ethereum-based networks. The most common reason for this error is that the relevant EVM package for Wormhole's NTT has not been imported correctly.
To resolve this issue, ensure you have imported the appropriate Wormhole SDK package for EVM environments. The necessary package for handling NTT on EVM chains is `@wormhole-foundation/sdk-evm-ntt`. Here's the correct import statement:
```rust
import '@wormhole-foundation/sdk-evm-ntt';
```
By importing this package, the Wormhole SDK can register and utilize the required protocols for EVM chains, enabling cross-chain token transfers using the NTT framework. Ensure to include this import at the start of your code, especially before attempting any interactions with EVM chains in your project.
## How can I transfer ownership of NTT to a multisig?
Transferring ownership of Wormhole's NTT to a multisig is a two-step process for safety. This ensures that ownership is not transferred to an address that cannot claim it. Refer to the `transfer_ownership` method in the [NTT Manager Contract](https://github.com/wormhole-foundation/native-token-transfers/blob/main/solana/programs/example-native-token-transfers/src/instructions/admin/transfer_ownership.rs#L55){target=\_blank} to initiate the transfer.
1. **Initiate transfer** - use the `transfer_ownership` method on the NTT Manager contract to set the new owner (the multisig)
2. **Claim ownership** - the multisig must then claim ownership via the `claim_ownership` instruction. If not claimed, the current owner can cancel the transfer
3. **Single-step transfer (Riskier)** - you can also use the `transfer_ownership_one_step_unchecked` method to transfer ownership in a single step, but if the new owner cannot sign, the contract may become locked. Be cautious and ensure the new owner is a Program Derived Address (PDA)
For a practical demonstration of transferring ownership of Wormhole's NTT to a multisig on Solana, visit the [GitHub demo](https://github.com/wormhole-foundation/demo-ntt-solana-multisig-tools){target=\_blank} providing scripts and guidance for managing an NTT program using Squads multisig functionality, including ownership transfer procedures.
## How can I specify a custom RPC for NTT?
To specify a custom RPC for Wormhole's NTT, create an `overrides.json` file in the root of your deployment directory. This file allows you to define custom RPC endpoints, which can be helpful when you need to connect to specific nodes or networks for better performance, security, or control over the RPC connection.
Below’s an example of how the `overrides.json` file should be structured:
???- code "`overrides.json`"
```json
{
"chains": {
"Bsc": {
"rpc": "http://127.0.0.1:8545"
},
"Sepolia": {
"rpc": "http://127.0.0.1:8546"
},
"Solana": {
"rpc": "http://127.0.0.1:8899"
}
}
}
```
## How can I redeem tokens if NTT rate limits block them on the target chain?
If the rate limits on Wormhole's NTT block tokens from being received on the target chain, the transaction will typically be paused until the rate limits are adjusted. Rate limits are implemented to manage congestion and prevent chain abuse, but they can occasionally delay token redemptions.
To resolve this:
1. **Adjust rate limits** - the rate limits must be modified by an administrator or through the appropriate configuration tools to allow the blocked transaction to proceed
2. **Resume transaction flow** - once the rate limits are adjusted, you can resume the flow, which should be visible in the UI. The tokens will then be redeemable on the target chain
In most cases, the transaction will resume automatically once the rate limits are adjusted, and the UI will guide you through the redemption process.
## What are the challenges of deploying NTT to non-EVM chains?
NTT requires the same transceiver for all routes, limiting flexibility when deploying across EVM and non-EVM chains. For example, if you're deploying to Ethereum, Arbitrum, and Solana, you can't use Wormhole and Axelar as transceivers because Axelar doesn't support Solana. This constraint forces integrators to use a single transceiver (e.g., Wormhole) for all chains, reducing flexibility in optimizing cross-chain transfers.
## Does the NTT manager function as an escrow account for a hub chain?
Yes, the NTT manager acts like an escrow account for non-transferable tokens on a hub chain. To manage non-transferable tokens, you would add the NTT manager to the allowlist, ensuring that only the NTT manager can hold and control the tokens as they are transferred across chains.
## Which functions or events does Connect rely on for NTT integration?
Connect relies on the NTT SDK for integration, with platform-specific implementations for both [Solana](https://github.com/wormhole-foundation/native-token-transfers/blob/main/solana/ts/sdk/ntt.ts){target=\_blank} and [EVM](https://github.com/wormhole-foundation/native-token-transfers/blob/main/evm/ts/src/ntt.ts){target=\_blank}. The key methods involved include:
- **Initiate and redeem functions** - these functions are essential for initiating token transfers and redeeming them on the destination chain
- **Rate capacity methods** - methods for fetching inbound and outbound rate limits are also critical for controlling the flow of tokens and preventing congestion
These functions ensure Connect can handle token transfers and manage chain-rate limits.
## How does the relayer contract determine which transceiver to call?
The source chain's transceiver includes the destination chain's transceiver in the message via the relayer contract. The admin configures each transceiver's mapping of its peers on other chains. This mapping allows the destination transceiver to verify that the message came from a trusted source.
## How do I create a verifier or transceiver?
To run your verifier, you need to implement a transceiver. This involves approximately 200 lines of code, leveraging the base functionality provided by the [abstract transceiver contract](https://github.com/wormhole-foundation/example-native-token-transfers/blob/main/evm/src/Transceiver/Transceiver.sol){target=\_blank}.
For reference, you can review the [Axelar transceiver implementation](https://github.com/wormhole-foundation/example-wormhole-axelar-wsteth/blob/main/src/axelar/AxelarTransceiver.sol){target=\_blank}.
## Can I use Hetzner for the NTT deployment?
No, using Hetzner servers for Solana deployments is not recommended. Hetzner has blocked Solana network activity on its servers, leading to connection issues. Hetzner nodes will return a `ConnectionRefused: Unable to connect` error for Solana deployments. Therefore, choosing alternative hosting providers that support Solana deployments is advisable to ensure seamless operation.
## How can I transfer tokens with NTT with an additional payload?
You can include an extra payload in NTT messages by overriding specific methods in the [NttManager contract](https://github.com/wormhole-foundation/native-token-transfers/blob/main/evm/src/NttManager/NttManager.sol){target=\_blank}.
- On the source chain, override the [`_handleMsg` function](https://github.com/wormhole-foundation/example-native-token-transfers/blob/main/evm/src/NttManager/NttManager.sol#L216-L226){target=\_blank} to query any additional data you need for the transfer. The extra payload can then be added to the message
- On the destination chain override the [`_handleAdditionalPayload` function](https://github.com/wormhole-foundation/example-native-token-transfers/blob/main/evm/src/NttManager/NttManager.sol#L262-L275){target=\_blank} to process and utilize the extra payload sent in the message
!!!Important
You cannot pass the additional data as part of the entry point directly. Instead, the data must be queried on-chain via the `_handleMsg` method, ensuring the payload is properly included and processed.
## Why use NTT over xERC20?
Shortcomings of xERC20:
- **Single point of failure** - xERC20 relies on multiple bridges, but a compromise in any single bridge can jeopardize the token. It enforces a 1-of-n design rather than a more robust m-of-n approach
- **No pausing** - xERC20 lacks mechanisms to pause operations during emergencies
- **No access control** - there are no built-in access controls for managing token transfers securely
- **Limited rate limiting** - rate limits are bridge-specific and cannot be set per chain, reducing flexibility and security
- **No integration with relaying systems** - xERC20 does not natively support relayer systems, limiting its usability in automated or dynamic setups
While xERC20 is an extension of the ERC20 standard, NTT is designed as a framework rather than a rigid standard. It is compatible with any token that supports `burn` and `mint` functions and allows the NTT manager to act as a minter.
## How can I start transferring tokens to a chain that is in burning mode, if no tokens are locked yet?
To begin transferring tokens to a chain in burning mode when no tokens are locked, you must first send tokens to the NTT manager to back the supply. The address of the NTT manager can be found in the `deployment.json` file.
## Is there a way to use NTT tokens with chains that don't currently support NTT?
Yes. NTT tokens can be used with chains that do not support NTT by leveraging the [Token Bridge](/docs/learn/transfers/token-bridge/){target=\_blank}. For example:
- **Wrapped token scenario** - a token, such as the W token, can be bridged to non-NTT networks using the Token Bridge. When the token is bridged to a chain like Sui, a wrapped version of the token is created (e.g., Wrapped W token)
- **Unwrapping requirement** - tokens bridged using the Token Bridge cannot be directly transferred to NTT-supported chains. To transfer them, they must first be unwrapped on the non-NTT chain and then transferred via the appropriate mechanism
- **Messaging consistency** - the Token Bridge exclusively uses Wormhole messaging, ensuring consistent communication across all chains, whether or not they support NTT
This approach ensures interoperability while maintaining the integrity of the token's cross-chain movement.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/transfers/native-token-transfers/managers-transceivers/
--- BEGIN CONTENT ---
---
title: Managers and Transceivers
description: Explore the roles of Managers and Transceivers in NTT cross-chain token transfers, including key functions, lifecycle events, and rate-limiting mechanisms.
categories: NTT, Transfer
---
# Managers and Transceivers
## Managers
_Managers_ oversee the token transfer process and handle rate-limiting and message attestation. They manage interactions with multiple transceivers and ensure that tokens are locked or burned on the source chain before being minted or unlocked on the destination chain. Each NTT manager corresponds to a single token but can control multiple transceivers. Key functions include:
- **`transfer`** - initiate the transfer process where tokens on the source chain are locked or burned. This process ensures that an equivalent amount of tokens can be minted or unlocked on the destination chain
```solidity
function transfer(
uint256 amount, // amount (in atomic units)
uint16 recipientChain, // chain ID (Wormhole formatted)
bytes32 recipient // recipient address (Wormhole formatted)
) external payable nonReentrant whenNotPaused returns (uint64)
```
- **`quoteDeliveryPrice`** - calculate the cost of sending messages across chains by querying the transceivers for estimates on message delivery fees, allowing users to know the price before initiating a transfer
```solidity
function quoteDeliveryPrice(
uint16 recipientChain, // chain ID (Wormhole formatted)
bytes memory transceiverInstructions // extra instructions for transceivers (Transceiver-dependent on whether extra instructions are used/accepted)
) public view returns (uint256[] memory, uint256)
```
- **`setPeer`** - to maintain secure cross-chain communication, managers establish trust relationships between different instances of NTT manager contracts across chains. By recognizing each other as peers, they ensure that the token transfers happen securely and that rate limits on inbound transactions are respected
```solidity
function setPeer(
uint16 peerChainId, // chain ID (Wormhole formatted)
bytes32 peerContract, // peer NTT Manager address (Wormhole formatted)
uint8 decimals, // token decimals on the peer chain
uint256 inboundLimit // inbound rate limit (in atomic units)
) public onlyOwner
```
## Transceivers
_Transceivers_ are responsible for routing NTT transfers through the manager on the source chain and ensuring they are delivered to the corresponding manager on the recipient chain. They work with managers to ensure that messages are accurately processed and tokens are correctly transferred, providing a reliable system for cross-chain token transfers. Transceivers can be defined independently of the Wormhole core and modified to support any verification backend. Key functions:
- **`sendMessage`** - this external function sends token transfer messages to a specified recipient chain. It encodes the token transfer details into a message format recognized by the system
```solidity
function sendMessage(
uint16 recipientChain, // chain ID (Wormhole formatted)
TransceiverStructs.TransceiverInstruction memory instruction, // extra instruction for the Transceiver (optional, dependent on whether extra instructions are used/accepted for this Transceiver)
bytes memory nttManagerMessage, // serialized NTT Manager message, provided by the NTT Manager
bytes32 recipientNttManagerAddress, // NTT Manager address on the recipient chain (Wormhole formatted)
bytes32 refundAddress // address to receive refunds on the destination chain in case of excess quotes (Wormhole formatted)
) external payable nonReentrant onlyNttManager
```
- **`quoteDeliveryPrice`** - provides an estimation of the cost associated with delivering a message to a target chain and gauges transaction fees
```solidity
function quoteDeliveryPrice(
uint16 targetChain, // chain ID (Wormhole formatted)
TransceiverStructs.TransceiverInstruction memory instruction // extra instruction for the Transceiver (optional, dependent on whether extra instructions are used/accepted for this Transceiver)
) external view returns (uint256)
```
## Lifecycle of a Message
### EVM
#### Transfer
A client calls on `transfer` to initiate an NTT transfer. The client must specify, at minimum, the transfer amount, the recipient chain, and the recipient address on the recipient chain. `transfer` also supports a flag to specify whether the `NttManager` should queue rate-limited transfers or revert. Clients can also include additional instructions to forward along to the transceiver on the source chain. Depending on the mode set in the initial configuration of the `NttManager` contract, transfers are either "locked" or "burned." Once the transfer has been forwarded to the transceiver, the `NttManager` emits the `TransferSent` event.
**Events**
```ts
/// @notice Emitted when a message is sent from the nttManager.
/// @dev Topic0
/// 0x9716fe52fe4e02cf924ae28f19f5748ef59877c6496041b986fbad3dae6a8ecf
/// @param recipient The recipient of the message.
/// @param amount The amount transferred.
/// @param fee The amount of ether sent along with the tx to cover the delivery fee.
/// @param recipientChain The chain ID of the recipient.
/// @param msgSequence The unique sequence ID of the message.
event TransferSent(
bytes32 recipient, uint256 amount, uint256 fee, uint16 recipientChain, uint64 msgSequence
);
```
#### Rate Limit
A transfer can be rate-limited on both the source and destination chains. If a transfer is rate-limited on the source chain and the `shouldQueue` flag is enabled, it is added to an outbound queue. The transfer can be released after the configured `_rateLimitDuration` has expired via the `completeOutboundQueuedTransfer` method. The `OutboundTransferQueued` and `OutboundTransferRateLimited` events are emitted.
If the client attempts to release the transfer from the queue before the expiry of the `rateLimitDuration`, the contract reverts with an `OutboundQueuedTransferStillQueued` error.
Similarly, rate-limited transfers on the destination chain are added to an inbound queue. These transfers can be released from the queue via the `completeInboundQueuedTransfer` method, and the `InboundTransferQueued` event is emitted.
If the client attempts to release the transfer from the queue before the `rateLimitDuration` expires, the contract reverts with an `InboundQueuedTransferStillQueued` error.
To deactivate the rate limiter, set `_rateLimitDuration` to 0 and enable the `_skipRateLimiting` field in the `NttManager` constructor. Configuring this incorrectly will throw an error. If the rate limiter is deactivated, the inbound and outbound rate limits can be set to 0.
**Events**
```ts
/// @notice Emitted whenn an outbound transfer is queued.
/// @dev Topic0
/// 0x69add1952a6a6b9cb86f04d05f0cb605cbb469a50ae916139d34495a9991481f.
/// @param queueSequence The location of the transfer in the queue.
event OutboundTransferQueued(uint64 queueSequence);
```
```ts
/// @notice Emitted when an outbound transfer is rate limited.
/// @dev Topic0
/// 0x754d657d1363ee47d967b415652b739bfe96d5729ccf2f26625dcdbc147db68b.
/// @param sender The initial sender of the transfer.
/// @param amount The amount to be transferred.
/// @param currentCapacity The capacity left for transfers within the 24-hour window.
event OutboundTransferRateLimited(
address indexed sender, uint64 sequence, uint256 amount, uint256 currentCapacity
);
```
```ts
/// @notice Emitted when an inbound transfer is queued
/// @dev Topic0
/// 0x7f63c9251d82a933210c2b6d0b0f116252c3c116788120e64e8e8215df6f3162.
/// @param digest The digest of the message.
event InboundTransferQueued(bytes32 digest);
```
#### Send
Once the `NttManager` forwards the message to the transceiver, the message is transmitted via the `sendMessage method`. The method signature is enforced by the transceiver but transceivers are free to determine their own implementation for transmitting messages. (e.g. a message routed through the Wormhole transceiver can be sent via Wormhole relaying, a custom relayer, or manually published via the core bridge).
Once the message has been transmitted, the contract emits the `SendTransceiverMessage` event.
**Events**
```ts
/// @notice Emitted when a message is sent from the transceiver.
/// @dev Topic0
/// 0x53b3e029c5ead7bffc739118953883859d30b1aaa086e0dca4d0a1c99cd9c3f5.
/// @param recipientChain The chain ID of the recipient.
/// @param message The message.
event SendTransceiverMessage(
uint16 recipientChain, TransceiverStructs.TransceiverMessage message
);
```
#### Receive
Once a message has been emitted by a transceiver on the source chain, an off-chain process (for example, a relayer) will forward the message to the corresponding transceiver on the recipient chain. The relayer interacts with the transceiver via an entry point to receive messages. For example, the relayer will call the `receiveWormholeMessage` method on the `WormholeTransceiver` contract to execute the message. The `ReceiveRelayedMessage` event is emitted during this process.
This method should also forward the message to the `NttManager` on the destination chain. Note that the transceiver interface doesn't declare a signature for this method because receiving messages is specific to each transceiver, and a one-size-fits-all solution would be overly restrictive.
The `NttManager` contract allows an M of N threshold for transceiver attestations to determine whether a message can be safely executed. For example, if the threshold requirement is 1, the message will be executed after a single transceiver delivers a valid attestation. If the threshold requirement is 2, the message will only be executed after two transceivers deliver valid attestations. When a transceiver attests to a message, the contract emits the `MessageAttestedTo` event.
NTT implements replay protection, so if a given transceiver attempts to deliver a message attestation twice, the contract reverts with `TransceiverAlreadyAttestedToMessage` error. NTT also implements replay protection against re-executing messages. This check also acts as reentrancy protection as well.
If a message has already been executed, the contract ends execution early and emits the `MessageAlreadyExecuted` event instead of reverting via an error. This mitigates the possibility of race conditions from transceivers attempting to deliver the same message when the threshold is less than the total number of available of transceivers (i.e. threshold < totalTransceivers) and notifies the client (off-chain process) so they don't attempt redundant message delivery.
**Events**
```ts
/// @notice Emitted when a relayed message is received.
/// @dev Topic0
/// 0xf557dbbb087662f52c815f6c7ee350628a37a51eae9608ff840d996b65f87475
/// @param digest The digest of the message.
/// @param emitterChainId The chain ID of the emitter.
/// @param emitterAddress The address of the emitter.
event ReceivedRelayedMessage(bytes32 digest, uint16 emitterChainId, bytes32 emitterAddress);
```
```ts
/// @notice Emitted when a message is received.
/// @dev Topic0
/// 0xf6fc529540981400dc64edf649eb5e2e0eb5812a27f8c81bac2c1d317e71a5f0.
/// @param digest The digest of the message.
/// @param emitterChainId The chain ID of the emitter.
/// @param emitterAddress The address of the emitter.
/// @param sequence The sequence of the message.
event ReceivedMessage(
bytes32 digest, uint16 emitterChainId, bytes32 emitterAddress, uint64 sequence
);
```
```ts
/// @notice Emitted when a message has already been executed to notify client of against retries.
/// @dev Topic0
/// 0x4069dff8c9df7e38d2867c0910bd96fd61787695e5380281148c04932d02bef2.
/// @param sourceNttManager The address of the source nttManager.
/// @param msgHash The keccak-256 hash of the message.
event MessageAlreadyExecuted(bytes32 indexed sourceNttManager, bytes32 indexed msgHash);
```
#### Mint or Unlock
Once a transfer has been successfully verified, the tokens can be minted (if the mode is "burning") or unlocked (if the mode is "locking") to the recipient on the destination chain. Note that the source token decimals are bounded between `0` and `TRIMMED_DECIMALS` as enforced in the wire format. The transfer amount is untrimmed (scaled-up) if the destination chain token decimals exceed `TRIMMED_DECIMALS`. Once the appropriate number of tokens have been minted or unlocked to the recipient, the `TransferRedeemed` event is emitted.
**Events**
```ts
/// @notice Emitted when a transfer has been redeemed
/// (either minted or unlocked on the recipient chain).
/// @dev Topic0
/// 0x504e6efe18ab9eed10dc6501a417f5b12a2f7f2b1593aed9b89f9bce3cf29a91.
/// @param digest The digest of the message.
event TransferRedeemed(bytes32 indexed digest);
```
### Solana
#### Transfer
A client calls the `transfer_lock` or `transfer_burn` instruction based on whether the program is in `LOCKING` or `BURNING` mode. The program mode is set during initialization. When transferring, the client must specify the amount of the transfer, the recipient chain, the recipient address on the recipient chain, and the boolean flag `should_queue` to specify whether the transfer should be queued if it hits the outbound rate limit. If `should_queue` is set to false, the transfer reverts instead of queuing if the rate limit were to be hit.
!!! note
Using the wrong transfer instruction, i.e. `transfer_lock` for a program that is in `BURNING` mode, will result in an `InvalidMode` error.
Depending on the mode and instruction, the following will be produced in the program logs:
```ts
Program log: Instruction: TransferLock
Program log: Instruction: TransferBurn
```
Outbound transfers are always added to an Outbox via the `insert_into_outbox` method. This method checks the transfer against the configured outbound rate limit amount to determine whether the transfer should be rate-limited. An `OutboxItem` is a Solana Account that holds details of the outbound transfer. The transfer can be released from the Outbox immediately if no rate limit is hit. The transfer can be released from the Outbox immediately unless a rate limit is hit, in which case it will only be released after the delay duration associated with the rate limit has expired.
#### Rate Limit
During the transfer process, the program checks rate limits via the `consume_or_delay` function. The Solana rate-limiting logic is equivalent to the EVM rate-limiting logic.
If the transfer amount fits within the current capacity:
- Reduce the current capacity
- Refill the inbound capacity for the destination chain
- Add the transfer to the Outbox with `release_timestamp` set to the current timestamp, so it can be released immediately.
If the transfer amount doesn't fit within the current capacity:
- If `shouldQueue = true`, add the transfer to the Outbox with `release_timestamp` set to the current timestamp plus the configured `RATE_LIMIT_DURATION`.
- If `shouldQueue = false`, revert with a `TransferExceedsRateLimit` error
#### Send
The caller then needs to request each transceiver to send messages via the `release_outbound` instruction. To execute this instruction, the caller needs to pass the account of the Outbox item to be released. The instruction will then verify that the transceiver is one of the specified senders for the message. Transceivers then send the messages based on the verification backend they are using.
For example, the Wormhole transceiver will send by calling `post_message` on the Wormhole program, so that the Wormhole Guardians can observe and verify the message.
!!! note
When `revert_on_delay` is true, the transaction will revert if the release timestamp hasn't been reached. When `revert_on_delay` is false, the transaction succeeds, but the outbound release isn't performed.
The following will be produced in the program logs:
```ts
Program log: Instruction: ReleaseOutbound
```
#### Receive
Similar to EVM, transceivers vary in how they receive messages since message relaying and verification methods may differ between implementations.
The Wormhole transceiver receives a verified Wormhole message on Solana via the `receive_message` entrypoint instruction. Callers can use the `receive_wormhole_message` Anchor library function to execute this instruction. The instruction verifies the Wormhole Verified Action Approvals (VAAs) and stores it in a `VerifiedTransceiverMessage` account.
The following will be produced in the program logs:
```ts
Program log: Instruction: ReceiveMessage
```
`redeem` checks the inbound rate limit and places the message in an Inbox. Logic works the same as the outbound rate limit mentioned previously.
The following will be produced in the program logs:
```ts
Program log: Instruction: Redeem
```
#### Mint or Unlock
The inbound transfer is released and the tokens are unlocked or minted to the recipient through either `release_inbound_mint` if the mode is `BURNING`, or `release_inbound_unlock` if the mode is `LOCKING`. Similar to transfer, using the wrong transfer instruction (such as `release_inbound_mint` for a program that is in locking mode) will result in `InvalidMode` error.
!!! note
When `revert_on_delay` is true, the transaction will revert if the release timestamp hasn't been reached. When `revert_on_delay` is false, the transaction succeeds, but the minting/unlocking isn't performed.
Depending on the mode and instruction, the following will be produced in the program logs:
```ts
Program log: Instruction: ReleaseInboundMint
Program log: Instruction: ReleaseInboundUnlock
```
--- END CONTENT ---
## Basics Concepts [shared: true]
The following section contains foundational documentation shared across all Wormhole products.
It describes the architecture and messaging infrastructure that serve as the backbone for all integrations built with Wormhole.
This includes the core contracts, VAA (Verifiable Action Approval) structure, guardian set functionality, and message flow mechanisms.
This context is provided to help understand how the system works under the hood, but responses should stay focused on the specific product unless the user explicitly asks about the general architecture.
---
## List of shared concept pages:
## Full content for shared concepts:
Doc-Content: https://wormhole.com/docs/learn/glossary/
--- BEGIN CONTENT ---
---
title: Glossary
description: Explore a comprehensive glossary of technical terms and key concepts used in the Wormhole network, covering Chain ID, Guardian, VAA, and more.
categories: Basics
---
# 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/build/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/build/reference/consistency-levels/){target=\_blank} reference page for details.
## Delivery Provider
A Delivery Provider monitors for Wormhole Relayer 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 for the message 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 won't be reverted.
## Guardian
A [Guardian](/docs/learn/infrastructure/guardians/){target=\_blank} is one of the 19 parties running validators in the Guardian Network contributing to the VAA multisig.
## Guardian Network
Validators in their own P2P network who serve as Wormhole's oracle by observing activity on-chain and generating signed messages attesting to that activity.
## Guardian Set
The Guardian Set is a set of guardians responsible for validating a message emitted from the core contracts. Occasionally, the members of the set will change through a governance action.
## 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/learn/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.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/
--- BEGIN CONTENT ---
---
title: Infrastructure Components
description: Explore Wormhole's infrastructure, including the key components that enable secure multichain communication and asset transfers across blockchain networks.
categories: Basics
---
# Infrastructure Components
This section examines the core components that power Wormhole's infrastructure, including Guardians, relayers, VAAs, and the Spy.
## Get Started
Start here for an overview of Wormhole architecture components and security mechanisms:
- :octicons-book-16:{ .lg .middle } **Architecture Overview**
---
Overview of Wormhole's architecture, detailing key on-chain and off-chain components like the Core Contract, Guardian Network, and relayers.
[:custom-arrow: Learn About Architecture](/docs/learn/infrastructure/architecture/)
- :octicons-book-16:{ .lg .middle } **Security**
---
Explore Wormhole's security features, including the Guardian network, governance, and monitoring.
[:custom-arrow: Learn About Security](/docs/learn/security/)
## Explore Components
The relationship between individual components can be demonstrated through the simplified flow of a multichain message from a source-chain contract to a target-chain contract. Select the title of each step to learn more about that component:
[timeline left(wormhole-docs/.snippets/text/learn/infrastructure/infrastructure-index-timeline.json)]
The [Spy](/docs/learn/infrastructure/spy/) continuously runs in the background to subscribe to gossiped messages across the Guardian Network and enable real-time network activity monitoring.
## Next Steps
- :octicons-book-16:{ .lg .middle } **Messaging Components**
---
Learn more about individual messaging components such as Core Contracts, VAAs, Guardians, and relayers
[:custom-arrow: Explore Core Contracts](/docs/learn/infrastructure/core-contracts/)
- :octicons-people-16:{ .lg .middle } **Core Messaging Guides**
---
Explore this section for guides to using Wormhole Relayer and Core Contracts in your project.
[:custom-arrow: Build with Core Messaging](/docs/build/core-messaging/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/architecture/
--- BEGIN CONTENT ---
---
title: Architecture
description: Overview of Wormhole's architecture, detailing key on-chain and off-chain components like the Core Contract, Guardian Network, and relayers.
categories: Basics
---
# Architecture
## Overview
Wormhole has several noteworthy components. Before discussing each component in depth, this page will provide an overview of how the major pieces fit together.
The preceding diagram outlines the end-to-end flow of multichain communication through Wormhole's architecture, which is described as follows:
1. **Source chain** - a source contract emits a message by interacting with the [Wormhole Core Contract](/docs/learn/infrastructure/core-contracts/){target=\_blank} on the source chain, which publishes the message in the blockchain's transaction logs
2. **Guardian Network** - [Guardians](/docs/learn/infrastructure/guardians/){target=\_blank} validate these messages and sign them to produce [Verifiable Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank}
3. **Relayers** - off-chain relayers or applications fetch the VAA and relay it to the target chain
4. **Target chain** - on the target chain, the message is consumed by the appropriate contract. This contract interacts with the Wormhole Core Contract to verify the VAA and execute the intended multichain operation.
The flow from the relayer to the target chain involves an entry point contract, which could vary based on the use case:
- In some applications, the target contract acts as the entry point and performs verification via the Core Contract
- In products like the Token Bridge, the Token Bridge contract itself interacts with the Core Contract
## On-Chain Components
- **Emitter** - a contract that calls the publish message method on the Core Contract. To identify the message, the Core Contract will write an event to the transaction logs with details about the emitter and sequence number. This may be your [xDapp](/docs/learn/glossary/#xdapp){target=\_blank} or an existing ecosystem protocol
- **[Wormhole Core Contract](/docs/learn/infrastructure/core-contracts/){target=\_blank}** - primary contract, this is the contract which the Guardians observe and which fundamentally allows for multichain communication
- **Transaction logs** - blockchain-specific logs that allow the Guardians to observe messages emitted by the Core Contract
## Off-Chain Components
- **Guardian Network** - validators that exist in their own P2P network. Guardians observe and validate the messages emitted by the Core Contract on each supported chain to produce VAAs (signed messages)
- **[Guardian](/docs/learn/infrastructure/guardians/){target=\_blank}** - one of 19 validators in the Guardian Network that contributes to the VAA multisig
- **[Spy](/docs/learn/infrastructure/spy/){target=\_blank}** - a daemon that subscribes to messages published within the Guardian Network. A Spy can observe and forward network traffic, which helps scale up VAA distribution
- **[API](https://docs.wormholescan.io/){target=\_blank}** - a REST server to retrieve details for a VAA or the Guardian Network
- **[VAAs](/docs/learn/infrastructure/vaas/){target=\_blank}** - Verifiable Action Approvals (VAAs) are the signed attestation of an observed message from the Wormhole Core Contract
- **[Relayer](/docs/learn/infrastructure/relayer/){target=\_blank}** - any off-chain process that relays a VAA to the target chain
- **Wormhole relayers** - a decentralized relayer network that delivers messages that are requested on-chain via the Wormhole relayer contract
- **Custom relayers** - relayers that only handle VAAs for a specific protocol or multichain application. They can execute custom logic off-chain, reducing gas costs and increasing multichain compatibility. Currently, multichain application developers are responsible for developing and hosting custom relayers
## Next Steps
- :octicons-book-16:{ .lg .middle } **Core Contracts**
---
Discover Wormhole's Core Contracts, enabling multichain communication with message sending, receiving, and multicast features for efficient synchronization.
[:custom-arrow: Explore Core Contracts](/docs/learn/infrastructure/core-contracts/)
- :octicons-tools-16:{ .lg .middle } **Core Messaging**
---
Follow the guides in this section to work directly with the building blocks of Wormhole messaging, Wormhole-deployed relayers and Core Contracts, to send, receive, validate, and track multichain messages.
[:custom-arrow: Build with Core Messaging](/docs/build/core-messaging/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/core-contracts/
--- BEGIN CONTENT ---
---
title: Core Contracts
description: Discover Wormhole's Core Contracts, which enable multichain communication with message sending, receiving, and multicast features for efficient synchronization.
categories: Basics
---
# Core Contracts
## Introduction
The Wormhole Core Contract is deployed across each supported blockchain network. This contract is a fundamental component of the Wormhole interoperability protocol and acts as the foundational layer enabling secure and efficient multichain messaging. All multichain applications either interact directly with the Core Contract or with another contract that does.
This page summarizes the key functions of the Core Contract and outlines how the Core Contract works.
## Key Functions
Key functions of the Wormhole Core Contract include the following:
- **Multichain messaging** - standardizes and secures the format of messages to facilitate consistent communication for message transfer between Wormhole-connected blockchain networks, allowing developers to leverage the unique features of each network
- **Verification and validation** - verifies and validates all VAAs received on the target chain by confirming the Guardian signature to ensure the message is legitimate and has not been manipulated or altered
- **Guardian Network coordination** - coordinates with Wormhole's Guardian Network to facilitate secure, trustless communication across chains and ensure that only validated interactions are processed to enhance the protocol's overall security and reliability
- **Event emission for monitoring** - emits events for every multichain message processed, allowing for network activity monitoring like tracking message statuses, debugging, and applications that can react to multichain events in real time
## How the Core Contract Works
The Wormhole Core Contract is central in facilitating secure and efficient multichain transactions. It enables communication between different blockchain networks by packaging transaction data into standardized messages, verifying their authenticity, and ensuring they are executed correctly on the destination chain.
The following describes the role of the Wormhole Core Contract in message transfers:
1. **Message submission** - when a user initiates a multichain transaction, the Wormhole Core Contract on the source chain packages the transaction data into a standardized message payload and submits it to the Guardian Network for verification
2. **Guardian verification** - the Guardians independently observe and sign the message. Once enough Guardians have signed the message, the collection of signatures is combined with the message and metadata to produce a VAA
3. **Message reception and execution** - on the target chain, the Wormhole Core Contract receives the verified message, checks the Guardians' signatures, and executes the corresponding actions like minting tokens, updating states, or calling specific smart contract functions
For a closer look at how messages flow between chains and all of the components involved, you can refer to the [Architecture Overview](/docs/learn/infrastructure/architecture/) page.
### Message Submission
You can send multichain messages by calling a function against the source chain Core Contract, which then publishes the message. Message publishing strategies can differ by chain; however, generally, the Core Contract posts the following items to the blockchain logs:
- `emitterAddress` - the contract which made the call to publish the message
- `sequenceNumber` - a unique number that increments for every message for a given emitter (and implicitly chain)
- `consistencyLevel`- the level of finality to reach before the Guardians will observe and attest the emitted event. This is a defense against reorgs and rollbacks since a transaction, once considered "final," is guaranteed not to have the state changes it caused rolled back. Since different chains use different consensus mechanisms, each one has different finality assumptions, so this value is treated differently on a chain-by-chain basis. See the options for finality for each chain in the [Wormhole Finality](/docs/build/reference/consistency-levels/){target=\_blank} reference page
There are no fees to publish a message except when publishing on Solana, but this is subject to change in the future.
### Message Reception
When you receive a multichain message on the target chain Core Contract, you generally must parse and verify the [components of a VAA](/docs/learn/infrastructure/vaas#vaa-format){target=\_blank}. Receiving and verifying a VAA ensures that the Guardian Network properly attests to the message and maintains the integrity and authenticity of the data transmitted between chains.
## Multicast
Multicast refers to simultaneously broadcasting a single message or transaction across different blockchains with no destination address or chain for the sending and receiving functions. VAAs attest that "this contract on this chain said this thing." Therefore, VAAs are multicast by default and will be verified as authentic on any chain where they are used.
This multicast-by-default model makes it easy to synchronize state across the entire ecosystem. A blockchain can make its data available to every chain in a single action with low latency, which reduces the complexity of the n^2 problems encountered by routing data to many blockchains.
This doesn't mean an application _cannot_ specify a destination address or chain. For example, the [Token Bridge](/docs/learn/transfers/token-bridge/){target=\_blank} and [Wormhole relayer](/docs/learn/infrastructure/relayer/){target=\_blank} contracts require that some destination details be passed and verified on the destination chain.
Because the VAA creation is separate from relaying, the multicast model does not incur an additional cost when a single chain is targeted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
## Next Steps
- :octicons-book-16:{ .lg .middle } **Verified Action Approvals (VAA)**
---
Learn about Verified Action Approvals (VAAs) in Wormhole, their structure, validation, and their role in multichain communication.
[:custom-arrow: Learn About VAAs](/docs/learn/infrastructure/vaas/)
- :octicons-tools-16:{ .lg .middle } **Get Started with Core Contracts**
---
This guide walks through the key methods of the Core Contracts, providing you with the knowledge needed to integrate them into your multichain contracts.
[:custom-arrow: Build with Core Contracts](/docs/build/core-messaging/core-contracts/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/guardians/
--- BEGIN CONTENT ---
---
title: Guardians
description: Explore Wormhole's Guardian Network, a decentralized system for secure, scalable cross-chain communication across various blockchain ecosystems.
categories: Basics
---
## Guardian
Wormhole relies on a set of 19 distributed nodes that monitor the state on several blockchains. In Wormhole, these nodes are referred to as Guardians. The current Guardian set can be seen in the [Dashboard](https://wormhole-foundation.github.io/wormhole-dashboard/#/?endpoint=Mainnet){target=\_blank}.
Guardians fulfill their role in the messaging protocol as follows:
1. Each Guardian observes messages and signs the corresponding payloads in isolation from the other Guardians
2. Guardians combine their indpendent signatures to form a multisig
3. This multisig represents proof that a majority of the Wormhole network has observed and agreed upon a state
Wormhole refers to these multisigs as [Verifiable Action Approvals](/docs/learn/infrastructure/vaas/){target=\_blank} (VAAs).
## 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's not well-suited for a network that verifies many blockchains and doesn't 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 De-Fi 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 carefully chosen
- **19 validators is the optimal tradeoff** - a set of 19 participants presents a practical compromise between decentralization and efficiency. With a two-thirds consensus threshold, only 13 signatures must be verified on-chain—keeping gas costs reasonable while ensuring strong security
- **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 ([relayers](/docs/learn/infrastructure/relayer/){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/learn/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.
Every Guardian must run a full node for every blockchain in the ecosystem. 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.
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:
- **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 } **Relayers**
---
Discover the role of relayers in the Wormhole network, including client-side, custom, and Wormhole-deployed types, for secure cross-chain communication.
[:custom-arrow: Learn About Relayers](/docs/learn/infrastructure/relayer/)
- :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/build/queries/overview/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/relayer/
--- BEGIN CONTENT ---
---
title: Relayers
description: Discover the role of relayers in the Wormhole network, including client-side, custom, and Wormhole-deployed types, for secure cross-chain communication.
categories: Basics
---
# Relayers
This page provides a comprehensive guide to relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes.
Relayers in the Wormhole context are processes that deliver [Verified Action Approvals (VAAs)](/docs/learn/infrastructure/vaas/){target=\_blank} to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only availability, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome.
There are three primary types of relayers discussed:
- **Client-side relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved
- **Custom relayers** - backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy relaying)
- **Wormhole-deployed relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient
## Fundamentals
This section highlights the crucial principles underpinning the operation and handling of relayers within the Wormhole network.
Relayers are fundamentally trustless entities within the network, meaning while they don't require your trust to operate, you also shouldn't trust them implicitly. Relayers function as delivery mechanisms, transporting VAAs from their source to their destination.
Key characteristics of VAAs include:
- Public emission from the Guardian Network
- Authentication through signatures from the Guardian Network
- Verifiability by any entity or any Wormhole Core Contract
These characteristics mean anyone can pick up a VAA and deliver it anywhere, but no one can alter the VAA content without invalidating the signatures.
Keep in mind the following security considerations around relayers:
- **Trusting information** - it is crucial not to trust information outside your contract or a VAA. Relying on information from a relayer could expose you to input attacks
- **Gas optimization** - using relayers to perform trustless off-chain computation to pass into the destination contract can optimize gas costs but also risk creating attack vectors if not used correctly
- **Deterministic by design** - the design of a relayer should ensure a single, deterministic way to process messages in your protocol. Relayers should have a "correct" implementation, mirroring "crank turner" processes used elsewhere in blockchain
## Client-Side Relaying
Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to complete the cross-chain process.
### Key Features
- **Cost-efficiency** - users only pay the transaction fee for the second transaction, eliminating any additional costs
- **No backend infrastructure** - the process is wholly client-based, eliminating the need for a backend relaying infrastructure
### Implementation
Users themselves carry out the three steps of the cross-chain process:
1. Perform an action on chain A
2. Retrieve the resulting VAA from the Guardian Network
3. Perform an action on chain B using the VAA
### Considerations
Though simple, this type of relaying is generally not recommended if your aim is a highly polished user experience. It can, however, be useful for getting a Minimum Viable Product (MVP) up and running.
- Users must sign all required transactions with their own wallet
- Users must have funds to pay the transaction fees on every chain involved
- The user experience may be cumbersome due to the manual steps involved
## Custom Relayers
Custom relayers are purpose-built components within the Wormhole protocol, designed to relay messages for specific applications. They can perform off-chain computations and can be customized to suit a variety of use cases.
The main method of setting up a custom relayer is by listening directly to the Guardian Network via a [Spy](/docs/learn/infrastructure/spy/).
### Key Features
- **Optimization** - capable of performing trustless off-chain computations which can optimize gas costs
- **Customizability** - allows for specific strategies like batching, conditional delivery, multi-chain deliveries, and more
- **Incentive structure** - developers have the freedom to design an incentive structure suitable for their application
- **Enhanced UX** - the ability to retrieve a VAA from the Guardian Network and perform an action on the target chain using the VAA on behalf of the user can simplify the user experience
### Implementation
A plugin relayer to make the development of custom relayers easier is available in the [main Wormhole repository](https://github.com/wormhole-foundation/wormhole/tree/main/relayer){target=\_blank}. This plugin sets up the basic infrastructure for relaying, allowing developers to focus on implementing the specific logic for their application.
### Considerations
Remember, despite their name, custom relayers still need to be considered trustless. VAAs are public and can be submitted by anyone, so developers shouldn't rely on off-chain relayers to perform any computation considered "trusted."
- Development work and hosting of relayers are required
- The fee-modeling can become complex, as relayers are responsible for paying target chain fees
- Relayers are responsible for availability, and adding dependencies for the cross-chain application
## Wormhole Relayers
Wormhole relayers are a component of a decentralized network in the Wormhole protocol. They facilitate the delivery of VAAs to recipient contracts compatible with the standard relayer API.
### Key Features
- **Lower operational costs** - no need to develop, host, or maintain individual relayers
- **Simplified integration** - because there is no need to run a relayer, integration is as simple as calling a function and implementing an interface
### Implementation
The Wormhole relayer integration involves two key steps:
- **Delivery request** - request delivery from the ecosystem Wormhole relayer contract
- **Relay reception** - implement a [`receiveWormholeMessages`](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/bacbe82e6ae3f7f5ec7cdcd7d480f1e528471bbb/src/interfaces/IWormholeReceiver.sol#L44-L50){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA
### Considerations
Developers should note that the choice of relayers depends on their project's specific requirements and constraints. Wormhole relayers offer simplicity and convenience but limit customization and optimization opportunities compared to custom relayers.
- All computations are performed on-chain
- Potentially less gas-efficient compared to custom relayers
- Optimization features like conditional delivery, batching, and off-chain calculations might be restricted
- Support may not be available for all chains
## Next Steps
- :octicons-book-16:{ .lg .middle } **Spy**
---
Discover Wormhole's Spy daemon, which subscribes to gossiped messages in the Guardian Network, including VAAs and Observations, with setup instructions.
[:custom-arrow: Learn More About the Spy](/docs/learn/infrastructure/spy/)
- :octicons-book-16:{ .lg .middle } **Build with Wormhole Relayers**
---
Learn how to use Wormhole-deployed relayer configurations for seamless cross-chain messaging between contracts on different EVM blockchains without off-chain deployments.
[:custom-arrow: Get Started with Wormhole Relayers](/docs/build/core-messaging/wormhole-relayers/)
- :octicons-book-16:{ .lg .middle } **Run a Custom Relayer**
---
Learn how to build and configure your own off-chain custom relaying solution to relay Wormhole messages for your applications using the Relayer Engine.
[:custom-arrow: Get Started with Custom Relayers](/docs/infrastructure/relayers/run-relayer/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/spy/
--- BEGIN CONTENT ---
---
title: Spy
description: Discover Wormhole's Spy daemon, which subscribes to gossiped messages in the Guardian Network, including VAAs and Observations, with setup instructions.
categories: Basics
---
# 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 (Token Bridge, 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/learn/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/learn/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/learn/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/build/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/infrastructure/spy/run-spy/){target=\_blank}
- :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/build/queries/use-queries/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/infrastructure/vaas/
--- BEGIN CONTENT ---
---
title: VAAs
description: Learn about Verified Action Approvals (VAAs) in Wormhole, their structure, validation, and role in cross-chain communication.
categories: Basics
---
# Verified Action Approvals
Verified Action Approvals (VAAs) are Wormhole's core messaging primitive. They are packets of cross-chain data emitted whenever a cross-chain application contract interacts with the Core Contract.
[Guardians](/docs/learn/infrastructure/guardians/){target=\_blank} validate messages emitted by contracts before sending them to the target chain. Once a majority of Guardians agree the message is valid, they sign a keccak256 hash of the message body.
The message is wrapped up in a structure called a VAA, which combines the message with the Guardian signatures to form a proof.
VAAs are uniquely indexed by the (`emitter_chain`, `emitter_address`, `sequence`) tuple. To obtain a VAA, one can query the [Wormholescan API](https://docs.wormholescan.io/){target=\_blank} with this information.
The `sequence` field depends on the final ordering of blocks on the emitter chain. When a lower consistency level is chosen (i.e., not waiting for finality), there is a chance that chain reorganizations could lead to multiple, different VAAs appearing for what looks like the “same” message on the user side.
The tuple (`emitter_chain`, `emitter_address`, `sequence`) can only be considered unique if the chain does not undergo a reorg and the block containing the message has effectively reached finality. However, there is always a small chance of an extended reorg that could invalidate or alter a previously emitted sequence number.
## VAA Format
The basic VAA consists of header and body components described as follows:
- **Header** - holds metadata about the current VAA, the Guardian set that is currently active, and the list of signatures gathered so far
- `version` ++"byte"++ - the VAA Version
- `guardian_set_index` ++"u32"++ - indicates which Guardian set is signing
- `len_signatures` ++"u8"++ - the number of signatures stored
- `signatures` ++"[]signature"++ - the collection of Guardian signatures
Where each `signature` is:
- `index` ++"u8"++ - the index of this Guardian in the Guardian set
- `signature` ++"[65]byte"++ - the ECDSA signature
- **Body** - _deterministically_ derived from an on-chain message. Any two Guardians processing the same message must derive the same resulting body to maintain a one-to-one relationship between VAAs and messages to avoid double-processing messages
- `timestamp` ++"u32"++ - the timestamp of the block this message was published in
- `nonce` ++"u32"++
- `emitter_chain` ++"u16"++ - the id of the chain that emitted the message
- `emitter_address` ++"[32]byte"++ - the contract address (Wormhole formatted) that called the Core Contract
- `sequence` ++"u64"++ - the auto-incrementing integer that represents the number of messages published by this emitter
- `consistency_level` ++"u8"++ - the consistency level (finality) required by this emitter
- `payload` ++"[]byte"++ - arbitrary bytes containing the data to be acted on
The deterministic nature of the body is only strictly true once the chain's state is finalized. If a reorg occurs, and a transaction that previously appeared in block X is replaced by block Y, Guardians observing different forks may generate different VAAs for what the emitter contract believes is the same message. This scenario is less likely once a block is sufficiently buried, but it can still happen if you choose a faster (less finalized) consistency level
The body contains relevant information for entities, such as contracts or other systems, that process or utilize VAAs. When a function like `parseAndVerifyVAA` is called, the body is returned, allowing verification of the `emitterAddress` to determine if the VAA originated from a trusted contract.
Because VAAs have no destination, they are effectively multicast. Any Core Contract on any chain in the network will verify VAAs as authentic. If a VAA has a specific destination, relayers are responsible for appropriately completing that delivery.
## Consistency and Finality
The consistency level determines whether Guardians wait for a chain's final commitment state or issue a VAA sooner under less-final conditions. This choice is especially relevant for blockchains without instant finality, where the risk of reorganization remains until a block is deeply confirmed.
Guardian watchers are specialized processes that monitor each blockchain in real-time. They enforce the selected consistency level by deciding whether enough commitment has been reached before signing and emitting a VAA. Some chains allow only one commitment level (effectively final), while others let integrators pick between near-final or fully finalized states. Choosing a faster option speeds up VAA production but increases reorg risk. A more conservative option takes longer but reduces the likelihood of rollback.
## Signatures
The body of the VAA is hashed twice with `keccak256` to produce the signed digest message.
```js
// hash the bytes of the body twice
digest = keccak256(keccak256(body))
// sign the result
signature = ecdsa_sign(digest, key)
```
!!!tip "Hash vs. double hash"
Different implementations of the ECDSA signature validation may apply a keccak256 hash to the message passed, so care must be taken to pass the correct arguments.
For example, the [Solana secp256k1 program](https://docs.solanalabs.com/runtime/programs#secp256k1-program){target=\_blank} will hash the message passed. In this case, the argument for the message should be a single hash of the body, not the twice-hashed body.
## Payload Types
Different applications built on Wormhole may specify a format for the payloads attached to a VAA. This payload provides information on the target chain and contract so it can take action (e.g., minting tokens to a receiver address).
### Token Transfer
Many bridges use a lockup/mint and burn/unlock mechanism to transfer tokens between chains. Wormhole's generic message-passing protocol handles the routing of lock and burn events across chains to ensure Wormhole's Token Bridge is chain-agnostic and can be rapidly integrated into any network with a Wormhole contract.
Transferring tokens from the sending chain to the destination chain requires the following steps:
1. Lock the token on the sending chain
2. The sending chain emits a message as proof the token lockup is complete
3. The destination chain receives the message confirming the lockup event on the sending chain
4. The token is minted on the destination chain
The message the sending chain emits to verify the lockup is referred to as a transfer message and has the following structure:
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `1` for a token transfer
- `amount` ++"u256"++ - amount of tokens being transferred
- `token_address` ++"u8[32]"++ - address on the source chain
- `token_chain` ++"u16"++ - numeric ID for the source chain
- `to` ++"u8[32]"++ - address on the destination chain
- `to_chain` ++"u16"++ - numeric ID for the destination chain
- `fee` ++"u256"++ - portion of amount paid to a relayer
This structure contains everything the destination chain needs to learn about a lockup event. Once the destination chain receives this payload, it can mint the corresponding asset.
Note that the destination chain is agnostic regarding how the tokens on the sending side were locked. They could have been burned by a mint or locked in a custody account. The protocol relays the event once enough Guardians have attested to its existence.
### Attestation
While the destination chain can trust the message from the sending chain to inform it of token lockup events, it has no way of verifying the correct token is locked up. To solve this, the Token Bridge supports token attestation.
To create a token attestation, the sending chain emits a message containing metadata about a token, which the destination chain may use to preserve the name, symbol, and decimal precision of a token address.
The message format for token attestation is as follows:
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `2` for an attestation
- `token_address` ++"[32]byte"++ - address of the originating token contract
- `token_chain` ++"u16"++ - chain ID of the originating token
- `decimals` ++"u8"++ - number of decimals this token should have
- `symbol` ++"[32]byte"++ - short name of asset
- `name` ++"[32]byte"++ - full name of asset
#### Attestation Tips
Be aware of the following considerations when working with attestations:
- Attestations use a fixed-length byte array to encode UTF8 token name and symbol data. Because the byte array is fixed length, the data contained may truncate multibyte Unicode characters
- When sending an attestation VAA, it is recommended to send the longest UTF8 prefix that doesn't truncate a character and then right-pad it with zero bytes
- When parsing an attestation VAA, it is recommended to trim all trailing zero bytes and convert the remainder to UTF-8 via any lossy algorithm
- Be mindful that different on-chain systems may have different VAA parsers, resulting in different names/symbols on different chains if the string is long or contains invalid UTF8
- Without knowing a token's decimal precision, the destination chain cannot correctly mint the number of tokens when processing a transfer. For this reason, the Token Bridge requires an attestation for each token transfer
### Token Transfer with Message
The Token Transfer with Message data structure is identical to the token-only data structure, except for the following:
- **`fee` field** - replaced with the `from_address` field
- **`payload` field** - is added containing arbitrary bytes. A dApp may include additional data in this arbitrary byte field to inform some application-specific behavior
This VAA type was previously known as Contract Controlled Transfer and is also sometimes referred to as a `payload3` message. The Token Transfer with Message data sructure is as follows:
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `3` for a token transfer with message
- `amount` ++"u256"++ - amount of tokens being transferred
- `token_address` ++"u8[32]"++ - address on the source chain
- `token_chain` ++"u16"++ - numeric ID for the source chain
- `to` ++"u8[32]"++ - address on the destination chain
- `to_chain` ++"u16"++ - numeric ID for the destination chain
- `from_address` ++"u8[32]"++ - address that called the Token Bridge on the source chain
- `payload` ++"[]byte"++ - message, arbitrary bytes, app-specific
### Governance
Governance VAAs don't have a `payload_id` field like the preceding formats. Instead, they trigger an action in the deployed contracts (for example, an upgrade).
#### Action Structure
Governance messages contain pre-defined actions, which can target the various Wormhole modules currently deployed on-chain. The structure includes the following fields:
- `module` ++"u8[32]"++ - contains a right-aligned module identifier
- `action` ++"u8"++ - predefined governance action to execute
- `chain` ++"u16"++ - chain the action is targeting. This should be set to `0` for all chains
- `args` ++"any"++ - arguments to the action
Below is an example message containing a governance action triggering a code upgrade to the Solana Core Contract. The module field here is a right-aligned encoding of the ASCII Core, represented as a 32-byte hex string.
```js
module: 0x0000000000000000000000000000000000000000000000000000436f7265
action: 1
chain: 1
new_contract: 0x348567293758957162374959376192374884562522281937446234828323
```
#### Actions
The meaning of each numeric action is pre-defined and documented in the Wormhole design documents. For each application, the relevant definitions can be found via these links:
- [Core governance actions](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0002_governance_messaging.md){target=\_blank}
- [Token Bridge governance actions](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0003_token_bridge.md){target=\_blank}
## Lifetime of a Message
Anyone can submit a VAA to the target chain. Guardians typically don't perform this step to avoid transaction fees. Instead, applications built on top of Wormhole can acquire a VAA via the Guardian RPC and submit it in a separate flow.
With the concepts now defined, it is possible to illustrate a full flow for message passing between two chains. The following stages demonstrate each step of processing that the Wormhole network performs to route a message.
1. **A message is emitted by a contract running on Chain A** - any contract can emit messages, and the Guardians are programmed to observe all chains for these events. Here, the Guardians are represented as a single entity to simplify the graphics, but the observation of the message must be performed individually by each of the 19 Guardians
2. **Signatures are aggregated** - Guardians independently observe and sign the message. Once enough Guardians have signed the message, the collection of signatures is combined with the message and metadata to produce a VAA
3. **VAA submitted to target chain** - the VAA acts as proof that the Guardians have collectively attested the existence of the message payload. The VAA is submitted (or relayed) to the target chain to be processed by a receiving contract and complete the final step
## Next Steps
- :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/learn/infrastructure/guardians/)
- :octicons-tools-16:{ .lg .middle } **Wormhole Relayer**
---
Explore this guide to using Wormhole-deployed relayers to send and receive messages using VAAs.
[:custom-arrow: Build with Wormhole Relayer](/docs/build/core-messaging/wormhole-relayers/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/introduction/
--- BEGIN CONTENT ---
---
title: Introduction to Wormhole
description: Wormhole is a protocol for seamless communication between blockchains, enabling cross-chain applications and integrations.
categories: Basics
---
# 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/learn/infrastructure/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 (xDapps)
- **Asset transfers** - facilitate the movement of tokens and NFTs across supported chains with ease, powered by protocols built on Wormhole like [Portal](https://portalbridge.com/){target=\_blank}
- **Developer tools** - leverage [Wormhole’s SDKs](/docs/build/toolkit/typescript-sdk/){target=\_blank}, [APIs](/docs/build/toolkit/#wormhole-api-docs){target=\_blank}, [Wormhole Scan](https://wormholescan.io/){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/build/transfers/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-is-now-live-for-w-token-holders){target=\_blank}** - NFT collections on different networks can use Wormhole to communicate votes cast on their respective chains to a designated "voting" chain for combined proposals
- **Cross-chain game** - games can be developed on a performant network like Solana, with rewards issued as NFTs on another network, such as Ethereum
## Explore
Discover more about the Wormhole ecosystem, components, and protocols:
- **[Architecture](/docs/learn/infrastructure/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
- **[xDapp Book Projects](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects){target=\_blank}** - run and learn from example programs
!!! 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 Blockchains
Wormhole supports a growing number of blockchains.
### EVM
| Ethereum | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Acala | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Arbitrum | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Avalanche | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Base | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Berachain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Blast | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| BNB Smart Chain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Celo | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Fantom | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Gnosis | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| HyperEVM | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs |
| Ink | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Kaia | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Karura | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs |
| Linea | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Mantle | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Mezo | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Monad | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Moonbeam | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Neon | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Oasis | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Optimism | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Polygon | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Scroll | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Seievm | EVM | :x: | :white_check_mark: | |
| SNAXchain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Unichain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| World Chain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| X Layer | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### SVM
| Solana | SVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Pythnet | SVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### AVM
| Algorand | AVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### CosmWasm
| Injective | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Neutron | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Osmosis | CosmWasm | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Sei | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Terra | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Terra 2.0 | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| XPLA | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### Move VM
| Aptos | Move VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### NEAR VM
| NEAR | NEAR VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### Sui Move VM
| Sui | Sui Move VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/learn/security/
--- BEGIN CONTENT ---
---
title: Security
description: Explore Wormhole's security features, including the Guardian network, governance, monitoring, open-source development, and bug bounty programs.
categories: Basics
---
# Security
## Core Security Assumptions
At its core, Wormhole is secured by a network of [Guardian](/docs/learn/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/learn/glossary/#vaa){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
- [Relayers](/docs/learn/glossary/#relayer){target=\_blank} are considered untrusted in the Wormhole ecosystem
In summary:
- **Core integrators aren't exposed to risk from chains and contracts they don't 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 Guardian set currently comprises 19 validators, this is a limitation of current blockchain technology.
### 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 token bridge 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
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.
Guardians are not just running Wormhole validators; they're running validators for every blockchain inside of Wormhole as well, which allows them to perform monitoring holistically across decentralized computing rather than just at a few single points.
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.
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/learn/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}.
## Learn More
The [SECURITY.md](https://github.com/wormhole-foundation/wormhole/blob/main/SECURITY.md){target=\blank} from the official repository has the latest security policies and updates.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/core-messaging/core-contracts/
--- BEGIN CONTENT ---
---
title: Get Started with Core Contracts
description: This guide walks through the key methods of the Core Contracts, providing you with the knowledge needed to integrate them into your cross-chain contracts
categories: Basics
---
# Get Started with Core Contracts
## Introduction
Wormhole's Core Contracts, deployed on each supported blockchain network, enable the fundamental operations of sending and receiving cross-chain messages.
While the implementation details of the Core Contracts varies by network, the core functionality remains consistent across chains. Each version of the Core Contract facilitates secure and reliable cross-chain communication, ensuring that developers can effectively publish and verify messages.
This guide will walk you through the variations and key methods of the Core Contracts, providing you with the knowledge needed to integrate them into your cross-chain contracts. To learn more about Core Contracts' features and how it works, please refer to the [Core Contracts](/docs/learn/infrastructure/core-contracts/){target=\_blank} page in the Learn section.
## Prerequisites
To interact with the Wormhole Core Contract, you'll need the following:
- The [address of the Core Contract](/docs/build/reference/contract-addresses/#core-contracts){target=\_blank} on the chains you're deploying your contract on
- The [Wormhole chain ID](/docs/build/reference/chain-ids/){target=\_blank} of the chains you're deploying your contract on
- The [Wormhole Finality](/docs/build/reference/consistency-levels/){target=\_blank} (consistency) levels (required finality) for the chains you're deploying your contract on
## How to Interact with Core Contracts
Before writing your own contracts, it's essential to understand the key functions and events of the Wormhole Core Contracts. The primary functionality revolves around:
- **Sending messages** - submitting messages to the Wormhole network for cross-chain communication
- **Receiving and verifying messages** - validating messages received from other chains via the Wormhole network
While the implementation details of the Core Contracts vary by network, the core functionality remains consistent across chains.
### Sending Messages
To send a message, regardless of the environment or chain, the Core Contract is invoked with a message argument from an [emitter](/docs/learn/glossary/#emitter){target=\_blank}. This emitter might be your contract or an existing application such as the [Token Bridge](/docs/learn/transfers/token-bridge/#token-bridge){target=\_blank}.
=== "EVM"
The `IWormhole.sol` interface provides the `publishMessage` function, which can be used to publish a message directly to the Core Contract:
```solidity
function publishMessage(
uint32 nonce,
bytes memory payload,
uint8 consistencyLevel
) external payable returns (uint64 sequence);
```
??? interface "Parameters"
`nonce` ++"uint32"++
A free integer field that can be used however you like. Note that changing the `nonce` will result in a different digest.
---
`payload` ++"bytes memory"++
The content of the emitted message. Due to the constraints of individual blockchains, it may be capped to a certain maximum length.
---
`consistencyLevel` ++"uint8"++
A value that defines the required level of finality that must be reached before the Guardians will observe and attest to emitted events.
??? interface "Returns"
`sequence` ++"uint64"++
A unique number that increments for every message for a given emitter (and implicitly chain). This, combined with the emitter address and emitter chain ID, allows the VAA for this message to be queried from the [Wormholescan API](https://docs.wormholescan.io/){target=\_blank}.
??? interface "Example"
```solidity
IWormhole wormhole = IWormhole(wormholeAddr);
// Get the fee for publishing a message
uint256 wormholeFee = wormhole.messageFee();
// Check fee and send parameters
// Create the HelloWorldMessage struct
HelloWorldMessage memory parsedMessage = HelloWorldMessage({
payloadID: uint8(1),
message: helloWorldMessage
});
// Encode the HelloWorldMessage struct into bytes
bytes memory encodedMessage = encodeMessage(parsedMessage);
// Send the HelloWorld message by calling publishMessage on the
// wormhole core contract and paying the Wormhole protocol fee.
messageSequence = wormhole.publishMessage{value: wormholeFee}(
0, // batchID
encodedMessage,
wormholeFinality()
);
```
View the complete Hello World example in the [Wormhole Scaffolding](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/evm/src/01_hello_world){target=\_blank} repository on GitHub.
=== "Solana"
The `wormhole_anchor_sdk::wormhole` module and the Wormhole program account can be used to pass a message directly to the Core Contract via the `wormhole::post_message` function:
```rs
pub fn post_message<'info>(
ctx: CpiContext<'_, '_, '_, 'info, PostMessage<'info>>,
batch_id: u32,
payload: Vec,
finality: Finality
) -> Result<()>
```
??? interface "Parameters"
`ctx` ++"CpiContext<'_, '_, '_, 'info, PostMessage<'info>>"++
Provides the necessary context for executing the function, including the accounts and program information required for the Cross-Program Invocation (CPI).
??? child "Type `pub struct CpiContext<'a, 'b, 'c, 'info, T>`"
```rs
pub struct CpiContext<'a, 'b, 'c, 'info, T>
where
T: ToAccountMetas + ToAccountInfos<'info>,
{
pub accounts: T,
pub remaining_accounts: Vec>,
pub program: AccountInfo<'info>,
pub signer_seeds: &'a [&'b [&'c [u8]]],
}
```
For more information, please refer to the [`wormhole_anchor_sdk` Rust docs](https://docs.rs/anchor-lang/0.29.0/anchor_lang/context/struct.CpiContext.html){target=\_blank}.
??? child "Type `PostMessage<'info>`"
```rs
pub struct PostMessage<'info> {
pub config: AccountInfo<'info>,
pub message: AccountInfo<'info>,
pub emitter: AccountInfo<'info>,
pub sequence: AccountInfo<'info>,
pub payer: AccountInfo<'info>,
pub fee_collector: AccountInfo<'info>,
pub clock: AccountInfo<'info>,
pub rent: AccountInfo<'info>,
pub system_program: AccountInfo<'info>,
}
```
For more information, please refer to the [`wormhole_anchor_sdk` Rust docs](https://docs.rs/wormhole-anchor-sdk/latest/wormhole_anchor_sdk/wormhole/instructions/struct.PostMessage.html){target=\_blank}.
---
`batch_id` ++"u32"++
An identifier for the message batch.
---
`payload` ++"Vec"++
The data being sent in the message. This is a variable-length byte array that contains the actual content or information being transmitted. To learn about the different types of payloads, check out the [VAAs](/docs/learn/infrastructure/vaas#payload-types){target=\_blank} page.
---
`finality` ++"Finality"++
Specifies the level of finality or confirmation required for the message.
??? child "Type `Finality`"
```rs
pub enum Finality {
Confirmed,
Finalized,
}
```
??? interface "Returns"
++"Result<()>"++
The result of the function’s execution. If the function completes successfully, it returns `Ok(())`, otherwise it returns `Err(E)`, indicating that an error occurred along with the details about the error
??? interface "Example"
```rust
let fee = ctx.accounts.wormhole_bridge.fee();
// ... Check fee and send parameters
let config = &ctx.accounts.config
let payload: Vec = HelloWorldMessage::Hello { message }.try_to_vec()?;
// Invoke `wormhole::post_message`.
wormhole::post_message(
CpiContext::new_with_signer(
ctx.accounts.wormhole_program.to_account_info(),
wormhole::PostMessage {
// ... Set fields
},
&[
// ... Set seeds
],
),
config.batch_id,
payload,
config.finality.into(),
)?;
```
View the complete Hello World example in the [Wormhole Scaffolding](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/solana/programs/01_hello_world){target=\_blank} repository on GitHub.
Once the message is emitted from the Core Contract, the [Guardian Network](/docs/learn/infrastructure/guardians/){target=\_blank} will observe the message and sign the digest of an Attestation [VAA](/docs/learn/infrastructure/vaas/){target=\_blank}. On EVM chains, the body of the VAA is hashed twice with keccak256 to produce the signed digest message. On Solana, the [Solana secp256k1 program](https://docs.solana.com/developing/runtime-facilities/programs#secp256k1-program){target=\_blank} will hash the message passed. In this case, the argument for the message should be a single hash of the body, not the twice-hashed body.
VAAs are [multicast](/docs/learn/infrastructure/core-contracts/#multicast){target=\_blank} by default. This means there is no default target chain for a given message. The application developer decides on the format of the message and its treatment upon receipt.
### Receiving Messages
The way a message is received and handled depends on the environment.
=== "EVM"
On EVM chains, the message passed is the raw VAA encoded as binary. The `IWormhole.sol` interface provides the `parseAndVerifyVM` function, which can be used to parse and verify the received message.
```solidity
function parseAndVerifyVM(
bytes calldata encodedVM
) external view returns (VM memory vm, bool valid, string memory reason);
```
??? interface "Parameters"
`encodedVM` ++"bytes calldata"++
The encoded message as a Verified Action Approval (VAA), which contains all necessary information for verification and processing.
??? interface "Returns"
`vm` ++"VM memory"++
The valid parsed VAA, which will include the original `emitterAddress`, `sequenceNumber`, and `consistencyLevel`, among other fields outlined on the [VAAs](/docs/learn/infrastructure/vaas/) page.
??? child "Struct `VM`"
```solidity
struct VM {
uint8 version;
uint32 timestamp;
uint32 nonce;
uint16 emitterChainId;
bytes32 emitterAddress;
uint64 sequence;
uint8 consistencyLevel;
bytes payload;
uint32 guardianSetIndex;
Signature[] signatures;
bytes32 hash;
}
```
For more information, refer to the [`IWormhole.sol` interface](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/interfaces/IWormhole.sol){target=\_blank}.
---
`valid` ++"bool"++
A boolean indicating whether the VAA is valid or not.
---
`reason` ++"string"++
If the VAA is not valid, a reason will be provided
??? interface "Example"
```solidity
function receiveMessage(bytes memory encodedMessage) public {
// Call the Wormhole core contract to parse and verify the encodedMessage
(
IWormhole.VM memory wormholeMessage,
bool valid,
string memory reason
) = wormhole().parseAndVerifyVM(encodedMessage);
// Perform safety checks here
// Decode the message payload into the HelloWorldMessage struct
HelloWorldMessage memory parsedMessage = decodeMessage(
wormholeMessage.payload
);
// Your custom application logic here
}
```
View the complete Hello World example in the [Wormhole Scaffolding](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/evm/src/01_hello_world){target=\_blank} repository on GitHub.
=== "Solana"
On Solana, the VAA is first posted and verified by the Core Contract, after which it can be read by the receiving contract and action taken.
Retrieve the raw message data:
```rs
let posted_message = &ctx.accounts.posted;
posted_message.data()
```
??? interface "Example"
```rust
pub fn receive_message(ctx: Context, vaa_hash: [u8; 32]) -> Result<()> {
let posted_message = &ctx.accounts.posted
if let HelloWorldMessage::Hello { message } = posted_message.data() {
// Check message
// Your custom application logic here
Ok(())
} else {
Err(HelloWorldError::InvalidMessage.into())
}
}
```
View the complete Hello World example in the [Wormhole Scaffolding](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/solana/programs/01_hello_world){target=\_blank} repository on GitHub.
#### Validating the Emitter
When processing cross-chain messages, it's critical to ensure that the message originates from a trusted sender (emitter). This can be done by verifying the emitter address and chain ID in the parsed VAA.
Typically, contracts should provide a method to register trusted emitters and check incoming messages against this list before processing them. For example, the following check ensures that the emitter is registered and authorized:
```solidity
require(isRegisteredSender(emitterChainId, emitterAddress), "Invalid emitter");
```
This check can be applied after the VAA is parsed, ensuring only authorized senders can interact with the receiving contract. Trusted emitters can be registered using a method like `setRegisteredSender` during contract deployment or initialization.
```typescript
const tx = await receiverContract.setRegisteredSender(
sourceChain.chainId,
ethers.zeroPadValue(senderAddress as BytesLike, 32)
);
await tx.wait();
```
#### Additional Checks
In addition to environment-specific checks that should be performed, a contract should take care to check other [fields in the body](/docs/learn/infrastructure/vaas/){target=\_blank}, including:
- **Sequence** - is this the expected sequence number? How should out-of-order deliveries be handled?
- **Consistency level** - for the chain this message came from, is the [Wormhole Finality](/docs/build/reference/consistency-levels/){target=\_blank} level enough to guarantee the transaction won't be reverted after taking some action?
The VAA digest is separate from the VAA body but is also relevant. It can be used for replay protection by checking if the digest has already been seen. Since the payload itself is application-specific, there may be other elements to check to ensure safety.
## Source Code References
For a deeper understanding of the Core Contract implementation for a specific blockchain environment and to review the actual source code, please refer to the following links:
- [Algorand Core Contract source code](https://github.com/wormhole-foundation/wormhole/blob/main/algorand/wormhole_core.py){target=\_blank}
- [Aptos Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/aptos/wormhole){target=\_blank}
- [EVM Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/ethereum/contracts){target=\_blank} ([`IWormhole.sol` interface](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/interfaces/IWormhole.sol){target=\_blank})
- [NEAR Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/near/contracts/wormhole){target=\_blank}
- [Solana Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/solana/bridge/program){target=\_blank}
- [Sui Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/sui/wormhole){target=\_blank}
- [Terra Core Contract source code](https://github.com/wormhole-foundation/wormhole/tree/main/terra/contracts/wormhole){target=\_blank}
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/core-messaging/wormhole-relayers/
--- BEGIN CONTENT ---
---
title: Wormhole-Deployed Relayers
description: Learn about the Wormhole-deployed relayer configuration for seamless cross-chain messaging between contracts on different EVM blockchains without off-chain deployments.
categories: Relayers, Basics
---
# Wormhole Relayer
## Introduction
The Wormhole-deployed relayers provide a mechanism for contracts on one blockchain to send messages to contracts on another without requiring off-chain infrastructure. Through the Wormhole relayer module, developers can use an untrusted delivery provider to transport VAAs, saving the need to build and maintain custom relaying solutions. The option to [run a custom relayer](/docs/infrastructure/relayers/run-relayer/) is available for more complex needs.
This section covers the components and interfaces involved in using the Wormhole relayer module, such as message sending and receiving, delivery guarantees, and considerations for building reliable and efficient cross-chain applications. Additionally, you'll find details on how to handle specific implementation scenarios and track message delivery progress using the Wormhole CLI tool.
## Get Started with the Wormhole Relayer
Before getting started, it's important to note that the Wormhole-deployed relayer configuration is currently **limited to EVM environments**. The complete list of EVM environment blockchains is on the [Supported Networks](/docs/build/start-building/supported-networks/) page.
To interact with the Wormhole relayer, you'll need to create contracts on the source and target chains to handle the sending and receiving of messages. No off-chain logic needs to be implemented to take advantage of Wormhole-powered relaying.
The components outlined in blue must be implemented.
### Wormhole Relayer Interfaces
There are three relevant interfaces to discuss when utilizing the Wormhole relayer module:
- [**`IWormholeRelayer`**](https://github.com/wormhole-foundation/wormhole/blob/main/relayer/ethereum/contracts/interfaces/relayer/IWormholeRelayer.sol){target=\_blank} - the primary interface by which you send and receive messages. It allows you to request the sending of messages and VAAs
- [**`IWormholeReceiver`**](https://github.com/wormhole-foundation/wormhole/blob/main/relayer/ethereum/contracts/interfaces/relayer/IWormholeReceiver.sol){target=\_blank} - this is the interface you are responsible for implementing. It allows the selected delivery provider to deliver messages/VAAs to your contract
- [**`IDeliveryProvider`**](https://github.com/wormhole-foundation/wormhole/blob/main/relayer/ethereum/contracts/interfaces/relayer/IDeliveryProvider.sol){target=\_blank} - this interface represents the delivery pricing information for a given relayer network. Each delivery provider implements this on every blockchain they support delivering from
## Interact with the Wormhole Relayer
To start interacting with the Wormhole relayer in your contracts, you'll need to import the `IWormholeRelayer` interface and set up a reference using the contract address to the Wormhole-deployed relayer on the supported network of your choice.
To easily integrate with the Wormhole relayer interface, you can use the [Wormhole Solidity SDK](https://github.com/wormhole-foundation/wormhole-solidity-sdk){target=\_blank}.
To retrieve the contract address of the Wormhole relayer, refer to the Wormhole relayer section on the [Contract Addresses](/docs/build/reference/contract-addresses/#wormhole-relayer) reference page.
Your initial set up should resemble the following:
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;
import "wormhole-solidity-sdk/interfaces/IWormholeRelayer.sol";
contract Example {
IWormholeRelayer public wormholeRelayer;
constructor(address _wormholeRelayer) {
wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
}
}
```
The code provided sets up the basic structure for your contract to interact with the Wormhole relayer using the address supplied to the constructor. By leveraging methods from the `IWormholeRelayer` interface, you can implement message sending and receiving functionalities. The following sections will detail the specific methods you need to use for these tasks.
### Send a Message
To send a message to a contract on another EVM chain, you can call the `sendPayloadToEvm` method provided by the `IWormholeRelayer` interface.
```solidity
function sendPayloadToEvm(
// Chain ID in Wormhole format
uint16 targetChain,
// Contract Address on target chain we're sending a message to
address targetAddress,
// The payload, encoded as bytes
bytes memory payload,
// How much value to attach to the delivery transaction
uint256 receiverValue,
// The gas limit to set on the delivery transaction
uint256 gasLimit
) external payable returns (
// Unique, incrementing ID, used to identify a message
uint64 sequence
);
```
!!! tip
To reduce transaction confirmation time, you can lower the consistency level using the [`sendToEvm`](https://github.com/wormhole-foundation/wormhole/blob/v{{repositories.wormhole.version}}/sdk/js/src/relayer/relayer/send.ts#L33){target=\_blank} method.
The `sendPayloadToEvm` method is marked `payable` to receive fee payment for the transaction. The value to attach to the invocation is determined by calling the `quoteEVMDeliveryPrice`, which provides an estimate of the cost of gas on the target chain.
```solidity
function quoteEVMDeliveryPrice(
// Chain ID in Wormhole format
uint16 targetChain,
// How much value to attach to delivery transaction
uint256 receiverValue,
// The gas limit to attach to the delivery transaction
uint256 gasLimit
) external view returns (
// How much value to attach to the send call
uint256 nativePriceQuote,
uint256 targetChainRefundPerGasUnused
);
```
This method should be called before sending a message, and the value returned for `nativePriceQuote` should be attached to the call to send the payload to cover the transaction's cost on the target chain.
In total, sending a message across EVM chains can be as simple as getting a fee quote and sending the message as follows:
```solidity
// Get a quote for the cost of gas for delivery
(cost, ) = wormholeRelayer.quoteEVMDeliveryPrice(
targetChain,
valueToSend,
GAS_LIMIT
);
// Send the message
wormholeRelayer.sendPayloadToEvm{value: cost}(
targetChain,
targetAddress,
abi.encode(payload),
valueToSend,
GAS_LIMIT
);
```
### Receive a Message
To receive a message using a Wormhole relayer, the target contract must implement the [`IWormholeReceiver`](https://github.com/wormhole-foundation/wormhole-relayer-solidity-sdk/blob/main/src/interfaces/IWormholeReceiver.sol){target=\_blank} interface, as shown in the [previous section](#interact-with-the-wormhole-relayer).
```solidity
function receiveWormholeMessages(
bytes memory payload, // Message passed by source contract
bytes[] memory additionalVaas, // Any additional VAAs that are needed (Note: these are unverified)
bytes32 sourceAddress, // The address of the source contract
uint16 sourceChain, // The Wormhole chain ID
bytes32 deliveryHash // A hash of contents, useful for replay protection
) external payable;
```
The logic inside the function body may be whatever business logic is required to take action on the specific payload.
## Delivery Guarantees
The Wormhole relayer protocol is intended to create a service interface whereby mutually distrustful integrators and delivery providers can work together to provide a seamless dApp experience. You don't trust the delivery providers with your data, and the delivery providers don't trust your smart contract. The primary agreement between integrators and delivery providers is that when a delivery is requested, the provider will attempt to deliver the VAA within the provider's stated delivery timeframe.
This creates a marketplace whereby providers can set different price levels and service guarantees. Delivery providers effectively accept the slippage risk premium of delivering your VAAs in exchange for a set fee rate. Thus, the providers agree to deliver your messages even if they do so at a loss.
Delivery providers should set their prices such that they turn a profit on average but not necessarily on every single transfer. Thus, some providers may choose to set higher rates for tighter guarantees or lower rates for less stringent guarantees.
## Delivery Statuses
All deliveries result in one of the following four outcomes before the delivery provider's delivery timeframe. When they occur, these outcomes are emitted as EVM events from the Wormhole relayer contract. The four possible outcomes are:
- (0) Delivery Success
- (1) Receiver Failure
- (2) Forward Request Success
- (3) Forward Request Failure
A receiver failure is a scenario in which the selected provider attempted the delivery but it could not be completely successfully. The three possible causes for a delivery failure are:
- The target contract does not implement the `IWormholeReceiver` interface
- The target contract threw an exception or reverted during the execution of `receiveWormholeMessages`
- The target contract exceeded the specified `gasLimit` while executing `receiveWormholeMessages`
All three of these scenarios can be avoided with correct design by the integrator, and thus, it is up to the integrator to resolve them. Any other scenario that causes a delivery to not be performed should be considered an outage by some component of the system, including potentially the blockchains themselves.
`Forward Request Success` and `Forward Failure` represent when the delivery succeeded and the user requested a forward during the delivery. If the user has enough funds left over as a refund to complete the forward, the forward will be executed, and the status will be `Forward Request Success`. Otherwise, it will be `Forward Request Failure`.
## Other Considerations
Some implementation details should be considered during development to ensure safety and a pleasant UX. Ensure that your engineering efforts have appropriately considered each of the following areas:
- Receiving a message from a relayer
- Checking for expected emitter
- Calling `parseAndVerify` on any additional VAAs
- Replay protection
- Message ordering (no guarantees on order of messages delivered)
- Forwarding and call chaining
- Refunding overpayment of `gasLimit`
- Refunding overpayment of value sent
## Track the Progress of Messages with the Wormhole CLI
While no off-chain programs are required, a developer may want to track the progress of messages in flight. To track the progress of messages in flight, use the [Wormhole CLI](/docs/build/toolkit/cli/) tool's `status` subcommand. As an example, you can use the following commands to track the status of a transfer by providing the environment, origin network, and transaction hash to the `worm status` command:
=== "Mainnet"
```bash
worm status mainnet ethereum INSERT_TRANSACTION_HASH
```
=== "Testnet"
```bash
worm status testnet ethereum INSERT_TRANSACTION_HASH
```
See the [Wormhole CLI tool docs](/docs/build/toolkit/cli/) for installation and usage.
## Step-by-Step Tutorial
For detailed, step-by-step guidance on creating cross-chain contracts that interact with the Wormhole relayer, refer to the [Create Cross-Chain Contracts](/docs/tutorials/solidity-sdk/cross-chain-contracts/) tutorial.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/start-building/products/
--- BEGIN CONTENT ---
---
title: Compare Wormhole's Cross-Chain Solutions
description: Compare Wormhole’s cross-chain solutions for bridging, native transfers, data queries, and governance to enable seamless blockchain interoperability.
categories: Transfer, Basics
---
# Products
Wormhole provides a comprehensive suite of cross-chain solutions, enabling seamless asset transfers, data retrieval, and governance across blockchain ecosystems.
Wormhole provides multiple options for asset transfers: Connect for a plug-and-play bridging UI, Native Token Transfers (NTT) for moving native assets without wrapped representations, and Token Bridge for a secure lock-and-mint mechanism.
Beyond transfers, Wormhole extends interoperability with tools for cross-chain data access, decentralized governance, and an intent-based protocol through Wormhole Settlement.
## Transfer Products
Wormhole offers different solutions for cross-chain asset transfer, each designed for various use cases and integration requirements.
- [**Connect**](/docs/build/transfers/connect/overview/){target=\_blank} - a pre-built bridging UI for cross-chain token transfers, requiring minimal setup. Best for projects seeking an easy-to-integrate UI for bridging without modifying contracts
- [**Native Token Transfers (NTT)**](/docs/learn/transfers/native-token-transfers/overview/){target=\_blank} - a mechanism to transfer native tokens cross-chain seamlessly without conversion to wrapped asset. Best for projects that require maintaining token fungibility and native chain functionality across multiple networks
- [**Token Bridge**](/docs/learn/transfers/token-bridge/){target=\_blank} - a bridging solution that uses a lock and mint mechanism. Best for projects that need cross-chain liquidity using wrapped assets and the ability to send messages
- [**Settlement**](/docs/learn/messaging/wormhole-settlement/overview/){target=\_blank} - intent-based protocols enabling fast multichain transfers, optimized liquidity flows, and interoperability without relying on traditional bridging methods
Beyond asset transfers, Wormhole provides additional tools for cross-chain data and governance.
## Real-time Data
[**Queries**](/docs/build/queries/overview/){target=\_blank} is a data retrieval service to fetch on-chain data from multiple networks. Best for applications that need multichain analytics, reporting, and data aggregation.
## Multichain Governance
[**MultiGov**](/docs/learn/governance/overview/){target=\_blank} is a unified governance framework that manages multichain protocol governance through a single mechanism. Best for projects managing multichain governance and protocol updates.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/start-building/use-cases/
--- BEGIN CONTENT ---
---
title: Use Cases
description: Explore Wormhole's use cases, from cross-chain swaps to DeFi, lending, gaming, and more. See how projects integrate Wormhole solutions.
categories: Basics
---
# Wormhole Use Cases
## Cross-Chain Swaps and Liquidity Aggregation
Enable seamless swaps between chains with real-time liquidity routing.
## Memecoin Launchpads
Launch and distribute memecoins across multiple chains, enabling cross-chain fundraising and liquidity access.
🛠 **Wormhole products used:**
- [**Native Token Transfer**](/docs/build/transfers/native-token-transfers/){target=\_blank} – enables native asset transfers for seamless fundraising
- [**Messaging**](/docs/learn/infrastructure/){target=\_blank} – facilitates cross-chain token distribution and claim processes
🔗 **Used in:** Token launchpads, IDOs, and meme token ecosystems
## Cross-Chain Perpetuals
Enable leveraged perpetual trading across chains with seamless collateral and liquidity management.
🛠 **Wormhole products used:**
- [**Queries**](/docs/build/queries/overview/){target=\_blank} – fetches real-time asset prices and manages position state across chains
- [**Wormhole Settlement**](/docs/learn/transfers/settlement/overview/){target=\_blank} - for quick cross-chain token execution, providing efficient and seamless user experiences
🔗 **Used in:** Perpetual DEXs, trading platforms and cross-chain derivatives
## Gas Abstraction
Allow users to pay gas fees with any token across different networks, removing friction in multichain interactions.
🛠 **Wormhole products used:**
- [**Messaging**](/docs/learn/infrastructure/){target=\_blank} – routes gas fee payments across chains
- [**Native Token Transfer**](/docs/build/transfers/native-token-transfers/){target=\_blank} – facilitates native token conversion for gas payments
🔗 **Used in:** Wallets, dApps, and multichain user experience improvements
## Bridging Intent Library
Provide developers with a library of bridging intents and automation functions, enabling plug-and-play interoperability logic.
🛠 **Wormhole products used:**
- [**Messaging**](/docs/learn/infrastructure/){target=\_blank} – enables predefined cross-chain actions and triggers.
- [**Wormhole Settlement**](/docs/learn/transfers/settlement/overview/){target=\_blank} - provides a framework for executing user-defined bridging intents
🔗 **Used in:** Bridging protocols, DeFi automation, and smart contract libraries
## Multichain Prediction Markets
Allow users to place bets, manage positions, and receive payouts seamlessly across different networks.
🛠 **Wormhole products used:**
- [**Queries**](/docs/build/queries/overview/){target=\_blank} – fetches real-time market data, tracks collateral, and manages odds across chains
- [**Wormhole Settlement**](/docs/learn/transfers/settlement/overview/){target=\_blank} – automates token execution for efficient and seamless cross-chain prediction market interactions
🔗 **Used in:** Decentralized betting, prediction markets, and cross-chain gaming
## Cross-Chain Payment Widgets
Allow merchants and platforms to accept payments in any token, auto-converting them into a desired asset.
## Oracle Networks
Fetch and verify cross-chain data, enabling reliable, decentralized Oracle services for multichain applications.
🛠 **Wormhole products used:**
- [**Queries**](/docs/build/queries/overview/){target=\_blank} – fetches data from multiple chains and Oracle providers
- [**Messaging**](/docs/learn/infrastructure/){target=\_blank} – ensures tamper-proof data relay across networks
🔗 **Used in:** Price feeds, DeFi protocols, and smart contract automation 🏗️ **Used by:** [Pyth](https://wormhole.com/case-studies/pyth){target=\_blank}
## Cross-Chain Staking
Enable users to stake assets on one chain while earning rewards or securing networks on another.
🛠 **Wormhole products used:**
- [**Messaging**](/docs/learn/infrastructure/){target=\_blank} – moves staking rewards and governance signals across chains
- [**Native Token Transfer**](/docs/build/transfers/native-token-transfers/){target=\_blank} – transfers staked assets natively between networks
🔗 **Used in:** Liquid staking, cross-chain governance, and PoS networks 🏗️ **Used by:** [Lido](https://lido.fi/){target=\_blank}
--- END CONTENT ---
## Reference Concepts [shared: true]
The following section contains reference material for Wormhole.
It includes Wormhole chain IDs, canonical contract addresses, and finality levels for Guardians for each of the supported blockchains in the Wormhole ecosystem.
While it may not be required for all use cases, it offers a deeper technical layer for advanced development work.
---
## List of shared concept pages:
## Full content for shared concepts:
Doc-Content: https://wormhole.com/docs/build/reference/
--- BEGIN CONTENT ---
---
title: Reference
description: Find essential reference information for development, including canonical contract addresses, Wormhole chain IDs, and Wormhole finality levels for Guardians.
categories: Reference
---
# Reference
## Get Started
In this section, you'll find reference information that is essential for development. This includes Wormhole chain IDs, canonical contract addresses, and finality levels for Guardians for each of the supported blockchains in the Wormhole ecosystem.
- :octicons-list-ordered-16:{ .lg .middle } **Chain IDs**
---
Find a mapping of Wormhole chain IDs to the names and network IDs of the supported blockchains.
[:custom-arrow: View list of chain IDs](/docs/build/reference/chain-ids/)
- :material-timer-sand:{ .lg .middle } **Wormhole Finality**
---
See the levels of finality (consistency) a transaction should meet before being signed by a Guardian for each network.
[:custom-arrow: View list of finality levels](/docs/build/reference/consistency-levels/)
- :octicons-file-code-16:{ .lg .middle } **Contract Addresses**
---
Discover the contract addresses for Wormhole-deployed contracts on each of the supported blockchains.
This includes the following protocol contracts:
- Core Contract
- Token Bridge
- NFT Bridge
- Wormhole relayer
- CCTP
[:custom-arrow: View list of contract addresses](/docs/build/reference/contract-addresses/)
- :octicons-checkbox-16:{ .lg .middle } **Wormhole Formatted Addresses**
---
Learn how Wormhole formats addresses into a 32-byte hex format for cross-chain compatibility.
This includes converting addresses between their native formats and the Wormhole format across multiple blockchains.
[:custom-arrow: View details on Wormhole formatted addresses](/docs/build/reference/wormhole-formatted-addresses/)
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/reference/chain-ids/
--- BEGIN CONTENT ---
---
title: Chain IDs
description: This page documents the Wormhole-specific chain IDs for each chain and contrasts them to the more commonly referenced EVM chain IDs originating in EIP-155.
categories: Reference
---
# Chain IDs
The following table documents the chain IDs used by Wormhole and places them alongside the more commonly referenced [EVM Chain IDs](https://chainlist.org/){target=\_blank}.
!!! note
Please note, Wormhole chain IDs are different than the more commonly referenced EVM [chain IDs](https://eips.ethereum.org/EIPS/eip-155){target=\_blank}, specified in the Mainnet and Testnet ID columns.
=== "Mainnet"
| Ethereum | 2 | 1 |
| Solana | 1 | Mainnet Beta-5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d |
| Acala | 12 | 787 |
| Algorand | 8 | mainnet-v1.0 |
| Aptos | 22 | 1 |
| Arbitrum | 23 | Arbitrum One-42161 |
| Avalanche | 6 | C-Chain-43114 |
| Base | 30 | Base-8453 |
| Berachain | 39 | |
| Blast | 36 | 81457 |
| BNB Smart Chain | 4 | 56 |
| Celestia | 4004 | celestia |
| Celo | 14 | 42220 |
| Cosmos Hub | 4000 | cosmoshub-4 |
| Dymension | 4007 | dymension_1100-1 |
| Evmos | 4001 | evmos_9001-2 |
| Fantom | 10 | 250 |
| Gnosis | 25 | 100 |
| HyperEVM | 47 | |
| Injective | 19 | injective-1 |
| Ink | 46 | |
| Kaia | 13 | 8217 |
| Karura | 11 | 686 |
| Kujira | 4002 | kaiyo-1 |
| Linea | 38 | 59144 |
| Mantle | 35 | 5000 |
| Mezo | 50 | |
| Monad | 48 | |
| Moonbeam | 16 | 1284 |
| NEAR | 15 | mainnet |
| Neon | 17 | 245022934 |
| Neutron | 4003 | neutron-1 |
| Noble | 4009 | noble-1 |
| Oasis | 7 | 42262 |
| Optimism | 24 | 10 |
| Osmosis | 20 | osmosis-1 |
| Polygon | 5 | 137 |
| Provenance | 4008 | pio-mainnet-1 |
| Pythnet | 26 | |
| Scroll | 34 | 534352 |
| SEDA | 4006 | |
| Sei | 32 | pacific-1 |
| Seievm | 40 | |
| SNAXchain | 43 | 2192 |
| Stargaze | 4005 | stargaze-1 |
| Sui | 21 | 35834a8a |
| Terra | 3 | columbus-5 |
| Terra 2.0 | 18 | phoenix-1 |
| Unichain | 44 | |
| World Chain | 45 | 480 |
| X Layer | 37 | 196 |
| XPLA | 28 | dimension_37-1 |
=== "Testnet"
| Ethereum Holesky | 10006 | Holesky-17000 |
| Ethereum Sepolia | 10002 | Sepolia-11155111 |
| Solana | 1 | Devnet-EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG |
| Acala | 12 | 597 |
| Algorand | 8 | testnet-v1.0 |
| Aptos | 22 | 2 |
| Arbitrum Sepolia | 10003 | Sepolia-421614 |
| Avalanche | 6 | Fuji-43113 |
| Base Sepolia | 10004 | Base Sepolia-84532 |
| Berachain | 39 | 80084 |
| Blast | 36 | 168587773 |
| BNB Smart Chain | 4 | 97 |
| Celestia | 4004 | mocha-4 |
| Celo | 14 | Alfajores-44787 |
| Cosmos Hub | 4000 | theta-testnet-001 |
| Dymension | 4007 | |
| Evmos | 4001 | evmos_9000-4 |
| Fantom | 10 | 4002 |
| Gnosis | 25 | Chiado-10200 |
| HyperEVM | 47 | 998 |
| Injective | 19 | injective-888 |
| Ink | 46 | 763373 |
| Kaia | 13 | Kairos-1001 |
| Karura | 11 | 596 |
| Kujira | 4002 | harpoon-4 |
| Linea | 38 | 59141 |
| Mantle | 35 | Sepolia-5003 |
| Mezo | 50 | 31611 |
| Monad | 48 | 10143 |
| Moonbeam | 16 | Moonbase-Alphanet-1287 |
| NEAR | 15 | testnet |
| Neon | 17 | 245022940 |
| Neutron | 4003 | pion-1 |
| Noble | 4009 | grand-1 |
| Oasis | 7 | 42261 |
| Optimism Sepolia | 10005 | Optimism Sepolia-11155420 |
| Osmosis | 20 | osmo-test-5 |
| Polygon Amoy | 10007 | Amoy-80002 |
| Provenance | 4008 | |
| Pythnet | 26 | |
| Scroll | 34 | Sepolia-534351 |
| SEDA | 4006 | seda-1-testnet |
| Sei | 32 | atlantic-2 |
| Seievm | 40 | |
| SNAXchain | 43 | 13001 |
| Stargaze | 4005 | |
| Sui | 21 | 4c78adac |
| Terra | 3 | bombay-12 |
| Terra 2.0 | 18 | pisco-1 |
| Unichain | 44 | Unichain Sepolia-1301 |
| World Chain | 45 | 4801 |
| X Layer | 37 | 195 |
| XPLA | 28 | cube_47-5 |
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/reference/consistency-levels/
--- BEGIN CONTENT ---
---
title: Wormhole Finality | Consistency Levels
description: This page documents how long to wait for finality before signing, based on each chain’s consistency (finality) level and consensus mechanism.
categories: Reference
---
# Wormhole Finality
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.
| Ethereum | 200 | 201 | | finalized | ~ 19min | Details |
| Solana | | 0 | 1 | | ~ 14s | Details |
| Acala | 200 | 201 | | finalized | ~ 24s | |
| Algorand | | | 0 | | ~ 4s | Details |
| Aptos | | | 0 | | ~ 4s | Details |
| Arbitrum | 200 | 201 | | finalized | ~ 18min | Details |
| Avalanche | 200 | | | finalized | ~ 2s | Details |
| Base | 200 | 201 | | finalized | ~ 18min | |
| Berachain | 200 | | | finalized | ~ 4s | |
| Blast | 200 | 201 | | finalized | ~ 18min | |
| BNB Smart Chain | 200 | 201 | | finalized | ~ 48s | Details |
| Celestia | | | 0 | | ~ 5s | |
| Celo | 200 | | | finalized | ~ 10s | |
| Cosmos Hub | | | 0 | | ~ 5s | |
| Dymension | | | 0 | | ~ 5s | |
| Evmos | | | 0 | | ~ 2s | |
| Fantom | 200 | | | finalized | ~ 5s | |
| Injective | | | 0 | | ~ 3s | |
| Ink | | | 0 | | ~ 9min | |
| Kaia | 200 | | | finalized | ~ 1s | |
| Karura | 200 | 201 | | finalized | ~ 24s | Details |
| Kujira | | | 0 | | ~ 3s | |
| Mantle | 200 | 201 | | finalized | ~ 18min | |
| Mezo | | | 0 | | ~ 8s | |
| Monad | | | 0 | | ~ 2s | |
| Moonbeam | 200 | 201 | | finalized | ~ 24s | Details |
| NEAR | | | 0 | | ~ 2s | Details |
| Neutron | | | 0 | | ~ 5s | |
| Oasis | 200 | | | finalized | ~ 12s | |
| Optimism | 200 | 201 | | finalized | ~ 18min | |
| Osmosis | | | 0 | | ~ 6s | |
| Polygon | 200 | | | finalized | ~ 66s | Details |
| Scroll | 200 | | | finalized | ~ 16min | |
| Sei | | | 0 | | ~ 1s | |
| Stargaze | | | 0 | | ~ 5s | |
| Sui | | | 0 | | ~ 3s | Details |
| Terra | | | 0 | | ~ 6s | |
| Terra 2.0 | | | 0 | | ~ 6s | |
| Unichain | 200 | 201 | | finalized | ~ 18min | |
| World Chain | | | 0 | | ~ 18min | |
| X Layer | 200 | 201 | | finalized | ~ 16min | |
| XPLA | | | 0 | | ~ 5s | |
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/reference/contract-addresses/
--- BEGIN CONTENT ---
---
title: Contract Addresses
description: This page documents the deployed contract addresses of the Wormhole contracts on each chain, including Core Contracts, TokenBridge, and more.
categories: Reference
---
# Contract Addresses
## Core Contracts
=== "Mainnet"
| Ethereum | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Solana | worm2ZoG2kUd4vFXhvjh93UUH596ayRfgQ2MgjNMTth |
| Acala | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Algorand | 842125965 |
| Aptos | 0x5bc11445584a763c1fa7ed39081f1b920954da14e04b32440cba863d03e19625 |
| Arbitrum | 0xa5f208e072434bC67592E4C49C1B991BA79BCA46 |
| Avalanche | 0x54a8e5f9c4CbA08F9943965859F6c34eAF03E26c |
| Base | 0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6 |
| Berachain | 0xCa1D5a146B03f6303baF59e5AD5615ae0b9d146D |
| Blast | 0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6 |
| BNB Smart Chain | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Celo | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Fantom | 0x126783A6Cb203a3E35344528B26ca3a0489a1485 |
| Gnosis | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Injective | inj17p9rzwnnfxcjp32un9ug7yhhzgtkhvl9l2q74d |
| Ink | 0xCa1D5a146B03f6303baF59e5AD5615ae0b9d146D |
| Kaia | 0x0C21603c4f3a6387e241c0091A7EA39E43E90bb7 |
| Karura | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Mantle | 0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6 |
| Moonbeam | 0xC8e2b0cD52Cf01b0Ce87d389Daa3d414d4cE29f3 |
| NEAR | contract.wormhole_crypto.near |
| Neutron | neutron16rerygcpahqcxx5t8vjla46ym8ccn7xz7rtc6ju5ujcd36cmc7zs9zrunh |
| Oasis | 0xfE8cD454b4A1CA468B57D79c0cc77Ef5B6f64585 |
| Optimism | 0xEe91C335eab126dF5fDB3797EA9d6aD93aeC9722 |
| Polygon | 0x7A4B5a56256163F07b2C80A7cA55aBE66c4ec4d7 |
| Pythnet | H3fxXJ86ADW2PNuDDmZJg6mzTtPxkYCpNuQUTgmJ7AjU |
| Scroll | 0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6 |
| Sei | sei1gjrrme22cyha4ht2xapn3f08zzw6z3d4uxx6fyy9zd5dyr3yxgzqqncdqn |
| SNAXchain | 0xc1BA3CC4bFE724A08FbbFbF64F8db196738665f4 |
| Sui | 0xaeab97f96cf9877fee2883315d459552b2b921edc16d7ceac6eab944dd88919c |
| Terra | terra1dq03ugtd40zu9hcgdzrsq6z2z4hwhc9tqk2uy5 |
| Terra 2.0 | terra12mrnzvhx3rpej6843uge2yyfppfyd3u9c3uq223q8sl48huz9juqffcnhp |
| Unichain | 0xCa1D5a146B03f6303baF59e5AD5615ae0b9d146D |
| World Chain | 0xcbcEe4e081464A15d8Ad5f58BB493954421eB506 |
| X Layer | 0x194B123c5E96B9b2E49763619985790Dc241CAC0 |
| XPLA | xpla1jn8qmdda5m6f6fqu9qv46rt7ajhklg40ukpqchkejcvy8x7w26cqxamv3w |
=== "Testnet"
| Ethereum Holesky | 0xa10f2eF61dE1f19f586ab8B6F2EbA89bACE63F7a |
| Ethereum Sepolia | 0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78 |
| Solana | 3u8hJUVTA4jH1wYAyUur7FFZVQ8H635K3tSHHF4ssjQ5 |
| Acala | 0x64fb09E405D2043ed7785a29E296C766D56F2056 |
| Algorand | 86525623 |
| Aptos | 0x5bc11445584a763c1fa7ed39081f1b920954da14e04b32440cba863d03e19625 |
| Arbitrum Sepolia | 0x6b9C8671cdDC8dEab9c719bB87cBd3e782bA6a35 |
| Avalanche | 0x7bbcE28e64B3F8b84d876Ab298393c38ad7aac4C |
| Base Sepolia | 0x79A1027a6A159502049F10906D333EC57E95F083 |
| Berachain | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| Blast | 0x473e002D7add6fB67a4964F13bFd61280Ca46886 |
| BNB Smart Chain | 0x68605AD7b15c732a30b1BbC62BE8F2A509D74b4D |
| Celo | 0x88505117CA88e7dd2eC6EA1E13f0948db2D50D56 |
| Fantom | 0x1BB3B4119b7BA9dfad76B0545fb3F531383c3bB7 |
| Gnosis | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| HyperEVM | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| Injective | inj1xx3aupmgv3ce537c0yce8zzd3sz567syuyedpg |
| Ink | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| Kaia | 0x1830CC6eE66c84D2F177B94D544967c774E624cA |
| Karura | 0x64fb09E405D2043ed7785a29E296C766D56F2056 |
| Linea | 0x79A1027a6A159502049F10906D333EC57E95F083 |
| Mantle | 0x376428e7f26D5867e69201b275553C45B09EE090 |
| Mezo | 0x268557122Ffd64c85750d630b716471118F323c8 |
| Monad | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| Moonbeam | 0xa5B7D85a8f27dd7907dc8FdC21FA5657D5E2F901 |
| NEAR | wormhole.wormhole.testnet |
| Neon | 0x268557122Ffd64c85750d630b716471118F323c8 |
| Neutron | neutron1enf63k37nnv9cugggpm06mg70emcnxgj9p64v2s8yx7a2yhhzk2q6xesk4 |
| Oasis | 0xc1C338397ffA53a2Eb12A7038b4eeb34791F8aCb |
| Optimism Sepolia | 0x31377888146f3253211EFEf5c676D41ECe7D58Fe |
| Osmosis | osmo1hggkxr0hpw83f8vuft7ruvmmamsxmwk2hzz6nytdkzyup9krt0dq27sgyx |
| Polygon Amoy | 0x6b9C8671cdDC8dEab9c719bB87cBd3e782bA6a35 |
| Pythnet | EUrRARh92Cdc54xrDn6qzaqjA77NRrCcfbr8kPwoTL4z |
| Scroll | 0x055F47F1250012C6B20c436570a76e52c17Af2D5 |
| Sei | sei1nna9mzp274djrgzhzkac2gvm3j27l402s4xzr08chq57pjsupqnqaj0d5s |
| Seievm | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| SNAXchain | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| Sui | 0x31358d198147da50db32eda2562951d53973a0c0ad5ed738e9b17d88b213d790 |
| Terra | terra1pd65m0q9tl3v8znnz5f5ltsfegyzah7g42cx5v |
| Terra 2.0 | terra19nv3xr5lrmmr7egvrk2kqgw4kcn43xrtd5g0mpgwwvhetusk4k7s66jyv0 |
| Unichain | 0xBB73cB66C26740F31d1FabDC6b7A46a038A300dd |
| World Chain | 0xe5E02cD12B6FcA153b0d7fF4bF55730AE7B3C93A |
| X Layer | 0xA31aa3FDb7aF7Db93d18DDA4e19F811342EDF780 |
| XPLA | xpla1upkjn4mthr0047kahvn0llqx4qpqfn75lnph4jpxfn8walmm8mqsanyy35 |
=== "Devnet"
| Ethereum | 0xC89Ce4735882C9F0f0FE26686c53074E09B0D550 |
| Solana | Bridge1p5gheXUvJ6jGWGeCsgPKgnE3YgdGKRVCMY9o |
| Algorand | 1004 |
| Aptos | 0xde0036a9600559e295d5f6802ef6f3f802f510366e0c23912b0655d972166017 |
| BNB Smart Chain | 0xC89Ce4735882C9F0f0FE26686c53074E09B0D550 |
| NEAR | wormhole.test.near |
| Sui | 0x5a5160ca3c2037f4b4051344096ef7a48ebf4400b3f385e57ea90e1628a8bde0 |
| Terra | terra14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9ssrc8au |
| Terra 2.0 | terra14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9ssrc8au |
## Token Bridge
=== "Mainnet"
| Ethereum | 0x3ee18B2214AFF97000D974cf647E7C347E8fa585 |
| Solana | wormDTUJ6AWPNvk59vGQbDvGJmqbDTdgWgAqcLBCgUb |
| Acala | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Algorand | 842126029 |
| Aptos | 0x576410486a2da45eee6c949c995670112ddf2fbeedab20350d506328eefc9d4f |
| Arbitrum | 0x0b2402144Bb366A632D14B83F244D2e0e21bD39c |
| Avalanche | 0x0e082F06FF657D94310cB8cE8B0D9a04541d8052 |
| Base | 0x8d2de8d2f73F1F4cAB472AC9A881C9b123C79627 |
| Berachain | 0x3Ff72741fd67D6AD0668d93B41a09248F4700560 |
| Blast | 0x24850c6f61C438823F01B7A3BF2B89B72174Fa9d |
| BNB Smart Chain | 0xB6F6D86a8f9879A9c87f643768d9efc38c1Da6E7 |
| Celo | 0x796Dff6D74F3E27060B71255Fe517BFb23C93eed |
| Fantom | 0x7C9Fc5741288cDFdD83CeB07f3ea7e22618D79D2 |
| Injective | inj1ghd753shjuwexxywmgs4xz7x2q732vcnxxynfn |
| Ink | 0x3Ff72741fd67D6AD0668d93B41a09248F4700560 |
| Kaia | 0x5b08ac39EAED75c0439FC750d9FE7E1F9dD0193F |
| Karura | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Mantle | 0x24850c6f61C438823F01B7A3BF2B89B72174Fa9d |
| Moonbeam | 0xb1731c586ca89a23809861c6103f0b96b3f57d92 |
| NEAR | contract.portalbridge.near |
| Oasis | 0x5848C791e09901b40A9Ef749f2a6735b418d7564 |
| Optimism | 0x1D68124e65faFC907325e3EDbF8c4d84499DAa8b |
| Polygon | 0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE |
| Scroll | 0x24850c6f61C438823F01B7A3BF2B89B72174Fa9d |
| Sei | sei1smzlm9t79kur392nu9egl8p8je9j92q4gzguewj56a05kyxxra0qy0nuf3 |
| SNAXchain | 0x8B94bfE456B48a6025b92E11Be393BAa86e68410 |
| Sui | 0xc57508ee0d4595e5a8728974a4a93a787d38f339757230d441e895422c07aba9 |
| Terra | terra10nmmwe8r3g99a9newtqa7a75xfgs2e8z87r2sf |
| Terra 2.0 | terra153366q50k7t8nn7gec00hg66crnhkdggpgdtaxltaq6xrutkkz3s992fw9 |
| Unichain | 0x3Ff72741fd67D6AD0668d93B41a09248F4700560 |
| World Chain | 0xc309275443519adca74c9136b02A38eF96E3a1f6 |
| X Layer | 0x5537857664B0f9eFe38C9f320F75fEf23234D904 |
| XPLA | xpla137w0wfch2dfmz7jl2ap8pcmswasj8kg06ay4dtjzw7tzkn77ufxqfw7acv |
=== "Testnet"
| Ethereum Holesky | 0x76d093BbaE4529a342080546cAFEec4AcbA59EC6 |
| Ethereum Sepolia | 0xDB5492265f6038831E89f495670FF909aDe94bd9 |
| Solana | DZnkkTmCiFWfYTfT41X3Rd1kDgozqzxWaHqsw6W4x2oe |
| Acala | 0xe157115ef34c93145Fec2FE53706846853B07F42 |
| Algorand | 86525641 |
| Aptos | 0x576410486a2da45eee6c949c995670112ddf2fbeedab20350d506328eefc9d4f |
| Arbitrum Sepolia | 0xC7A204bDBFe983FCD8d8E61D02b475D4073fF97e |
| Avalanche | 0x61E44E506Ca5659E6c0bba9b678586fA2d729756 |
| Base Sepolia | 0x86F55A04690fd7815A3D802bD587e83eA888B239 |
| Berachain | 0xa10f2eF61dE1f19f586ab8B6F2EbA89bACE63F7a |
| Blast | 0x430855B4D43b8AEB9D2B9869B74d58dda79C0dB2 |
| BNB Smart Chain | 0x9dcF9D205C9De35334D646BeE44b2D2859712A09 |
| Celo | 0x05ca6037eC51F8b712eD2E6Fa72219FEaE74E153 |
| Fantom | 0x599CEa2204B4FaECd584Ab1F2b6aCA137a0afbE8 |
| HyperEVM | 0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78 |
| Injective | inj1q0e70vhrv063eah90mu97sazhywmeegp7myvnh |
| Ink | 0x376428e7f26D5867e69201b275553C45B09EE090 |
| Kaia | 0xC7A13BE098720840dEa132D860fDfa030884b09A |
| Karura | 0xe157115ef34c93145Fec2FE53706846853B07F42 |
| Linea | 0xC7A204bDBFe983FCD8d8E61D02b475D4073fF97e |
| Mantle | 0x75Bfa155a9D7A3714b0861c8a8aF0C4633c45b5D |
| Mezo | 0xA31aa3FDb7aF7Db93d18DDA4e19F811342EDF780 |
| Monad | 0xF323dcDe4d33efe83cf455F78F9F6cc656e6B659 |
| Moonbeam | 0xbc976D4b9D57E57c3cA52e1Fd136C45FF7955A96 |
| NEAR | token.wormhole.testnet |
| Neon | 0xEe3dB83916Ccdc3593b734F7F2d16D630F39F1D0 |
| Oasis | 0x88d8004A9BdbfD9D28090A02010C19897a29605c |
| Optimism Sepolia | 0x99737Ec4B815d816c49A385943baf0380e75c0Ac |
| Polygon Amoy | 0xC7A204bDBFe983FCD8d8E61D02b475D4073fF97e |
| Scroll | 0x22427d90B7dA3fA4642F7025A854c7254E4e45BF |
| Sei | sei1jv5xw094mclanxt5emammy875qelf3v62u4tl4lp5nhte3w3s9ts9w9az2 |
| Seievm | 0x23908A62110e21C04F3A4e011d24F901F911744A |
| SNAXchain | 0xa10f2eF61dE1f19f586ab8B6F2EbA89bACE63F7a |
| Sui | 0x6fb10cdb7aa299e9a4308752dadecb049ff55a892de92992a1edbd7912b3d6da |
| Terra | terra1pseddrv0yfsn76u4zxrjmtf45kdlmalswdv39a |
| Terra 2.0 | terra1c02vds4uhgtrmcw7ldlg75zumdqxr8hwf7npseuf2h58jzhpgjxsgmwkvk |
| Unichain | 0xa10f2eF61dE1f19f586ab8B6F2EbA89bACE63F7a |
| World Chain | 0x430855B4D43b8AEB9D2B9869B74d58dda79C0dB2 |
| X Layer | 0xdA91a06299BBF302091B053c6B9EF86Eff0f930D |
| XPLA | xpla1kek6zgdaxcsu35nqfsyvs2t9vs87dqkkq6hjdgczacysjn67vt8sern93x |
=== "Devnet"
| Ethereum | 0x0290FB167208Af455bB137780163b7B7a9a10C16 |
| Solana | B6RHG3mfcckmrYN1UhmJzyS1XX3fZKbkeUcpJe9Sy3FE |
| Algorand | 1006 |
| Aptos | 0x84a5f374d29fc77e370014dce4fd6a55b58ad608de8074b0be5571701724da31 |
| BNB Smart Chain | 0x0290FB167208Af455bB137780163b7B7a9a10C16 |
| NEAR | token.test.near |
| Sui | 0xa6a3da85bbe05da5bfd953708d56f1a3a023e7fb58e5a824a3d4de3791e8f690 |
| Terra | terra1nc5tatafv6eyq7llkr2gv50ff9e22mnf70qgjlv737ktmt4eswrquka9l6 |
| Terra 2.0 | terra1nc5tatafv6eyq7llkr2gv50ff9e22mnf70qgjlv737ktmt4eswrquka9l6 |
## Wormhole Relayer
=== "Mainnet"
| Ethereum | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Arbitrum | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Avalanche | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Base | 0x706f82e9bb5b0813501714ab5974216704980e31 |
| Berachain | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Blast | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| BNB Smart Chain | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Celo | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Fantom | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Ink | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Kaia | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Mantle | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Moonbeam | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Optimism | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Polygon | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Scroll | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| SNAXchain | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| Unichain | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
| World Chain | 0x1520cc9e779c56dab5866bebfb885c86840c33d3 |
| X Layer | 0x27428DD2d3DD32A4D7f7C497eAaa23130d894911 |
=== "Testnet"
| Ethereum Sepolia | 0x7B1bD7a6b4E61c2a123AC6BC2cbfC614437D0470 |
| Arbitrum Sepolia | 0x7B1bD7a6b4E61c2a123AC6BC2cbfC614437D0470 |
| Avalanche | 0xA3cF45939bD6260bcFe3D66bc73d60f19e49a8BB |
| Base Sepolia | 0x93BAD53DDfB6132b0aC8E37f6029163E63372cEE |
| Berachain | 0x362fca37E45fe1096b42021b543f462D49a5C8df |
| BNB Smart Chain | 0x80aC94316391752A193C1c47E27D382b507c93F3 |
| Celo | 0x306B68267Deb7c5DfCDa3619E22E9Ca39C374f84 |
| Fantom | 0x7B1bD7a6b4E61c2a123AC6BC2cbfC614437D0470 |
| Ink | 0x362fca37E45fe1096b42021b543f462D49a5C8df |
| Monad | 0x362fca37E45fe1096b42021b543f462D49a5C8df |
| Moonbeam | 0x0591C25ebd0580E0d4F27A82Fc2e24E7489CB5e0 |
| Optimism Sepolia | 0x93BAD53DDfB6132b0aC8E37f6029163E63372cEE |
| Seievm | 0x362fca37E45fe1096b42021b543f462D49a5C8df |
| Unichain | 0x362fca37E45fe1096b42021b543f462D49a5C8df |
=== "Devnet"
| Ethereum | 0xcC680D088586c09c3E0E099a676FA4b6e42467b4 |
| BNB Smart Chain | 0xcC680D088586c09c3E0E099a676FA4b6e42467b4 |
## CCTP
=== "Mainnet"
| Ethereum | 0xAaDA05BD399372f0b0463744C09113c137636f6a |
| Arbitrum | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
| Avalanche | 0x09Fb06A271faFf70A651047395AaEb6265265F13 |
| Base | 0x03faBB06Fa052557143dC28eFCFc63FC12843f1D |
| Optimism | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
| Polygon | 0x0FF28217dCc90372345954563486528aa865cDd6 |
=== "Testnet"
| Ethereum Sepolia | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
| Arbitrum Sepolia | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
| Avalanche | 0x58f4c17449c90665891c42e14d34aae7a26a472e |
| Base Sepolia | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
| Optimism Sepolia | 0x2703483B1a5a7c577e8680de9Df8Be03c6f30e3c |
=== "Devnet"
N/A
## Read-Only Deployments
=== "Mainnet"
| Corn | 0xa683c66045ad16abb1bCE5ad46A64d95f9A25785 |
| Gnosis | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Goat | 0x352A86168e6988A1aDF9A15Cb00017AAd3B67155 |
| LightLink | 0x352A86168e6988A1aDF9A15Cb00017AAd3B67155 |
| Rootstock | 0xbebdb6C8ddC678FfA9f8748f85C815C556Dd8ac6 |
| Sonic | 0x352A86168e6988A1aDF9A15Cb00017AAd3B67155 |
| Telos | 0x352A86168e6988A1aDF9A15Cb00017AAd3B67155 |
!!!note
Read-only deployments allow Wormhole messages to be received on chains not fully integrated with Wormhole Guardians. These deployments support cross-chain data verification but cannot originate messages. For example, a governance message can be sent from a fully integrated chain and processed on a read-only chain, but the read-only chain cannot send messages back.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/reference/wormhole-formatted-addresses/
--- BEGIN CONTENT ---
---
title: Wormhole Formatted Addresses
description: Explanation of Wormhole formatted 32-byte hex addresses, their conversion, and usage across different blockchain platforms.
categories: Reference
---
# Wormhole Formatted Addresses
## Introduction
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.
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/start-building/supported-networks/
--- BEGIN CONTENT ---
---
title: Supported Networks
description: Learn about the compatible environments and individual networks that Wormhole supports. Readers can click on each of the blockchain logos for more information.
categories: Reference
---
# Supported Networks
Wormhole supports several different blockchains and environments. Since many of the concepts for using Wormhole within a given blockchain environment are the same, this section is organized by environment, and individual chains are detailed within the environment page.
## Supported Environments
- [EVM (Ethereum and compatible chains)](#evm)
- [SVM (Solana and compatible chains)](#svm)
- [CosmWasm (Cosmos ecosystem chains)](#cosmwasm)
- [AVM (Algorand)](#avm)
- [NEAR VM (NEAR)](#near-vm)
- [Move VM (Aptos)](#move-vm)
- [Sui Move VM (Sui)](#sui-move-vm)
## Supported Blockchains by Environment
### EVM
| Ethereum | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Acala | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Arbitrum | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Avalanche | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Base | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Berachain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Blast | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| BNB Smart Chain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Celo | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Fantom | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Gnosis | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| HyperEVM | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs |
| Ink | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Kaia | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Karura | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs |
| Linea | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Mantle | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Mezo | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Monad | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Moonbeam | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Neon | EVM | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Oasis | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Optimism | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Polygon | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Scroll | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Seievm | EVM | :x: | :white_check_mark: | |
| SNAXchain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Unichain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| World Chain | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| X Layer | EVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### SVM
| Solana | SVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Pythnet | SVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### AVM
| Algorand | AVM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### CosmWasm
| Injective | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Neutron | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Osmosis | CosmWasm | :x: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Sei | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Terra | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| Terra 2.0 | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
| XPLA | CosmWasm | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### Move VM
| Aptos | Move VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### NEAR VM
| NEAR | NEAR VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
### Sui Move VM
| Sui | Sui Move VM | :white_check_mark: | :white_check_mark: | :material-web:Website:material-file-document:Developer Docs:octicons-package-16:Block Explorer |
--- END CONTENT ---
Doc-Content: https://wormhole.com/docs/build/start-building/testnet-faucets/
--- BEGIN CONTENT ---
---
title: Testnet Faucets
description: This page includes resources to quickly find the Testnet tokens you need to deploy and test applications and contracts on Wormhole's supported networks.
categories: Reference
---
# Testnet Faucets
## Get Started
Don't let the need for testnet tokens get in the way of buildling your next great idea with Wormhole. Use this guide to quickly locate the testnet token faucets you need to deploy and test applications and contracts on Wormhole's supported networks.
### EVM
| Ethereum Holesky | EVM | ETH | Alchemy Faucet |
| Ethereum Sepolia | EVM | ETH | Alchemy Faucet |
| Acala | EVM | ACA | Discord Faucet |
| Arbitrum Sepolia | EVM | ETH | List of Faucets |
| Avalanche | EVM | AVAX | Official Avalanche Faucet |
| Base Sepolia | EVM | ETH | List of Faucets |
| Berachain | EVM | BERA | Official Berachain Faucet |
| Blast | EVM | ETH | List of Faucets |
| BNB Smart Chain | EVM | BNB | Official BNB Faucet |
| Celo | EVM | CELO | Official Celo Faucet |
| Fantom | EVM | FTM | Official Fantom Faucet |
| Gnosis | EVM | xDAI | Official Gnosis Faucet |
| HyperEVM | EVM | mock USDC | Official Hyperliquid Faucet |
| Ink | EVM | ETH | Official Ink Faucet |
| Kaia | EVM | KAIA | Official Kaia Faucet |
| Karura | EVM | ACA | Discord Faucet |
| Linea | EVM | ETH | List of Faucets |
| Mantle | EVM | MNT | Official Mantle Faucet |
| Monad | EVM | MON | Official Monad Faucet |
| Moonbeam | EVM | DEV | Official Moonbeam Faucet |
| Neon | EVM | NEON | Official Neon Faucet |
| Oasis | EVM | TEST | Official Oasis Faucet |
| Optimism Sepolia | EVM | ETH | Superchain Faucet |
| Polygon Amoy | EVM | POL | Official Polygon Faucet |
| Scroll | EVM | ETH | List of Faucets |
| Unichain | EVM | ETH | QuickNode Faucet |
| World Chain | EVM | ETH | Alchemy Faucet |
| X Layer | EVM | OKB | X Layer Official Faucet |
### SVM
| Pythnet | SVM | ETH | Superchain Faucet |
### AVM
| Algorand | AVM | ALGO | Official Algorand Faucet |
### CosmWasm
| Celestia | CosmWasm | TIA | Discord Faucet |
| Cosmos Hub | CosmWasm | ATOM | Discord Faucet |
| Evmos | CosmWasm | TEVMOS | Official Evmos Faucet |
| Injective | CosmWasm | INJ | Official Injective Faucet |
| Kujira | CosmWasm | KUJI | Discord Faucet |
| Neutron | CosmWasm | NTRN | List of Faucets |
| Noble | CosmWasm | USDC | Circle Faucet |
| Osmosis | CosmWasm | OSMO | Official Osmosis Faucet |
| SEDA | CosmWasm | SEDA | Official SEDA Faucet |
| Sei | CosmWasm | SEI | Sei Atlantic-2 Faucet |
| Terra | CosmWasm | LUNA | Terra Official Faucet |
| Terra 2.0 | CosmWasm | LUNA | Terra Official Faucet |
| XPLA | CosmWasm | XPLA | XPLA Official Faucet |
### Move VM
| Aptos | Move VM | APT | Official Aptos Faucet |
### NEAR VM
| NEAR | NEAR VM | NEAR | Official NEAR Faucet |
### Sui Move VM
| Sui | Sui Move VM | SUI | List of Faucets |