Skip to content

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:
      entity:
        claim-key:
          - claim-value
          - claim-value-two
      access:
        other-claim-key:
          - other-claim-value
    require:
      ... same structure as `set`
    extract:
      entity:
        - claim-key
      access:
        - 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.
  • entity – Entity-level claims (always required).
  • access – Access-level claims (optional).

Rule restrictions

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

Example

Given the following protocol:

package iou

protocol[issuer, payee] Iou(amount: Number) { }

A rule descriptor that statically assigns the issuer party:

iou.Iou:
  issuer:
    set:
      entity:
        org:
          - Lending AG
      access:
        email:
          - issuer@lending-ag.com

Deployment

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