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

# Bridge

The ParlayIt bridge moves USDC between Polygon and the ParlayIt chain. It is the path your funds travel every time you deposit or withdraw.

## Architecture At A Glance

* A **Polygon contract** escrows deposited USDC and releases withdrawn USDC.
* A set of independent **guardian validators** each verify and sign every transfer.
* A **relayer** process coordinates the flow between the two chains but cannot authorize anything on its own.
* The **ParlayIt chain bridge module** mints and burns the user-facing USDC balance against the Polygon escrow.

**Deposit flow:**

```mermaid
flowchart LR
    A[User wallet on Polygon] -->|1. Deposit USDC| B[Polygon bridge contract]
    B -->|2. Event log| C[Relayer]
    C -->|3. Request attestation| D[Guardian validators]
    D -.->|4. Verify across Polygon RPCs| B
    D -->|5. Signed attestations| C
    C -->|6. Submit with signatures| E[ParlayIt chain]
    E -->|7. Verify Merkle proof + mint| F[User's ParlayIt balance]
```

The dotted arrow is the part that matters most for trust: guardian validators do not take the relayer's word that a deposit happened. Each guardian queries Polygon directly through multiple independent RPCs and produces a signature only when every configured RPC agrees on the result. The relayer cannot fabricate a deposit because it never produces or controls the signatures.

**Withdrawal flow:**

```mermaid
flowchart LR
    A[User wallet on Polygon] -->|1. Sign EIP-712 withdraw| B[ParlayIt backend]
    B -->|2. Submit to chain| C[ParlayIt chain<br/>burns USDC + fee]
    C -->|3. Emit withdraw event| D[Relayer]
    D -->|4. Request attestation| E[Guardian validators]
    E -.->|5. Verify against ParlayIt| C
    E -->|6. Signed attestations| D
    D -->|7. Submit with signatures| F[Polygon bridge contract]
    F -->|8. Release USDC or queue 14h| A
```

The same trust pattern applies on the way out: each guardian validator queries the ParlayIt chain directly to confirm the withdraw event was emitted with the right details. The Polygon contract then cryptographically verifies the collected guardian signatures before releasing the USDC, either immediately on the fast path or after the 14-hour timelock if the withdrawal qualifies for the slow queue.

## Deposits

Deposits start on Polygon and are credited to your ParlayIt account once the bridge has verified them.

1. Connect your wallet to Polygon and choose the amount to deposit.
2. Sign the USDC transfer to the bridge contract.
3. The relayer observes the deposit on-chain and waits for **Polygon finality** before continuing. The bridge verifies the deposit against Polygon's finalized state and waits an additional safety buffer of about **3 minutes** in total before crediting funds to your ParlayIt account.
4. Each guardian validator independently re-verifies the deposit by querying multiple independent Polygon RPCs, **without relying on the relayer's input**. Every configured RPC must return the same result before the guardian signs.
5. Once **all four guardian signatures** are collected, the ParlayIt chain re-checks the Polygon receipt against the submitted block header and mints USDC into your ParlayIt account.

Unanimous (4-of-4) guardian signatures are required: every guardian must independently verify the Polygon deposit and sign. This makes minting on the ParlayIt side conditional on full agreement across the guardian set.

## Withdrawals

Withdrawals move USDC out of your ParlayIt account and release it back to your wallet on Polygon. Your wallet stays connected to Polygon for the entire flow. No network switch is needed.

1. Click Withdraw and enter the amount.
2. Sign an EIP-712 typed-data message in your wallet authorizing the withdrawal.
3. The ParlayIt backend forwards your signed request to the ParlayIt chain.
4. The chain burns the requested USDC from your account and deducts the **0.5 USDC withdrawal fee**.
5. Each guardian validator independently verifies the request after ParlayIt finality and signs the withdrawal payload.
6. Once all four guardian signatures are collected, the relayer submits the payload to the Polygon bridge contract.
7. The Polygon contract verifies the signatures and either releases the USDC immediately or queues it (see Fast Path vs. Slow Queue below).

## Withdrawal Fee

