# State Channels vs Payment Channels

This repo implements **payment channels** and (optionally) a **generic state channel** for committed state. Here is how they relate and when to use each.

---

## Definitions

### Payment channels

- **State** = two participants’ balances (and a nonce).
- **Off-chain**: Parties exchange signed balance updates; no on-chain tx until close.
- **Settlement**: On-chain contract distributes ETH according to the last signed (balanceA, balanceB).
- **Use cases**: Payments, micropayments, streaming, simple value transfer.

### State channels (general)

- **State** = arbitrary application state (e.g. game board, escrow conditions, multi-step agreement).
- **Off-chain**: Parties exchange signed state updates; state transition rules are agreed by the app.
- **Settlement**: On-chain contract verifies that the final state was signed by both and (if value is involved) distributes accordingly.
- **Use cases**: Turn-based games, conditional payments, complex protocols.

**Payment channels are a subset of state channels** where the only state is the two balances.

---

## What this repo provides

| Component | Type | State | Use when |
|-----------|------|--------|----------|
| **PaymentChannelManager** | Payment channel | (balanceA, balanceB, nonce) | Same-chain payments, micropayments, streaming. |
| **GenericStateChannelManager** | State channel (optional) | stateHash + (balanceA, balanceB, nonce) | You need to commit to an off-chain state (e.g. game, attestation) and still settle balances; stateHash proves what was agreed. |
| **External protocols** | Various | Depends (Connext, Raiden, Statechannels.org) | Cross-chain, routed payments, or full state-channel frameworks. |

We do **not** implement a full general-purpose state channel VM (arbitrary transitions verified on-chain). For that, use or integrate [Statechannels.org](https://statechannels.org/) or similar (see [EXTERNAL_PROTOCOL_INTEGRATION.md](EXTERNAL_PROTOCOL_INTEGRATION.md)).

---

## Do you need both?

- **Payments only** → **PaymentChannelManager** is enough.
- **Payments + proof of agreed state** (e.g. hash of game result or attestation) → use **GenericStateChannelManager** so settlement commits to a `stateHash` as well as balances.
- **Arbitrary state transitions verified on-chain** → use an external state channel framework (Statechannels.org, etc.) and link from our docs/UI.

See [README.md](README.md) for the full index of channel docs and [EXTERNAL_PROTOCOL_INTEGRATION.md](EXTERNAL_PROTOCOL_INTEGRATION.md) for external options.
