1.7 BlacklistKeeper

1. Bot Identity

Operational profile

2. Purpose

BlacklistKeeper maintains a dual-registry of banned market condition IDs and banned counterparty wallet addresses. On every OrderIntent it checks both registries and hard-rejects any intent whose target market or counterparty appears on either list. The bot also monitors for ambiguity signals (undefined resolution sources, prior dispute history, time-to-resolution below threshold) and rejects structurally hostile markets before execution. It is fail-closed: if the registry cannot be read, the intent is rejected.

3. Why This Bot Matters

• Intent routed to a banned market

  Trading a market that has been operator-banned (due to ambiguous resolution rules, prior disputes, or platform policy) exposes the system to unresolvable settlement risk and potential fund loss.

• Order matched against a banned counterparty wallet

  Engaging with a blacklisted counterparty (e.g. a wallet flagged for manipulation, wash-trading, or prior sanctions escalation) introduces regulatory exposure and may contaminate position records.

• Market with ambiguous resolution rules passes through

  Markets using vague trigger words (“substantial”, “primary”) or undefined resolution sources frequently go to UMA dispute. Each dispute costs a $750 pUSD bond and 24–48 h of DVM voting delay, eroding capital efficiency.

• Single-source resolution market accepted

  A market that resolves on a single oracle feed is vulnerable to feed manipulation or temporary outage; the bot blocks these when block_single_source is enabled.

• Fail-open on registry outage

  If BlacklistKeeper approves orders when the registry is unavailable, banned markets and counterparties can trade undetected. The bot must never approve when its data source is unreachable.

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

{ "blacklisted_condition_ids": [] }

if (blacklisted_condition_ids.includes(intent.market_id)) return reject('BLACKLIST_KEEPER_MARKET_BANNED');

{ "blacklisted_counterparties": [] }

if (blacklisted_counterparties.includes(intent.counterparty)) return reject('BLACKLIST_KEEPER_COUNTERPARTY_BANNED');

{ "min_hours_to_resolution": 2 }

const htr = (market.end_date_iso - now()) / 3600000; if (htr < params.min_hours_to_resolution) return reject('BLACKLIST_KEEPER_NEAR_RESOLUTION');

{ "block_single_source": true }

if (params.block_single_source && market.single_source) return reject('BLACKLIST_KEEPER_SINGLE_SOURCE');

{ "ambiguity_keywords": ["substantial", "primary", "significant", "material", "reasonable"] }

const hit = params.ambiguity_keywords.find(kw => market.resolution_rules.includes(kw)); if (hit) return reject('BLACKLIST_KEEPER_AMBIGUOUS_RULES');

8. Default Configuration

