Neodymium Plated Magnet

    @notabene/nodejs
    TypeScript icon, indicating that this package has built-in type declarations

    1.12.1 • Public • Published

    Notabene NodeJS SDK

    pipeline status Latest Release

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

    DocumentationGetting startedInstallationConfiguration

    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 and audience to https://api.notabene.dev.

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

    VASP methods

    • client.trustFramework.get(...) get properties of a VASP
    • client.trustFramework.list(...) get a list of VASPs
    • client.trustFramework.update(...) update properties of your VASP

    Transaction methods

    • client.transaction.create(...) create a new outgoing transaction (see details below)
    • client.transaction.get(...) get transaction by id (see details below)
    • client.transaction.update(...) update transaction (see details below)
    • client.transaction.list(did) retrieve a list of transactions
    • client.transaction.approve(id) approve a transaction by ID
    • client.transaction.cancel(id) cancel a transaction by ID
    • client.transaction.confirm(id) confirm a transaction by ID
    • client.transaction.reject(id) reject a transaction by ID
    • client.transaction.notReady(id) mark transaction as Not Ready by ID
    • client.transaction.accept(id) accept a transaction by ID
    • client.transaction.decline(id) decline a transaction by ID
    • client.transaction.notify(...) create an empty incoming transaction
    • client.transaction.redirect(fromDID, toDID) redirect transaction
    • client.transaction.verifyMessage(signature, message, address) Verify a signature (for beneficiary ownership proof)

    Creating Transactions

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

    Create a Basic Transaction

    const ivms = ...; // (see Appendix)
    const payload = ...; // (see Appendix)
    
    const txCreated = await client.transaction.create(payload);

    Create an "End-2-End Encrypted" Transaction

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

    const ivms = ...; // (see Appendix)
    const payload = ...; // (see Appendix)
    const jsonDIDKey = ...; // create or import a jsonDIDKey (see below)
    
    const txCreated = await client.transaction.create(
      payload,
      jsonDIDKey
    );

    Hybrid Encryption

    The hybrid encryption method 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.

    const txCreated = await client.transaction.create(
      payload,
      jsonDIDKey,
      true // hybrid
    );

    JsonDIDKey

    For END_2_END and HYBRID encryption your VASP needs a dedicated DIDKey, which is a public-private keypair. You can create a new keypair using the @notabene/cli and then publish it to the Notabene directory under the pii_didkey field. This allows other VASPs retrieve your public key and encrypt PII data to you.

    // get your encryption key
    const ikey = ... // or create a new key using the CLI, or: await client.toolset.createKey();
    
    // extract the did:key (public key)
    const pii_didkey = JSON.parse(ikey).did;
    
    // upload did:key to your VASP on the Notabene directory
    const fields = [
      {
        fieldName: 'pii_didkey',
        values: [
          {
            value: pii_didkey,
          },
        ],
      },
    ];
    await client.trustFramework.update(vaspDID, fields);

    Typically you will do this only once, and re-use the same keypair for a long time. If you believe your private key was compromised, you can rotate your keypair (ie. create a new one + publish it again). Data encrypted using a specific public key can only be decrypted with its private key, so 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 HOSTED (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: '...',
    });

    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: '...' },
      jsonDIDKey // for END_2_END | HYBRID
      // false | true
    );

    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.

    Keywords

    none

    Install

    npm i @notabene/nodejs

    DownloadsWeekly Downloads

    39

    Version

    1.12.1

    License

    MIT

    Unpacked Size

    60.1 kB

    Total Files

    6

    Last publish

    Collaborators

    • richardnotabene
    • ajunge