4.7 OnChainWatcher

1. Bot Identity

2. Purpose

OnChainWatcher monitors Polygon on-chain events for a configured list of high-signal wallet addresses, detecting CTFExchangeV2 order fills, position transfers, and pUSD balance changes that exceed min_position_change_usd. It emits an ObservationReport for each qualifying wallet event after a publish_delay_s hold (to prevent front-running its own signals). Output feeds liquidity-aware strategies and the LiquidityGuard risk bot with smart-money flow intelligence. OnChainWatcher is strictly read-only — it never submits or signs orders.

3. Why This Bot Matters

• High-signal wallet entry not detected

  Strategy misses a leading indicator; enters after the smart-money move has already re-priced the market, capturing reduced or negative edge.

• publish_delay_s misconfigured to zero

  OnChainWatcher signals are published immediately, allowing the trading infrastructure itself to front-run other participants using its own on-chain data feed.

• Watched wallet list stale after wallet rotation

  Previously high-signal addresses are no longer the active trading wallets; signals become irrelevant and may mislead strategies.

• RPC outage causes missed position changes during high-activity period

  Smart-money entries during the blackout are not detected; strategies enter a market after the signal window has closed.

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_position_change_usd": 500 }

if (p.min_position_change_usd < p.hard) return; // silently skip dust

{ "publish_delay_s": 15 }

if (p.publish_delay_s < 5) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "poll_interval_s": 12 }

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

8. Default Configuration

{
  "bot_id": "intel.onchainwatcher",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "min_position_change_usd": 500,
    "publish_delay_s": 15,
    "poll_interval_s": 12
  },
  "locked": {
    "min_position_change_usd": {
      "min": 50
    },
    "publish_delay_s": {
      "min": 5
    },
    "poll_interval_s": {
      "max": 60
    }
  }
}

9. Implementation Flow

1. On startup, subscribe to Polygon RPC event log for CTFExchangeV2 OrderFilled events and pUSD Transfer events, filtered to watched_wallets addresses.
2. On each block (poll_interval_s), fetch new events since last_processed_block.
3. For each event, check if wallet address is in watched_wallets. If not, skip.
4. Resolve CTFExchangeV2 token_id to condition_id via data_api. If resolution fails, buffer event and retry on next block.
5. Compute position_change_pusd from event size fields (denominated in pUSD).
6. If position_change_pusd < min_position_change_usd hard floor (50 pUSD), discard as dust.
7. If position_change_pusd < min_position_change_usd default (500 pUSD), flag ONCHAINWATCHER_SMALL_POSITION.
8. Add event to publish_queue with emit_at = now_ms() + publish_delay_s * 1000.
9. Check KillSwitch. If active, continue monitoring and queuing but suppress emissions.
10. On each tick, drain publish_queue of events whose emit_at <= now_ms().
11. For each drained event (if KillSwitch not active), emit ObservationReport with: report_id, trace_id, wallet_address, condition_id, side (BUY/SELL), position_change_pusd, price, block_number, tx_hash, warnings.
12. Log per-block summary: events_detected, events_emitted, events_queued, dust_skipped, killswitch_active.

10. Reference Implementation

Subscribes to Polygon RPC event log for CTFExchangeV2 OrderFilled events filtered to watched_wallets, resolves token IDs to condition_ids, applies dust filter and size threshold, holds events for publish_delay_s, then emits ObservationReports.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output.

