feat(observability): correlate the sign and broadcast stages

The signed operation is the same object both stages see, so object identity is the
correlation key — a WeakMap, hence no TTL, no eviction policy and no retained
signatures. Where it hits, the broadcast event carries the transaction's own action
wording, delegation target and send-max.

That matters most where the optimistic operation is generic: hedera claim-rewards
and algorand claimReward report OUT, solana stake.withdraw reports IN. A miss
(serialised signed operations, ACRE) falls back to the operation type, and
tx_data_source records which path ran.

Author: beths-ledger

.changeset/LIVE-35350-sign-broadcast-correlation.md

@@ -0,0 +1,12 @@
+---
+"@ledgerhq/transaction-observability": minor
+"@ledgerhq/live-common": minor
+---
+
+Correlate the sign and broadcast stages, so a broadcast event carries the transaction's own data rather than what survives on the optimistic operation.
+
+`signOperation` emits a `SignedOperation` and that same object is later handed to `broadcast`, so object identity is the correlation key — nothing to invent, nothing to reconcile. A `WeakMap` means no TTL, no eviction policy and no size cap to get wrong, and no signature is retained: a transaction signed but never broadcast simply becomes garbage.
+
+Without this, the broadcast stage is uneven in ways a data consumer cannot predict. Cosmos copies its validators into the optimistic operation and Solana does not; Hedera's `claim-rewards` and Algorand's `claimReward` are crafted as plain transfers and so report `OUT`, and Solana's `stake.withdraw` reports `IN` — indistinguishable from an incoming transfer. Correlation recovers the exact action, the delegation target and send-max for all of them.
+
+Correlation legitimately misses when a signed operation is serialised and rehydrated (the wallet-api `transaction.sign` route, or one persisted and broadcast later) and for ACRE, which signs outside the wrapper. Those fall back to the operation type. `tx_data_source` on every event records which path produced it, so the hit rate is measurable rather than assumed. Route attribution still comes from the broadcast stage, which is the only stage that knows it.

libs/transaction-observability/src/eventBuilders.test.ts

