# Guide: Payments, Escrow & Settlement — What You Can Use Today

**Goal:** choose the right on-chain mechanism for money in your app: a one-off payment, held funds released by a
rule, or stakes settled by a game or agreement. The page also says exactly which contracts are live.

For the payment *model* (a crypto floor, with a fiat on-ramp as a labelled enhancement), read
**[Concepts → Payments](../concepts/payments.md)** first. This page covers the contracts.

## Choose

| You need | Use | Status |
|---|---|---|
| The user pays a fixed amount to an address or contract | A declared payable action: `action: { to, sig, value, args }` | Works on every chain. `value` is fixed at compile time (see **[Declare a Safe Action](./declare-action.md)**) |
| Funds held until a rule releases them (fundraise, deposit, bounty, sale) | **Your own contract** in the shape of `GoalEscrow`: per-item parameters, pull payments, single-value views | `contracts/examples/GoalEscrow.sol` is a tested example **that you deploy** (**[Writing an App Contract](./app-contract.md)**) |
| Two players stake on a game, and the winner is paid by the rules | `GameLobbyV2` + `GameChannelV2` | Deployed on Sepolia, Robinhood and Arc (**[Multiplayer & Lobbies](./multiplayer-and-lobbies.md)**) |
| N parties, an arbitrary payout split, off-chain signed transitions (loans, grants, milestones) | The settlement framework: `SettlementChannel`, `AgreementRegistry` / `Erc20AgreementRegistry`, `LoanChannel`, `AttestedLoanChannel`, `EthStakeVault` / `Erc20StakeVault` | Built and tested; **not deployed**. Read the pre-deploy note below |
| Show a payment's or position's state | Resolver kinds: `balance`, `erc20balance`, `price`, `vault4626`, … | See **[Resolver Kinds](../reference/resolver-kinds.md)**. Each kind says whether its contract is deployed |
| A claimable tip link (TipLink) | — | **Design only** (`docs/158`). There is no TipLink contract; do not build on one |

Whether a contract is live is decided by **[Deployed Addresses](../reference/addresses.md)**: a generated page with
a "Built, not deployed on any chain" section. If a contract is not listed with an address, an app cannot call it.

## Holding funds in your own contract

These rules come from `GoalEscrow` and its tests (`test/GoalEscrow.ts`):

- **Pull, don't push.** Each party calls to take what it is owed. Zero their balance before the transfer.
- **Decide the outcome from on-chain facts only.** Use the time, the amounts and the rules in your contract. If a
  release depends on something off-chain (a delivery, a court, a sensor), the chain cannot check it. Name who
  attests it, and grade the app accordingly.
- **No admin escape hatch.** A contract with an owner who can sweep funds is custodial, whatever the page says.
- **Native token or ERC-20.** `GoalEscrow` uses the native token: ETH on Sepolia and Robinhood, USDC on Arc. For an
  ERC-20, follow `Erc20StakeVault`'s rule and verify every transfer by balance delta, so a token that returns
  `false`, returns nothing, or charges a fee cannot short the escrow.

## The settlement framework (built, not deployed): pre-deploy note

`SettlementChannel` generalises the v1 game channel to N parties and an arbitrary `distribution(state)`. Reading
its source shows it carries the same design that `GameChannelV2` replaced (`docs/185`). Each item needs a fix and a
test before it is deployed (verify):

1. **`settleWithHistory` accepts any signed prefix, including the empty one** (lines 184–197). The payout is then
   `distribution(state)` of that prefix. That is safe only if the rules make every reachable state's distribution
   acceptable to everyone, which most real agreements do not.
2. **Signatures are checked through ERC-1271 at the time of use** (`_isValidSig`). A contract party can switch its
   signatures off and on, so the history it signed can be hidden from the other parties.
3. **There is no force-move.** A party who stops responding cannot be made to act. A dispute ends only through the
   arbiter (if one is named) or a co-signed close.

`LoanChannel` and `AttestedLoanChannel` move funds by on-chain transactions, not by signed histories, so items 1
and 2 do not apply to them. They have not yet had a security review of their own (verify). Until those reviews and redeployments happen, use your own escrow contract for funds and
`GameChannelV2` for games.

## Related

- **[Concepts → Payments](../concepts/payments.md)** · **[Writing an App Contract](./app-contract.md)** ·
  **[Multiplayer & Lobbies](./multiplayer-and-lobbies.md)**
- **[Deployed Addresses](../reference/addresses.md)** · `docs/172` (the settlement framework design) · `docs/185`