Every Tern swap starts with a quote and ends one of two ways: the user receives the tokens they asked for, or they get their deposit back. This page walks through what happens in between.

​
Who’s involved

​
The lifecycle of a cross-chain swap

  1. Quote. Your app creates a secret and asks for a quote, sending only a fingerprint of the secret (its hash). Solvers compete, and Tern returns the best offer.
  2. Deposit. The user deposits the tokens they’re selling on the source chain, from their wallet or by sending them to a deposit address. The deposit is locked to the secret’s fingerprint.
  3. Execution. Tern detects the deposit. The winning solver then locks the tokens the user is buying on the destination chain, under the same fingerprint.
  4. Settlement. Your app checks that the solver’s tokens are really there, then reveals the secret. Tern submits it on the destination chain, and the user receives their tokens. The secret is now public, and the solver uses it to collect the deposit.
  5. Refund. If anything stops the swap before settlement, nobody reveals the secret. Both sides get their funds back when the locks expire, or sooner if the solver declines.
The user signs one thing: the deposit. Everything else is handled by your app and Tern. The cross-chain guide shows each step in code.

​
Why a swap can’t half-finish

  • The user is paid first. The secret becomes public in the same transaction that pays the user. The solver can only collect the deposit after that.
  • Locks expire in a safe order. The solver’s lock expires about 4 hours after the quote, and the user’s at least an hour later. So the solver always has time to collect after paying, and the user always gets the deposit back if the swap stops.
  • No one can override the rules. The contracts have no owner and can’t be paused or upgraded. Funds can only go to the right person with the secret, or back to whoever sent them.
See Refunds for every way a swap can end without completing.

​
Same-chain swaps

When both tokens are on the same chain, there’s no solver and nothing to lock. The user sends one transaction to Tern’s swap contract, which trades through the best route Tern found across DEX aggregators. It checks the user gets at least the quoted minimum, or the whole transaction reverts and nothing moves. See Same-chain swaps.

​
Private swaps

On Starknet, users can swap from a shielded balance in the network’s privacy pool. Their wallet prepares the transaction, Tern submits it, and the output lands in a new shielded balance. Nothing on chain links the swap to the user’s account. See Private swaps.

​
What Tern can and can’t do

Tern makes swaps fast and convenient: it finds prices, watches the chains, and submits transactions so users don’t have to. It can’t take funds or send them anywhere else. If Tern went offline mid-swap, the swap would refund when its locks expire, and anyone can trigger those refunds. See Security.

Quotes and statuses

Prices, firm quotes, deadlines, and the statuses a swap moves through.

Escrow specification

The contracts and their rules, in full detail.