PoC: extension reward reporting + expansion (Daml)

[timwu20]

Daml PoC of the extension reward integration sketched in the design doc's Section H, stacked on the buy rung (#2). On-ledger pieces only — the SV-side rate computation (tranche split by burn share, the voted per-synchronizer weight, the report timeout) and the operator-side automation stay off-ledger and are not part of this PR.

What this does

Per round, a registered synchronizer's operator commits its activity on the decentralized synchronizer, and later expands that commitment into reward coupons through the existing CIP-104 machinery:

• DedicatedSynchronizerState (new, splice-amulet): per-synchronizer reporting state. The operator's ReportActivity choice records a Merkle root hash over its activity records plus the round total, enforces strictly increasing rounds, accumulates a running total-ever-reported, and creates a per-round ExtensionActivityReport.
• AmuletRules_StartProcessingExtensionRewardsV2 (new choice, vote-dispatched via appended CRARC_StartProcessingExtensionRewardsV2): consumes a report and creates the root ProcessRewardsV2 carrying the report's root hash, the issuance rate computed by DSO automation, the operator as expander, and the report's total as the root weight budget. The vote also attests the synchronizer's total traffic ever purchased, and the choice rejects a report whose lifetime reported activity exceeds it (each report carries the synchronizer's running total, stamped by the report choice). It further requires the report to match a live RegisteredSynchronizer on both synchronizer id and operator, so offboarding (archiving the registration) closes the reward path the same way it closes the buy path, and a duplicate registration under another operator authorizes nothing.
• ProcessRewardsV2 (extended, per Section H "noting that party on the ProcessRewardsV2 contracts" + "push issuance per activity record into process rewards"): appended expander : Optional Party, issuancePerActivityUnit : Optional Decimal, and weightBudget : Optional Decimal; the expander is an observer (it must see the contracts to act) and the controller of ProcessBatch when set; leaf expansion mints coupons at activity weight × rate. Nones everywhere (all existing contracts and the gsync path) is byte-for-byte today's behavior — including that the delegate-based DsoRules_ProcessRewardsV2_ProcessBatch wrapper cannot touch extension contracts.
• BatchOfWeightedBatches (appended Batch constructor) — per review, now the unified format for all reward trees: internal nodes declare each child's subtree weight inside the hashed commitment, and expansion requires exact sums at every level, endowing each child with its declared weight. BatchOfBatches is deprecated (kept so rounds committed before the switch finish processing), and AmuletRules_StartProcessingRewardsV2 gains appended-Optional issuancePerActivityUnit / weightBudget: None is byte-for-byte today's behavior (in-flight vote requests decode fine), Some is the hook the Scala switch uses when Scan starts building weighted trees. A new test runs a decentralized-synchronizer round through the weighted format end to end.

Economic bound

The decentralized synchronizer's own trust does not rest on this because every SV recomputes the full tree before confirming the root — expansion is transcription; under the unified format its trees are budget-pinned too, as defense in depth. An extension tree has a single author the SVs cannot recompute; what stands in is a chain of on-ledger checks, each anchored one level up:

minted  =  Σ committed tree weights  =  round's reported total      lifetime reported  ≤  lifetime purchased
        (B: exact-sum threading)     (B: root budget)               (A: vote-attested cap)

A binds the report to reality: the confirming vote carries the purchased total (from MemberTraffic, which SVs already see), and AmuletRules_StartProcessingExtensionRewardsV2 requires the synchronizer's lifetime reported activity — stamped into every report — to fit within it, so rounds that individually fit cannot together report past what was ever purchased. B binds the tree to the report: the root's budget is the reported total, every internal node's children must sum to exactly its budget, and every leaf's allowances to exactly its own (activity records exist only for reward-eligible providers, so the tree accounts for the full total) — no expansion order or tree shape can mint more or less than what was reported. An operator can still distribute weight among its own parties as it pleases; what it cannot do is mint more than the round's attested activity. Processing is also gated on the live registration matching the report (synchronizer id and operator), so an offboarded synchronizer's outstanding reports can never be turned into minting.

How it's verified (Daml Script)

• TestExtensionRewardReporting (splice-amulet-test): full report → start → expand flow with a two-level weighted tree, coupon amounts = weight × rate; report monotonicity/negative-total/wrong-party negatives; expansion security (tampered pre-image fails the hash check, the DSO party cannot expand extension batches, a leaf cannot be replayed against the wrong hash); economic bound (a report pushing lifetime reported activity past the attested purchased total is rejected, including the multi-round overrun where each round individually fits; internal nodes and leaves must sum exactly to their budgets — over- and under-declaration all fail; a plain unweighted batch cannot smuggle a rate); registration gate (offboarded, wrong-operator, and wrong-synchronizer registrations are all rejected at start-processing).
• TestExtensionRewardVote (splice-dso-governance-test): the governance path — register via vote, report as operator, start processing via a 4-SV supermajority vote, expand, assert the coupon.

Full amulet, wallet, and dso-governance suites pass.

Assumptions (Section H implies but does not pin — flagging for review)

