---

Table of Contents

• NodeJS Driver for ProvenDB.
• Table of Contents
• Requirements
• Getting Started
  • Installation
  • Quick Start
    • ProvenDB Service
    • Connect to MongoDB
    • Using ProvenDB
      • Document History.
      • Create a Proof
      • Get an existing Proof
  • Next Steps
• Documentation
• Troubleshooting
  • Change Log
  • Compatability
• Contributing

Requirements

_ Full requirements have not yet been tested, coming soon._

Getting Started

First, create a new project using npm.

mkdir myProvenDBApp
cd myProvenDBApp

npm init

Installation

Now we can add the only two dependencies we need to get started.

npm install mongodb --save
npm install @southbanksoftware/provendb-node-driver --save

Quick Start

ProvenDB Service

This driver will only work when run against a ProvenDB service. You can get a free early access account here.

Connect to MongoDB

Create a file called index.js and put the following code inside.

Note: We'll use using Async/Await syntax for this example to maintain clarity of code, but the same can be accomplished with callbacks or promises.

// Import required libraries.
const ProvenDB = require('@southbanksoftware/provendb-node-driver').Database;
const { MongoClient } = require('mongodb');
// Define our connection information.
const URL = process.env.PROVENDB_URI;             // The URI for your ProvenDB service.
const DATABASE = process.env.PROVENDB_DATABASE;   // The Database for your ProvenDB service.
let connection; // Our MongoDB connection object.
let db;         // Our MongoDB Database
let pdb;        // Our ProvenDB Database.
let result;     // To store our result documents.

async function proveMyDB() {
  connection = await MongoClient.connect(process.env.PDB_PROXY_URI);
  db = await connection.db(DATABASE);

  // ProvenDB Logic goes here...

  // Document History

  // Create a Proof

  // View a Proof.
}

proveMyDB();

You may notice this looks just like MongoDB code so far. Run your app with node index.js, you should see the Connected successfully to server message.

Using ProvenDB

To use the extra Blockchain and versioning capabilties of ProvenDB, all you need to do is pass your Mongo Connection into the ProvenDB driver.

Under this section:

// ProvenDB Logic goes here...

Add the following code to insert a document:

  pdb = new ProvenDB(db);                           // Create ProvenDB Client.
  collection = pdb.collection('proven_staff');      // Get collection.
  result = await pdb.getVersion();                  // Check current version.
  console.log(`Version was ${result.version}.`);
  result = await collection.insertOne({             // Add a document.
    name: 'Michael',
    role: 'Code Monkey'
  });
  console.log(`Inserted a document.`);
  result = await pdb.getVersion();                  // Check version again.
  console.log(`Version is now ${result.version}.`);

You may have noticed that we can get the collection('proven_staff') directly from the ProvenDB client, that's because it exposes the underyling MongoDB functions as well. This means you don't need to go back and forth between the native MongoDB driver and the ProvenDB driver, everything you need is now avaliable in our pdb object!

If you run this script again with node index.js you'll see that each time we insert a document, our version number increments. This is what allows us to keep point in time history of your documents for later anchoring on the blockchain. For more information about versioning, see this page.

Document History.

Let's have a look at one of the things we can do with this new version information. We'll make some updates to our document, and then retrieve the history of that document.

Under this section:

// Document History

Add the following code:

  // Update a document.
  result = await collection.update(
    { name: 'Michael', role: 'Code Monkey' },
    { $set: { role: 'Chief Code Monkey' } }
  );
  console.log(`Updated ${result.result.nModified} document/s.`);
  // Fetch the history of that document.
  result = await pdb.docHistory('proven_staffe', { name: 'Michael' });
  console.log(
    `History for document: ${JSON.stringify(result.docHistory[0], null, 4)}`
  );

You should see something like the following if you execute your code:

History for document: {
    "collection": "proven_staff",
    "_id": "5d19a8ee33faa1ed71a8e364",
    "history": {
        "versions": [
            {
                "minVersion": 58,
                "maxVersion": 59,
                "status": "Unproven",
                "started": "2019-07-01 06:32:14",
                "ended": "2019-07-01 06:32:14",
                "document": {
                    "name": "Michael",
                    "role": "Code Monkey"
                }
            },
            {
                "minVersion": 60,
                "maxVersion": "9223372036854775807",
                "status": "Unproven",
                "started": "2019-07-01 06:32:21",
                "ended": "2019-07-01 06:32:21",
                "document": {
                    "name": "Michael",
                    "role": "Chief Code Monkey"
                }
            }
        ]
    }
}

Here we can see that Michael was promoted along with the time that update occured. You may notice that the status field is set to Unproven. This indicated to us that these version of the Database have not yet been placed on the Blockchain. Let's change that.

Create a Proof

Under this section:

// Create a Proof

Add the following code:

  result = await pdb.submitProof();
  console.log(`Submitted Proof: ${JSON.stringify(result, null, 4)}`);

Run the code again and you will see a result like this:

Submitted Proof: {
    "ok": 1,
    "version": 68,
    "dateTime": "2019-07-01T06:40:32.000Z",
    "hash": "0ad12bf41ab2a7047148d5ee30cc61284f11676bf0e907a38741a740db072ca4",
    "proofId": "1ffbe8e0-9bcb-11e9-a57b-01d798cd6796",
    "status": "Pending"
}

We can see here that a new proof has been created for version 68, at the current time and that it is still in status Pending. This means it has been sent to the Blockchain but is not yet part of a block. For more information about working with proofs see this page.

Get an existing Proof

  result = await pdb.getProof();
  console.log(`Latest Proof Is: ${JSON.stringify(result, null, 4)}`);

Run the code again and you will see a result like this:

Latest Proof Is: {
    "ok": 1,
    "proofs": [
        {
            "proofId": "1ffbe8e0-9bcb-11e9-a57b-01d798cd6796",
            "version": 68,
            "submitted": "2019-07-01T06:40:32.000Z",
            "hash": "0ad12bf41ab2a7047148d5ee30cc61284f11676bf0e907a38741a740db072ca4",
            "scope": "database",
            "status": "Pending",
            "details": {
                "protocol": {
                    "name": "chainpoint",
                    "uri": "http://35.235.91.33",
                    "hashIdNode": "1ffbe8e0-9bcb-11e9-a57b-01d798cd6796"
                }
            }
        }
    ]
}

By default both submitProof and getProof will operate on the latest version of the database, however you can also submitProof for a specific version and collection. See the documentation for more details.

Next Steps

If you're searching for some help getting started, take a look at some of these helpful next steps

• Read through the documentation and examples.
• Read through some of our blogs.
• Try our sample application built on top of ProvenDB: ProvenDocs
• Send us an email at [email protected].

Documentation

• ProvenDB high level documentation and concepts manual is avaliable here

• Node Driver API documentation is avaliable online here.

  OR

• You can generate the Driver documentation by cloning this repository and running:

npm install
npm generate-docs

Troubleshooting

Change Log

You can view the full change log here.

Compatability

Full compatability has not yet been tested, coming soon.

Contributing

For issues, questsions or feature requests relating directly to the ProvenDB Node driver you can create Github Issues here or by emailing us directly at [email protected].

For issues, questions or requests relating to the ProvenDB platform you can ask us questions on our support forum here.

For questsions about ProvenDB or Southbanksoftware the companies, please email us directly at [email protected].