certusone
/
xdapp-book
mirror of https://github.com/certusone/xdapp-book.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update 3_coreLayerContracts.md 

Adjusted language for clarity and syntax. Revised punctuation and reorganized some of the opening concepts.
This commit is contained in:
Ian Traas 2022-07-18 20:49:00 -05:00 committed by GitHub
parent 360f2aefbc
commit d52953ef94
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
src/wormhole/3_coreLayerContracts.md
View File

@ -1,51 +1,55 @@
# Core Contracts
The Wormhole Core Contracts are one of the most pivotal pieces of the Wormhole ecosystem, and serve as a great place to start when learning about how data flows through the ecosystem.
The Wormhole Core Contracts are one of the most pivotal pieces of the Wormhole ecosystem. They serve as a great place to start when learning about how data flows through the ecosystem.
There is one Core Contract on each blockchain in the ecosystem, and this is the contract which the Guardians are required to observe. The Core Contracts are the mechanism by which all Wormhole messages are emitted. All xDapps either interact directly with the Core Contract, or interact with some other contract which does.
The Core Contracts are the mechanism by which all Wormhole messages are emitted. All xDapps either interact directly with the Core Contract or interact with another contract that does. There is one Core Contract on each blockchain in the ecosystem, and this is the contract which the Guardians are required to observe.
The Core Contracts are quite simple and only have a few public-facing functions.
In general, Core Contracts are simple with only a few public-facing functions, which we'll define next.
---
First, we have the 'sending' side of the Core Contract:
publishMessage(
int nonce,
byte[] payload,
int consistencyLevel
) returns int sequenceNumber
This is the mechanism by which Wormhole Messages are emitted.
This is the foundational mechanism by which Wormhole Messages are emitted. Let's break it down a bit:
- **payload** is an arbitrary byte array, and is the content of the emitted message. It may be capped to a certain maximum length due to the constraints of individual blockchains.
- **consistencyLevel** is the number of blocks which the guardians should wait prior to emitting a VAA for this message. This number is usually either 1, or equal to the chain's finality period. This is a defense against transactions being orphaned.
- **nonce** - on chains where batch VAAs are supported, if multiple messages in the same transaction have the same nonce, a batch VAA will be produced alongside the individual VAAs. This feature reduces gas costs and simplifies composeability.
- **payload** - The content of the emitted message and an arbitrary byte array. It may be capped to a certain maximum length due to the constraints of individual blockchains.
- **sequenceNumber** - this is a unique index number for the message. When combined with the emitter contract address and emitter chain ID, the corresponding VAA can be retrieved from a guardian network node.
- **consistencyLevel** - The number of blocks which the Guardians should wait prior to emitting a VAA for this message. This number is usually either 1 or equal to the chain's finality period. This is a defense against transactions being orphaned.
The implementation strategy for publishMessage differs by chain. However, the general strategy is that the Core Contract will post the emitterAddress (the contract which called publishMessage), sequenceNumber, and consistencyLevel into the blockchain logs. Once the desired consistencyLevel has elapsed, the Guardian Network will produce the requested VAAs.
- **nonce** - If multiple messages in the same transaction have the same nonce, a batch VAA will be produced alongside the individual VAAs on chains that allow them. This reduces gas costs and simplifies composeability.
Currently there are no fees to publish a message, except when publishing on Solana. This is not guaranteed to always be the case, however.
- **sequenceNumber** - A unique index number for the message. When combined with the emitter contract address and emitter chain ID, the corresponding VAA can be retrieved from a guardian network node.
The implementation strategy for publishMessage differs by chain, but the general strategy consists of the Core Contract posting the emitterAddress (the contract which called publishMessage), sequenceNumber, and consistencyLevel into the blockchain logs. Once the desired consistencyLevel has elapsed, the Guardian Network will produce the requested VAAs.
Currently there are no fees to publish a message (with the exception of publishing on Solana) but this is not guaranteed to always be the case in the future.
---
Second, we have 'receiving' side of the Core contract.
Next, we have the 'receiving' side of the Core contract.
parseAndVerifyVAA( byte[] VAA )
This function, when passed a VAA, will either return the payload and associated metadata for the VAA, or throw an exception. An exception should only ever throw if the VAA fails signature verification, which would indicate that the VAA is invalid or inauthentic in some form.
When passed a VAA, this function will either return the payload and associated metadata for the VAA or throw an exception. An exception should only ever throw if the VAA fails signature verification, indicating the VAA is invalid or inauthentic in some form.
---
## Multicasting
Let's take a moment to point out that there is no inclusion of any destination address or chain in these functions.
Let's take a moment to point out that there is no destination address or chain in these functions.
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 they are brought to.
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 they are brought to.
This multicast-by-default model is intentional, and also integral to the design. Having this multicast capacity makes it easy to synchronize 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, in turn, reduces the complexity of the n^2 problems encountered by routing data to a large number of blockchains.
This multicast-by-default model is integral to the design. Having this multicast capacity makes it easy to synchronize 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.
Use cases where the message has an intended recipient or is only meant to be consumed once must be handled in logic outside the Core Contract. There are standard practices for accomplishing these features shown later on in the code examples, and some ecosystem contracts (namely Portal & the Relaying contract) handle this on behalf of downstream consumers.
Use cases where the message has an intended recipient or is only meant to be consumed a single time must be handled in logic outside the Core Contract. There are standard practices for accomplishing these features later on in the code examples, and some ecosystem contracts (namely Portal & the Relaying contract) handle this on behalf of downstream consumers.
Lastly, because the VAA creation is a separate concern from relaying, there is _no additional cost_ to this multicast model when a single chain is being targetted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
Lastly, because the VAA creation is separate from relaying, there is _no additional cost_ to the multicast model when a single chain is being targetted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
In the next section we'll dive into the technical specfications of the VAA.
In our next section, we'll dive into the technical specfications of the VAA.