Skip to content

replace static CARBON_CPM_RATE with reconciliation against actual Carbon payouts #33

@distroinfinity

Description

@distroinfinity

Problem

CARBON_CPM_RATE is a static env var ($0.80) used to calculate developer earnings per Carbon impression (cpmRate / 1000 * 0.70). Carbon's SDK returns no pricing data per impression — the CarbonAd response contains company, description, link, and tracking URLs but zero CPM or bid information. Carbon tracks impressions on their side and pays publishers based on their own accounting.

This means developer earnings recorded in earnings_ledger are estimates that may not match what Carbon actually pays us. Before enabling real USDC payouts, we need to reconcile.

Current behavior

  1. CARBON_CPM_RATE=0.80 set as env var (mid-range of Carbon's published $0.50–$1.10)
  2. Each Carbon impression stamps this rate on the creative row and impression row
  3. earnedAmount = (0.80 / 1000) * 0.70 = $0.00056 per completed impression
  4. Written to earnings_ledger.amount_usdc as if it were a confirmed amount

Required changes

  1. Reconciliation layer — periodically pull actual earnings from Carbon's publisher reporting dashboard/API and compare against our recorded estimates
  2. Mark earnings as estimated — use earnings_ledger.status = 'pending' to indicate unreconciled, move to 'confirmed' after reconciliation
  3. Settle deltas — adjust developer balances when Carbon's actual payout differs from estimate
  4. Dynamic rate updates — if Carbon exposes a reporting API, update CARBON_CPM_RATE (or per-impression rates) based on actual observed CPMs

Context

  • Currently using Carbon demo zone (CWYDC2QE) with no real payout implications
  • The earnings_ledger.status field already has pending|confirmed enum — designed for this
  • This blocks enabling real USDC developer payouts for Carbon-sourced impressions
  • Related PR: S2-03: carbon ads integration as primary provider #32 (Carbon Ads integration)
  • Documented in gitbook-docs/engineering/known-gaps.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions