Implement a deterministic voting power snapshot calculator with delegation-safe accounting

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): governance, backend, consistency, expert

Background

Governance systems often need to freeze voting power at a specific logical snapshot so that later balance or membership changes do not alter an already active vote.

This issue introduces a pure snapshot calculator. It does not create proposals, persist snapshots or integrate with Stellar balances.

Problem

There is currently no standard Core primitive for converting a set of eligible participants and weighted sources into an immutable, deterministic voting-power snapshot.

Without explicit rules, duplicate identities or duplicated source entries can inflate voting power and result ordering may vary across runs.

Expected Outcome

Implement a deterministic voting-power snapshot calculator that validates source records, aggregates power safely and produces a canonical snapshot representation suitable for hashing or persistence by future modules.

Suggested Implementation

Inputs may resemble:

interface VotingPowerSource {
  participantId: string;
  sourceId: string;
  power: bigint;
}

The calculator should:

• validate non-negative voting power;
• define uniqueness rules for source IDs;
• reject duplicate source records that would double-count power;
• aggregate multiple legitimate sources for the same participant;
• support very large bigint values;
• sort snapshot entries deterministically;
• calculate total voting power;
• optionally calculate a deterministic snapshot fingerprint using a local self-contained hashing implementation;
• preserve input immutability;
• expose structured validation errors;
• remain independent of membership and delegation persistence.

Do not depend on the separate canonical-JSON or delegation-graph campaign issues. If fingerprinting is implemented, include the minimal deterministic encoding needed within this task.

Acceptance Criteria

• Voting power is aggregated correctly per participant.
• Total voting power equals the sum of valid participant allocations.
• Duplicate source records cannot inflate voting power.
• Negative power values are rejected.
• Zero-power entries have explicitly documented behaviour.
• Output ordering is deterministic regardless of input order.
• Very large bigint values are supported.
• Input arrays and objects are not mutated.
• If a snapshot fingerprint is provided, identical logical snapshots produce identical fingerprints regardless of input order.
• Unit tests cover duplicates, aggregation, reordered input and large values.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No proposal, Stellar balance, delegation database or API functionality is introduced.

Likely Affected Files/Directories

packages/voting-power-snapshot/ or equivalent isolated governance package
unit tests

Independence Requirement

This issue must be independently implementable from the current main branch. It must not depend on the delegation graph, quorum engine or another governance campaign issue.

[s6pa1rta3n-lab]

/try

[Santia2004]

Hi team! I’d love to take on this issue. I’ve previously contributed and had multiple PRs successfully merged in this repository, so I’m already well-familiar with the codebase, architecture, and workflow. Could you please assign this to me? Thanks!

[OmniZlatoon]

If I can have just one of your issues sir.... I garantuee you best code practices and quality , ensuring proper documentation of implemented work.

[OmniZlatoon]

If I can have just one of your issues sir.... I garantuee you best code practices and quality , ensuring proper documentation of implemented work.