84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# 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).
|