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 chain | Contract | Send | Quote the fee |
|---|---|---|---|
| Ethereum or SupraEVM | TokenBridge (proxy) | sendTokens, sendNative | inboundTokenFee |
| SupraMVM | token_bridge_service module | send_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,
receiveris abytes32. For a SupraMVM destination, pass the recipient’s 32-byte account address. On SupraMVM,receiver_addressis 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
TokenBridgeproxy to spend the amount of an ERC-20 token before callingsendTokens. - 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.
EVM chains
- The
TokenBridgeproxy address for the source chain, from Contract Addresses. - The token address, from Supported Tokens, and the destination chain ID, from Supported Networks.
- An account on the source chain with the token and enough native currency for gas.
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=0x0000000000000000000000000000000000000000000000000000000000000000Send a transfer
Quote the fee
EVM chains
cast call $TOKEN_BRIDGE \
"inboundTokenFee(uint64,uint256,address)(uint64,uint64,uint64,uint256)" \
$DEST_CHAIN_ID $AMOUNT $TOKEN --rpc-url $RPC_URLThe 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
EVM chains
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_KEYSend
EVM chains
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_KEYFor 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_KEYThe 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
EVM chains
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));
}
}Related
- Quote Fees and Limits — read every fee and limit from the contracts
- Track a Transfer
- Troubleshooting — when a call reverts or aborts