Token Bridge Overview
The Token Bridge is the SupraNova application that moves assets between chains. The Token Bridge is a set of contracts on each EVM chain and a set of Move modules on SupraMVM. The Token Bridge sends every transfer as a HyperNova message, so the same verification protects transfers and Messaging.
How the Token Bridge moves assets
On the source chain, the Token Bridge locks the asset in a vault, or burns it if it is a wrapped token. On the destination chain, it mints the wrapped token, or releases the original asset from the vault. Which action applies depends on where the asset originates. See Token Transfer Models.
Transfer limits bound every transfer, and every transfer pays the service fee configured for its route on the source chain, which can be zero. See Fees. A relayer delivers the transfer, and the destination chain verifies it before the Token Bridge mints or releases anything.
Components on EVM chains
| Contract | Role |
|---|---|
TokenBridge | The entry point for senders and relayers. On a send, it checks the route and the token, gets the fee from FeeOperator, locks or burns the asset, and posts the transfer to Hypernova. On a delivery, it has Hypernova verify the message, then mints or releases the asset. |
TokenVault | Holds every asset locked on the chain. The vault wraps native currency first, so it holds ETH as WETH. Only the TokenBridge can lock or release, and the vault enforces the per-request limits and the global cap. |
FeeOperator | Calculates the fee for a transfer. It holds no funds. |
WrappedTokenFactory | Deploys the wrapped token of each asset that originates on another chain, and records which tokens are wrapped. |
WrappedToken | The ERC-20 implementation shared by every wrapped token, such as the SUPRA ERC-20 token. The TokenBridge mints it on delivery and burns it on a send. |
Components on SupraMVM
| Module | Role |
|---|---|
token_bridge_service | The entry point for senders and relayers. Its resource account signs the vault, mint and message calls. It enforces the wrapped-token limit and keeps the record of transfers delivered from Ethereum. |
token_vault | Holds every SupraMVM-native asset that is locked, such as SUPRA. Only token_bridge_service can lock or release, and the vault enforces the per-request limits and the global cap. |
fee_operator | Calculates the fee for a transfer from SupraMVM. It holds no funds. |
wrapped_token_deployer | Creates the wrapped fungible asset of each asset from another chain, such as supETH, and mints and burns it for token_bridge_service. |
token_bridge_codec | Encodes and decodes the Token Bridge’s messages. |
For addresses, see Contract Addresses. For the admin of each component, see Roles and Permissions.
Where funds are held
| Funds | EVM chains | SupraMVM |
|---|---|---|
| Locked assets | TokenVault | token_vault |
| Wrapped tokens | No vault: supply is minted and burned | No vault: supply is minted and burned |
| Service fees, less the relayer reward | TokenBridge | The resource account of token_bridge_service |
| Verification fees paid by relayers | Hypernova | hypernova_core |
What happens on each chain
| Stage | EVM chains | SupraMVM |
|---|---|---|
| Send | TokenBridge.sendTokens or sendNative gets the fee from FeeOperator, locks the asset in TokenVault or burns the WrappedToken, then calls Hypernova.postMessage. | token_bridge_service::send_tokens gets the fee from fee_operator, locks the asset in token_vault or burns the wrapped token, then calls hypernova_core_from_supra::post_message. |
| Delivery | A relayer calls TokenBridge.receiveTokensFromSupra, which has Hypernova verify the message, mints the WrappedToken or releases from TokenVault, and pays the relayer reward. | For a transfer from Ethereum, a relayer calls token_bridge_service::execute_optimistic_or_safe or execute_finality. On Testnet, the relayer calls their _v2 versions. hypernova_core verifies the message. For a transfer from SupraEVM, a relayer calls receive_tokens_from_sevm, and supra_hypernova_core verifies the message. The module then mints the wrapped token or releases the asset from token_vault, and pays the relayer reward. |
Each direction is described stage by stage in Cross-Chain Message Flow.
The contracts name the two sides of a transfer differently. On EVM chains, “inbound” means the sending side, as in
inboundTokenFee. On SupraMVM, “outbound” means the sending side, as in get_outbound_token_info.
Next steps
- Smart Contract Integration — send a transfer from code
- Quote Fees and Limits
- Track a Transfer