Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

System transactions

Stable uses system transactions to convert SDK module events into standard EVM logs. Applications can consume those logs through eth_getLogs or an existing WebSocket subscription.

For example, a system transaction emits UnbondingCompleted after the staking module finishes an unbonding operation. The event includes the delegator, validator, original completion height, and amount.

What applications receive

Consider tracking when a user's tokens finish unbonding. Without system transactions, a dApp would need to either:

  • Run a separate indexer that watches for SDK events and stores them in its own database. Operational overhead plus a new failure point.
  • Poll a REST endpoint periodically. 5–10 second latency, higher RPC load, two client stacks (web3 + REST) to maintain.

System transactions give dApps real-time event notifications through the same WebSocket connections they already use for EVM logs. No separate indexer. No REST polling.

How the flow works

1. Protocol event:    An SDK-layer operation completes (e.g. staking unbonding).
2. Detection:         The x/stable EndBlocker detects the event and queues it in state.
3. System TX:         In the next block's PrepareProposal, the protocol generates a
                      system transaction calling StableSystem.notifySystemTxLogs().
4. EVM emission:      The precompile processes the queued entries and emits standard
                      EVM events. dApps see them through eth_getLogs and subscriptions.

The system transaction is created by validators during block proposal, not by users. It lands at the front of the block, before any user transactions.

The StableSystem precompile

Events flow through the StableSystem precompile at 0x0000000000000000000000000000000000009999. Today it emits UnbondingCompleted with the delegator, validator, original completion height, and amount.

The same precompile exposes the public blockspaceLanes() view method. It returns the active Enterprise and transaction-type lane registry for off-chain transaction classification.

Security model

Two properties keep the event stream trustworthy:

  • Protocol-only sender. System transactions use 0x0000000000000000000000000000000000000001 as their sender. The EVM state-transition rules reserve this address for protocol-generated transactions. Users cannot forge events or call notifySystemTxLogs() from their own transactions.
  • Deterministic emission. Every honest validator produces the same system transaction for the same protocol events. There's no additional trust assumption beyond standard consensus.

Batch processing

To bound block size, each call processes at most 100 queued system log entries. If a burst exceeds the limit, the remaining entries stay queued for later blocks.

There's a one-block (~700 ms) delay between the SDK event and the EVM emission, which is negligible relative to the 7-day unbonding period itself.

Where to find the ABI

The StableSystem interface, blockspace return types, event signatures, and authorization rules are in the System transactions reference.

Where to go next