@@ -1,4 +1,4 @@
-import type { Account, AccountLike, Operation, SignedOperation } from "@ledgerhq/types-live";
+import type { Account, AccountLike, SignedOperation } from "@ledgerhq/types-live";
 import { setEnv } from "@shared/env";
 import {
   buildBroadcastCommonEvent,
@@ -19,7 +19,8 @@ const cosmos = account({ id: "cosmos", family: "cosmos", ticker: "ATOM" });
 const sei = account({ id: "sei_evm", family: "evm", ticker: "SEI" });
 
 const tx = (fields: Record<string, unknown>): TransactionLike => fields;
-const operation = (fields: Record<string, unknown>) => fields as unknown as Operation;
+const signed = (op: Record<string, unknown>) =>
+  ({ signature: "0xsig", operation: op }) as unknown as SignedOperation;
 
 const attribution = (mainAccount: Account, over: Partial<{ account: AccountLike }> = {}) => ({
   account: over.account ?? mainAccount,
@@ -86,7 +87,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("derives the action from the optimistic operation type", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(cosmos),
-      operation: operation({ type: "DELEGATE", extra: {} }),
+      signedOperation: signed({ type: "DELEGATE", extra: {} }),
     });
 
     expect(common).toMatchObject({
@@ -99,7 +100,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("reads the validators cosmos copies into the operation extra", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(cosmos),
-      operation: operation({
+      signedOperation: signed({
         type: "DELEGATE",
         extra: { validators: [{ address: "cosmosvaloper1" }] },
       }),
@@ -111,7 +112,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("reports no validators for a family that does not copy them across", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(cardano),
-      operation: operation({ type: "DELEGATE", extra: {} }),
+      signedOperation: signed({ type: "DELEGATE", extra: {} }),
     });
 
     expect(common.validators).toBeUndefined();
@@ -122,7 +123,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("prefers the exact mode off transactionRaw where it survives", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(sei),
-      operation: operation({
+      signedOperation: signed({
         type: "REWARD",
         extra: {},
         transactionRaw: { mode: "compoundReward", valAddress: "0xval" },
@@ -139,7 +140,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("falls back to the operation type when transactionRaw carries no usable mode", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(sei),
-      operation: operation({ type: "REWARD", extra: {}, transactionRaw: { mode: "send" } }),
+      signedOperation: signed({ type: "REWARD", extra: {}, transactionRaw: { mode: "send" } }),
     });
 
     expect(common).toMatchObject({
@@ -151,7 +152,7 @@ describe("buildBroadcastCommonEvent", () => {
   it("derives nothing from a plain send, so it never enters the funnel", () => {
     const common = buildBroadcastCommonEvent({
       ...attribution(cosmos),
-      operation: operation({ type: "OUT", extra: {} }),
+      signedOperation: signed({ type: "OUT", extra: {} }),
     });
 
     expect(common.earnTransactionType).toBeUndefined();

libs/transaction-observability/src/eventBuilders.ts

@@ -18,6 +18,7 @@ import {
 import { deriveEarnTransactionType, type EarnTransactionType } from "./earnTransactionType";
 import { deriveFromOperationType } from "./operationType";
 import { getRawTransactionType, getStakeTarget, type TransactionLike } from "./transactionShape";
+import { recallSignContext } from "./signContext";
 import { classifyTransactionError, ErrorCategory, toError, unwrapRpcError } from "./errorCategory";
 
 type Attribution = {
@@ -116,10 +117,27 @@ function stakeTargetFromOperation(operation: Operation): string[] | undefined {
  * `compoundReward`, since both become `REWARD`.
  */
 export function buildBroadcastCommonEvent(
-  attribution: Attribution & { operation: Operation },
+  attribution: Attribution & { signedOperation: SignedOperation },
 ): CommonLogEvent {
-  const { operation, mainAccount } = attribution;
+  const { signedOperation, mainAccount } = attribution;
+  const { operation } = signedOperation;
   const family = mainAccount.currency.family;
+
+  // The sign stage saw the real transaction. Where that correlates, its data is strictly
+  // better than anything recoverable here — and for the families that report a generic
+  // operation type it is the only thing that makes the action legible at all.
+  const signed = recallSignContext(signedOperation);
+  if (signed?.earnTransactionType) {
+    return buildCommon(attribution, {
+      ...signed,
+      // Celo and tron put the target only on the optimistic operation (`celoSourceValidator`,
+      // `extra.votes`), where the sign stage cannot see it — so take whichever stage has one
+      // rather than letting a correlation hit throw the other away.
+      validators: signed.validators ?? stakeTargetFromOperation(operation),
+      dataSource: TransactionDataSource.Sign,
+    });
+  }
+
   const rawMode = (operation.transactionRaw as { mode?: string } | undefined)?.mode;
   const fromRawMode = deriveEarnTransactionType(family, rawMode);
 

libs/transaction-observability/src/index.ts

@@ -15,6 +15,8 @@ export { deriveFromOperationType } from "./operationType";
 
 export { getRawTransactionType, getStakeTarget, type TransactionLike } from "./transactionShape";
 
+export { rememberSignContext, type SignContext } from "./signContext";
+
 export {
   buildBroadcastCommonEvent,
   buildSignCommonEvent,

libs/transaction-observability/src/signContext.test.ts

@@ -0,0 +1,151 @@
+import type { Account, SignedOperation } from "@ledgerhq/types-live";
+import { setEnv } from "@shared/env";
+import { hasSignContext, recallSignContext, rememberSignContext } from "./signContext";
+import { buildBroadcastCommonEvent } from "./eventBuilders";
+import { TransactionDataSource, TransactionFlow } from "./logEvent";
+
+const account = (id: string, family: string, ticker: string) =>
+  ({ id: "acc", type: "Account", currency: { id, family, ticker } }) as unknown as Account;
+
+const signed = (op: Record<string, unknown>) =>
+  ({ signature: "0xsig", operation: op }) as unknown as SignedOperation;
+
+const attribution = (mainAccount: Account) => ({
+  account: mainAccount,
+  mainAccount,
+  flow: TransactionFlow.Send,
+});
+
+beforeEach(() => setEnv("LEDGER_CLIENT_VERSION", "llc/test"));
+
+describe("rememberSignContext / recallSignContext", () => {
+  it("carries the exact action and the delegation target across the stages", () => {
+    const signedOperation = signed({ type: "DELEGATE", extra: {} });
+    rememberSignContext(signedOperation, "solana", {
+      family: "solana",
+      model: { kind: "stake.createAccount", uiState: { voteAccAddr: "voteAcc" } },
+    });
+
+    expect(recallSignContext(signedOperation)).toEqual({
+      earnTransactionType: "delegate",
+      rawTransactionType: "stake.createAccount",
+      validators: ["voteAcc"],
+      isSendMax: false,
+    });
+  });
+
+  it("does not correlate a different signed operation", () => {
+    rememberSignContext(signed({ type: "DELEGATE" }), "cosmos", {
+      family: "cosmos",
+      mode: "delegate",
+    });
+
+    expect(recallSignContext(signed({ type: "DELEGATE" }))).toBeUndefined();
+    expect(recallSignContext(undefined)).toBeUndefined();
+  });
+
+  it("stores nothing for a non-staking transaction", () => {
+    const signedOperation = signed({ type: "OUT" });
+    rememberSignContext(signedOperation, "cosmos", { family: "cosmos", mode: "send" });
+
+    expect(recallSignContext(signedOperation)?.earnTransactionType).toBeUndefined();
+  });
+
+  it("survives a read, so a rebroadcast still correlates", () => {
+    const signedOperation = signed({ type: "DELEGATE" });
+    rememberSignContext(signedOperation, "cosmos", { family: "cosmos", mode: "delegate" });
+
+    recallSignContext(signedOperation);
+    expect(hasSignContext(signedOperation)).toBe(true);
+  });
+});
+
+describe("buildBroadcastCommonEvent with a sign context", () => {
+  // Solana's stake.withdraw becomes an `IN` operation, indistinguishable from an incoming
+  // transfer — correlation is the only thing that makes it reportable at all.
+  it("recovers an action the operation type cannot express", () => {
+    const solana = account("solana", "solana", "SOL");
+    const signedOperation = signed({ type: "IN", extra: {} });
+    rememberSignContext(signedOperation, "solana", {
+      family: "solana",
+      model: { kind: "stake.withdraw" },
+    });
+
+    expect(buildBroadcastCommonEvent({ ...attribution(solana), signedOperation })).toMatchObject({
+      earnTransactionType: "withdraw",
+      rawTransactionType: "stake.withdraw",
+      dataSource: TransactionDataSource.Sign,
+    });
+  });
+
+  it("recovers the validator for a family that drops it from the operation", () => {
+    const cardano = account("cardano", "cardano", "ADA");
+    const signedOperation = signed({ type: "DELEGATE", extra: {} });
+    rememberSignContext(signedOperation, "cardano", {
+      family: "cardano",
+      mode: "delegate",
+      poolId: "pool123",
+    });
+
+    expect(
+      buildBroadcastCommonEvent({ ...attribution(cardano), signedOperation }).validators,
+    ).toEqual(["pool123"]);
+  });
+
+  // The sign stage has no broadcastConfig, so it must never win on attribution.
+  it("keeps the broadcast stage's route attribution", () => {
+    const cosmos = account("cosmos", "cosmos", "ATOM");
+    const signedOperation = signed({ type: "DELEGATE", extra: {} });
+    rememberSignContext(signedOperation, "cosmos", { family: "cosmos", mode: "delegate" });
+
+    const common = buildBroadcastCommonEvent({
+      account: cosmos,
+      mainAccount: cosmos,
+      flow: TransactionFlow.Dapp,
+      manifestId: "kiln",
+      signedOperation,
+    });
+
+    expect(common).toMatchObject({ flow: TransactionFlow.Dapp, manifestId: "kiln" });
+  });
+
+  // Celo and tron only expose the target on the optimistic operation, so a correlation hit
+  // must not discard it just because the sign stage had none.
+  it("keeps an operation-only validator when the sign stage had none", () => {
+    const celo = account("celo", "celo", "CELO");
+    const signedOperation = signed({ type: "VOTE", extra: { celoSourceValidator: "0xgroup" } });
+    rememberSignContext(signedOperation, "celo", { family: "celo", mode: "vote" });
+
+    const common = buildBroadcastCommonEvent({ ...attribution(celo), signedOperation });
+    expect(common).toMatchObject({
+      earnTransactionType: "delegate",
+      dataSource: TransactionDataSource.Sign,
+      validators: ["0xgroup"],
+    });
+  });
+
+  it("falls back to the operation type when nothing correlates", () => {
+    const cosmos = account("cosmos", "cosmos", "ATOM");
+
+    expect(
+      buildBroadcastCommonEvent({
+        ...attribution(cosmos),
+        signedOperation: signed({ type: "DELEGATE", extra: {} }),
+      }),
+    ).toMatchObject({
+      earnTransactionType: "delegate",
+      rawTransactionType: "DELEGATE",
+      dataSource: TransactionDataSource.Broadcast,
+    });
+  });
+
+  it("falls back when the sign stage saw no staking action", () => {
+    const cosmos = account("cosmos", "cosmos", "ATOM");
+    const signedOperation = signed({ type: "DELEGATE", extra: {} });
+    rememberSignContext(signedOperation, "cosmos", { family: "cosmos", mode: "send" });
+
+    expect(buildBroadcastCommonEvent({ ...attribution(cosmos), signedOperation })).toMatchObject({
+      dataSource: TransactionDataSource.Broadcast,
+    });
+  });
+});

libs/transaction-observability/src/signContext.ts

@@ -0,0 +1,58 @@
+import type { SignedOperation } from "@ledgerhq/types-live";
+import { deriveEarnTransactionType, type EarnTransactionType } from "./earnTransactionType";
+import { getRawTransactionType, getStakeTarget, type TransactionLike } from "./transactionShape";
+
+/**
+ * What the sign stage knows and the broadcast stage does not: the family's own action
+ * wording, the delegation target, and send-max.
+ */
+export type SignContext = {
+  earnTransactionType?: EarnTransactionType;
+  rawTransactionType?: string;
+  validators?: string[];
+  isSendMax: boolean;
+};
+
+/**
+ * Correlates the two lifecycle stages.
+ *
+ * `signOperation` emits a `SignedOperation` and that same object is later handed to
+ * `broadcast`, so object identity is the correlation key — no id to invent, nothing to
+ * reconcile. A `WeakMap` rather than a keyed cache means there is no TTL, no eviction policy
+ * and no size cap to get wrong, and no signature is retained: a transaction that is signed
+ * and never broadcast simply becomes garbage. Entries survive a read, so a rebroadcast or a
+ * speed-up still correlates.
+ *
+ * Identity is lost when a signed operation is serialised and rehydrated — the wallet-api
+ * `transaction.sign` route across the webview boundary, or one persisted and broadcast later
+ * — and ACRE signs outside the wrapper entirely. Those miss and fall back to the operation
+ * type, which is why {@link deriveFromOperationType} is still load-bearing.
+ */
+const contexts = new WeakMap<object, SignContext>();
+
+export function rememberSignContext(
+  signedOperation: SignedOperation,
+  family: string,
+  transaction: TransactionLike | undefined | null,
+): void {
+  if (!signedOperation || typeof signedOperation !== "object") return;
+  const rawTransactionType = getRawTransactionType(transaction);
+  contexts.set(signedOperation, {
+    earnTransactionType: deriveEarnTransactionType(family, rawTransactionType),
+    rawTransactionType,
+    validators: getStakeTarget(transaction),
+    isSendMax: Boolean(transaction?.useAllAmount),
+  });
+}
+
+export function recallSignContext(
+  signedOperation: SignedOperation | undefined | null,
+): SignContext | undefined {
+  if (!signedOperation || typeof signedOperation !== "object") return undefined;
+  return contexts.get(signedOperation);
+}
+
+/** Test-only: the map is otherwise invisible, so a leak assertion needs a way in. */
+export function hasSignContext(signedOperation: SignedOperation): boolean {
+  return contexts.has(signedOperation);
+}