UserActivityLedger

gov.useractivityledger

Governance & Ops planned Spec started frozen

UserActivityLedger records every user-initiated action — strategy starts, parameter changes, halts, and overrides — as a SettlementReport, providing a

What it does

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.

Pipeline placement

runs after: Any user-initiated action: strategy start, parameter change, halt, override → UserActivityLedger → runs before: Nothing — runs on every user action event

Applies to: All user wallet sessions across the Polytraders platform

Why it matters

If this fails	Consequence
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.

Inputs

Polymarket inputs

Input	Source	Required	Use
None — UserActivityLedger consumes internal event stream only	internal	optional	N/A

Internal inputs

Input	Source	Required	Use
User action events from the platform event stream	internal.event_stream	required	Record every user-initiated action with wallet address, session ID, and action type.
ExecutionReport for fills linked to user sessions	internal.report_bus	required	Link fills to the user session that initiated the strategy.

Authority

What this bot is permitted to do

Explain

State

Readiness

Spec started

Status

planned

Class

Governance Service

Default mode

shadow_only

Developer owner

Polytraders core

Capital impact

Indirect

Reason codes emitted

Code	Severity	Meaning	Action
USER_ACTION_RECORDED	INFO	A user action was recorded in the ledger.	Log and emit SettlementReport.
ACTION_LINKED_TO_FILL	INFO	A user action was linked to a fill via trace_id.	Update ledger record.
RETENTION_BELOW_REGULATORY_MINIMUM	WARN	retain_days < 2555.	Emit WARN; refuse config change.
LEDGER_WRITE_FAILED	WARN	Postgres write failed; event buffered in memory.	Buffer; emit WARN; flush on reconnect.
KILL_SWITCH_ACTIVE	WARN	KillSwitch active; KillSwitch event recorded in ledger.	Record kill-switch event as USER_ACTION.

Related bots in Governance & Ops

gov.api_degradation_monitor gov.attributionrevenuereporter gov.backtester

Used by

Reverse index — strategies that currently reference gov.useractivityledger. If you change this bot's authority or reason codes, these strategies must re-pass shadow.

Strategy	State	Activity
US Elect — book-builder	demo-wired	last triggered 25m ago
NBA H2H — moneyline market-make	demo-wired	last triggered 32m ago

Showing 2 of 2 · demo-wired ≠ production-live

Why this matters

Governance & Ops bots does NOT propose, approve, or block trades; only observes and reports. Understanding the authority boundary prevents misuse and makes promotion-gate reviews faster and more reliable. View raw spec JSON →

Polytraders Operator UX Mock · INTERNAL · demo-wired ≠ production-live · the plan · reason codes · shadow-mode pipeline