Draft the M2 CHW incentive-layer contract design spec

[ink-mami]

Difficulty: Advanced  |  Estimated effort: Large (4-6 days, design + writeup)

Context

The README's roadmap lists M2 — 'USDC-on-Stellar payout to a CHW per verified registration' — as
the next milestone after this repo's current M1 scope. No design work exists yet for the payout
contract(s) that milestone implies.

Requirements

• Write docs/architecture/m2-incentive-design.md proposing: how a payout contract observes or is called on AttestationRecorded (weighing tight coupling to attestation-registry vs. an independent event-driven design), the USDC-on-Stellar payment mechanism (Stellar classic asset via the Soroban token interface, trustline handling), anti-fraud considerations (rate-limiting payouts per attester to prevent farming via self-dealing attestations), and funding-pool mechanics (how donor/grant USDC enters the pool, per the README's 'Transparent funding' feature).
• This is a design-only issue — scope actual contract implementation as explicit follow-up issues once the design is reviewed.

Acceptance Criteria

• Design doc merged and reviewed by at least one maintainer.
• Explicit list of follow-up implementation issues included in the doc.

Skills Required

Protocol/systems design, Stellar token interface (SEP-41), technical writing

How to Apply for This Issue

1. Comment below to express interest. Wait for a maintainer to assign the issue to you before starting — this avoids duplicate work on overlapping issues (several in this batch touch the same files).
2. Fork the repository and create a branch named issue-48-<short-slug>.
3. Follow the local dev workflow in CONTRIBUTING.md: install the wasm32v1-none target, make your change, and add or update tests per the Requirements and Acceptance Criteria above.
4. Run make check locally (fmt-check + clippy + test + wasm build) — this mirrors CI exactly and must pass before you open a PR.
5. Open a pull request against main that references this issue (Closes #48), describing the change and any design tradeoffs you made.
6. Address review feedback. The PR merges once CI is green and at least one maintainer has approved.

Questions before or during the work are welcome as comments on this issue.

[TechBroAfrica]

Hi, I'm Olalekan a Full-Stack & Blockchain Developer with 3+ years of experience. I've reviewed this issue and I'm confident I can handle it. I'll submit a clean PR within 1-2 days max. Please assign it to me!

[khyiengkc]

Hello team,
I'd like to take on this task and feel free to assign it to me.
Looking forward to getting started!

[grantfox-oss]

🦊 GrantFox — @khyiengkc has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #48)
2. Your PR will be reviewed by the Lafiya-xyz maintainers

Good luck! Track your progress on GrantFox.

[bitstarkbridge]

Hi maintainer,

I would like to work on this issue.

From my understanding, the goal is to replace the compile-time HISTORY_MAX_DEPTH constant with an admin-configurable on-chain value while enforcing a hard upper bound at the contract level. This will allow LedgerLens to adjust history retention requirements without requiring contract redeployment, while preserving predictable storage costs and maintaining compatibility with existing integrations.

I have experience working with Rust smart contracts, storage-driven configuration patterns, and state management in blockchain applications. I am comfortable implementing configurable contract parameters, validation logic, and storage-backed settings while ensuring behavior remains deterministic and well-tested.

If assigned, I will:

• Review the current history storage implementation and trace how HISTORY_MAX_DEPTH is used throughout the score history lifecycle

• Replace the existing compile-time depth constant with the proposed MAX_HISTORY_DEPTH and DEFAULT_HISTORY_MAX_DEPTH constants

• Add the new HistoryMaxDepth storage key to DataKey and implement storage helpers for retrieving and persisting the configured depth

• Update push_score_history to use the configured depth from contract storage rather than a compile-time value

• Implement set_history_max_depth with proper admin authorization and validation to reject zero values and values exceeding the configured ceiling

• Implement get_history_max_depth to expose the current configured value while correctly falling back to the default when no configuration exists

• Add the new InvalidHistoryDepth error and ensure validation failures return the appropriate contract error

• Carefully implement and verify the lazy-truncation behavior when history depth is reduced, ensuring existing entries remain intact until the next submit_score operation triggers the eviction logic

• Add comprehensive Rustdoc documentation explaining the depth configuration behavior and explicitly documenting the lazy-truncation edge case

• Update the README to include both configuration functions and their intended usage

• Add and validate all required test cases covering default values, depth increases, depth decreases, ceiling enforcement, invalid depth handling, and lazy-truncation behavior

• Verify that storage usage remains bounded by the hard ceiling and that the configurable depth integrates cleanly with the existing ring-buffer implementation

I will also ensure the implementation remains consistent with existing Soroban storage patterns, keeps function signatures clean, and avoids introducing unnecessary coupling throughout the history management code.

Kindly assign this issue to me. Thank you!

[github-actions]

This issue has been automatically marked as stale because it has had no activity for 60 days. It will be closed in 14 days if no further activity occurs. Remove the stale label or comment to keep it open.