{
  "bot_id": "risk.blacklist_keeper",
  "version": "2.0.0",
  "mode": "hard_guard",
  "defaults": {
    "blacklisted_condition_ids": [],
    "blacklisted_counterparties": [],
    "min_hours_to_resolution": 2,
    "block_single_source": true,
    "ambiguity_keywords": [
      "substantial",
      "primary",
      "significant",
      "material",
      "reasonable"
    ]
  },
  "locked": {
    "min_hours_to_resolution": {
      "min": 2
    },
    "ambiguity_keywords": {
      "min_length": 2
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer including market_id, counterparty wallet, and intent metadata.
2. Check KillSwitch active flag; if active, return REJECT with KILL_SWITCH_ACTIVE immediately.
3. Look up intent.market_id in the banned-market registry (Redis SET). On any match, return HARD_REJECT with BLACKLIST_KEEPER_MARKET_BANNED. If registry is unavailable, return HARD_REJECT with BLACKLIST_KEEPER_DATA_UNAVAILABLE (fail-closed).
4. Look up intent.counterparty in the banned-counterparty registry (Redis SET). On any match, return HARD_REJECT with BLACKLIST_KEEPER_COUNTERPARTY_BANNED.
5. Fetch target market metadata from Gamma API: resolution_rules text, single_source flag, end_date_iso, and prior dispute history.
6. If Gamma fetch fails or returns stale data (age > 300s), return HARD_REJECT with BLACKLIST_KEEPER_DATA_UNAVAILABLE.
7. Compute hours_to_resolution = (market.end_date_iso - now_ms()) / 3600000. If hours_to_resolution < params.min_hours_to_resolution, return HARD_REJECT with BLACKLIST_KEEPER_NEAR_RESOLUTION.
8. If params.block_single_source = true and market.single_source = true, return HARD_REJECT with BLACKLIST_KEEPER_SINGLE_SOURCE.
9. Scan market.resolution_rules text for any term in params.ambiguity_keywords. On any match, return HARD_REJECT with BLACKLIST_KEEPER_AMBIGUOUS_RULES.
10. Check market dispute history: if prior_disputes > 0, return HARD_REJECT with BLACKLIST_KEEPER_PRIOR_DISPUTE.
11. All checks passed — return APPROVE with inputs_used list and checked_at timestamp (ms).

10. Reference Implementation

Runs five sequential guardrail checks — KillSwitch, banned-market registry lookup, banned-counterparty registry lookup, structural market checks (time-to-resolution, single-source, ambiguity keywords, dispute history) — before emitting a RiskVote. All checks are fail-closed: any registry or data-source error produces HARD_REJECT.

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

FUNCTION evaluateBlacklist(intent):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT RiskVote(decision=HARD_REJECT, reason=KILL_SWITCH_ACTIVE)
    RETURN

  // --- 1. Banned-market registry check ---
  bannedMarkets = FETCH internal.registry.banned_markets
  IF bannedMarkets IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_DATA_UNAVAILABLE,
                  detail="banned_markets registry unavailable")
    RETURN
  IF bannedMarkets.contains(intent.market_id):
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_MARKET_BANNED,
                  market_id=intent.market_id)
    RETURN

  // --- 2. Banned-counterparty registry check ---
  bannedCounterparties = FETCH internal.registry.banned_counterparties
  IF bannedCounterparties IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_DATA_UNAVAILABLE,
                  detail="banned_counterparties registry unavailable")
    RETURN
  IF bannedCounterparties.contains(intent.counterparty):
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_COUNTERPARTY_BANNED,
                  counterparty=intent.counterparty)
    RETURN

  // --- 3. Fetch Gamma market metadata ---
  market = FETCH gamma.getMarketByConditionId(intent.market_id)
  IF market IS NULL OR market.fetched_at_ms < now_ms() - 300000:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_DATA_UNAVAILABLE,
                  detail="gamma market metadata unavailable or stale")
    RETURN

  // --- 4. Time-to-resolution check ---
  htr = (market.end_date_ms - now_ms()) / 3600000
  IF htr < params.min_hours_to_resolution:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_NEAR_RESOLUTION,
                  hours_to_resolution=htr)
    RETURN
  IF htr < 4:
    annotations.append(WARN(BLACKLIST_KEEPER_NEAR_RESOLUTION, hours_to_resolution=htr))

  // --- 5. Single-source resolution check ---
  IF params.block_single_source AND market.single_source:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_SINGLE_SOURCE)
    RETURN

  // --- 6. Ambiguity keyword scan ---
  FOR keyword IN params.ambiguity_keywords:
    IF keyword IN market.resolution_rules.lower():
      EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_AMBIGUOUS_RULES,
                    keyword=keyword)
      RETURN

  // --- 7. Prior dispute history check ---
  IF market.prior_disputes > 0:
    EMIT RiskVote(decision=HARD_REJECT, reason=BLACKLIST_KEEPER_PRIOR_DISPUTE,
                  prior_disputes=market.prior_disputes)
    RETURN

  // --- 8. All checks passed ---
  EMIT RiskVote(decision=APPROVE, reason=BLACKLIST_KEEPER_PASS,
                inputs_used=["internal.registry.banned_markets",
                             "internal.registry.banned_counterparties",
                             "gamma.market.resolution_rules",
                             "gamma.market.single_source",
                             "gamma.market.end_date_ms",
                             "gamma.market.prior_disputes"],
                annotations=annotations,
                checked_at=now_ms())

SDK calls used

• gamma.getMarketByConditionId(market_id)
• internal.registry.banned_markets.contains(condition_id)
• internal.registry.banned_counterparties.contains(wallet)
• internal.killswitch.status()
• toPusdUnits(amount)

Complexity: O(1) — constant number of registry lookups and linear keyword scan over resolution_rules text (bounded by max text length ~2 KB); all backed by in-memory Redis cache

11. Wire Examples

Input — what arrives on the wire

OrderIntent from strategy — market on banned list — internal

{
  "intent_id": "int_a1b2c3d4e5f6a7b8",
  "trace_id": "trc_0011223344556677",
  "market_id": "0x3f7a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "side": "BUY",
  "outcome": "YES",
  "size_pusd": 250,
  "price": 0.6,
  "counterparty": "0xFa9E1234567890AbCdEf1234567890AbCdEf1234",
  "wallet": "0x1aBcDeF0987654321AbCdEf0987654321AbCdEf09",
  "generated_at_ms": 1746780000000
}

Gamma market metadata for the target market — gamma