FUNCTION watchBlock(block_number):
  // --- 0. RPC health check ---
  IF rpc.last_block_age_s > 2 * params.poll_interval_s:
    EMIT WARN 'STALE_DATA — RPC unresponsive'
    RETURN

  // --- 1. Fetch new events since last_processed_block ---
  events = rpc.getLogs(
    address   = CTFEXCHANGEV2_ADDR,
    topics    = [ORDER_FILLED_SIG, PUSD_TRANSFER_SIG],
    fromBlock = last_processed_block + 1,
    toBlock   = block_number
  )

  // --- 2. KillSwitch gate ---
  ks = FETCH internal.killswitch.status

  FOR event IN events:
    // --- 3. Wallet filter ---
    wallet = event.makerAddress OR event.takerAddress
    IF wallet NOT IN params.watched_wallets:
      CONTINUE

    // --- 4. Resolve token_id -> condition_id ---
    condition_id = data_api.GET('/token/' + event.tokenId + '/condition')
    IF condition_id IS NULL:
      buffer_for_retry(event)
      CONTINUE

    // --- 5. Dust filter ---
    position_change_pusd = toPusdUnits(event.fillAmount)
    IF position_change_pusd < params.min_position_change_usd.hard:
      dust_skipped_counter += 1
      CONTINUE

    // --- 6. Warning threshold ---
    warnings = []
    IF position_change_pusd < params.min_position_change_usd.default:
      warnings.append('ONCHAINWATCHER_SMALL_POSITION')

    side = 'BUY' IF event.makerSide == 'SELL' ELSE 'SELL'

    // --- 7. Queue with publish delay ---
    publish_queue.add({
      wallet_address:          wallet,
      condition_id:            condition_id,
      side:                    side,
      position_change_pusd:    position_change_pusd,
      price:                   event.price,
      block_number:            block_number,
      tx_hash:                 event.transactionHash,
      emit_at_ms:              now_ms() + params.publish_delay_s * 1000,
      warnings:                warnings
    })

  // --- 8. Drain publish queue ---
  FOR item IN publish_queue.due_items(now_ms()):
    // KillSwitch suppress
    IF ks.active:
      LOG INFO 'KILL_SWITCH_ACTIVE — suppressing ObservationReport'
      CONTINUE

    EMIT ObservationReport {
      report_id:              'rep_ocw_' + item.condition_id[:6] + '_' + now_ms(),
      trace_id:               new_trace_id(),
      bot_id:                 'intel.onchainwatcher',
      kind:                   'ObservationReport',
      wallet_address:         item.wallet_address,
      condition_id:           item.condition_id,
      side:                   item.side,
      position_change_pusd:   item.position_change_pusd,
      price:                  item.price,
      block_number:           item.block_number,
      tx_hash:                item.tx_hash,
      publish_delay_applied_s: params.publish_delay_s,
      warnings:               item.warnings,
      emitted_at_ms:          now_ms()
    }

  last_processed_block = block_number

SDK calls used

• rpc.getLogs(address=CTFEXCHANGEV2_ADDR, topics=[ORDER_FILLED_SIG], fromBlock, toBlock)
• data_api.GET('/token/<tokenId>/condition')
• toPusdUnits(fillAmount)

Complexity: O(E) per block where E = OrderFilled events for watched wallets; typically O(1) in steady state

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Polygon RPC CTFExchangeV2 OrderFilled event for watched wallet",
  "source": "onchain",
  "payload": {
    "event": "OrderFilled",
    "makerAddress": "0xF1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0",
    "takerAddress": "0x000000000000000000000000000000000000dead",
    "tokenId": "87654321",
    "fillAmount": "12500000000",
    "price": "0.68",
    "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "block_number": 72346001,
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — high-signal wallet BUY detected",
  "payload": {
    "report_id": "rep_ocw_0xf1a2_1746703000000",
    "trace_id": "trc_0xbeef0102030405060708",
    "bot_id": "intel.onchainwatcher",
    "kind": "ObservationReport",
    "wallet_address": "0xF1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0",
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "side": "BUY",
    "position_change_pusd": 12500,
    "price": 0.68,
    "block_number": 72346001,
    "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "publish_delay_applied_s": 15,
    "warnings": [],
    "emitted_at_ms": 1746703015000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_ocw_0xf1a2_1746703000000",
  "trace_id": "trc_0xbeef0102030405060708",
  "bot_id": "intel.onchainwatcher",
  "kind": "ObservationReport",
  "wallet_address": "0xF1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "side": "BUY",
  "position_change_pusd": 12500,
  "price": 0.68,
  "block_number": 72346001,
  "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
  "publish_delay_applied_s": 15,
  "warnings": [],
  "emitted_at_ms": 1746703015000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / OnChainWatcher wallet event rate and queue depth
• Grafana — Intelligence / per-wallet position change size distribution

16. Developer Reporting

{
  "bot_id": "intel.onchainwatcher",
  "block_number": 72346001,
  "events_detected": 8,
  "events_emitted": 3,
  "events_queued": 2,
  "dust_skipped": 3,
  "condition_id_resolutions_failed": 0,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, last_processed_block loaded from Redis. Missed blocks since last checkpoint re-fetched from RPC. publish_queue drained normally.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

4.14

External services

23. Security Surfaces

Abuse vectors considered

• Adversary discovers watched_wallets list and wash-trades to inject false buy/sell signals
• RPC provider returns crafted event logs to fake large wallet fills for a specific condition_id

Mitigations

• watched_wallets list is operator-confidential config; not exposed in ObservationReport payloads
• publish_delay_s minimum (5 s) prevents use as a sub-second front-run vector
• All ObservationReports are informational only — LiquidityGuard and strategies independently validate market state before acting on signals

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

OnChainWatcher incidents are most commonly RPC outages or data_api failures preventing condition_id resolution. An RPC outage causes smart-money signals to be missed for the outage duration. Page immediately on RPC down.

On-call actions

Manual overrides

• —

Healthcheck

Endpoint: /internal/health/onchainwatcher | Green: rpc_block_lag_s < 24 AND Redis reachable AND publish_queue_depth < 50 AND watched_wallets non-empty | Red: rpc_block_lag_s > 60 OR Redis unreachable OR watched_wallets empty OR publish_queue_depth > 200

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%