TP1 - DWeb Node Protocols Interface

Created: August 9, 2022
Status: Draft

Summary

Across a wide array of decentralized app, service, and protocol scenarios there exists a need for entities to expose various interactions to the public and shape interactions that adhere to expected schemas, data relationships, and protocol flows (e.g. tbDex). The following proposal describes a mechanism for defining protocols and associated logic DWeb Nodes use to address these needs in an extensible way that covers the vast majority of app and service use cases.

Motivation

When thinking about apps and services as protocols, most apps and services have some aspects of interactions between participants that is open to the public and must follow certain business rules for how data is related and handled. Being able to expose open initiation of app or service flows is something you see with Twitter (anyone can reply to your tweets), credential issuance (anyone can apply for a credential), and tbDEX (anyone can submit an Ask), to name a few. Additionally, in virtually all apps and services there exist relationships between data/objects that define what objects are attached to others, and who can perform certain actions within a flow. Due to the fact both credential issuance and tbDEX require both of the technical capabilities outlined above, we need to put such a mechanism in place to enable them.

Goals

• Enable DWeb Nodes to intake messages from the wider internet that fall within a set of protocol-specific constraints.
• Enable developers to define a set of messages under a given protocol definition, their relationships with each other, and the conditions for which external entities are able to interact/affect them.

Requirements

• MUST enable an inbox-style mechanism for external parties to send data to a DWN.
• MUST enable segmentation of messages/data into protocol-specific buckets.
• MUST enable the ability to securely separate invocations of protocol invocations so that different activity streams between participants can be made private from one another.
• MUST enable a protocol to define who can perform certain actions within the bounds of the declared protocol’s data and flows.

Proposal

The core of this proposal is to create a new interface that enables the static declaration of a protocol’s structure, the allowed interactions, and enforced constraints. This would manifest as the following set of interface methods:

ProtocolsConfigure

The ProtocolsConfigure interface method installs a configuration of a protocol definition in a DWeb Node. The definition installed is used to gate ingest of different records, sets forth the relationships between said records, and determines what actions an outside entity can take in relation to the records and data model it defines.

{
	method: "ProtocolsConfigure", // required
  protocol: "identity.foundation/protocols/credential-issuance", // required
  version: "1.0.0", // required
	definition: { PROTOCOL_DEFINITION_OBJ }, // optional
	lastConfiguration: CID_OF_PREVIOUS_CONFIG, // required if previous exists
	retainedRecords: CHAMP_OF_INCLUDED_ITEMS // optional
}

The evaluation logic for configurations of protocols must be constructed such that conflicting versions of the same protocol cannot be active at the same time. To do this configurations of the same version must form a linked list from one configuration to another. Any root or branch-level conflicts between configuration entries will be resolved via the simple lexicographic comparison of their CIDs, proceeding with the greatest value and discarding others.

Here is the lifecycle of a protocol envisioned from initial configuration addition to closure of a version:

1. A new configuration is added for Protocol X, Version Y (assumes no lastConfiguration value is present).
2. Check existing protocol configurations for other ‘root’ entries for the tuple of Protocol X, Version Y.
3. If another configuration exists and is at the ‘root’ level, proceed with the configuration that has the greatest lexicographical value and discard the other.
4. Inbound records that are invocations of a protocol must invoke the protocol configuration CID they are invoking.
5. Evaluation of a record invoking a configuration must adhere to the Protocol Evaluation Process outlined in the Protocol Definition section below.
6. At such time a configuration for the tuple Protocol X, Version Y is desired, the owner will craft a ProtocolConfigure message that sets the same tuple, includes the new definition, references the last configuration being superseded, and includes any record references to be retained in relation to that configuration. (consider using a CHAMP for the retainedRecords value)
7. When the new configuration for the tuple is evaluated, ensure that it links to a configuration of the same Protocol/Version tuple and there are no existing configurations at this ‘level’ (the same process as in step 2).
8. Once accepted as the new configuration of the protocol, discard any records from the last configuration not indicated by the retainedRecords value in the new configuration entry.

ProtocolsQuery

The ProtocolsQuery interface method allows an outside entity to query for any active protocols the owner has an active configuration for.

{
	method: "ProtocolsQuery",
	protocol: "identity.foundation/protocols/credential-issuance" ???
	versions: [???], // optional, absence = return all active versions
	active: true / false
}

Protocol Definitions

Protocol definitions are objects that set forth the rules for handling of records that invoke a given protocol version. They determine acceptance of records by external entities, how records must relate to one another, and what external entities can do in relation to those records.

Example of a credential issuance flow modeled as a protocol definition:

{
	method: "ProtocolsConfigure",
	protocolDefinition: {
	  "objects": {
	    "credentialApplication": {
	      "schema": "https://identity.foundation/schemas/credential-application"
	    },
	    "credentialResponse": {
	      "schema": "https://identity.foundation/schemas/credential-response"
	    }
	  },
	  "structure": {
	    "credentialApplication": {
	      "encryptionRequired": true,
	      "allow": { // Issuers would have this allow present
	        "anyone": {
	          "to": [
	            {
								"write": {
			            "published": true
								}
							}
	          ]
	        }
	      },
	      "records": {
	        "credentialResponse": {
	          "allow": {
	            "recipient": {
	              "of": "credentialApplication",
	              "to": [
	                { action: "create",  }
	              ]
	            }
	          }
	        }
	      }
	    }
	  }
	}
}

Recursive example:

{
  "protocol": "https://protocols.org/dwitter/v1.1.0",
  "objects": {
    "ask": {
      "schema": "https://tbdex.orb/protocol/ask"
    },
    "conditionalOffer": {
      "schema": "https://tbdex.orb/protocol/conditionalOffer"
    },
    "close": {
      "schema": "https://tbdex.orb/protocol/close"
    },
  },
  "structure": {
    "ask": {
      "allow": {
        "anyone": {
          "to": [
            { action: "create" }
          ]
        },
	  "records": {
        "conditionalOffer": {
	      "allow": {
	        "recipient": {
			  "of": "ask",
	          "to": [
	             { action: "create", penalty: "block" }
	          ]
	        }
	      }
	    },
		"close": {
	      "allow": {
	        "participants": {
	          "to": [
	            { action: "create" }
	          ]
	        }
	      }
	    }
      }
    }
  }
  }
}

Graph representations of contextual protocol invocations:

{
  "credentialApplication": {
    "__value__": ASK_DATA_OR_REF,
    "conditionalResponse": {
      "__value__": OFFER_DATA_OR_REF
    }
  }
}

The process of evaluation is envisioned as follows:

1. Validate the authorization invocation of the protocol/version tuple.
2. Use the protocol/version tuple in the record to look up the active configuration for the specified tuple. If none exists, reject the record.
3. Build up a graph representation of the record in relation to its position in the protocol configuration’s structure, and ensure that the record’s schema, context, encryption, and other aspects are in line with the configuration’s requirements, and that the action it is attempting to perform is permitted in the allow directives that pertain the record.

Structure of Protocol-Encoded Records

{
	descriptor: {
		method: "CollectionsWrite",
		protocol: "identity.foundation/protocols/credential-issuance",
		protocolVersion: "1.0.0",
		contextId: ???,
		schema: "https://identity.foundation/schemas/credential-application",
		published: true, // must be set if anyone: { to: ['read'] }
	},
	authorization: { INVOKE_CID_OF_CONFIGURATION }
}

Open Items

• Closing out contexts