Consent/contracts negotiating agent BB – Design Document – Prometheus-X Components & Services

Consent/contracts negotiating agent BB – Design Document

Consent/contracts negotiating agent BB – Design Document

The Consent/Contracts Negotiating Agent streamlines the process for individuals to set consent preferences regarding data usage, automates responses to consent requests from managers, and matches individuals with relevant services based on their consent profiles. Additionally, it assists organizations in negotiating and managing contractual agreements for data sharing within the dataspace ecosystem.

Its components encompass consent preference settings, service matching capabilities, communication with consent managers, contract profile management, and the provision for organizations to define default rules and conditions for contractual agreements.

Technical usage scenarios & Features

The Consent/Contracts Negotiating Agent empowers individuals and data providers to manage consent preferences, discover suitable services, and negotiate data sharing agreements within dataspace ecosystems. It facilitates automatic matching and recommendation processes based on an individual's consent profile and organizations' data sharing agreements.

Features/main functionalities

Empowers individuals to set consent preferences for data usage.
Automatic matching and recommendation process based on consent profiles and data sharing agreements.
Communication with consent managers to handle consent requests and responses.
Integration with dataspace ecosystems to ensure compatibility with ecosystem conditions.
Provision for organizations to define default rules and conditions for contractual agreements.

Technical usage scenarios

Enable individuals to manage their consent preferences efficiently and effectively.
Facilitate automatic matching of individuals' consent profiles with the conditions of dataspace ecosystems.
Recommend the best services to individuals based on their needs and the permissibility of the data.
Streamline the process of handling consent requests and responses between individuals and consent managers.
Provide organizations with the capability to establish default rules and conditions for contractual agreements, ensuring compliance and consistency.

Requirements

Requirement ID	Short Description	BB Input Format	BB Output Format	Requirement Type
BB-REQ_ID__1	Must enable individuals to set and manage consent preferences for data usage	REST API call	REST API response	Functional (FUN)
BB-REQ_ID__2	Must facilitate automatic matching and recommendation processes based on consent profiles and organizations' data sharing agreements	REST API call	REST API response	Functional (FUN)
BB-REQ_ID__3	Must communicate effectively with consent managers to handle consent requests and responses	REST API call	REST API response	Dependency, Functional (DEP, FUN)
BB-REQ_ID__4	Must integrate seamlessly with dataspace ecosystems to ensure compatibility with ecosystem conditions	REST API call	REST API response	Dependency (DEP)
BB-REQ_ID__5	Must provide configuration options for organizations to define default rules and conditions for contractual agreements	REST API call	REST API response	Functional (FUN)
BB-REQ_ID__6	Should be able to process both bilateral and data space use case data sharing agreements	REST API call	REST API response	Dependency, Functional (DEP, FUN)

Integrations

Direct Integrations with Other BBs

Core Building Blocks

Interaction with other building blocks are essential to ensuring the functionalities of Consent / Contract Negotiating Agent as it needs to be able to read from consents and contracts, as well as read information from the catalogue.

Integrations via Connector

This building block is not aimed to have a connector integration as it will be intimitely linked to the Consent and Contract building blocks which exist outside of the connector.

It will however be a source of data exchange trigger which will enable the Consent service to notify the connectors of the data exchange following the protocol defined in the consent building block.

Relevant Standards

Data Format Standards

JSON-LD for schema definitions
ISO 3166-1 alpha-2 for location country codes
ISO 8601 for Date and time format
ODRL for contract policies

Input / Output Data

This Building Block reads from existing contracts generated by the Contract building block and existing consent from the Consent building block.

Matching

The consent negotiating agent interacts with the catalog to identify similar types of data and services based on individuals' consent preferences. By analyzing consent profiles, the agent discerns the authorization levels, conditions, and preferences set by individuals regarding data usage.

Leveraging this information, it proposes potential data exchanges to individuals, recommending suitable data sources or services that align with their consent preferences. This process ensures that individuals have access to relevant and permissible data within the dataspace.

