Important:

The package is for the Chainpont v4 proof schema. If you are looking to produce or read binary proofs for the older Chainpoint v3 Network (chainpoint-services), use version 4.1.0.

Chainpoint Binary

A Javascript library for serializing/deserializing a Chainpoint v4 proof between its Javascript Object/JSON and compressed binary forms.

About the Chainpoint Binary Format

Chainpoint v4 proofs are found in one of two forms; a Javascript Object, or its JSON String form, or a compressed binary. The binary form is designed to be:

• easy to use
• significantly smaller than JSON text
• simple and safe to convert to and from
• lossless across serialization/deserialization
• usable cross platform
• usable across many development languages
• easy to parse and understand
• lightweight

To acheive these goals we have chosen a simple mechanism for serializing proofs to binary form using two very common and well supported tools, MessagePack and zlib deflate:

MessagePack

MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.

MessagePack is currently supported by over 50 different programming languages.

This library makes use of the msgpack-lite implementation for Node.js. You can try it out or read the documentation.

zlib

MessagePack encoded proofs are then compressed with the zlib deflate compression function.

zlib is designed to be a free, general-purpose, legally unencumbered -- that is, not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. The zlib data format is itself portable across platforms.

This library makes use of the pako implementation of zlib which can be found here.

Chainpoint File Extensions

Chainpoint proofs should typically have a filename that is either the same as the proof_id that was returned when the hash was submitted to Chainpoint or the same filename as the original file that was hashed. A proof_id is a Version 1 UUID and is used as a handle to retrieve a proof.

When storing a proof alongside an original file on a filesystem that was hashed and sent to Chainpoint it may be more convenient to mirror the original filename and add the appropriate file extension.

Chainpoint v4 proofs should have one of the following file name + file extensions:

<filename>.chp.json

Uncompressed JSON string proof mirroring the original filename

<filename>.chp

MessagePack + zlib binary proof mirroring the original filename

<proof_id>.chp.json

Uncompressed JSON string proof named after the proof_id

<proof_id>.chp

MessagePack + zlib binary proof named after the proof_id

Installation

$ npm install --save chainpoint-binary

or

yarn add chainpoint-binary

Try it out

Try out the conversion of a sample proof, or one of your own, to Binary and back to JSON. This example code can be found in the docs directory.

https://chainpoint.org/chainpoint-binary/

Usage

Node.js

objectToBinary

objectToBinarySync

This function converts a Chainpoint proof in JSON String or Javascript Object form to a Buffer containing the standard binary form. The incoming Object will be validated against the formal Chainpoint Proof JSON Schema.

const cpb = require('chainpoint-binary')

// Valid proof in JSON or JS Object form
let chainpointProofObject = {...}

cpb.objectToBinary(chainpointProofObject, function (err, proofBinary) {
    if (err) {
      // if an error occurs, the error message will return here
    } else {
      // proofBinary is a Buffer representing the binary form of a Chainpoint proof
    }
})

const cpb = require('chainpoint-binary')

// Valid proof in JSON or JS Object form
let chainpointProofObject = {...}

let proofBinary = cpb.objectToBinarySync(chainpointProofObject)

objectToBase64

objectToBase64Sync

This function converts a Chainpoint proof in JSON String or Javascript Object form to a Base64 encoded string of the standard binary form. The incoming Object will be validated against the formal Chainpoint Proof JSON Schema.

const cpb = require('chainpoint-binary')

// Valid proof in JSON or JS Object form
let chainpointProofObject = {...}

cpb.objectToBase64(chainpointProofObject, function (err, proofBase64) {
    if (err) {
      // if an error occurs, the error message will return here
    } else {
      // proofBase64 is a Base64 encoded string representing the binary form of a Chainpoint proof
    }
})

const cpb = require('chainpoint-binary')

// Valid proof in JSON or JS Object form
let chainpointProofObject = {...}

let proofBase64 = cpb.objectToBase64Sync(chainpointProofObject)

binaryToObject

binaryToObjectSync

This function converts a Chainpoint binary proof to a Javascript Object. A Hexadecimal string or Base64 string in place of a Buffer is also acceptable as input. The outgoing Object will be validated against the formal Chainpoint Proof JSON Schema before being returned.

const cpb = require('chainpoint-binary')

// Valid proof in Buffer, Hex String, or Base64 String form
let chainpointProofBinaryBuffer = [...]

cpb.binaryToObject(chainpointProofBinaryBuffer, function (err, proofObject) {
    if (err) {
      // if an error occurs, the error message will return here
    } else {
      // proofObject contains the Javascript Object form of a Chainpoint proof
      // Wrap this with JSON.stringify() for the JSON form as needed.
    }
})

const cpb = require('chainpoint-binary')

// Valid proof in Buffer, Hex String, or Base64 String form
let chainpointProofBinaryBuffer = [...]

let proofObject = cpb.binaryToObjectSync(chainpointProofBinaryBuffer)

Browser

Note : You can copy docs/bundle.js into your app to include in a script tag, or use a CDN to serve it to your app directly.

Or install the npm package in a place available to your web pages and set the script src tag to something like the following. A set of window global functions chainpointBinary.binaryToObject() and chainpointBinary.objectToBinary() will be available and operate the same as the Node.js example above.

<script src="./node_modules/chainpoint-binary/docs/bundle.js">

Development

Code Formatting & Linting

This project makes use of Prettier & ESLint to maintain clean, and consistently styled, code.

You can run ESLint manually using the CLI:

./node_modules/.bin/eslint .

You can run Prettier manually to see which files would be re-formatted by it. For example:

./node_modules/.bin/prettier -l *.js

This project is coded in the Visual Studio Code IDE and we use the following plugins to auto-format and report on linting issues during development:

vscode-eslint

EditorConfig