2.13 DustAndRoundingCleaner

1. Bot Identity

Operational profile

2. Purpose

DustAndRoundingCleaner prevents creation of dust positions — holdings so small that their eventual pUSD value at settlement is less than the transaction cost of acquiring or selling them. It rounds order sizes to economically viable minimums and sweeps existing dust positions on a configurable cron schedule.

3. Why This Bot Matters

• Dust position created

  A position of <$1 pUSD accumulates with no path to profitable exit; creates accounting noise and wastes position-budget slots.

• Rounding not applied before submission

  Orders with fractional pUSD sizes are rejected by CTFExchangeV2 which requires integer token units; submission fails with a parse error.

• Dust sweep not scheduled

  Over time, hundreds of dust positions accumulate from partial fills, consuming wallet gas allowance on Polygon and polluting portfolio reporting.

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

{ "min_economic_size_usd": 5 }

if size_usd < params.min_economic_size_usd: emit(DUST_WARN)

{ "round_strategy": "round_down" }

roundedSize = toUsdcUnits(plan.size_usd, params.round_strategy)

{ "auto_sweep_dust": true }

if params.auto_sweep_dust: scheduleSweep(params.sweep_cron)

{ "sweep_cron": "0 4 * * *" }

if not isValidCron(params.sweep_cron): raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

8. Default Configuration

{
  "bot_id": "exec.dustandroundingcleaner",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_economic_size_usd": 5,
    "round_strategy": "round_down",
    "auto_sweep_dust": true,
    "sweep_cron": "0 4 * * *"
  },
  "locked": {
    "min_economic_size_usd": {
      "min": 1
    },
    "sweep_cron": {
      "requires_approval": true
    }
  }
}

9. Implementation Flow

1. On receipt of ExecutionPlan from SmartRouter: round plan.size_usd to nearest valid integer pUSD unit using round_strategy.
2. If rounded_size < min_economic_size_usd: emit DUST_WARN or DUST_HARD_REJECT; cancel plan.
3. If remainder from PartialFillHandler is < min_economic_size_usd: cancel remainder; emit DUST_REMAINDER_CANCELLED.
4. On sweep_cron trigger: fetch clob_auth /positions; filter positions where value_usd < min_economic_size_usd.
5. For each dust position: if market is still open, issue a GTC sell order at mid; else wait for settlement.
6. Emit ExecutionReport(DUST_SWEPT) per swept position with builder_code for attribution.
7. Log all sweep actions to WAL for 7-year audit retention.

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.

// ── Real-time path: size validation ──
FUNCTION validateSize(plan):
  // Round to 6-decimal pUSD units
  IF params.round_strategy == 'round_down':
    roundedSize = floor(plan.size_usd * 1e6) / 1e6
  ELSE:
    roundedSize = round(plan.size_usd * 1e6) / 1e6

  IF roundedSize < params.hard:  // < 1 pUSD
    DISCARD plan; reason=DUST_HARD_REJECT
    RETURN
  IF roundedSize < params.min_economic_size_usd:
    EMIT ExecutionReport(DUST_WARN)
    // Still proceed (warn only above hard)
  IF roundedSize < plan.size_usd:
    plan.size_usd = roundedSize
    EMIT ExecutionReport(DUST_ROUNDED)
  RETURN plan

// ── Cron path: sweep existing dust positions ──
FUNCTION sweepDust():
  IF NOT params.auto_sweep_dust:
    RETURN
  positions = FETCH clob_auth.GET('/positions')
  IF positions IS NULL:
    EMIT WARN(DUST_SWEEP_POSITIONS_UNAVAILABLE)
    RETURN
  dustPositions = [p FOR p IN positions IF p.value_usd < params.min_economic_size_usd]
  FOR pos IN dustPositions:
    book = FETCH clob_public.GET('/book?market=' + pos.market_id)
    mid = (book.best_bid + book.best_ask) / 2
    sweepOrder = buildOrderTypedData({
      market_id: pos.market_id,
      side: 'SELL',
      price: mid,
      size: pos.size,
      builder: BUILDER_CODE,
      timestamp: now_ms()
    })
    clob_auth.POST('/order', sign(sweepOrder))
    EMIT ExecutionReport(DUST_SWEPT, pos.market_id, pos.value_usd)

SCHEDULE sweepDust AT params.sweep_cron

SDK calls used

• clob_auth.GET('/positions')
• clob_public.GET('/book?market=' + market_id)
• buildOrderTypedData({side: SELL, price: mid, size, builder_code, timestamp})
• clob_auth.POST('/order', signed_sweep_order)

Complexity: O(P) where P = number of dust positions (sweep path); O(1) real-time

11. Wire Examples

Input — what arrives on the wire

ExecutionPlan with fractional size — exec.smart_router

{
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "size_usd": 5.73,
  "order_type": "GTC",
  "collateral": "pUSD",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000"
}

Output — what the bot emits

ExecutionReport — DUST_ROUNDED

{
  "report_id": "rep_8b9c0d1e2f3a4b5c",
  "bot_id": "exec.dustandroundingcleaner",
  "original_size_usd": 5.73,
  "rounded_size_usd": 5.0,
  "verdict": "DUST_ROUNDED",
  "collateral": "pUSD",
  "evaluated_at_ms": 1746770600000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "report_id": "rep_8b9c0d1e2f3a4b5c",
  "trace_id": "trc_7a8b9c0d1e2f3a4b",
  "bot_id": "exec.dustandroundingcleaner",
  "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "original_size_usd": 5.73,
  "rounded_size_usd": 5.0,
  "verdict": "DUST_ROUNDED",
  "collateral": "pUSD",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
  "evaluated_at_ms": 1746770600000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "original_size_usd": 5.73,
  "rounded_size_usd": 5.0,
  "round_strategy": "round_down",
  "min_economic_size_usd": 5,
  "verdict": "DUST_ROUNDED",
  "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

Rounding state stateless per order. Cron state read from Redis on restart.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Triggering the sweep cron repeatedly via schedule manipulation to generate excessive CLOB sell orders
• Injecting a position report with inflated value_usd to prevent legitimate dust positions from being swept

Mitigations

• Cron uses Redis SETNX to prevent double-sweep; sweep rate limited to 5 sell orders/s
• Position list fetched directly from clob_auth; not from a cache that could be tampered with

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

DustAndRoundingCleaner incidents are either high DUST_HARD_REJECT rates (strategy generating undersized orders) or sweep accumulation (dust positions building up faster than cron clears them).

On-call actions

Manual overrides

• polytraders bot trigger-sweep exec.dustandroundingcleaner — Manual sweep needed outside scheduled cron time; e.g. after a period of high partial fills.

Healthcheck

GET /internal/health/dustandroundingcleaner -> 200 if clob_auth reachable, last_sweep < 25h ago, hard_reject_rate < 0.01/min. Red: last_sweep > 25h ago, hard_reject_rate > 0.1/min, cron not firing.

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%