Skip to Content
SupraNova (Bridge)Smart Contract Integration

Smart Contract Integration

Wallets, dApps and exchanges can call the Token Bridge contracts directly instead of using the SupraNova application. This page states the rules that apply to every transfer, then shows how to send a transfer step by step. Each step has one tab for EVM chains (Ethereum and SupraEVM) and one for SupraMVM.

A TypeScript SDK and an Indexer REST API are planned. Until they are released, integrate with the contracts directly, as described here.

What to call on each chain

Source chainContractSendQuote the fee
Ethereum or SupraEVMTokenBridge (proxy)sendTokens, sendNativeinboundTokenFee
SupraMVMtoken_bridge_service modulesend_tokens<CoinType>get_fee_for_amount

For addresses, see Contract Addresses. On EVM chains, always call the proxy.

Rules for every transfer

  • Destination chain. Pass the destination’s chain ID, as listed in Supported Networks. The route must be registered for the token.
  • Receiver. On EVM chains, receiver is a bytes32. For a SupraMVM destination, pass the recipient’s 32-byte account address. On SupraMVM, receiver_address is the recipient’s 20-byte EVM address.
  • Amount and decimals. Give amounts in the token’s own base units on the source chain. The Token Bridge normalizes them to the destination chain’s maximum token decimals before it sends the transfer. On EVM chains, the Token Bridge never takes the remainder (dust), and refunds it for native currency.
  • Fees. The Token Bridge deducts the service fee, which includes the relayer reward, from the amount on the source chain. The recipient receives the amount after fees. See Fees.
  • Limits. The amount must fall within the asset’s transfer limits. On SupraMVM and SupraEVM Devnet, a wrapped token cannot be sent until its wrapped-token limit is configured.
  • Approval. On EVM chains, approve the TokenBridge proxy to spend the amount of an ERC-20 token before calling sendTokens.
  • Payload. The send functions on every chain accept a payload. The Token Bridge carries the payload unchanged to the destination and includes it in the delivery event, but does not act on it.
  • Finality. A relayer can deliver a transfer only after its block meets the finality rules of its direction.

After the source transaction is confirmed, the asset is locked or burned, and you cannot cancel the transfer. Check the destination chain ID and the receiver before you send.

Before you begin

The examples use Foundry’s cast on EVM chains and the Supra CLI on SupraMVM. You can make the same calls from any library or from a contract.

export RPC_URL=<SOURCE_CHAIN_RPC_URL> export PRIVATE_KEY=<SENDER_PRIVATE_KEY> export TOKEN_BRIDGE=<TOKEN_BRIDGE_PROXY> export TOKEN=<TOKEN_ADDRESS> export DEST_CHAIN_ID=<DESTINATION_CHAIN_ID> export RECEIVER=<RECIPIENT_AS_BYTES32> # for SupraMVM: the 32-byte account address export AMOUNT=<AMOUNT_IN_TOKEN_BASE_UNITS> export PAYLOAD=0x0000000000000000000000000000000000000000000000000000000000000000

Send a transfer

Quote the fee

cast call $TOKEN_BRIDGE \ "inboundTokenFee(uint64,uint256,address)(uint64,uint64,uint64,uint256)" \ $DEST_CHAIN_ID $AMOUNT $TOKEN --rpc-url $RPC_URL

The call returns finalAmount, feeCutToService and relayerReward, normalized to the destination chain’s maximum token decimals (maxTokenDecimals), and dust in the token’s own decimals. finalAmount is what the recipient receives. The call reverts if the token is not registered for the destination chain. For native currency, pass the address returned by nativeToken() as the token.

Prepare the token

For an ERC-20 token, approve the TokenBridge proxy to spend the amount. Skip this step for native currency.

cast send $TOKEN "approve(address,uint256)" $TOKEN_BRIDGE $AMOUNT \ --rpc-url $RPC_URL --private-key $PRIVATE_KEY

Send

For an ERC-20 token, call sendTokens:

cast send $TOKEN_BRIDGE \ "sendTokens(uint64,address,uint256,bytes32,bytes32)" \ $DEST_CHAIN_ID $TOKEN $AMOUNT $RECEIVER $PAYLOAD \ --rpc-url $RPC_URL --private-key $PRIVATE_KEY

For native currency, call sendNative and pass the amount as the transaction value:

cast send $TOKEN_BRIDGE \ "sendNative(uint64,bytes32,bytes32)" \ $DEST_CHAIN_ID $RECEIVER $PAYLOAD \ --value $AMOUNT --rpc-url $RPC_URL --private-key $PRIVATE_KEY

The TokenVault locks tokens native to the source chain. The TokenBridge burns wrapped tokens, such as the SUPRA ERC-20 token. The TokenVault wraps native currency and locks it.

Track the transfer

The transaction emits MessagePosted from the Hypernova contract, with the TokenBridge proxy as caller. Its messageId identifies the transfer.

A relayer delivers the transfer to the destination chain, and the sender has nothing more to do. To follow the delivery, see Track a Transfer.

Send from an EVM contract

A contract can send on behalf of its users. The TokenBridge pulls the tokens from its caller, so the contract must hold the tokens and approve the TokenBridge first. The transfer records the contract as its sender.

import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; interface ITokenBridge { function sendTokens(uint64 chainId, address token, uint256 amount, bytes32 receiver, bytes32 payload) external; function sendNative(uint64 chainId, bytes32 receiver, bytes32 payload) external payable; function inboundTokenFee(uint64 chainId, uint256 amount, address token) external view returns (uint64 finalAmount, uint64 feeCutToService, uint64 relayerReward, uint256 dust); } contract BridgeSender { using SafeERC20 for IERC20; ITokenBridge public immutable tokenBridge; constructor(ITokenBridge tokenBridge_) { tokenBridge = tokenBridge_; } function bridge(uint64 destChainId, address token, uint256 amount, bytes32 receiver) external { // The contract must already hold `amount` of `token`. forceApprove also works with tokens // such as USDT, whose approve returns no value. IERC20(token).forceApprove(address(tokenBridge), amount); tokenBridge.sendTokens(destChainId, token, amount, receiver, bytes32(0)); } }
Last updated on