Contract Matching

The contract negotiating agent utilizes the catalog to identify comparable data categories and services based on organizations' contract profiles. By examining the ODRL policies and values specified in the contract profiles, the agent identifies relevant organizations and datasets that align with the contractual agreements and obligations defined by the organizations.

It then proposes potential partners or datasets to organizations, facilitating streamlined negotiations and partnerships within the dataspace.

This approach enables organizations to efficiently discover and engage with compatible partners and datasets, optimizing data sharing and utilization while ensuring adherence to contractual agreements and regulatory requirements.

Streamlining Negotiation Process


sequenceDiagram
  participant org as Organization
  participant ca as Contract Agent
  participant cat as Catalog Integration

  org->>ca: Initiate negotiation with new organization
  ca->>cat: Access contract profiles from catalog
  cat-->>ca: Contract profiles retrieved
  ca->>org: Pre-set ODRL policies and values based on contract profiles

Recommendations of Data Exchanges

sequenceDiagram
  participant org as Organization
  participant ca as Contract Agent
  participant cat as Catalog Integration

  org->>ca: Request recommendations for data exchanges/services
  ca->>cat: Access contract profiles from catalog
  cat-->>ca: Contract profiles retrieved
  ca->>ca: Analyze ODRL policies and values in contract profiles
  ca->>cat: Request data exchanges/services recommendations based on contract profiles
  cat-->>ca: Data exchanges/services recommendations
  ca-->>org: Provide recommendations based on contract profiles

Architecture

Negotiating Agents: The core components responsible for managing consent and contract negotiations. These agents communicate with individuals, organizations, and the catalog to gather and analyze consent preferences and contract profiles.
Catalog Integration: Integration with the catalog system to access metadata about available data sources, services, and organizations within the dataspace. This integration enables the negotiating agents to identify relevant data and services based on consent preferences and contract profiles.
Consent Management Module: A module responsible for managing consent preferences of individuals. It allows individuals to set and update their consent preferences, including authorization levels and conditions for data uage.
Contract Management Module: A module dedicated to managing contract profiles of organizations. It enables organizations to define ODRL policies and values for data categories and services, facilitating streamlined negotiations with potential partners.
Communication Interface: An interface for communication between the negotiating agents, individuals, organizations and the catalog. This interface ensures seamless exchange of consent preferences, contract profiles, and negotiation proposals.
Data Exchange Proposals: Components responsible for generating data exchange proposals for individuals based on their consent preferences and for proposing relevant organizations or datasets to organizations based on their contract profiles.
Authorization Level Evaluation: Components for evaluating authorization levels and conditions specified in consent preferences and contract profiles. These components determine the permissibility of data exchanges and partnerships.
Logging: Mechanisms for logging operations and monitoring the performance of the agents and related components.
Error Handling & Recovery: Strategies and mechanisms for handling errors and recovering from failures gracefully.

classDiagram
  class ConsentContractNegotiatingAgent {
    - ConsentManagementModule consentModule
    - ContractManagementModule contractModule
    - CatalogIntegration catalogIntegration
    - CommunicationInterface communicationInterface
    - DataExchangeProposals dataExchangeProposals
    - AuthorizationLevelEvaluation authorizationEvaluation
    - LoggingMonitoring loggingMonitoring
    - ErrorHandlingRecovery errorHandlingRecovery
  }
  class ConsentManagementModule {
    + setConsentPreferences()
    + updateConsentPreferences()
  }
  class ContractManagementModule {
    + setContractProfile()
    + updateContractProfile()
  }
  class CatalogIntegration {
    + accessMetadata()
  }
  class CommunicationInterface {
    + exchangeData()
  }
  class DataExchangeProposals {
    + generateProposals()
  }
  class AuthorizationLevelEvaluation {
    + evaluateAuthorization()
  }
  class LoggingMonitoring {
    + logOperations()
    + monitorPerformance()
  }
  class ErrorHandlingRecovery {
    + handleErrors()
    + recoverFromFailures()
  }

  ConsentContractNegotiatingAgent --> ConsentManagementModule
  ConsentContractNegotiatingAgent --> ContractManagementModule
  ConsentContractNegotiatingAgent --> CatalogIntegration
  ConsentContractNegotiatingAgent --> CommunicationInterface
  ConsentContractNegotiatingAgent --> DataExchangeProposals
  ConsentContractNegotiatingAgent --> AuthorizationLevelEvaluation
  ConsentContractNegotiatingAgent --> LoggingMonitoring
  ConsentContractNegotiatingAgent --> ErrorHandlingRecovery

