> For the complete documentation index, see [llms.txt](https://galactic-bridge.gitbook.io/galactic-bridge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://galactic-bridge.gitbook.io/galactic-bridge-docs/how-it-works.md).

# How it works

Five stages run between pasting an address and signing a transaction.

## 1. Resolving the OFT contract

The bridge first asks the LayerZero API whether the token address is itself an OFT. Most of the time it is, and this takes one request.

If it is not, the token is moved by a separate **adapter** contract. Finding it works like this:

1. Fetch the token's `Transfer` logs for a range of blocks.
2. Fetch LayerZero's `OFTSent` / `OFTReceived` events for the **same** range.
3. Intersect them by transaction hash.

A transaction that both moved the token and emitted a LayerZero event is a bridge transaction, and the address that emitted the event is the adapter. No transaction-by-transaction probing is needed, and the method works for both lock/unlock and burn/mint designs.

The candidate is then verified by calling `token()` on it. Without that check, an aggregator swapping several tokens in one transaction could produce a false match.

## 2. Resolving the route

In order:

1. **Forward** — look for a delivered LayerZero message in this exact direction.
2. **Reverse** — if the destination contract is known, search from that side instead.
3. **peers()** — ask the source contract which address it is paired with on the destination network. This is a standard LayerZero V2 function, so a route can be confirmed with **zero transaction history**. Knowing the destination contract, the reverse search runs again and returns real transactions.
4. If none of that works, you can enter the contract or a sample transaction hash by hand.

## 3. Building the transaction

Two paths, in order of authority:

**A direct example.** If the history contains a transaction sent straight to the OFT contract, its call format is read and reused. Router transactions are skipped deliberately — their call data belongs to the router, not the token.

**The standard interface.** If no direct example exists, the bridge calls `quoteSend()`. A valid fee proves the contract implements the LayerZero V2 standard, so the call is assembled from scratch. This is what makes popular tokens work: they are almost always bridged through aggregators, so a usable direct example rarely exists.

The fee always comes from a live `quoteSend()` for the actual destination.

## 4. Discovering networks

When you save a token, the bridge walks every connected contract through `peers()` and supplements the result with LayerZero history.

Networks are not always wired in a star topology. One token's Base adapter may know only BNB Chain, while BNB Chain knows both Base and Mantle — so every node is queried, not just the starting one.

Results are cached in memory: the OFT adapter for 24 hours, since it does not change, and the network list for one hour. A repeated search for the same token returns instantly instead of scanning again.

Fees and balances are **never** cached. They depend on gas prices and would go stale within minutes, and a stale fee means a rejected transaction.

## 5. Checking that the direction is open

History proves a route *worked*. It does not prove it *works*.

Projects switch directions off by clearing the `peer` setting on the contract — often after a single test transaction, sometimes when migrating to new contracts. The route then still exists in LayerZero's history, but the contract will refuse it.

`peer` is also one-directional, and the two failure modes are not equally serious:

| Missing peer on | What happens                                                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Source**      | The transaction is rejected immediately. Your funds are untouched.                                                                  |
| **Destination** | The source transaction **succeeds** and your tokens are sent, but delivery fails on the other side — leaving them stuck in transit. |

The bridge therefore checks both sides before it shows you a fee, and blocks the route with an explanation rather than letting you sign a transaction that cannot complete.

It only blocks when a contract explicitly answers that no peer is set. If `peers()` is not supported by that contract, or the node cannot be reached, nothing is blocked — a rare working route must never be hidden by a node that happened to be down.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://galactic-bridge.gitbook.io/galactic-bridge-docs/how-it-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.