Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refresh core contracts page #294

Merged
merged 23 commits into from
Mar 25, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
83b7958
move pages, links, images, and snippets to new IA
eshaben Feb 19, 2025
1658d73
Ilariae/settlement ia (#268)
ilariae Mar 4, 2025
7d99922
Dawn/connect index makeover (#263)
dawnkelly09 Mar 13, 2025
96b7119
Bring token bridge build into new ia (#279)
ilariae Mar 13, 2025
48cfe08
refactors core contracts page for new IA release
dawnkelly09 Mar 14, 2025
6644b78
applies review feedback, updates llms
dawnkelly09 Mar 17, 2025
8da2ab9
Ilariae/settlement faq (#278)
ilariae Mar 18, 2025
2d8893a
adds content: build/core messaging/index (#281)
dawnkelly09 Mar 18, 2025
dae1fe6
merge the latest from main into new-product-ia (#295)
eshaben Mar 18, 2025
8ae0a30
Add build/transfers/index page (#275)
dawnkelly09 Mar 18, 2025
76e3fea
Updates learn infra index page (#282)
dawnkelly09 Mar 18, 2025
2e21892
updates learn transfers index (#283)
dawnkelly09 Mar 18, 2025
49119d7
new content: build index page (#289)
dawnkelly09 Mar 18, 2025
cd80065
Dawn/learn index (#290)
dawnkelly09 Mar 18, 2025
1be8067
Martinh/new product ia (#303)
martin0995 Mar 18, 2025
fa05cb6
typo fix (#308)
ilariae Mar 19, 2025
0986687
temporarily lower needed solana cli version for NTT (#306)
ilariae Mar 19, 2025
8bda922
Martinh/update sdk v1.13.3 new ia (#309)
martin0995 Mar 19, 2025
36505ee
merge conflicts (#311)
eshaben Mar 19, 2025
b3c6f91
Apply suggestions from code review
dawnkelly09 Mar 20, 2025
f5b00ff
clear merge conflicts
dawnkelly09 Mar 20, 2025
70141b4
merge conflicts
dawnkelly09 Mar 20, 2025
84a658c
clear conflicts, update llms
dawnkelly09 Mar 24, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 41 additions & 22 deletions learn/infrastructure/core-contracts.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,40 @@
---
title: Core Contracts
description: Discover Wormhole's Core Contracts, enabling cross-chain communication with message sending, receiving, and multicast features for efficient synchronization.
description: Discover Wormhole's Core Contracts, which enable multichain communication with message sending, receiving, and multicast features for efficient synchronization.
---

# Core Contracts

## Introduction

The Wormhole Core Contract is a fundamental component of the Wormhole interoperability protocol deployed across each supported blockchain network. This contract acts as the foundational layer that enables secure and efficient cross-chain messaging, as all cross-chain applications either interact directly with the Core Contract or with another contract that does.
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 guide summarizes the key functions of the Core Contract and outlines how the Core Contract works.
This page summarizes the key functions of the Core Contract and outlines how the Core Contract works.

## Key Functions of the Wormhole Core Contract
## Key Functions

- **Cross-chain messaging** - the Core Contract enables the transfer of messages between different blockchain networks connected via Wormhole. It standardizes and secures the message format, ensuring consistent communication across multiple chains. This capability allows developers to build cross-chain applications that leverage the unique features of each network
Key functions of the Wormhole Core Contract include the following:

- **Verification and validation** - the Core Contract is responsible for verifying and validating all VAAs received on the target chain. When a message is transmitted from one blockchain, it is signed by the Wormhole Guardians (a decentralized set of validators). The Core Contract on the target chain checks this signature to confirm that the message is legitimate and has not been tampered with

- **Guardian Network coordination** - the Core Contract coordinates with Wormhole's Guardian Network to facilitate secure, trustless communication across chains. By relying on a quorum of Guardians to verify cross-chain messages and transactions, the contract ensures that only validated interactions are processed, enhancing the protocol's overall security and reliability

- **Event emission for monitoring** - the Core Contract emits events for every cross-chain message it processes, allowing dApps and developers to monitor activity on the network. These events are critical for tracking message statuses, debugging, and building responsive applications that can react to cross-chain events in real time
- **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 cross-chain 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. This process involves several steps, from the initial message submission to final execution, all while leveraging the Wormhole Guardian network to maintain trust and security.
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.

Below is a simplified breakdown that focuses on the role of the Wormhole Core Contract in these operations:
The following describes the role of the Wormhole Core Contract in message transfers:

1. **Message submission** - when a user initiates a cross-chain 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 observe and sign the message independently. 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, such as minting tokens, updating states, or calling specific smart contract functions
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

When sending a cross-chain message from the source chain Core Contract, you'll call a function that publishes the message. The implementation strategy for publishing messages differs by chain. However, the general strategy consists of the Core Contract posting the following items to the blockchain logs:
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)
Expand All @@ -45,16 +44,36 @@ There are no fees to publish a message except when publishing on Solana, but thi

### Message Reception

When receiving a cross-chain message on the target chain Core Contract, the general approach involves parsing and verifying the [components of a VAA](/docs/learn/infrastructure/vaas#vaa-format).

The process of receiving and verifying a VAA ensures that the message was properly attested by the Guardian Network, maintaining the integrity and authenticity of the data transmitted between chains.
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. This means there is no destination address or chain for the sending and receiving functions. This is possible because 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.
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 the state across the entire ecosystem because a single blockchain can make its data available to every chain in a single action with low latency. This reduces the complexity of the n^2 problems encountered by routing data to a large number of blockchains.
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 and Wormhole relayer contracts require that some destination details be passed and verified on the destination chain.
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

<div class="grid cards" markdown>

- :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/)

</div>
Loading