Dynamic Behaviour

This statechart shows the internal state changes of the component.

---
title: Setting of authorization level in consent preferences
---

stateDiagram-v2
  [*] --> ManualConsent: Default State
  ManualConsent --> AutomaticConsent: Authorization Level "always"
  ManualConsent --> ConditionalConsent: Authorization Level "conditional"
  ConditionalConsent --> ManualConsent: Conditions Not Met
  ConditionalConsent --> AutomaticConsent: Conditions Met
  AutomaticConsent --> ManualConsent: Authorization Level Changed to "conditional"
  ConditionalConsent --> AutomaticConsent: Authorization Level Changed to "always"

Communication with other components


sequenceDiagram
  participant i as Individual
  participant pdi as Personal Data Intermediary
  participant ccna as Consent Negotiating Agent

  i->>pdi: Request data sharing from <br>Data Provider to Data Consumer
  pdi->>ccna: Send Consent
  ccna->>ccna: Verify authorization level on <br>the user consent preferences
  alt Authorization Level "always"
    ccna-->>pdi: Consent granted automatically
  else Authorization Level "never"
    ccna-->>i: Request manual consent grant
  else Authorization Level "conditional"
    ccna->>ccna: Check conditions
    alt Conditions Met
      ccna-->>pdi: Consent granted automatically
    else Conditions Not Met
      ccna-->>i: Request manual consent grant
    end
  end

Technical Specifications

graph TD
    subgraph ConsentManager["Consent - Manager"]
        subgraph ConsentAgent["Consent Agent"]
            Algorithms["Algorithms<br/>(Consent preferences,<br/>consent matching,<br/>negotiation agent,<br/>Data exchanges recommendations)"]
            API
            Algorithms <--> API
        end
    end

    MongoDB[(consent-manager<br/>mongodb)]
    AtlasSearch[(Atlas Search)]

    MongoDB <--> ConsentManager
    AtlasSearch --> |consent<br/>& Data exchanges| ConsentManager

Entities in the consent preferences are defined by the following UML diagram

classDiagram
  class Data {
    id: string/uri
    authorizationLevel: string
    conditions: Condition[]
  }
  class Service {
    id: string/uri
    authorizationLevel: string
    conditions: Condition[]
  }
  class Participant {
    id: string/uri
    asDataProvider: Data
    asServiceProvider: Service
  }
  class Condition {
    time: TimeCondition
    location: LocationCondition
  }
  class TimeCondition {
    dayOfWeek: string[]
    startTime: string
    endTime: string
  }
  class LocationCondition {
    countryCode: string
  }

  Participant -- Data
  Participant -- Service
  Condition -- TimeCondition
  Condition -- LocationCondition
  Service -- Condition
  Data -- Condition

User input will allow setting the consent profile preferences. An example of a simple consent profile would follow the following structure:

JSON structure for consent preferences

API Endpoints

The agent provides API endpoints through the consent manager to give access to the algorithm’s output and to give access to the preferences options.

Get Recommendations

GET /recommendations/:profileId/consent

Output example

{
	"consentRecommendations": ["6675866105d813cd97de8171"]
}

Get Recommendations

GET /recommendations/:profileId/dataexchanges

Output example

