Creating transactions

There are three ways to create and send a travel rule transaction using the SDK:

  1. Basic transaction - Hosted
  2. End-to-end encryption
  3. Hybrid encryption

See here for more information.


Hosted Encryption

Notabene encrypts all raw Travel Rule transaction data created through our easy-to-use restful API without worrying about local key management. Each VASP has a dedicated encryption key managed by Notabene’s PII service and can be rotated on-demand.

const ivms = {
    originator: {
      originatorPersons: [
        {
          naturalPerson: {
            name: [
              {
                nameIdentifier: [
                  {
                    primaryIdentifier: 'Normann',
                    secondaryIdentifier: 'Christoffer'
                  },
                ],
              },
            ],
            nationalIdentification: {
              nationalIdentifier: 'AABBCCDDEEFF0011223344',
              nationalIdentifierType: 'CCPT',
              countryOfIssue: 'NO',
            },
            dateAndPlaceOfBirth: {
              dateOfBirth: '1900-01-01',
              placeOfBirth: 'Norway',
            },
            geographicAddress: [
              {
                addressLine: ['Oslo street 123, 2001, Oslo'],
                country: 'NO'
              },
            ],
          },
        },
      ],
      accountNumber: ['01234567890'],
    },
  
    beneficiary: {
      beneficiaryPersons: [
        {
          naturalPerson: {
            name: [
              {
                nameIdentifier: [
                  {
                    primaryIdentifier: 'Danskmann',
                    secondaryIdentifier: 'Niels'
                  },
                ],
              },
            ],
          },
        },
      ],
      accountNumber: ['01234567890'],
    },
  };
  
  const payload = {
    transactionAsset: 'BTC',
    transactionAmount: '12345678987654321',
    originatorVASPdid: 'did:ethr:0x940a4b2a0932733b842e4aa906761bb3d3bd8148',
    beneficiaryVASPdid: 'did:ethr:0x270d4f239359471f1d1c80781a53cf8105f7d08f',
    transactionBlockchainInfo: {
      origin: '0x12htre34567897grt5644e56dtv',
      destination: '0x3215867456brt342436423',
    },
    originator: ivms.originator,
    beneficiary: ivms.beneficiary,
  };
    
  // needs to be called async:
  
  const myfunc = async function(){
      const txCreated = await client.transaction.create(payload);
      console.log(txCreated);
    }
    myfunc().catch((err)=>console.error(err));

End-2-End Encrypted

End-to-End Escrow PII brings the most security, as the Originating VASP encrypts PII data so that only they and the Beneficiary VASP can decrypt it:

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 Escrow PII mode extends the End-to-End flow, where the Originator VASP further encrypts the PII data selectively using their dedicated Notabene-managed encryption key, allowing Notabene to decrypt the PII (or parts of the PII data) for in-flow pre-transaction name sanction screening:

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

Getting your 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:

  1. Installing the CLI:
npm i -g @notabene/cli
  1. Generate JsonDIDkey
notabene keys:create

This will generate a JSON object containing an Ed25519 key and metadata which can be passed to the Notabene SDK when creating transactions to encrypt the PII.

{
"did":"did:key:z6MkjwpTikNZkpfop2ebcbPfsxi786ftTr9nGBD3XKKHZ2S",
"controllerKeyId":"519b59a6b7ebf128f6c6af4081f5e512750e768908263dbc656b7b3541c33",
"keys":[{"type":"Ed25519","kid":"519b59a6b7eb7689c6af4081f5e512750e1b4e47f08263dbc656b7b3541c33",
"publicKeyHex":"519b59a6b7ebf128f6c7689f5e512750e1b4e47f08263dbc656b7b3541c33",
"meta":{"algorithms":["Ed25519","EdDSA"]},
"kms":"local",
"privateKeyHex":"0d07d8acda928f98765e4a0b80013e2be369c29564419ac3ba08107599aeb3fc519b59a6b7ebf128f6c6af4081f5e512750e1b4e47f08263dbc656b7b3541c33"}],
"services":[],
"provider":"did:key"
}

Adding the public key to the Notabene network VASP profile

// 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).