fix(token): deduplicate composite-owner inputs whose token IDs are filtered out

[EvanYan1024]

Problem

InputStream.UniquePerInput() (#2148) deduplicates the member rows of a composite-owner input by (token ID, enrollment ID) and keeps every input whose token ID is nil. But Metadata.filterTransfer clones only Senders and never TokenID, and ttx marshals that eID-filtered copy for each counterparty — so on those consumers every Input carries Id == nil, the deduplication no-ops, and a composite owner's spend is summed once per member again: 40 spent from a two-member wallet sharing an enrollment ID lands as -80 in that party's movements.

Fixes #2240

Fix

The filtering is position-preserving — filterTransfer emits one (possibly empty) entry per input and Request.extractTransferInputs walks them by index — so the input's position survives filtering and no driver/metadata wire change is needed.

• token/stream.go — Input gains Index, its position within the action, mirroring the role of Output.Index. UniquePerInput keys on (token ID, enrollment ID) when the token ID is present — unchanged behavior for existing callers, including those that construct Input directly and never set Index — and falls back to (action index, input index, enrollment ID) when it has been filtered out. The two key spaces cannot mix: filterIssue keeps Inputs verbatim (token IDs included), so only transfer inputs ever lose their token ID, and the per-type action index is unique among transfers.
• token/request.go — extractTransferInputs / extractIssueInputs record the position.
• token/stream_test.go — contract tests for both key spaces: member rows with a filtered-out token ID now collapse, distinct token IDs at equal positions stay distinct, and a row with a token ID never collides with a positionally identical row without one.
• docs/services/storage/ttxdb.md — documents the fallback.

Testing

go build, go vet, go test -race ./token/..., and golangci-lint v2.12.2 with the repo config, all clean locally.

[AkramBitar]

Hello @EvanYan1024,

Thanks a lot for submitting the PR.

The fix looks correct to me. When a wallet is shared by two members, spending a token produces one row per member, which is then deduplicated so the token is counted only once. The problem was that the auditor receives metadata with token IDs stripped for privacy, so every row had Id == nil and deduplication failed, causing a 40-token spend to be counted as -80.

The fix adds a position (action index + input index) to each input and uses it as the fallback identifier when the token ID is missing. Since both member rows for the same token share the same position, they are correctly collapsed to -40. Other cases remain unaffected.

One minor concern: Index defaults to 0, so a future caller that forgets to set it could cause silent incorrect deduplication. I am wondering, would it be worth adding a constructor that requires Index? What do you think on this?

Regards,
Akram

[EvanYan1024]

@AkramBitar Good catch. A constructor alone would not enforce this while Input remains an exported struct — callers can still build literals and bypass it. What I would suggest is the constructor plus an internal marker:

• NewInput(actionIndex, index, id) becomes the canonical way to build an input, and also stamps an unexported "position known" flag; the extraction paths go through it.
• UniquePerInput applies positional deduplication only to inputs carrying the flag, so a manually constructed or zero-valued input with no token ID keeps the previous keep-all behavior instead of silently collapsing.
• A regression test locks in that hand-built zero-position inputs do not collapse into each other.

If that works for you, I'll push it.

[AkramBitar]

@AkramBitar Good catch. A constructor alone would not enforce this while Input remains an exported struct — callers can still build literals and bypass it. What I would suggest is the constructor plus an internal marker:

• NewInput(actionIndex, index, id) becomes the canonical way to build an input, and also stamps an unexported "position known" flag; the extraction paths go through it.
• UniquePerInput applies positional deduplication only to inputs carrying the flag, so a manually constructed or zero-valued input with no token ID keeps the previous keep-all behavior instead of silently collapsing.
• A regression test locks in that hand-built zero-position inputs do not collapse into each other.

If that works for you, I'll push it.

@EvanYan1024

Thanks a lot. Works for me push it.

Regards,
Akram

[EvanYan1024]

@AkramBitar Pushed in ba27c1c3 — NewInput + the internal marker, with the regression test for literal-built inputs.

[AkramBitar]

@EvanYan1024,

Thanks a lot for working on this PR.

Ready to merge it could you please rebase and squash the commits to one?

Regards,
Akram

[EvanYan1024]

@AkramBitar Done — rebased onto main and squashed into a single commit (4f886802). Ready to merge. Thanks a lot for the review!