{
	"dataExchangesRecommendations": ["6675866105d813cd97de8171"]
}

Consent preferences

GET /preferences/:id
POST /preferences
PUT /preferences/:id
DELETE /preferences/:id

Output example

{
	"id": "667bc534e22d10c930808556",
	"asDataProvider": {
		"id": "667bc534e22d10c930808556",
		"authorizationLevel": "always",
		"conditions": [
			{
				"time": {
					"dayOfWeek": ["0"],
					"startTime": "2024-03-27T14:08:19.986Z",
					"endTime": "2025-03-27T14:08:19.986Z"
				},
				"location": {
					"countryCode": "US"
				}
			}
		]
	},
	"asServiceProvider": {
		"id": "667bc534e22d10c930808556",
		"authorizationLevel": "always",
		"conditions": [
			{
				"time": {
					"dayOfWeek": ["0"],
					"startTime": "2024-03-27T14:08:19.986Z",
					"endTime": "2025-03-27T14:08:19.986Z"
				},
				"location": {
					"countryCode": "US"
				}
			}
		]
	},
	"configurations": {
		"allowRecommendations": true,
		"allowPolicies": true
	}
}

Contract Agent

graph TD
    subgraph ContractManager["Contract - Manager"]
        subgraph ContractAgent["Contract Agent"]
            Algorithms["Algorithms<br/>(Profile management,<br/>recommendation logic,<br/>policies management)"]
            API
            Algorithms <--> API
        end
    end

    MongoDB[(contract-manager<br/>mongodb)]
    AtlasSearch[(Atlas Search)]

    MongoDB <--> ContractManager
    AtlasSearch --> |recommendations<br/>& policies| ContractManager

Contract Profiles

For organizations within the dataspace, they are subject to negotiate and contractualise for the usage of their data or services under a certain set of ODRL policies. The contract profile and agent would enable a streamlined experience in setting up ODRL policies and their values when negotiating with new organisations if similar data or services has been configured within the contract profile.

classDiagram
  class Policies {
    +policy: string
    +frequency: int
  }

  class Recommendations {
    +policies: [Policies]
    +ecosystemContracts: [string]
  }

  class profiles {
    +_id: ObjectId
    +url: string
    +recommendations: [Recommendations]
    +configurations: configurations
  }

  class Configurations {
    +allowRecommendation: boolean
    +allowPolicies: boolean
  }

  profiles "1" -- "1" Configurations
  profiles "1" -- "*" Recommendations
  Recommendations "1" -- "*" Policies

Organizations can create a contract profile where they define various data categories and services they offer or utilize. For each data category and service, organizations specify the corresponding ODRL policies, including permissions, prohibitions, obligations, and constraints. When negotiating with new organizations or entities, the contract negotiating agent leverages these pre-configured contract profiles. It identifies similarities between the data categories and services involved, utilizing existing policies and values whenever possible to expedite the negotiation process. This approach not only accelerates negotiation but also ensures consistency and compliance across contractual agreements within the dataspace ecosystem.

API Endpoints

The agent provides API endpoints through the contract manager to give access to the algorithm’s output and to give access to the configuration options.

Get Recommendations

GET /recommendations/:profileId/contracts

Output example

{
	"contractsRecommendations": ["6675866105d813cd97de8171"]
}

Get Policies

GET /policies/:profileId

Output example

{
	"policies": ["6675867c2ef5d0e40b021e6b"]
}

Profile Configurations

GET /profile/:id/configurations
POST /profile/configurations
PUT /profile/:id/configurations
DELETE /profile/:id/configurations

Output example

{
	"configurations": {
		"allowRecommendations": true,
		"allowPolicies": true
	}
}

Library Setup - Example

Setting up the agent would look something like the following:

Although this is still at a specification level and can change, having an example setup helps to visualise the implication for setup in the other building blocks.

pnpm install contract-agent

Initialization Example

import { initializeConsentAgent } from "contract-consent-agent";
const express = require("express");
const mongoose = require("mongoose");

