Events Framework

Get granular insights into the Micro-Rollup

Stackr provides a really powerful events framework that allows developers to get granular insights into the Micro-Rollup's working. This framework is designed to provide a detailed view of the state transitions that are happening within the Micro-Rollup.

Subscribing to events

You can subscribe to specific events by using the events utility returned by the rollup instance like this

index.ts

import { ConfirmationEvents } from "@stackr/sdk";
 
const rollup = await MicroRollup({
  config: stackrConfig,
  stateMachines: [machine],
});
 
await rollup.init();
 
// subscribe to Confirmation event
rollup.events.subscribe(ConfirmationEvents.C0, (args) => { 
  // take any action here with args
  console.log("C0 event fired", args); 
});

Unsubscribing from events

You can unsubscribe from an existing event subscription like this

const listener = (args) => {...};
rollup.events.subscribe(ConfirmationEvents.C0, listener); // previously subscribed event
 
/**
 * Some logic in between
 */
 
rollup.events.unsubscribe(ConfirmationEvents.C0, listener);

Inspecting active subscriptions

You can inspect all active subscriptions for a particular event like this

const listeners: { name: string, code: string }[] = rollup.events.getListeners(ConfirmationEvents.C0);

Event Types and Arguments

This framework supports a variety of events that cover different aspects of the Micro-Rollup's operation, from action submission to block acknowledgment by the Vulcan system.

Action Events

`ActionEvents.SUBMIT`

Triggered when an action is submitted.

Event Arguments: ActionSubmitEventArgs

actionName: Name of the action submitted.
actionHash: Hash of the action.
msgSender: Address of the sender.
signature: Signature of the action.
payload: Input types allowed for the action.

`ActionEvents.REJECT`

Occurs when an action is rejected.

Event Arguments: ActionSubmitEventArgs

Follows the same structure as ActionEvents.SUBMIT.

`ActionEvents.EXECUTION_STATUS`

Fires when there is a status update on the execution of an action.

Event Arguments: ActionExecutionStatusEventArgs

actionName: Name of the action.
actionHash: Hash of the action.
status: Execution status of the action.
logs: Logs during the execution of action.
errors: Errors during the execution of action.

`ActionEvents.CONFIRMATION_STATUS`

Triggered when the confirmation status of an action is updated.

Event Arguments: ActionConfirmationStatusEventArgs

actionName: Name of the action.
actionHash: Hash of the action.
status: Confirmation status of the action.

Action Pool Events

`ActionPoolEvents.ENQUEUE`

Occurs when an action is enqueued.

Event Arguments: ActionPoolEnqueueEventArgs

actionHash: Hash of the action enqueued.

Sequencer Events

`SequencerEvents.ACTION_PICK`

Occurs when an action is picked by the sequencer.

Event Arguments: SequencerPickActionEventArgs

actionHash: Hash of the action picked.
blockParentHash: Hash of the parent block.
blockHeight: Current block height.

`SequencerEvents.ORDER_ACTIONS`

Triggered when actions are ordered by the sequencer.

Event Arguments: SequencerOrderActionEventArgs

actionHashes: List of action hashes ordered.
actionRootHash: Root hash of the ordered actions.
signature: Signature verifying the order.
blockParentHash: Hash of the parent block.
blockHeight: Current block height.

`SequencerEvents.PROPOSE_BLOCK`

Occurs when a block is proposed by the sequencer.

Event Arguments: SequencerProposeBlockEventArgs

block: Data of the block proposed.

`SequencerEvents.SEQUENCE_BLOCK`

Occurs when a block is sequenced by the sequencer.

Event Arguments: SequencerSequenceBlockEventArgs

block: Data of the block sequenced.

`SequencerEvents.PAUSED`

Triggered when the sequencer is paused.

Event Arguments: SequencerPausedEventArgs

reason: Reason for the pause.

`SequencerEvents.RESUMED`

Fires when the sequencer is resumed.

Event Arguments: SequencerPausedEventArgs

reason: Reason for the resumption (similar structure as the paused event).

Confirmation Events

Detailed events tracking the various stages of action confirmation, providing insights into each phase of the confirmation process within the Micro-Rollup.

`ConfirmationEvents.C0`

Triggered when action receives and acknowledgement from the rollup operator

Event Arguments: C0EventArgs

actionName: Name of the action being confirmed.
actionHash: Hash of the action.
msgSender: Address of the sender.
signature: Signature of the action.
payload: Input types allowed for the action.
actionNumber: Sequential number of the action in the block.
acknowledgement: Data confirming the preliminary acknowledgment.

`ConfirmationEvents.C1`

Occurs when an action has been successfully applied to the state of the rollup

Event Arguments: C1EventArgs

actionName: Name of the action being confirmed.
actionHash: Hash of the action.
msgSender: Address of the sender.
signature: Signature of the action.
payload: Input types allowed for the action.
state: Current state or relevant state information pertaining to the action.

We emit C1X event when the action execution fails.

`ConfirmationEvents.C2`

Fires when the block is verified by Vulcan

Event Arguments: C2EventArgs

block: Data of the block that includes the confirmed action.

`ConfirmationEvents.C2X`

Triggered when the block was sent to Vulcan but it found the block to be invalid.

Event Arguments: C2EventArgs

Similar to ConfirmationEvents.C2, focusing on exceptional or adjusted block data.

`ConfirmationEvents.C3A`

Triggered when the block body data is settled on DA layer

Event Arguments: C3EventArgs

block: Data of the block awaiting final confirmation.
vulcanResponse: Optional response from Vulcan, if applicable, that may influence the final confirmation status.

`ConfirmationEvents.C3B`

Triggered when an action's block receives final confirmation from ethereum. This event marks the completion of the confirmation process and finalizes the block within the chain.

Event Arguments: C3EventArgs

block: Data of the confirmed block.

Executor Events

`ExecutorEvents.EXECUTE_BLOCK`

Triggered when a block is executed.

Event Arguments: ExecuteBlockEventArgs

previousState: Previous state before execution.
state: Current state after execution.
previousStateRoot: Root hash of the previous state.
stateRoot: Root hash of the state.
actionHashes: List of hashes of executed actions.
executionHooks: List of list of pre and post hooks that were executed as part of this block.
executionHooksLogs: Logs emitted from block hooks.

`ExecutorEvents.EXECUTE_HOOK`

Triggered when a hook is executed.

Event Arguments: ExecuteHookEventArgs

type: Type of the hook.
hookName: Name of the hook.
blockInfo: Information of the block is executed for.
updateResults: Results of the state update containing previousState, newState and logs.

`ExecutorEvents.EXECUTE_ACTION`

Triggered when an action is executed.

Event Arguments: ExecuteActionEventArgs

actionHash: Hash of the action causing the state change.
actionName: Name of the action.
payload: Inputs of the action.
updateResults: Results of the state update containing previousState, newState and logs.

Chain Events

`ChainEvents.REORG`

Triggered when the chain is reorged.

Event Arguments: ChainReOrgEventArgs

blockHashes: Hashes of the blocks reverted