Each withdrawal includes a flat fee of **0.5 USDC**, charged on the ParlayIt chain when the withdrawal is requested. The fee discourages spam and helps keep the withdrawal flow available for normal use.

## Fast Path vs. Slow Queue

The Polygon contract decides whether a withdrawal is released immediately or sent to the slow queue. To qualify for the **fast path**, **all three** of the following must hold:

* Amount ≤ **1,000 USDC** per withdrawal
* Amount ≤ **2.5% of the bridge's current TVL**
* Total fast-path throughput in the current hour ≤ **10,000 USDC**

If all three pass, the USDC is transferred to the user's Polygon wallet immediately.

If any one fails, the withdrawal enters the **slow queue**:

* The withdrawal is recorded on Polygon with an unlock time **14 hours** in the future.
* During that window, the queue entry is publicly visible.
* Once the timelock expires, anyone (typically the relayer) can execute the queued withdrawal to release the USDC.
* The owner multisig can reject a queued withdrawal during the timelock window, as a safety mechanism for catching incorrect or compromised payloads before they're released.

## Security Model

The bridge is a federated multisig system. Safety relies on the guardian set, not on a fully trustless mechanism.

* **Guardian validators.** There are currently **4 guardians**. Each runs an independent signer service and holds its own key.
* **Independent verification.** Each guardian queries Polygon directly through multiple independent RPCs when validating a deposit. **Every configured RPC must agree on the result**. If any RPC is unreachable or returns conflicting data, the guardian refuses to sign rather than continuing with reduced verification. The system fails closed.
* **Multisig thresholds.** Both deposits and withdrawals require unanimous **4-of-4** guardian signatures. A single rogue or compromised guardian cannot move funds, and a single offline guardian pauses transfers until it is restored.
* **Merkle receipt proofs for deposits.** The ParlayIt chain re-verifies each deposit's Polygon receipt against the submitted block header before minting USDC.
* **Replay protection.** Both sides keep mappings of processed and cancelled transfers so the same deposit or withdrawal cannot be executed twice.
* **Relayer as coordinator only.** The relayer forwards events and payloads but cannot authorize transfers on its own. Every payload must carry valid guardian attestations. If the relayer is offline, transfers pause but funds remain safe.
* **14-hour timelock on the slow path.** Larger withdrawals sit in a public queue before execution, giving the owner multisig time to react to anything irregular.
* **Pause switch.** The owner multisig can pause deposits and withdrawals across the bridge if something is wrong.
* **Upgradeable implementation.** The Polygon contract is deployed behind a TransparentUpgradeableProxy (EIP-1967). The owner multisig can upgrade the implementation if a fix or improvement is needed.

## Limits Summary

| Item                             | Current value      |
| -------------------------------- | ------------------ |
| Minimum deposit                  | 5 USDC             |
| Minimum withdrawal               | 1 USDC             |
| Withdrawal fee                   | 0.5 USDC           |
| Fast-path per-withdrawal cap     | 1,000 USDC         |
| Fast-path TVL cap                | 2.5% of bridge TVL |
| Fast-path hourly throughput      | 10,000 USDC / hour |
| Slow queue timelock              | 14 hours           |
| Polygon finality wait (deposits) | \~3 minutes        |
| Guardian set size                | 4                  |
| Withdrawal signature threshold   | 4 of 4             |
| Deposit signature threshold      | 4 of 4             |

## Contract Addresses

| Contract                         | Address                                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| ParlayIt bridge (Polygon, proxy) | [`0x33c8d5a7fbef76fd1c71713b769b3744662bc94a`](https://polygonscan.com/address/0x33c8d5a7fbef76fd1c71713b769b3744662bc94a) |
| Bridge implementation (Polygon)  | [`0x22FaFe583468dBa03d88685fB92842447d02083E`](https://polygonscan.com/address/0x22FaFe583468dBa03d88685fB92842447d02083E) |

The proxy address is the contract you interact with when depositing or withdrawing. It is the address that receives your USDC on deposit and releases it on withdrawal. The proxy delegates calls to the implementation contract, which can be upgraded by the owner multisig.