Universal Token Bridge

A bridge moves a token from one chain to another: units are removed on the source chain and the same amount appears on the destination chain. Done right, nothing is created from nothing. Smart Engines builds one bridge engine with per-chain adapters, instead of a new bridge per chain pair. Today that engine covers one pair of chains, Hedera and XRPL, in two forms:

The HSUITE bridge

Moves HSUITE from Hedera to XRPL, where it is HST. It is one-way and burn-first, and it is the only way HST is ever minted.

Lock-wallet bridges

Let any Hedera HTS token be wrapped on XRPL. They are built and switched off: each validator has to opt in, and nothing moves until a threshold of validators has.

What holds it back

Each piece of the bridge has its own switch, and every one is off by default. No network turns any of them on.

Switch	Default	While it is off
The HSUITE bridge’s mint executor	off	The HSUITE bridge’s mint executor drives nothing
The HSUITE bridge’s settings (bridge id, source token, its treasury, XRPL launch ledger)	empty	No validator installs its HSUITE evidence check, so every validator refuses every bridge mint
The HSUITE bridge’s activation date	unset on every network	No removal can back a mint. The date can only be set by a software release, never by a setting
The claim registry topic and its fee	empty	No claim resolves. The executor cannot be switched on without the registry’s fee
The lock-wallet executor	off	Set per validator. A validator with it off mints and unlocks nothing for a lock-wallet bridge, refuses to activate one, and withholds its signature share from every lock-wallet mint and unlock. Nothing moves until a threshold of validators has each turned it on. It cannot be turned on without the claim registry and its fee
Treasury funding for lock wallets	off	The Protocol Treasury pays nothing toward lock-wallet accounts. It also needs the lock-wallet executor on, and a Treasury rule that permits bridge funding
Public exposure of the bridge API	off	The bridge routes are not reachable from outside the cluster

On top of the switches, the HSUITE bridge needs two things done first: a network whose genesis mints zero HST, and the Hedera HSUITE token’s supply and wipe keys moved to a key the validators hold. The activation date is set only after both.

The HSUITE bridge (Hedera → XRPL)

Genesis mints zero HST, on every network, mainnet included. HST enters XRPL only through this bridge, one-for-one against HSUITE removed from circulation on Hedera, and only after that removal. That gives an invariant anyone can check from the two public ledgers: the HST the bridge has minted equals the HSUITE it has removed. Genesis runs once per network, so this holds from each network’s next genesis.

sequenceDiagram
    autonumber
    participant H as Holder
    participant HED as Hedera
    participant REG as HCS claim registry
    participant EX as Mint executor
    participant V as Every validator's gate
    participant X as XRPL

    H->>HED: removal of HSUITE (wipe or burn), memo commits to the claim.<br/>The holder's account pays the fee, which is its consent
    H->>REG: register the claim (anyone may)
    EX->>HED: scan for removals carrying a bridge memo
    EX->>V: ask for a signature on a mint of exactly the removed amount
    V->>HED: re-read the removal (own endpoint)
    V->>REG: earliest valid registration for this removal
    V->>X: issuer's next Sequence, no earlier mint for this claim
    V-->>EX: signature share, or withheld
    EX->>X: HST minted 1:1 to the committed XRPL address

1. The removal comes first

The validators’ threshold key, which will hold HSUITE’s wipe and supply keys, removes the HSUITE on Hedera. A holder’s HSUITE is removed with a TOKENWIPE; the token treasury’s own HSUITE is removed with a TOKENBURN. The account being debited must be the transaction’s fee payer. Hedera runs no transaction without its payer’s signature, so a removal cannot happen without that account’s consent. Every validator’s sign gate checks the same thing before it co-signs: the bound source token, an amount above zero, payer equal to the debited account, and a memo that is a well-formed claim commitment.

The memo commits to the bridge, the claimant and the XRPL address (see The claim memo), so nobody can redirect the HST to another address.

2. The claim is registered on HCS

Each claim is registered on the HCS claim registry, a public Hedera topic with no submit key: anyone may write to it, and each message pays the topic’s fee. A registration counts only if the removal’s own memo commits to exactly what it says, so registering somebody else’s removal cannot send it anywhere else. For each removal, the earliest valid registration wins, and every validator reads the same topic in the same order. The executor registers a claim itself when its cluster already holds a verified port request for it.

A flood of junk messages cannot halt the bridge. A registration only counts if it was written inside its claim’s window (from 60 seconds before the removal), and the reader pages through the topic into one shared, persisted index instead of loading the whole topic. Junk still costs the flooder the topic’s fee for every message, and can still delay claims while the reader pages through it.

3. Every validator checks for itself

