Skip to content
Getting Started

Building your first Micro-rollup

Bootstrapping a new project

To create a new project, run the following command:

npm
npx @stackr/cli@latest init
  • Choose a template from the list and follow the instructions.
Terminal
        _             _                        _ _
    ___| |_ __ _  ___| | ___ __            ___| (_)
   / __| __/ _` |/ __| |/ / '__|  _____   / __| | |
   \__ \ || (_| | (__|   <| |    |_____| | (__| | |
   |___/\__\__,_|\___|_|\_\_|             \___|_|_|
 
? Pick a template (Use arrow keys)
❯ Counter (Recommended)
  Chess
  Token Transfer
  Bridge
  Empty

For the purpose of this tutorial, we will use the Counter template.

  • After this you'll be asked to enter a "Project Name", enter a name and press enter.
  • You'll be asked to pick the Database after this, based on the Database you choose, we set up the project for you. For this tutorial, we will use SQLite. You can choose any database you want. For any other database, you'll have to manually change the database configuration in the stackr.config.ts file.
Terminal
? Database Driver (Use arrow keys)
❯ SQLite (Recommended)
  PostgreSQL
  MySQL
  MariaDB
  • You'll see some green checkmarks at this point and instructions to follow. Follow the instructions and you'll have a new project created.
Terminal
✔ ⚙️  Set up MRU
✔ 🧹  Set up git
✔ ⬇️  Installed packages
 
Get started by running the following commands:
 
  1. cd uno/
  2. cp .env.example .env & modify values
  3. Register your rollup using npx @stackr/cli@latest register

Now that we have a local copy of a micro-rollup project, let's understand its architecture.

Project Structure

Our pre-defined project templates use the default and recommended project structure which is as given:

├── src
│   ├── stackr
│   │   ├── machine.ts
│   │   ├── mru.ts
│   │   ├── state.ts
│   │   └── transitions.ts
│   └── index.ts
│── .env.example
└── stackr.config.ts

  • The root directory contains configuration files of your project.

    • .env.example is a template containing the necessary environment variables required by the micro-rollup.
    • stackr.config.ts exports the StackrConfig object defining the configuration of the your micro-rollup.

  • The src directory contains source code files of your project.

    • index.ts is the main entrypoint file containing code to run your project.

  • The src/stackr directory contains the source code files specific to defining a micro-rollup with Stackr SDK.

    • machine.ts contains the custom state machine class (extending StateMachine) instance for your app.

      • Please make sure to export the StateMachine object from this file in one of the following ways:
      machine.ts (declaration export)
      export const myMachine = new StateMachine({ ... });

    • state.ts exports the custom state class (extending State) for your micro-rollup.

    • transitions.ts exports the State Transition Functions (as Transitions) for your micro-rollup. This file may be omitted if no transitions are defined.

    • mru.ts exports the MicroRollup instance which is the controller for your micro-rollup.

Setting up your config

Since we are using the "Counter" template for this tutorial, the source code is already there so we only need to setup the micro-rollup configuration before we can run it.

Setup .env

  • Let's cd into the project directory and first copy the .env.example file to .env.
  • Update the following values in the .env file.
    • PRIVATE_KEY is the hex-encoded private key of the Ethereum address that will act as the rollup operator. This private key is used for registration and deployment of your micro-rollup, and to sign on incoming actions and proposed blocks.
    • For the other fields, you can get the latest values listed in the Providers and RPCs page.
.env
PRIVATE_KEY=<PRIVATE_KEY>
REGISTRY_CONTRACT=<REGISTRY_CONTRACT>
VULCAN_RPC=<VULCAN_RPC>
L1_RPC=<L1_RPC>
DATABASE_URI=<DATABASE_URI>

Setup stackr.config.ts

Now let's dive into the stackr.config.ts file.

  • By default, the micro-rollup is configured to run in Sandbox mode. This will be explained in the next section.
    stackr.config.ts
    const stackrConfig: StackrConfig = {
  isSandbox: true,
  /* ... */
};
  • Tune the sequencer as per your needs.
    • blockSize: The number of actions that the sequencer picks up from the pool to build a block.
    • blockTime: The time interval (in milliseconds) after which the sequencer picks up actions from the pool to build a block.
    • allowEmptyBlocks: A flag to allow creation of empty blocks every blockTime even when there are no actions. Defaults to false.
    stackr.config.ts
    const stackrConfig: StackrConfig = {
  /* ... */
  sequencer: {
    blockSize: 16,
    blockTime: 10,
    allowEmptyBlocks: false,
  },
  /* ... */
};
  • The domain object contains some fields for EIP-712 domain definition.
    • name: The name of the micro-rollup
    • version: The version of the micro-rollup
    • salt: A random salt value
    stackr.config.ts
    const stackrConfig: StackrConfig = {
  /* ... */
  domain: {
    name: "<APP_NAME>",
    version: "<APP_VERSION>",
    salt: "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  },
  /* ... */
};
  • You can refer to Stackr Config section for the explanation of every available configuration property.

Next Steps

In this section, we covered how to create and setup a new project using Stackr CLI and SDK. In the next section, we will see how to run our micro-rollup and interact with it.