Party Automation

Overview

Party automation defines engine-level rules to construct and validate parties at runtime, removing the need for external logic or process to generate the party needed for protocol creation. Rules are configured declaratively using YAML and applied automatically during protocol instantiation.

---

Applicable API Endpoints

Party automation rules are applied only when protocols are instantiated via the API. These rules are not observed during native NPL execution.

Here are list of applicable endpoints:

• POST /api/engine/protocols
• POST /npl/{package}/{protocol}

---

Descriptor File

Party automation rules are defined in a descriptor file, which specifies how each party in a protocol should be constructed and validated at runtime.

YAML Schema

protocol-package.protocol-name:
  party-name:
    set:
      claims:
        claim-key:
          - claim-value
          - claim-value-two
        other-claim-key:
          - other-claim-value
    require:
      ... same structure as `set`
    extract:
      claims:
        - claim-key
        - other-claim-key

Schema Breakdown

• protocol-package.protocol-name – The qualified name of the protocol (e.g., npl.Iou).
• party-name – The name of the party to automate (e.g., issuer, lender, payer).
• rule-type – One of set, extract, or require:
  • set: Assigns a fixed party.
  • extract: Builds party from JWT claims.
  • require: Validates required claims are present.
• claims – Authorization claims (always required).

Rule restrictions

A rule may only appear once for a protocol-party combination. SET and EXTRACT are mutually exclusive.

---

Rules

Rules automation supports three different rules: set, extract, and require. The following sections describe how these rules are interpreted. For each rule, we use the following protocol as an example.

package example

protocol[myParty] Example() { }

Set

The set rule explicitly the full party assignment. This rule cannot be combined with other rules. When a set rule is present, the party assignment cannot be specified when creating a new protocol instance.

The final party assignment consists of all the claim/values-pairs in the set rule.

For example, given the following ruleset:

example.Example:
  myParty:
    set:
      claims:
        roles:
          - r1
          - r2

When creating an instance of example.Example, it is forbidden to specify the party assignment for myParty. After construction, the party assignment will be:

"@parties": {
  "myParty": {
    "roles": ["r1", "r2"]
  }
}

Extract

The extract rule extracts claim values from the caller's token. This rule can be combined with a require rule. When an extract rule is present, the party assignment cannot be specified when creating a new protocol instance.

The final party assignment consists of all the claims in the extract rule, mapped to the value in the provided token. Each claim in the extract rule must be present in the provided token.

For example, given the following ruleset:

example.Example:
  myParty:
    extract:
      claims:
        - email

and a token containing the following claims:

{
  "email": "npl@example.com",
  "roles": ["r1", "r2"]
}

When create a new instance of example.Example, it is forbidden to specify the party assignment for myParty. After construction, the party assignment will be:

"@parties": {
  "myParty": {
    "email": ["npl@example.com"]
  }
}

Require

The require rule does not construct a party assignment, but validates that the final party assignment is correct. This rule can be combined with an extract rule.

When verifying the final party assignment (which is either explicitly provided, or constructed through an extract rule), each claim specified in the require rule must be present; and at least one of the provided values must be present in the final party assignment.

For example, given the following ruleset:

example.Example:
  myParty:
    require:
      claims:
        roles:
          - r1
          - r2

When creating an instance of example.Example with the following party assignment:

"@parties": {
  "myParty": {
    "roles": ["r2", "r3"],
    "email": ["npl@example.com"]
  }
}

the creation will succeed because the required role "r2" is present, and the final party assignment will match the provided party assignment:

"@parties": {
  "myParty": {
    "roles": ["r2", "r3"],
    "email": ["npl@example.com"]
  }
}

Deployment

Use the migration process to deploy the rules defined in the descriptor file.

Things to keep in mind regarding rules:

• Rules are validated during the migration process. Invalid rules will cause the migration to fail.

• If no rules file is provided, existing rules remain unchanged. The existing rules will then be validated to ensure the that they match any new sources.

• To delete all existing rules, provide an empty rules descriptor file.