const app = express();
await mongoose.connect(url, { retryWrites: true });
const consentAgent = initializeConsentAgent(mongoose);

// ...other app code...

app.listen(3000, () => {
	console.log("Server is running on port 3000");
});

API Integration Example

The library is expected to return a router used by the consent manager. Here is what it could look like

import { initializeConsentAgent } from "contract-consent-agent";
const express = require("express");
const mongoose = require("mongoose");

const app = express();
await mongoose.connect(url, { retryWrites: true });
const consentAgent = initializeConsentAgent(mongoose);

// ...other app code...

app.use("/", authMiddleware, consentAgent.router);

app.listen(3000, () => {
	console.log("Server is running on port 3000");
});

Objective

Provide an interface to search documents in the selected search engine (Atlas Search) in order to highlight suggestions or specific elements that might be found within the documents (ex: suggesting an ecosystem contract for a user, retrieving policies associated with a user).

Main Features

API for document suggestion queries, precise document searches, or searches for sub-elements such as policies.
Accept search parameters (filters, scoring, etc.).
Execute queries on the search engine and return the results.
Set up search profiles if necessary:
- Define search profiles for the relevant documents based on the required return format.
Set up the search API:
- Implement a search interface (API) allowing the search for documents and sub-elements based on specific criteria.

Atlas Search Example

[
	{
		"$search": {
			"index": "contracts",
			"moreLikeThis": {
				"like": [
					{
						"serviceOfferings.policies.description": "MUST use data for a specified time period"
					}
				]
			}
		}
	},
	{
		"$limit": 5
	},
	{
		"$project": {
			"serviceOfferings": 1,
			"score": { "$meta": "searchScore" }
		}
	}
]

Algorithms

The algorithms need to respond to the previous described requirements. To do so we will use Atlas search and its functionality to empower the recommendations and the matching.

Profile Algorithms Execution

This algorithm will create and manage the Contract profiles

See input/output example

Input

{
	"_id": "6661c8e34371f3eabe3ddfde",
	"createdAt": "2024-06-06T14:34:11.128Z",
	"ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536",
	"members": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"role": "orchestrator",
			"signature": "hasSigned",
			"date": "2024-06-06T14:34:16.722Z"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"role": "participant",
			"signature": "hasSigned",
			"date": "2024-06-06T14:35:51.524Z"
		}
	],
	"orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
	"purpose": [],
	"revokedMembers": [],
	"rolesAndObligations": [],
	"serviceOfferings": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c8fb4371f3eabe3ddfea"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c9474371f3eabe3ddff0"
		}
	],
	"status": "signed",
	"updatedAt": "2024-06-06T14:35:51.522Z"
}

Output

[
	{
		"url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
		"configurations": {
			"allowRecommendation": true,
			"allowPolicies": true
		},
		"recommendations": [
			{
				"policies": [
					{
						"policy": "MUST not use data for more than n times",
						"frequency": 1
					}
				],
				"ecosystemContracts": []
			}
		],
		"matching": [
			{
				"policies": [],
				"ecosystemContracts": []
			}
		]
	},
	{
		"url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
		"configurations": {
			"allowRecommendation": true,
			"allowPolicies": true
		},
		"recommendations": [
			{
				"policies": [
					{
						"policy": "MUST not use data for more than n times",
						"frequency": 1
					}
				],
				"ecosystemContracts": []
			}
		],
		"matching": [
			{
				"policies": [],
				"ecosystemContracts": []
			}
		]
	}
]

This algorithm will handle the recommendations by sending a query to Altas Search and saving the results.

See input/output example

Input

