@notabene/reactnative-sdk

React Native SDK for Notabene

Installation

npm install @notabene/reactnative-sdk

Installation

Installing the library:

Using Yarn:

yarn add @notabene/reactnative-sdk

Using NPM:

npm install @notabene/reactnative-sdk

If you installed the library into your project, you can import it into your project:

import Notabene from '@notabene/reactnative-sdk';

Usage

Authentication

Use the customer token endpoint with your access token to receive a token with a customer's scope.

⚠️ IMPORTANT ⚠️

When requesting the customer token you must pass a unique customerRef per customer for ownership proof reusability, otherwise you might encounter unwanted behavior.

Create a new Notabene instance:

const notabene = new Notabene({
  nodeUrl: 'https://api.notabene.id',
  authToken: '{CUSTOMER_TOKEN}',
  resultDeepLink: 'yourapp://nb/result', // This is required to return the user to your app after the flow is completed
  componentDeepLink: 'yourapp://nb/component', // This is optional but should load up the component in your app. It is required for most Self-Hosted Wallet flows
  locale: 'de' // default locale
});

Use the same nodeUrl that you use to interact with the Notabene API.

Assisted Withdrawal

The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.

Embedded Webview Component

In some cases, in particular institutional or mobile apps you may prefer to link your customers to the component through an email or redirect the user to it in a mobile app.

const withdrawal = notabene.createWithdrawalAssist(tx, options);
const result = await withdrawal.openModal();

Bear in mind that this is a full screen view for your users.

The two parameters that should be configured are:

callback - a URL for your serverside. On completion this will receive an HTTP POST with the result as a json body and the authToken as an Authorization: Bearer header.
redirectUri - the user will be redirected here on completion. The result parameters will be json encoded in the URL fragment. You can use a mobile app schema to intercept these in your mobile app.

Note for data privacy reasons the callback will be coming from your users web browser and not from our infrastructure, so no static IP is currently possible. Instead please check the authToken provided with the request.

Transaction parameters

Asset specification

The asset field the following types of assets specified:

notabene_asset code passed as astring. See Notabene Assets Service.
CAIP-19 is a chain agnostic format allows you to support the widest amount of assets and blockchains including NFTs.
DTI is the ISO Digital Token Identifier format. See DTI registry for supported tokens.

Transaction amount specification

Use one of the following

amountDecimal A number specifying the amount in decimal format. Eg. amountDecimal=1.1 would mean 1.1 of for example BTC or ETH.

Destination address

Specify the beneficiary address as destination using one of the following formats:

CAIP-10 is a chain agnostic format allows you to specify the specific blockchain and address
EIP-3770 EVM URI
BIP-21 Bitcoin URI
Native blockchain address

Destination address

The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this:

assetPrice: {
  currency: 'USD', // ISO currency code
  price: 1700.12, // Asset price
};

Connect Wallet

The Connect Wallet component helps you collect and verify the address of your users self-hosted wallet in one go.

Asset specification

The asset field the following types of assets specified:

notabene_asset code passed as astring. See Notabene Assets Service.
CAIP-19 is a chain agnostic format allows you to support the widest amount of assets and blockchains including NFTs.
DTI is the ISO Digital Token Identifier format. See DTI registry for supported tokens.

Modal

Instantiate the modal and open it

const connect = notabene.createConnectWallet({asset:'ETH'}, options);
const {valid, ivms101, proof } = await connect.openModal();

Linked Component

In some cases, in particular institutional or mobile apps you may prefer to link your customers to the component through an email or redirect the user to it in a mobile app.

const connect = notabene.createConnectWallet({asset:'ETH'}, options, {
  callback: /// a serverside backend url
  redirectUri: // URI of website or mobile app to redirect user to after completion
});

// NodeJS redirect. Link also works in an email.
res.redirect(withdrawal.url);

Bear in mind that this is a full screen view for your users.

The two parameters that should be configured are:

callback - a URL for your serverside. On completion this will receive an HTTP POST with the result as a json body and the authToken as an Authorization: Bearer header.
redirectUri - the user will be redirected here on completion. The result parameters will be json encoded in the URL fragment. You can use a mobile app schema to intercept these in your mobile app.

Transaction Options

All components can be configured using an optional TransactionOptions object.

The following shows the full set of options in typescript:

import Notabene, {
		AgentType,
		PersonType,
		ProofTypes,
	} from '@notabene/javascript-sdk';

const options: TransactionOptions = {
  proofs: {
    microTransfer: {
      destination: '0x...',
      amountSubunits: '12344',
      timeout: 86440,
    },
    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
  },
  allowedAgentTypes: [AgentType.PRIVATE, AgentType.VASP], // js ['WALLET','VASP']
  allowedCounterpartyTypes: [
    PersonType.LEGAL, // JS: 'legal'
    PersonType.NATURAL, // JS: 'natural'
    PersonType.SELF, // JS: 'self'
  ],
  fields: {
    naturalPerson: {
      name: true, // Default true
      website: { optional: true },
      email: true,
      phone: true,
      geographicAddress: false,
      nationalIdentification: false,
      dateOfBirth: false,
      placeOfBirth: false,
      countryOfResidence: true,
    },
    legalPerson: {
      name: true, // Default true
      lei: true, // Default true
      website: { optional: true }, // Default true
      email: true,
      phone: true,
      geographicAddress: false,
      nationalIdentification: false,
      countryOfRegistration: true,
    },
    vasps: {
      addUnknown: true, // Allow users to add a missing VASP - Defaults to false
      onlyActive: true // Only list active VASPs - Default false
    }
  },
};
const withdrawal = notabene.createWithdrawalAssist(tx, options);

