contract-manager

Prerequisites

Before you begin, ensure you have met the following requirements in local:

pnpm package manager installed
mongodb

requirements with docker:

Docker or Docker desktop

Setup

Make sure to fill your .env (see .env.sample):

cat .env.sample

Copy the .env file

cp .env.sample.env

Setup contract-agent.config.json (needed if USE_CONTRACT_AGENT=true in .env)

by default in the sample file the url are set to work with the mongodb provided in the docker compose file.

cp contract-agent.config.sample.json contract-agent.config.json

Install project dependencies using pnpm:

pnpm install

This will install all the necessary dependencies for your project.

Usage for development

Watch for changes and automatically restart the server in development:

pnpm dev

This command will use nodemon to watch for changes and restart your application when changes are detected.

Generators

Generate TypeScript types for Mongoose using mongoose-tsgen:

pnpm gen-types

This command will generate TypeScript types based on your Mongoose models.

Generate Swagger API doc with:

pnpm gen-swagger

This command will generate Swagger documentation, accessible at http://localhost:{port}/docs/#/

Generate Source Code documentation with:

pnpm gen-docs

This command will generate documentation using TypeDoc for the source code and save it in a "docs" folder.

Building the project for production

Build the project:

pnpm build

This command will clean the build/ directory and compile your TypeScript code.

Start your Node.js application:

pnpm start

This command will start your application using the compiled code.

Docker

Clone the repository from GitHub: git clone https://github.com/Prometheus-X-association/contract-manager.git
Navigate to the project directory: cd contract-manager
Configure the application by setting up the necessary environment variables. You will need to specify database connection details and other relevant settings.

#example
NODE_ENV="development"
MONGO_USERNAME=""
MONGO_PASSWORD=""
MONGO_URL="mongodb://contract-manager-mongodb:27017/contract"
MONGO_TEST_URL="mongodb://contract-manager-mongodb:27017/test-contract"
SERVER_PORT=8888
SECRET_AUTH_KEY="abc123"
SECRET_SESSION_KEY="abc123Session"
CATALOG_REGISTRY_URL="https://registry.visionstrust.com/static/references/rules"
SERVER_BASE_URL=""
CATALOG_REGISTRY_FILE_EXT=""
LOGS_KEY=""
USE_CONTRACT_AGENT =true
CATALOG_AUTHORIZATION_KEY="123"

Create a docker network using docker network create ptx
Start the application: docker-compose up -d
If you need to rebuild the image docker-compose build and restart with: docker-compose up -d
If you don't want to use the mongodb container from the docker compose you can use the command docker run -d -p your-port:your-port --name contract-manager contract-manager after running docker-compose build

Terraform

Install Terraform: Ensure Terraform is installed on your machine.
Configure Kubernetes: Ensure you have access to your Kubernetes cluster and kubectl is configured.
Initialize Terraform: Run the following commands from the terraform directory.

cd terraform
terraform init

Apply the Configuration: Apply the Terraform configuration to create the resources.

terraform apply

Retrieve Service IP: After applying the configuration, retrieve the service IP.

terraform output contract_manager_service_ip

Replace placeholder values in the kubernetes_secret resource with actual values from your .env.

Ensure the server_port value matches the port used in your application.

Adjust the host_path in the kubernetes_persistent_volume resource to an appropriate path on your Kubernetes nodes.

Deployment with Helm

Install Helm: Ensure Helm is installed on your machine. You can install it following the instructions here.
Package the Helm chart:
```
helm package ./path/to/contract-manager
```

Deploy the Helm chart:

helm install contract-manager ./path/to/contract-manager

Verify the deployment:
```
kubectl get all -n contract-manager
```
Retrieve Service IP:
```
kubectl get svc -n contract-manager
```

Replace placeholder values in the values.yaml file with actual values from your .env.

Ensure the server_port value matches the port used in your application.

Configure your MongoDB connection details in the values.yaml file to point to your managed MongoDB instance.

Tests

Run tests:

pnpm test

This command will run your tests using Mocha, with test files located at ./src/tests/!(*.agent).test.ts.

Using the Contract Agent

To enable the Contract Agent, add the following line to your .env file:

USE_CONTRACT_AGENT=true

Configuring a DataProvider (`contract-agent.config.json`)

The configuration file is a JSON document consisting of sections, where each section describes the configuration for a specific DataProvider. Below is a detailed explanation of the available attributes:

source: The name of the target collection or table that the DataProvider connects to.
url: The base URL of the database host.
dbName: The name of the database to be used.
watchChanges: A boolean that enables or disables change monitoring for the DataProvider. When enabled, events will be fired upon detecting changes.
hostsProfiles: A boolean indicating whether the DataProvider hosts the profiles.
existingDataCheck: A boolean that enables the creation of profiles when the module is initialized.

Example Configuration

Here’s an example of a JSON configuration:

{
  "dataProviderConfig": [
    {
      "source": "contracts",
      "url": "mongodb://contract-manager-mongodb:27017",
      "dbName": "contract"
    },
    {
      "source": "profiles",
      "url": "mongodb://contract-manager-mongodb:27017",
      "dbName": "contract",
      "watchChanges": false,
      "hostsProfiles": true
    }
  ]
}

Contract Agent Tests

Prerequisites

requires a running mongoose server

Run tests:

pnpm test-agent

or

docker exec -it contract-manager pnpm test-agent