{
	"_id": "6661c8e34371f3eabe3ddfde",
	"createdAt": "2024-06-06T14:34:11.128Z",
	"ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536",
	"members": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"role": "orchestrator",
			"signature": "hasSigned",
			"date": "2024-06-06T14:34:16.722Z"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"role": "participant",
			"signature": "hasSigned",
			"date": "2024-06-06T14:35:51.524Z"
		}
	],
	"orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
	"purpose": [],
	"revokedMembers": [],
	"rolesAndObligations": [],
	"serviceOfferings": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c8fb4371f3eabe3ddfea"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c9474371f3eabe3ddff0"
		}
	],
	"status": "signed",
	"updatedAt": "2024-06-06T14:35:51.522Z"
}

Output

[
  {
    "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    "recommendations": [
      {
        ...other fields
        "ecosystemContracts": [
          "66796b01cbcaf23233cf4de1"
        ]
      }
    ],
    ...other fields
  },
  {
    "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    "recommendations": [
      {
        ...other fields
        "ecosystemContracts": [
          "66796b16b11a476c352a68bc"
        ]
      }
    ],
    ...other fields
  }
]

See input/output example

Input

{
	"_id": "6661c8e34371f3eabe3ddfde",
	"createdAt": "2024-06-06T14:34:11.128Z",
	"ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536",
	"members": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"role": "orchestrator",
			"signature": "hasSigned",
			"date": "2024-06-06T14:34:16.722Z"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"role": "participant",
			"signature": "hasSigned",
			"date": "2024-06-06T14:35:51.524Z"
		}
	],
	"orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
	"purpose": [],
	"revokedMembers": [],
	"rolesAndObligations": [],
	"serviceOfferings": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c8fb4371f3eabe3ddfea"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c9474371f3eabe3ddff0"
		}
	],
	"status": "signed",
	"updatedAt": "2024-06-06T14:35:51.522Z"
}

Output

[
  {
    "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    ...other fields
    "matching": [
      {
        "policies": [
          {
            "policy": "MUST not use data for more than n times"
          },
        ],
        "ecosystemContracts": [
          "66796b01cbcaf23233cf4de1"
        ]
      }
    ]
  },
  {
    "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    ...other fields
    "matching": [
      {
        "policies": [
          {
            "policy": "MUST not use data for more than n times"
          },
        ],
        "ecosystemContracts": [
          "66796b16b11a476c352a68bc"
        ]
      }
    ]
  }
]

Policies Algorithms Execution

See input/output example

Input

{
	"_id": "6661c8e34371f3eabe3ddfde",
	"createdAt": "2024-06-06T14:34:11.128Z",
	"ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536",
	"members": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"role": "orchestrator",
			"signature": "hasSigned",
			"date": "2024-06-06T14:34:16.722Z"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"role": "participant",
			"signature": "hasSigned",
			"date": "2024-06-06T14:35:51.524Z"
		}
	],
	"orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
	"purpose": [],
	"revokedMembers": [],
	"rolesAndObligations": [],
	"serviceOfferings": [
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c8fb4371f3eabe3ddfea"
		},
		{
			"participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
			"serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
			"policies": [
				{
					"description": "MUST not use data for more than n times",
					"permission": [
						{
							"action": "use",
							"target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb",
							"constraint": [
								{
									"leftOperand": "count",
									"operator": "lt",
									"rightOperand": 10
								}
							]
						}
					],
					"prohibition": []
				}
			],
			"_id": "6661c9474371f3eabe3ddff0"
		}
	],
	"status": "signed",
	"updatedAt": "2024-06-06T14:35:51.522Z"
}

Output

[
  {
    "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    "recommendations": [
      {
        "policies": [
          {
            "policy": "MUST not use data for more than n times",
            "frequency": 2
          },
        ],
       ...other fields
      }
    ],
    ...other fields
  },
  {
    "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1",
    "configurations": {
      "allowRecommendation": true,
      "allowPolicies": true
    },
    "recommendations": [
      {
        "policies": [
          {
            "policy": "MUST not use data for more than n times",
            "frequency": 2
          },
        ],
        ...other fields
      }
    ],
    ...other fields
  }
]

Change Stream