{
  "condition_id": "0x3f7a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
  "resolution_rules": "This market resolves YES if the primary government agency publishes an official statement before end date.",
  "single_source": false,
  "end_date_ms": 1746866400000,
  "prior_disputes": 0,
  "neg_risk": false,
  "fetched_at_ms": 1746779980000
}

Output — what the bot emits

RiskVote — HARD_REJECT (market banned)

{
  "guard_id": "risk.blacklist_keeper",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "BLACKLIST_KEEPER_MARKET_BANNED",
  "message": "Market 0x3f7a...7f8a is on the banned-market registry. Order rejected.",
  "constraints": {},
  "inputs_used": [
    "internal.registry.banned_markets",
    "internal.registry.banned_counterparties",
    "gamma.market.resolution_rules",
    "gamma.market.single_source",
    "gamma.market.end_date_ms"
  ],
  "trace_id": "trc_0011223344556677",
  "checked_at": "2026-05-09T11:05:00Z"
}

RiskVote — APPROVE (all checks pass)

{
  "guard_id": "risk.blacklist_keeper",
  "decision": "APPROVE",
  "severity": "INFO",
  "reason_code": "BLACKLIST_KEEPER_PASS",
  "message": "All blacklist and structural checks passed for market 0xb2c3...e4f5.",
  "constraints": {},
  "inputs_used": [
    "internal.registry.banned_markets",
    "internal.registry.banned_counterparties",
    "gamma.market.resolution_rules",
    "gamma.market.single_source",
    "gamma.market.end_date_ms",
    "gamma.market.prior_disputes"
  ],
  "trace_id": "trc_aabbccddeeff0011",
  "checked_at": "2026-05-09T11:05:02Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.blacklist_keeper",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "BLACKLIST_KEEPER_MARKET_BANNED",
  "message": "Market 0x3f7a...d9c2 is on the banned-market registry. Order rejected.",
  "constraints": {},
  "inputs_used": [
    "internal.registry.banned_markets",
    "internal.registry.banned_counterparties",
    "gamma.market.resolution_rules",
    "gamma.market.single_source",
    "gamma.market.end_date_iso"
  ],
  "checked_at": "2026-05-09T11:05:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / BlacklistKeeper
• Grafana — Risk compliance / banned-market and banned-counterparty hit rates

16. Developer Reporting

{
  "bot_id": "risk.blacklist_keeper",
  "decision": "HARD_REJECT",
  "reason_code": "BLACKLIST_KEEPER_MARKET_BANNED",
  "inputs_used": [
    "internal.registry.banned_markets",
    "gamma.market.resolution_rules"
  ],
  "metrics": {
    "market_id": "0x3f7a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
    "counterparty": "0xAbCd...redacted",
    "registry_hit": true,
    "hours_to_resolution": 18.3,
    "single_source": false,
    "ambiguity_keyword_found": null,
    "prior_disputes": 0
  },
  "checked_at": "2026-05-09T11:05:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, registry snapshot is loaded from Redis synchronously before the first evaluation. If Redis is unavailable, all evaluations return HARD_REJECT(BLACKLIST_KEEPER_DATA_UNAVAILABLE) until connectivity is restored.

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

• Operator registry poisoning: unauthorized modification of the banned-market or banned-counterparty SET in Redis, either to add legitimate markets (denial-of-service) or to remove banned entries (allowing hostile markets through)
• Cache timing window: submitting an order for a newly banned market within the 30s registry refresh window before the in-memory snapshot is updated
• Resolution-rules text injection: crafting a market with resolution_rules text that avoids ambiguity keywords but is semantically ambiguous, evading keyword-based detection

Mitigations

• Redis registry SETs are write-protected by role-based access control; only the risk-admin service account may modify entries
• Registry refresh is triggered both on TTL expiry and on write events (Redis keyspace notifications) to minimize the window between a ban and its enforcement
• Fail-closed policy: Redis unavailability → HARD_REJECT, never APPROVE
• All registry modifications are audit-logged with timestamp, operator ID, and before/after state

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

BlacklistKeeper incidents typically involve a Redis registry outage causing fail-closed mass rejections, a stale registry cache preventing a newly banned market from being blocked, or an unexpected spike in ambiguity-rule rejections indicating a new market category has been listed without review.

On-call actions

Manual overrides

• —
• —
• —

Healthcheck

GET /internal/health/blacklistkeeper → 200 if Redis registry SETs are reachable, snapshot age < 30s, and Gamma metadata cache is populated for all recently seen market_ids; red if Redis is unreachable, registry snapshot age > 60s, Gamma metadata fetch failing for > 60s, or p99 evaluation latency > 100ms.

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%