@notabene/javascript-sdk 1.35.2 → 2.0.0-RC

package/README.md

@@ -2,37 +2,49 @@
 
 <img src="https://assets-global.website-files.com/5e68f0772de982756aa8c1a4/5eee5fb470215e6ecdc34b94_Full_transparent_black_1280x413.svg" height=50>
 <br>
+# Notabene SafeConnect Components JavaScript SDK
 
-# JavaScript SDK
+[![pipeline status](https://gitlab.com/notabene/open-source/javascript-sdk/badges/v2/pipeline.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/v2)
+[![npm version](https://img.shields.io/npm/v/@notabene/javascript-sdk.svg)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@notabene/javascript-sdk.svg)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@notabene/javascript-sdk)](https://bundlephobia.com/package/@notabene/javascript-sdk)
+[![Types](https://img.shields.io/npm/types/@notabene/javascript-sdk)](https://www.npmjs.com/package/@notabene/javascript-sdk)
+[![License](https://img.shields.io/npm/l/@notabene/javascript-sdk)](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/main/LICENSE.md)
+[![Dependencies](https://img.shields.io/librariesio/release/npm/@notabene/javascript-sdk)](https://libraries.io/npm/@notabene%2Fjavascript-sdk)
 
-See v2 branch for the latest version of the SDK.
+This library is the JavaScript SDK for loading the Notabene UX components in the front-end.
 
-[![npm version](https://badge.fury.io/js/%40notabene%2Fjavascript-sdk.svg)](https://badge.fury.io/js/%40notabene%2Fjavascript-sdk)
-[![Coverage Status](https://coveralls.io/repos/github/notabene-id/javascript-sdk/badge.svg?branch=master)](https://coveralls.io/github/notabene-id/javascript-sdk?branch=master)
-
-[![pipeline status](https://gitlab.com/notabene/open-source/javascript-sdk/badges/master/pipeline.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/master)
-[![Latest Release](https://gitlab.com/notabene/open-source/javascript-sdk/-/badges/release.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/releases)
-
-This library is the JavaScript SDK for loading the widget on a frontend.
-
-[Documentation](https://devx.notabene.id/docs/widget-v2) •
-[Installation](#installation)
+[Additional Documentation](https://devx.notabene.id/docs/embedded=ux)
 
 </div>
 
+## Table of Contents
+
 - [Installation](#installation)
-- [Usage](#usage)
-  - [Supported asset formats](#supported-asset-formats)
-  - [Re-rendering](#re-rendering)
-  - [Error handling](#error-handling)
-- [Customization](#customization)
-  - [Functionality](#functionality)
-  - [Pass the variables in the configuration](#pass-the-variables-in-the-configuration)
-  - [Theme](#theme)
-  - [Dictionary](#dictionary)
-  - [Fields Properties](#fields-properties)
-  - [Fallbacks](#fallbacks)
-  - [Transaction Custom Asset Price](#transaction-custom-asset-price)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Authentication](#authentication)
+- [General Component Usage](#general-component-usage)
+  - [Embedded Component](#embedded-component)
+    - [Dynamic updates](#dynamic-updates)
+  - [Modal](#modal)
+  - [Linked Component](#linked-component)
+- [Components](#components)
+  - [Assisted Withdrawal](#assisted-withdrawal)
+  - [Connect Wallet](#connect-wallet)
+  - [Deposit Request](#deposit-request)
+- [Error handling](#error-handling)
+- [Transaction parameters](#transaction-parameters)
+  - [Asset specification](#asset-specification)
+  - [Transaction amount](#transaction-amount)
+  - [Destination](#destination)
+  - [Asset Price](#asset-price)
+- [Configuration](#configuration)
+  - [Transaction Options](#transaction-options)
+  - [Common use cases](#common-use-cases)
+  - [Configuring ownership proofs](#configuring-ownership-proofs)
+  - [Counterparty Field Properties](#counterparty-field-properties)
+- [Locales](#locales)
 - [License](#license)
 
 ## Installation
@@ -40,16 +52,53 @@ This library is the JavaScript SDK for loading the widget on a frontend.
 There are two options for loading the Notabene SDK:
 
 ```bash
-<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@1.31.0/dist/es/index.js"></script>
+<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@next/dist/notabene.js"></script>
 ```
 
 Or installing the library:
 
+Using Yarn:
+
 ```bash
-yarn add @notabene/javascript-sdk
+yarn add @notabene/javascript-sdk@next
+```
+
+Using NPM:
+
+```bash
+npm install @notabene/javascript-sdk@next
+```
+
+If you installed the library into your project, you can import it into your project:
+
+```js
+import Notabene from '@notabene/javascript-sdk';
 ```
 
-## Usage
+## Quick Start
+
+```js
+// 1. Create Notabene instance
+const notabene = new Notabene({
+  nodeUrl: 'https://api.notabene.id',
+  authToken: 'YOUR_CUSTOMER_TOKEN'
+});
+
+// 2. Create and mount withdrawal component
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x1234...',
+  amountDecimal: 1.0
+});
+withdrawal.mount('#nb-withdrawal');
+
+// 3. Handle completion
+const { valid, value, txCreate } = await withdrawal.completion();
+if (valid) {
+  // Submit to your backend
+}
+
+## Core Concepts
 
 ### Authentication
 
@@ -63,353 +112,534 @@ Create a new Notabene instance:
 
 ```js
 const notabene = new Notabene({
-  vaspDID: 'did:ethr:0x94c38fd29ef36f5cb2f7bc771f9d5bd9f7d05f27',
-  widget: 'https://beta-widget.notabene.id',
-  container: '#container',
+  nodeUrl: 'https://api.notabene.id', // use `https://api.notabene.dev` for testing
   authToken: '{CUSTOMER_TOKEN}',
-  onValidStateChange: (isValid) => {
-    // Use this value to determine if the transaction is ready to be created.
-    console.log('is transaction valid', isValid);
-  },
-  onError: (err) => {
-    // If any errors are encountered, they will be passed to this function
-    alert(err.message);
-  },
+  locale: 'de', // default locale = `en`
 });
 ```
 
-Then render the widget:
+Use the same `nodeUrl` that you use to interact with the Notabene API.
 
-```js
-// Use this method when you need to collect missing information from the sender about the recipient (normal withdrawal)
-notabene.renderWidget('WITHDRAWAL');
+## General Component Usage
 
-// Use this method when you need to collect missing information from the recipient about the sender (for transactions created via notification)
-notabene.renderWidget('POST_DEPOSIT');
-```
+Each component can be used in various ways depending on your use case.
 
-To update the widget as users enter transaction details:
+### Embedded Component
 
-```js
-notabene.setTransaction({
-  transactionAsset: 'ETH',
-  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  transactionAmount: '2000000000',
-});
+This will let you embed the component into your existing withdrawal flow.
+
+Create an html element to contain the component:
+
+```html
+<div id="nb-withdrawal/>
 ```
 
-Once the widget determines the transaction is valid, it will call the `onValidStateChange` callback, to access the transaction details:
+Instantiate the withdrawal element and mount it using the id from above
 
 ```js
-const currentTransactionInfo = notabene.tx;
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+withdrawal.mount('#nb-withdrawal');
 ```
 
-### Supported asset formats
+The simplest way to get the result is to use:
 
-- `USDC` the simple asset code passed as a `string`, in case different chain (polygon) -> `USDC-POLY`
-- `CAIP19` format
-  ```js
-  {
-    caip19: 'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'; // for USDC
-  }
-  ```
-- `coingeckoId` and `network` format
-  ```js
-  {
-    coingeckoId: "usd-coin",
-    network: "ethereum"
+```js
+try {
+  const { valid, value, txCreate, ivms101, proof } =
+    await withdrawal.completion();
+  if (valid) {
+    // Submit result to your backend
   }
-  ```
+} catch (e) {
+  console.error(e);
+}
+```
 
----
+#### Dynamic updates
 
-### Re-rendering
+To update the component as users enter transaction details:
+
+```js
+withdrawal.update({
+  asset: 'ETH',
+  destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
+  amountDecimal: 1.12,
+});
+```
 
-**WARNING:** this shouldn't be used often, if you need to change the transaction's initial fields call `setTransaction` again. (This should be used only for tearing down the component).
+To be notified once the validation is completed so you can submit the withdrawal to your back end:
 
-The container of the widget must be in the DOM before calling `destroyWidget` or `renderWidget`.
+```js
+withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
+```
 
-If you need to close and re-render the widget, call the `destroyWidget` method like so:
+To be notified of any validation errors use:
 
 ```js
-// Will remove the widget
-notabene.destroyWidget();
-// Will re-render the widget
-notabene.renderWidget();
+withdrawal.on('error',error => ...)
 ```
 
-Calling the `renderWidget` methods without destroying it first will not work.
+Calling `on` returns a function that will allow you to cleanly unsubscribe.
 
----
+```js
+const unsubscribe = withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
+
+// Clean up
+unsubscribe()
 
-### Error handling
+```
 
-If any error occurs, the `onError` function from the Notabene instance will be triggered. The `error` passed as argument contains a `data` property that has the following type `ErrorData`.
+### Modal
 
-> ⚠️ **Note**: These errors are mainly used for debugging internal issues while implementing the widget. They are not meant to be shown directly to the end user.
+All components support being opened in a modal using `openModal()`, which returns a promise.
 
 ```js
-type ErrorData = {
-  title: string;
-  detail: string;
-  code: number;
-  type: string;
-};
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+try {
+  const { valid, value, txCreate, ivms101, proof } =
+    await withdrawal.openModal();
+  if (valid) {
+    // Submit result to your backend
+  }
+} catch (e) {
+  console.error(e);
+}
+```
 
-const notabene = new Notabene({
-  ...,
-  onError: (err) => {
-    const errorData = err.data;
 
-    // Do something
-  },
+### 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.
+
+```js
+const withdrawal = notabene.createWithdrawalAssist(tx, options, {
+  callback: /// a serverside backend url
+  redirectUri: // URI of website or mobile app to redirect user to after completion
 });
-```
 
-**Notabene Internal Errors**
+// NodeJS redirect. Link also works in an email.
+res.redirect(withdrawal.url);
+```
 
-Type | Code | Title | Detail
--- | -- | -- | --
-`BAD_REQUEST` | `400` | `Bad Request` | `NotabeneBadRequest: ...`
-`TRANSACTION_INVALID` | `400` | `Transaction Invalid` | `NotabeneTransactionInvalid: ...`
-`TOKEN_INVALID` | `401` | `Token Invalid` | `NotabeneTokenInvalid: ...`
-`ASSET_NOT_SUPPORTED` | `404` | `Asset Not Supported` | `NotabeneAssetNotSupported: ...`
-`SERVICE_UNAVAILABLE` | `500` | `Service Unavailable` | `NotabeneServiceUnavailable: ...`
-`WALLET_CONNECTED_FAILED` | `500` | `Wallet Connection Failed` | `NotabeneWalletConnectionFailed: ...`
-`WALLET_NOT_SUPPORTED` | `501` | `Wallet Not Supported` | `NotabeneWalletNotSupported: ...`
+Bear in mind that this is a full screen view for your users.
 
-## Customization
+The two parameters that should be configured are:
 
-### Functionality
+- `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.
 
-`transactionTypeAllowed`: `ALL` | `VASP_2_VASP_ONLY` | `SELF_TRANSACTION_ONLY`
+**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.
 
-For limiting the type of transaction destinations you can pass.
 
-`ALL`: All transaction destinations are allowed. (DEFAULT)
-`VASP_2_VASP_ONLY`: Only transaction destinations that are VASPs are allowed.
-`SELF_TRANSACTION_ONLY`: Only transaction destinations that the originator owns are allowed.
+## Components
 
----
+## Assisted Withdrawal
 
-`nonCustodialDeclarationType`: `SIGNATURE` | `DECLARATION`
+The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
 
-For deciding which ownership proof type you want to use.
+```js
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  assetPrice: {
+    currency: 'USD', // ISO currency code
+    price: 1700.12, // Asset price
+  }
+});
+```
 
-`SIGNATURE`: The ownership proof will be signed by the originator using a wallet. (DEFAULT)
-`DECLARATION`: The ownership proof will be declared by the originator using a checkbox.
+### Parameters
 
----
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
+- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
+- `amountDecimal`: The amount to transfer in decimal format. See [Transaction Amount](#transaction-amount)
+- `assetPrice`: Optional price information in a fiat currency. See [Asset Price](#asset-price)
 
-`counterpartyManualEntry`: `TRUE` | `FALSE`
+If any of the required parameters are missing the component will just show the Notabene badge.
 
-For deciding if you would like to allow your customer to provide a manual counterparty vasp name in the counterparty field.
+### Configuration Options
 
-### Pass the variables in the configuration
+Include configuration Options as a second optional parameter:
 
 ```js
-const notabene = new Notabene({
-    vaspDID: 'did:ethr:0x94c38fd29ef36f5cb2f7bc771f9d5bd9f7d05f27',
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    allowedTransactionTypes: 'VASP_2_VASP_ONLY',
-    nonCustodialDeclarationType: 'DECLARATION',
+const withdrawal = notabene.createWithdrawalAssist({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  assetPrice: {
+    currency: 'USD', // ISO currency code
+    price: 1700.12, // Asset price
+  }
+}, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
 });
 ```
 
----
-
-### Theme
+See [Transaction Options](#transaction-options)
 
-Pass a `theme` object when creating an instance
+## Connect Wallet
 
-Here you can pass configuration which will customize the styles of the widget to meet your brand needs, all values are optional.
+The Connect Wallet component helps you collect and verify the address of your users self-hosted wallet in one go.
 
 ```js
-{
-  primaryColor: '#fff',
-  secondaryColor: '#fff',
-  primaryFontColor: '#fff',
-  secondaryFontColor: '#fff',
-  backgroundColor: '#fff',
-  fontFamily: Arial,
-  logo: {LOGO_URL},
-  mode: 'dark', // default: 'light'
-
-  // If you are using the Signature flow, here is the full list of custom theme that can be applied to the WalletConnect Modal.
-  '--w3m-font-family',
-  '--w3m-font-feature-settings',
-  '--w3m-overlay-background-color',
-  '--w3m-overlay-backdrop-filter',
-  '--w3m-z-index',
-  '--w3m-accent-color',
-  '--w3m-accent-fill-color',
-  '--w3m-background-color',
-  '--w3m-background-image-url',
-  '--w3m-logo-image-url',
-  '--w3m-background-border-radius',
-  '--w3m-container-border-radius',
-  '--w3m-wallet-icon-border-radius',
-  '--w3m-wallet-icon-large-border-radius',
-  '--w3m-wallet-icon-small-border-radius',
-  '--w3m-input-border-radius',
-  '--w3m-notification-border-radius',
-  '--w3m-button-border-radius',
-  '--w3m-secondary-button-border-radius',
-  '--w3m-icon-button-border-radius',
-  '--w3m-button-hover-highlight-border-radius',
-}
+const connect = notabene.createConnectWallet({
+  asset: 'ETH'
+});
+
+const { proof, txCreate } = await connect.openModal()
 ```
 
-To get a list of supported fonts, visit [https://fonts.google.com/](https://fonts.google.com/)
+### Parameters
 
-To get more details about the WalletConnect theme variables, visit [General style variables](https://docs.walletconnect.com/2.0/web/web3modal/react/wagmi/theming#general-style-variables).
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
 
----
+### Configuration Options
 
-### Dictionary
+Include configuration Options as a second optional parameter:
 
-Pass a `dictionary` object mapping in text in the widget to your own language, for example:
+```js
+const connect = notabene.createConnectWallet({
+    asset: 'ETH',
+  }, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
+});
+```
 
-To replace `Loading...` with `Cargando...`
+## Deposit Request
+
+The Deposit Request lets your customers request deposits that are fully Travel Rule compliant.
 
 ```js
-{
-  'Loading...': 'Cargando...',
-}
+const withdrawal = notabene.createDepositRequest({
+  asset: 'ETH',
+  destination: '0x...',
+  amountDecimal: 1.23,
+  customer: {
+    name: "John Smith"
+  }
+});
 ```
 
-###### The property name must be the same as the text in the widget, for it to be replaced
+### Parameters
+
+- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
+- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
+- `amountDecimal`: Optional amount to deposit in decimal format. See [Transaction Amount](#transaction-amount)
+- `customer`: Optional Customer object containing their name
+
+If any of the required parameters are missing the component will just show the Notabene badge.
 
 ---
 
-### Fields Properties
+## Error handling
 
-Possible fields customization support:
+If any error occurs, the `error` event is passed containing a message.
 
-| field name               | `forceDisplay` | `optional` | description                                             |
-| ------------------------ | -------------- | ---------- | ------------------------------------------------------- |
-| `counterparty`           | --             | ☑️         | Counterparty VASP or Wallet (destination or originator) |
-| `dateAndPlaceOfBirth`    | ☑️             | --         | Recipient (or Sender) Date and Place of Birth           |
-| `geographicAddress`      | ☑️             | ☑️          | Recipient (or Sender) Address                           |
-| `firstName`              | ☑️             | --         | Recipient (or Sender) First name                        |
-| `name`                   | ☑️             | --         | Recipient (or Sender) Last Name / Company Name          |
-| `nationalIdentification` | ☑️             | --️         | Recipient (or Sender) National Identification           |
-| `country`                | ☑️             | ☑️          | Recipient (or Sender) Country of Residence (for natural person) / Country of Registration (for legal person)           |
+```ts
+withdrawal.on('error', {message} => ...)
+```
 
-**Field Options**
+## Transaction parameters
 
-- **forceDisplay** - Force a field that is not required by your jurisdiction to be displayed - defaults to **false**
-- **optional** - Bypass the jurisdiction rules validation for that specific field - defaults to **false**
+### Asset specification
 
-```js
-{
-  counterparty: {
-    optional: true;
+The `asset` field the following types of assets specified:
+
+- `notabene_asset` code passed as a`string`. See [Notabene Assets Service](https://devx.notabene.id/docs/coins-decimals#assets-service-api).
+- [CAIP-19](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-19.md_) is a chain agnostic format allows you to support the widest amount of assets and blockchains including NFTs.
+- [DTI](https://www.iso.org/standard/80601.html) is the ISO Digital Token Identifier format. See [DTI registry](https://dtif.org/registry-search/) for supported tokens.
+
+### Transaction amount
+
+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
+
+Specify the beneficiary address as `destination` using one of the following formats:
+
+- [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md_) is a chain agnostic format allows you to specify the specific blockchain and address
+- [EIP-3770](https://eips.ethereum.org/EIPS/eip-3770) EVM URI
+- [BIP-21](https://en.bitcoin.it/wiki/BIP_0021) Bitcoin URI
+- Native blockchain address
+
+### Asset Price
+
+The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this:
+
+```ts
+assetPrice: {
+  currency: 'USD', // ISO currency code
+  price: 1700.12, // Asset price
+};
+```
+
+
+## Configuration
+
+### Transaction Options
+
+Some components can be configured using an optional [TransactionOptions](./docs/types/interfaces/TransactionOptions.md) object.
+
+The following shows the full set of options in typescript:
+
+```ts
+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']
+    deminimis: {
+      threshold: 1000,
+      currency: 'EUR',
+      proofTypes: [ProofTypes.SelfDeclaration]
+    }
   },
-  geographicAddress: {
-    forceDisplay: true,
-    optional: true;
+  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
+    },
+    hide: [ValidationSections.ASSET, ValidationSections.DESTINATION] // Don't show specific sections of component
   },
-}
+};
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
 ```
 
----
+The options can additionally be updated dynamically with the `update()` function.
 
-**_Beneficiary Details_ [DEPRECATED]**
+```js
+withdrawal.update({
+  asset: 'ETH',
+  destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
+  amountDecimal: 1.12,
+}, {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      amountSubunits: '12344',
+      timeout: 86440,
+    }
+  }
+});
+```
 
-You can require specific beneficiary fields that are not required by your jurisdiction.
+### Common use cases
 
-Possible fields:
+#### Only allow first party transactions
 
-- `beneficiaryName` - Recipient Name
-- `beneficiaryGeographicAddress` - Recipient Address
-- `beneficiaryNationalIdentification` - Recipient National Identification
-- `beneficiaryDateAndPlaceOfBirth` - Recipient Date and Place of Birth
+```ts
+const firstParty: TransactionOptions = {
+  allowedCounterpartyTypes: [
+    PersonType.SELF, // JS: 'self'
+  ],
+};
+```
 
-```js
-beneficiaryDetails: [
-  'benficiaryName',
-  'beneficiaryGeographicAddress',
-  'beneficiaryNationalIdentification',
-  'beneficiaryDateAndPlaceOfBirth',
-];
+#### Only VASP to VASP transactions
+
+```ts
+const vasp2vasp: TransactionOptions = {
+  allowedAgentTypes: [AgentType.VASP], // js ['VASP']
+};
 ```
 
----
+#### Only Self-hosted wallet transactions
 
-### Fallbacks
+```ts
+const options: TransactionOptions = {
+  allowedAgentTypes: [AgentType.PRIVATE], // js ['WALLET']
+};
+```
 
-Fallbacks are custom options provided when desired outcome is not achieved
+### Configuring ownership proofs
 
-Possible options and actions:
+By default components support message signing proofs.
 
-- `WALLET_NOT_SUPPORTED` - Performs one of the following options when wallet is not supported
-  - `DECLARATION` - Falls back to the self declaration flow
-  - `REJECT` - Rejects the transaction and throws an error
-    - The error that will be thrown here will have the following structure
-      ```js
-        {
-          "type": "WALLET_NOT_SUPPORTED",
-          "title": "Wallet Not Supported",
-          "status": 501,
-          "detail": "We don't support the wallet for the provided asset"
-        }
-      ```
+#### Supporting Micro Transactions (aka Satoshi tests)
 
-```js
-fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
+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.
+
+```ts
+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']
+  },
+};
 ```
----
 
-Finally you pass the configuration to a Notabene instance:
+Notabene does not currently verify these tests automatically as you likely already have the infrastructure to do so.
 
-```js
-const notabene = new Notabene({
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    theme: {THEME},
-    dictionary: {DICTIONARY},
-    fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
-});
+You will receive a response back from the component containing a proof object. For MicroTransfers it will look like this:
+
+```ts
+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
+}
 ```
----
 
-### Opt-In Features
+#### Fallback Proof Options
 
-```js
-const notabene = new Notabene({
-    widget: 'https://beta-widget.notabene.id',
-    container: '#container',
-    authToken: '{CUSTOMER_TOKEN}'
-    theme: {THEME},
-    dictionary: {DICTIONARY},
-    optInFeatures: ['REUSE_ADDRESS_OWNERSHIP_PROOF']
-});
+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:
+
+```ts
+const options: TransactionOptions = {
+  proofs: {
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
+  },
+};
 ```
 
-**Available Opt-In Features**
+The two options are:
 
-- `REUSE_ADDRESS_OWNERSHIP_PROOF`: For a given unique customer (identified by the `customerRef` from the customer token used) + unique wallet address, the widget would not ask for data collection if the customer previously verified the address ownership in a previous first party self-hosted transfer.
+- `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
 
-### Transaction Custom Asset Price
+### Counterparty Field Properties
 
-To use your own asset price as fallback in case an asset is not supported by Notabene, you can provide a `customAssetPrice` object that will be used instead to render the widget with the correct jurisdiction requirements.
+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.
 
-```js
-notabene.setTransaction({
-  transactionAsset: 'ASSET_UNSUPPORTED_FROM_NOTABENE',
-  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  transactionAmount: '2000000000',
-  customAssetPrice: {
-      priceUSD: 1700.12, // Asset price in USD
-      decimals: 10 // Decimals used for the given transactionAmount
-    };
-});
+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
+
+Eg:
+
+```ts
+{
+  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
+
+```ts
+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 |  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                       |
+
+## Locales
+
+See [locales](src/locales.ts) for the list of supported locales.
+
 ## [License](LICENSE.md)
 
-BSD 3-Clause © Notabene Inc.
+MIT © Notabene Inc.