The change stream is a MongoDB functionality that allows listening to events from collections (insert, update, delete, …). This way we can manage to process the algorithm whenever we want through the entities lifecycle to keep the profiles up to date and give real time recommendations and matching.

3 potential events can be listened to for the contract agent:

Creation or signature of bilateral: create a new profile or update the profile policies preferences.
Signature of ecosystem contract for the policies and preferences of the ecosystem: create a new profile or update the policies preferences and recommendations.
Revocation of ecosystem contract: update profile recommendations.

3 potential events can be listened to for the consent agent:

Consent given: create a new profile or update the profile policies preferences.
New data exchanges created: create a new profile or update the policies preferences and recommendations.
Consent status changed: update profile recommendations.

Change Stream Handling

The agent will handle the change stream event provided by mongodb or mongoose (same usage).

const { MongoClient } = require("mongodb");

async function watchCollection(dbUrl, dbName, collectionName, onChange) {
	const client = new MongoClient(dbUrl, {
		useNewUrlParser: true,
		useUnifiedTopology: true,
	});

	try {
		await client.connect();
		console.log("Connected to MongoDB");
		const db = client.db(dbName);
		const collection = db.collection(collectionName);

		const changeStream = collection.watch();

		changeStream.on("change", (change) => {
			console.log("Change detected:", change);
			onChange(change);
		});

		console.log(`Watching collection: ${collectionName}`);
	} catch (err) {
		console.error(err);
	}
}

Example of a signature applied to a use case contract Workflow

sequenceDiagram
    actor External
    participant CM as Contract-manager
    participant DB as Database
    box rgb(33,66,99) Contract-Agent
      participant CS as Change stream
      participant PA as Profile algorithm
      participant R as Recommendation
      participant AS as Atlas Search
    end

    External->>CM: sign dsuo contract
    CM->>DB: update document
    DB->>CS: event
    CS->>PA: Execute
    PA->>PA: check if profile exists
    PA->>DB: query
    DB-->>PA: Profil
    alt
        PA->>PA: profile doesn't exists
        PA->>CM: Create profile
    end
    CS->>R: Execute
    R->>AS: Query
    AS-->>R: Results
    R->>DB: Update document
    CM->>AS: Query
    AS-->>DB: Update document

sequenceDiagram
    actor External
    participant CM as Consent-manager
    participant DB as Database
    box rgb(33,66,99) Consent-Agent
      participant CS as Change stream
      participant PA as Matching
      participant R as Recommendation
      participant AS as Atlas Search
    end

    External->>CM: give consent
    CM->>DB: update document
    DB->>CS: event
    CS->>PA: Execute
    PA->>PA: check if preferences exists
    PA->>DB: query
    DB-->>PA: preferences
    alt
        CS->>R: Execute
        R->>AS: Query
        AS-->>R: Results
        R->>DB: Update document
    end

Configuration and deployment settings

Logging and Operations

The Consent/Contracts Negotiating Agent logs operations, errors, and warnings to designated log files. Logging includes details such as consent requests, contract negotiations, integration errors, and system status updates. Error scenarios, such as failed consent requests or contract validation errors, are logged with appropriate error codes and descriptions to aid in troubleshooting and debugging.

Limits and Usage Constraints

The Consent/Contracts Negotiating Agent imposes certain limits and usage constraints to ensure efficient operation and resource allocation within the dataspace ecosystem. These limits may include maximum concurrent requests, maximum dataset size for contract profiles, and rate limiting for API calls to external systems. Additionally, the agent may enforce authentication and access control mechanisms to protect sensitive data and ensure compliance with regulatory requirements. Configuration options for these limits and constraints can be adjusted based on deployment requirements and scalability considerations.

OpenAPI Specification

TODO When ready.

Third Party Components & Licenses

Component	Link	License
Atlas Search	https://www.mongodb.com/products/platform/atlas-search	Proprietary license

Test specification

Test plan

