Ilariae/token bridge

build/contract-integrations/.pages

@@ -3,7 +3,7 @@ nav:
  - index.md
  - 'Wormhole Relayer': 'wormhole-relayers.md'
  - 'Core Contracts': 'core-contracts.md'
-#  - 'Token Bridge': 'token-bridge.md'
+ - 'Token Bridge': 'token-bridge.md'
  - 'CCTP': 'cctp.md'
  - 'Cosmos Gateway' : 'gateway.md'
  - native-token-transfers

build/contract-integrations/token-bridge.md

@@ -0,0 +1,301 @@
+---
+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.
+---
+
+# 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.
+
+This page will walk you through the essential methods and events of the Token Bridge contracts, providing you with the knowledge needed to integrate them into your cross-chain applications. For more details on how the Token Bridge works, refer to the [Token Bridge](/docs/learn/messaging/token-nft-bridge/){target=\_blank} or [Native Token Transfers](/docs/learn/messaging/native-token-transfers/overview/#token-bridge){target=\_blank} pages in the Learn section and the [Token Bridge Whitepaper](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0003_token_bridge.md){target=\_blank}.
+
+## Prerequisites
+
+To interact with the Wormhole Token Bridge, you'll need the following:
+
+- **SDK Installation** - Ensure the Wormhole SDK is installed in your project. You can install it via npm or yarn:
+```sh
+npm install @wormhole-foundation/sdk
+```
+- [The address of the Token Bridge Core Contract](/docs/build/reference/contract-addresses#core-contracts) 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
+- **Token attestation** - the token you wish to transfer must be compatible with the destination chain as a wrapped asset. For tokens that do not exist on the target chain, you must attest their details, including metadata like `name`, `symbol`, `decimals`, and `payload_id`, which must be set to `2` for an attestation. This ensures that the wrapped token on the destination chain preserves the original token’s properties. The attestation process records the token's metadata on the target chain to ensure consistency across chains. See the [Attestation section](/docs/learn/infrastructure/vaas/#attestation){target=\_blank} for more details and all the required metadata fields
+
+## How to Interact with the Token Bridge Contracts
+
+The Wormhole Token Bridge SDK offers a set of TypeScript types and functions that make it easy to interact with the bridge. The key functionality revolves around:
+
+- **Token transfers** - locking tokens on the source chain and minting wrapped tokens on the destination chain
+- **Attestations** - submitting metadata about a token to other chains for wrapping
+- **Verifying wrapped assets** - checking if a token is wrapped and retrieving its original chain and asset details
+
+### Check If a Token Is Wrapped
+
+To verify whether a token is a wrapped asset (i.e., a token from another chain that has been bridged), use the `isWrappedAsset` function.
+
+```ts
+isWrappedAsset(nativeAddress: TokenAddress<C>): Promise<boolean>;
+```
+
+??? interface "Parameters"
+
+    `nativeAddress` ++"TokenAddress<C>"++
+
+    The address of the token you want to check.
+
+??? interface "Returns"
+
+    `true` ++"Promise<boolean>"++
+
+    True if the token is a wrapped version of a foreign token.
+
+### Retrieve the Original Asset of a Wrapped Token
+
+If a token is wrapped, you can retrieve its original asset and the chain it originated from using the `getOriginalAsset` function.
+
+```ts
+getOriginalAsset(nativeAddress: TokenAddress<C>): Promise<TokenId<Chain>>;
+```
+
+??? interface "Parameters"
+
+    `nativeAddress` ++"TokenAddress<C>"++
+
+    The wrapped token's address.
+
+??? interface "Returns"
+
+    `Promise` ++"<TokenId<Chain>>"++
+
+    The original asset's token ID and the chain it belongs to.
+
+### Get a Token's Universal Address
+
+The UniversalAddress represents a token in a cross-chain manner, allowing you to handle the same token on different chains. Use the `getTokenUniversalAddress` function to retrieve this address.
+
+```ts
+getTokenUniversalAddress(token: NativeAddress<C>): Promise<UniversalAddress>;
+```
+
+??? interface "Parameters"
+
+    `token` ++"TokenAddress<C>"++
+
+    The wrapped token's address.
+
+??? interface "Returns"
+
+    `Promise` ++"<TokenId<Chain>>"++
+
+    The original asset's token ID and the chain it belongs to.
+
+### Create a Token Attestation
+
+To transfer a token between chains, its metadata must be attested first. Use the `createAttestation` function to generate an attestation message for the token.
+
+```ts
+createAttestation(
+  token: TokenAddress<C>,
+  payer?: AccountAddress<C>
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `token` ++"TokenAddress<C>"++
+
+    The address of the token you want to attest.
+
+    `payer` ++"AccountAddress<C>"++
+
+    (Optional) The account paying for the transaction.
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+### Submit a Token Attestation
+
+Once you have an attestation message (VAA), you can submit it using the `submitAttestation` function to create the wrapped token on the target chain.
+
+```ts
+submitAttestation(
+  vaa: TokenBridge.AttestVAA,
+  payer?: AccountAddress<C>
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `vaa` ++"TokenBridge.AttestVAA"++
+
+    The attestation VAA that contains the token metadata.
+
+    `payer` ++"AccountAddress<C>"++
+
+    (Optional) The account paying for the transaction.
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+### Initiate a Token Transfer
+
+You can use the' transfer' function to transfer tokens from one chain to another. This function locks the tokens on the source chain and generates a transfer message.
+
+```ts
+transfer(
+  sender: AccountAddress<C>,
+  recipient: ChainAddress,
+  token: TokenAddress<C>,
+  amount: bigint,
+  payload?: Uint8Array
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `sender` ++"AccountAddress<C>"++
+
+    The account initiating the transfer.
+
+    `recipient` ++"ChainAddress"++
+
+    The recipient's address on the destination chain.
+
+    `token` ++"TokenAddress<C>"++
+
+    The token being transferred.
+
+    `amount` ++"bigint"++
+
+    The amount of the token to transfer.
+
+    `payload` ++"Uint8Array"++
+
+    (Optional) A custom payload attached to the transfer
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+### Redeem a Token Transfer
+
+After transferring tokens between chains, the recipient can redeem the transfer using the `redeem` function. This function mints the wrapped tokens on the destination chain or unlocks them if they were previously locked.
+
+```ts
+redeem(
+  sender: AccountAddress<C>,
+  vaa: TokenBridge.TransferVAA,
+  unwrapNative?: boolean
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `sender` ++"AccountAddress<C>"++
+
+    The account redeeming the transfer.
+
+    `vaa` ++"TokenBridge.TransferVAA"++
+
+    The transfer VAA that contains the details of the token lockup on the source chain.
+
+    `unwrapNative` ++"boolean"++
+
+    (Optional) Whether to unwrap the native token if it is a wrapped asset.
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+## Automatic Token Bridge
+
+The `AutomaticTokenBridge` interface offers additional functionality for automatic token transfers, including automatic redemption on the destination chain. This makes the transfer process more efficient by removing the need for manual redemption.
+
+### Initiate an Automatic Transfer
+
+To initiate a token transfer that includes automatic redemption on the destination chain, use the `transfer` method from the `AutomaticTokenBridge` interface.
+
+```ts
+transfer(
+  sender: AccountAddress<C>,
+  recipient: ChainAddress,
+  token: TokenAddress<C>,
+  amount: bigint,
+  nativeGas?: bigint
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `sender` ++"AccountAddress<C>"++
+
+    The account initiating the transfer.
+
+    `recipient` ++"ChainAddress"++
+
+    The recipient's address on the destination chain.
+
+    `token` ++"TokenAddress<C>"++
+
+    The token being transferred.
+
+    `amount` ++"bigint"++
+
+    The amount of the token to transfer.
+
+    `nativeGas` ++"bigint"++
+
+    (Optional) The amount of native gas to include for the transfer.
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+### Manually Redeem a Transfer
+
+In rare cases where automatic redemption fails, you can manually redeem the transfer using the `AutomaticTokenBridge`'s `redeem` function.
+
+!!! note
+    This function should _only_ be used if it is necessary to take over some stalled transfer.
+
+```ts
+redeem(
+  sender: AccountAddress<C>,
+  vaa: AutomaticTokenBridge.VAA
+): AsyncGenerator<UnsignedTransaction<N, C>>;
+```
+
+??? interface "Parameters"
+
+    `sender` ++"AccountAddress<C>"++
+
+    The account redeeming the transfer.
+
+    `vaa` ++"AutomaticTokenBridge.VAA"++
+
+    The transfer VAA to redeem.
+
+??? interface "Returns"
+
+    `AsyncGenerator` ++"<UnsignedTransaction<N, C>>"++
+
+    An asynchronous generator that produces transactions to sign and send.
+
+
+## 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.

learn/messaging/token-nft-bridge.md

@@ -7,15 +7,63 @@ description: Learn about Wormhole's Token and NFT Bridge for cross-chain transfe
 
 ## Token Bridge
 
-!!! note
-    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](/docs/learn/infrastructure/vaas/#attestation){target=\_blank} the token details on the target chain.
+Transferring tokens across blockchain networks is challenging due to the lack of interoperability. Maintaining token properties such as value, name, and precision while ensuring security during transfers often requires complex and costly solutions like liquidity pools or native swaps, which can introduce inefficiencies and risks.
 
-The Token Bridge contract allows token transfers between blockchains through a lock and mint mechanism, using the [Core Contract](/docs/learn/infrastructure/core-contracts/){target=\_blank} with a specific [payload](/docs/learn/infrastructure/vaas/#token-transfer){target=\_blank} to pass information about the transfer. 
+Wormhole’s Token Bridge addresses these challenges by providing a decentralized protocol for seamless cross-chain token transfers through a lock-and-mint mechanism. Using Wormhole’s message-passing protocol, the Token Bridge allows standards-compliant tokens, like ERC-20 on Ethereum or SPL on Solana, to be transferred between different blockchains while preserving their original attributes.
 
-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](/docs/learn/infrastructure/vaas/#token-transfer-with-message){target=\_blank}.
+Offering a more efficient, scalable, and secure alternative to traditional solutions, the Token Bridge ensures that assets retain their properties across multiple blockchain ecosystems. Additionally, it supports flexible features like [Contract Controlled Transfer](/docs/learn/infrastructure/vaas/#token-transfer-with-message){target=\_blank}, enabling custom interactions by allowing tokens to carry additional data for smart contract integration on the destination chain.
+
+This page introduces the core concepts and functions of Wormhole’s Token Bridge, explaining how it operates, its key features, and how it enables secure and efficient cross-chain token transfers.
+
+### How Does It Work?
+
+At the core of the Token Bridge lies the lock-and-mint mechanism, which uses the [Core Contract](/docs/learn/infrastructure/core-contracts/){target=\_blank} with a specific [payload](/docs/learn/infrastructure/vaas/#token-transfer){target=\_blank} to pass information about the transfer. Tokens on the source chain are locked, and wrapped tokens are minted on the destination chain. This approach guarantees that token transfers are secure and consistent, ensuring that token properties such as name, symbol, and decimal precision are preserved across chains.
+
+Before a token can be transferred to a new chain, the token’s metadata must be [attested](/docs/learn/infrastructure/vaas/#attestation){target=\_blank}. This process registers the token details (such as decimals and symbol) on the destination chain, enabling the creation of wrapped assets.
 
 While the [Core Contract](/docs/learn/infrastructure/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.
 
+In addition to standard token transfers, the Token Bridge supports [Contract Controlled Transfer](/docs/learn/infrastructure/vaas/#token-transfer-with-message){target=\_blank}. This functionality allows users to attach additional data to token transfers, enabling more complex interactions with smart contracts on the destination chain. For instance, a token transfer can include a payload that triggers specific actions, such as interacting with a decentralized exchange (DEX) or automated market maker (AMM).
+
+### Token Transfer Flow
+
+The transfer process is simple yet secure, involving a few key steps:
+
+1. **Attestation** - first, a token's metadata is attested on the source chain, ensuring that its properties are consistent across chains
+2. **Locking** - on the source chain, the native token is locked in a custody account
+3. **Message emission** - a message detailing the transfer is sent through Wormhole’s guardian network, which verifies the transfer and signs the message
+4. **Verification and Minting** - on the destination chain, the transfer message is verified, and wrapped tokens are minted, or native tokens are released from custody
+
+### Key Features of the Token Bridge
+
+The Token Bridge creates wrapped versions when tokens are transferred to a different chain. These wrapped assets represent the locked tokens on the source chain and allow users to interact with them on the destination chain. This mechanism ensures seamless functionality without needing liquidity pools or native token swaps.
+
+The Token Bridge employs a universal token representation that is compatible with various virtual machine (VM) data types. This allows the tokens to interact with decentralized applications (dApps) across different chains without issues related to differing token standards.
+
+### Message and Payload Structure
+
+To facilitate cross-chain communication, the Token Bridge uses specialized payloads that carry the necessary information for token transfers and attestations. These payloads ensure that the correct tokens are minted or unlocked on the destination chain.
+
+- `Transfer` - this payload initiates the transfer of tokens, either by minting wrapped tokens or releasing locked tokens
+- `TransferWithPayload` - in addition to transferring tokens, this payload carries additional data, allowing integration with smart contracts or dApps on the target chain
+- `AssetMeta` - before a token can be transferred for the first time, this payload is used to attest to the token’s metadata, including decimals, symbol, and name
+- `RegisterChain` - register the token bridge contract (emitter address) for a foreign chain
+- `UpgradeContract` - upgrade the contract
+
+Each payload type is designed to serve a specific function in the token transfer process, ensuring that the bridge operates efficiently and securely.
+
+One of the key challenges in cross-chain token transfers is maintaining the correct token precision. The Token Bridge addresses this using the `AssetMeta` payload to store token metadata. Before transferring a token to a new chain, metadata such as its decimal precision, name, and symbol must be attested. The bridge ensures token amounts are truncated to a maximum of 8 decimals, guaranteeing compatibility with chains that may not support higher decimal precision. For example, an 18-decimal token on Ethereum will be represented with only eight decimals on the destination chain, simplifying integration with various decentralized applications.
+
+### Security and Authorization
+
+The Token Bridge uses an emitter chain and address authorization system to verify the validity of messages. Each token bridge endpoint is registered on its respective chain, ensuring only trusted contracts can send or receive transfer messages.
+
+The [Wormhole guardian network](/docs/learn/infrastructure/guardians/#guardian-network){target=\_blank} plays a critical role in verifying each transfer and ensuring that the message is signed and relayed securely between chains.
+
+### Portal Bridge
+
+A real-world example of Wormhole's Token Bridge in action is the [Portal Bridge](https://portalbridge.com/){target=\_blank}, which provides users with a simple interface to transfer tokens across multiple blockchains. Using the Wormhole infrastructure, Portal Bridge guarantees secure and seamless cross-chain transfers, making it easier for users to move assets between different blockchain ecosystems.
+
 ## NFT Bridge
 
 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.