jsonld-signatures-merkleproof2019

A jsonld signature implementation to support MerkleProof2019 verification in Verifiable Credential context

NOTE

To make use of this package, consumers need to modify the security-context package locally as MerkleProof2019 is not part of the current npm distribution. Another solution is to install from github and use the v3-unstable vocab.

Usage

This package is currently designed to work with vc.js in order to verify MerkleProof2019 signed documents.

You will need to wrap the certificate with the Signature Suite:

    const myBlockcertsV3Definition = {
  ...
};

const verificationSuite = new LDMerkleProof2019({document: myBlockcertsV3Definition});

In the case of vc.js, you would then pass this suite to the verify method, through the suite parameter.

Under the hood

The verification principle of MerkleProof2019 is to compare the distant hash of the document (the one saved on the blockchain) with the hash of the local document being verified.

Anchoring chains

MerkleProof2019 verification as provided by Blockcerts does out of the box verification for Bitcoin (mainnet and testnet) and Ethereum (main and tests), using a set of public explorers.

REST APIs

By default this library provides some blockchain explorers to retrieve the transaction data associated with a proof. They are:

• For Bitcoin
  • Bitpay
  • Blockcypher
  • Blockexplorer. To confirm if still active
  • Blockstream
• For Ethereum
  • Blockcypher
  • Etherscan

You may provide your own explorer or even overwrite the existing ones. This is useful if you have a paid account with one explorer service and you want to ensure a high service availability, or if you'd like to provide identification keys to the ones provided by default.

Here is an example of how you would provide such service:

    const myBlockcertsV3Definition = {
  ...
};

const myOwnExplorerAPI: ExplorerAPI = {
  serviceURL: 'path/to/distant/api', // you may need to provide identification details here according to your service pattern
  priority: 0, // this is to decide if this gets called before the out-of-the-box services. 0 means your custom service is going to be called first, use 1 if you prefer the default explorers to be called first.
  parsingFunction: function ({jsonResponse: serviceReponse}: IParsingFunctionAPI): TransactionData { // only define this function when referring to a custom explorer
    // parse your service response in order to return the following information:
    return {
      remoteHash,
      issuingAddress,
      time,
      revokedAddresses
    }
  }
};
const options = {
  explorerAPIs: [myOwnExplorerAPI]
};

const verificationSuite = new LDMerkleProof2019({document: myBlockcertsV3Definition, options});

RPCs

In an alpha implementation, it is now possible to verify transaction of non natively supported chains, using RPC calls. If such is your case, 2 options are offered to you:

Your chain is compatible with EVM or BTC

In that case you can take advantage of the built-ins lookup functions. You only need to provide the url to the RPC service you want to use and the chainType property to decide which lookup function to use:

    const myBlockcertsV3Definition = {
  ...
};

const options = {
  explorerAPIs: [{
    serviceURL: 'https://rpc-mumbai.maticvigil.com/',
    priority: 0,
    apiType: 'rpc',
    chainType: 'evm'
  }]
};
const verificationSuite = new LDMerkleProof2019({document: myBlockcertsV3Definition, options});

Your chain is not compatible with EVM or BTC

NOTE: you can use this approach to modify the provided RPC lookup functions.

You will need to additionally provide your own lookup function. Contrary to rest APIs in this package, the parsing function needs to make the calls to the RPC service by itself.

    const myBlockcertsV3Definition = {
  ...
};

const options = {
  explorerAPIs: [{
    serviceURL: 'https://rpc-mumbai.maticvigil.com/',
    priority: 0,
    apiType: 'rpc',
    chainType: 'evm',
    parsingFunction: function ({serverUrl, transactionId}: IParsingFunctionAPI): TransactionData { // note that function signature is different than for REST parsingFunctions
      // your call to the `serverUrl` with the `transaction` id
      // parse your service response in order to return the following information:
      return {
        remoteHash,
        issuingAddress,
        time,
        revokedAddresses
      }
    }
  }]
};
const verificationSuite = new LDMerkleProof2019({document: myBlockcertsV3Definition, options});