Micro-Rollup Utilities

The Micro-Rollup object exposes a few utility functions that can be used for various purposes -

Initialization and Termination

init()

Initializes the Micro-Rollup instance. Sets up all necessary configurations, and state machines required for the rollup to operate.

Returns: Promise<void>

shutdown()

Gracefully shuts down the Micro-Rollup instance, ensuring all pending operations are completed and resources are properly released.

Returns: Promise<void>

Configuration

config

A readonly object representing the final configuration of the Micro-Rollup. This is essentially a flattened and complete version of StackrConfig combined with values from deployment.json.

Returns: Readonly<ExternalConfig> (definition)

getStfSchemaMap()

A map of the STF names to the EIP-712 types definition.

Returns: Record<string, Record<string, TypedDataField[]>>

Action Handling

submitAction(actionParams: ActionParams)

Submits an action to be processed by the rollup, routed based on the specified transition name.

• actionParams: ActionParams object to be processed. (definition)

Returns: Promise<SerializedAcknowledgement> (definition)

ack.waitFor(confirmationStatus? = ActionConfirmationStatus.C1)

Waits for the action, for which the acknowledgment is created, to reach a specific confirmation status. Returns immediately if the action has already reached or surpassed the desired status.

• confirmationStatus: ActionConfirmationStatus to wait for (defaults to C1). Can take one of C1, C2, C3A or C3B.

Returns: Promise<SerializedAction> (definition)

actions.getByHash(actionHash: string)

Retrieves a serialized action from the rollup using its hash.

• actionHash: Hash of the action.

Returns: Promise<SerializedAction | null> (definition)

actions.query(filters: ActionFilterParams, orderAsc?: boolean)

Query and fetch list of actions along with their block data (if applicable) from DB.

• filters: Fields to filter on.

  interface ActionFilterParams {
    name?: string;
    executionStatus?: ActionExecutionStatus | ActionExecutionStatus[];
    confirmationStatus?: ActionConfirmationStatus | ActionConfirmationStatus[];
    block?: {
      status?: BlockStatus;
      isReverted?: boolean;
    };
  }

• orderAsc: Whether the actions should be sorted in ascending or descending order of block height and position in block. Defaults to ascending order.

Returns: Promise<SerializedActionAndBlock[]> (definition)

Sequencer Functions

sequencer.setStrategy(strategy: BaseStrategy)

Set the sequencer strategy for your micro-rollup's sequencer. Defaults to FIFOStrategy.

Returns: void

sequencer.start()

Starts the sequencer to process actions.

Returns: void

sequencer.stop()

Stops the sequencer.

Returns: void

sequencer.tick()

Processes the next set of actions in one sequencer tick. Returns flag indicating whether a new block was sequenced or not.

Returns: Promise<boolean>

State Machine Operations

stateMachines.get(id)

Retrieves a specific state machine by its identifier.

• id: Identifier of the state machine.

Returns: T | undefined

stateMachines.getFirst()

Retrieves the first state machine in the rollup.

Returns: T

stateMachines.getAllTransitions()

Lists all transitions available within the state machines.

Returns: string[]

Syncer Functions

syncer.start(slotTime)

Starts the syncer with a specified slot time.

• slotTime: Time interval in milliseconds between each block.

Returns: void

syncer.stop()

Stops the syncer.

Returns: void

syncer.submitBlock()

Submits the earliest block with C1 confirmation to Vulcan for verification.

Returns: Promise<void>

Chain Interaction

chain.getCurrentHeight()

Retrieves the current blockchain height.

Returns: Promise<number>

chain.getBlockByHeight(height)

Retrieves a block by its height.

• height: Height of the block.

Returns: Promise<BlockData | null> (definition)

chain.getBlockByHash(hash)

Retrieves a block by its hash.

• hash: Hash of the block.

Returns: Promise<BlockData | null> (definition)

chain.getBlockByActionHash(actionHash)

Retrieves a block containing a specific action by its hash.

• actionHash: Hash of the action.

Returns: Promise<BlockData | null> (definition)

Event Handling

events

Handles subscriptions to events within the Micro-Rollup framework. More about these in the next section.