The mint executor holds no authority. It finds work by scanning the Hedera chain for removals that carry a bridge memo. One validator at a time drives the mints, rotating hourly. It takes a lease on each claim, records each signed attempt before submitting it, and resubmits the same bytes after a crash.

A mint needs a threshold of signature shares, and each validator releases its share only after its own reads confirm the claim. These checks include:

the bridge id is the one for this genesis: hsuite-<HST issuer address>;
the removal is re-read from this validator’s own mirror node, and it was paid by the debited account. A known shared public endpoint is refused (a test network may accept one explicitly, never mainnet), and a validator withholds its share while a peer announces reading from the same server;
the removal is no older than the bridge’s activation date;
the mint is for exactly the removed amount, at HSUITE’s full four-decimal precision. An amount HST cannot hold exactly is refused, never rounded;
the claim’s registration is the earliest valid one;
the mint uses the issuer’s next Sequence, and no validated mint already carries this claim’s key in its InvoiceID.

No person, DAO vote or validator quorum can authorise a mint, and once the bridge is enabled, anyone can bridge. A mint happens only because a threshold of validators each confirmed the removal on its own.

4. Caps and one mint per removal

Mints are capped at 1 billion HST per transaction, 2 billion per 24 hours and 50 billion in total (the whole HSUITE supply). The caps are fixed in the HST issuer’s rule for the next genesis, so no vote can raise them. One removal backs at most one mint: the claim key comes from the removal transaction, every mint carries it as its InvoiceID, and XRPL validates at most one transaction per Sequence.

5. When a mint cannot land

The bridge is one-way: nothing is ever refunded on Hedera. A claim stays open until its mint lands. Before signing, the executor checks that the XRPL address can receive HST: the account exists, has an HST trust line with room for the amount, needs no destination tag, and accepts payments from the issuer. A claim that keeps failing is parked with an alert (2 failed transactions, 5 signed attempts, or about a day without a signature), and a removal that can never back a claim is parked at once.

An operator can re-drive a parked claim. That returns it to the queue with fresh budgets; it skips no check, cannot approve or size a mint, and is not reachable from outside the cluster.

6. Conservation is reconciled

A reconciler compares the two ledgers: every mint is backed by a removal, no removal backs two mints, minted equals removed, no mint comes before its removal, and the HST outstanding on XRPL is at most what was minted. It detects only: a violation raises metrics and an alert, and nothing pauses automatically. Outstanding HST can sit below the amount minted, because HST burned on XRPL (including HST’s transfer fee, which is burned on every transfer) leaves circulation.

The claim memo

A removal or a burn is public: anyone can see it on the chain. So the transaction itself has to say who it is for. It must carry a short memo that commits to the claim. The validators read that memo from the transaction on the chain, never from a request, and refuse the claim unless it matches exactly. This stops someone who watches the chain from claiming your transaction to their own address.

What the memo commits to. Four things, hashed together with SHA-256:

the leg: port (source chain to destination chain) or return (back again);
the bridge id;
the claimant: your account on the chain the transaction is on;
the payout address on the other chain.

It does not commit to the amount: the amount is part of the same signed transaction and is read from the chain. It has no nonce and no expiry.

What it looks like. The text hsuite-bridge/v1: followed by 64 lower-case hex characters, 81 bytes in all. For a port on bridge bridge-hedera-xrpl-1767225600000 by Hedera account 0.0.999, paying out to XRPL address rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY, the memo is:

hsuite-bridge/v1:db38c5d1ff1367261359babe9448eb3c76c569f2479188ae6da8a2f97f11a5bb

Where it goes.

Chain	Where	What to put there
Hedera	The transaction memo	The memo text, exactly
XRPL	One entry in the transaction’s `Memos`	`MemoType` = hex of `hsuite-bridge`; `MemoData` = hex of the memo text; no `MemoFormat`

On XRPL, memos of other types (a wallet’s own tag, for example) are ignored. Two hsuite-bridge entries in one transaction are refused.

A claim is refused when:

the memo is missing, or spelled any other way: upper-case letters in the hash, extra spaces or characters, or another version;
the memo commits to a different bridge, leg, claimant or payout address;
the transaction is older than the bridge’s activation.

A refused claim records nothing. So if someone else submits your transaction first and is refused, you can still claim it.

Set the memo before you sign. The memo is part of the signed transaction and cannot be added afterwards. The published SDK does not include memo builders or any bridge support while the bridge routes are not public. The hsuite CLI has no bridge command.

Creating and governing a bridge

A bridge for any other token goes through the generic lifecycle routes: create, PATCH rules, activate, pause and close. Like every bridge route, they are reachable only inside the cluster today. A wallet session alone is refused (403). Every lifecycle call needs one of two proofs:

Owner proof
DAO proof