Common use cases

Only allow first party transactions

const firstParty: TransactionOptions = {
  allowedCounterpartyTypes: [
    PersonType.SELF, // JS: 'self'
  ],
};

Only VASP to VASP transactions

const vasp2vasp: TransactionOptions = {
  allowedAgentTypes: [AgentType.VASP], // js ['VASP']
};

Only Self-hosted wallet transactions

const options: TransactionOptions = {
  allowedAgentTypes: [AgentType.PRIVATE], // js ['WALLET']
};

Configuring ownership proofs

By default components support message signing proofs.

Supporting Micro Transactions (aka Satoshi tests)

You can support Micro Transfers (aka Satoshi tests) by adding a deposit address for the test.

Your compliance team will have to determine how to handle and verify these transactions in the rules engine or individually.

const options: TransactionOptions = {
  proofs: {
    microTransfer: {
      destination: '0x...',
      amountSubunits: '1234',
      timeout: 86440, // Optional timeout in seconds, which is displayed to the user
    },
    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
  }
}

Notabene does not currently verify these tests automatically as you likely already have the infrastructure to do so.

You will receive a response back from the component containing a proof object. For MicroTransfers it will look like this:

type MicroTransferProof {
  type: ProofTypes.MicroTransfer;
  status: ProofStatus.PENDING;
  did: DID;
  address: CAIP10; // CAIP10 account to be verified
  txhash: string; // Transaction Hash to verify
  chain: CAIP2; // CAIP2 identifier of blockchain
  amountSubunits: string; // Amount in subunits eg (satoshi or wei) to be verified
}

Fallback Proof Options

You may accept a few options if none of the other are available. We do not recommend them, as they do not provide sufficient proof. However many VASPs do allow them for now:

const options: TransactionOptions = {
  proofs: {
    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
  }
}

The two options are:

screenshot Where a user is requested to upload a screenshot of their wallet
self-declaration Where a user self declares that they control the wallet address

Counterparty Field Properties

The fields requested from a customer about a counterparty can be configured with the fields object. You can configure required and optional fields individually for both natural and legal persons.

We recommend working closely with your compliance team for this. Bearing in mind that different jurisdictions have different rules.

Each field can be configured like this:

true required field
false don't show
{ optional: true } show but don't require
{ transmit: true } Include in beneficiary field of IVMS101 to be transmitted to counterparty

Eg:

{
  naturalPerson: {
    website: { optional: true },
    email: true,
    phone: false,
  }
}

The above will always ask the user for the following for natural persons:

name since it is on by default (you can disable it explicitly by setting it to false)
website is show but is optional
email is required

Full Example

const options: TransactionOptions = {
  fields: {
    naturalPerson: {
      name: true, // Default true
      website: { optional: true },
      email: true,
      phone: true,
      geographicAddress: false,
      nationalIdentification: false,
      dateOfBirth: {
        transmit: true
      },
      placeOfBirth: false,
      countryOfResidence: true,
    },
    legalPerson: {
      name: true, // Default true
      lei: true, // Default true
      website: { optional: true }, // Default true
      email: true,
      phone: true,
      geographicAddress: false,
      nationalIdentification: false,
      countryOfRegistration: true,
    },
  },
};

Field reference

Field name	Natural	Legal	IVMS101	Transmitted	description
`name`	✅	✅	✅	✅	Full name
`email`	🟩	🟩	--	--	Email (for your internal purposes)
`website`	--	✅	--	--	Business Website (for your internal purposes)
`phone`	🟩	🟩	--	--	Mobile Phone (for your internal purposes)
`geographicAddress`	🟩	🟩	✅	🟩	Residencial or business address
`nationalIdentification`	🟩	🟩	✅	🟩	National Identification number
`dateOfBirth`	🟩	--	✅	🟩	Date of birth
`placeOfBirth`	🟩	--	✅	🟩	Place of birth
`countryOfResidence`	🟩	--	✅	🟩	Country of Residence
`lei`	--	✅	✅	✅	LEI (Legal Entity Identifier)
`countryOfRegistration`	--	🟩	✅	🟩	Country of Registration

Troubleshooting

When developing with the SDK, there is a requirement which uses a Web View to display the content. We recommend having the the WebView launch as either an external browser, or utilise with iOS the secure browser which attaches to the application. The SDK will utilise this by default for iOS.

Embedding a WebView within the application itself, causes difficulties with external providers like MetaMask, etc. During the Wallet Connect phase, the WebView will attempt to open a third party provider which the user selected to perform the connection. If embedded, the iOS operating system prevents the opening of these URLs unless the schema for that provider has been added to the host applications plist file.

For this purpose following the default process of the SDK is recommended.