Feature: Build a Full-Stack Buyback-and-Burn Campaign System With CRDT-Backed State Consistency

[Emmyt24]

Overview

The largest of these feature requests, spanning all three layers: treasury-driven buyback-and-burn campaigns.

• Contract: a campaign module providing operational control over campaigns with a strict, replay-resistant, governance-authorized state machine:
  Active -> Paused -> Active, Active -> Completed, Active|Paused -> Cancelled (other transitions rejected with a dedicated error). A buyback module defines the campaign record itself (token address, total budget, spent, tokens bought/burned, max spend per step, slippage tolerance, active flag) and the step-execution logic that actually swaps treasury funds for tokens and burns them.
• Backend: a campaign ingestion/projection/consistency pipeline — event parsing off the chain, a projection service materializing campaign state for the API, a CRDT-based projection for conflict-free concurrent updates (campaign step execution can race with concurrent event ingestion, so plain last-write-wins isn't safe here), a dedicated consistency checker verifying backend state never drifts from on-chain state, plus campaign and buyback routes.
• Frontend: a full campaign creation form, a campaign dashboard, a step-execution button, real-time step-subscription hooks, and supporting API/service/mapper/validation utilities.

Scope: contract + backend + frontend. This is a big feature — see "Suggested sequencing" below before starting.

Suggested sequencing

Given the size, land this as a stack of smaller PRs rather than one PR, roughly in dependency order:

1. Contract: campaign state machine + buyback step execution + tests
2. Backend: ingestion/parsing + projection service + routes (depends on 1's event shapes)
3. Backend: CRDT projection + consistency checker + chaos/fuzz test suites (depends on 2)
4. Frontend: campaign creation form + API/service layer (depends on 2)
5. Frontend: dashboard + step execution + real-time subscription (depends on 3, 4)

Feel free to split each numbered item into its own issue/PR — don't try to land this as a single change.

Integration points

Contract:

• New module files contracts/token-factory/src/campaign.rs and buyback.rs, declared via mod in lib.rs
• New DataKey/Error variants added to types.rs (errors starting at 133, current highest in-use is 132) — do not reuse existing discriminants; Error::name() updated to match
• Storage and events wired via storage.rs / events.rs following existing patterns
• A property test for the core financial invariant (spent + burned accounting never diverges across pause/resume/execute/cancel) is cheap, high-value coverage — include one

Backend:

• New routes for campaigns and buyback steps, mounted alongside existing admin/token routes
• Event parser + projection service consuming the contract's campaign events
• CRDT-based projection (or an equivalent conflict-free design) plus a consistency checker verifying no drift between backend and on-chain state — this is not optional for a feature that directly represents money movement
• Chaos/concurrency tests exercising concurrent step execution racing with event ingestion

Frontend:

• Campaign creation form + API/service layer
• Dashboard + step-execution button + real-time step-subscription hook, wired against current wallet/service patterns (@creit.tech/stellar-wallets-kit v2 subpath imports — see frontend/src/services/walletKit.ts for the current pattern)

Acceptance criteria

• Contract state machine has explicit, tested transition rules; illegal transitions are rejected with a dedicated error
• Buyback step execution correctly enforces max_spend_per_step and slippage_tolerance_bps
• New DataKey/Error variants added per the checklist above
• Backend event parser/projection service correctly reconstructs campaign state from on-chain events, with a consistency checker verifying no drift
• Backend routes mounted, authenticated/authorized consistently with other admin routes, and covered by tests
• Frontend creation form, dashboard, and step-execution UI wired against the backend API using current wallet/service patterns
• If this feature needs its own CI gate(s) (e.g. a dedicated consistency-check workflow or chaos-test workflow), wire them into .github/workflows/
• cargo check --lib / cargo test --lib clean in contracts/token-factory; npm run type-check / npm run build clean in backend/ and frontend/

Notes for implementers

• Don't simplify away the CRDT/conflict-free design for campaign state without understanding why it's needed: step execution racing with concurrent event ingestion is a real scenario for this feature, and your concurrency test suite should demonstrably exercise it.

[benzy018]

Hello Maintainer I’d like to work on this issue. I can deliver it according to the requirements and submit a PR within 2 days. Thank you

[Peculiarr7]

Hi! I’m a full-stack developer with a strong blockchain background, and I’m confident I can resolve this issue quickly and effectively. I’ll deliver a clean, reliable solution with immediate attention to detail, ensuring it’s completed as soon as possible. Please assign it to me—I’m ready to get started right away.