Rewards & income architecture

Status: accepted direction for specification; services and value-moving paths are not implemented. Updated: September 5, 2026.

The Clubs and Harvest extension adds accepted managed-strategy and collateral requirements. Merchant rewards, operator service compensation, customer investment results and collateral reimbursements remain different economic records. Harvest reuses approved funding/order paths and creates no new income.

1. Customer experience and economic separation

The product leads with customer earnings and personal asset bundles that users create, hold and trade in their own subaccounts. Discovery, merchant benefits and saving support that financial outcome. The earning and asset-bundle specification defines customer actions and truthful earnings/P&L attribution. Each asset and entitlement retains a named legal owner, provider, source, currency and availability rule.

An available reward may be a claim against Forage or a fulfillment provider; it is not automatically a bank deposit, stablecoin, or brokerage cash. The signed funds-flow agreement specifies that relationship before launch. A money-market fund or tokenized Treasury investment never silently occupies a CASH account label implying a deposit.

2. Service and credential boundaries

Next.js: Home / Explore / Portfolio
  -> Fastify API on Railway
       -> Merchant catalog and attribution
       -> Rewards accounting and campaign budgets
       -> Trails, groups, cosmetic collections
       -> Provider eligibility, income and equity read models
       -> Customer funding/order intents

Private workers
  merchant-sync -> authenticated events -> immutable inbox -> reward journal
  reward-payout -> approved, reserved claims -> fulfillment / payment partner
  provider-sync -> cash, income, holdings, corporate actions -> reconciliation
  execution    -> customer-authorized provider orders / bounded gateway
  engagement   -> approved read events -> cosmetic progress / opt-in sharing

The public API owns auth and orchestration, with secrets outside the browser. A merchant webhook cannot invoke a securities order or add wallet authority. The reward payout worker has credentials for only its approved payout rail. A securities worker cannot debit a reward treasury. An AI or trail worker has neither credential set.

Use PostgreSQL transactions, row locks, unique source keys, an outbox, retries with backoff, and an immutable journal. Exactly-once delivery is not assumed. Duplicate or reordered events must produce the same final economic result. No cross-service transaction can be called complete solely because the outbox event was emitted.

3. Minimum persistent records

• publisher_connections, advertiser_permissions, merchant_locations, offers, offer_versions;
• attribution_consents, attribution_events, merchant_transactions, provider_event_inbox;
• reward_claims, reward_claim_adjustments, funding_lots, journal_entries, journal_lines;
• campaigns, campaign_budget_reservations, referral_qualifications, payout_intents, payout_attempts;
• income_products, income_entitlements, income_observations, provider_distributions;
• destination_preferences, reward_funding_intents, funding_receipts;
• trail_definitions, trail_participation, cosmetic_awards, group_memberships, share_links;
• existing customer, provider account, Account Instance, mandate, reconciliation, audit, and outbox records.

Rewards may be explored before financial onboarding. A basic app identity maps to a verified Legal Account only when the customer opens a financial product or another required check applies. Public discovery never requires brokerage KYC or a wallet signature.

Every monetary record stores integer minor units and currency, or exact token units, decimals, asset identity and chain where needed. Do not add USD to a USDC amount without a priced conversion. Finance entries balance per currency and legal entity; movements across entities require matching receivable/payable records and actual settlement. Corrections reverse or adjust journal entries instead of deleting them.

4. Reward state and funding proof

Maintain separate state dimensions to avoid equating merchant approval with payment:

Validation: observed -> tracked -> pending -> approved | rejected
Funding:    unfunded -> collected | guaranteed_by_funded_reserve
Allocation: unreserved -> reserved -> applied_to_payout | released
Delivery:   unavailable -> available -> payout_reserved -> submitted
                                             -> reconciled | needs_review
Adjustments: append-only reversals, disputes, and corrections at any stage

available requires an approved claim AND contractually sufficient liquid funding assigned to that claim. Funding comes from collected merchant commission, a prefunded sponsor, or a specifically allocated Forage advance. An approved but uncollected commission remains pending unless that advance is present.

