6.1 BuilderAttribution

1. Bot Identity

2. Purpose

BuilderAttribution tags every outgoing order with the Polytraders builder code before submission, logs each fill against the builder code, and reconciles the local fill log against the Polymarket builder-code report every 24 hours. If a discrepancy is detected — missing attribution, volume drift, or order counts that do not match — it quarantines the affected records and raises an alert. BuilderAttribution never submits, modifies, or cancels orders. Its authority is to explain and audit only.

3. Why This Bot Matters

• Builder code missing from an outgoing order

  Volume attributed to the builder is undercounted in the Polymarket report, which affects fee rebates, builder-tier status, and audit trails for compliance.

• Daily reconciliation not performed

  Attribution drift compounds silently over time. Without regular reconciliation, discrepancies may only be discovered during a formal audit when they are much harder to investigate.

• Quarantine not applied on drift

  Unreconciled records remain in the live ledger and may be double-counted or misreported in downstream reports if not flagged and isolated.

• Attribution log retention not enforced

  Without a defined retention policy, old attribution records may be purged before they are needed for a historical audit or fee dispute.

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

{ "builder_code": "polytraders" }

if (!order.builder_code) { order.builder_code = p.builder_code; alerting.emit('MISSING_CODE'); }

{ "reconcile_window_h": 24 }

if (p.reconcile_window_h > p.hard) throw new ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "quarantine_on_drift": true }

if (p.quarantine_on_drift && reconciliationDrift) quarantine.move(driftedRecords);

{ "alert_on_missing_code": true }

if (p.alert_on_missing_code && !order.builder_code) alerting.emit('MISSING_BUILDER_CODE', { order_id: order.id });

8. Default Configuration

{
  "bot_id": "gov.builder_attribution",
  "version": "1.0.0",
  "mode": "general_live",
  "defaults": {
    "builder_code": "polytraders",
    "reconcile_window_h": 24,
    "quarantine_on_drift": true,
    "alert_on_missing_code": true
  },
  "locked": {
    "builder_code": {
      "change_requires_signed_admin_action": true
    },
    "quarantine_on_drift": {
      "immutable": true
    },
    "alert_on_missing_code": {
      "immutable": true
    },
    "reconcile_window_h": {
      "max": 72
    }
  }
}

9. Implementation Flow

1. Intercept every outgoing order from StrategyRegistry before it reaches the signing step; verify builder_code is present and correct.
2. If builder_code is absent, attach the configured builder_code value and emit an alert to the monitoring stack (alert_on_missing_code).
3. After each fill confirmation from the CLOB, extract the fill metadata (order_id, market_id, size_usd, price, side, timestamp, builder_code echoed by exchange).
4. Append the fill record to the local attribution log with all metadata fields and a log_sequence_number for ordering.
5. Every reconcile_window_h hours, fetch the Polymarket builder-code volume report from Data API for the matching time window.
6. Compare local fill log totals (volume, order count, unique market count) against the Polymarket report for the same window.
7. If discrepancy is detected: compute the drift delta, tag affected records with a quarantine flag, and move them to the quarantine partition (quarantine_on_drift).
8. Emit a reconciliation report to the governance audit trail (GovernanceLog) whether the reconciliation passes or flags drift.
9. Retain all attribution log records for a minimum of 90 days; quarantined records are retained indefinitely until manually reviewed and resolved.
10. Produce a PostTradeExplanation entry for each reconciliation cycle summarising: total volume attributed, match status, drift delta if any, and quarantine record count.

10. Reference Implementation

Intercepts every outgoing order to verify the builderCode bytes32 field is present, logs each fill to the attribution ledger, and runs a 24-hour reconciliation against the Data API builder-code volume report. Quarantines drift records and emits a GovernanceLog on every cycle.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

// ---- PRE-SUBMISSION HOOK: called on every outgoing order ----
FUNCTION attachAndVerifyBuilderCode(order):
  // In V2, builderCode is a bytes32 field on the order (not HMAC)
  IF order.builder IS NULL OR order.builder == ZERO_BYTES32:
    order.builder = config.builder_code_bytes32
    alerting.emit('BUILDER_CODE_MISSING', { order_id: order.id })
  IF order.builder != config.builder_code_bytes32:
    alerting.emit('BUILDER_CODE_MISMATCH', { order_id: order.id, found: order.builder })
    raise PARAMETER_CHANGE_REQUIRES_APPROVAL
  RETURN order

