# Architecture

The Goliath Bridge is a **lock-and-mint** bridge between Ethereum (Chain `1`) and Goliath (Chain `327`). It uses one contract on each side, plus a trusted off-chain relayer that observes events and submits the mirroring transaction on the destination chain.

This page explains the pieces. If you only want to call the bridge, skip to [Ethereum → Goliath](/developer-guide/bridge/ethereum-to-goliath.md) or [Goliath → Ethereum](/developer-guide/bridge/goliath-to-ethereum.md).

## Components

### On-chain Contracts

| Contract       | Chain           | Role                                                                      |
| -------------- | --------------- | ------------------------------------------------------------------------- |
| **BridgeLock** | Ethereum (`1`)  | Locks ERC-20 / native assets on deposit; releases them on withdrawal.     |
| **BridgeMint** | Goliath (`327`) | Mints bridged ERC-20s on deposit; accepts "burn" transfers on withdrawal. |

Both contracts expose a small, **user-facing public interface** (deposit / depositNative / burn) and a **relayer-only interface** (release / releaseNative / mint) gated by a single `relayer` address. External developers only ever call the user-facing functions.

### Off-chain Relayer

A single relayer wallet — operated by the Goliath team — observes events on both chains and submits the mirroring transaction on the destination side. It is the authorised caller of the privileged contract functions (`mint`, `release`, `releaseNative`). Its Ethereum and Goliath address is the same: `0x90F26908Ee30C8fA6812f6BA66c050a86C8aF6cB`.

External developers **do not call the relayer** directly. Your only interaction with relayer-side state is through the [bridge REST API](/developer-guide/bridge/api-reference.md), which exposes read-only status and history plus a signed-intent endpoint used for native-XCN withdrawals.

### Bridge REST API

