Skip to content

Commit 96b7119

Browse files
ilariaeIlaria Enache0xlukem
authored
Bring token bridge build into new ia (#279)
* adds token bridge build page in the new ai and fixes links * Update build/transfers/token-bridge.md Co-authored-by: Lucas Malizia <131050418+0xlukem@users.noreply.github.com> * Update build/transfers/token-bridge.md Co-authored-by: Lucas Malizia <131050418+0xlukem@users.noreply.github.com> --------- Co-authored-by: Ilaria Enache <ilaria@Host-009.homenet.telecomitalia.it> Co-authored-by: Lucas Malizia <131050418+0xlukem@users.noreply.github.com>
1 parent 7d99922 commit 96b7119

File tree

2 files changed

+218
-1
lines changed

2 files changed

+218
-1
lines changed

‎build/transfers/.pages

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ nav:
44
- connect
55
- native-token-transfers
66
- settlement
7-
# TODO: Token Bridge
7+
- 'Token Bridge': 'token-bridge.md'
88
- 'CCTP Bridge': 'cctp.md'

‎build/transfers/token-bridge.md

+217
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
title: Get Started with Token Bridge
3+
description: Learn how to integrate Wormhole's Token Bridge for seamless multichain token transfers with a lock-and-mint mechanism and cross-chain asset management.
4+
---
5+
6+
# Token Bridge
7+
8+
## Introduction
9+
10+
Wormhole's Token Bridge enables seamless cross-chain token transfers using a lock-and-mint mechanism. The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain. Additionally, the Token Bridge supports [contract-controlled transfers (transfers with messages)](/docs/learn/infrastructure/vaas/#token-transfer-with-message){target=\_blank}, where arbitrary byte payloads can be attached to the token transfer, enabling more complex chain interactions.
11+
12+
This page outlines the core contract methods needed to integrate Token Bridge functionality into your smart contracts. To understand the theoretical workings of the Token Bridge, refer to the [Token Bridge](/docs/learn/transfers/token-bridge/){target=\_blank} page in the Learn section.
13+
14+
## Prerequisites
15+
16+
To interact with the Wormhole Token Bridge, you'll need the following:
17+
18+
- [The address of the Token Bridge contract](/docs/build/reference/contract-addresses/#token-bridge){target=\_blank} on the chains you're working with
19+
- [The Wormhole chain ID](/docs/build/reference/chain-ids/){target=\_blank} of the chains you're targeting for token transfers
20+
21+
## How to Interact with Token Bridge Contracts
22+
23+
The primary functions of the Token Bridge contracts revolve around:
24+
25+
- **Attesting a token** - registering a new token for cross-chain transfers
26+
- **Transferring tokens** - locking and minting tokens across chains
27+
- **Transferring tokens with a payload** - including additional data for contract-controlled transfers
28+
29+
### Attest a token
30+
31+
Suppose a token has never been transferred to the target chain before transferring it cross-chain. In that case, its metadata must be registered so the Token Bridge can recognize it and create a wrapped version if necessary.
32+
33+
The attestation process doesn't require you to manually input token details like name, symbol, or decimals. Instead, the Token Bridge contract retrieves these values from the token contract itself when you call the `attestToken()` method.
34+
35+
```solidity
36+
function attestToken(
37+
address tokenAddress,
38+
uint32 nonce
39+
) external payable returns (uint64 sequence);
40+
```
41+
42+
??? interface "Parameters"
43+
44+
`tokenAddress` ++"address"++
45+
46+
The contract address of the token to be attested.
47+
48+
---
49+
50+
`nonce` ++"uint32"++
51+
52+
An arbitrary value provided by the caller to ensure uniqueness.
53+
54+
??? interface "Returns"
55+
56+
`sequence` ++"uint64"++
57+
58+
A unique identifier for the attestation transaction.
59+
60+
When `attestToken()` is called, the contract emits a Verifiable Action Approval (VAA) containing the token's metadata, which the Guardians sign and publish.
61+
62+
You must ensure the token is ERC-20 compliant. If it does not implement the standard functions, the attestation may fail or produce incomplete metadata.
63+
64+
### Transfer Tokens
65+
66+
Once a token is attested, a cross-chain token transfer can be initiated following the lock-and-mint mechanism. On the source chain, tokens are locked (or burned if they're already a wrapped asset), and a VAA is emitted. On the destination chain, that VAA is used to mint or release the corresponding amount of wrapped tokens.
67+
68+
Call `transferTokens()` to lock/burn tokens and produce a VAA with transfer details.
69+
70+
```solidity
71+
function transferTokens(
72+
address token,
73+
uint256 amount,
74+
uint16 recipientChain,
75+
bytes32 recipient,
76+
uint256 arbiterFee,
77+
uint32 nonce
78+
) external payable returns (uint64 sequence);
79+
```
80+
81+
??? interface "Parameters"
82+
83+
`token` ++"address"++
84+
85+
The address of the token being transferred.
86+
87+
---
88+
89+
`amount` ++"uint256"++
90+
The amount of tokens to be transferred.
91+
92+
---
93+
94+
`recipientChain` ++"uint16"++
95+
The Wormhole chain ID of the destination chain.
96+
97+
---
98+
99+
`recipient` ++"bytes32"++
100+
The recipient's address on the destination chain.
101+
102+
---
103+
104+
`arbiterFee` ++"uint256"++
105+
Optional fee to be paid to an arbiter for relaying the transfer.
106+
107+
---
108+
109+
`nonce` ++"uint32"++
110+
A unique identifier for the transaction.
111+
112+
??? interface "Returns"
113+
114+
`sequence` ++"uint64"++
115+
116+
A unique identifier for the transfer transaction.
117+
118+
Once a transfer VAA is obtained from the Wormhole Guardian network, the final step is to redeem the tokens on the destination chain. Redemption verifies the VAA's authenticity and releases (or mints) tokens to the specified recipient. To redeem the tokens, call `completeTransfer()`.
119+
120+
```solidity
121+
function completeTransfer(bytes memory encodedVm) external;
122+
```
123+
124+
??? interface "Parameters"
125+
126+
`encodedVm` ++"bytes memory"++
127+
128+
The signed VAA containing the transfer details.
129+
130+
!!!note
131+
- The Token Bridge normalizes token amounts to 8 decimals when passing them between chains. Make sure your application accounts for potential decimal truncation
132+
- The VAA ensures the integrity of the message. Only after the Guardians sign the VAA can it be redeemed on the destination chain
133+
134+
### Transfer tokens with payload
135+
136+
While a standard token transfer moves tokens between chains, a transfer with a payload allows you to embed arbitrary data in the VAA. This data can be used on the destination chain to execute additional logic—such as automatically depositing tokens into a DeFi protocol, initiating a swap on a DEX, or interacting with a custom smart contract.
137+
138+
Call `transferTokensWithPayload()` instead of `transferTokens()` to include a custom payload (arbitrary bytes) with the token transfer.
139+
140+
```solidity
141+
function transferTokensWithPayload(
142+
address token,
143+
uint256 amount,
144+
uint16 recipientChain,
145+
bytes32 recipient,
146+
uint32 nonce,
147+
bytes memory payload
148+
) external payable returns (uint64 sequence);
149+
```
150+
151+
??? interface "Parameters"
152+
153+
`token` ++"address"++
154+
155+
The address of the token being transferred.
156+
157+
---
158+
159+
`amount` ++"uint256"++
160+
The amount of tokens to be transferred.
161+
162+
---
163+
164+
`recipientChain` ++"uint16"++
165+
The Wormhole chain ID of the destination chain.
166+
167+
---
168+
169+
`recipient` ++"bytes32"++
170+
The recipient's address on the destination chain.
171+
172+
---
173+
174+
`nonce` ++"uint32"++
175+
A unique identifier for the transaction.
176+
177+
---
178+
179+
`payload` ++"bytes memory"++
180+
Arbitrary data payload attached to the transaction.
181+
182+
??? interface "Returns"
183+
184+
`sequence` ++"uint64"++
185+
186+
A unique identifier for the transfer transaction.
187+
188+
After initiating a transfer on the source chain, the Wormhole Guardian network observes and signs the resulting message, creating a Verifiable Action Approval (VAA). You'll need to fetch this VAA and then call `completeTransferWithPayload()`.
189+
190+
Only the designated recipient contract can redeem tokens. This ensures that the intended contract securely handles the attached payload. On successful redemption, the tokens are minted (if foreign) or released (if native) to the recipient address on the destination chain. For payload transfers, the designated contract can execute the payload's logic at this time.
191+
192+
```solidity
193+
function completeTransferWithPayload(bytes memory encodedVm) external returns (bytes memory);
194+
```
195+
196+
??? interface "Parameters"
197+
198+
`encodedVm` ++"bytes memory"++
199+
200+
The signed VAA containing the transfer details.
201+
202+
??? interface "Returns"
203+
204+
`bytes memory`
205+
206+
The extracted payload data.
207+
208+
## Source Code References
209+
210+
For a deeper understanding of the Token Bridge implementation and to review the actual source code, please refer to the following links:
211+
212+
- [Token Bridge contract](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/bridge/Bridge.sol){target=\_blank}
213+
- [Token Bridge interface](https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/main/src/interfaces/ITokenBridge.sol){target=\_blank}
214+
215+
## Portal Bridge
216+
217+
A practical implementation of the Wormhole Token Bridge can be seen in [Portal Bridge](https://portalbridge.com/){target=\_blank}, which provides an easy-to-use interface for transferring tokens across multiple blockchain networks. It leverages the Wormhole infrastructure to handle cross-chain asset transfers seamlessly, offering users a convenient way to bridge their assets while ensuring security and maintaining token integrity.

0 commit comments

Comments
 (0)