On-chain architecture

The on-chain architecture of the Application consists of two abstraction layers: Node and Modules.

The Node is the main object in charge of acting on the blockchain including:

  • forging blocks

  • synchronizing with the network

  • processing blocks from the network

  • …​ and broadcasting blocks and transactions to the network.

The Node is a private abstraction layer of the above mentioned activities, which is the reason it’s not visible to the SDK user.

Only the Module interface is exposed to the user, for defining any on-chain logic.

The life cycle of a block

If a node receives a new block, it always performs the following actions.

The bold steps are the steps exposed to the developer via the base module and base asset, see the Lisk Framework reference.

  1. Receive block

  2. Apply fork choice rule

  3. Validate block

    1. Validate transactions

      1. Validate transaction

      2. Validate transaction asset

  4. Verify block header

  5. Before block apply

  6. Apply block

    1. Apply transactions

      1. beforeTransactionApply

      2. Apply asset

      3. afterTransactionApply

  7. After block apply

  8. Save block and updated states

What is a module?

Modules hold all logic that is changing the state of the blockchain; or in other words, all logic that makes changes on the chain.

on chain architecture

All of the logic implemented using a custom module / asset must be “deterministic” and executable within the block time.

Modules define an account schema to store the module related data in the account. The definition of this schema is totally flexible and it is possible to define very complex data structures as well, if needed.

The second part of modules enables to control the behaviour of the module. The BaseModule, which every module extends from, offers various lifecycle hooks that allow each module to execute certain logic before or after transactions or blocks. Also, it defines the logic for the transaction assets of the module.

As third part, modules expose an interface. This interface allows other components of the applications to interact with the module. Reducers are actions that can only be invoked by other modules of the application. Actions and Events are exposed to the plugins and to external services. More information about the exposed interface can be found in the section about the Communication Architecture.

When to create a custom module

Modules enable to…​

  • define how data is stored on the blockchain

  • define logic which is executed per block

  • define logic which is executed per transaction

In addition, all of the logic implemented using a module/asset must be deterministic and executable within the block time.

Transaction assets

Transaction assets contain all logic related to transactions that belong to the module. Formerly, this logic was implemented in a custom transaction. The implementation of a custom transaction asset is similar to a custom transaction, but much more simple.

When to create a custom asset

Create a custom asset for every transaction type that you want to use in the blockchain application.

Assets enable to…​

  • define a schema for data sent through transaction asset

  • validate the data

  • define logic which is executed per asset

How to add a module to the application

Modules are registered in the file src/app/modules.ts.

Registering a new module requires the generation of a new genesis block and therefore always results in a hardfork of the blockchain of the application.

Check out the Generating a genesis block guide for more information on how to generate a new genesis block for your application.

Example: How to register a module with the application in modules.ts
import { Application } from 'lisk-sdk';
import { SomeModule } from "some-module"; (1)

export const registerModules = (app: Application): void => {
    app.registerModule(SomeModule); (2)
1 Import the module from an NPM package or from a local path.
2 Add this line to register the module with the application.

SDK default modules

Name Description

DPoS module

The DPoS module is responsible for handling all DPoS related logics. Specifically:

  • Snapshotting vote weights

  • Calculating productivity

  • Handling registerDelegate, voteDelegate, unlockToken and reportDelegateMisbehavior transaction assets

  • Setting the next delegates set

Keys module

The Keys module handles all logic related to the signatures.

It should verify the signatures based on the multi-signature rules including non-multi-signature accounts. It also handles the registration of multi-signature accounts.

Sequence module

The Sequence module handles all logic related to the nonce.

It should verify the nonce for all transactions and increment if valid.

Token module

The Token module handles all logic related to balance. Specifically:

  • Validating and subtracting fees for all transactions

  • Checking the minimum remaining balance requirement

  • Giving block rewards to the block generator

  • Transferring account balances