Build a deterministic reward allocation engine using integer weights

[Lakes41]

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

Background

GuildPass communities may eventually distribute fixed reward pools across contributors according to contribution weight, governance decisions or campaign outcomes.

The complete reward system does not need to exist before the allocation mathematics can be implemented as a standalone pure engine.

Problem

Reward allocation becomes error-prone when floating-point percentages are used or when rounding behaviour is undefined. A pool must be distributed deterministically without creating or losing units during rounding.

Expected Outcome

Implement a pure reward allocation engine that distributes an integer reward pool across weighted recipients while guaranteeing conservation of the total pool.

Suggested Implementation

Inputs may resemble:

interface WeightedRecipient {
  id: string;
  weight: bigint;
}

The engine should:

• accept an integer total reward amount;
• accept one or more recipients with non-negative integer weights;
• avoid JavaScript floating-point calculations;
• calculate proportional allocations using integer arithmetic;
• distribute rounding remainders deterministically;
• guarantee that the sum of allocations equals the input pool;
• define tie-breaking semantics explicitly;
• reject duplicate recipient identifiers unless intentionally supported;
• reject negative weights;
• define behaviour when all weights are zero;
• support very large bigint values safely;
• preserve deterministic output regardless of runtime object ordering;
• return allocation metadata useful for auditability.

A largest-remainder approach or another mathematically sound method may be used if documented clearly.

Acceptance Criteria

• Allocations use exact integer arithmetic.
• The sum of all allocated values always equals the original reward pool.
• No recipient receives a negative allocation.
• Equal weights produce deterministic allocations.
• Unequal weights produce proportional results according to the documented algorithm.
• Remainder distribution has a deterministic tie-breaking rule.
• Zero-weight recipients are handled consistently.
• All-zero-weight input has explicitly documented behaviour.
• Duplicate recipient identifiers are rejected or handled according to a documented contract.
• Very large bigint values are tested.
• Unit tests include rounding-heavy cases where the pool is smaller than or not divisible by total weight.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No database, badge, role-upgrade or payout integration is implemented.

Likely Affected Files/Directories

packages/reward-allocation/ or equivalent isolated package
unit tests

Independence Requirement

This task must remain a pure mathematical engine and must not depend on the GuildPass reward engine, contribution engine or database schema.

[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 please? Thanks!