smom-dbis-138/docs/channels/PAYMENT_CHANNELS_ARCHITECTURE.md

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

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. 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.