Available, payout-reserved, and submitted liabilities are mutually exclusive balance buckets. Their sum remains an obligation until payout reconciliation proves delivery. A timeout does not release submitted funds. Partial payouts split a claim into linked allocations; one claim's total can never be overpaid.

External reversals can occur after normal locking windows. The reserve absorbs authorized post-payment losses according to the offer terms. Forage cannot silently sell customer investments, debit unrelated holdings, or recreate a paid claim to recover a merchant chargeback. Suspected fraud enters a recorded dispute process with the agreed customer remedies.

For each campaign, currency and restricted funding pool:

liquid funding remaining + evidenced restricted payout assets in transit
  >= available customer liabilities
   + reserved/submitted payout liabilities
   + other accepted campaign promises
   + required liquidity/loss buffer

free new-campaign funding
  = unrestricted liquid business cash
  - existing obligations and committed operating cash needs
  - required reserves

Exclude uncollected receivables, customer investments, customer income, refundable sponsor balances, and unredeemed speculative tokens from free funding. A funding lot cannot back two claims or fund both a referral and BURR allocation.

When a payout provider debits cash before recipient delivery, move the matching asset into a restricted payout-in-transit record backed by provider evidence. It covers only that pending delivery obligation, cannot finance a new award and disappears on reconciliation or recognized loss. This avoids double-counting debited cash while preserving the liability until delivery. Assess provider credit exposure and liquidity buffers separately.

5. Daily income

Income accrual, NAV changes, distribution entitlement, credited cash, and withdrawable funds are separate observations. Each income product describes:

• issuer/provider, legal form, eligible customer types and locations;
• rate type: APY, nominal annual rate, seven-day yield, or another defined measure;
• rate timestamp, calculation base, day-count convention, fees and tax treatment;
• accrual method and business-day/calendar-day treatment;
• distribution schedule, reinvestment policy and customer consent;
• minimums, redemption cutoff, expected cash settlement and exceptional delays;
• deposit insurance, if applicable to that exact account, and investment risk otherwise.

Never divide a displayed APY by 365 as an exact daily payout. For a purely illustrative nominal annual rate r, simple actual/365 income is principal * r * days / 365. Production follows the provider's records, including rate changes, deposits, withdrawals, rounding and fees.

A growing NAV and a reported income estimate must not both be added to portfolio value. Cash distributions reduce the accrued entitlement exactly once; automatic reinvestment creates one position update. Missing data is marked stale, without inventing another day's yield.

Customer interest and dividends accrue without checking in, claiming a daily bonus, owning an NFT, keeping a streak, or permitting notifications. Principal and earned customer income never fund someone else's rewards. Eligible yield providers and their limitations are in the economics evaluation.

6. Reward-to-ownership flow

Customer selects an Available reward
  -> selects an eligible destination and sees costs / rights / timing
  -> approves funding intent
  -> reserve reward exactly once
  -> approved payment/fulfillment partner delivers value
  -> provider confirms available customer funds
  -> customer reviews current eligible instrument and quote
  -> customer authorizes order
  -> provider fills and settles
  -> holdings and reward payout reconcile

The initial product uses customer-mediated funding and orders. A later standing preference can choose where to propose a reward; it does not itself authorize a bank debit, wallet withdrawal, foreign-exchange conversion, or securities order. Any later automation uses a separately approved customer mandate with source, destination, instrument, lifetime cap, expiry, and cancellation rules.

For the researched Dinari U.S. lane, settlement uses supported USDC. An affiliate cash payment or gift card has no assumed direct conversion to brokerage buying power. An approved conversion/onramp and customer-specific destination must be proven. If unavailable, offer permitted reward redemption and show the financial feature as unavailable; do not route cash through the operating treasury as an improvised bridge.

Batch small rewards in the customer's reward entitlement ledger to reduce fulfillment costs. Batch infrastructure may submit separate customer instructions, but cannot create a pooled investment or omnibus customer wallet. Before an order, check provider minimums and total cost. Give the customer a disclosed alternative when a small reward would be consumed by fees; do not retain value indefinitely just to reach an investment minimum.