// ---- POST-FILL HOOK: called on every fill confirmation ----
FUNCTION logFill(fillEvent):
  // fillEvent.builder is echoed back by CTFExchangeV2 from the on-order builderCode
  IF fillEvent.builder != config.builder_code_bytes32:
    alerting.emit('BUILDER_CODE_MISSING', { fill_id: fillEvent.fill_id })

  record = {
    fill_id:           fillEvent.fill_id,
    order_id:          fillEvent.order_id,
    market_id:         fillEvent.market_id,
    side:              fillEvent.side,
    size_pusd:         toUsdcUnits(fillEvent.size_usd),
    price:             fillEvent.price,
    builder_code:      fillEvent.builder,
    // V2 fee: builder_fee = notional * bps / 10000
    builder_fee_pusd:  toUsdcUnits(fillEvent.size_usd * fillEvent.builder_fee_bps / 10000),
    fill_confirmed_at: fillEvent.timestamp,
    log_seq:           postgres.nextval('attribution_log_seq')
  }
  postgres.INSERT('attribution_log', record)
  EMIT GovernanceLog(event_type='FILL_LOGGED', fill_id=fillEvent.fill_id)

// ---- RECONCILIATION: runs every reconcile_window_h hours ----
FUNCTION reconcile(windowStart, windowEnd):
  localRows = postgres.SELECT('attribution_log',
                WHERE fill_confirmed_at BETWEEN windowStart AND windowEnd)
  localVolume = SUM(r.size_pusd FOR r IN localRows)
  localCount  = COUNT(localRows)

  report = FETCH data_api.GET(
    '/builder-code-report?code=' + config.builder_code
    + '&from=' + windowStart + '&to=' + windowEnd
  )
  IF report IS NULL:
    alerting.emit('RECONCILIATION_SKIP', { reason: 'data_api_unavailable' })
    RETURN

  drift_usd = abs(localVolume - report.volume_pusd)
  drift_pct = drift_usd / max(localVolume, 1)

  IF drift_pct > 0.01:  // > 1% drift
    driftRows = identify_drift_rows(localRows, report)
    postgres.UPDATE('attribution_log', driftRows, { quarantined: true })
    alerting.emit('RECONCILIATION_DRIFT_OBSERVED', { drift_usd, drift_pct })
    EMIT GovernanceLog(event_type='RECONCILIATION_DRIFT',
                       drift_usd=drift_usd, quarantine_count=len(driftRows))
  ELSE:
    EMIT GovernanceLog(event_type='RECONCILIATION_COMPLETE',
                       drift_detected=False, local_volume=localVolume,
                       polymarket_volume=report.volume_pusd)

  // Retain all records >= 90 days; quarantined records retained indefinitely

Helpers used

SDK calls used

• data_api.GET('/builder-code-report?code=...&from=...&to=...')
• clob_auth.GET('/fills?order_id=...&limit=100')
• postgres.INSERT('attribution_log', record)
• postgres.SELECT('attribution_log', WHERE fill_confirmed_at BETWEEN ... AND ...)
• alerting.emit('RECONCILIATION_DRIFT_OBSERVED', metadata)

Complexity: O(F) per reconciliation window where F = fill count; O(1) per fill log event

11. Wire Examples

Input — what arrives on the wire

Fill confirmation from CTFExchangeV2 — clob_auth

{
  "fill_id": "fill_00a1b2c3d4e5f6a7",
  "order_id": "ord_00123",
  "market_id": "0x9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c",
  "side": "BUY",
  "size_usd": 250.0,
  "price": 0.62,
  "builder": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "builder_fee_bps": 25,
  "fill_confirmed_at": "2026-05-09T11:45:00Z"
}

Data API builder-code volume report — data_api

{
  "builder_code": "polytraders",
  "window_start": "2026-05-08T00:00:00Z",
  "window_end": "2026-05-09T00:00:00Z",
  "volume_pusd": 48320.5,
  "order_count": 217,
  "fill_count": 217
}

Output — what the bot emits

GovernanceLog — RECONCILIATION_COMPLETE (no drift)

