CIP-8: MPP Session (Retroactive)

Payer (signer)                   Runner (HTTP endpoint)             SESSION_ACTOR (0x0C)
       │                                  │                                  │
       │── tx: OpenSession (max_amount) ──────────────────────────────────▶  │
       │                                  │                                  │ escrow max_amount
       │                                  │   ◀──── SessionOpened event ───  │
       │                                  │   (cached locally)               │
       │                                  │                                  │
       │── HTTP request + voucher_k ─────▶│                                  │
       │   ◀────── response_k + ack ──────│                                  │
       │   (repeat N times, voucher_k.cumulative_amount monotonic)           │
       │                                  │                                  │
       │                                  │── tx: Settle (voucher_max) ─────▶│
       │                                  │                                  │ verify voucher → split
       │                                  │                                  │   89% → runner
       │                                  │                                  │   10% → burn (0x00)
       │                                  │                                  │   1%  → treasury (0x08)
       │                                  │   (repeat at runner discretion)  │
       │── tx: CloseSession ────────────────────────────────────────────────▶│
       │                                  │                                  │ status = Closing
       │   (DISPUTE_WINDOW_BLOCKS = 75 blocks)
       │                                  │                                  │
       │── tx: Finalize  (anyone) ──────────────────────────────────────────▶│
       │                                  │                                  │ refund (max_amount - spent)
       │                                                                     │ status = Refunded | Settled

SESSION_ACTOR_ADDRESS = 0x0C

key = b"session:" || session_id   // 8-byte prefix + 32-byte id; total 40 bytes
val = bincode(Session)             // see §6.1

struct Session {
    session_id:            [u8; 32],       // payer-chosen, see §6.3
    payer:                 Address,        // signs vouchers; funded escrow
    runner:                Address,        // receives 89% of settled amount
    asset:                 SessionAsset,   // CBY (PoC) | Cip20(token_addr) | future
    max_amount:            u128,           // escrow ceiling; spent <= max_amount enforced
    deposit:               u128,           // current escrow balance
    spent:                 u128,           // cumulative settled so far
    last_voucher_nonce:    u64,            // monotonicity guard
    price_advert_digest:   [u8; 32],       // hash of off-chain price advert
    expires_at_block:      u64,            // block height after which Close is enforced
    opened_at_block:       u64,
    status:                SessionStatus,  // see §6.2
}

enum SessionStatus {
    Open,                                     // accepting Deposit / Settle
    Closing { closed_at: u64 },               // dispute window, still accepting Settle
    Disputed { ... },                         // transient — Slash invoked, awaiting CIP-2 verdict
    Settled,                                  // terminal — runner took everything
    Refunded,                                 // terminal — payer got change back
    Slashed { ... },                          // terminal — dispute won by payer; future work
}

session_id = keccak256(payer || runner || nonce || open_block_height)

enum SessionAsset {
    Cby,                       // native CBY (PoC default)
    Cip20(Address),            // CIP-20 fungible token (future)
}

struct SessionVoucher {
    session_id:        [u8; 32],
    cumulative_amount: u128,            // total owed at this point; >= previous voucher
    nonce:             u64,             // strictly increasing per session
    expires_at:        u64,             // block height; settle rejects after this
    usage_digest:      [u8; 32],        // keccak256(off-chain usage_log); auditable
    signature:         [u8; 65],        // secp256k1 (r, s, v) over EIP-712 digest
}

EIP712Domain {
    name:              "Cowboy MPP Session",       // DOMAIN_NAME
    version:           "1",                         // DOMAIN_VERSION
    chainId:           COWBOY_SESSION_CHAIN_ID,    // PoC: 1 (V-13 — see §13)
    verifyingContract: <SESSION_ACTOR_ADDR as 20-byte padded>
}

Voucher(bytes32 session_id, uint128 cumulative_amount, uint64 nonce, uint64 expires_at, bytes32 usage_digest)

input:  session_id, payer, runner, asset, max_amount, price_advert_digest, expires_at_block
caller: payer (signed tx)
preconditions:
    - !exists(session_id)
    - runner is registered (Runner Registry 0x01)
    - max_amount > 0
    - asset == Cby (PoC); Cip20 → Unsupported
effects:
    - debit payer.balance -= max_amount (escrow into SESSION_ACTOR storage)
    - write Session{ status=Open, deposit=max_amount, spent=0, last_voucher_nonce=0, ... }
    - emit SessionOpened event

input:  session_id, amount
caller: payer (signed tx)
preconditions:
    - session.status == Open
    - amount > 0
effects:
    - debit payer.balance -= amount
    - session.deposit += amount
    - session.max_amount += amount  (extends ceiling)
    - emit SessionDeposited event

input:  session_id, voucher: SessionVoucher
caller: any (typically runner; permissionless on the happy path because the voucher is self-authenticating)
preconditions (per node/execution/src/runner/session.rs:171-291):
    - session.status in {Open, Closing{...}}
    - voucher.session_id == session_id
    - voucher.nonce > session.last_voucher_nonce
    - voucher.cumulative_amount >= session.spent
    - voucher.cumulative_amount <= session.deposit
    - voucher.expires_at >= current_block_height
    - voucher.signature recovers to session.payer (EIP-712 digest from §7.2)
effects:
    - increment = voucher.cumulative_amount - session.spent
    - session.spent = voucher.cumulative_amount
    - session.last_voucher_nonce = voucher.nonce
    - split increment per SettlementConfig (default 89% / 10% / 1%):
        - runner_share to session.runner
        - burn_share  to address(0x00)
        - treasury_share to TREASURY (0x08)
    - emit SessionSettled event

input:  session_id
caller: must be session.payer
preconditions:
    - session.status == Open
effects:
    - session.status = Closing{ closed_at: current_block_height }
    - emit SessionClosing event

input:  session_id
caller: any (permissionless)
preconditions:
    - session.status == Closing{closed_at} OR (status == Open AND current_block > session.expires_at_block)
    - current_block >= closed_at + DISPUTE_WINDOW_BLOCKS  (default 75)
    - no active Disputed{...}
effects:
    - refund_amount = session.deposit - session.spent
    - credit session.payer.balance += refund_amount
    - session.status = Refunded   (if refund_amount > 0) | Settled  (if refund_amount == 0)
    - emit SessionFinalized event

input:  session_id, dispute: SessionDispute
caller: must be session.payer
status (PoC): handler returns ExecutionError::Unsupported
future:       wires into CIP-2 commit-reveal via Result Verifier (0x03);
              successful slash transfers session.deposit - session.spent
              proportions to payer + burn + treasury per slashing policy.

1. Payer calls Slash(session_id, dispute_payload) within DISPUTE_WINDOW_BLOCKS of CloseSession
2. session.status = Disputed{ opened_at: current_block }
3. Result Verifier (0x03) runs CIP-2 verification mode chosen at session OpenSession
   (default: MajorityVote with explicit min-runner = 3)
4. On verdict:
   - Payer wins:  session.status = Slashed; deposit-spent proportions go to payer + burn + treasury
   - Runner wins: session.status = Settled; Finalize releases nothing further to payer
5. Finalize is gated behind status not Disputed.

ActorMessage {
    to: SESSION_ACTOR,
    selector: "session.open" | "session.deposit" | "session.settle" |
              "session.close" | "session.finalize" | "session.slash",
    args: ...
}

pub const COWBOY_SESSION_CHAIN_ID: u64 = 1;