Skip to content

Protocols

Introduction

Protocols are the core constructs of NPL. A protocol definition is a blueprint for an interaction, and are therefore first and foremost agreements between parties. Protocols define such interactions in terms of permissions and obligations, and may furthermore constrain these through prohibitions. Protocol definitions do pertain to specific parties, but rather define parties in terms of roles such as 'employer' and 'employee'.

Interactions with protocols only happen to protocol instances. An instance represents a single agreement between multiple specific parties as outlined by the protocol definition.

Refer to the language reference for more detail on protocols.

Protocol life cycle

A protocol digitally formalizes a contract, regulations, business processes or operational procedures. It is a template that needs to be instantiated and agreed upon by parties. This is when the protocol's lifecycle starts.

Protocol instantiation

A protocol starts its lifecycle when it is instantiated and agreed upon by parties. The parties agree on a set of protocol arguments that are passed to the protocol parameters. The protocol fields are initialized according to the protocol description (which can be seen as a protocol template). If defined, the protocol will be set to its initial state. The protocol instance now received an immutable protocol instance reference, which can be referred to during its whole lifecycle.

Execute permission or obligation on protocol

During its lifecycle, the instantiated protocol defines the permissions and/or obligations of the parties that agreed on this protocol. When a party is permitted or obliged by the protocol instance to take action, they can interact with the protocol instance and execute a permission or obligation on it by using the protocol instance reference. The party provides arguments for all the parameters of the permission/obligation and the engine tries to execute the actions defined in its body. Upon successful completion of all actions, the party might receive a return value. If the engine is not able to execute all actions, no event is written to the ledger, protocol states won't change and the party receives an error message.

Protocols referring to other protocols

A protocol Foo can refer to another protocol Bar if:

  • protocol Foo has a protocol parameter of type Bar (and receives the reference to a protocol instance Bar as an argument)
  • protocol Foo has a permission/obligation with a parameter of type Bar or directly or indirectly creates an instance of protocol Bar and keeps a reference to it in a protocol field.
  • protocol Foo has a protocol/permission/obligation parameter of a struct type which contains directly or indirectly a member field of type Bar and keeps a reference to it in a protocol field

Any permission or obligation of protocol Foo will then be able to refer to the instance of protocol Bar through the protocol parameter or protocol field of protocol Foo that has this reference.

Refer to an example of a protocol composition here.

Transferring rights and obligations to other parties

Parties may be 'swapped out' by combining &-type unanimous actions combined with party reassignment.

protocol[owner] Transferable() {
    permission[owner & *newOwner] transfer() {
        this.owner = newOwner;
    };
};

In this example the owner invokes the transfer permission together with the newOwner. This in turn makes the newOwner the owner, along with all corresponding rights and obligations.

Refer to an example for protocol ownership transfer here.

Request protocol state

A party that agreed on a protocol instance always has access to the state of the protocol instance through its protocol instance reference. The state of a protocol instance is defined by:

  • the value of the protocol state
  • the set of values of the protocol fields (including the protocol parameters)

Deletion

Protocols continue to live indefinitely, i.e. they may be in a final state, but they are still queryable and referenced through their protocol instance reference. The engine does not support protocol deletion.