@notabene/javascript-sdk 2.0.0-next.9 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/README.md +477 -111
- package/dist/js/notabene.js +1 -0
- package/dist/notabene.cjs +1 -1
- package/dist/notabene.js +286 -110
- package/package.json +34 -25
- package/src/__tests__/notabene.test.ts +113 -2
- package/src/arbitraries.ts +0 -13
- package/src/components/EmbeddedComponent.ts +125 -63
- package/src/components/__tests__/EmbeddedComponent.test.ts +402 -32
- package/src/ivms/types.ts +177 -140
- package/src/locales.ts +48 -0
- package/src/notabene.ts +199 -63
- package/src/types.ts +773 -150
- package/src/utils/MessageEventManager.ts +70 -9
- package/src/utils/__tests__/MessageEventManager.test.ts +29 -5
- package/src/utils/__tests__/urls.test.ts +112 -0
- package/src/utils/arbitraries.ts +219 -1
- package/src/utils/urls.ts +30 -5
- package/dist/notabene.d.ts +0 -780
- package/dist/tsdoc-metadata.json +0 -11
package/README.md
CHANGED
|
@@ -2,54 +2,104 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://assets-global.website-files.com/5e68f0772de982756aa8c1a4/5eee5fb470215e6ecdc34b94_Full_transparent_black_1280x413.svg" height=50>
|
|
4
4
|
<br>
|
|
5
|
-
|
|
6
|
-
# JavaScript SDK
|
|
5
|
+
# Notabene SafeConnect Components JavaScript SDK
|
|
7
6
|
|
|
8
7
|
[](https://gitlab.com/notabene/open-source/javascript-sdk/-/commits/master)
|
|
9
|
-
[](https://www.npmjs.com/package/@notabene/javascript-sdk)
|
|
9
|
+
[](https://www.npmjs.com/package/@notabene/javascript-sdk)
|
|
10
|
+
[](https://bundlephobia.com/package/@notabene/javascript-sdk)
|
|
11
|
+
[](https://www.npmjs.com/package/@notabene/javascript-sdk)
|
|
12
|
+
[](https://gitlab.com/notabene/open-source/javascript-sdk/-/blob/main/LICENSE.md)
|
|
13
|
+
[](https://libraries.io/npm/@notabene%2Fjavascript-sdk)
|
|
10
14
|
|
|
11
15
|
This library is the JavaScript SDK for loading the Notabene UX components in the front-end.
|
|
12
16
|
|
|
13
|
-
[Documentation](https://devx.notabene.id/docs/embedded=ux)
|
|
14
|
-
[Installation](#installation)
|
|
17
|
+
[Additional Documentation](https://devx.notabene.id/docs/embedded=ux)
|
|
15
18
|
|
|
16
19
|
</div>
|
|
17
20
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
21
|
+
## Table of Contents
|
|
22
|
+
|
|
23
|
+
- [Installation](#installation)
|
|
24
|
+
- [Quick Start](#quick-start)
|
|
25
|
+
- [Core Concepts](#core-concepts)
|
|
26
|
+
- [Authentication](#authentication)
|
|
27
|
+
- [General Component Usage](#general-component-usage)
|
|
28
|
+
- [Embedded Component](#embedded-component)
|
|
29
|
+
- [Dynamic updates](#dynamic-updates)
|
|
30
|
+
- [Modal](#modal)
|
|
31
|
+
- [Linked Component](#linked-component)
|
|
32
|
+
- [Components](#components)
|
|
22
33
|
- [Assisted Withdrawal](#assisted-withdrawal)
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
34
|
+
- [Connect Wallet](#connect-wallet)
|
|
35
|
+
- [Deposit Request](#deposit-request)
|
|
36
|
+
- [Error handling](#error-handling)
|
|
37
|
+
- [Transaction parameters](#transaction-parameters)
|
|
38
|
+
- [Asset specification](#asset-specification)
|
|
39
|
+
- [Transaction amount](#transaction-amount)
|
|
40
|
+
- [Destination](#destination)
|
|
41
|
+
- [Asset Price](#asset-price)
|
|
42
|
+
- [Configuration](#configuration)
|
|
43
|
+
- [Transaction Options](#transaction-options)
|
|
44
|
+
- [Common use cases](#common-use-cases)
|
|
45
|
+
- [Configuring ownership proofs](#configuring-ownership-proofs)
|
|
46
|
+
- [Counterparty Field Properties](#counterparty-field-properties)
|
|
47
|
+
- [Locales](#locales)
|
|
48
|
+
- [License](#license)
|
|
37
49
|
|
|
38
50
|
## Installation
|
|
39
51
|
|
|
40
52
|
There are two options for loading the Notabene SDK:
|
|
41
53
|
|
|
42
54
|
```bash
|
|
43
|
-
<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@
|
|
55
|
+
<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@next/dist/notabene.js"></script>
|
|
44
56
|
```
|
|
45
57
|
|
|
46
58
|
Or installing the library:
|
|
47
59
|
|
|
60
|
+
Using Yarn:
|
|
61
|
+
|
|
48
62
|
```bash
|
|
49
63
|
yarn add @notabene/javascript-sdk
|
|
50
64
|
```
|
|
51
65
|
|
|
52
|
-
|
|
66
|
+
Using NPM:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npm install @notabene/javascript-sdk
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
If you installed the library into your project, you can import it into your project:
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
import Notabene from '@notabene/javascript-sdk';
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Quick Start
|
|
79
|
+
|
|
80
|
+
```js
|
|
81
|
+
// 1. Create Notabene instance
|
|
82
|
+
const notabene = new Notabene({
|
|
83
|
+
nodeUrl: 'https://api.notabene.id',
|
|
84
|
+
authToken: 'YOUR_CUSTOMER_TOKEN',
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
// 2. Create and mount withdrawal component
|
|
88
|
+
const withdrawal = notabene.createWithdrawalAssist({
|
|
89
|
+
asset: 'ETH',
|
|
90
|
+
destination: '0x1234...',
|
|
91
|
+
amountDecimal: 1.0,
|
|
92
|
+
});
|
|
93
|
+
withdrawal.mount('#nb-withdrawal');
|
|
94
|
+
|
|
95
|
+
// 3. Handle completion
|
|
96
|
+
const { valid, value, txCreate } = await withdrawal.completion();
|
|
97
|
+
if (valid) {
|
|
98
|
+
// Submit to your backend
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Core Concepts
|
|
53
103
|
|
|
54
104
|
### Authentication
|
|
55
105
|
|
|
@@ -62,19 +112,18 @@ Use the [customer token endpoint](https://devx.notabene.id/docs/customertoken) w
|
|
|
62
112
|
Create a new Notabene instance:
|
|
63
113
|
|
|
64
114
|
```js
|
|
65
|
-
|
|
66
115
|
const notabene = new Notabene({
|
|
67
|
-
nodeUrl: 'https://api.notabene.id',
|
|
116
|
+
nodeUrl: 'https://api.notabene.id', // use `https://api.notabene.dev` for testing
|
|
68
117
|
authToken: '{CUSTOMER_TOKEN}',
|
|
69
|
-
locale: 'de' // default locale
|
|
118
|
+
locale: 'de', // default locale = `en`
|
|
70
119
|
});
|
|
71
120
|
```
|
|
72
121
|
|
|
73
122
|
Use the same `nodeUrl` that you use to interact with the Notabene API.
|
|
74
123
|
|
|
75
|
-
##
|
|
124
|
+
## General Component Usage
|
|
76
125
|
|
|
77
|
-
|
|
126
|
+
Each component can be used in various ways depending on your use case.
|
|
78
127
|
|
|
79
128
|
### Embedded Component
|
|
80
129
|
|
|
@@ -90,19 +139,20 @@ Instantiate the withdrawal element and mount it using the id from above
|
|
|
90
139
|
|
|
91
140
|
```js
|
|
92
141
|
const withdrawal = notabene.createWithdrawalAssist(tx, options);
|
|
93
|
-
withdrawal.mount(
|
|
142
|
+
withdrawal.mount('#nb-withdrawal');
|
|
94
143
|
```
|
|
95
144
|
|
|
96
145
|
The simplest way to get the result is to use:
|
|
97
146
|
|
|
98
147
|
```js
|
|
99
148
|
try {
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
149
|
+
const { valid, value, txCreate, ivms101, proof } =
|
|
150
|
+
await withdrawal.completion();
|
|
151
|
+
if (valid) {
|
|
152
|
+
// Submit result to your backend
|
|
153
|
+
}
|
|
104
154
|
} catch (e) {
|
|
105
|
-
|
|
155
|
+
console.error(e);
|
|
106
156
|
}
|
|
107
157
|
```
|
|
108
158
|
|
|
@@ -114,22 +164,49 @@ To update the component as users enter transaction details:
|
|
|
114
164
|
withdrawal.update({
|
|
115
165
|
asset: 'ETH',
|
|
116
166
|
destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
|
|
117
|
-
amountDecimal: 1.12
|
|
167
|
+
amountDecimal: 1.12,
|
|
118
168
|
});
|
|
119
169
|
```
|
|
120
170
|
|
|
121
171
|
To be notified once the validation is completed so you can submit the withdrawal to your back end:
|
|
122
172
|
|
|
123
173
|
```js
|
|
124
|
-
withdrawal.on('
|
|
174
|
+
withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
|
|
125
175
|
```
|
|
126
176
|
|
|
127
|
-
To be notified of any errors use:
|
|
177
|
+
To be notified of any validation errors use:
|
|
128
178
|
|
|
129
179
|
```js
|
|
130
180
|
withdrawal.on('error',error => ...)
|
|
131
181
|
```
|
|
132
182
|
|
|
183
|
+
Calling `on` returns a function that will allow you to cleanly unsubscribe.
|
|
184
|
+
|
|
185
|
+
```js
|
|
186
|
+
const unsubscribe = withdrawal.on('complete', { valid, value, txCreate, ivms101, proof } => ...)
|
|
187
|
+
|
|
188
|
+
// Clean up
|
|
189
|
+
unsubscribe()
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Modal
|
|
194
|
+
|
|
195
|
+
All components support being opened in a modal using `openModal()`, which returns a promise.
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
const withdrawal = notabene.createWithdrawalAssist(tx, options);
|
|
199
|
+
try {
|
|
200
|
+
const { valid, value, txCreate, ivms101, proof } =
|
|
201
|
+
await withdrawal.openModal();
|
|
202
|
+
if (valid) {
|
|
203
|
+
// Submit result to your backend
|
|
204
|
+
}
|
|
205
|
+
} catch (e) {
|
|
206
|
+
console.error(e);
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
133
210
|
### Linked Component
|
|
134
211
|
|
|
135
212
|
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.
|
|
@@ -153,6 +230,133 @@ The two parameters that should be configured are:
|
|
|
153
230
|
|
|
154
231
|
**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.
|
|
155
232
|
|
|
233
|
+
## Components
|
|
234
|
+
|
|
235
|
+
## Assisted Withdrawal
|
|
236
|
+
|
|
237
|
+
The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.
|
|
238
|
+
|
|
239
|
+
```js
|
|
240
|
+
const withdrawal = notabene.createWithdrawalAssist({
|
|
241
|
+
asset: 'ETH',
|
|
242
|
+
destination: '0x...',
|
|
243
|
+
amountDecimal: 1.23,
|
|
244
|
+
assetPrice: {
|
|
245
|
+
currency: 'USD', // ISO currency code
|
|
246
|
+
price: 1700.12, // Asset price
|
|
247
|
+
},
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Parameters
|
|
252
|
+
|
|
253
|
+
- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
|
|
254
|
+
- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
|
|
255
|
+
- `amountDecimal`: The amount to transfer in decimal format. See [Transaction Amount](#transaction-amount)
|
|
256
|
+
- `assetPrice`: Optional price information in a fiat currency. See [Asset Price](#asset-price)
|
|
257
|
+
|
|
258
|
+
If any of the required parameters are missing the component will just show the Notabene badge.
|
|
259
|
+
|
|
260
|
+
### Configuration Options
|
|
261
|
+
|
|
262
|
+
Include configuration Options as a second optional parameter:
|
|
263
|
+
|
|
264
|
+
```js
|
|
265
|
+
const withdrawal = notabene.createWithdrawalAssist(
|
|
266
|
+
{
|
|
267
|
+
asset: 'ETH',
|
|
268
|
+
destination: '0x...',
|
|
269
|
+
amountDecimal: 1.23,
|
|
270
|
+
assetPrice: {
|
|
271
|
+
currency: 'USD', // ISO currency code
|
|
272
|
+
price: 1700.12, // Asset price
|
|
273
|
+
},
|
|
274
|
+
},
|
|
275
|
+
{
|
|
276
|
+
proofs: {
|
|
277
|
+
microTransfer: {
|
|
278
|
+
destination: '0x...',
|
|
279
|
+
amountSubunits: '12344',
|
|
280
|
+
timeout: 86440,
|
|
281
|
+
},
|
|
282
|
+
},
|
|
283
|
+
},
|
|
284
|
+
);
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
See [Transaction Options](#transaction-options)
|
|
288
|
+
|
|
289
|
+
## Connect Wallet
|
|
290
|
+
|
|
291
|
+
The Connect Wallet component helps you collect and verify the address of your users self-hosted wallet in one go.
|
|
292
|
+
|
|
293
|
+
```js
|
|
294
|
+
const connect = notabene.createConnectWallet({
|
|
295
|
+
asset: 'ETH',
|
|
296
|
+
});
|
|
297
|
+
|
|
298
|
+
const { proof, txCreate } = await connect.openModal();
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
### Parameters
|
|
302
|
+
|
|
303
|
+
- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
|
|
304
|
+
|
|
305
|
+
### Configuration Options
|
|
306
|
+
|
|
307
|
+
Include configuration Options as a second optional parameter:
|
|
308
|
+
|
|
309
|
+
```js
|
|
310
|
+
const connect = notabene.createConnectWallet(
|
|
311
|
+
{
|
|
312
|
+
asset: 'ETH',
|
|
313
|
+
},
|
|
314
|
+
{
|
|
315
|
+
proofs: {
|
|
316
|
+
microTransfer: {
|
|
317
|
+
destination: '0x...',
|
|
318
|
+
amountSubunits: '12344',
|
|
319
|
+
timeout: 86440,
|
|
320
|
+
},
|
|
321
|
+
},
|
|
322
|
+
},
|
|
323
|
+
);
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
## Deposit Request
|
|
327
|
+
|
|
328
|
+
The Deposit Request lets your customers request deposits that are fully Travel Rule compliant.
|
|
329
|
+
|
|
330
|
+
```js
|
|
331
|
+
const withdrawal = notabene.createDepositRequest({
|
|
332
|
+
asset: 'ETH',
|
|
333
|
+
destination: '0x...',
|
|
334
|
+
amountDecimal: 1.23,
|
|
335
|
+
customer: {
|
|
336
|
+
name: 'John Smith',
|
|
337
|
+
},
|
|
338
|
+
});
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
### Parameters
|
|
342
|
+
|
|
343
|
+
- `asset`: The cryptocurrency or token being transferred. See [Asset Specification](#asset-specification)
|
|
344
|
+
- `destination`: The destination or blockchain address for the withdrawal. See [Destination](#destination)
|
|
345
|
+
- `amountDecimal`: Optional amount to deposit in decimal format. See [Transaction Amount](#transaction-amount)
|
|
346
|
+
- `customer`: Optional Customer object containing their name
|
|
347
|
+
|
|
348
|
+
If any of the required parameters are missing the component will just show the Notabene badge.
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
## Error handling
|
|
353
|
+
|
|
354
|
+
If any error occurs, the `error` event is passed containing a message.
|
|
355
|
+
|
|
356
|
+
```ts
|
|
357
|
+
withdrawal.on('error', {message} => ...)
|
|
358
|
+
```
|
|
359
|
+
|
|
156
360
|
## Transaction parameters
|
|
157
361
|
|
|
158
362
|
### Asset specification
|
|
@@ -163,14 +367,13 @@ The `asset` field the following types of assets specified:
|
|
|
163
367
|
- [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.
|
|
164
368
|
- [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.
|
|
165
369
|
|
|
166
|
-
### Transaction amount
|
|
370
|
+
### Transaction amount
|
|
167
371
|
|
|
168
372
|
Use one of the following
|
|
169
373
|
|
|
170
374
|
- `amountDecimal` A number specifying the amount in decimal format. Eg. `amountDecimal=1.1` would mean 1.1 of for example BTC or ETH.
|
|
171
|
-
- `amountSubunits` A string specifying the amount in the native blockchain subunits eg Satoshi for Bitcoin or wei for Ethereum
|
|
172
375
|
|
|
173
|
-
### Destination
|
|
376
|
+
### Destination
|
|
174
377
|
|
|
175
378
|
Specify the beneficiary address as `destination` using one of the following formats:
|
|
176
379
|
|
|
@@ -179,108 +382,271 @@ Specify the beneficiary address as `destination` using one of the following form
|
|
|
179
382
|
- [BIP-21](https://en.bitcoin.it/wiki/BIP_0021) Bitcoin URI
|
|
180
383
|
- Native blockchain address
|
|
181
384
|
|
|
182
|
-
|
|
385
|
+
### Asset Price
|
|
183
386
|
|
|
184
|
-
|
|
387
|
+
The price of the asset is used to determine certain rules based on thresholds. We recommond you pass in your price like this:
|
|
388
|
+
|
|
389
|
+
```ts
|
|
390
|
+
assetPrice: {
|
|
391
|
+
currency: 'USD', // ISO currency code
|
|
392
|
+
price: 1700.12, // Asset price
|
|
393
|
+
};
|
|
394
|
+
```
|
|
185
395
|
|
|
186
|
-
|
|
396
|
+
## Configuration
|
|
397
|
+
|
|
398
|
+
### Transaction Options
|
|
399
|
+
|
|
400
|
+
Some components can be configured using an optional [TransactionOptions](./docs/types/interfaces/TransactionOptions.md) object.
|
|
401
|
+
|
|
402
|
+
The following shows the full set of options in typescript:
|
|
403
|
+
|
|
404
|
+
```ts
|
|
405
|
+
import Notabene, {
|
|
406
|
+
AgentType,
|
|
407
|
+
PersonType,
|
|
408
|
+
ProofTypes,
|
|
409
|
+
} from '@notabene/javascript-sdk';
|
|
410
|
+
|
|
411
|
+
const options: TransactionOptions = {
|
|
412
|
+
proofs: {
|
|
413
|
+
microTransfer: {
|
|
414
|
+
destination: '0x...',
|
|
415
|
+
amountSubunits: '12344',
|
|
416
|
+
timeout: 86440,
|
|
417
|
+
},
|
|
418
|
+
fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
|
|
419
|
+
deminimis: {
|
|
420
|
+
threshold: 1000,
|
|
421
|
+
currency: 'EUR',
|
|
422
|
+
proofTypes: [ProofTypes.SelfDeclaration],
|
|
423
|
+
},
|
|
424
|
+
},
|
|
425
|
+
allowedAgentTypes: [AgentType.PRIVATE, AgentType.VASP], // js ['WALLET','VASP']
|
|
426
|
+
allowedCounterpartyTypes: [
|
|
427
|
+
PersonType.LEGAL, // JS: 'legal'
|
|
428
|
+
PersonType.NATURAL, // JS: 'natural'
|
|
429
|
+
PersonType.SELF, // JS: 'self'
|
|
430
|
+
],
|
|
431
|
+
fields: {
|
|
432
|
+
naturalPerson: {
|
|
433
|
+
name: true, // Default true
|
|
434
|
+
website: { optional: true },
|
|
435
|
+
email: true,
|
|
436
|
+
phone: true,
|
|
437
|
+
geographicAddress: false,
|
|
438
|
+
nationalIdentification: false,
|
|
439
|
+
dateOfBirth: false,
|
|
440
|
+
placeOfBirth: false,
|
|
441
|
+
countryOfResidence: true,
|
|
442
|
+
},
|
|
443
|
+
legalPerson: {
|
|
444
|
+
name: true, // Default true
|
|
445
|
+
lei: true, // Default true
|
|
446
|
+
website: { optional: true }, // Default true
|
|
447
|
+
email: true,
|
|
448
|
+
phone: true,
|
|
449
|
+
geographicAddress: false,
|
|
450
|
+
nationalIdentification: false,
|
|
451
|
+
countryOfRegistration: true,
|
|
452
|
+
},
|
|
453
|
+
vasps: {
|
|
454
|
+
addUnknown: true, // Allow users to add a missing VASP - Defaults to false
|
|
455
|
+
onlyActive: true, // Only list active VASPs - Default false
|
|
456
|
+
},
|
|
457
|
+
hide: [ValidationSections.ASSET, ValidationSections.DESTINATION], // Don't show specific sections of component
|
|
458
|
+
},
|
|
459
|
+
};
|
|
460
|
+
const withdrawal = notabene.createWithdrawalAssist(tx, options);
|
|
461
|
+
```
|
|
187
462
|
|
|
188
|
-
|
|
463
|
+
The options can additionally be updated dynamically with the `update()` function.
|
|
189
464
|
|
|
190
465
|
```js
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
466
|
+
withdrawal.update(
|
|
467
|
+
{
|
|
468
|
+
asset: 'ETH',
|
|
469
|
+
destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
|
|
470
|
+
amountDecimal: 1.12,
|
|
471
|
+
},
|
|
472
|
+
{
|
|
473
|
+
proofs: {
|
|
474
|
+
microTransfer: {
|
|
475
|
+
destination: '0x...',
|
|
476
|
+
amountSubunits: '12344',
|
|
477
|
+
timeout: 86440,
|
|
478
|
+
},
|
|
479
|
+
},
|
|
480
|
+
},
|
|
481
|
+
);
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
### Common use cases
|
|
485
|
+
|
|
486
|
+
#### Only allow first party transactions
|
|
487
|
+
|
|
488
|
+
```ts
|
|
489
|
+
const firstParty: TransactionOptions = {
|
|
490
|
+
allowedCounterpartyTypes: [
|
|
491
|
+
PersonType.SELF, // JS: 'self'
|
|
492
|
+
],
|
|
196
493
|
};
|
|
494
|
+
```
|
|
197
495
|
|
|
198
|
-
|
|
199
|
-
...,
|
|
200
|
-
onError: (err) => {
|
|
201
|
-
const errorData = err.data;
|
|
496
|
+
#### Only VASP to VASP transactions
|
|
202
497
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
498
|
+
```ts
|
|
499
|
+
const vasp2vasp: TransactionOptions = {
|
|
500
|
+
allowedAgentTypes: [AgentType.VASP], // js ['VASP']
|
|
501
|
+
};
|
|
206
502
|
```
|
|
207
503
|
|
|
208
|
-
|
|
504
|
+
#### Only Self-hosted wallet transactions
|
|
505
|
+
|
|
506
|
+
```ts
|
|
507
|
+
const options: TransactionOptions = {
|
|
508
|
+
allowedAgentTypes: [AgentType.PRIVATE], // js ['WALLET']
|
|
509
|
+
};
|
|
510
|
+
```
|
|
209
511
|
|
|
210
|
-
|
|
211
|
-
-- | -- | -- | --
|
|
212
|
-
`BAD_REQUEST` | `400` | `Bad Request` | `NotabeneBadRequest: ...`
|
|
213
|
-
`TRANSACTION_INVALID` | `400` | `Transaction Invalid` | `NotabeneTransactionInvalid: ...`
|
|
214
|
-
`TOKEN_INVALID` | `401` | `Token Invalid` | `NotabeneTokenInvalid: ...`
|
|
215
|
-
`ASSET_NOT_SUPPORTED` | `404` | `Asset Not Supported` | `NotabeneAssetNotSupported: ...`
|
|
216
|
-
`SERVICE_UNAVAILABLE` | `500` | `Service Unavailable` | `NotabeneServiceUnavailable: ...`
|
|
217
|
-
`WALLET_CONNECTED_FAILED` | `500` | `Wallet Connection Failed` | `NotabeneWalletConnectionFailed: ...`
|
|
218
|
-
`WALLET_NOT_SUPPORTED` | `501` | `Wallet Not Supported` | `NotabeneWalletNotSupported: ...`
|
|
512
|
+
### Configuring ownership proofs
|
|
219
513
|
|
|
220
|
-
|
|
514
|
+
By default components support message signing proofs.
|
|
221
515
|
|
|
222
|
-
|
|
516
|
+
#### Supporting Micro Transactions (aka Satoshi tests)
|
|
223
517
|
|
|
224
|
-
|
|
518
|
+
You can support Micro Transfers (aka Satoshi tests) by adding a deposit address for the test.
|
|
225
519
|
|
|
226
|
-
|
|
227
|
-
`DECLARATION`: The ownership proof will be declared by the originator using a checkbox.
|
|
520
|
+
Your compliance team will have to determine how to handle and verify these transactions in the rules engine or individually.
|
|
228
521
|
|
|
229
|
-
|
|
522
|
+
```ts
|
|
523
|
+
const options: TransactionOptions = {
|
|
524
|
+
proofs: {
|
|
525
|
+
microTransfer: {
|
|
526
|
+
destination: '0x...',
|
|
527
|
+
amountSubunits: '1234',
|
|
528
|
+
timeout: 86440, // Optional timeout in seconds, which is displayed to the user
|
|
529
|
+
},
|
|
530
|
+
fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
|
|
531
|
+
},
|
|
532
|
+
};
|
|
533
|
+
```
|
|
230
534
|
|
|
231
|
-
|
|
535
|
+
Notabene does not currently verify these tests automatically as you likely already have the infrastructure to do so.
|
|
232
536
|
|
|
233
|
-
|
|
537
|
+
You will receive a response back from the component containing a proof object. For MicroTransfers it will look like this:
|
|
234
538
|
|
|
235
|
-
|
|
539
|
+
```ts
|
|
540
|
+
type MicroTransferProof {
|
|
541
|
+
type: ProofTypes.MicroTransfer;
|
|
542
|
+
status: ProofStatus.PENDING;
|
|
543
|
+
did: DID;
|
|
544
|
+
address: CAIP10; // CAIP10 account to be verified
|
|
545
|
+
txhash: string; // Transaction Hash to verify
|
|
546
|
+
chain: CAIP2; // CAIP2 identifier of blockchain
|
|
547
|
+
amountSubunits: string; // Amount in subunits eg (satoshi or wei) to be verified
|
|
548
|
+
}
|
|
549
|
+
```
|
|
236
550
|
|
|
237
|
-
|
|
551
|
+
#### Fallback Proof Options
|
|
238
552
|
|
|
239
|
-
|
|
553
|
+
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:
|
|
240
554
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
555
|
+
```ts
|
|
556
|
+
const options: TransactionOptions = {
|
|
557
|
+
proofs: {
|
|
558
|
+
fallbacks: [ProofTypes.Screenshot, ProofTypes.SelfDeclaration], // js ['screenshot','self_declaration']
|
|
559
|
+
},
|
|
560
|
+
};
|
|
561
|
+
```
|
|
248
562
|
|
|
249
|
-
|
|
563
|
+
The two options are:
|
|
250
564
|
|
|
251
|
-
-
|
|
252
|
-
-
|
|
565
|
+
- `screenshot` Where a user is requested to upload a screenshot of their wallet
|
|
566
|
+
- `self-declaration` Where a user self declares that they control the wallet address
|
|
253
567
|
|
|
254
|
-
|
|
568
|
+
### Counterparty Field Properties
|
|
569
|
+
|
|
570
|
+
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.
|
|
571
|
+
|
|
572
|
+
We recommend working closely with your compliance team for this. Bearing in mind that different jurisdictions have different rules.
|
|
573
|
+
|
|
574
|
+
Each field can be configured like this:
|
|
575
|
+
|
|
576
|
+
- `true` required field
|
|
577
|
+
- `false` don't show
|
|
578
|
+
- `{ optional: true }` show but don't require
|
|
579
|
+
|
|
580
|
+
Eg:
|
|
581
|
+
|
|
582
|
+
```ts
|
|
255
583
|
{
|
|
256
|
-
|
|
257
|
-
optional: true
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
optional: true;
|
|
262
|
-
},
|
|
584
|
+
naturalPerson: {
|
|
585
|
+
website: { optional: true },
|
|
586
|
+
email: true,
|
|
587
|
+
phone: false,
|
|
588
|
+
}
|
|
263
589
|
}
|
|
264
590
|
```
|
|
265
591
|
|
|
592
|
+
The above will always ask the user for the following for natural persons:
|
|
593
|
+
|
|
594
|
+
- `name` since it is on by default (you can disable it explicitly by setting it to `false`)
|
|
595
|
+
- `website` is show but is optional
|
|
596
|
+
- `email` is required
|
|
597
|
+
|
|
598
|
+
#### Full Example
|
|
599
|
+
|
|
600
|
+
```ts
|
|
601
|
+
const options: TransactionOptions = {
|
|
602
|
+
fields: {
|
|
603
|
+
naturalPerson: {
|
|
604
|
+
name: true, // Default true
|
|
605
|
+
website: { optional: true },
|
|
606
|
+
email: true,
|
|
607
|
+
phone: true,
|
|
608
|
+
geographicAddress: false,
|
|
609
|
+
nationalIdentification: false,
|
|
610
|
+
dateOfBirth: {
|
|
611
|
+
transmit: true,
|
|
612
|
+
},
|
|
613
|
+
placeOfBirth: false,
|
|
614
|
+
countryOfResidence: true,
|
|
615
|
+
},
|
|
616
|
+
legalPerson: {
|
|
617
|
+
name: true, // Default true
|
|
618
|
+
lei: true, // Default true
|
|
619
|
+
website: { optional: true }, // Default true
|
|
620
|
+
email: true,
|
|
621
|
+
phone: true,
|
|
622
|
+
geographicAddress: false,
|
|
623
|
+
nationalIdentification: false,
|
|
624
|
+
countryOfRegistration: true,
|
|
625
|
+
},
|
|
626
|
+
},
|
|
627
|
+
};
|
|
628
|
+
```
|
|
266
629
|
|
|
630
|
+
#### Field reference
|
|
267
631
|
|
|
268
|
-
|
|
632
|
+
| Field name | Natural | Legal | IVMS101 | description |
|
|
633
|
+
| ------------------------ | ------- | ----- | ------- | --------------------------------------------- |
|
|
634
|
+
| `name` | ✅ | ✅ | 🟩 | Full name |
|
|
635
|
+
| `email` | 🟩 | 🟩 | -- | Email (for your internal purposes) |
|
|
636
|
+
| `website` | -- | ✅ | -- | Business Website (for your internal purposes) |
|
|
637
|
+
| `phone` | 🟩 | 🟩 | -- | Mobile Phone (for your internal purposes) |
|
|
638
|
+
| `geographicAddress` | 🟩 | 🟩 | 🟩 | Residencial or business address |
|
|
639
|
+
| `nationalIdentification` | 🟩 | 🟩 | 🟩 | National Identification number |
|
|
640
|
+
| `dateOfBirth` | 🟩 | -- | 🟩 | Date of birth |
|
|
641
|
+
| `placeOfBirth` | 🟩 | -- | 🟩 | Place of birth |
|
|
642
|
+
| `countryOfResidence` | 🟩 | -- | 🟩 | Country of Residence |
|
|
643
|
+
| `lei` | -- | ✅ | 🟩 | LEI (Legal Entity Identifier) |
|
|
644
|
+
| `countryOfRegistration` | -- | 🟩 | 🟩 | Country of Registration |
|
|
269
645
|
|
|
270
|
-
|
|
646
|
+
## Locales
|
|
271
647
|
|
|
272
|
-
|
|
273
|
-
notabene.setTransaction({
|
|
274
|
-
transactionAsset: 'ASSET_UNSUPPORTED_FROM_NOTABENE',
|
|
275
|
-
beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
|
|
276
|
-
transactionAmount: '2000000000',
|
|
277
|
-
customAssetPrice: {
|
|
278
|
-
priceUSD: 1700.12, // Asset price in USD
|
|
279
|
-
decimals: 10 // Decimals used for the given transactionAmount
|
|
280
|
-
};
|
|
281
|
-
});
|
|
282
|
-
```
|
|
648
|
+
See [locales](src/locales.ts) for the list of supported locales.
|
|
283
649
|
|
|
284
650
|
## [License](LICENSE.md)
|
|
285
651
|
|
|
286
|
-
|
|
652
|
+
MIT © Notabene Inc.
|