Event vocabulary

The append-only event log is the spine of Olbos. It is simultaneously the audit trail, the replay source, the engine checkpoint, and the dashboard's narration feed. If it isn't an event, it didn't happen. This is the complete vocabulary.

Envelope

Every event is wrapped as it's persisted:

interface EventRecord {
  seq: number;          // monotonic sequence, assigned by the log
  ts: string;           // ISO-8601 timestamp
  correlationId: string;// ties together all events from one logical action
  event: EngineEvent;   // the payload (one of the types below)
}

correlationId is what makes tenant isolation possible: a tx.confirmed (keyed by intent ID, not strategy) is linked back to its strategy because it shares a correlation ID with that strategy's rebalance.proposed. See Security — multi-tenancy.

Strategy lifecycle

Event	Meaning
`strategy.deployed`	a strategy was created — carries `strategyId`, `policy`, `owner`
`strategy.paused` / `strategy.resumed`	lifecycle transitions

Custody

Event	Meaning
`custody.created`	the per-strategy Swig is live: `swigAddress`, `walletAddress`, `owner`, `engineRoleId`, `dailyCapUsdc`, `payoutDestination`. Funding is gated on this.
`custody.revoked`	the owner removed the engine's role on-chain — terminal break-glass

Capital flows

Event	Meaning
`deposit.credited`	capital credited to a strategy (`amount`, `source`, `ref`)
`withdrawal.executed`	positions unwound to liquid (`amount`, `signature`)
`payout.executed`	owner-signed transfer out to the owner's wallet (`amount`, `to`, `signature`)

Market observation

Event	Meaning
`apy.sampled`	the venue rates the engine saw this cycle (per-venue `apyBps`, `index`) — shared market data, not tenant-specific

Decisions

Event	Meaning
`rebalance.proposed`	a planned move (`from`, `to`, `amount`, `improvementBps`) — before gating
`risk.passed`	the risk gate approved an action
`risk.blocked`	the risk gate (or a policy gate) rejected an action, with `reason`

A blocked move is as important to the audit as an executed one — it's evidence the bounds are holding.

Execution pipeline

Event	Meaning
`tx.simulated`	a transaction was simulated (`ok`; `error` if it failed — and it's never sent)
`tx.sent`	broadcast (`signature`)
`tx.confirmed`	confirmed on-chain (`signature`, `slot`)
`tx.failed`	failed at send/confirm (`error`)
`rebalance.executed`	a move landed (`from`, `to`, `amount`, `signature`)

These are keyed by intent ID, the deterministic content hash that gives at-most-once execution. See Architecture — intents.

Safety

Event	Meaning
`kill.activated`	break-glass engaged — `by: "owner"` or `by: "engine fail-safe"`
`kill.cleared`	break-glass released
`reconcile.mismatch`	an invariant violation (e.g. a venue health-check failure) — `detail`

Payments (x402)

Event	Meaning
`x402.payment.received`	the engine was paid (`endpoint`, `amount`, `payer`, `settlementTx`)
`x402.payment.sent`	the engine paid for an input, e.g. premium data (`endpoint`, `amount`, `settlementTx`)

Why this design

Audit is free. There's no separate audit system to keep in sync — the log is the audit.
Replay is truth. The engine's entire view (strategies, custody, kill state) is a fold over these events. Lose the in-memory state, replay the log, you're back.
Idempotency is cheap. Before acting, the engine reads the log; a prior tx.confirmed for an intent means "already done."
The dashboard is honest. It narrates these events directly — it can't show something that didn't happen, because there'd be no event for it.

Next: Architecture · API reference.

On this page