Capitalization Plans

contracts/products/capitalization_plan.trea models a capitalization plan (plano de capitalização): periodic or one-off contributions into a per-participant reserve, eligibility for a periodic lottery drawing (sorteio), and maturity/redemption.

CapitalizationPlan -> one admin, one participant, one drawing series

Like the FX hedge and parametric insurance templates, this contract does not generate randomness on-chain. The drawing result must come from an authorized off-chain oracle/draw-source and is verified on-chain via an Ed25519 signature.

Lifecycle

initialize -> enroll -> contribute -> submit_drawing_result (oracle-signed)
                          \-> redeem_prize (if winner)
                          \-> redeem after maturity, or after cancel_plan

States (CapitalizationPlanState enum):

• Proposed — plan initialized, participant has not enrolled yet
• Active — participant enrolled; accepts contributions, drawings, and redemptions after maturity
• Suspended — contributions paused (drawings and redemptions still allowed)
• Cancelled — admin cancelled before maturity; reserve becomes redeemable immediately
• Closed — plan settled (reserve and prize both zero)

Reserve And Prize Balance

Contributions are tracked 1:1 in reserve, the same technique used by the pension plan templates (see Pension Plans). contribute moves the managed token into vault_account and increases reserve and total_contributed; it also sets eligible = True for the next drawing.

prize_balance is a separate balance, credited only when a signed drawing result names this participant as winner. It is redeemed independently of the reserve via redeem_prize.

Drawing Result Verification

The runtime exposes capitalization.verify_drawing_result(pubkey, signature, drawing_id, series_id, winner, prize_amount, drawn_at, valid_until), which verifies an Ed25519 signature over a canonical, domain-separated payload (atlas_common::schemas::capitalization_signing) — the same pattern used by hedge.verify_fixing and hedge.verify_option_quote_lock (see Hedge Contracts).

submit_drawing_result enforces, in this order:

1. The plan is Active or Suspended.
2. ctx.block_timestamp <= valid_until — drawing_result_expired otherwise.
3. drawing_id is not already in consumed_drawing_ids — drawing_result_replayed otherwise.
4. The Ed25519 signature verifies against oracle_public_key — invalid_drawing_signature otherwise.
5. The participant is eligible (has contributed at least once) — participant_not_eligible otherwise.

The signature's canonical bytes bind contract_id from the runtime's active_contract_id, never from a contract-supplied argument, so a valid signature for one plan instance cannot be replayed against another instance of the same series. Replay of the same drawing_id *within* one instance is blocked by consumed_drawing_ids (a bounded Vec[String, 64]).

This design deliberately keeps randomness generation out of scope for the contract: TREA has no entropy/RNG intrinsic, so the drawing result must always originate from an authorized off-chain source and arrive signed.

Maturity And Redemption

redeem(amount) requires either:

• the plan state is Cancelled (admin cancelled before maturity), or
• ctx.block_timestamp >= enrolled_at + maturity_seconds.

It pays out from reserve. If both reserve and prize_balance reach zero, the plan auto-transitions to Closed and emits PlanClosed.

cancel_plan() lets the admin cancel before maturity, immediately allowing redeem regardless of the elapsed time; any already-won, unredeemed prize remains claimable via redeem_prize.

Receipts

The contract emits CapitalizationReceipt(plan_id, participant, action, kind, state, amount, token) on every lifecycle step — initialization, enrollment, contribution, drawing result, prize redemption, reserve redemption, cancellation, and closure — alongside more specific events (ContributionMade, DrawingResultRecorded, PrizeWon, PrizeRedeemed, RedemptionMade, PlanCancelled, PlanClosed, PlanSuspended, PlanResumed).

Product Boundary

The contract governs plan rules, participant rights, and the lifecycle. It does not generate randomness, run a draw, or select winners — those remain the responsibility of the authorized oracle/draw-source whose signature is verified on-chain. This keeps the TREA surface auditable while letting institutions plug in their own regulated drawing mechanism.