fix: notification dedup regression causing exchange triple-counting (#148 side-effect)

igorls · igorls · commit a8a7e62d7187 · 2026-03-31T13:09:39.000-03:00
The v4.0 fix for #148 changed the action dedup grouping key to act_digest:action_ordinal, which prevented notification traces from merging with their parent action. This caused get_transaction to return 3 separate transfer entries instead of 1 action with 3 receipts. Indexer: - Use creator_action_ordinal as canonical ordinal for notifications - Notifications (creator>0) group with parent, roots (creator=0) stay separate - Fixes both #148 (distinct duplicates) and notification merging API (backward-compatible, no re-index required): - Add regroupActions() helper to re-merge fragmented data on read - Apply to both v1 and v2 get_transaction handlers - Add 'notified' field to v2 response (comma-separated receivers) Bump to v4.0.5
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hyperion-history",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "description": "Scalable Full History API Solution for Antelope based blockchains",
   "main": "./build/indexer/launcher.js",
   "scripts": {
diff --git a/src/api/helpers/regroup-actions.ts b/src/api/helpers/regroup-actions.ts
@@ -0,0 +1,46 @@
+/**
+ * Re-groups actions that were indexed as separate documents per notification
+ * back into the correct format: one action per unique act_digest + root ordinal,
+ * with all notification receipts merged into a single receipts array.
+ *
+ * This handles both correctly-indexed data (already grouped) and data indexed
+ * with the broken dedup that stored one document per notification.
+ */
+export function regroupActions(actions: any[]): any[] {
+    if (actions.length <= 1) return actions;
+
+    const groups = new Map<string, any>();
+
+    for (const action of actions) {
+        // determine canonical ordinal: notifications group with their parent
+        const creator = action.creator_action_ordinal ?? 0;
+        const ordinal = action.action_ordinal ?? 1;
+        const canonical = creator > 0 ? creator : ordinal;
+        const digest = action.act_digest ?? '';
+        const key = `${digest}:${canonical}`;
+
+        if (groups.has(key)) {
+            // merge receipts into existing group
+            const existing = groups.get(key);
+            if (action.receipts && action.receipts.length > 0) {
+                for (const receipt of action.receipts) {
+                    // avoid duplicates (already-grouped data)
+                    const isDup = existing.receipts.some(
+                        (r: any) => r.receiver === receipt.receiver
+                    );
+                    if (!isDup) {
+                        existing.receipts.push(receipt);
+                    }
+                }
+            }
+        } else {
+            // ensure receipts array exists
+            if (!action.receipts) {
+                action.receipts = [];
+            }
+            groups.set(key, action);
+        }
+    }
+
+    return [...groups.values()];
+}
diff --git a/src/api/routes/v1-history/get_transaction/get_transaction.ts b/src/api/routes/v1-history/get_transaction/get_transaction.ts
@@ -1,6 +1,7 @@
 import {FastifyInstance, FastifyReply, FastifyRequest} from "fastify";
 import {mergeActionMeta, timedQuery} from "../../../helpers/functions.js";
 import {API} from "@wharfkit/antelope";
+import {regroupActions} from "../../../helpers/regroup-actions.js";
 
 
 async function getTransaction(fastify: FastifyInstance, request: FastifyRequest) {
@@ -120,7 +121,16 @@ async function getTransaction(fastify: FastifyInstance, request: FastifyRequest)
 
 
     if (hits.length > 0) {
-        const actions = hits;
+        const rawActions: any[] = [];
+        for (let action of hits) {
+            action = action._source;
+            mergeActionMeta(action);
+            rawActions.push(action);
+        }
+
+        // re-group notifications that were indexed as separate documents
+        const actions = regroupActions(rawActions);
+
         response.trx.trx = {
             "expiration": "",
             "ref_block_num": 0,
@@ -134,9 +144,7 @@ async function getTransaction(fastify: FastifyInstance, request: FastifyRequest)
             "signatures": [],
             "context_free_data": []
         };
-        for (let action of actions) {
-            action = action._source;
-            mergeActionMeta(action);
+        for (const action of actions) {
             response.block_num = action.block_num;
             response.block_time = action['@timestamp'];
             for (const receipt of action.receipts) {
diff --git a/src/api/routes/v2-history/get_transaction/get_transaction.ts b/src/api/routes/v2-history/get_transaction/get_transaction.ts
@@ -1,5 +1,6 @@
 import {FastifyInstance, FastifyReply, FastifyRequest} from "fastify";
 import {mergeActionMeta, timedQuery} from "../../../helpers/functions.js";
+import {regroupActions} from "../../../helpers/regroup-actions.js";
 import {API} from "@wharfkit/antelope";
 
 async function getTransaction(fastify: FastifyInstance, request: FastifyRequest) {
@@ -108,13 +109,28 @@ async function getTransaction(fastify: FastifyInstance, request: FastifyRequest)
                 highestBlockNum = action._source.block_num;
             }
         }
-        response.actions = [];
+        const rawActions: any[] = [];
         for (let action of hits) {
             if (action._source.block_num === highestBlockNum) {
                 mergeActionMeta(action._source);
-                response.actions.push(action._source);
+                rawActions.push(action._source);
             }
         }
+
+        // re-group notifications that were indexed as separate documents
+        const grouped = regroupActions(rawActions);
+
+        // add notified field derived from receipts
+        response.actions = grouped.map(action => {
+            if (action.receipts && action.receipts.length > 0) {
+                const receivers = new Set<string>(
+                    action.receipts.map((r: any) => r.receiver)
+                );
+                action.notified = [...receivers].join(',');
+            }
+            return action;
+        });
+
         response.executed = true;
     }
     return response;
diff --git a/src/indexer/helpers/action-dedup.ts b/src/indexer/helpers/action-dedup.ts
@@ -5,16 +5,22 @@ import { ActionTrace } from "../../interfaces/action-trace.js";
  *
  * In Antelope, when an action notifies other accounts (e.g. eosio.token::transfer),
  * the same action appears multiple times — once per receiver — with the same
- * `act_digest` and `action_ordinal` but different `receiver`.
+ * `act_digest` but different `action_ordinal` and `receiver`. The
+ * `creator_action_ordinal` links each notification back to the parent action.
  *
  * These notification traces should be merged into a single document with
  * multiple receipts (the `receipts` array).
  *
- * However, genuinely distinct duplicate actions (same content, different
- * `action_ordinal`) must be kept as separate documents.
+ * However, genuinely distinct duplicate actions (same content and `act_digest`,
+ * but independent root actions with `creator_action_ordinal === 0`) must be
+ * kept as separate documents.
  *
- * The grouping key is `act_digest + ":" + action_ordinal` to distinguish
- * between these two cases.
+ * The grouping key is `act_digest + ":" + canonical_ordinal` where:
+ * - Root actions (creator_action_ordinal === 0): canonical = action_ordinal
+ * - Notifications (creator_action_ordinal > 0): canonical = creator_action_ordinal
+ *
+ * This ensures notifications merge with their parent while genuinely distinct
+ * duplicate actions remain separate (fixes #148 without breaking notifications).
  *
  * @param processedTraces - Array of parsed action traces with receipt data
  * @returns Array of grouped action traces with merged receipts
@@ -25,9 +31,12 @@ export function groupActionTraces(processedTraces: ActionTrace[]): ActionTrace[]
     if (processedTraces.length > 1) {
         const traceGroups: Record<string, any[]> = {};
 
-        // collect receipts grouped by act_digest + action_ordinal
+        // collect receipts grouped by act_digest + canonical ordinal
         for (const trace of processedTraces) {
-            const groupKey = `${trace.receipt.act_digest}:${trace.action_ordinal}`;
+            const canonical = trace.creator_action_ordinal > 0
+                ? trace.creator_action_ordinal
+                : trace.action_ordinal;
+            const groupKey = `${trace.receipt.act_digest}:${canonical}`;
             if (traceGroups[groupKey]) {
                 traceGroups[groupKey].push(trace.receipt);
             } else {
@@ -37,7 +46,10 @@ export function groupActionTraces(processedTraces: ActionTrace[]): ActionTrace[]
 
         // merge receipts into the first trace instance per group
         for (const trace of processedTraces) {
-            const groupKey = `${trace.receipt.act_digest}:${trace.action_ordinal}`;
+            const canonical = trace.creator_action_ordinal > 0
+                ? trace.creator_action_ordinal
+                : trace.action_ordinal;
+            const groupKey = `${trace.receipt.act_digest}:${canonical}`;
             if (traceGroups[groupKey]) {
                 trace['receipts'] = [];
                 for (const receipt of traceGroups[groupKey]) {
diff --git a/tests/unit/action-dedup.test.ts b/tests/unit/action-dedup.test.ts
diff --git a/tests/unit/regroup-actions.test.ts b/tests/unit/regroup-actions.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "hyperion-history",`
`3`		`- "version": "4.0.4",`
	`3`	`+ "version": "4.0.5",`
`4`	`4`	`"description": "Scalable Full History API Solution for Antelope based blockchains",`
`5`	`5`	`"main": "./build/indexer/launcher.js",`
`6`	`6`	`"scripts": {`