Recourse

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

Recourse handles disputes that rest on objective facts only. A case names one fact the core can check; its outcome is computed from that fact, never from either party's say-so; and the only money a case moves is a terms-breach refund through the existing refund path, never above the amount you dispute. Proven work stays paid.

Recourse is on owner-api 1.8.0. On the hosted tier, pin Dynamo-Version: 1.8.0 to reach these routes. Status: Live; terms_breach cases are Preview: they need a core with a terms catalogue (CORE_TERMS_CATALOGUE_FILE, which needs CORE_VERIFIED=1; both off by default).

What a case can be about

KindThe factHow it resolves
terms_breacha breach report, signed by a catalogue signer you opted into, that shows a breach of the stream's catalogue termsthe stream's breach refund returns the value streamed after the breach, if that cannot exceed your disputed units; otherwise, or when that value is already final, the case escalates and nothing moves
non_deliverya Task Allowance milestone of the streaman expired or rejected milestone's units went back when its task closed: the case records that refund; delivered and accepted work is the payee's (no refund); until the task settles the milestone, resolve refuses (recourse_pending)
payment_mismatcha payment record of the streama payment matching its signed voucher is no refund; one that does not match has no refund path in the protocol, so the case escalates with the facts

A report that does not show a breach, a milestone of another stream, or a payment record the stream does not carry is refused (recourse_claim_invalid). One fact carries at most one open case.

Life of a case

  1. Open. You open the case with the fact and your disputed units. The core attaches the budget's evidence bundle at that moment and signs its hash into the case. For a terms breach, the report is admitted now and the stream stops at the breach, as it does when the report arrives on the breach route; nothing is refunded yet.
  2. Answer (optional). The stream's payee answers with its own signature: concede or contest, and optionally a hash of the facts it points to. The answer is recorded; it does not decide anything.
  3. Resolve. The core computes the outcome from the fact: refunded (with the refund's reference and units) or no_refund (with its basis). When the fact allows no refund path, resolve escalates instead.
  4. Escalate. Either party can escalate an open or answered case. The core exports a package for an external arbitrator: the case's signed records, the evidence bundle attached at open, and the facts it read, with the package's hash signed into the escalation.

A resolved or escalated case is final.

Routes

RouteWhat it does
POST /owner/v1/recourse/casesopen: {kind, budgetId, streamId, disputedUnits} plus breachReport, taskId and milestoneId, or paymentRecordHash
GET /owner/v1/recourse/casescases (?budgetId= narrows)
GET /owner/v1/recourse/cases/:idone case: state, outcome, escalation
GET /owner/v1/recourse/cases/:id/recordsits signed records
POST /owner/v1/recourse/cases/:id/resolvecompute the outcome
POST /owner/v1/recourse/cases/:id/escalateescalate
GET /owner/v1/recourse/cases/:id/packagethe arbitrator package of an escalated case
GET /payee/v1/recourse/cases/:idthe payee's view (its own streams only)
POST /payee/v1/recourse/cases/:id/answer{answer, signature}: the payee's signed answer
POST /payee/v1/recourse/cases/:id/escalatethe payee escalates

The payee routes take the payee's own Dynamo-Payee v2 proof for that request (how to sign one) or a payee credential; a case on another payee's stream answers 404.

Records and evidence

Every transition is one record signed by the core and linked to the case's previous record. The budget's evidence export carries its cases' records, and both offline verifiers check them: signatures, links, the payee's signature on its answer, nothing after a case ends, and no terms refund above the disputed units.

What offline verification covers. The verifier checks every signature and digest in the file. On its own the file does not prove billing: the engine-signed records do not yet bind each stream's session key. Verification is complete when you pair it with the on-chain settlement or with the engine-signed payment records. It is weakest on Control Mode and the credit card rail, where there is no chain to check.

A payment that does not match its voucher makes the budget's evidence fail verification (the verifier names it payment_voucher); a case about it attaches the bundle together with the verifier's failures, which are the fact at issue.