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, action schemas, 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 ActionSchema names. Available only if stfSchemaMap parameter was passed to MicroRollup constructor.

Returns: Record<string, string>

Action Handling

`submitAction(reducerName: string, action: Action)`

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

Parameters:

reducerName: Name of the reducer handling the action.
action: Action object to be processed.

Returns: Promise<SerializedAcknowledgement>

`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.

Parameter:

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

Returns: Promise<SerializedAction> (definition)

`actions.getSchema(identifier: string)`

Fetches a specific action schema by its identifier.

Parameters:

identifier: Unique identifier of the schema.

Returns: ActionSchema | undefined

`actions.getByHash(actionHash: string)`

Retrieves a serialized action from the rollup using its hash.

Parameters:

actionHash: Hash of the action.

Returns: Promise<SerializedAction | null> (definition)

`actions.getAllSchemas()`

Returns all action schemas available in the Micro-Rollup.

Returns: SchemaObject[]

`actions.waitFor(actionHash: Keccak256, confirmationStatus = ActionConfirmationStatus.C1)`

Waits for an action to reach a certain confirmation status. Returns immediately if the action is already at or higher than the desired status.

Parameter:

actionHash: Hash of the action.
confirmationStatus: Confirmation status to wait for (defaults to C1). Can take one of C1, C2, C3A or C3B.

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.

Parameter:

filters: Fields to filter on.

interface ActionFilterParams {
  name?: string;
  schemaIdentifier?: 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.

Parameters:

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.

Parameters:

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.

Parameters:

height: Height of the block.

Returns: Promise<BlockData | null>

`chain.getBlockByHash(hash)`

Retrieves a block by its hash.

Parameters:

hash: Hash of the block.

Returns: Promise<BlockData | null>

`chain.getBlockByActionHash(actionHash)`

Retrieves a block containing a specific action by its hash.

Parameters:

actionHash: Hash of the action.

Returns: Promise<BlockData | null>

Event Handling

`events`

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