# How It Works

The deal flow from creation to settlement.

---

## The flow

1. **Create a deal** — A deal is defined by a set of recipient wallets and the exact amount (in wei) each one receives. The creator can also set a `referrer` wallet (to receive Shaka's automatic 1% creator bonus) and choose whether the deal requires recipient approval before it can be paid (`verificationRequired`) — both fixed at creation. The contract returns a deal ID.

2. **Approve (optional)** — If the deal was created with `verificationRequired = true`, every recipient must approve it before it can be paid. Each recipient signs the digest returned by `approvalDigest(dealId, recipient, amount)` (an EIP-712 signature); the collected signatures are passed to `pay()`. A deal created without verification skips this step entirely.

3. **Quote** — Before paying, the payer calls `quote(dealId)` to get the exact `grandTotal`, in wei, to send — the recipient amounts plus the referrer and Shaka fee.

4. **Pay** — The payer sends `grandTotal` to the contract's `pay()` function, referencing the deal ID and passing the recipient signatures (an empty array when no verification is required).

5. **Route** — The contract distributes the recipient amounts, the referrer's bonus, and Shaka's fee — all in the same transaction. The transaction is final and irreversible.

A deal can also be **cancelled** by its creator at any point before it's paid — after that, it can never be paid.

## Key properties

- **Single transaction** — recipients, referrer, and Shaka are all settled in one `pay()` call. If a recipient or the referrer transfer fails, the whole payment reverts — nothing moves and nothing is lost.
- **Optional recipient approval** — a deal can require every recipient to approve (EIP-712 signature) before it becomes payable, so no one is paid into a deal they haven't agreed to.
- **Immutable** — the contract cannot be modified after deployment. No admin can change the routing logic or fee rate.
- **Permissionless** — anyone can create a deal or pay into one. No account required.
- **Cancellable, not editable** — the creator can cancel an unpaid deal, but nothing about a deal (recipients, amounts, referrer) can be changed after creation.

## Fee calculation

The fee (routed to the referrer and Shaka) is added on top of the recipient amounts, not deducted from them — recipients always receive their amounts in full. Rather than computing it yourself, call `quote(dealId)` to get the exact total to send:

```javascript
const grandTotal = await shaka.quote(dealId);
await shaka.pay(dealId, signatures, { value: grandTotal });
```

`signatures` is an empty array (`[]`) unless the deal requires recipient approval. See the [Fees](/docs/fees) page for how `grandTotal` breaks down between recipients, referrer, and Shaka.

## Events

Every payment emits a `DealPaid` event:

```solidity
event DealPaid(
  bytes32 indexed dealId,
  address indexed payer,
  uint256 referrerAmount,
  uint256 shakaAmount,
  uint256 grandTotal
);
```

Creating a deal emits `DealCreated`:

```solidity
event DealCreated(
  bytes32 indexed dealId,
  address indexed creator,
  address indexed referrer,
  uint256 total,
  uint256 grandTotal,
  bool verificationRequired
);
```

Cancelling a deal emits `DealCancelled`:

```solidity
event DealCancelled(
  bytes32 indexed dealId,
  address indexed creator
);
```