Skip to content

Commit b3f185a

Browse files
dawnkelly09dawnkelly09
authored
Merge pull request #8 from wormhole-foundation/ilariae/core-contracts
Ilariae/core contracts
2 parents 5b693ea + 638b304 commit b3f185a

File tree

8 files changed

+145
-0
lines changed

8 files changed

+145
-0
lines changed

‎.snippets/code/learn/messaging/core-contracts/receiving.js

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
parseAndVerifyVAA(byte[] VAA)

‎.snippets/code/learn/messaging/core-contracts/sending.js

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
publishMessage(
2+
int nonce,
3+
byte[] payload,
4+
int consistencyLevel
5+
) returns int sequenceNumber

‎learn/.pages

+1
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ nav:
55
- 'Security': 'security.md'
66
- 'Architecture Overview': 'architecture.md'
77
- infrastructure
8+
- messaging

‎learn/messaging/.pages

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
title: Messaging
2+
nav:
3+
- index.md
4+
- 'Overview': 'overview.md'
5+
- 'Core Contracts': 'core-contracts.md'
6+
- 'Token Bridge': 'token-nft-bridge.md'

‎learn/messaging/core-contracts.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: Core Contracts
3+
description: Discover Wormhole's Core Contracts, enabling cross-chain communication with message sending, receiving, and multicast features for efficient synchronization.
4+
---
5+
6+
# Core Contracts
7+
8+
The Core Contracts are the mechanism by which all Wormhole messages are emitted. All cross-chain applications either interact directly with the Core Contract or interact with another contract that does. Each blockchain in the ecosystem has a single Core Contract, which the Guardians are required to monitor. These Core Contracts emit the messages that the [Guardians](/learn/infrastructure/guardians/){target=_blank} pick up as [Observations](#){target=_blank}.
9+
10+
Core Contracts are generally simple and can be divided into sending and receiving sides, each of which will be defined next.
11+
12+
## Sending
13+
14+
The implementation strategy for `publishMessage` differs by chain. However, the general strategy consists of the Core Contract posting the following items to the blockchain logs:
15+
16+
- `emitterAddress` of the contract which made the `publishMessage` call
17+
- `sequenceNumber`
18+
- `consistencyLevel`
19+
20+
Once the desired `consistencyLevel` has been reached and the message passes all of the Guardians' optional checks, the Guardian Network will produce the requested Verified Action Approvals (VAAs).
21+
22+
The method signature for publishing messages:
23+
24+
```js
25+
--8<-- 'code/learn/messaging/core-contracts/sending.js'
26+
```
27+
28+
There are no fees to publish a message, except when publishing on Solana, but this is subject to change in the future.
29+
30+
### Parameters
31+
32+
- `payload` ++"byte[]"++ - the content of the emitted message is an arbitrary byte array. Due to the constraints of individual blockchains, it may be capped to a certain maximum length
33+
34+
- `consistencyLevel` ++"int"++ - a numeric value that defines the required level of finality that must be reached before the Guardians will observe and attest to emitted events. 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 [Environments](#){target=\_blank} pages <!-- link to blockchain platforms -->
35+
36+
- `nonce` ++"int"++ - a free integer field that can be used however you like. Note that changing the `nonce` will result in a different digest
37+
38+
### Returns
39+
40+
- `sequenceNumber` ++"int"++ - 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 [APIs](#){target=\_blank}
41+
42+
## Receiving
43+
44+
The method signature for receiving a message encoded as a VAA:
45+
46+
```js
47+
--8<-- 'code/learn/messaging/core-contracts/receiving.js'
48+
```
49+
50+
The general approach involves the Core Contract on a target Chain parsing and verifying the components of a VAA, which include the original `emitterAddress`, `sequenceNumber`, and `consistencyLevel` among other fields.
51+
52+
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.
53+
54+
### Parameters
55+
56+
- `VAA` ++"byte[]"++ - the encoded message as a Verified Action Approval, which is a byte array that contains all necessary information for verification and processing
57+
58+
### Returns
59+
60+
- `payload` ++"byte[]"++ - the original payload of the message, as extracted from the VAA, which can then be further processed or acted upon according to the logic of the contract
61+
62+
### Error Handling
63+
64+
When a VAA is passed to the `parseAndVerifyVAA` function, it will either return the payload and associated metadata for the VAA or throw an exception. An exception should only be thrown if the VAA fails signature verification, an indication the VAA is invalid or inauthentic in some form.
65+
66+
!!! note
67+
Take care to make sure this method is called during the execution of a transaction where a VAA is passed to ensure the signatures are checked and verified.
68+
69+
## Multicast
70+
71+
Multicast refers to simultaneously broadcasting a single message or transaction across different blockchains. This means that there is no destination address or chain for the sending and receiving functions. This is possible because VAAs simply 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.
72+
73+
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.
74+
75+
This does not mean an application _cannot_ specify a destination address or chain. For example, the Token Bridge and Standard Relayer contracts require that some destination details be passed and verified on the destination chain.
76+
77+
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.
78+

‎learn/messaging/index.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: TODO
3+
description: TODO
4+
---

‎learn/messaging/overview.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Overview
3+
description: Discover Wormhole's Messaging features, including cross-chain communication, token and NFT bridges, and the Circle Bridge integration.
4+
---
5+
6+
# Messaging Overview
7+
8+
The Messaging section covers various aspects and services related to communication protocols and systems within our platform. Each subsection provides detailed information on specific components, contracts, and bridges for messaging and data transfer. Below is a brief overview of each subsection:
9+
10+
## Core Contracts
11+
12+
The [Core Contracts](/learn/messaging/core-contracts/){target=\_blank} form the backbone of Wormhole's cross-chain communication system, allowing for the emission and receipt of messages across different blockchains. Each blockchain in the ecosystem has its own Core Contract, which Guardians observe to ensure the integrity and synchronization of data. These contracts handle message sending, receiving, and multicast, providing a seamless mechanism for inter-chain communication without additional costs.
13+
14+
## Native Token Transfers
15+
16+
Wormhole's [Native Token Transfers](/learn/messaging/ntt/ntt-overview/){target=\_blank} (NTT) offer an open-source and flexible framework for cross-chain token transfers, providing full control over token behavior on each blockchain. This system supports two operation modes: locking mode for preserving the original token supply on a single chain and burning mode for distributing multichain tokens across various chains. Key features include integrator flexibility, advanced rate limiting, no need for liquidity pools, and custom attestation options. This ensures a consistent user experience, robust security, and easy integration for complex multichain deployments.
17+
18+
## Token Bridge
19+
20+
The [Token and NFT Bridges](/learn/messaging/token-nft-bridge/){target=\_blank} facilitate cross-chain transfers of fungible and non-fungible tokens (NFTs). Utilizing a lock and mint mechanism, the bridge ensures secure and efficient asset movement between blockchains. The Token Bridge allows for token transfers with specific receiver details, while the NFT Bridge handles the transfer of unique digital assets with specialized rules for creating wrapped versions on the destination chain.
21+
22+
## Circle's CCTP Bridge
23+
24+
The [CCTP Bridge](/learn/messaging/cctp/){target=\_blank} supports fast and cost-effective native USDC transfers across blockchains using Circle's Cross Chain Transfer Protocol (CCTP). While distinct from Wormhole, this protocol is enhanced by Wormhole's features, such as automated relaying, gas payment on the destination chain, and native gas dropoff, making it more user-friendly. The integration can be achieved through the Wormhole Connect Widget or the Connect SDK, providing a seamless experience for developers and users.
25+
26+
## Gateway
27+
28+
Wormhole [Gateway](/learn/messaging/gateway/){target=\_blank} is a Cosmos-SDK chain designed to bridge non-native assets into the Cosmos ecosystem, offering unified liquidity across Cosmos chains. By utilizing IBC (Inter-Blockchain Communication), Wormhole Gateway prevents liquidity fragmentation and ensures that foreign assets bridged via Wormhole have unified liquidity across the Cosmos ecosystem. In addition to facilitating asset transfers, Wormhole Gateway includes features like the IBC Shim Contract, Token Factory Module, and IBC Composability Middleware, allowing seamless integration with other Cosmos chains and external blockchains. This setup supports various transfer models, including external-to-cosmos, Cosmos-to-external, and inter-cosmos transfers, ensuring flexibility and security in multichain asset movement.
29+

‎learn/messaging/token-nft-bridge.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Token Bridge
3+
description: Learn about Wormhole's Token and NFT Bridge for cross-chain transfers using lock and mint mechanisms, ensuring secure and efficient asset movement.
4+
---
5+
6+
# Token and NFT Bridge
7+
8+
## Token Bridge
9+
10+
!!! note
11+
Before a token transfer can be made, the token being transferred must exist as a wrapped asset on the target chain. This is done by [Attesting](#){target=\_blank} the token details on the target chain. <!-- link to VAAs -->
12+
13+
The Token Bridge contract allows token transfers between blockchains through a lock and mint mechanism, using the [Core Contract](/learn/messaging/core-contracts/){target=\_blank} with a specific [payload](#){target=\_blank} to pass information about the transfer. <!--payload links to VAAs page payloads -->
14+
15+
The Token Bridge also supports sending tokens with some additional data in the form of arbitrary byte payload attached to the token transfer. This type of transfer is referred to as a [Contract Controlled Transfer](#){target=\_blank}. <!-- links to VAAs page token + msg -->
16+
17+
While the [Core Contract](/learn/messaging/core-contracts/){target=\_blank} has no specific receiver by default, transfers sent through the token bridge do have a specific receiver chain and address to ensure the tokens are minted to the expected recipient.
18+
19+
## NFT Bridge
20+
21+
The NFT Bridge functions similarly to the Token Bridge but with special rules for what may be transferred and how the wrapped version is created on the destination chain.

0 commit comments

Comments
 (0)