CIP 0104: Traffic Weighted App Rewards: Serve App Activity Records and Traffic Summarys from /v0/events by adetokunbo · Pull Request #4154 · hyperledger-labs/splice

adetokunbo · 2026-02-26T06:04:35Z

Follows-up from #4037

N.B. #4037 is not yet merged, so this contains all it's commits. It will be submitted before this one is, in the meantime please review the latest commits on this PR

Pull Request Checklist

Cluster Testing

If a cluster test is required, comment /cluster_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.
If a hard-migration test is required (from the latest release), comment /hdm_test on this PR to request it, and ping someone with access to the DA-internal system to approve it.

PR Guidelines

Include any change that might be observable by our partners or affect their deployment in the release notes.
Specify fixed issues with Fixes #n, and mention issues worked on using #n
Include a screenshot for frontend-related PRs - see README or use your favorite screenshot tool

Merge Guidelines

Make the git commit message look sensible when squash-merging on GitHub (most likely: just copy your PR description).

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

dfordivam

we possibly also need to add two "enable" flags in request, and disable serving these by default with events

dfordivam · 2026-02-26T06:19:55Z

apps/scan/src/main/openapi/scan.yaml

+      description: |
+        Computed app activity record derived from verdicts and traffic summaries.
+        Each record represents the traffic-weighted activity of featured app providers at a given record_time,
+        and is derived from a computation involving the verdict and traffic summary data.


We could mention CIP-0104 here

Possible, but at the moment it does not look like a CIP number is mentioned in any other open API descriptions, so this would be the first

dfordivam · 2026-02-26T06:20:48Z

apps/scan/src/main/openapi/scan.yaml

+        - total_traffic_cost
+        - envelope_traffic_costs
+      properties:
+        sequencing_time:


Not sure if we really need to include this

Neither am I. @meiersi-da should we replicate fields like sequencing time, and in the activity record record time that can be obtained from the verdict ?

I think sequencing_time is special. It serves as the primary key for the events themselves. The right place might be to serve it on the EventHistoryItem itself.

That said: I'm not sure. It really depends on the access patterns that we want to make easily possible. Let's have a quick chat in our sync meeting.

dfordivam · 2026-02-26T06:27:21Z

apps/scan/src/main/scala/org/lfdecentralizedtrust/splice/scan/admin/http/HttpScanHandler.scala