The backend at [`https://bridge.goliath.net/api/v1`](https://bridge.goliath.net/api/v1) exposes:

* `GET /bridge/status` — look up an in-flight or completed operation by origin tx hash, depositId, or withdrawId.
* `GET /bridge/history` — list operations for a wallet address.
* `GET /bridge/fee-quote` — preview fees and minimums for a pending transfer.
* `GET /bridge/limits` — current per-token fee and minimum configuration.
* `POST /bridge/xcn-withdraw-intent` — required for **native-XCN withdrawals only** (see below).
* `POST /bridge/xcn-withdraw-intent/bind-origin` — pair the signed intent to the on-chain tx hash.
* `GET /health` — liveness / readiness probe.

Full request/response shapes are documented in the [API Reference](/developer-guide/bridge/api-reference.md).

## The Three Transaction Shapes

Every bridge transfer falls into one of three shapes. The choice depends on the **direction** and whether the asset is **native** on the source chain.

### 1. Deposit (Ethereum → Goliath)

```solidity
// Native ETH
BridgeLock.depositNative(address destinationAddress) payable returns (bytes32 depositId);

// ERC-20 (USDC, XCN on Ethereum)
BridgeLock.deposit(address token, uint256 amount, address destinationAddress)
    returns (bytes32 depositId);
```

Emits a `Deposit` event. The relayer observes the event, waits for Ethereum finality, then calls `BridgeMint.mint(...)` on Goliath to credit the recipient.

### 2. Burn (Goliath → Ethereum, ERC-20 only)

```solidity
BridgeMint.burn(
    address token,                // bridged ERC-20 address on Goliath
    uint256 amount,
    address destinationAddress,
    uint64  destinationChainId    // 1 for Ethereum Mainnet
) returns (bytes32 withdrawId);
```

Emits a `Withdraw` event. After the one-hour hold, the relayer calls `BridgeLock.release(...)` or `BridgeLock.releaseNative(...)` on Ethereum to deliver the (post-fee) amount to `destinationAddress`.

{% hint style="info" %}
The "burn" on Goliath is implemented as a transfer to the relayer wallet, not a burn to `0x0`. This is an internal detail — from your perspective the tokens leave your wallet and re-appear on Ethereum.
{% endhint %}

### 3. Native-XCN Withdrawal (Goliath → Ethereum, XCN only)

XCN is the **native gas token** on Goliath. There is no ERC-20 to burn. Instead the flow is:

1. Client builds and signs an **EIP-712 intent** describing the withdrawal.
2. Client submits the signed intent to `POST /bridge/xcn-withdraw-intent`.
3. API returns an `intentId` and the current `relayerWalletAddress`.
4. Client sends a plain **native XCN transfer** from the signer wallet to `relayerWalletAddress` with `value = amount`.
5. Client pairs the tx hash to the intent via `POST /bridge/xcn-withdraw-intent/bind-origin`.
6. After the hold, the relayer releases XCN (as ERC-20) on Ethereum.

The bridge accepts both **EOA signatures** (ECDSA recovery) and **ERC-1271 smart-account signatures** (on-chain `isValidSignature(bytes32,bytes)` returning magic `0x1626ba7e`). For smart-account senders — Safe, Coinbase Smart Wallet, Biconomy, Alchemy AA, ZeroDev, thirdweb, etc. — the origin-funds proof walks the execution-tx call tree (via the Hedera mirror's `/api/v1/contracts/results/{txHash}/actions` endpoint) to find the `(smartAccount → relayerWalletAddress, value)` child `CALL`, so `EntryPoint.handleOps(...)` bundler execution is supported as long as the smart account calls the relayer directly (multi-hop `smartAccount → Router → relayer` is rejected).

Full walkthrough in [Goliath → Ethereum — Native XCN](/developer-guide/bridge/goliath-to-ethereum.md#native-xcn-withdraw); smart-account-specific rules, failure modes, and worked examples in [Smart Account Integration](/developer-guide/bridge/smart-account-integration.md).

## Events You Can Observe

All event signatures are part of the public ABI. Addresses are listed in [Contracts & Events](/developer-guide/bridge/contracts-and-events.md).

### `Deposit` — BridgeLock on Ethereum

```solidity
event Deposit(
    bytes32 indexed depositId,
    address indexed token,        // address(0) for native ETH
    address indexed sender,
    address destinationAddress,
    uint256 amount,
    uint64  timestamp,
    uint64  sourceChainId
);
```

### `Mint` — BridgeMint on Goliath

```solidity
event Mint(
    bytes32 indexed depositId,
    address indexed token,
    address indexed recipient,
    uint256 amount
);
```

`Mint.depositId` matches the `Deposit.depositId` on Ethereum — use it to correlate the two sides.

### `Withdraw` — BridgeMint on Goliath

```solidity
event Withdraw(
    bytes32 indexed withdrawId,
    address indexed token,
    address indexed sender,
    address destinationAddress,
    uint256 amount,
    uint64  timestamp,
    uint64  sourceChainId,
    uint64  destinationChainId
);
```

### `Release` — BridgeLock on Ethereum

```solidity
event Release(
    bytes32 indexed withdrawId,
    address indexed token,        // address(0) for native ETH
    address indexed recipient,
    uint256 amount
);
```

`Release.withdrawId` matches the `Withdraw.withdrawId` on Goliath.

## Finality and Timing

Each direction waits for source-chain finality before the relayer submits the destination transaction.

| Direction          | Required source confirmations                         | Typical wall-clock time |
| ------------------ | ----------------------------------------------------- | ----------------------- |
| Ethereum → Goliath | 12 blocks (\~144 s)                                   | \~5 min total           |
| Goliath → Ethereum | 6 Goliath blocks (\~12 s), then **1 h security hold** | \~1 h total             |

The hold is configurable and applied on the Goliath → Ethereum path only. Current values are exposed in every `GET /bridge/status` response via `requiredConfirmations`, `originConfirmations`, `holdUntil`, and `estimatedCompletionTime` — read those fields rather than hardcoding the numbers above.

## Status Lifecycle

Every bridge operation the backend tracks moves through these states:

| Status                   | Meaning                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `PENDING_ORIGIN_TX`      | Operation registered (usually an XCN withdraw intent) but no origin tx hash bound yet.  |
| `CONFIRMING`             | Origin tx seen; waiting for source-chain finality.                                      |
| `AWAITING_RELAY`         | Finalized. Waiting for relayer to submit destination tx (includes hold period for G→E). |
| `PROCESSING_DESTINATION` | Destination tx submitted; waiting for it to confirm.                                    |
| `COMPLETED`              | Destination tx confirmed. Funds delivered.                                              |
| `DELAYED`                | Relayer retrying after a transient failure. Will still complete.                        |
| `FAILED`                 | Non-recoverable error (e.g. signature mismatch, rejected intent).                       |
| `EXPIRED`                | Signed intent expired before it could be paired to an origin tx.                        |

Terminal states are `COMPLETED`, `FAILED`, and `EXPIRED` — once there, the record will not change. Clients should **stop polling** at that point.

## Where to Next

* [Ethereum → Goliath](/developer-guide/bridge/ethereum-to-goliath.md) — deposit flow with code.
* [Goliath → Ethereum](/developer-guide/bridge/goliath-to-ethereum.md) — burn / native-XCN flows with code.
* [REST API Reference](/developer-guide/bridge/api-reference.md) — exact request/response shapes.
* [Smart Account Integration](/developer-guide/bridge/smart-account-integration.md) — ERC-1271 / ERC-4337 variant of the native-XCN flow.
* [Contracts & Events](/developer-guide/bridge/contracts-and-events.md) — addresses, ABIs (mainnet + testnet).


---

# 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/architecture.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.