{ "schema_version": "1.0.0", "bot_id": "2.13", "bot_name": "DustAndRoundingCleaner", "slug": "dustandroundingcleaner", "layer": "Execution", "layer_key": "exec", "bot_class": "Execution Utility", "authority": [ "Reshape" ], "status": "planned", "readiness": "Spec started", "flagship": false, "is_reference": false, "public_export": false, "identity": { "layer": "Execution", "bot_class": "Execution Utility", "authority": "Reshape", "runs_before": "Order signing and CLOB V2 submission; dust sweep runs on cron", "runs_after": "PartialFillHandler (remainder below min_economic_size) or strategy sizing step", "applies_to": "Any order with remainder below min_economic_size and any existing dust positions on cron", "default_mode": "shadow_only", "user_visible": "yes", "developer_owner": "Polytraders core \u2014 Execution pod" }, "purpose": "DustAndRoundingCleaner prevents creation of dust positions \u2014 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.", "why_it_matters": [ { "failure": "Dust position created", "consequence": "A position of <$1 pUSD accumulates with no path to profitable exit; creates accounting noise and wastes position-budget slots." }, { "failure": "Rounding not applied before submission", "consequence": "Orders with fractional pUSD sizes are rejected by CTFExchangeV2 which requires integer token units; submission fails with a parse error." }, { "failure": "Dust sweep not scheduled", "consequence": "Over time, hundreds of dust positions accumulate from partial fills, consuming wallet gas allowance on Polygon and polluting portfolio reporting." } ], "polymarket_inputs": [ { "input": "CLOB V2 minimum order size for market", "source": "clob_public", "required": true, "use": "Ensure order size is above CLOB V2 minimum (1 share unit) after rounding." }, { "input": "Current position holdings for sweep", "source": "clob_auth", "required": true, "use": "Identify existing positions below min_economic_size_usd for the sweep cron." } ], "internal_inputs": [ { "input": "Remainder below min_economic_size from PartialFillHandler", "source": "exec.partialfillhandler", "required": false, "use": "Forward sub-minimum remainders to DustAndRoundingCleaner for sweep or cancellation." }, { "input": "ExecutionPlan size before signing", "source": "exec.smart_router", "required": true, "use": "Round plan.size_usd to nearest integer pUSD unit before signing." } ], "raw_params": [ "min_economic_size_usd \u00b7 int", "round_strategy \u00b7 enum", "auto_sweep_dust \u00b7 bool", "sweep_cron \u00b7 cron" ], "parameters": [ { "name": "min_economic_size_usd", "default": 5, "warning": 2, "hard": 1, "controls": "Minimum order or position size in pUSD below which the order is rejected (too small) or position is flagged for sweep.", "why_default_matters": "At $5 pUSD minimum, a worst-case transaction cost of ~$0.50 (10% of position) is acceptable. Below $2, fees dominate.", "threshold_logic": [ { "condition": "size_usd >= 5", "action": "No intervention" }, { "condition": "2 <= size_usd < 5", "action": "WARN \u2014 DUST_WARN; flag for sweep" }, { "condition": "size_usd < 1 (hard)", "action": "HARD_REJECT \u2014 DUST_HARD_REJECT; cancel order or sweep position" } ], "dev_check": "if size_usd < params.min_economic_size_usd: emit(DUST_WARN)", "user_facing": "A portion of your order was too small to keep open and was removed." }, { "name": "round_strategy", "default": "round_down", "warning": "\u2014", "hard": "\u2014", "controls": "Rounding strategy for order sizes: round_down (conservative, never oversize), round_nearest (closest integer), or truncate (same as round_down).", "why_default_matters": "Round-down ensures the final order never exceeds the intent size, which is important for risk constraint compliance.", "threshold_logic": [ { "condition": "round_strategy=round_down", "action": "floor(size_usd * 1e6) / 1e6 \u2014 never exceeds intent" }, { "condition": "round_strategy=round_nearest", "action": "round(size_usd * 1e6) / 1e6" }, { "condition": "round_strategy=truncate", "action": "int(size_usd * 1e6) / 1e6" } ], "dev_check": "roundedSize = toUsdcUnits(plan.size_usd, params.round_strategy)", "user_facing": "Your order size was rounded to the nearest valid unit." }, { "name": "auto_sweep_dust", "default": true, "warning": "\u2014", "hard": "\u2014", "controls": "Automatically sweep dust positions (sell or cancel) on the sweep_cron schedule.", "why_default_matters": "Automated sweep prevents dust accumulation without requiring manual operator intervention.", "threshold_logic": [ { "condition": "auto_sweep_dust=true", "action": "Dust positions swept on cron" }, { "condition": "auto_sweep_dust=false", "action": "WARN only; operator must sweep manually" } ], "dev_check": "if params.auto_sweep_dust: scheduleSweep(params.sweep_cron)", "user_facing": "Small leftover positions are automatically cleaned up on a schedule." }, { "name": "sweep_cron", "default": "0 4 * * *", "warning": "\u2014", "hard": "\u2014", "controls": "Cron expression defining when the automatic dust sweep runs (default: 04:00 UTC daily).", "why_default_matters": "04:00 UTC is typically low-volume on Polymarket; sweeping then minimises market impact of small sell orders.", "threshold_logic": [ { "condition": "valid cron expression", "action": "Sweep scheduled at specified time" }, { "condition": "invalid cron expression", "action": "Reject config \u2014 PARAMETER_CHANGE_REQUIRES_APPROVAL" } ], "dev_check": "if not isValidCron(params.sweep_cron): raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')", "user_facing": "Small leftover positions are cleaned up automatically each day." } ], "default_config": { "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 } } }, "implementation_flow": [ "On receipt of ExecutionPlan from SmartRouter: round plan.size_usd to nearest valid integer pUSD unit using round_strategy.", "If rounded_size < min_economic_size_usd: emit DUST_WARN or DUST_HARD_REJECT; cancel plan.", "If remainder from PartialFillHandler is < min_economic_size_usd: cancel remainder; emit DUST_REMAINDER_CANCELLED.", "On sweep_cron trigger: fetch clob_auth /positions; filter positions where value_usd < min_economic_size_usd.", "For each dust position: if market is still open, issue a GTC sell order at mid; else wait for settlement.", "Emit ExecutionReport(DUST_SWEPT) per swept position with builder_code for attribution.", "Log all sweep actions to WAL for 7-year audit retention." ], "decision_logic": { "approve": "size_usd >= min_economic_size_usd after rounding; proceed to signing.", "reshape_required": "Size rounded down to nearest integer unit; DUST_ROUNDED emitted.", "reject": "Rounded size < hard threshold (1 pUSD); DUST_HARD_REJECT; order or remainder cancelled.", "warning_only": "Size between warning (2 pUSD) and default (5 pUSD) threshold; DUST_WARN emitted." }, "decision_output_schema": "ExecutionReport", "decision_output_example": { "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 }, "developer_log": { "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" }, "user_explanations": [ { "situation": "Order size rounded", "message": "Your order size was rounded to the nearest valid unit before submission." }, { "situation": "Remainder too small \u2014 cancelled", "message": "The remaining portion of your order was too small to be worth keeping open and was cancelled." }, { "situation": "Dust position swept", "message": "A small leftover position in your account was automatically sold to clean up your portfolio." } ], "failure_modes": { "main_failure_mode": "Sweep order submitted at an unfavourable mid price if market is wide-spread or illiquid at sweep time, resulting in a sweep fill worse than just holding the dust to settlement.", "false_positive_risk": "Rounding down a legitimate $5.01 order to $5.00 when the minimum order unit is $1.00 is acceptable, but rounding a $1.01 order to $1.00 could trigger the warning threshold.", "false_negative_risk": "auto_sweep_dust=false: dust accumulates indefinitely if operator does not sweep manually.", "safe_fallback": "If clob_auth /positions is unavailable during sweep cron, skip the sweep cycle and emit WARN; do not retry aggressively to avoid rate-limit exhaustion on a degraded exchange.", "required_dependencies": [ "clob_auth /positions endpoint for sweep", "clob_public minimum order size", "PartialFillHandler for sub-minimum remainder forwarding" ] }, "acceptance_tests": { "unit": [ { "test": "Round-down applied to 5.73 pUSD", "setup": "size_usd=5.73, round_strategy=round_down", "expected": "rounded_size_usd=5.0; DUST_ROUNDED emitted" }, { "test": "HARD_REJECT when rounded size < 1 pUSD", "setup": "size_usd=0.80", "expected": "rounded_size_usd=0; DUST_HARD_REJECT; order cancelled" }, { "test": "Sweep: identify positions < min_economic_size_usd", "setup": "position value=3.50 pUSD, min_economic_size=5", "expected": "Position flagged for sweep; GTC sell order submitted at mid" } ], "integration": [ { "test": "Cron sweep: fetch positions, filter dust, submit sell orders, emit ExecutionReports", "expected": "All dust positions swept; DUST_SWEPT emitted per position; WAL entries written" }, { "test": "Remainder from PartialFillHandler: 2.50 pUSD remainder forwarded and cancelled", "expected": "DUST_REMAINDER_CANCELLED emitted; no remainder order left on book" } ], "property": [ { "property": "rounded_size_usd always <= original_size_usd when round_strategy=round_down", "required": "Always true" }, { "property": "Sweep orders carry builder_code for attribution", "required": "Always true" } ] }, "checklist_overrides": {}, "legacy_goal": "Avoid creating dust positions that cost more in fees than they earn.", "legacy_pm_signals": [ "Order size vs. CLOB V2 minimum and tick increments", "Predicted post-trade dust given partial-fill probability", "Existing dust holdings flagged for sweep" ], "legacy_external_feeds": [], "reporting_groups": [ "execution" ], "network": [ "polygon" ], "api_surface": [ "clob_auth", "clob_public", "internal" ], "version": { "spec": "2.0.0", "implementation": "0.1.0", "schema": "2", "released": null, "planned_release": "Q4-2026" }, "migration_history": [ { "date": "2026-04-28", "from": "n/a", "to": "v2-spec", "reason": "Spec drafted post-CLOB-V2 cutover; bot not yet implemented", "action_taken": "Designed against V2 schema (pUSD, builder codes, V2 EIP-712 domain)" } ], "polymarket_v2_compat": { "clob_version": "v2", "collateral": "pUSD", "eip712_domain_version": "2", "builder_code_aware": true, "negrisk_aware": false, "multichain_ready": false, "sdk_used": "py-clob-client-v2", "settlement_contract": "CTFExchangeV2", "notes": "All sizes rounded to 6-decimal pUSD integer units as required by CTFExchangeV2. Sweep sell orders include builder_code bytes32 for attribution on Polygon." }, "reference_implementation": { "pseudocode": "// \u2500\u2500 Real-time path: size validation \u2500\u2500\nFUNCTION validateSize(plan):\n // Round to 6-decimal pUSD units\n IF params.round_strategy == 'round_down':\n roundedSize = floor(plan.size_usd * 1e6) / 1e6\n ELSE:\n roundedSize = round(plan.size_usd * 1e6) / 1e6\n\n IF roundedSize < params.hard: // < 1 pUSD\n DISCARD plan; reason=DUST_HARD_REJECT\n RETURN\n IF roundedSize < params.min_economic_size_usd:\n EMIT ExecutionReport(DUST_WARN)\n // Still proceed (warn only above hard)\n IF roundedSize < plan.size_usd:\n plan.size_usd = roundedSize\n EMIT ExecutionReport(DUST_ROUNDED)\n RETURN plan\n\n// \u2500\u2500 Cron path: sweep existing dust positions \u2500\u2500\nFUNCTION sweepDust():\n IF NOT params.auto_sweep_dust:\n RETURN\n positions = FETCH clob_auth.GET('/positions')\n IF positions IS NULL:\n EMIT WARN(DUST_SWEEP_POSITIONS_UNAVAILABLE)\n RETURN\n dustPositions = [p FOR p IN positions IF p.value_usd < params.min_economic_size_usd]\n FOR pos IN dustPositions:\n book = FETCH clob_public.GET('/book?market=' + pos.market_id)\n mid = (book.best_bid + book.best_ask) / 2\n sweepOrder = buildOrderTypedData({\n market_id: pos.market_id,\n side: 'SELL',\n price: mid,\n size: pos.size,\n builder: BUILDER_CODE,\n timestamp: now_ms()\n })\n clob_auth.POST('/order', sign(sweepOrder))\n EMIT ExecutionReport(DUST_SWEPT, pos.market_id, pos.value_usd)\n\nSCHEDULE sweepDust AT params.sweep_cron", "sdk_calls": [ "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" }, "wire_examples": { "input": [ { "label": "ExecutionPlan with fractional size", "source": "exec.smart_router", "payload": { "market_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "size_usd": 5.73, "order_type": "GTC", "collateral": "pUSD", "builder_code": "0x706f6c7974726164657273000000000000000000000000000000000000000000" } } ], "output": [ { "label": "ExecutionReport \u2014 DUST_ROUNDED", "payload": { "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 } } ] }, "reason_codes": [ { "code": "DUST_ROUNDED", "severity": "RESHAPE", "meaning": "Order size rounded down to nearest valid integer pUSD unit.", "action": "Update plan.size_usd; forward to signing.", "user_message": "Your order size was rounded to the nearest valid unit." }, { "code": "DUST_WARN", "severity": "WARN", "meaning": "Order size below min_economic_size_usd but above hard threshold.", "action": "Emit WARN; proceed with order (size still valid for CLOB).", "user_message": "Your order size is very small and may not be economically optimal." }, { "code": "DUST_HARD_REJECT", "severity": "HARD_REJECT", "meaning": "Order size below hard threshold (1 pUSD) after rounding; not viable.", "action": "Discard order; emit no submission.", "user_message": "Your order was too small to submit." }, { "code": "DUST_SWEPT", "severity": "INFO", "meaning": "Dust position swept via sell order on cron schedule.", "action": "Emit ExecutionReport; log to WAL.", "user_message": "A small leftover position was automatically sold." }, { "code": "DUST_REMAINDER_CANCELLED", "severity": "INFO", "meaning": "Sub-minimum remainder from PartialFillHandler cancelled.", "action": "Cancel remainder; emit ExecutionReport.", "user_message": "The tiny remaining portion of your order was cancelled." } ], "metrics": { "emitted": [ { "name": "polytraders_exec_dustandroundingcleaner_decisions_total", "type": "counter", "unit": "count", "labels": [ "verdict" ], "meaning": "Total decisions by verdict (ROUNDED/WARN/REJECT/SWEPT)." }, { "name": "polytraders_exec_dustandroundingcleaner_dust_positions_swept_total", "type": "counter", "unit": "count", "labels": [], "meaning": "Total dust positions swept by the cron sweep." }, { "name": "polytraders_exec_dustandroundingcleaner_dust_value_swept_usd", "type": "histogram", "unit": "pUSD", "labels": [], "meaning": "Distribution of pUSD values of swept dust positions." } ], "alerts": [ { "name": "DRCHighDustRejectRate", "condition": "rate(polytraders_exec_dustandroundingcleaner_decisions_total{verdict='DUST_HARD_REJECT'}[5m]) > 0.1", "severity": "P2", "runbook": "#runbook-drc-dust-reject" }, { "name": "DRCSweepAccumulation", "condition": "increase(polytraders_exec_dustandroundingcleaner_dust_positions_swept_total[24h]) > 50", "severity": "P3", "runbook": "#runbook-drc-sweep-accumulation" } ] }, "state": { "store": "in-memory for real-time path; cron state in Redis", "shape": "Redis key 'dust_sweep:last_run_ms'; in-memory rounding stats per session", "ttl": "Cron state: 25h (just over 1 day to detect missed sweeps)", "recovery": "Rounding state stateless per order. Cron state read from Redis on restart.", "size_estimate": "~100 bytes for cron state; negligible for real-time path" }, "concurrency": { "execution_model": "per-order goroutine (real-time); single-threaded cron worker (sweep)", "max_in_flight": 50, "idempotency_key": "order_id + size_usd (real-time); sweep_run_ts_ms (cron)", "timeout_ms": 500, "backpressure": "Cron sweep rate-limited to 5 sweep orders/s to avoid CLOB rate limit", "locking": "Redis SETNX for cron to prevent double-sweep if multiple instances run" }, "dependencies": { "depends_on": [ { "bot_id": "exec.partialfillhandler", "why": "Source of sub-minimum remainders forwarded for dust handling.", "contract": "Receives remainder size and order_id; issues cancel." }, { "bot_id": "exec.smart_router", "why": "Source of ExecutionPlan sizes to validate and round.", "contract": "Rounded size replaces original in plan before signing." } ], "emits_to": [ { "bot_id": "gov.builder_attribution", "why": "Every sweep sell order includes builder_code for attribution.", "contract": "builder_code bytes32 present on all sweep orders." } ], "sibling": [], "external": [ { "service": "CLOB V2 auth API", "endpoint": "https://clob.polymarket.com", "sla": "99.95% / 200ms p99", "failure_mode": "If /positions unavailable at cron time, skip sweep; emit WARN." }, { "service": "CLOB V2 public API", "endpoint": "https://clob.polymarket.com", "sla": "99.9% / 200ms p99", "failure_mode": "If book unavailable for sweep price, skip that position; retry next cron cycle." } ] }, "security_surfaces": { "signs_orders": true, "private_key_access": "signing-only", "abuse_vectors": [ "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" ] }, "failure_injection": [ { "scenario": "CRON_POSITIONS_UNAVAILABLE", "how_to_inject": "Block clob_auth /positions at sweep cron time", "expected_behaviour": "DUST_SWEEP_POSITIONS_UNAVAILABLE WARN emitted; sweep skipped; next cron cycle retries", "recovery": "Automatic on next cron trigger" }, { "scenario": "HARD_REJECT_UNDERSIZED_ORDER", "how_to_inject": "Submit ExecutionPlan with size_usd=0.50", "expected_behaviour": "roundedSize < 1 pUSD; DUST_HARD_REJECT; plan discarded", "recovery": "Strategy corrects minimum order size" }, { "scenario": "SWEEP_RATE_LIMIT", "how_to_inject": "Create 100 dust positions to sweep in one cron cycle", "expected_behaviour": "Sweep rate-limited to 5/s; all 100 swept over 20s; no 429 errors", "recovery": "Automatic \u2014 all positions swept within sweep window" } ], "runbook": { "summary": "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).", "oncall_actions": [ { "alert": "DRCHighDustRejectRate", "first_step": "Identify strategy generating undersized orders; check minimum size configuration.", "diagnosis": "", "mitigation": "", "escalation": "Strategy pod lead" }, { "alert": "DRCSweepAccumulation", "first_step": "Check sweep cron execution log; if cron missed due to clob_auth outage, trigger manual sweep.", "diagnosis": "", "mitigation": "", "escalation": "Exec pod lead" } ], "manual_overrides": [ { "name": "trigger_sweep_now", "how": "polytraders bot trigger-sweep exec.dustandroundingcleaner", "when": "Manual sweep needed outside scheduled cron time; e.g. after a period of high partial fills.", "command": "polytraders bot trigger-sweep exec.dustandroundingcleaner", "effect": "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." }, "promotion_gates": { "to_shadow": [ { "gate": "Round-down and hard-reject unit tests pass with known edge cases", "how_measured": "CI test run", "threshold": "100% pass" } ], "to_limited_live": [ { "gate": "Sweep cron executes cleanly for 7 consecutive days in shadow run", "how_measured": "dust_positions_swept_total increments daily; no sweep errors", "threshold": "7/7 clean sweeps" } ], "to_general_live": [ { "gate": "Zero DUST_HARD_REJECT false positives over 7-day limited-live (i.e. no rejections of legitimately sized orders)", "how_measured": "Audit log of DUST_HARD_REJECT events cross-checked with original strategy intent sizes", "threshold": "Zero false positives" } ] }, "reporting": { "emits_kinds": [ "ExecutionReport" ], "topics": [ "polytraders.reports.execution" ], "partition_key": "trace_id", "cadence": "every-event", "retention_class": "7y", "sampling_rule": "emit-every", "bus_failure_action": "wal-then-retry", "user_visible": "yes", "consumes_kinds": [ "DecisionReport" ] }, "capital_impact": "Direct", "mode_support": [ "quarantine" ], "v3_status": { "phase": 5, "phase_name": "Execution rails", "docs": { "done": 27, "total": 27, "state": "done" }, "impl": { "done": 0, "total": 15, "state": "pending" }, "runtime": { "done": 0, "total": 8, "state": "pending" }, "overall": "pending" } }