-          .map(toUpdateV2)
-        val verdictEncoded = verdictWithViewsO.map { case (v, views) =>
-          ScanHttpEncodings.encodeVerdict(v, views)
+        items <- Future.traverse(events) { case (verdictWithViewsO, updateO) =>


How about doing a batch read of activity records?
Given that the activity records are also being provided by the ScanEventStore, modifying the getEvents may be better?

apps/scan/src/main/scala/org/lfdecentralizedtrust/splice/scan/store/db/DbScanVerdictStore.scala

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

adetokunbo · 2026-02-26T07:00:03Z

we possibly also need to add two "enable" flags in request, and disable serving these by default with events

These have been added.

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

meiersi-da · 2026-02-26T07:22:33Z

apps/scan/src/main/openapi/scan.yaml

        If an event pertains to a contract reassignment, there will be no verdict data.
        If an event pertains to a wholly private transaction, there will only be verdict data.
        If an event pertains to a transaction that is partially private, it may also bear verdict information for the private portions.
        When both fields are present, the transaction and verdict have the same `update_id` and `record_time`.


Update this comment as well wrt traffic summaries and activity records.

meiersi-da

Thanks. Did a quick review of the API parts only as prep for our meeting.

meiersi-da · 2026-02-26T07:27:20Z

apps/scan/src/main/openapi/scan.yaml

+          items:
+            type: integer
+            format: int32
+    EventHistoryAppActivityRecord:


Suggested change

EventHistoryAppActivityRecord:

EventHistoryAppActivityRecords:

meiersi-da · 2026-02-26T07:28:29Z

apps/scan/src/main/openapi/scan.yaml

+      properties:
+        record_time:
+          description: |
+            The record_time (= sequencing_time) of the verdict/traffic summary.


Yeah, OK. This hints very much at pushing the sequencing_time of the confirmation request to the top-level.

Fixed, as discussed in the meeting

apps/scan/src/main/openapi/scan.yaml

meiersi-da · 2026-02-26T07:29:54Z

apps/scan/src/main/openapi/scan.yaml

+          format: int64
+        entries:
+          description: |
+            App activity entries, one per featured app provider.


Suggested change

App activity entries, one per featured app provider.

App activity entries, one per app provider.

we'll want this API to also work when we start to support unfeatured app providers: https://github.com/canton-foundation/cips/blob/main/cip-0104/cip-0104.md#rewards-for-unfeatured-apps

Done, and in 2 other locations in the change.

meiersi-da · 2026-02-26T07:31:37Z

apps/scan/src/main/openapi/scan.yaml

+        Computed app activity record derived from verdicts and traffic summaries.
+        Each record represents the traffic-weighted activity of featured app providers at a given record_time,
+        and is derived from a computation involving the verdict and traffic summary data.


Suggested change

Computed app activity record derived from verdicts and traffic summaries.

Each record represents the traffic-weighted activity of featured app providers at a given record_time,

and is derived from a computation involving the verdict and traffic summary data.

App activity record compted from verdicts and traffic summaries

as per [CIP-104](https://github.com/canton-foundation/cips/blob/main/cip-0104/cip-0104.md).

Minimize specificity to make the API hold up when we evolve rewards further. Referring to CIP-104 seems fine though, as we can just replace it with a reference to the new CIP that changes it.

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

adetokunbo · 2026-02-26T09:34:50Z

@meiersi-da PTAL, the outstanding comments should all be addressed, and I also removed duplicate fields as discussed earlier

meiersi-da

Thanks. Looks good. Looking forward to seeing this code pass an integration test.

meiersi-da · 2026-02-26T10:01:24Z

apps/scan/src/main/openapi/scan.yaml

        If an event pertains to a wholly private transaction, there will only be verdict data.
        If an event pertains to a transaction that is partially private, it may also bear verdict information for the private portions.
        When both fields are present, the transaction and verdict have the same `update_id` and `record_time`.
+        A traffic summary is present when sequencer traffic cost data is available for the verdict's confirmation request.


Suggested change

A traffic summary is present when sequencer traffic cost data is available for the verdict's confirmation request.

**Experimental**: for networks where the SVs enable activity record

computation, a traffic summary and app activity record are present when

a verdict is present.

This support is experimental while the preview phase of CIP-104

is running.

I know we internally have a finer grained configuration. I'd not communicate this as the intention is to enable both of them at all times, but we might disable one of them in case of problems. No need for users to care about the exceptional circumstance.

meiersi-da · 2026-02-26T10:01:33Z

apps/scan/src/main/openapi/scan.yaml

+        An app activity record is present when the verdict is successful and involves app providers.
+        When present, both the traffic summary and app activity record correspond to the verdict's record_time.


Suggested change

An app activity record is present when the verdict is successful and involves app providers.

When present, both the traffic summary and app activity record correspond to the verdict's record_time.

meiersi-da · 2026-02-26T10:02:45Z

apps/scan/src/main/openapi/scan.yaml

+            **EXPERIMENTAL**: This property is experimental and subject to change. Data may be incomplete or missing.
+          $ref: "#/components/schemas/EventHistoryTrafficSummary"
+          nullable: true
+        app_activity_record:


Suggested change

app_activity_record:

app_activity_records:

meiersi-da · 2026-02-26T10:02:58Z

apps/scan/src/main/openapi/scan.yaml

+      properties:
+        round_number:
+          description: |
+            The round number assigned to the activity record.


Suggested change

The round number assigned to the activity record.

The round number assigned to the activity records.

meiersi-da · 2026-02-26T10:03:07Z

apps/scan/src/main/openapi/scan.yaml

+        as per [CIP-104](https://github.com/canton-foundation/cips/blob/main/cip-0104/cip-0104.md).
+      required:
+        - round_number
+        - entries


Suggested change

- entries

- records

here and in related names

reason for using record is whitepaper, page 12 scoping an activity record to a single app

meiersi-da · 2026-02-26T10:04:27Z

apps/scan/src/main/openapi/scan.yaml

+          type: array
+          items:
+            $ref: "#/components/schemas/AppActivityEntry"
+    AppActivityEntry:


Suggested change

AppActivityEntry:

AppActivityRecord:

meiersi-da · 2026-02-26T10:04:43Z

apps/scan/src/main/openapi/scan.yaml

+    AppActivityEntry:
+      type: object
+      description: |
+        A single app provider's activity weight.


Suggested change

A single app provider's activity weight.

Activity record for an app.

meiersi-da · 2026-02-26T10:10:57Z

.../src/main/scala/org/lfdecentralizedtrust/splice/scan/store/db/DbAppActivityRecordStore.scala

+  )(implicit tc: TraceContext): Future[Map[CantonTimestamp, AppActivityRecordT]] = {
+    if (recordTimes.isEmpty) Future.successful(Map.empty)
+    else {
+      val inClause = sqlCommaSeparated(recordTimes.map(rt => sql"$rt"))


@rautenrieth-da : what is our guidance of using in-clauses with many parameters, vs using ANY(array)? AFAIR, the latter has lower query parsing overhead, and better planner cache hits...

Fixed. I updated this to ANY(array) via the inClause function. Details in f61dbcd

Thanks! Using the inClause() helper is definitely the right thing to do here.

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

- needed to add an implicit for setting arrays of timestamps to AcsJdbcTypes Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Tim Emiola and others added 10 commits February 26, 2026 03:24

Add traffic summary as part of EventHistoryItem in scan.yaml

959b2fe

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Serve traffic summaries in /v0/events

c7e1368

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Add app activity record as part of EventHistoryItem in scan.yaml

7c0c28a

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Serve app activity records in /v0/events

b211496

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Update traffic cost description in scan.yaml

f40ea81

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Update traffic summary description in scan.yaml

3a9596a

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Update description of the app activity record mining round in scan.yaml

6ef7bb0

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Add experimental note for the new properties

12999cb

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Pair the party and weight in the app activity record

02df4e9

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Update description of view IDs in scan.yaml

f22220f

Co-authored-by: Divam <681060+dfordivam@users.noreply.github.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

github-actions bot assigned isegall-da, martinflorian-da, rautenrieth-da and ray-roestenburg-da Feb 26, 2026

dfordivam assigned dfordivam and unassigned rautenrieth-da, ray-roestenburg-da, isegall-da and martinflorian-da Feb 26, 2026

dfordivam changed the base branch from dfordivam/feat-cip-104-activity-records to dfordivam/adetokunbo/cip-0104-composite-ingestion February 26, 2026 06:14

dfordivam self-requested a review February 26, 2026 06:18

dfordivam reviewed Feb 26, 2026

View reviewed changes

Gate serving on config flags

957b5ac

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Fetch the app activity records in a batch

990cc5e

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

meiersi-da reviewed Feb 26, 2026

View reviewed changes

adetokunbo and others added 3 commits February 26, 2026 16:36

Update mining round description in scan.yaml

9234cf5

Co-authored-by: Simon Meier <simon@digitalasset.com> Signed-off-by: Timothy Emiola <adetokunbo@users.noreply.github.com>

Update EventHistoryItem in scan.yaml

0da8143

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

s/featured app provider/app provider/

ea8a4af

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Tim Emiola added 3 commits February 26, 2026 07:50

s/EventHistoryAppActivityRecord/EventHistoryAppActivityRecords/

e57a1c6

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Update description of EventHistoryAppActivityRecords to include CIP-104

221a16a

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Remove sequencing time and distinct record time

19604d8

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

meiersi-da reviewed Feb 26, 2026

View reviewed changes

Tim Emiola added 4 commits February 26, 2026 12:02

s/app_activity_record/app_activity_records/

dcbe067

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Update EventHistoryItem description

effeb79

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

s/entries/records/ and similar changes

b0b392b

Signed-off-by: Tim Emiola <adetokunbo@emio.la>

Use ANY(array) via the inClause function

d0879d7

- needed to add an implicit for setting arrays of timestamps to AcsJdbcTypes Signed-off-by: Tim Emiola <adetokunbo@emio.la>

adetokunbo force-pushed the adetokunbo/cip-0104-serve-other-info-in-events-api branch from f61dbcd to d0879d7 Compare March 2, 2026 04:03

	EventHistoryAppActivityRecord:
	EventHistoryAppActivityRecords:

	App activity entries, one per featured app provider.
	App activity entries, one per app provider.

-        A traffic summary is present when sequencer traffic cost data is available for the verdict's confirmation request.
+        **Experimental**: for networks where the SVs enable activity record
+        computation, a traffic summary and app activity record are present when
+        a verdict is present.
+        This support is experimental while the preview phase of CIP-104
+        is running.

		An app activity record is present when the verdict is successful and involves app providers.
		When present, both the traffic summary and app activity record correspond to the verdict's record_time.

	The round number assigned to the activity record.
	The round number assigned to the activity records.

	A single app provider's activity weight.
	Activity record for an app.

Conversation

adetokunbo commented Feb 26, 2026

Pull Request Checklist

Cluster Testing

PR Guidelines

Merge Guidelines

Uh oh!

dfordivam left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adetokunbo Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adetokunbo commented Feb 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

meiersi-da left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adetokunbo commented Feb 26, 2026

Uh oh!

meiersi-da left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adetokunbo Feb 26, 2026 •

edited

Loading