Owner proof. A short-lived intent (10 minutes at most), signed with the source token’s admin key as the chain reports it. The intent binds the action, the bridge, the exact request body and a random nonce. On Hedera the admin key must be a single key. A token whose admin key is a key list or a threshold key uses the DAO route instead.

Each proof works once, across the whole network. create, activate, pause and close are each recorded as one message on an HCS bridge directory, threshold-signed by the validators. Every validator reads the directory from its own mirror node. A record counts only if its proof checks out at the record’s consensus time and no earlier record already used it. When two records conflict, the first valid one wins. A bridge’s id is derived from its create proof, so one proof names one bridge on every cluster.

An owner proof for a token on any chain other than Hedera cannot be recorded in the directory, so such a bridge uses the DAO proof for every recorded action.

Pause and close. A pause can be lifted by a later activate whose proof was issued after the pause. A close is final. Each validator’s lock-wallet gates read the directory themselves, so a pause recorded through any cluster stops every validator from co-signing that bridge’s lock-wallet mints and unlocks, and a close stops its mints. Each cluster’s own copy of the bridge record, which the claim routes check, follows the directory when that cluster next reads it. There is no single-validator emergency pause. PATCH rules is not recorded in the directory: it changes one cluster’s copy only, and it is refused on a lock-wallet bridge if it would change that bridge’s anchored terms.

A lock-wallet close is drain-only. A closed lock-wallet bridge takes no new deposits, but its holders can still return: every validator’s return gate co-signs an unlock for a closed bridge as it does for an active one, so a close does not strand the tokens locked behind wrapped tokens still in circulation. A deposit made after the close is never minted: the mint executor parks it with an alert, and it is not refunded. A paused bridge holds its returns until it is active again. Any other close, the HSUITE bridge’s included, stays final.

Trust levels. A bridge records a trust level at creation: owner-rekeyed, owner-verified or community. Nothing reads it for any limit. owner-rekeyed is recorded whenever the bridge is created in rekey mode; nothing checks on chain that the keys were handed over.

Lock-wallet bridges (Hedera HTS → XRPL)

A lock-wallet bridge is for a token the validators do not control: holders deposit it into a lock wallet on Hedera, and an equal wrapped token (an XRPL issued currency) is minted on XRPL. Returning burns the wrapped token and releases the original. Version 1 supports one pair only: a Hedera HTS token to XRPL.

What is built:

Creation. Refused, before the proof is spent, for any other pair, for a source token with a KYC key or freeze_default, or when fewer than 3 validators are attested. Creation provisions the lock wallet: a Hedera account under a threshold key the validators hold, created through the validators’ standard entity path (DKG plus a rule published on HCS).
Anchored terms. The bridge’s terms are written into the lock wallet’s rule on HCS when it is created, and can never change: the source token’s decimals, the XRPL currency it mints, per-transaction, daily and total mint caps, and an optional minimum deposit (at most the per-transaction cap). Validators read the terms from HCS, never from one cluster’s database.
Issuer crowning. The wrapped token’s XRPL issuer is the first matching issuer registration on the HCS tokens topic, in HCS order. Every validator reads the same order, so all of them agree on the same issuer. Later registrations are ignored. Every candidate must carry exactly the wallet’s anchored terms, so whoever registers first decides only who issues, never on what terms. An issuer that cannot be finalised is marked stalled after 24 hours. The remedy is to close the bridge and create a new one.
Port gate. Each validator co-signs a wrapped mint only on its own reads: a single deposit of the source token into the wallet, paid by the depositor, carrying the port memo to the mint’s destination, made after the issuer was registered, at least the minimum deposit, for exactly the deposited amount, registered on the claim registry, and with no earlier mint for the same deposit.
Return gate. Each validator co-signs an unlock only on its own reads: a burn of the wrapped token to the crowned issuer, carrying the return memo, registered on the claim registry, for exactly the burned amount, paid out from the lock wallet, while the bridge is active or closed. One burn can unlock once.
Mint executor. It mints for deposits, with the same lease, attempt and park machinery as the HSUITE executor.
Unlock executor. It finds burns of the wrapped token on XRPL itself, binds each to its registered return claim as the return gate will, and unlocks it out of the lock wallet through the validators’ threshold key. Each unlock’s Hedera transaction id is fixed by its claim, in one of 64 time slots over about 30 days after the burn, and a later slot is signed only once the earlier ones are proven empty, so one burn unlocks at most once. A burn that can never unlock is parked with its reason, and the operator is alerted while returns are at risk: the bridge is paused or unreadable, or a return’s last slot closes within 7 days.
Arming, per validator. Both executors run, and a validator activates a lock-wallet bridge and co-signs its mints and unlocks, only with its own lock-wallet switch on, which is off by default. One validator cannot arm the bridge for the network: a mint or an unlock needs a threshold of validators that each opted in.
Treasury funding. A lock wallet pays its own unlock fees, at most 1 hbar each. The Protocol Treasury can top it up, and fund the XRPL reserve of the bridge’s issuer account, as an ordinary Treasury payment that every validator confirms from its own reads, within a per-payment bound and the Treasury’s own caps. This funding has its own switch, off by default, and it also needs a Treasury rule that permits bridge funding, which the current genesis rule set adds.

