Skip to content
Getting Started

Running a Micro-rollup

If you are using a template it might already have a micro-rollup setup. But a few things to make sure before running or deploying your micro-rollup are:

MicroRollup Setup

You have created an instance of MicroRollup and passed the necessary options.

Configuration

You have passed the stackrConfig object exported from the stackr.config.ts file to the MicroRollup constructor like this

index.ts
const rollup = await MicroRollup({
  config: stackrConfig, 
  ...
});

Action Registration

You have added all the ActionSchemas to the MicroRollup constructor like this

index.ts
const rollup = await MicroRollup({
  config: stackrConfig,
  actionSchemas: [ActionSchema1, ActionSchema2, ...], 
  ...
});

State Machine Registration

You have added the State Machine lazily to the micro-rollup, using

index.ts
const rollup = await MicroRollup({
  config: stackrConfig,
  actionSchemas: [ActionSchema1, ActionSchema2, ...],
  stateMachines: [machine], 
  ...
});

Initialization

You have started the micro-rollup using

index.ts
const rollup = await MicroRollup({
  config: stackrConfig,
  actionSchemas: [ActionSchema1, ActionSchema2, ...],
  stateMachines: [machine],
  ...
});
 
await rollup.init()

Let's Run 🏃‍♂ [Sandbox mode]

To be doubly sure that everything is working fine, let's try to run your application and see if it works as expected.

In this example, we will run our micro-rollup in sandbox mode.

Run using Node.js

npm
npm start

Run using Docker 🐳

  • Build the image using the following command:
Linux
docker build -t <app_name>:latest .
  • Run the Docker container using the following command:
File-based DB
docker run --env-file .env \
  -v ./db.sqlite:/app/db.sqlite \
  -p <HOST_PORT>:<CONTAINER_PORT> \
  --name=<app_name> -it <app_name>:latest

If everything is working fine, you should see the logs in the terminal, like this:

Terminal
[Stackr] - 04/02/2024, 5:14:19 PM     LOG [InstanceLoader] ExecutorModule dependencies initialized
[Stackr] - 04/02/2024, 5:14:19 PM     LOG [InstanceLoader] SequencerModule dependencies initialized
[Stackr] - 04/02/2024, 5:14:19 PM     LOG [L1-Syncer] Started L1 syncer
[Stackr] - 04/02/2024, 5:14:19 PM     LOG [Vulcan-Syncer] Started with slot time: 1000ms
[Stackr] - 04/02/2024, 5:14:19 PM     LOG [Sequencer] Started with block time: 1000ms

If you see the above logs, congratulations! Your application is running successfully.

Interacting with Micro-rollup

If you are using the "Counter" example, the index.ts file already contains the code to interact with the micro-rollup.

Submitting Action

Using the submitAction method, you can submit the action to the micro-rollup.

index.ts
const inputs = {
  timestamp: Date.now(),
};
 
const signature = await signMessage(wallet, UpdateCounterSchema, inputs);
const incrementAction = UpdateCounterSchema.actionFrom({
  inputs,
  signature,
  msgSender: wallet.address,
});
 
const ack = await mru.submitAction("increment", incrementAction);

Once an action is submitted to the micro-rollup, you get an acknowledgment in the form of a Promise which resolves to the Acknowledgment object. You can use this object to track the status of the action.

Tracking Action's Lifecycle

Using ack.waitFor

The Acknowledgment object returned by submitAction contains a waitFor method that can be used to wait for the action to reach a specific confirmation status.

index.ts
import { SerializedAction } from "@stackr/sdk";
 
/* ... */
 
// resolves when action reaches C1
const action: SerializedAction = await ack.waitFor(ActionConfirmationStatus.C1);

Using events

You can also use the subscribe method to listen for changes to the action's lifecycle.

For example, you can define a custom callback function subscribing to the ActionEvents.CONFIRMATION_STATUS event that is called whenever the confirmation status of the action changes, like this:

index.ts
import { ActionEvents } from "@stackr/sdk";
 
/* ... */
 
mru.events.subscribe(ActionEvents.CONFIRMATION_STATUS, ({ actionName, actionHash, status }) => {
  console.log({ actionName, actionHash, status });
});

Refer to the Events section for more details on this.

Querying the State

You can also query the state of your State Machines anytime using the MRU instance. As below:

index.ts
const machine = mru.stateMachines.get<typeof counterMachine>("counter"); 
if (!machine) {
  throw new Error("Machine not found");
}
const { state } = machine; 
console.log("Current state:", state);

Play with it

Stackr comes with a Playground plugin along with the SDK to interact with the micro-rollup. You can attach the plugin to your MRU instance and use it to debug, interact or track the life-cycle of action or block.

index.ts
import { Playground } from "@stackr/sdk/plugins"; 
 
const mru = new MicroRollup({
    ...
});
 
Playground.init(mru);

This will spin up a local server on http://localhost:42069 by default, which will be utilized by our Playground app to interact with your MRU.

You can now visit playground.stf.xyz in your browser to interact with your micro-rollup. If prompted give it the URL of your local server started by playground.

Everything else...

You can refer to Micro-Rollup Utilities section for details on all the methods available to interact with the MicroRollup instance.

Next Steps

In this section, we learned how to run our micro-rollup and interact with it.

You can now start building and customizing your rollup using the Stackr SDK. Start by modifying the machine.ts, transitions.ts, and relevant files as per your requirements.

You can wrap the micro-rollup in a REST API or GraphQL API to interact with it from the frontend.

In the next section, we will learn how to register and deploy our application on Stackr's network and on-chain.