0001 EVS-01d: NPL Broker

[wojake]

Title:        NPL Broker
Description:  A NPL brokerage standard for HotPocket instances to manage NPL messages systematically.
Revision:     1 (06-07-2023)
Author:
- Wo Jake, Independent Developer (@wojake)

NPL Brokerage System

HotPocket supports sub-consensus communication, in which, arbitrary data is distributed and collected between nodes to collectively come to a consensus on a particular set of (unique) data, allowing a HP cluster to maintain a canonical state & return a valid, consistent response across the cluster.

This proposal, EVS-01d, structures an internal brokerage system on a HP instance, that manages sub-consensus "NPL" communication systematically.

More on NPL messaging.

1. Problem Statement

Out of the box, the Node Party Line channel "NPL" enables instances to read incoming sub-consensus messages and relay sub-consensus messages to their peers in raw format. HotPocket does not facilitate a built-in system to manage NPL messages in a systematic manner per se.

The simplicity of the NPL channel may introduce issues for most HP dApps, such as:

1. sub-consensus "NPL" messages are not uniquely tagged.
2. sub-consensus "NPL" rounds may overlap one another.
3. sub-consensus "NPL" rounds are not timed.

On the other hand, the flexibility comes at a cost, as different third-party components (libraries) have to come to an agreement on which NPL framework/standard they will be adopting. This inherent problem is solveable as we introduce a standard that may be adequate for future production use.

Discussions, tests, and reviews are more than welcome from all developers, as this standard will be crucial as a foundational building block in the HotPocket ecosystem.

2. Implementation

An EVS-01d NPL broker manages NPL rounds in a timely manner, and each NPL round being performed consumes a unique "spot" on the NPL broker's round registry according to its round name (i.e., DKM-signature-collection-rXXRP). For example, the "DKM-signature-collection-rXXRP" round will temporarily consume the "DKM-signature-collection-rXXRP" position on the NPL broker's round registry.

tl;dr:

• NPL round names must be unique.
• NPL rounds must be timed from start to finish.
• Each instance could only send one NPL message per NPL round.

Function: Initialize NPL Broker

This function creates an NPL Broker instance on a HP instance and returns said instance to the caller, the caller's runtime could interact with NPL Broker.

The function must have the following fields:

Field Name	Type	Internal Type	Description
ctx	object	object	The HP instance's contract context.

EVS-01d follows a singelton pattern; after the NPL Broker instance has been initialized, any additional calls to init() will return the NPL Broker instance rather than initializing it again. There could only be one instance of an NPL Broker per ledger.

JavaScript implementation sample:

function init(ctx) {
    // Singelton pattern since the intention is to only use NPLBroker instance for direct NPL access.
    // If the NPL broker instance has been initialized, return the broker's instance to the call,
    // this ensures that the broker is accessible to all components of the HP dApp
    if (!instance) {
        instance = new NPLBroker(ctx);
    }
    return instance;
}

Function: Perform NPL Round

This function performs an NPL round, which distributes arbitary data within the instance's UNL via ctx.unl.send() and collects NPL messages from its peers.

The function must have the following fields:

Field Name	Type	Internal Type	Description
roundName	string	string	The NPL round's name. This must be unique.
content	string, number, object, array, boolean, date	string	The content that will be distributed to this instance's peers.
desiredCount	number	number	The desired count of NPL messages to collect from peers.
timeout	number	number	The time given to this NPL round to conclude.

Perform NPL round sample:

{
roundName: "DKM-signature-collection-B36542F68656FB2E73CA123ACE747EAFA5AC2114F4FA2543BA78615CD8B9B9DA",
content: "304502210098A1269B7DF040558C9BC3AFD93AB67CA78BDE83D82FFBFFB89B1005D392F5490220134346FB126500E5134EA17B5258D40789A31F5E82EE5DAA6309CABB6B3B1FF4",
desiredCount: 8,
timeout: 400
}

The function returns the following fields:

