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

If you are looking for a high-level overview of the encryption process, have a look at our knowledge base article.

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:0xd4bd902ec78578f33a20ff601504d2ab324cfab9',
  beneficiaryVASPdid: 'did:ethr:0x75215d5bfc19e1a4f0301b40abcf542aa6de8613',
  transactionBlockchainInfo: {
    origin: '0x12htre34567897grt5644e56dtv',
    destination: '0x3215867456brt342436423',
  },
  originator: ivms.originator,
  beneficiary: ivms.beneficiary,
};

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

// needs to be called async:

const myfunc = async function(){
    const txCreated = await client.transaction.create(payload);
    console.log(txCreated);
  }
  myfunc();

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


Did this page help you?