docs(cch): clarify SwapProposal btc_amount_msat and add ReceiveBTC fee example

Cross-review against the implementation surfaced two documentation
gaps in the multi-asset swap spec.

* Section 5.6 implied the SwapProposal's btc_amount_msat for SendBTC
  was the raw Bolt11 amount, but the actor sends the total payout
  (Bolt11 amount + configured fee). Clarify the field semantics and
  note that the raw Bolt11 amount can be recovered as
  btc_amount_msat - fee_on_btc_side_msat.
* Section 6.2 left ReceiveBTC proposal-path operators to infer how
  to combine the configured fee with their chosen rate. Add a worked
  formula and numeric example matching the fast-path computation, so
  operators have a reference implementation for the BTC-leg amount
  they submit.

Author: ian

docs/specs/cch-multi-asset-swap.md

@@ -180,9 +180,11 @@ A `SwapProposalResponse` carries either a rejection or an acceptance that includ
 
 - `proposal_id` (must match a pending proposal previously notified to this client),
 - `accept` (boolean),
-- `counterparty_leg_amount` (REQUIRED when `accept` is true; smallest-unit integer in the counterparty leg’s asset),
+- `counterparty_leg_amount` (REQUIRED and **must be > 0** when `accept` is true; smallest-unit integer in the counterparty leg’s asset),
 - `reject_reason` (optional string; logged by the hub and returned to the swap client as the failure reason when `accept` is false).
 
+A response is **valid** when it parses, references a pending `proposal_id`, and \u2014 if `accept` is true \u2014 carries a positive `counterparty_leg_amount`. The first valid response resolves the proposal; later responses for the same `proposal_id` return `SwapProposalUnknown`. A malformed accept (missing or zero `counterparty_leg_amount`) is rejected with `SwapProposalResponseMissingAmount` / `SwapProposalResponseInvalidAmount` but **leaves the proposal pending** so the operator may correct and resubmit before the timeout elapses.
+
 ### 5.4 Timeout
 
 - If no operator submits a valid `SwapProposalResponse` for a given `proposal_id` within `swap_proposal_timeout_seconds` (CCH config), the proposal is treated as **rejected** (same outcome as `accept: false`) with reason `acceptor_timeout`.
@@ -227,7 +229,7 @@ Fields delivered to subscribers (see `SwapProposal` in `fiber-types`):
 | `payment_hash` | Links both legs (derived from the client-submitted invoice). |
 | `fiber_asset` | UDT type script when the Fiber leg is a UDT; absent (or null) when the Fiber leg is native CKB. |
 | `fiber_amount_smallest_unit` | Fiber-leg amount in smallest units when known up-front (parsed from the submitted invoice on `ReceiveBTC`); absent on `SendBTC` because the operator supplies it in their response. |
-| `btc_amount_msat` | Lightning amount in millisatoshis when known up-front (parsed from the submitted Bolt11 on `SendBTC`); absent on `ReceiveBTC` because the operator supplies it in their response. |
+| `btc_amount_msat` | **Total** Lightning amount in millisatoshis the hub will pay out, **inclusive of `fee_on_btc_side_msat`** (i.e. submitted-Bolt11 amount + configured fee), when known up-front on `SendBTC`; absent on `ReceiveBTC` because the operator supplies it in their response. The raw Bolt11 amount can be recovered as `btc_amount_msat - fee_on_btc_side_msat`. |
 | `configured_fee_rate_per_million_sats` | Hub-configured proportional fee in effect for this swap. |
 | `configured_base_fee_sats` | Hub-configured flat base fee in effect for this swap. |
 | `fee_on_btc_side_msat` | Fee attributed to the BTC leg derived from the configured rate, in millisatoshi. For `SendBTC` this is computed from the submitted Bolt11; for `ReceiveBTC` it is reported as `0` because it depends on the operator-set BTC-leg amount — the operator is responsible for accounting for the configured rate/base when choosing the counterparty amount. |
@@ -269,6 +271,28 @@ The swap client submits the **Fiber invoice** they want the hub to pay on the Fi
 5. Continue with the existing order machinery.
 6. Return the order with the Lightning hold invoice attached; the swap client (if the amount is acceptable) forwards it to the user-side payer.
 
+#### Worked example: ReceiveBTC proposal-path operator math
+
+For a `ReceiveBTC` proposal the hub reports `fee_on_btc_side_msat = 0` because it cannot compute the fee until the operator picks a BTC-leg amount. The operator’s `counterparty_leg_amount` is taken as the **final** BTC-leg amount in millisatoshi (fee included). A reference computation that mirrors the fast path is:
+
+1. Choose an effective BTC/asset rate $r$ in **fiber smallest units per satoshi** (the operator’s FX/inventory decision).
+2. Convert the submitted Fiber-leg amount to a fee-exclusive BTC amount:
+   $$\text{btc\_msat\_pre\_fee} = \frac{\text{fiber\_amount\_smallest\_unit} \times 1000}{r}$$
+3. Apply the hub’s configured fee:
+   $$\text{fee\_msat} = \Big\lfloor \frac{\text{btc\_msat\_pre\_fee} \times \text{configured\_fee\_rate\_per\_million\_sats}}{1\,000\,000} \Big\rfloor + \text{configured\_base\_fee\_sats} \times 1000$$
+4. Submit:
+   $$\text{counterparty\_leg\_amount} = \text{btc\_msat\_pre\_fee} + \text{fee\_msat}$$
+
+Concretely, given `fiber_amount_smallest_unit = 1_000_000` shannons, $r = 1$ shannon/sat, `configured_fee_rate_per_million_sats = 1000` (0.1 %), and `configured_base_fee_sats = 10`:
+
+- `btc_msat_pre_fee = 1_000_000 * 1000 / 1 = 1_000_000_000` msat
+- `fee_msat = 1_000_000_000 * 1000 / 1_000_000 + 10 * 1000 = 1_000_000 + 10_000 = 1_010_000` msat
+- `counterparty_leg_amount = 1_001_010_000` msat
+
+Operators MAY price more aggressively (larger `r`, larger fee) to cover FX/inventory risk. The hub does not validate the chosen rate — the swap client is the final gate by accepting or refusing to forward the minted Lightning hold invoice.
+
+The symmetric `SendBTC` proposal already includes `btc_amount_msat` (Bolt11 amount + configured fee) and `fee_on_btc_side_msat`, so the operator’s task there is purely the BTC→asset conversion at their chosen rate.
+
 ## 7. Security and operations
 
 - **Preimage release**: Preserve ordering guarantees so the hub does not strand funds (same class of concerns as current CCH).