V2-SC-019 — Implement Reward Allocation Ledger

[dDevAhmed]

V2-SC-019 — Implement Reward Allocation Ledger

Overview

Implement bounty and verifier reward allocation records using frozen final outcomes and effective weights.

Problem Context

Rewards must be recorded as claimable entitlements only after final settlement. Push payouts and backend-calculated rewards create denial-of-service and authority risks.

This issue belongs to V2-EPIC-SC-001 — Canonical Contract Topology and Deployment. Existing repository issues are historical only; their titles, labels, closure state, or partial implementations do not satisfy this issue.

Technical Scope

• Calculate winner allocations pro rata by frozen effective weight.
• Represent submitter refunds, successful-challenge rewards, protocol fees, and inconclusive policy outputs.
• Write claimable balances in StakeVault or a dedicated ledger through narrow hooks.
• Use deterministic remainder handling and emit RewardAllocated for every category.

The contributor must begin by auditing current files that overlap this scope. Reusable logic may be retained only when it conforms to the governing V2 interfaces, events, authority boundaries, and tests. The pull request must identify reused, replaced, and deprecated paths.

Security and Integrity Requirements

• No reward before finalization.
• No allocation may exceed the source pool.
• Prevent double allocation and cross-claim consumption.
• Avoid loops that make finalization exceed configured gas bounds.
• Preserve blockchain authority and every applicable protocol invariant.
• Do not add secrets, production credentials, dummy production addresses, backend settlement authority, or Stellar/Freighter runtime dependencies.

Required Tests

• Conclusive True/False, inconclusive, disputed, and undisputed tests.
• Pro rata and rounding boundary tests.
• Duplicate settlement and insufficient-pool tests.
• Accounting invariant fuzz tests.
• Run the repository’s complete required Hardhat and Foundry suites and report unrelated pre-existing failures separately.
• Add regression coverage for every defect or unsafe legacy behavior removed by this work.

Acceptance Criteria

• All reward categories reconcile with source pools.
• Entitlements are pull-based and idempotent.
• Rounding destination is explicit.
• Events match stored claimable balances.
• All new and existing relevant tests pass on the final commit.
• Static analysis and formatting introduce no new unresolved finding.
• Documentation and generated artifacts affected by the change are current.
• The pull request maps evidence to every acceptance criterion.

Deliverables

• Production-quality Solidity, interfaces, libraries, deployment code, or test code required by the scope.
• Unit and higher-level tests described above.
• NatSpec and contract-specific technical documentation.
• A pull-request summary covering architecture, security analysis, gas or storage impact, migration implications, and residual risks.
• Evidence of commands run and their results.

Dependencies

• V2-SC-004 — Implement Versioned Protocol Configuration Registry
• V2-SC-009 — Implement Stake Vault Custody and Lock Ledger
• V2-SC-015 — Implement Provisional Settlement Engine
• V2-SC-018 — Implement Appeal Aggregation and Final Dispute Resolution

This issue must not be assigned while any required dependency is unresolved or incompatible with the reviewed interface version.

Non-Goals

• Executing withdrawals.
• Setting launch allocation percentages.
• Creating, modifying, reopening, or relabelling historical GitHub issues.
• Applying the external Stellar Wave label.

Complexity and Review

• Complexity: high
• Repository: DigiNodes/truthbounty-contract
• Risk: protocol-critical
• Required review: human maintainer review; automatic merge is prohibited
• Candidate state: wave-candidate

References

• Protocol specification §16
• TruthBounty Protocol V2 Specification
• TruthBounty V2 Engineering Blueprint
• ADR-0001 — Canonical V2 Contract Topology
• Drips Stellar Wave Operations

---

🏷 Labels

• contracts
• rewards
• protocol-critical
• web3
• complexity-high
• wave-candidate
• accounting
• security

---

[Opulencechuks]

@Opulencechuks has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I am confident that I can implement this issues. Please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Opulencechuks to this issue.

[olatundefay-prog]

@olatundefay-prog has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

i have reviewed the issues i can work on this kindly assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @olatundefay-prog to this issue.

[drips-wave]

Congratulations, @olatundefay-prog! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @olatundefay-prog: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