6.13 UserActivityLedger

1. Bot Identity

2. Purpose

UserActivityLedger records every user-initiated action — strategy starts, parameter changes, halts, and overrides — as a SettlementReport, providing a per-user, per-session compliance ledger retained for 7 years.

3. Why This Bot Matters

• No user activity ledger

  Regulatory requests for user action history cannot be fulfilled; compliance audit fails.

• User activity not linked to fills

  It is impossible to reconstruct which user action led to which trade; audit trail is broken.

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

{ "retain_days": 2555 }

if p.retain_days < 2555: emit('RETENTION_BELOW_REGULATORY_MINIMUM')

{ "scrub_on_account_close": false }

if p.scrub_on_account_close: record.wallet = hash(record.wallet)

8. Default Configuration

{
  "bot_id": "gov.useractivityledger",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "retain_days": 2555,
    "export_format": "jsonl",
    "scrub_on_account_close": false,
    "publish_to_user": true
  }
}

9. Implementation Flow

1. Subscribe to user action events on the internal platform event stream.
2. For each event, record: wallet_address, session_id, action_type, parameters, timestamp.
3. Link fill events to user sessions via trace_id from ExecutionReport.
4. Emit SettlementReport(event_type=USER_ACTION_RECORDED) on every action.
5. Enforce retain_days; purge records older than retention window (or scrub PII if scrub_on_account_close=true).
6. Provide a read API for compliance export in jsonl format.

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.

// ---- SUBSCRIBE TO USER EVENTS ----
FUNCTION onUserAction(event):
  record = {
    wallet_address: event.wallet,
    session_id:     event.session_id,
    action_type:    event.action_type,
    action_params:  event.params,
    trace_id:       event.trace_id,
    recorded_at:    now()
  }
  IF postgres.exists('user_activity_ledger', idempotency_key=event.event_id):
    RETURN  // deduplicate replay
  postgres.insert('user_activity_ledger', record)
  EMIT SettlementReport(event_type='USER_ACTION_RECORDED', ...record,
    retained_until=now() + days(config.retain_days))

// ---- LINK FILL TO SESSION ----
FUNCTION onExecutionReport(execReport):
  ledgerRows = postgres.select('user_activity_ledger',
    WHERE trace_id = execReport.trace_id)
  FOR row IN ledgerRows:
    row.fill_ids.append(execReport.fill_id)
    postgres.upsert('user_activity_ledger', row)
    EMIT SettlementReport(event_type='ACTION_LINKED_TO_FILL', ...)

SDK calls used

• postgres.insert('user_activity_ledger', record)
• postgres.select('user_activity_ledger', WHERE trace_id=...)
• alerting.emit('RETENTION_BELOW_REGULATORY_MINIMUM')

Complexity: O(1) per user action; O(R) for fill linking where R = ledger rows per trace_id

11. Wire Examples

Input — what arrives on the wire

{
  "label": "User action event",
  "source": "internal.event_stream",
  "payload": {
    "event_id": "evt_01HX9Z",
    "wallet": "0xdeadbeef00000000000000000000000000000001",
    "session_id": "sess_01HX9Z",
    "action_type": "STRATEGY_START",
    "params": {
      "strategy": "sports-model"
    },
    "trace_id": "trc_01HX9Z"
  }
}

Output — what the bot emits

{
  "label": "SettlementReport — USER_ACTION_RECORDED",
  "payload": {
    "report_id": "stl_activity_01HX9Z",
    "event_type": "USER_ACTION_RECORDED",
    "wallet_address": "0xdeadbeef00000000000000000000000000000001",
    "action_type": "STRATEGY_START",
    "report_kind": "SettlementReport",
    "topic": "polytraders.reports.settlement",
    "retained_until": "2033-05-09"
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a SettlementReport object. See SettlementReport schema.

{
  "report_id": "stl_useractivityledger_01HX9Z",
  "bot_id": "gov.useractivityledger",
  "event_type": "USER_ACTION_RECORDED",
  "wallet_address": "0xdeadbeef00000000000000000000000000000001",
  "session_id": "sess_01HX9Z",
  "action_type": "STRATEGY_START",
  "action_params": {
    "strategy": "sports-model",
    "max_size_pusd": 500.0
  },
  "trace_id": "trc_01HX9Z",
  "recorded_at": "2026-05-09T10:00:00Z",
  "report_kind": "SettlementReport",
  "topic": "polytraders.reports.settlement",
  "retained_until": "2033-05-09"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "gov.useractivityledger",
  "event_type": "ACTION_LINKED_TO_FILL",
  "session_id": "sess_01HX9Z",
  "fill_id": "fill_00a1b2c3d4e5f6a7",
  "linked_at_ms": 1746792060000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, flush memory buffer; resume event stream consumption from last committed offset.

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

• Querying another user's activity ledger without authorisation

Mitigations

• All ledger reads require authenticated user context; wallet_address is verified against session token

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

UserActivityLedger incidents are usually Postgres unavailability or retention config breaches.

On-call actions

Manual overrides

• —

Healthcheck

/internal/health/useractivityledger → green if Postgres reachable; buffer_size == 0; retention_days >= 2555; red if retention_days < 2555 or buffer_size > 500

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%