@notabene/nodejs

Notabene NodeJS SDK

Notabene NodeJS SDK for sending and receiving transactions through the Notabene Travel Rule gateway.

Documentation • Getting started • Installation • Configuration

Getting Started

Step 1: Install the library

npm install @notabene/nodejs

Step 2: Initialize the client

const Notabene = require('@notabene/nodejs');

const client = new Notabene({
  clientId: '{CLIENT_ID}', // Add your own client ID
  clientSecret: '{CLIENT_SECRET}', // Add your own client secret
});

Configuration

Client ID and Client Secret

The client ID and client secret required to authenticate against Notabene's APIs must be requested.

Test environment

For sending transactions to Notabene's test environment, use your test Client ID and Client Secret and set the baseURL to https://api.notabene.dev.

const Notabene = require('@notabene/nodejs');

const client = new Notabene({
  baseURL: 'https://api.notabene.dev',
  clientId: '{CLIENT_ID}', // Add your own client ID
  clientSecret: '{CLIENT_SECRET}', // Add your own client secret
});

Creating Transactions

Examples for ivms and payload variables can be found in the Appendix.

Create a Basic Transaction

async function demo() {
  const ivms = ...;
  const payload = ...;

  const txCreated = await client.transaction.create(
    payload,
    PIIEncryptionMethod.DEFAULT
  );

  console.log(txCreated);
}

Create an "End-2-End Encrypted" Transaction

E2E encryption method will encryt PII that such that only you and the beneficiary VASP

async function demo() {
  const ivms = ...;
  const payload = ...;
  const jsonDIDKey = ...; // create or import a jsonDIDKey (see Appendix)

  const txCreated = await client.transaction.create(
    payload,
    PIIEncryptionMethod.END_2_END,
    jsonDIDKey
  );

  console.log(txCreated);
}

Hybrid Encryption

The hybrid encryption method PIIEncryptionMethod.HYBRID will also encrypt the PII data to Notabene, using a unique managed Escrow Key for your VASP. This allows us to run sanction screening on the PII data.

JsonDIDKey

For END_2_END and HYBRID encryption your VASP needs a dedicated DIDKey, which is a public-private keypair. The function initVASPkey will create a new DIDKey for your VASP and publish the public key to the Notabene directory. This allows other VASPs retrieve your public key and encrypt PII data to you.

const jsonDIDKey = await client.initVASPkey(vaspDID);

Typically you need to call this function only once, and re-use the jsonDIDKey for a long time. If you believe your private key was compromised, calling this function again will rotate your keypair. Data encrypted using a specific public key, can only be decrypted with its private key, don't throw away your old key(s) if you still have data of interest encrypted with those key(s).

Retrieving transactions

To retrieve a transaction simply call:

const txInfo = await client.transaction.get(id);

If the transaction was encrypted with the DEFAULT or HYBRID strategy, the PII Service will be able to decrypt it for you, the ivms101 property will contain the decrypted data. However, for END_2_END encrypted data you can pass your jsonDIDKey argument to decrypt it locally:

const txInfo = await client.transaction.get(id, jsonDIDKey);

Updating transactions

To update a transaction simply call the following with the fields you wish to update:

const updatedTx = await client.transaction.update(
  { id: txCreated.id, beneficiaryVASPdid: '...' },
  PIIEncryptionMethod.DEFAULT
);

Note, you need specify an encryption method just like in transaction.create (and your jsonDIDKey):

const updatedTxEnd2End = await client.transaction.update(
  { id: txCreated.id, beneficiaryVASPdid: '...' },
  PIIEncryptionMethod.END_2_END,
  jsonDIDKey
);

Appendix

txCreate example

// transaction.create payload:
const payload = {
  transactionAsset: 'ETH',
  transactionAmount: '1111111000000000000',
  originatorVASPdid: 'did:ethr:0xb086499b7f028ab7d3c96c4c2b71d7f24c5a0772',
  beneficiaryVASPdid: 'did:ethr:0xa80b54afa45dc22a4ebc0e1a9b638998a7899c33',
  transactionBlockchainInfo: {
    origin: '0x123',
    destination: '0x321',
  },
  originator: ivms.originator,
  beneficiary: ivms.beneficiary,
};

IVMS101 example

const ivms = {
  originator: {
    originatorPersons: [
      {
        naturalPerson: {
          name: [
            {
              nameIdentifier: [
                {
                  primaryIdentifier: 'Frodo',
                  secondaryIdentifier: 'Baggins',
                  nameIdentifierType: 'LEGL',
                },
              ],
            },
          ],
          nationalIdentification: {
            nationalIdentifier: 'AABBCCDDEEFF0011223344',
            nationalIdentifierType: 'CCPT',
            countryOfIssue: 'NZ',
          },
          dateAndPlaceOfBirth: {
            dateOfBirth: '1900-01-01',
            placeOfBirth: 'Planet Earth',
          },
          geographicAddress: [
            {
              addressLine: ['Cool Road /-.st'],
              country: 'BE',
              addressType: 'HOME',
            },
          ],
        },
      },
    ],
    accountNumber: ['01234567890'],
  },

  beneficiary: {
    beneficiaryPersons: [
      {
        naturalPerson: {
          name: [
            {
              nameIdentifier: [
                {
                  primaryIdentifier: 'Bilbo',
                  secondaryIdentifier: 'Bolson',
                  nameIdentifierType: 'LEGL',
                },
              ],
            },
          ],
        },
      },
    ],
    accountNumber: ['01234567890'],
  },
};

License

BSD 3-Clause © Notabene Inc.