token bridge sdk page #280
Conversation
ilariae
added
A0 - New Content
|
|
||
| Before you can start interacting with Wormhole's Token Bridge, you need to set up your development environment by installing the Wormhole SDK and configuring your project to use it. This section guides you through the necessary steps to get started. | ||
|
|
||
| 1. **Install the Wormhole SDK** |
There was a problem hiding this comment.
| 1. **Install the Wormhole SDK** | |
| 1. **Install the Wormhole SDK** - ensure you have `Node.js` and `npm` installed on your machine. Then, install the Wormhole SDK packages: |
Let’s unite the sentences like this, as they are united on the other content pages, to maintain consistency.
Please remove any space left
|
|
||
| 1. **Install the Wormhole SDK** | ||
|
|
||
| First, ensure you have `Node.js` and `npm` installed on your machine. Then, install the Wormhole SDK packages: |
There was a problem hiding this comment.
| First, ensure you have `Node.js` and `npm` installed on your machine. Then, install the Wormhole SDK packages: |
|
|
||
| 2. **Import the necessary modules** | ||
|
|
||
| In your TypeScript or JavaScript file (e.g., index.ts), import the required classes and functions from the SDK: |
There was a problem hiding this comment.
| In your TypeScript or JavaScript file (e.g., index.ts), import the required classes and functions from the SDK: |
| - `@wormhole-foundation/sdk-base` - Base SDK provides foundational types and interfaces | ||
|
|
||
| 2. **Import the necessary modules** | ||
|
|
| - `@wormhole-foundation/wormhole-sdk` - core Wormhole SDK for interacting with the Wormhole network | ||
| - `@wormhole-foundation/sdk-base` - Base SDK provides foundational types and interfaces | ||
|
|
||
| 2. **Import the necessary modules** |
There was a problem hiding this comment.
| 2. **Import the necessary modules** | |
| 2. **Import the necessary modules** in your TypeScript or JavaScript file (e.g., index.ts), import the required classes and functions from the SDK: |
Same as above
There was a problem hiding this comment.
Agree. But just make sure to add a hyphen between the title and description
There was a problem hiding this comment.
Also wrap index.ts in back ticks
| // Import other necessary modules as needed | ||
| ``` | ||
|
|
||
| 3. **Initialize the TokenBridge Interface** |
| The [Verifiable Action Approval (VAA)](/docs/learn/infrastructure/vaas/){target=\_blank} is a crucial component in the Wormhole Token Bridge workflow. It proves that the Wormhole Guardians have observed and approved a specific action (such as attesting a token or initiating a transfer) on the source chain. This approval is necessary to execute actions on the destination chain. | ||
|
|
||
| ### Essential Steps to Retrieve a VAA | ||
|
|
There was a problem hiding this comment.
This step should be rewritten like the ones above.
Co-authored-by: Lucas Malizia <131050418+0xlukem@users.noreply.github.com>
Co-authored-by: Lucas Malizia <131050418+0xlukem@users.noreply.github.com>
There was a problem hiding this comment.
This tutorial covers most of the topics mentioned on this page. Maybe you could reference it somewhere as a "Practical Implementation" of the Token Bridge.
|
|
||
| ## Introduction | ||
|
|
||
| Wormhole's Token Bridge offers a solution that enables token transfers across blockchain networks using a lock-and-mint mechanism. Leveraging Wormhole's [generic message-passing protocol](/docs/learn/fundamentals/introduction/){target=\_blank}, the Token Bridge allows assets to move across supported blockchains without native token swaps. The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain, making the transfer process efficient and chain-agnostic. This approach is highly scalable and doesn't require each blockchain to understand the token transfer logic of other chains, making it a robust and flexible solution for multichain dApps. Additionally, the Token Bridge supports [Contract Controlled Transfers](/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. |
There was a problem hiding this comment.
This liknk returns 404: /docs/learn/fundamentals/introduction/
There was a problem hiding this comment.
ah yeah i havent fixed all links for the new ia yet
|
|
||
| Wormhole's Token Bridge offers a solution that enables token transfers across blockchain networks using a lock-and-mint mechanism. Leveraging Wormhole's [generic message-passing protocol](/docs/learn/fundamentals/introduction/){target=\_blank}, the Token Bridge allows assets to move across supported blockchains without native token swaps. The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain, making the transfer process efficient and chain-agnostic. This approach is highly scalable and doesn't require each blockchain to understand the token transfer logic of other chains, making it a robust and flexible solution for multichain dApps. Additionally, the Token Bridge supports [Contract Controlled Transfers](/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. | ||
|
|
||
| This page demonstrates how to practically interact with Wormhole's Token Bridge, leveraging the Wormhole SDK and various contract interfaces to send tokens across chains, attest new tokens, and attach arbitrary payloads for contract-controlled transfers. For more details on how the Token Bridge works, refer to the [Token Bridge](/docs/learn/messaging/token-bridge/){target=\_blank} or [Native Token Transfers](/docs/learn/messaging/native-token-transfers/overview/#token-bridge){target=\_blank} pages in the Learn section. |
There was a problem hiding this comment.
Token Bridge and NTT links are returning 404
|
|
||
| 1. **Install the Wormhole SDK** | ||
|
|
||
| First, ensure you have `Node.js` and `npm` installed on your machine. Then, install the Wormhole SDK packages: |
There was a problem hiding this comment.
You could mention npm and Node.js in the prerequisites sections. We usually do this in tutorials.
| ```ts | ||
| // Replace with your blockchain provider setup | ||
| // A provider connects your application to the blockchain network (e.g., via JSON-RPC, WebSocket) | ||
| const provider = /* Initialize your blockchain provider here */; |
There was a problem hiding this comment.
It would be nice to show how to get the provider and signer here. The SDK uses types, so if the provider or signer does not match the type, creating the instance of the token bridge won't work, and it will throw an error.
| !!!note | ||
| - Emitter address - typically the Token Bridge contract address on the source chain | ||
| - Sequence number - extracted from the transaction receipt by parsing the emitted events/logs | ||
| - API endpoint - ensure you're using the correct Wormhole API endpoint corresponding to your network |
There was a problem hiding this comment.
Where do we get the API endpoint? maybe share a link to the API endoints here
|
|
||
| The attestation process doesn't require you to manually input token details like name, symbol, or decimals. The Token Bridge contract retrieves these values from the token contract itself when you call the `attestToken()` method. | ||
|
|
||
| The `createAttestation()` method is part of the TokenBridge interface provided by the Wormhole SDK, which you initialized in the [setup and installation section](docs/build/contract-integrations/token-bridge/#setup-and-installation){target=\_blank} above. This method abstracts the underlying smart contract call to `ITokenBridge.attestToken()`, simplifying the attestation process. |
There was a problem hiding this comment.
Link returns 404: docs/build/contract-integrations/token-bridge/#setup-and-installation
|
|
||
| To attest a token, follow these steps: | ||
|
|
||
| 1. **Create an instance of the Token Bridge contract** - ensure you have initialized the `tokenBridge` instance as shown in the [Setup and Installation section](/docs/build/contract-integrations/token-bridge/#setup-and-installation){target=\_blank} |
| console.log('Attestation submitted on target chain:', submitTx.hash); | ||
| ``` | ||
|
|
||
| !!!note |
There was a problem hiding this comment.
There is a practical implementation on how to create wrapped assets in the tutorials. Maybe you could reference it somewhere in this section: https://wormhole.com/docs/tutorials/by-product/wormhole-sdk/tokens-via-token-bridge/#check-and-create-wrapped-tokens
There was a problem hiding this comment.
Sorry, I know you have quite a few reviews on this, so there might be some overlapping comments. But I just wanted to get this review out of the way.
Things to consider:
- The main focus should be on the SDK, the underlying contract information is a nice touch and definitely helpful, but should be treated as secondary information
- Action-oriented headers
- Sections can be tightened up and made more concise
- Snippets should be in the
.snippets/codedirectory because when we implement prettier, we'll be running it on all files there - Saw some grammar issues. Please make sure when this is ready again that you've run it through grammarly
| @@ -0,0 +1,340 @@ | |||
| --- | |||
| title: Get Started with Token Bridge | |||
| 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. | |||
There was a problem hiding this comment.
| 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. | |
| description: Integrate Wormhole's Token Bridge with the TypeScript SDK for multichain token transfers with a lock-and-mint mechanism and cross-chain asset management. |
| @@ -0,0 +1,340 @@ | |||
| --- | |||
| title: Get Started with Token Bridge | |||
There was a problem hiding this comment.
| title: Get Started with Token Bridge | |
| title: Token Bridge Transfers with TypeScript SDK |
If someone's searching token bridge, this should be able to differentiate from other docs pages about token bridge
| - 'VAAs and Protocol Messages': 'vaas-protocols.md' | ||
| - 'Token Bridge': 'token-bridge-sdk.md' |
There was a problem hiding this comment.
Ah we need to figure out the plan for the SDK section. I don't think we should just add this here. I think we need like a "Transfers" section or something like that. There's pieces that need to be pulled out of the wormhole-sdk.md page and made into separate pages because that page is just too long and overwhelming
| To interact with the Wormhole Token Bridge, you must ensure you have the addresses and chain IDs for the Wormhole Core and Token Bridge contracts on the networks you want to work with. | ||
|
|
||
| - [The address of the Token Bridge Core Contract](/docs/build/reference/contract-addresses/#token-bridge) on the chains you're working with | ||
| - [The Wormhole chain ID](/docs/build/reference/chain-ids/) of the chains you're you're targeting for token transfers |
There was a problem hiding this comment.
The sentence leading into the bulleted items is just repeating the bulleted items. Should be more concise
|
|
||
| ## Introduction | ||
|
|
||
| Wormhole's Token Bridge offers a solution that enables token transfers across blockchain networks using a lock-and-mint mechanism. Leveraging Wormhole's [generic message-passing protocol](/docs/learn/fundamentals/introduction/){target=\_blank}, the Token Bridge allows assets to move across supported blockchains without native token swaps. The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain, making the transfer process efficient and chain-agnostic. This approach is highly scalable and doesn't require each blockchain to understand the token transfer logic of other chains, making it a robust and flexible solution for multichain dApps. Additionally, the Token Bridge supports [Contract Controlled Transfers](/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. |
There was a problem hiding this comment.
| Wormhole's Token Bridge offers a solution that enables token transfers across blockchain networks using a lock-and-mint mechanism. Leveraging Wormhole's [generic message-passing protocol](/docs/learn/fundamentals/introduction/){target=\_blank}, the Token Bridge allows assets to move across supported blockchains without native token swaps. The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain, making the transfer process efficient and chain-agnostic. This approach is highly scalable and doesn't require each blockchain to understand the token transfer logic of other chains, making it a robust and flexible solution for multichain dApps. Additionally, the Token Bridge supports [Contract Controlled Transfers](/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. | |
| Wormhole's [Token Bridge](/docs/learn/transfers/token-bridge/){target=\_blank} offers a solution that enables token transfers across blockchain networks using a lock-and-mint mechanism. Leveraging Wormhole's [generic message-passing protocol](/docs/learn/introduction/){target=\_blank}, the Token Bridge allows assets to move across supported blockchains without [native token swaps](/docs/learn/transfers/native-token-transfers/overview/#token-bridge){target=\_blank}. | |
| The bridge locks tokens on the source chain and mints them as wrapped assets on the destination chain, making the transfer process efficient and chain-agnostic. This approach is highly scalable and doesn't require each blockchain to understand the token transfer logic of other chains, making it a robust and flexible solution for multichain dApps. | |
| Additionally, the Token Bridge supports [Contract-Controlled Transfers](/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. |
Breaking larger paras into smaller ones helps out in terms of readability
There was a problem hiding this comment.
We've referred to "Token Message with Payload" more commonly as "Contract-Controlled Transfers" or "Contract Controlled Transfers" without a hyphen. We should clean this up and be consistent with how we refer to this because for someone who doesn't really know, they could click on the link and if it says something different, that could be confusing. Even if the first thing under that section is a note saying it's referred to as contract-controlled
|
|
||
| The examples assume you have set up a project with TypeScript, the Wormhole SDK, RPC endpoints, and private keys configured. | ||
|
|
||
| ### Attesting a Token |
There was a problem hiding this comment.
This section could be improved. It's a lot of text and then lists and then notes with lists. And there is some repetition as well. I'd like to see you clean it up and make it more concise and easier to follow
| Under the hood, calling `tokenBridge.createAttestation()` uses Wormhole’s core method: | ||
|
|
||
| - The `createAttestation` method is defined in the Wormhole SDK's [`TokenBridge` interface](https://github.com/wormhole-foundation/wormhole-sdk-ts/blob/main/core/definitions/src/protocols/tokenBridge/tokenBridge.ts#L188){target=\_blank} | ||
| - On-chain, the `attestToken` method can be found in `bridge/Bridge.sol` and is part of the [`ITokenBridge` interface](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/bridge/Bridge.sol#L38){target=\_blank} | ||
| - The logic for creating the attestation VAA can be found in `bridge/Bridge.sol`, specifically in the [`attestToken`](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/bridge/Bridge.sol#L38){target=\_blank} function |
There was a problem hiding this comment.
Maybe the under the hood stuff can be in an expandable section titled "Explore how it works under the hood" or something? Because it's not essential information that they need to know to be able to use the SDK
|
|
||
| Attesting a new token involves providing its metadata and setting the `payload_id` to `2`. This ensures the wrapped token on the destination chain preserves the original token's properties and consistency across chains. For more details, see the [Attestation section](/docs/learn/infrastructure/vaas/#attestation){target=\_blank}. | ||
|
|
||
| The attestation process doesn't require you to manually input token details like name, symbol, or decimals. The Token Bridge contract retrieves these values from the token contract itself when you call the `attestToken()` method. |
There was a problem hiding this comment.
What is the attestToken method? This hasn't really been introduced yet. Is it part of the SDK? We need to prioritize the SDK functions in this guide and then supplementally provide the underlying functions. It can be really confusing to go back and forth between the SDK functions and under the hood functions
| - Ensure the token contract on the source chain implements standard ERC-20 metadata functions (`decimals()`, `symbol()`, `name()`) | ||
| - Call `attestToken()` (via the Wormhole SDK or directly on the contract) for the token address | ||
| - You don't have to put the token details anywhere in your code. If the token contract is a standard ERC-20, the Token Bridge will read its metadata | ||
| - The attestation may fail or produce incomplete metadata if the token does not implement these standard functions. In that case, you must ensure the token is ERC-20 compliant |
There was a problem hiding this comment.
Some of this can and should be embedded into the steps. Especially if it's important information that they'll need to know at a specific step.
Something to keep in mind is that you should only use notes for information that isn't essential but can be valuable
| ## Portal Bridge | ||
|
|
||
| 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. |
There was a problem hiding this comment.
This is available in other places. I don't think it makes sense to have it here
Description
Added the token bridge sdk page to the new ia, this page needs another good review before adding it
Checklist
wormhole-mkdocsrepo