# Payment Channels Architecture

This document describes how payment channels combine with the existing Mainnet Tether and Transaction Mirror on Mainnet and Chain-138.

---

## Overview

- **MainnetTether** and **TransactionMirror** are unchanged. They anchor Chain-138 state proofs and mirror Chain-138 transactions to Mainnet.
- **PaymentChannelManager** is a new contract deployed on both Ethereum Mainnet and Chain-138. It manages payment channels (open, fund, cooperative close, unilateral close with challenge window).
- Channel open/close/update transactions on **Chain-138** are normal on-chain txs: they are mirrored by the existing Transaction Mirroring Service and reflected in state anchored by the State Anchoring Service. No changes to those services or contracts are required.

---

## Architecture Diagram

```mermaid
flowchart LR
  subgraph mainnet [Ethereum Mainnet]
    MT[MainnetTether]
    TM[TransactionMirror]
    PC_M[PaymentChannelManager]
  end
  subgraph chain138 [Chain 138]
    PC_138[PaymentChannelManager]
  end
  subgraph offchain [Off-chain]
    Anchor[State Anchoring Service]
    MirrorSvc[Transaction Mirroring Service]
    Watchtower[Watchtower optional]
  end
  Chain138 -->|state proofs| Anchor --> MT
  Chain138 -->|tx data| MirrorSvc --> TM
  PC_138 -->|anchored via| MT
  PC_138 -->|mirrored via| TM
  PC_M -->|optional Connext| Connext
  PC_138 -->|optional Connext| Connext
```

---

## Data Flow

### Same-chain (Mainnet or Chain-138)

1. **Open**: Party A calls `openChannel(participantB)` with `value` (ETH). Optionally party B calls `fundChannel(channelId)` with `value`.
2. **Off-chain updates**: Parties exchange signed state (channelId, nonce, balanceA, balanceB) off-chain. No on-chain tx until close.
3. **Cooperative close**: Either party calls `closeChannelCooperative(channelId, nonce, balanceA, balanceB, vA, rA, sA, vB, rB, sB)`. Contract verifies both signatures and pays out.
4. **Unilateral close**: One party calls `submitClose(...)` with a signed state. Contract enters Dispute and sets a challenge deadline. The other party can call `challengeClose(...)` with a newer state (higher nonce) before the deadline. After the deadline, anyone can call `finalizeClose(channelId)` to distribute according to the last submitted state.

### Chain-138 and Mainnet visibility

- Every channel tx on Chain-138 (open, fund, submitClose, challengeClose, finalizeClose) is a normal transaction. The existing **Transaction Mirroring Service** mirrors these to **TransactionMirror** on Mainnet, so they appear on Etherscan (Mainnet).
- The **State Anchoring Service** anchors Chain-138 state (including contract state of PaymentChannelManager) to **MainnetTether** at intervals. So the state of channels on Chain-138 is reflected in the anchored state roots.

### Optional external protocol (Connext)

- For cross-chain or routed payments, the dApp can integrate **Connext** (or similar). See [EXTERNAL_PROTOCOL_INTEGRATION.md](EXTERNAL_PROTOCOL_INTEGRATION.md). Custom PaymentChannelManager remains for same-chain, direct A↔B channels.

---

## Disputes and security

- **Newest state wins**: In Dispute, only a state with `nonce` strictly greater than the current `disputeNonce` is accepted. This enforces the standard payment-channel guarantee.
- **Challenge window**: Configurable (e.g. 24h). Participants (or a watchtower) must respond before the deadline to submit a newer state.
- **Liveness**: If a participant is offline and the other submits an old state, the offline participant must have a watchtower or come online before the deadline to challenge. See watchtower documentation.

---

## Contracts and config

| Contract | Chain(s) | Purpose |
|----------|----------|---------|
| MainnetTether | Mainnet | Anchor Chain-138 state proofs |
| TransactionMirror | Mainnet | Mirror Chain-138 tx data |
| PaymentChannelManager | Mainnet, Chain-138 | Payment channels (one deployment per chain) |

Frontend config (`contracts.ts`):

- `CONTRACT_ADDRESSES.mainnet.PAYMENT_CHANNEL_MANAGER`
- `CONTRACT_ADDRESSES.chain138.PAYMENT_CHANNEL_MANAGER`

Set these after deploying PaymentChannelManager to each chain. See [PAYMENT_CHANNELS_DEPLOYMENT.md](../deployment/PAYMENT_CHANNELS_DEPLOYMENT.md).