Skip to content

Commit 5b693ea

Browse files
eshabeneshaben
authored
Merge pull request #7 from wormhole-foundation/ilariae/VAAs
Ilariae/vaas
2 parents 1dc4dfa + 44c9185 commit 5b693ea

File tree

3 files changed

+178
-0
lines changed

3 files changed

+178
-0
lines changed

‎.snippets/code/learn/infrastructure/VAAs/snippet-1.js

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// hash the bytes of the body twice
2+
digest = keccak256(keccak256(body))
3+
// sign the result
4+
signature = ecdsa_sign(digest, key)

‎.snippets/code/learn/infrastructure/VAAs/snippet-2.js

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module: 0x0000000000000000000000000000000000000000000000000000436f7265
2+
action: 1
3+
chain: 1
4+
new_contract: 0x348567293758957162374959376192374884562522281937446234828323

‎learn/infrastructure/vaas.md

+170
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: VAAs
3+
description: Learn about Verified Action Approvals (VAAs) in Wormhole, their structure, validation, and role in cross-chain communication.
4+
---
5+
6+
# Verified Action Approvals
7+
8+
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.
9+
10+
The Guardians must validate messages emitted by contracts before sending them to the target chain. Once a majority of Guardians observe the message and determine finality, the Guardians sign a keccak256 hash of the message body.
11+
12+
The message is wrapped up in a structure called a VAA, which combines the message with the Guardian signatures to form a proof.
13+
14+
VAAs are uniquely indexed by the (`emitter_chain`, `emitter_address`, `sequence`) tuple. To obtain a VAA, one can query the Guardian [RPC](#){target=\_blank} or the [API](#){target=\_blank} with this information.
15+
16+
These VAAs are ultimately what a smart contract on a receiving chain must process to receive a Wormhole message.
17+
18+
## VAA Format
19+
20+
The basic VAA has two components: a header and a body.
21+
22+
### Header
23+
24+
The header holds metadata about the current VAA, the Guardian set that is currently active, and the list of signatures gathered so far.
25+
26+
- `version` ++"byte"++ - the VAA Version
27+
- `guardian_set_index` ++"u32"++ - indicates which Guardian set is signing
28+
- `len_signatures` ++"u8"++ - the number of signatures stored
29+
- `signatures` ++"[]signature"++ - the collection of Guardian signatures
30+
31+
Where each `signature` is:
32+
33+
- `index` ++"u8"++ - the index of this Guardian in the Guardian set
34+
- `signature` ++"[65]byte"++ - the ECDSA signature
35+
36+
### Body
37+
38+
The body is _deterministically_ derived from an on-chain message. Any two Guardians processing the same message must derive the same resulting body. This requirement exists so that there is always a one-to-one relationship between VAAs and messages to avoid double-processing messages.
39+
40+
- `timestamp` ++"u32"++ - the timestamp of the block this message was published in
41+
- `nonce` ++"u32"++
42+
- `emitter_chain` ++"u16"++ - the id of the chain that emitted the message
43+
- `emitter_address` ++"[32]byte"++ - the contract address (Wormhole formatted) that called the Core Contract
44+
- `sequence` ++"u64"++ - the auto-incrementing integer that represents the number of messages published by this emitter
45+
- `consistency_level` ++"u8"++ - the consistency level (finality) required by this emitter
46+
- `payload` ++"[]byte"++ - arbitrary bytes containing the data to be acted on
47+
48+
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.
49+
50+
!!! note
51+
Because VAAs have no destination, they are effectively multicast. Any Core Contract on any chain in the network will verify them as authentic. If a VAA has a specific destination, relayers are entirely responsible for completing that delivery appropriately.
52+
53+
## Signatures
54+
55+
The body of the VAA is hashed twice with `keccak256` to produce the signed digest message.
56+
57+
```js
58+
--8<-- 'code/learn/infrastructure/VAAs/snippet-1.js'
59+
```
60+
61+
!!! note
62+
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.
63+
64+
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.
65+
66+
## Payload Types
67+
68+
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).
69+
70+
### Token Transfer
71+
72+
Tokens are transferred between chains using a lockup/mint and burn/unlock mechanism. Many bridges use such a basic method, but the implementation described leverages the generic message-passing protocol provided by Wormhole to handle the routing of lock and burn events across chains. This approach ensures that Wormhole's Token Bridge is chain-agnostic. The bridge can be rapidly integrated into any network with a Wormhole contract. Wormhole's generic message-passing does not require any program to send messages to understand the specific implementation details of other chains.
73+
74+
To transfer tokens from Chain A to Chain B, we must lock them on A and mint them on B. The tokens on A must be proven to be locked before the minting can occur on B. To facilitate this process, Chain A first locks the tokens and emits a message indicating that the locking has been completed. This message has the following structure and is referred to as a transfer message:
75+
76+
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `1` for a token transfer
77+
- `amount` ++"u256"++ - amount of tokens being transferred
78+
- `token_address` ++"u8[32]"++ - address on the source chain
79+
- `token_chain` ++"u16"++ - numeric ID for the source chain
80+
- `to` ++"u8[32]"++ - address on the destination chain
81+
- `to_chain` ++"u16"++ - numeric ID for the destination chain
82+
- `fee` ++"u256"++ - portion of amount paid to a relayer
83+
84+
This structure contains everything the receiving chain needs to learn about a lockup event. Once Chain B receives this payload, it can mint the corresponding asset.
85+
86+
Note that Chain B 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.
87+
88+
### Attestation
89+
90+
The Transfer event above needs an important detail added. While the program on Chain B can trust the message to inform it of token lockup events, it has no way of verifying the correct token is locked up. The address alone is a meaningless value to most users. To solve this, the Token Bridge supports token attestation.
91+
92+
For a token attestation, Chain A emits a message containing metadata about a token, which Chain B may use to preserve the name, symbol, and decimal precision of a token address.
93+
94+
The message format for this action is as follows:
95+
96+
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `2` for an attestation
97+
- `token_address` ++"[32]byte"++ - address of the originating token contract
98+
- `token_chain` ++"u16"++ - chain ID of the originating token
99+
- `decimals` ++"u8"++ - number of decimals this token should have
100+
- `symbol` ++"[32]byte"++ - short name of asset
101+
- `name` ++"[32]byte"++ - full name of asset
102+
103+
Attestations use a fixed-length byte array to encode UTF8 token name and symbol data.
104+
105+
!!! note
106+
Because the byte array is fixed length, the data contained may truncate multibyte Unicode characters.
107+
108+
When sending an attestation VAA, it is recommended to send the longest UTF-8 prefix that does not truncate a character and then right-pad it with zero bytes.
109+
110+
When parsing an attestation VAA, it is recommended to trim all trailing zero bytes and converting the remainder to UTF-8 via any lossy algorithm.
111+
112+
!!! note
113+
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.
114+
115+
Without knowing a token's decimal precision, Chain B cannot correctly mint the number of tokens when processing a transfer. For this reason, the Token Bridge requires an attestation for each token transfer.
116+
117+
### Token Transfer with Message
118+
119+
!!! note
120+
This VAA type is also referred to as a payload3 message or a Contract Controlled Transfer.
121+
122+
The Token Transfer with Message data structure is identical to the token-only data structure with the addition of a `payload` field containing arbitrary bytes. In this arbitrary byte field, an app may include additional data in the transfer to inform some application-specific behavior.
123+
124+
- `payload_id` ++"u8"++ - the ID of the payload. This should be set to `3` for a token transfer with message
125+
- `amount` ++"u256"++ - amount of tokens being transferred
126+
- `token_address` ++"u8[32]"++ - address on the source chain
127+
- `token_chain` ++"u16"++ - numeric ID for the source chain
128+
- `to` ++"u8[32]"++ - address on the destination chain
129+
- `to_chain` ++"u16"++ - numeric ID for the destination chain
130+
- `fee` ++"u256"++ - portion of amount paid to a relayer
131+
- `payload` ++"[]byte"++ - message, arbitrary bytes, app specific
132+
133+
### Governance
134+
135+
Governance VAAs don't have a `payload_id` field like the above formats; they're used to trigger some action in the deployed contracts (e.g., upgrade).
136+
137+
### Action Structure
138+
139+
Governance messages contain pre-defined actions, which can target the various Wormhole modules currently deployed on-chain. The structure contains the following fields:
140+
141+
- `module` ++"u8[32]"++ - contains a right-aligned module identifier
142+
- `action` ++"u8"++ - predefined governance action to execute
143+
- `chain` ++"u16"++ - chain the action is targeting. This should be set to `0` for all chains
144+
- `args` ++"any"++ - arguments to the action
145+
146+
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.
147+
148+
```js
149+
--8<-- 'code/learn/infrastructure/VAAs/snippet-2.js'
150+
```
151+
152+
### Actions
153+
154+
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:
155+
156+
- [Core governance actions](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0002_governance_messaging.md){target=\_blank}
157+
- [Token Bridge governance actions](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0003_token_bridge.md){target=\_blank}
158+
- [NFT Bridge governance actions](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0006_nft_bridge.md){target=\_blank}
159+
160+
## Lifetime of a Message
161+
162+
!!! note
163+
Anyone can submit the VAA to the target chain. The Guardians typically do not perform this step to avoid transaction fees. Instead, applications built on top of Wormhole can acquire the VAA via the Guardian RPC and make the submission in a separate flow.
164+
165+
With the concepts now defined, it is possible to illustrate what a full flow for message passing between two chains looks like. The following stages demonstrate each step of processing that the Wormhole network performs to route a message.
166+
167+
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
168+
2. **Signatures are aggregated** - 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
169+
3. **VAA submitted to target chain** - the VAA acts as proof that the Guardians have collectively attested the existence of the message payload; to complete the final step, the VAA itself is submitted (or relayed) to the target chain to be processed by a receiving contract
170+

0 commit comments

Comments
 (0)