Skip to content

Creating a new NPL project

Learn how to create a new NPL project from scratch and understand its structure.

Prerequisites

  • This track has no prerequisite track
  • NPL CLI installed (see NPL CLI for installation steps)

Initialize a new project

Create a new NPL project using the npl init command:

npl init --name my-project

This command will:

  • Create a new directory called my-project
  • Set up the basic project structure
  • Configure the project with default settings

Understanding the project structure

After running npl init, your project will contain:

.
├── .npl
│   └── deploy.yml
├── api
│   └── src
│       ├── main
│       │   ├── migration.yml
│       │   ├── npl-1.0.0
│       │   │   └── demo
│       │   │       └── helloWorld.npl
│       │   └── rules
│       │       └── rules_1.0.0.yml
│       └── test
│           └── npl
│               └── demo
│                   └── test-hello-world.npl
├── docker-compose.yml
└── README.md

Key files and folders in the structure are:

  • npl-1.0.0: NPL sources
  • migration.yml: Configuration file to manage application code migrations
  • rules_1.0.0.yml: Configuration file to enable the automatic creation of parties using the attributes in the user's authorisation token
  • deploy.yml: NPL deployment target configurations

Exploring the code

NPL

The api/src/main/npl-1.0.0/demo/helloWorld.npl file contains a basic Hello World example:

@api
protocol[greeter] HelloWorld() {

    initial state ungreeted;
    final state greeted;

    @api
    permission[greeter] sayHello() returns Text | ungreeted {
        become greeted;
        return "Hello " + getUsername(greeter) + "!";
    };
};

Migration

The api/src/main/migration.yml contains a single changeset describing the current version of NPL. It indicates where to load the npl sources from and specifies the npl version tag.

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
      - migrate:
        dir-list:
          - npl
        rules: rules/rules_1.0.0.yml

Party rules

The migration.yml file points to the rules/rules_1.0.0.yml file containing the party automation rules. Automation rules enable the specification of attributes for the different parties to a protocol. In this example, they extract the preferred_username from the protocol creation request's auth token and assign it to the greeter party's entity.

demo.HelloWorld:
  greeter:
    extract:
      entity:
        - preferred_username

Deployment configuration

The .npl/deploy.yml contains the configuration to deploy NPL sources to a local engine as alice, a user pre-populated when the engine runs in development mode.

schemaVersion: v1
defaultTarget: local
targets:
  local:
    type: engine
    engineManagementUrl: http://localhost:12400
    authUrl: http://localhost:11000
    username: alice
    password: password123

Running your project

Navigate to your project directory and run:

cd my-project
docker compose up --wait
npl deploy --sourceDir api/src/main

Next steps

  • Modify the files in api/src/main/npl-1.0.0 to add your own logic
  • Write tests in the api/src/test/npl-1.0.0 directory
  • Explore NPL built-in functions and modules

Common commands

  • npl check - Check for syntax and type errors
  • npl test - Run project tests
  • npl openapi - Generate an openapi spec