This command will run your tests using Mocha, with test files located at ./src/tests/*.agent.test.ts.

Expected result

example endpoints

POST /contracts

First create the contract to create the profile

headers: {"x-ptx-catalog-key": process.env.CATALOG_AUTHORIZATION_KEY, Content-Type: application/json}

the x-ptx-catalog-key is needed if you have set up the optional variable CATALOG_AUTHORIZATION_KEY in you .env

input:

{
 "role": "ecosystem",
 "contract": {
   "ecosystem": "test-ecosystem",
   "orchestrator": "",
   "serviceOfferings": [
     {
       "participant": "participant-1",
       "serviceOffering": "allowed-service",
       "policies": [
         {
           "description": "allowed-policy",
           "permission": [
             {
               "action": "read",
               "target": "http://contract-target/policy",
               "duty": [],
               "constraint": []
             },
             {
               "action": "use",
               "target": "http://contract-target/service",
               "duty": [],
               "constraint": []
             }
           ],
           "prohibition": []
         }
       ],
     }
   ],
   "purpose": [],
   "members": [],
   "revokedMembers": [],
   "dataProcessings": [],
 }
}

output :

{
   "ecosystem": "test-ecosystem",
   "orchestrator": "",
   "serviceOfferings": [
       {
           "participant": "participant-1",
           "serviceOffering": "allowed-service",
           "policies": [
               {
                   "description": "allowed-policy",
                   "permission": [
                       {
                           "action": "read",
                           "target": "http://contract-target/policy",
                           "duty": [],
                           "constraint": []
                       },
                       {
                           "action": "use",
                           "target": "http://contract-target/service",
                           "duty": [],
                           "constraint": []
                       }
                   ],
                   "prohibition": []
               }
           ],
           "_id": "67dc5c77a4e381ca892935d7"
       }
   ],
   "rolesAndObligations": [
       {
           "role": "ecosystem",
           "policies": [
               {
                   "permission": [],
                   "prohibition": []
               }
           ],
           "_id": "67dc5ead968a8212c516f18b"
       }
   ],
   "dataProcessings": [],
   "purpose": [],
   "members": [],
   "revokedMembers": [],
   "status": "pending",
   "_id": "67dc5c77a4e381ca892935d6",
   "createdAt": "2025-03-20T18:20:39.850Z",
   "updatedAt": "2025-03-20T18:20:39.850Z",
   "__v": 0
}

POST /negotiation/contract/negotiate

headers: {"x-ptx-catalog-key": process.env.CATALOG_AUTHORIZATION_KEY, Content-Type: application/json}

the x-ptx-catalog-key is needed if you have set up the optional variable CATALOG_AUTHORIZATION_KEY in you .env

input:

 {
    "profileId":  "participant-1",
    "contractData": {
      "_id": "67c70ff1e8ccfc4faadc683a",
      "ecosystem": "test-ecosystem",
      "@context": "http://www.w3.org/ns/odrl/2/",
      "@type": "Offer",
      "serviceOfferings": [
        {
          "participant": "test",
          "serviceOffering": "test-service",
          "policies": [
            {
              "description": "test-policy",
              "permission": [
                {
                  "action": "use",
                  "target": "test-target",
                  "constraint": [],
                  "duty": []
                }
              ],
              "prohibition": []
            }
          ]
        }
      ],
      "status": "signed"
    }
  }

output :

{
  "canAccept": false,
  "reason": "Contract contains unacceptable policies or services",
  "unacceptablePolicies": [
    "test-policy"
  ],
  "unacceptableServices": [
    "test-service"
  ]
}

PUT /negotiation/profile/preferences

headers: {"x-ptx-catalog-key": process.env.CATALOG_AUTHORIZATION_KEY, Content-Type: application/json}

the x-ptx-catalog-key is needed if you have set up the optional variable CATALOG_AUTHORIZATION_KEY in you .env

input:
{
  "profileId": "participant-1",
  "preferences": {
       "policies": [{ "policy": "test-policy", "frequency": 1 }],
       "services": ["test-service"],
       "ecosystems": ["test-ecosystem"]
     }
}
output :
{
  "message": "Profile preferences updated successfully."
}

For more information see the Tests definition.

License

This project is licensed under MIT License

see the [LICENSE.md] file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 301 Commits
.github/workflows		.github/workflows
.scannerwork		.scannerwork
docker		docker
public/rules		public/rules
src		src
templates		templates
terraform		terraform
.dockerignore		.dockerignore
.env.sample		.env.sample
.gitignore		.gitignore
.npmrc.sample		.npmrc.sample
.nvmrc		.nvmrc
.prettierrc		.prettierrc
Chart.yaml		Chart.yaml
LICENSE.md		LICENSE.md
README.md		README.md
contract-agent.config.sample.json		contract-agent.config.sample.json
docker-compose.yml		docker-compose.yml
mtgen.config.json		mtgen.config.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
sonar-project.properties		sonar-project.properties
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
values.yaml		values.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

contract-manager

Prerequisites

Setup

Usage for development

Generators

Building the project for production

Docker

Terraform

Deployment with Helm

Tests

Using the Contract Agent

Configuring a DataProvider (`contract-agent.config.json`)

Example Configuration

Contract Agent Tests

Prerequisites

example endpoints

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors 5

Uh oh!

Languages

License

Prometheus-X-association/contract-manager

Folders and files

Latest commit

History

Repository files navigation

contract-manager

Prerequisites

Setup

Usage for development

Generators

Building the project for production

Docker

Terraform

Deployment with Helm

Tests

Using the Contract Agent

Configuring a DataProvider (contract-agent.config.json)

Example Configuration

Contract Agent Tests

Prerequisites

example endpoints

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Configuring a DataProvider (`contract-agent.config.json`)

Packages