6.14 AttributionRevenueReporter

1. Bot Identity

2. Purpose

AttributionRevenueReporter reconciles builder-code rebates with internal fill records and publishes a daily auditable SettlementReport. Retained 7 years for financial and regulatory compliance.

3. Why This Bot Matters

• Rebate not reconciled

  Builder-code fee rebates may be under- or over-reported; financial records are inaccurate.

• Per-strategy slice missing

  Revenue attribution to individual strategies is impossible; resource allocation decisions lack data.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "report_cron": "0 6 * * *" }

scheduler.register(p.report_cron, generateReport)

{ "drift_alert_pct": 1.0 }

if abs(drift_pct) > p.drift_alert_pct: emit('REVENUE_DRIFT_DETECTED')

8. Default Configuration

{
  "bot_id": "gov.attributionrevenuereporter",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "report_cron": "0 6 * * *",
    "drift_alert_pct": 1.0,
    "publish_to": [
      "governance_audit",
      "finance_team"
    ],
    "retain_days": 2555
  }
}

9. Implementation Flow

1. On cron schedule, fetch the Polymarket builder-code volume and rebate report for the previous day.
2. Aggregate internal fill records from the ExecutionReport stream by strategy and by user for the same window.
3. Compare total rebate_pusd from official report against sum of builder_fee_pusd from internal records.
4. If drift > drift_alert_pct, emit REVENUE_DRIFT_DETECTED alert and quarantine the report pending review.
5. Emit SettlementReport(event_type=REVENUE_REPORT) with per-strategy slices, drift delta, and reconciliation status.
6. Publish report to governance_audit and finance_team recipients.

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

// ---- DAILY CRON JOB ----
FUNCTION generateReport(reportDate):
  window = {start: reportDate + T00:00Z, end: reportDate + T23:59Z}

  // Fetch official Polymarket rebate report
  official = FETCH data_api.GET(
    '/builder-code-report?code=polytraders&from=' + window.start + '&to=' + window.end
  )
  IF official IS NULL:
    scheduleRetry(generateReport, reportDate, delay=3600)
    EMIT SettlementReport(event_type='REPORT_DEFERRED', report_date=reportDate)
    RETURN

  // Aggregate internal fill records
  fills = postgres.select('attribution_log', WHERE fill_confirmed_at BETWEEN window)
  internalRebate = SUM(f.builder_fee_pusd FOR f IN fills)
  perStrategy = GROUP_BY(fills, 'strategy_slug', SUM('size_pusd'), SUM('builder_fee_pusd'))

  // Compute drift
  drift_pusd = abs(internalRebate - official.rebate_pusd)
  drift_pct = drift_pusd / official.rebate_pusd * 100 IF official.rebate_pusd > 0 ELSE 0

  IF drift_pct > config.drift_alert_pct:
    alerting.emit('REVENUE_DRIFT_DETECTED', {drift_pct, drift_pusd})

  // Emit SettlementReport
  EMIT SettlementReport(event_type='REVENUE_REPORT',
    report_date=reportDate,
    total_volume_pusd=SUM(f.size_pusd),
    total_rebate_pusd=internalRebate,
    official_rebate_pusd=official.rebate_pusd,
    drift_pusd=drift_pusd, drift_pct=drift_pct,
    drift_detected=drift_pct > config.drift_alert_pct,
    per_strategy=perStrategy,
    retained_until=now() + days(config.retain_days))

SDK calls used

• data_api.GET('/builder-code-report?code=polytraders&from=...&to=...')
• postgres.select('attribution_log', WHERE fill_confirmed_at BETWEEN ...)
• alerting.emit('REVENUE_DRIFT_DETECTED', metadata)

Complexity: O(F) per report where F = fill count in window

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Polymarket builder-code report",
  "source": "data_api",
  "payload": {
    "builder_code": "polytraders",
    "window_start": "2026-05-08T00:00:00Z",
    "window_end": "2026-05-08T23:59:59Z",
    "rebate_pusd": 120.8,
    "volume_pusd": 48320.5
  }
}

Output — what the bot emits

{
  "label": "SettlementReport — REVENUE_REPORT",
  "payload": {
    "report_id": "stl_revenue_01HX9Z",
    "event_type": "REVENUE_REPORT",
    "drift_detected": false,
    "report_kind": "SettlementReport",
    "topic": "polytraders.reports.settlement",
    "retained_until": "2033-05-08"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a SettlementReport object. See SettlementReport schema.

{
  "report_id": "stl_attributionrevenuereporter_01HX9Z",
  "bot_id": "gov.attributionrevenuereporter",
  "event_type": "REVENUE_REPORT",
  "report_date": "2026-05-08",
  "total_volume_pusd": 48320.5,
  "total_rebate_pusd": 120.8,
  "official_rebate_pusd": 120.8,
  "drift_pusd": 0.0,
  "drift_pct": 0.0,
  "drift_detected": false,
  "per_strategy": [
    {
      "strategy": "sports-model",
      "volume_pusd": 30000.0,
      "rebate_pusd": 75.0
    }
  ],
  "report_kind": "SettlementReport",
  "topic": "polytraders.reports.settlement",
  "retained_until": "2033-05-08"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "gov.attributionrevenuereporter",
  "event_type": "REPORT_GENERATED",
  "report_date": "2026-05-08",
  "fetch_latency_ms": 230,
  "strategies_included": 3
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, check for any deferred reports and retry immediately.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Manipulating internal fill records to inflate reported rebate figures

Mitigations

• Internal fill records are immutably written; any manipulation would show as drift against the official Polymarket report

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

AttributionRevenueReporter incidents are usually revenue drift (P1) or deferred reports due to Data API unavailability.

On-call actions

Manual overrides

• —

Healthcheck

/internal/health/attributionrevenuereporter → green if Last report completed today; drift_pusd == 0; no deferred reports; red if Drift detected or report deferred for > 2h

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%