How a swap works

Every QuipSwap trade settles through one contract, Omnibus. This page describes the lifecycle exactly as that contract enforces it: commit, claim and reclaim. The claim step is also called execute; the order book labels it Settle, and on chain the function is claim.

The secret, the lock and the swap ID

A swap is coordinated by a hashlock. The party that proposes the swap generates a random 32-byte secret and publishes only its hash:

lock = keccak256(secret)

claim derives the lock from the secret it is given, so nobody can settle a swap without knowing the secret. The contract never checks who holds it.

Swap state is stored under a swap ID that binds the lock to the negotiated terms of both sides:

swapId = keccak256(lock ‖ digestTermsCanonically(party, counterparty))

The canonical digest hashes both sides in sorted order, so the ID is the same whichever side is passed first. An unrelated pairing that reuses an observed lock gets its own slot and cannot block or alter another swap. Read it on chain with swapId(lock, party, counterparty).

Terms: one struct per side

Each side of a swap is a Terms struct:

Each Asset has a type (Native, ERC20, ERC721 or ERC1155), a target contract (zero for native), an id (ERC-721 and ERC-1155 only) and an amount. The contract rejects terms that break any of these rules:

• One to 20 assets per side.
• Non-zero recipient and reclaimRecipient, and a non-zero chainId.
• A non-zero amount on every asset, ERC-721 included.
• Native assets carry a zero target and zero id. ERC-20 assets carry a non-zero target and zero id. ERC-721 and ERC-1155 assets carry a non-zero target; token id 0 is valid.
• Within a side, commitmentDeadline < claimDeadline < reclaimRelease, and reclaimRelease below the maximum uint256.

Proposer and taker

The two sides are not symmetric, and nothing in the struct labels them. The side with the earlier commitmentDeadline is the proposer: it generates the secret, commits first and reveals first. The other side is the taker: it commits second and claims second, using the secret the proposer revealed.

In a cross-chain swap the secret holder must be the proposer. A taker who held the secret could withhold its own commitment and still claim the proposer’s leg, and the contract cannot see the other chain to prevent it.

The deadline schedule

At every commit the contract checks that the six deadlines of the two sides strictly interleave, proposer first:

P.commitmentDeadline < T.commitmentDeadline < P.claimDeadline
  < T.claimDeadline < P.reclaimRelease < T.reclaimRelease

Any other ordering reverts with DisordedDeadlines. The interleave produces one action window per step. Every window is half-open, [lower, upper): the lower bound is included and the upper bound is excluded, so exactly one window accepts a shared boundary instant.

Three consequences follow:

1. The taker can only commit after the proposer’s commit window has closed, so it commits against a leg that can no longer change.
2. The taker can only claim after the proposer’s claim deadline. The proposer reveals first, or the swap does not settle.
3. The taker’s reaction window after the reveal is P.reclaimRelease − P.claimDeadline. The contract enforces its position in the schedule. Its width is a parameter the integrator chooses.

The contract checks the order of the deadlines and never their spacing. The QuipSwap SDK checks spacing: its presets are 300 seconds for fast-finality L2s, 1,800 seconds as the default, and 3,600 seconds for congested L1s. Cross-chain, each window is judged against the local chain’s block.timestamp, so the reaction window also has to absorb the worst-case clock skew between the two chains. The SDK’s validateCrossChainSchedule takes a maxClockSkewSeconds argument for this.

The schedule the order book builds

The order book spaces all six deadlines one gap apart, starting from the moment the maker accepts a request. With s as the acceptance time and g as the listing’s gap:

The default gap is 1,800 seconds. In plain terms, with the default gap the maker commits within 30 minutes of accepting, the taker commits in the next 30 minutes, and the maker settles in the 30 minutes after that. On a cross-chain swap the taker then settles on the maker’s chain inside [s + 3g, s + 5g), a 60-minute window at the default gap. Each side must be online for its step. A swap that nobody settles is fully reclaimable three hours after acceptance. A maker can set a gap as short as 60 seconds; a gap under 1,800 seconds, or under the minimum the order book sets for that chain pair if higher, asks for confirmation. The longest gap keeps the last reclaimRelease within 14 days of acceptance.

Lock states

A swap ID moves through four states:

The allowed transitions are Unused → Free, Unused → Committed, Free → Committed, Free → Spent and Committed → Spent. Anything else reverts with InvalidLockAdvancement. Settlement marks the swap Spent before any asset moves, so a reentrant claim or reclaim fails.