{
  "attribution_id": "gov.builder_attribution",
  "event_type": "RECONCILIATION_COMPLETE",
  "window_start": "2026-05-08T00:00:00Z",
  "window_end": "2026-05-09T00:00:00Z",
  "local_volume_pusd": 48320.5,
  "polymarket_volume_pusd": 48320.5,
  "local_order_count": 217,
  "polymarket_order_count": 217,
  "drift_detected": false,
  "quarantine_count": 0,
  "builder_code": "polytraders",
  "retention_days": 90,
  "reconciled_at": "2026-05-09T00:05:12Z"
}

GovernanceLog — RECONCILIATION_DRIFT (quarantine triggered)

{
  "attribution_id": "gov.builder_attribution",
  "event_type": "RECONCILIATION_DRIFT",
  "window_start": "2026-05-08T00:00:00Z",
  "window_end": "2026-05-09T00:00:00Z",
  "local_volume_pusd": 48420.5,
  "polymarket_volume_pusd": 48320.5,
  "drift_usd": 100.0,
  "drift_pct": 0.00207,
  "drift_detected": true,
  "quarantine_count": 2,
  "reconciled_at": "2026-05-09T00:06:00Z"
}

Reproduce locally

curl 'https://data-api.polymarket.com/builder-code-report?code=polytraders&from=2026-05-08T00:00:00Z&to=2026-05-09T00:00:00Z'

12. Decision Logic

13. Standard Decision Output

This bot returns a GovernanceLog object. See GovernanceLog schema.

{
  "attribution_id": "gov.builder_attribution",
  "event_type": "RECONCILIATION_COMPLETE",
  "window_start": "2026-05-08T00:00:00Z",
  "window_end": "2026-05-09T00:00:00Z",
  "local_volume_usd": 48320.5,
  "polymarket_volume_usd": 48320.5,
  "local_order_count": 217,
  "polymarket_order_count": 217,
  "drift_detected": false,
  "quarantine_count": 0,
  "builder_code": "polytraders",
  "retention_days": 90,
  "reconciled_at": "2026-05-09T00:05:12Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Governance / BuilderAttribution reconciliation
• Grafana — Fee accounting / builder code volume and drift

Log levels

16. Developer Reporting

{
  "attribution_id": "gov.builder_attribution",
  "event_type": "FILL_LOGGED",
  "order_id": "ord_00123",
  "market_id": "CLOB:0xabc123",
  "side": "BUY",
  "size_usd": 250.0,
  "price": 0.62,
  "builder_code_present": true,
  "builder_code_echoed": "polytraders",
  "log_sequence_number": 4821,
  "fill_confirmed_at": "2026-05-09T11:45:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Maintains a durable Postgres attribution ledger with all fill records, plus a quarantine partition for drift records. Reconciliation state is persisted per window.

State stores

Cold-start recovery

On cold start, Postgres attribution_log is read immediately. No in-memory state needs rebuilding.

On restart

All state is in Postgres and available immediately. The next fill event triggers a fresh log write.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Sibling bots (same OrderIntent)

Used by (auto-aggregated)

6.14 6.3

External services

23. Security Surfaces

BuilderAttribution reads fill data and writes to the governance ledger. It never signs orders or holds private keys.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Clearing quarantine records automatically without manual review to hide attribution drift
• Substituting a different builder code bytes32 on orders to redirect fee attribution
• Modifying builder_code parameter without a signed admin action

Mitigations

• quarantine_on_drift is locked immutable; auto-clear is rejected
• builder_code parameter requires signed admin action and is audit-logged
• Each fill record is immutable once written; log_seq is monotonically increasing
• alert_on_missing_code is locked immutable; every missing code alert is raised regardless

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

BuilderAttribution incidents involve missing builder codes, reconciliation drift, or quarantine growth. Every RECONCILIATION_DRIFT event is a P1 requiring investigation before the next daily report.

On-call actions

Manual overrides

• polytraders gov clear-quarantine --fill-ids <ids> --reviewed-by <operator> — Clears specific quarantine records after manual review. Requires governance pod lead sign-off and is audit-logged.
• polytraders gov rerun-reconciliation --window-start <ts> --window-end <ts> — Re-runs a specific reconciliation window without clearing existing records. Used to check if drift resolves after a Data API format fix.

Healthcheck

GET /health → 200 if Postgres attribution_log is reachable, last fill was logged < 300s ago during active trading, and quarantine_count has not increased in the last 24h.

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%