CIP-104 rewards-accounting walkthrough script

[pepebndc]

What

Two artifacts telling the same CIP-0104 rewards-accounting story, one on each side of the ledger boundary:

1. A narrated on-ledger walkthrough (Cip0104RewardsWalkthrough.daml) adds test_cip0104_rewardsAccountingWalkthrough, a step-by-step script showing:

• which functions an integrator calls: mint (ToyHolding create), SettlementFactory_CreateAllocationInstruction + AllocationInstruction_Accept per side, SettlementFactory_SettleBatch by the app-provider executor;
• balances and accumulated rewards before/after each action: every step logs issuer-view balances, the app-provider's attributed activity (settlements, settled volume, holdings-change events) derived purely from SettlementReceipt + SettlementEventLogEntry queries, and an illustrative accrued reward;
• that only confirmed executor activity accrues: a non-executor's settle attempt fails and the counters do not move (and alice's spendable balance visibly dips while her holding is locked in the pending allocation);
• round-close distribution: the accrued reward is split across declared beneficiaries (venue 0.7 / instrument registrar 0.2 / validator operator 0.1), shares conserve the total.

Registered in the LocalNet gate (scripts/localnet-cip-interop-validation.sh, now 12 scripts) with the CIP-0104 row updated in LOCALNET.md.

2. A fully off-chain client (app-rewards/harness.mjs + README) that consumes the settlement surface the way real CIP-0104 reward infrastructure would: a Node harness driving mint, allocation, and settlement over the JSON Ledger API v2 (factory handed to the executor as a disclosed contract), deriving attribution and the accrued reward purely from Ledger API reads. It replays the same six steps and asserts the same numbers as the Daml walkthrough, so the on-ledger executable spec and the off-chain consumer stay in lockstep. Launched by scripts/localnet-cip0104-rewards-walkthrough.sh (wallclock sandbox, no deadline, mirrors the wallet-gateway gate's structure).

In both artifacts the reward math is clearly-labeled illustrative stand-ins for CIP-0104's off-ledger traffic-proportional CC calculation (deferred to M2, per the DEX reference architecture section 6.2), and no reward-marker templates are introduced, preserving the exemplar's core CIP-0104 property.

Why

The existing Cip0104AppRewards scripts prove the structural properties but do not narrate how rewards are distributed and accounted for. The walkthrough pair gives integrators both the ledger-side spec and a concrete off-chain consumer of it (coordinated with Ionut).

Validation

dpm build --all                                    # compiles
scripts/check-lint.sh                              # no hints
scripts/check-docs.sh                              # 308 local links OK
cd experiments/interoperability/cip-exemplar && dpm test   # 15/15 scripts pass
scripts/localnet-cip-interop-validation.sh         # 12/12 on a static-time Canton sandbox (2026-08-07, SDK 3.4.11)
scripts/localnet-cip0104-rewards-walkthrough.sh    # off-chain harness passes, numbers match the Daml walkthrough

Sample narrative (identical from both artifacts):

== step 1: app settled alice -> bob 30 USD ==
balances (issuer view): alice=70 USD, bob=30 USD, totalSupply=100 USD
attribution (app view): settlements=1, settledVolume=30 USD, holdingsChangeEvents=2
accrued reward (illustrative): 0.3 CC
...
== step 5: round closes, reward distributed (illustrative) ==
venue (app-provider): 0.42 CC
instrument registrar: 0.12 CC
validator operator: 0.06 CC

🤖 Generated with Claude Code