The testing strategy for the Consent/Contracts Negotiating Agent will focus on ensuring the correctness, reliability, and performance of its functionalities. We will employ a combination of unit tests, integration tests, and possibly UI tests where relevant. The testing environment will replicate production-like conditions to validate the agent's behavior accurately. Acceptance criteria will be defined based on user stories, functional requirements, and performance benchmarks.

Unit tests

For unit testing, we will utilize the Mocha testing framework along with Chai for assertions. The test cases will cover individual components and modules of the Consent/Contracts Negotiating Agent, including consent management, contract profile management, catalog integration, communication interface, and data exchange proposals. Mocking frameworks like Sinon may be used to isolate dependencies and simulate external interactions.

Integration tests

Integration tests will focus on validating the interaction between different components of the Consent/Contracts Negotiating Agent. We will use tools such as Postman for API testing to verify communication interfaces and data exchange protocols. Additionally, integration tests will ensure seamless integration with external systems like consent managers and catalog APIs. Continuous Integration (CI) pipelines will be set up to automate the execution of integration tests.

UI test

UI tests will be defined for any user interfaces or administrative dashboards provided by the Consent/Contracts Negotiating Agent. Testing frameworks like Cypress will be used to automate UI interactions and validate the usability and functionality of the user interface. UI tests will cover scenarios such as consent preference settings, contract profile management, and error handling.

Partnerships & Roles

Visions

Source code of the contract agent
Source code of the consent agent
Integration documentation of the agent in the contract-manager
Integration documentation of the agent in the consent-manager
Definition of the indexation for the search engines
OpenAPI specification (integrated in the contract/consent managers)
Provide first implementation solution through VisionsTrust services

IMC

Ensure alignment with consent management development in Gaia-x and IDSA
Specification design review

NomadLabs

Provide decentralized data governance expertise

Usage in the Dataspace

The Consent/Contracts Agent significantly enhances the management of data usage and sharing agreements within the dataspace ecosystem. By automating consent and contract negotiations, it ensures compliance with predefined policies and conditions, streamlining the process for both individuals and organizations.

For individuals, the agent provides an intuitive interface to manage consent preferences, facilitating personalized service recommendations and enabling data exchanges that align with their consent profiles. Organizations benefit from the agent’s ability to streamline negotiations, applying consistent contractual agreements through the use of ODRL policies and values to identify relevant partners and datasets.

Through integration with the dataspace ecosystem, the agent guarantees compatibility with ecosystem conditions and regulatory requirements. This integration not only improves data governance but also promotes collaboration and innovation within the dataspace by enabling efficient and secure data exchanges.

Consent/contracts negotiating agent BB – Design Document – Prometheus-X Components & Services

Consent/contracts negotiating agent BB – Design Document

Technical usage scenarios & Features

Features/main functionalities

Technical usage scenarios

Requirements

Integrations

Direct Integrations with Other BBs

Core Building Blocks

Integrations via Connector

Relevant Standards

Data Format Standards

Input / Output Data

Matching

Consent Matching

Contract Matching

Streamlining Negotiation Process

Recommendations of Data Exchanges

Architecture

Dynamic Behaviour

Communication with other components

Verification of consent preferences to automate consent grant

Technical Specifications

Consent Agent

Consent preferences

API Endpoints

Contract Agent

Contract Profiles

API Endpoints

Library Setup - Example

Initialization Example

API Integration Example

Search Module for Contrat and Consent Agents

Objective

Main Features

Atlas Search Example

Algorithms

Profile Algorithms Execution

Consent / contract Recommendation

Consent / Contract Matching

Policies Algorithms Execution

Change Stream

Change Stream Handling

Example of a signature applied to a use case contract Workflow

Example of a consent given

Configuration and deployment settings

Logging and Operations

Limits and Usage Constraints

OpenAPI Specification

Third Party Components & Licenses

Test specification

Test plan

Unit tests

Integration tests

UI test

Partnerships & Roles

Visions

IMC

NomadLabs

Usage in the Dataspace