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

Setting up your config

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.
.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 (isSandbox). This is explained in the next section.
  • The main properties you might wish to tune here are blockSize and blockTime of your micro-rollup. You can also set allowEmptyBlocks to true if you want your micro-rollup to always produce blocks every blockTime milliseconds (even when there are no actions).
    stackr.config.ts
    sequencer: {
  blockSize: 16,
  blockTime: 10,
  allowEmptyBlocks: true
}
  • The domain in the config is used to create EIP-712 Typed Signature over the inputs of actions. Feel free to tune this as per your requirements.
    stackr.config.ts
    domain: {
  name: "<APP_NAME>",
  version: "<APP_VERSION>",
  salt: "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
  • You can refer to Stackr Config section for the explanation of every available configuration property.

Project Structure

  • The src directory contains the code for your application.
  • The src/stackr directory contains the code for the State Machines and State Transition Functions.

We don't enforce any specific restrictions on the naming of the files, but keeping files related to the State Machines and STF in the src/stackr directory is recommended.

├── src
│   ├── stackr
│   │   ├── machine.ts
│   │   ├── schemas.ts
│   │   ├── transitions.ts
│   │   └── hooks.ts
│   ├── index.ts
│   ├── stackr.config.ts
│   └── deployment.json

  • machine.ts contains the StateMachine and State classes for your application.

    • 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({ ... });

  • schemas.ts contains the Action Schemas for your application.

  • transitions.ts contains the State Transition Functions (STF) for your application.

  • hooks.ts contains the Block Hooks for your application, if any.

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.