# Bridge Integration

The **Goliath Bridge** moves assets between **Ethereum Mainnet** (Chain ID `1`) and **Goliath Mainnet** (Chain ID `327`) in both directions. This guide is written for external developers — mobile, web, and backend integrators — who want to submit bridge transactions and track them to completion without depending on the Onyx App UI.

{% hint style="info" %}
The same flows work on testnet, with different chain IDs and contract addresses. See [Contracts & Events](/developer-guide/bridge/contracts-and-events.md) for both environments.
{% endhint %}

## Supported Assets

| Asset    | Ethereum → Goliath |          Goliath → Ethereum         | Ethereum side | Goliath side     |
| -------- | :----------------: | :---------------------------------: | ------------- | ---------------- |
| **ETH**  |     Lock + mint    |            Burn + release           | Native ETH    | Bridged ERC-20   |
| **USDC** |     Lock + mint    |            Burn + release           | ERC-20        | Bridged ERC-20   |
| **XCN**  |     Lock + mint    | **Signed intent + native transfer** | ERC-20        | Native gas token |

Each direction uses a slightly different transaction shape. See [Ethereum → Goliath](/developer-guide/bridge/ethereum-to-goliath.md) and [Goliath → Ethereum](/developer-guide/bridge/goliath-to-ethereum.md) for the exact steps.

{% hint style="info" %}
**Smart-account wallets (Safe, Coinbase Smart Wallet, Biconomy, Alchemy AA, ZeroDev, thirdweb, …) are supported on the XCN withdraw flow** via ERC-1271 signatures and ERC-4337 `handleOps(...)` execution. See [Smart Account Integration](/developer-guide/bridge/smart-account-integration.md) for the hard rules and worked examples.
{% endhint %}

## Transfer Times and Fees

| Direction          | Typical time | Fee                             |
| ------------------ | ------------ | ------------------------------- |
| Ethereum → Goliath | \~5 minutes  | **Free** (gas on Ethereum only) |
| Goliath → Ethereum | \~1 hour\*   | `max(0.25%, minimum fee)`       |

\* The Goliath → Ethereum path includes a one-hour security hold before the relayer releases funds on Ethereum.

### Goliath → Ethereum Fee Schedule

| Token    | Fee rate | Minimum fee | Minimum bridge amount |
| -------- | -------- | ----------- | --------------------- |
| **ETH**  | 0.25%    | 0.003 ETH   | 0.01 ETH              |
| **USDC** | 0.25%    | 5 USDC      | 10 USDC               |
| **XCN**  | 0.25%    | 1,000 XCN   | 5,000 XCN             |

The fee is `max(amount * 25 / 10000, minFee[token])`. Transfers below the minimum bridge amount are rejected. **Always call** [**`GET /bridge/fee-quote`**](/developer-guide/bridge/api-reference.md#get-bridge-fee-quote) before prompting the user — the canonical values come from the API, not from this document.

## Network Endpoints

### Goliath Mainnet (Chain ID `327`)

| Service         | URL                                                                      |
| --------------- | ------------------------------------------------------------------------ |
| EVM JSON-RPC    | [`https://rpc.goliath.net`](https://rpc.goliath.net)                     |
| Block Explorer  | [`https://explorer.goliath.net`](https://explorer.goliath.net)           |
| Bridge REST API | [`https://bridge.goliath.net/api/v1`](https://bridge.goliath.net/api/v1) |

### Ethereum Mainnet (Chain ID `1`)

Use any public or private Ethereum RPC provider — the bridge has no chain-specific requirements on the Ethereum side.

## Contract Addresses (Mainnet)

| Contract           | Chain         | Address                                      |
| ------------------ | ------------- | -------------------------------------------- |
| **BridgeLock**     | Ethereum (1)  | `0xa9fd64b5095d626f5a3a67e6db7fb766345f8092` |
| **BridgeMint**     | Goliath (327) | `0x1d14ae13ca030eb5e9e2857e911af515cf5ffff2` |
| **Relayer wallet** | Goliath (327) | `0x90F26908Ee30C8fA6812f6BA66c050a86C8aF6cB` |

Token addresses and testnet equivalents live in [Contracts & Events](/developer-guide/bridge/contracts-and-events.md).

{% hint style="warning" %}
The **relayer wallet address** is the destination for native-XCN withdrawals (Goliath → Ethereum for XCN only). Always read the current address from [`POST /bridge/xcn-withdraw-intent`](/developer-guide/bridge/api-reference.md#post-bridge-xcn-withdraw-intent) — never hardcode it in mobile builds, because it may rotate.
{% endhint %}

## End-to-End Flow at a Glance

```
Ethereum (1)                               Goliath (327)
============                               ==============

User -> BridgeLock.deposit(...)       [Ethereum tx confirmed]
                                           |
                                           v
                                      Relayer observes Deposit event
                                           |
                                           v
User                              <-  BridgeMint.mint(...)     [Goliath tx confirmed]

                                   ... (1 hour hold for security)

User -> BridgeMint.burn(...)  or  XCN withdraw intent + native transfer
                                           |
                                           v
                                      Relayer observes Withdraw / native tx
                                           |
                                           v
User <-  BridgeLock.release(...)      [Ethereum tx confirmed]
```

Both legs are triggered by on-chain events (or a signed intent for native XCN). The **relayer is an off-chain service operated by the Goliath team** — external developers never call its endpoints directly.

## Quick Start for Mobile Developers

1. Read [Architecture](/developer-guide/bridge/architecture.md) to understand the lifecycle and the three transaction shapes.
2. Pick your direction:
   * **Ethereum → Goliath:** [Ethereum → Goliath guide](/developer-guide/bridge/ethereum-to-goliath.md)
   * **Goliath → Ethereum (ETH/USDC):** [Goliath → Ethereum guide](/developer-guide/bridge/goliath-to-ethereum.md#erc-20-withdraw-eth-usdc)
   * **Goliath → Ethereum (XCN):** [Goliath → Ethereum guide](/developer-guide/bridge/goliath-to-ethereum.md#native-xcn-withdraw)
3. Wire up status polling via [`GET /bridge/status`](/developer-guide/bridge/api-reference.md#get-bridge-status) keyed by your origin tx hash.
4. Render history via [`GET /bridge/history`](/developer-guide/bridge/api-reference.md#get-bridge-history) keyed by the user's wallet address.

## Index

* [**Architecture**](/developer-guide/bridge/architecture.md) — Contracts, flows, finality, status lifecycle.
* [**Ethereum → Goliath**](/developer-guide/bridge/ethereum-to-goliath.md) — Deposit flow with code.
* [**Goliath → Ethereum**](/developer-guide/bridge/goliath-to-ethereum.md) — Withdraw flows for ERC-20 and native XCN.
* [**REST API Reference**](/developer-guide/bridge/api-reference.md) — All public endpoints.
* [**Contracts & Events**](/developer-guide/bridge/contracts-and-events.md) — Addresses, ABIs, events (mainnet + testnet).
* [**Smart Account Integration**](/developer-guide/bridge/smart-account-integration.md) — ERC-1271 / ERC-4337 (Safe, Coinbase Smart Wallet, Biconomy, Alchemy AA, ZeroDev, thirdweb).


---

# Agent Instructions: 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:

```
GET https://docs.goliath.net/developer-guide/bridge.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.