Skip to main content
MetaToken is Caldera’s omnichain token standard built on top of the Metalayer message-passing stack. It provides hub-and-spoke contracts that maintain a single canonical supply, deterministic addresses across every domain, and configurable security controls for high-value transfers.

​
Architecture Overview

  • MetaERC20Hub (canonical chain): Locks the native asset, tracks escrowed balances, and dispatches mint instructions to spokes. Receives UnlockRequest messages to release canonical tokens. Maintains a validator-reviewed buffer for high-value relays.
  • MetaERC20Spoke (remote chains): Mints and burns the synthetic representation of the token. Routes transfers either directly to another spoke or back through the hub depending on security thresholds.
  • MetaERC20Base: Shared logic that handles transfer bookkeeping, deterministic transfer IDs, domain registration, and dispatching through IMetalayerRouter.
All contracts are upgradeable via AccessControlDefaultAdminRulesUpgradeable and inherit Metalayer’s interchain security guarantees.

​
Message Types

MetaToken messages are encoded via MetaERC20MessageStruct and fall into one of four categories:
TypeDescription
MintRequestSpoke mints synthetic tokens to the recipient. Default for spoke-to-spoke transfers.
UnlockRequestHub releases canonical tokens to the recipient after a spoke burn.
SecurityRelaySpoke-to-spoke transfer exceeding the configured threshold. Buffered on the hub for manual validator approval.
AdminActionReserved for emergency reissue or administrative overrides.
Each message carries the transfer ID, timestamp, source token decimals, destination domain, recipient, and raw amount. Transfer IDs are deterministic hashes of sender, amount, and destination to guarantee uniqueness across the network.

​
Transfer Flows

​
Hub → Spoke

  1. User deposits canonical tokens into the Hub (MetaERC20Hub).
  2. Hub locks funds and emits a MintRequest to the destination spoke.
  3. Spoke mints the synthetic supply to the recipient after converting decimals if necessary.

​
Spoke → Hub

  1. User calls transferRemote on the spoke with the hub domain and target recipient.
  2. Spoke burns the synthetic tokens and emits an UnlockRequest to the hub.
  3. Hub validates the request against locked balance and releases canonical tokens.

​
Spoke → Spoke (Standard)

  1. Spoke burns the source-chain synthetic tokens and generates a MintRequest for the destination spoke.
  2. Destination spoke mints the requested amount to the recipient address.

​
Spoke → Spoke (High Value)

  1. If amount >= securityThreshold, the spoke emits a SecurityRelay targeting the hub instead of the destination spoke.
  2. Hub buffers the transfer and emits SecurityRelayBuffered until an operator with VALIDATOR_ROLE reviews the request.
  3. Upon approval, the hub re-dispatches the transfer as a MintRequest to the destination spoke.
This layered approach lets token issuers tailor latency vs. security for different transfer sizes.

​
On-Chain Integration

Tokens expose a single entry point for user transfers: 
import {TypeCasts} from "@hyperlane-xyz/core/contracts/libs/TypeCasts.sol";
import {MetaERC20Spoke} from "@metalayer/contracts/token/MetaERC20Spoke.sol";

using TypeCasts for address;

MetaERC20Spoke spoke = MetaERC20Spoke(0xYourToken);

bytes32 transferId = spoke.transferRemote{
  value: gasFee
}(
  33139,                               // recipient domain (Apechain)
  address(0xRecipient).addressToBytes32(),
  1_000_000 * 10 ** spoke.decimals()   // amount in local units
);
transferRemote internally:
  1. Validates the destination domain and recipient.
  2. Records the transfer for replay protection and TTL-based pruning.
  3. Dispatches the encoded MetaERC20 message via metalayerRouter.dispatch using the spoke’s configured finality state and gas limit.
To determine the required gasFee, call the spoke’s quoteDispatchFee() helper (available in the deployed package) or invoke router.quoteDispatch directly with the token’s configured gas limit and finality state.

​
Roles & Governance

ContractRolePurpose
HubDEFAULT_ADMIN_ROLEOwns upgrades and role assignment.
HubADMIN_ROLEManages domain mappings, gas limits, and TTL windows.
HubVALIDATOR_ROLEApproves or rejects buffered SecurityRelay transfers.
SpokeDEFAULT_ADMIN_ROLEOwns upgrades and role assignment.
SpokeADMIN_ROLEUpdates thresholds, domain mappings, and gas configuration.
Issuers typically maintain the admin roles while Caldera maintains the router roles. Validators can be rotated to expand or tighten manual review policies.

​
Operational Controls

  • TTL Window: Transfers older than the configured TTL can be pruned to reclaim storage.
  • Security Threshold: Adjustable per spoke; setting to zero forces all transfers through the hub, while high values favour low-latency spoke-to-spoke routing.
  • Gas Limits: Each deployment specifies a max gas limit enforced when dispatching through the router to prevent runaway costs.
  • Emergency Procedures: Hub admins can perform MetaERC20AdminUnlock to release stuck funds; spoke admins can MetaERC20AdminReissue synthetic balances if a destination chain requires remediation.

​
Deployment Information

  • Deterministic addresses and per-network configuration will be published alongside each rollout; reach out to Caldera for the latest deployment matrix.
  • All deployments share the same message format and can be upgraded without breaking deterministic transfer IDs, provided the storage layout gaps are respected.
For architectural diagrams and example flows, refer back to the Omnichain Tokens solution guide.