7. AGW, accounts, mirrors and contracts

Keep PROVIDER, BASKET, CASH, STRATEGY, and other existing Account Instance classes. A savings goal is a label over one customer's balances. If it uses an investment product, classify the position by its actual instrument and provider, not the word "savings". A group trail shares progress, never funds or wallet ownership.

No AGW signature is required to earn an offchain merchant entitlement. Create or link financial accounts only when needed. Recheck provider ownership and eligibility at funding, quote and execution. AGW policy registration, provider-approved smart-account validation, local expiry and revocation remain required for production delegation.

Mirrors carry policy, not rewards balances, yield promises, collateral, duplicated equities, or synthetic versions of restricted securities. Every instance keeps independent assets and settlement. Reward availability is determined by the central journal and actual payment provider records, never by a remote mirror acknowledgement.

The merchant pilot needs no reward token, new reward blockchain, yield vault, randomness contract, or Promotion Escrow deployment. A later onchain escrow may pay only pre-funded, authorized obligations and needs a separate specification for claim roots, replay domains, expiry, disputes, treasury controls and liquidity. Existing contract interfaces remain scaffolds, not the approved implementation.

8. Proposed API additions

These are implementation targets, not existing endpoints:

GET  /v1/merchants                  GET  /v1/offers/:offerId
GET  /v1/trails                     POST /v1/trail-participations
GET  /v1/rewards                    GET  /v1/rewards/:rewardId
POST /v1/attribution-consents       POST /v1/reward-claims
POST /v1/reward-payout-intents      GET  /v1/reward-payout-intents/:id
POST /v1/reward-funding-intents     GET  /v1/reward-funding-intents/:id
GET  /v1/income-products            GET  /v1/income-entitlements
POST /v1/destination-preferences    POST /v1/share-links
GET  /v1/campaigns/:id/budget       GET  /v1/reconciliation/rewards

Administrative reads such as campaign budgets require staff/merchant scope; they are not public merely because they use GET. Claims need authenticated ownership and signed provider evidence; a client cannot submit its own reward amount. Monetary writes require durable idempotency, validation, authorization, funding reservation, audit and explicit status. Webhooks use separate provider authentication, replay controls, body limits and asynchronous processing.

9. Release evidence

Managed strategy and collateral extension

In addition to the reward records above, the accepted Clubs design needs versioned operator/strategy agreements, customer enrollments and mandate bindings, fee accruals/holdbacks, collateral lots, per-customer coverage reservations, claims, payouts and discharge evidence. These are specification requirements, not existing database tables or APIs.

Conduct-bond obligations and optional market-loss coverage occupy separate operator-funded namespaces. Customer portfolio value excludes unclaimed reserve capacity. Reserved collateral cannot back merchant rewards, another Club, another customer cap or a remote mirror simultaneously. Claims and collateral impairments reconcile independently; a timeout, withdrawal request or strategy stop cannot release an unresolved obligation. Record customer reimbursements separately from strategy performance and never charge performance fees on them. The detailed claim, fee, loss-measurement and shortfall requirements are in the Clubs extension.

Existing reward and income proofs

Before the merchant pilot: duplicate and reordered events, partial refunds, expired offers, insufficient campaign funding, overlapping affiliate attribution, duplicate receipts, GPS spoofing, fake referrals, payout timeouts, blocked payout recipients and late reversals must reconcile without duplicate awards.

Before income: prove variable rates, weekends, zero/negative returns where applicable, deposits mid-period, fee deductions, accrued/distributed/reinvested income and redemption delays against provider statements.

Before reward-funded equities: prove blocked eligibility, expired quote, conversion failure, partial fill, rejected order, halted asset, payout ambiguity and customer cancellation. Show exactly which value is still available, reserved, in transit or held by the provider.

Before growth spend: show campaign liabilities are funded, cohort contribution is positive after all attributable costs, sponsor renewals are measured, and referral cost fits a funded acquisition budget. A positive per-customer margin alone does not prove company profitability.