Field Name	Type	Description
roundName	string	The NPL round's name.
record	array	An array of records containing nodes' public keys, NPL messages, and the time taken for each respective NPL message to be processed.
desiredCount	number	The desired count of NPL messages to collect from peers.
desiredCountReached	boolean	The condition of this NPL round. If the number of NPL messages collected meets the threshold (desiredCount), return true.
timeout	number	The time given to this NPL round to conclude. The NPL round must not continue after the given time.
timeTaken	number	The time taken for this NPL round to conclude.
meanTime	number	The mean of the time it took to receive all the collected NPL messages.

NPL round result sample:

{
  roundName: 'TEST ROUND',
  record: [
    {
      roundName: 'TEST ROUND',
      node: 'ed44351a3adff423f6e2d14f3738e789cb40ab14cc0c6d09fb20578cebcfeaba0e',
      content: 'This is a unique NPL message?! Random value: 48',
      timeTaken: 103.66199803352356
    },
    {
      roundName: 'TEST ROUND',
      node: 'ed941cb59012365d23996a737c82df8f66e0ad7f510881fb0c0d210dd131bef83c',
      content: 'This is a unique NPL message?! Random value: 39',
      timeTaken: 104.63827395439148
    },
    {
      roundName: 'TEST ROUND',
      node: 'ed735fff5b89aed352634ab1e4ba647403105fe18655ae5fef0734473a75be424a',
      content: 'This is a unique NPL message?! Random value: 43',
      timeTaken: 104.97707295417786
    },
    {
      roundName: 'TEST ROUND',
      node: 'ed8dff8ef3dee4a9bd645223b558638fe392292d32d45bd88a58952c8a3d21b20f',
      content: 'This is a unique NPL message?! Random value: 15',
      timeTaken: 105.65762591362
    },
    {
      roundName: 'TEST ROUND',
      node: 'ed134fb3644a539e4d81a9ea0d963c954aaca596d148011ae537bb9c7c52356258',
      content: 'This is a unique NPL message?! Random value: 28',
      timeTaken: 106.16832304000854
    },
    {
      roundName: 'TEST ROUND',
      node: 'edcf3a1ccd09587f27d9a820182d4ee09eec4ea7bb084a8141075f6c54dfc52d6e',
      content: 'This is a unique NPL message?! Random value: 17',
      timeTaken: 106.58795595169067
    }
  ],
  desiredCount: 6,
  desiredCountReached: true,
  timeout: 400,
  timeTaken: 106.95626187324524,
  meanTime: 105.28187497456868
}

Function: Subscribe to Round

This function subscribes to an NPL round name.

This function must have the following fields:

Field Name	Type	Description
roundName	string	The NPL round's name.
listener	function	The function that will be called per each incoming NPL message passing through the specified NPL round name.

This function is separate from an NPL round being performed, it does not influence an NPL round in any way. Each incoming NPL message will pass through the subscribed function 'listener' and the listener function could react according to its defined code block.

The amount of NPL messages passing through the listener function is capped according to the desired amount of NPL messages that the NPL round will be collecting.

Function: Unsubscribe to Round

This function removes a particular subscriber of an NPL round name, only one unique subscriber is removed per each call.

Field Name	Type	Description
roundName	string	The NPL round's name.
listener	function	The function that will be removed in the specified NPL round.

3. Adoption & Interoperability

As an NPL Broker calls the ctx.unl.onMessage() during initialization, each component (library) on a HP dApp must adopt and utilize EVS-01d.

If EVS-01d is not adopted throughout the ecosystem, it would be difficult or impossible to adopt an implementation of this standard in any mainstream component (library).

Security Considerations

Utilizing EVS-01d does not entirely combat overlapping NPL rounds, however, it does introduce a guard to avoid repeated NPL messages from the same HP peer, which would combat overlapping NPL rounds as one instance would only be able to send 1 NPL message per round.

It is advisable to not re-use an NPL round name twice.

Reference Implementation

We've developed an implementation of EVS-01d on NodeJS.

https://github.com/Evernerd/npl-broker-js/