@notabene/javascript-sdk 1.34.0 → 2.0.0-next.11

package/README.md

@@ -5,37 +5,45 @@
 
 # JavaScript SDK
 
-[![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)
+[![pipeline status](https://gitlab.com/notabene/open-source/javascript-sdk/badges/v2/pipeline.svg)](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/v2)
 
-This library is the JavaScript SDK for loading the widget on a frontend.
+This library is the JavaScript SDK for loading the Notabene UX components in the front-end.
 
-[Documentation](https://devx.notabene.id/docs/widget-v2) •
+[Documentation](https://devx.notabene.id/docs/embedded=ux)
 [Installation](#installation)
 
 </div>
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Supported asset formats](#supported-asset-formats)
-  - [Re-rendering](#re-rendering)
+- [JavaScript SDK](#javascript-sdk)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Authentication](#authentication)
+  - [Assisted Withdrawal](#assisted-withdrawal)
+    - [Embedded Component](#embedded-component)
+      - [Dynamic updates](#dynamic-updates)
+    - [Linked Component](#linked-component)
+  - [Transaction parameters](#transaction-parameters)
+    - [Asset specification](#asset-specification)
+    - [Transaction amount specification](#transaction-amount-specification)
+    - [Destination address](#destination-address)
+    - [Destination address](#destination-address-1)
+  - [Connect Wallet](#connect-wallet)
+    - [Asset specification](#asset-specification-1)
+    - [Modal](#modal)
+    - [Linked Component](#linked-component-1)
   - [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)
-- [License](#license)
+  - [Transaction Options](#transaction-options)
+    - [Common use cases](#common-use-cases)
+    - [Configuring ownership proofs](#configuring-ownership-proofs)
+    - [Counterparty Field Properties](#counterparty-field-properties)
+  - [License](#license)
 
 ## Installation
 
 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:
@@ -57,348 +65,398 @@ Use the [customer token endpoint](https://devx.notabene.id/docs/customertoken) w
 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',
   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
 });
 ```
 
-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');
+## Assisted Withdrawal
+
+The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
+
+### Embedded Component
 
-// 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');
+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/>
 ```
 
-To update the widget as users enter transaction details:
+Instantiate the withdrawal element and mount it using the id from above
 
 ```js
-notabene.setTransaction({
-  transactionAsset: 'ETH',
-  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
-  transactionAmount: '2000000000',
-});
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
+withdrawal.mount("nb-withdrawal");
 ```
 
-Once the widget determines the transaction is valid, it will call the `onValidStateChange` callback, to access the transaction details:
+The simplest way to get the result is to use:
 
 ```js
-const currentTransactionInfo = notabene.tx;
+try {
+ const {valid, ivms101} = await withdrawal.completion()
+ if (valid) {
+  // Submit result to your backend
+ }
+} catch (e) {
+ console.error(e)
+}
 ```
 
-### Supported asset formats
-
-- `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"
-  }
-  ```
+#### Dynamic updates
 
----
+To update the component as users enter transaction details:
 
-### Re-rendering
+```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, txCreate } => ...)
+```
 
-If you need to close and re-render the widget, call the `destroyWidget` method like so:
+To be notified of any 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.
+### 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.
 
-### Error handling
+```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
+});
 
-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`.
+// NodeJS redirect. Link also works in an email.
+res.redirect(withdrawal.url);
+```
 
-> ⚠️ **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.
+Bear in mind that this is a full screen view for your users.
 
-```js
-type ErrorData = {
-  title: string;
-  detail: string;
-  code: number;
-  type: string;
-};
+The two parameters that should be configured are:
 
-const notabene = new Notabene({
-  ...,
-  onError: (err) => {
-    const errorData = err.data;
+- `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.
 
-    // Do something
-  },
-});
-```
+**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.
 
-**Notabene Internal Errors**
+## Transaction parameters
 
-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: ...`
+### Asset specification
 
-## Customization
+The `asset` field the following types of assets specified:
 
-### Functionality
+- `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.
 
-`transactionTypeAllowed`: `ALL` | `VASP_2_VASP_ONLY` | `SELF_TRANSACTION_ONLY`
+### Transaction amount specification
 
-For limiting the type of transaction destinations you can pass.
+Use one of the following
 
-`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.
+- `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
 
-`nonCustodialDeclarationType`: `SIGNATURE` | `DECLARATION`
+Specify the beneficiary address as `destination` using one of the following formats:
 
-For deciding which ownership proof type you want to use.
+- [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
 
-`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.
+### Destination address
 
-### Pass the variables in the configuration
+The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this:
 
-```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',
-});
+```ts
+assetPrice: {
+  currency: 'USD', // ISO currency code
+  price: 1700.12, // Asset price
+};
 ```
 
----
+## Connect Wallet
 
-### Theme
+The Connect Wallet component helps you collect and verify the address of your users self-hosted wallet in one go.
 
-Pass a `theme` object when creating an instance
+### Asset specification
 
-Here you can pass configuration which will customize the styles of the widget to meet your brand needs, all values are optional.
+The `asset` field the following types of assets specified:
 
-```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',
-}
-```
+- `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.
 
-To get a list of supported fonts, visit [https://fonts.google.com/](https://fonts.google.com/)
 
-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).
+### Modal
 
----
+Instantiate the modal and open it
 
-### Dictionary
+```js
+const connect = notabene.createConnectWallet({asset:'ETH'}, options);
+const {valid, ivms101, proof } = await connect.openModal();
+```
 
-Pass a `dictionary` object mapping in text in the widget to your own language, for example:
+### Linked Component
 
-To replace `Loading...` with `Cargando...`
+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
-{
-  'Loading...': 'Cargando...',
-}
+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);
 ```
 
-###### The property name must be the same as the text in the widget, for it to be replaced
+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.
 
 ---
 
-### Fields Properties
+## Error handling
+
+If any error occurs, the `error` event is passed containing a message.
 
-Possible fields customization support:
+```ts
+withdrawal.on('error', {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)           |
+## Transaction Options
 
-**Field Options**
+All components can be configured using an optional [TransactionOptions](./docs/interfaces/TransactionOptions.md) object.
 
-- **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**
+The following shows the full set of options in typescript:
 
-```js
-{
-  counterparty: {
-    optional: true;
+```ts
+const options: TransactionOptions = {
+  proofs: {
+    microTransfer: {
+      destination: '0x...',
+      timeout: 86440,
+    },
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration],
   },
-  geographicAddress: {
-    forceDisplay: true,
-    optional: true;
+  allowedAgentTypes: [AgentType.PRIVATE, AgentType.VASP],
+  allowedCounterpartyTypes: [
+    PersonType.LEGAL,
+    PersonType.NATURAL,
+    PersonType.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,
+    },
   },
-}
+};
+const withdrawal = notabene.createWithdrawalAssist(tx, options);
 ```
 
----
+### Common use cases
 
-**_Beneficiary Details_ [DEPRECATED]**
+#### Only allow first party transactions
+
+```ts
+const firstParty: TransactionOptions = {
+  allowedCounterpartyTypes: [
+    PersonType.SELF,
+  ],
+};
+```
 
-You can require specific beneficiary fields that are not required by your jurisdiction.
+#### Only VASP to VASP transactions
 
-Possible fields:
+```ts
+const vasp2vasp: TransactionOptions = {
+  allowedAgentTypes: [AgentType.VASP],
+};
+```
 
-- `beneficiaryName` - Recipient Name
-- `beneficiaryGeographicAddress` - Recipient Address
-- `beneficiaryNationalIdentification` - Recipient National Identification
-- `beneficiaryDateAndPlaceOfBirth` - Recipient Date and Place of Birth
+#### Only Self-hosted wallet transactions
 
-```js
-beneficiaryDetails: [
-  'benficiaryName',
-  'beneficiaryGeographicAddress',
-  'beneficiaryNationalIdentification',
-  'beneficiaryDateAndPlaceOfBirth',
-];
+```ts
+const options: TransactionOptions = {
+  allowedAgentTypes: [AgentType.PRIVATE],
+};
 ```
 
----
+### Configuring ownership proofs
 
-### Fallbacks
+By default components support message signing proofs.
 
-Fallbacks are custom options provided when desired outcome is not achieved
 
-Possible options and actions:
+#### Supporting Micro Transactions (aka Satoshi tests)
 
-- `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"
-        }
-      ```
+You can support Micro Transfers (aka Satoshi tests) by adding a deposit address for the test.
 
-```js
-fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
+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...',
+      timeout: 86440, // Optional timeout in seconds, which is displayed to the user
+    },
+    fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration],
+  }
+}
 ```
----
 
-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],
+  }
+}
 ```
+The two options are:
 
-**Available Opt-In Features**
+- `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
 
-- `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.
+### Counterparty Field Properties
 
-### Transaction Custom Asset Price
+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.
 
-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.
+We recommend working closely with your compliance team for this. Bearing in mind that different jurisdictions have different rules.
 
-```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
-    };
-});
+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:
+```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 | 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                       |
+
 
 ## [License](LICENSE.md)
 
-BSD 3-Clause © Notabene Inc.
+MIT © Notabene Inc.