Systems16 min read
One quote, every bridge
How BRDG asks every bridge that can serve a route, ranks quotes by what you actually receive, and the bugs that shaped its sanity checks and transfer tracking.
From Print.World · Aug 2025 – Present
At Print.World I've been building BRDG. The pitch is short: one request asks every bridge that can serve your route, ranks the answers by what you'll actually receive, and you sign the winner in your own wallet. It covers around 35 bridges across 73 chains.
Getting a quote from one bridge is easy. Getting honest, comparable quotes from 35 of them, and then tracking the transfer afterwards, is where the engineering lives.
Asking every bridge at once
Every bridge that can serve the route is asked at the same time, and each call races its own timeout, 8 seconds by default. That bounds a whole fan-out at roughly one bridge's worth of latency rather than the sum of the slow ones. As an estimate: at around a second per bridge, asking 19 of them one after another would take about 19 seconds; in parallel it takes as long as the slowest bridge that answers inside its deadline. A bridge that times out is dropped from that request, and the rest of the table is unaffected.
Answers also stream to the table as each bridge settles, instead of waiting for the slowest. On one request, Symbiosis answered in 118 ms and deBridge in 1,584 ms; the person looking at the table saw the first row at 118 ms, not 1.6 seconds.
There are no quote retries. Most bridge APIs are rate limited per IP, and a retry storm against a rate-limited API is how you earn a ban. A missed quote is cheap anyway: on the shared board, the next refresh asks again two seconds later.
Show data
| stat | Fan-out latency |
|---|---|
| p50 | 886ms |
| p90 | 2.3s |
| max | 3.5s |
Ranking by what you receive
The first decision was what to rank by. Dollars seem natural, but converting to dollars means depending on a price feed. If that feed goes down, every quote becomes unrankable at once, which is a bad failure mode for something whose whole job is ranking.
So quotes are ranked in the route's own token. For a fixed input, the best quote is the highest net output. For a fixed output ("I need exactly this much on the other side"), it's the lowest net input. No external price needed.
"Net" is doing a lot of work there. Bridges disagree about whether fees are already subtracted from the amount they report. So each quote marks which fees it has already accounted for, and the ranking subtracts only what's left. Without that, you double-count fees for some bridges and miss them for others, and the ranking quietly favours whoever reports most optimistically.
Concretely, every fee on a quote is a line with a kind (protocol, solver, origin gas, destination gas, app, or other) and a field saying where it was taken from: the input, the output, or gas. A line taken from the output is already inside the bridge's reported figure, so nobody subtracts it again. A line taken from the input is charged on top, and it's the only kind the rank subtracts, converted at the quote's own implied rate and rounded against the bridge, so rounding can never make a quote look better than it is. A solver fee can be negative, because some solvers pay a rebate, and a rebate is real money. Two examples, with made-up numbers on a 1,000 USDC transfer:
Bridge A reports 999.0 out, with a 1.0 fee taken from the output
net = 999.0 (fee already inside the figure)
Bridge B reports 1,000.0 out, with a 1.5 fee charged on the input
net = 1,000.0 - 1.5 = 998.5 (fee charged on top, so subtracted)
Ranked on the reported figure, B wins by 1.0. Ranked net, A wins by 0.5. That's the whole bug this field exists to prevent.
Two kinds of fee deliberately stay out of the rank. Origin gas, the gas your wallet pays on the source chain, is a property of the route and the moment, not of the bridge: every bridge's transaction pays roughly the same gas, but only some of them itemise it. Subtracting it where it's reported would rank bridges by how honest they are about a cost they all share. So it stays in the fee breakdown, where you can see it, and out of the rank. And a fee charged in some third asset makes the row "unpriced": it stays visible, so you can see the bridge answered, but it can never win, because there's no honest way to compare it without a price.
Quotes that expire too soon to realistically sign and send are dropped. A great price you can't use isn't a great price. The floor is 15 seconds of remaining validity. Below that, the row stays on the table, marked as expiring too soon, but it can't win. Bridges that work through a deposit address, where you send funds to an address rather than signing a contract call, need 10 minutes left, because sending from another wallet or an exchange takes minutes, not seconds.
Guarding the ranking
Aggregating 35 integrations means trusting 35 different interpretations of "amount". Token decimals vary from 6 to 18 and beyond, so a unit mix-up isn't off by a little: it's off by a factor of 10^2 to 10^12, and a ranking that sorts by "best output" will put the most wrong quote at the top.
So I designed the ranking to distrust outliers from the start, with two independent guards:
- Relative to the crowd. Any quote more than 10x away from the median of the other quotes for the same route is excluded. On realistic transfer sizes, real price differences between bridges are measured in basis points, not multiples, so the threshold costs nothing for honest quotes. Tiny transfers are the exception, where a fixed gas fee can be a large share of the amount.
- Relative to itself. A median needs other quotes, and some routes only have one bridge. So there's a second rule that needs no comparison: if a quote's output looks like its input echoed back in different units, it's excluded.
The scale of the error is worth spelling out. USDC has 6 decimals and ETH has 18, so a module that reads an 18-decimal amount as 6-decimal is off by 10^12. No honest bridge price is anywhere near a 10x band, and a unit bug is nowhere near inside it, which is why the threshold can be that loose and still catch everything that matters.
The tiny-transfer exception is also bounded. As an estimate: a $2 fixed fee on a $10 transfer leaves $8, and a bridge with no fixed fee returns about $10. That's a ratio of 1.25, nowhere near 10. A fixed fee only trips the band when it eats about 90% of the amount, and at that point excluding the quote is doing the user a favour.
The details are where the guard earns its keep:
- A median needs at least three quotes. With two, there's no way to tell which one is wrong. With an even count, it uses the lower of the two middle values.
- The band can only remove a strict minority. If half the table or more falls outside the band, the thing that's wrong is the comparison set, not the rows, and a guard confident enough to delete most of a table would happily delete the honest half of it. In that case the band does nothing and only the self-contained rules apply.
- The echo rule is exact, not fuzzy. It fires only when the two sides are different assets, their decimals differ (or the median also puts the quote outside the band), and the output equals the input minus the declared output fee, to the last unit. A real exchange rate never lands on that number by accident.
- No crown on a demotion. If the guard demotes the quote that would have won, nothing is marked best on that refresh. Promoting the runner-up in the same breath would mean trusting a table that just produced a wrong winner.
A same-asset route (USDC to USDC) needs its own version of the echo rule, because some bridges honestly quote exactly 1:1. There, a quote is suspicious only if it's exactly 1:1, better than the median, and the bridge didn't back the price.
A shared quote board
Many users look at the same popular routes. Polling every bridge separately for each viewer would be wasteful and would hit rate limits fast. Instead, each route and amount is refreshed once per interval and pushed to everyone watching. A hundred viewers cost the same as one.
How fast "hit rate limits" comes is easy to work out. deBridge, for example, documents 50 requests a minute per IP without a key, and I budget every bridge at 80% of its documented limit to leave headroom, so 40 a minute, or about 0.67 requests a second. One watched route refreshing every 2 seconds costs 0.5 a second. So that budget covers about 1.3 routes refreshing at full speed, and with per-viewer polling a second person watching the same route would already push it over. Shared refreshing turns the cost from viewers times routes into just routes.
The mechanics:
- A route is keyed by source chain, source asset, destination chain, destination asset, and the exact amount in the token's smallest unit. Two people asking for the same transfer share one key; anything else doesn't.
- A worker loop ticks every 500 ms and re-prices watched routes on a 2-second cadence, four at a time and at most twelve per tick.
- Results go out through Centrifugo on a channel per route, and only when a value changed.
- A browser tab keeps its routes alive with a heartbeat every 10 seconds; a route nobody has heartbeated for 30 seconds stops being refreshed, and an idle tab stops heartbeating after a minute. Typing an amount is debounced by 350 ms, so typing "1000" doesn't price four routes.
- A bridge that doesn't answer keeps its last row, but the row keeps ageing: after 15 seconds it's shown as stale, and after 10 missed refreshes it stops competing.
The limit of this design is the worker, not the viewers. Its measured capacity was about 1.94 route refreshes a second. At a 2-second cadence that's 1.94 x 2 ≈ 4 routes at full speed, and that matches what I saw: past about four hot routes, the cadence stretches from 2 seconds toward 5 to 10. At 10x the routes, I'd need more workers splitting routes between them, and the per-bridge rate budgets would bind before the workers did, because those are per IP and don't grow with the fleet.
Ranking without flicker
Live quotes wobble. If the top two bridges are within a hair of each other, the table would swap them on every refresh, which looks broken. So a bridge only overtakes the row above it if it beats it by a margin.
That rule has a subtle problem. "Beats by a margin" isn't a consistent ordering: A can be roughly equal to B, and B roughly equal to C, while A clearly beats C. Passing a comparator like that to Array.sort leaves the resulting order implementation-defined by the spec, and in practice the order can change between refreshes.
So I don't sort with it. Starting from the previous order, I look for adjacent pairs that are out of order by more than the margin and swap them one at a time until none are left. It's stable, predictable, and it only moves rows that genuinely should move.
The margin is 5 basis points (0.05%). I picked it from the noise floor: the same request repeated four times about 15 seconds apart came back within about 1.6 bps on every bridge I tested, so 5 bps is roughly three times the jitter of an unchanged market. Below that, a swap is mostly noise; above it, it's a real change in price.
Termination isn't in doubt, even with an inconsistent relation. Every swap moves a strictly better quote, by more than the margin, above a worse one, so this is bubble sort that ignores small inversions: at most n(n-1)/2 swaps, a few hundred for a table of a few dozen bridges, which is nothing next to the network call that produced the quotes. Only pairs that were both on the previous board are ever held in place; a bridge that just appeared is placed by its plain value. The "best" badge follows the same rule, with one more condition: the current holder only keeps it if it answered on this refresh and its quote is still signable.
The cost of the margin is a known ceiling. A bridge that is consistently 4 bps better than the one above it never takes the top spot. On a $10,000 transfer that's at most $4, and I'd rather pay that than show a table that reshuffles every two seconds.
A cache key that includes who you are
Quotes are cached. The obvious key is route and amount. But a bridge's quote often includes ready-to-sign calldata, and that calldata bakes in the sender and recipient addresses. With a key that ignored them, one user could be served calldata that sends their funds to another user's recipient.
So the cache key includes sender and recipient. It costs some hit rate. That's fine.
The full key is bridge, source, destination, exact amount, trade direction, slippage, sender, and recipient. Entries live 10 seconds, and never past the bridge's own expiry for that quote. The cache serves only indicative quotes (the ones you're looking at, not the one you're about to sign), and the shared board doesn't use it at all, since the board already refreshes every route on its own schedule. One small trap: EVM addresses are case-insensitive and get lowercased in the key, but Solana's base58 addresses are case-sensitive and don't, or two different wallets could share a key.
Tracking the transfer
Once you've signed, a bridge transfer can take seconds or much longer, and statuses come from many different APIs. Ours normalises them into ten statuses, split into terminal ones and ones we keep polling.
A few rules I designed in deliberately:
- a transfer that repeatedly comes back "not found" becomes
UNKNOWN, neverFAILED; we don't tell someone their money is gone because an API was slow to index - a transfer filled with the wrong token, or less than expected, becomes
PARTIAL, not success - we record the broadcast before sending it, and a sweep flags any record still missing a transaction hash, so nothing falls through the gap between "we sent it" and "we saw it"
The numbers behind those rules, and why they're shaped that way:
- Open transfers are polled every 5 seconds, oldest-asked first, with at most three failures per bridge per tick, so one broken status API can't starve the others.
- "Not found" becomes
UNKNOWNonly after 10 not-found answers and at least 10 minutes since the transfer was submitted. Ten polls at 5 seconds is only 50 seconds, and indexers routinely lag longer than that, so the time floor is what actually decides it. Ten answers alone would turn every slow indexer into a scare. UNKNOWNis still polled and never retried automatically. A transfer is only written off asABANDONEDafter 30 not-founds and at least 30 minutes, or 24 hours after submission.- The missing-hash sweep runs at the end of every poll tick. A record that claimed a broadcast but has no transaction hash after 5 minutes becomes
UNKNOWN, which puts it in front of a human rather than silently dropping it.
Of the ten statuses, five are final (COMPLETED, PARTIAL, REFUNDED, FAILED, ABANDONED) and five are still in motion (PENDING_SIGNATURE, SUBMITTED, PENDING, NEEDS_ACTION, UNKNOWN).
Keeping the engine testable
The routing engine has no infrastructure dependencies. It talks to the outside world through five small injected interfaces, and lint rules enforce that it can't import anything else. That's what lets more than 400 routing tests run with no Redis, no network, and no bridges.
The five are an index of which bridges serve which routes, a snapshot of each bridge's state, a gate that hands out rate-budget tokens, a sink for health reports, and the quote cache. The lint rule is a plain restricted-imports list: the engine and the bridge modules can't import the database, the shared state package, Redis or Postgres clients, the ORM, or any app code. Three deterministic fake bridges live next to the real ones, with price curves that cross on purpose: one quotes the best rate with the steepest price impact, one the worst rate with the flattest, one in between. So the cheapest bridge changes with the amount, and a test can prove the ranking (and the route splitter) picks the right answer at each size without a network or a real market moving.
Redis failure policy is decided per use, not globally. The routing state cache fails closed, because routing on stale state is worse than not routing. Rate limits fail open, because a limiter outage shouldn't stop users. And locks are released only by their holder, so a slow worker can't free a lock someone else now owns.
| Use | If Redis is down | Why |
|---|---|---|
| Bridge state snapshot | Fail closed | Routing on state I can't see is worse than not routing |
| Acquiring a lock | Fail closed | A lock I can't read has a holder I can't know, and what it guards is a pass that spends every bridge's request budget |
| Rate budget | Fail open | The bridge's own limit still applies; blocking users is worse |
| Health monitor, bridge limits, watch registry | Fail open | Losing them degrades the board; it doesn't make it wrong |
| Quote cache, board reads | Treated as a miss | Ask the bridge directly |
The lock is the standard single-instance Redis pattern: SET key token NX PX ttl with a random token, and release is a short Lua script that deletes the key only if it still holds that token. Without the token check, a worker that stalls past its TTL would come back and delete the lock a second worker now holds. The lock is tried once and skipped if busy: another worker is already refreshing that route, and waiting would only duplicate its work.
Docs that can't drift
The public docs at docs.brdg.now are generated from the live OpenAPI spec, so they can't fall out of date with the API. There's also a TypeScript SDK on GitHub.
What I took from it
Most of the interesting decisions here were about what to do when something is wrong or unknown: a price feed that's down, a bridge reporting nonsense, a status API that hasn't caught up. I keep relearning the lesson from the perps aggregator: pick the honest status, not the optimistic one.
Next on my list is making those failure policies visible on the board itself, so a user can see not just which bridge won, but which ones were excluded and why.