What is not built, and the limits:

Off on every network. No network has opted in, so no lock-wallet bridge is active anywhere.
Returns are registered by the holder. The holder registers its own return claim on the claim registry; no cluster registers it for them. A burn that is not unlocked by its last slot, about 30 days after the burn, can no longer be unlocked.
Funding is off. With Treasury funding switched off, nothing tops a lock wallet up. While it holds less than one fee, returns wait.
No refunds. A deposit that never mints is not refunded. Nothing can be transferred out of the wallet except an unlock of the source token, so any other token sent to its address stays there.

Other `rekey` bridges: a claim ledger only

A bridge in rekey mode assumes the validators hold the token’s supply and wipe keys. For any rekey bridge other than the HSUITE bridge, the engine only records claims. A port verifies the source burn on the chain and records a pending claim, but no executor mints for it, and no return is released.

These checks run before any claim is recorded:

A source transaction is mandatory

A claim backed only by an amount the caller typed is impossible.

The verified amount wins

The validators re-read the transaction on its chain and use that amount. A request for a different amount is rejected. “1.50” and “1.5” count as equal.

Only a real supply reduction counts as a burn

On Hedera only TOKENBURN or TOKENWIPE is accepted, never a plain transfer.

The claim is bound

The signed-in wallet must be the claimant, on the chain of the transaction, and the memo must commit to the claim.

Only fresh transactions count

A transaction older than the bridge’s activation is refused.

One claim per source transaction, across every bridge, within one cluster

Clusters keep separate databases. Across clusters, only a mint is made unique, by the HCS claim registry and every validator’s gate.

Decimals are converted exactly

Hedera amounts are integer base units and XRPL amounts are decimal strings. The bridge converts with exact digit arithmetic, never floating point. A port or return for an amount the receiving chain cannot hold exactly is refused, never rounded: a fraction of a base unit, or an XRPL amount beyond 15 significant digits.

A per-bridge total limit

A port that would push a bridge past its totalLimit is refused. The per-transaction and daily limits a bridge may declare are not enforced on this path.

Built and not available

“Built” means written and merged. Nothing in this table is switched on for any network.

Piece	Status
Genesis mints zero HST	Built
HSUITE removal leg: wipe or burn, paid by the debited account	Built, not armed
HCS claim registry: earliest valid registration wins, flood-resistant	Built; no topic provisioned
Each validator re-reads the evidence from its own endpoint before co-signing	Built, not armed
HSUITE mint executor, caps, parking and operator re-drive	Built, switched off
Conservation reconciler (detects; does not pause)	Built, not installed on any network
Lifecycle authorization: owner proof or DAO proof, single use network-wide	Built; routes not public
HCS bridge directory: pause and close across the network	Built; routes not public
Lock-wallet creation, anchored terms, issuer crowning, port and return gates, mint and unlock executors, drain-only close	Built; off until a threshold of validators each opts in
Treasury funding of a lock wallet’s unlock fees and its issuer’s reserve	Built, switched off
Minting for `rekey` bridges other than HSUITE	Not available: claim ledger only
Refunds of any kind	Not available. The HSUITE bridge is one-way by design
Chain pairs other than Hedera ↔ XRPL	Not available: the burn verifier reads only Hedera and XRPL
Caps by trust level	Not available: the trust level is recorded, never read
Automatic pause on a conservation violation	Not available: the reconciler only alerts
Public bridge routes, a CLI command, and bridge support in the published SDK	Not available
Cross-chain operator payouts through the bridge	Not available
A security audit of the bridge	Not done

Why a universal bridge

Per-pair bridges (industry norm)	The Smart Engines design
New code per chain pair	One chain-neutral engine; adapters do the per-chain work
New review per pair	One set of checks to review for every pair
Often a small committee of keys signs	Each validator signs only on its own reads of the source chain
Supply reconciled privately, if at all	Conservation is checkable from the public ledgers

Hacked bridges have cost the industry billions, largely because each one is a separate attack surface. Today the engine covers one pair, Hedera and XRPL. Each new chain needs its own verifier and adapters before it can join.

Bridges in the economy

The HSUITE migration from Hedera to XRPL is the HSUITE bridge described above (see Settlement & migration). Paying operator rewards across chains through the bridge is not available (see Staking & node-runners).

Next steps

Settlement & migrationThe HSUITE migration.

The HSUITE tokenThe token itself.

Staking & node-runnersOperator rewards.