A cross-chain swap goes straight from Unused to Committed on each chain, because the counterparty’s commit lives on the other chain and is not visible here.

Commit

commit(lock, party, counterparty, auth) escrows one side.

1. party.chainId must equal the local chain. Both sides are validated, and so is their pairing.
2. The caller must be inside this side’s commit window from the table above.
3. msg.value must equal the total native amount in party.assets plus the current commitmentFee, exactly. Overpaying and underpaying both revert with IncorrectNativeAmountReceived.
4. The commit is authorized through one of two routes, described in Contracts and fees.
5. The first commit records the canonical terms digest. A second same-chain commit must match it and must post the other side.
6. The fee is added to accruedFees, the side is marked as posted, and ERC-20, ERC-721 and ERC-1155 assets are pulled from msg.sender. Fungible deposits are reconciled against the balance actually received.
7. The contract emits Commitment(lock, party, signer, sender).

The sender funds the leg and the fee. The identity in auth only authorizes it.

Claim

claim(secret, party, counterparty) settles. Anyone holding the secret may call it, and the transaction makes the secret public.

• The counterparty’s leg must be on the local chain, since that is where the party gets paid.
• The window depends on whose assets this chain holds: the proposer’s reveal window where the taker’s assets are held, and the taker’s window where only the proposer’s assets are held.
• The swap must be Committed and the counterparty’s side must have been posted.
• The counterparty’s assets go to party.recipient. On a same-chain swap the party’s assets go to counterparty.recipient in the same transaction, so one claim settles both legs.
• The contract emits Claim(lock, recipient, secret) once per leg paid out.

Claim payouts are exact or the call reverts. If a token’s pooled balance shrank after commit, claim reverts and the swap falls through to reclaim.

Reclaim

reclaim(lock, party, counterparty) returns one side’s assets to that side’s reclaimRecipient once party.reclaimRelease has passed. Anyone may call it; the recipient is fixed by the terms.

• Each side reclaims its own leg, once. A second attempt reverts with AlreadyReclaimed.
• The first reclaim moves the swap to Spent. The other side can still reclaim its own leg after that, but a swap that was settled by claim cannot be reclaimed.
• ERC-20 and ERC-1155 payouts are clamped to the balance the contract holds, so a reclaim can never be blocked by a token that shrank in place.
• The contract emits Reclaimed(caller, lock, recipient).

The commitmentFee paid at commit is not returned by a reclaim.

Timeouts and failure paths

Responsibilities the contract leaves to the integrator

• Confirm the proposer’s commit. The taker must confirm the proposer has committed before committing its own leg, on the same chain as well as across chains, because the contract checks deadlines only. On the same chain, a taker commit on an Unused swap moves it to Free and leaves the taker’s leg escrowed until T.reclaimRelease. Cross-chain, a taker who commits against a proposer that never committed can lose its leg; confirm on the proposer’s chain at a confirmation depth you trust. The SDK’s verifyRemoteCommitment reads the proposer chain’s storage for this.
• Keep the secret. If the proposer loses the secret, the swap cannot settle and both sides wait for reclaim.
• Watch for the reveal. The taker has to claim inside [P.claimDeadline, P.reclaimRelease) on the proposer’s chain.
• Vet the counter-leg asset. Fee-on-transfer and other lossy tokens are rejected at commit. Rebasing tokens are unsupported, as is any token or NFT contract whose transfers are dishonest. Tokens whose issuer can pause transfers or blacklist addresses, such as USDC, USDT, EURC and AUSD, carry issuer freeze risk: on a same-chain swap, a freeze makes claim revert, because its payout is exact or nothing, and the swap falls back to reclaim. Cross-chain, the proposer may already have claimed the taker’s leg; if a freeze then blocks the taker’s claim on the proposer’s chain, the taker can lose its leg once P.reclaimRelease passes. A leg that holds the frozen token cannot move until the issuer lifts the freeze, and if an issuer blacklists the Omnibus contract address itself, every escrowed leg in that token is frozen. The contract enforces the order of settlement. Judging whether the counter-leg asset is sound is up to each side before it commits.

Source: src/Omnibus.sol, src/TermsLib.sol and src/interfaces/IOmnibus.sol in the quip-swap-solidity repository.