1. Activity weights are Decimal, reusing MintingAllowance as the leaf type, with the weight × rate multiplication in Numeric 10 at expansion. The committed tree is in activity units because the rate does not exist at report time (it depends on all synchronizers' reports and burns).
2. The report lives on a new DedicatedSynchronizerState rather than on RegisteredSynchronizer (Section H says "possibly in registry contract"); kept separate to leave the registration stable. Production wiring of the state's creation (at registration) follows the report-home decision.
3. CalculateRewardsV2 is untouched: the extension flow starts from the report contract; the timeout / count-as-zero behavior is SV-side.
4. providersWithWrongVettingState remains caller-supplied at expansion; extension expansions pass what the operator knows, with the unhide trigger as the correction path.

Tracked in

Implements E10-1 (ChainSafe/canton-extending-mainnet#47); part of Epic E10 (#22). The SV-side integration and operator-side automation are tracked as follow-ups (#57 / #58).

[sadiq1971]

The SV's reward trigger will pick these up and get stuck

ProcessRewardsV2 is shared with the DSO path, and the SV trigger takes any contract of that template where dryRun is false (DbSvDsoStore.scala:797). So it will claim the extension ones too.

It then can't do anything with them: the batch data belongs to the operator, Scan has no way to serve it (GetRewardAccountingBatchResponse has no case for BatchOfWeightedBatches), and controller fromOptional dso expander means the SV isn't authorized anyway.

It's a polling trigger, so it retries forever on whichever SV currently holds the DSO delegate role.

The Daml tests don't catch this because they expand directly as the operator, never through the trigger.

Fix, which I think belongs in this PR since it's what introduces the condition:

and acs.create_arguments->>'expander' is null

The operator's trigger (ChainSafe/canton-extending-mainnet#58) filters the other way, so the two split the work cleanly.

Update: scope correction, this shouldn't land in this PR. E10-1 is Daml-only by design ("don't hook it up and run it"), and the problem is latent anyway: an extension ProcessRewardsV2 only exists once E10-2 starts proposing start-processing votes, so nothing breaks on merge. Raise an issue so the SV-side guard is tracked against E10-2 rather than lost on this thread.

[timwu20]

Update: scope correction, this shouldn't land in this PR. E10-1 is Daml-only by design ("don't hook it up and run it"), and the problem is latent anyway: an extension ProcessRewardsV2 only exists once E10-2 starts proposing start-processing votes, so nothing breaks on merge. Raise an issue so the SV-side guard is tracked against E10-2 rather than lost on this thread.

(full comment)

Agreed on all of it, including the scope correction — the guard is tracked as ChainSafe/canton-extending-mainnet#61 against E10-2, with one addition from verifying your findings: RewardMetricsTrigger reads the unfiltered listProcessRewardsV2() for the backlog gauges, so it needs the same filter or extension contracts pollute the DSO-side metrics. Both are in the issue.

[moritzkiefer-da]

nice work thanks!

[moritzkiefer-da]

So this works conceptually but this means we have a separate vote for each synchronizer each round. As the number of synchronizers increases that might become tricky to scale.

I wonder if instead we could have the svs commit to a hash of all synchronizers and then have a BatchOfSynchronizers` thing and thereby parallelize the expansion on that.

[timwu20]

Agreed on both the problem and the shape. Sketch of your suggestion as we would build it: per round, SV automation aggregates every synchronizer's report into a single commitment — a BatchOfSynchronizers node whose entries carry (root hash, operator, reported total, issuance rate) per synchronizer. One vote per round creates one root ProcessRewardsV2; expanding the synchronizers node fans out into per-synchronizer subtrees, each endowed with its own expander, rate, and weight budget, and from there operators expand their own trees in parallel exactly as in this PR. The per-synchronizer gates (live registration, reported-vs-purchased) come along as entry fields attested by the same vote. This PR's single-synchronizer flow stays as the primitive the fan-out lands on. And if the unification from the other thread happens, this generalizes all the way: one budget-bounded tree per round in which the global synchronizer is just another entry (expander None, recomputed as today) alongside the extensions.

Proposal: track it as the next Daml rung (issue to follow) rather than growing this PR — the fan-out constructor, the endow-children-per-entry expansion arm, and the round-level start-processing choice layer cleanly on top of what is here, and the aggregation automation rides the SV-side integration work. Should we proceed in this direction @moritzkiefer-da?

[moritzkiefer-da]

sgtm thanks

[moritzkiefer-da]

thx

[moritzkiefer-da]

why do we need this on both the extension activity report and the dedicated synchronizer state?

[timwu20]

Three reasons that interlock:

• The state has to hold it because reports do not survive: start-processing consumes the report
  it processes, so the running total needs a carrier that persists across rounds - the state is
  the accumulator ReportActivity adds to.
• The report has to carry it because the gate cannot safely read the state: the vote's action
  record pins contract ids at proposal time, and the state's id changes with every report - a
  report filed while the vote is open would invalidate it and fail the vote at close (the same
  blocking pattern your review found on the offboard vote in PoC: registration lifecycle (offboard vote + reporting-state wiring) #12).
• And the stamped copy is the semantically right value: the state's total is "as of now", but the
  vote authorizes processing one specific round. If the operator has reported rounds 5-7 while
  round 5's vote was pending, the gate should bound round 5's running total, not today's. The
  report freezes exactly that number, in the same transaction that created the report.

So: the state is where the total accumulates, the report is the immutable per-round snapshot
that travels to the vote.