@ambisafe/tabla-client/README.md

Ambisafe Tabla client library

# `tabla-client`

This library helps with Tabla API and contract interactions, and moves the maximum amount of work from the client to the blockchain.

## Installation

```
npm i @ambisafe/tabla-client
```

## Usage

1. Import Tabla client library

```ts
import { TablaClient } from '@ambisafe/tabla-client';
```

2. Create TablaClient instance 

```ts
const client = new TablaClient(
    'https://api.tabla.is', // Tabla API url
    '12d2b288-d327-4e0e-9916-f67268b06447', // Platform's public ID on Tabla
    'platform jwt secret' // Platform's JWT secret
);
```

3. Request transaction object

```ts
const transaction = await client.userWhitelist({
    kycType: 'PERSONAL:BASIC_KYC',
    walletAddress: '0xaddressaddressaddressaddressaddressaddre',
    country: 'US',
    city: 'Paris',
    residenceAddress: '1230 Ocean Avenue',
    region: 'South/Latin America',
    postcode: '12000',
    firstName: 'John',
    lastName: 'Doe',
    birthDate: '1970-01-01',
});
```

4. Send returned data from Tabla to a blockchain

```ts
const rpcProvider = new ethers.providers.JsonRpcProvider('https://rpc.ankr.com/eth');
const wallet = new ethers.Wallet(
    'private key', // Your private key of the address from which you will perform transactions to whitelist user addresses
    rpcProvider
);

await wallet.sendTransaction({
    to: transaction.to, // Whitelist contract address
    data: transaction.calldata, // Signed and ready calldata
});
```

## How can you receive all required data for whitelist your user's addresses and etc?

You can contact sales@tabla.is to add your platform to Tabla and receive all required instructions to perform user's addresses on-chain whitelist.

## Whitelist platform users

### KYC data examples

```ts
import type { PersonalKYCDataDTO, CorporateKYCDataDTO } from '@ambisafe/tabla-client';

const personalKYCData: PersonalKYCDataDTO = {
    kycType: 'PERSONAL:BASIC_KYC',
    walletAddress: '0xaddressaddressaddressaddressaddressaddre',
    country: 'US',
    city: 'Paris',
    residenceAddress: '1230 Ocean Avenue',
    region: 'South/Latin America',
    postcode: '12000',
    firstName: 'John',
    lastName: 'Doe',
    birthDate: '1970-01-01',
}

const corporateKYCData: CorporateKYCDataDTO = {
    kycType: 'CORPORATE:BASIC_KYC',
    walletAddress: '0xaddressaddressaddressaddressaddressaddre',
    country: 'US',
    city: 'Paris',
    residenceAddress: '1230 Ocean Avenue',
    region: 'South/Latin America',
    postcode: '12000',
    companyName: 'Senia',
    dateOfIncorporation: '1970-01-01',
}
```

### KYC types description

Personal:
1. ```PERSONAL:EMPTY``` - for example can be used to unwhitelist user's address on blockchain side
2. ```PERSONAL:BASIC_KYC``` - for basic kyc that include user's basic information and whitelist user's address for operations with basic tokens
3. ```PERSONAL:ACCREDITED_INVESTOR``` - for users with accredited investor status. Whitelist user's address if it's country require accredited investor status

Corporate:
1. ```CORPORATE:EMPTY``` - for example can be used to unwhitelist company's address on blockchain side
2. ```CORPORATE:BASIC_KYC``` - for basic kyc that include company's basic information and whitelist user's address for operations with basic tokens

### Here is example of whitelisting user address on a platform

```ts
import { ethers } from 'ethers'; // Or another web3 lib
import { TablaClient, PersonalKYCDataDTO } from '@ambisafe/tabla-client';

// Any PERSONAL KYC
(async () => {
    const rpcProvider = new ethers.providers.JsonRpcProvider('https://rpc.ankr.com/eth');
    const wallet = new ethers.Wallet(
        'private key', // Your private key of the address from which you will perform transactions to whitelist user addresses
        rpcProvider
    );

    const client = new TablaClient(
        'https://api.tabla.is', // Tabla API url
        '12d2b288-d327-4e0e-9916-f67268b06447', // Platform's public ID on Tabla
        'platform jwt secret' // Platform's JWT secret
    );
    const transaction = await client.userWhitelist({
        kycType: 'PERSONAL:BASIC_KYC',
        walletAddress: '0xaddressaddressaddressaddressaddressaddre', // User's address in Ethereum format
        country: 'US', // Alpha-2 country code
        city: 'Paris',
        residenceAddress: '1230 Ocean Avenue', // Street, Building, Apartment
        region: 'South/Latin America', // Optional
        postcode: '12000',
        firstName: 'John',
        lastName: 'Doe',
        birthDate: '1970-01-01',
    });

    await wallet.sendTransaction({
      to: transaction.to,
      data: transaction.calldata,
    });
})();

// Any CORPORATE KYC
(async () => {
    const rpcProvider = new ethers.providers.JsonRpcProvider('https://rpc.ankr.com/eth');
    const wallet = new ethers.Wallet(
        'private key', // Your private key of the address from which you will perform transactions to whitelist user addresses
        rpcProvider
    );

    const client = new TablaClient(
        'https://api.tabla.is', // Tabla API url
        '12d2b288-d327-4e0e-9916-f67268b06447', // Platform's public ID on Tabla
        'platform jwt secret' // Platform's JWT secret
    );
    const transaction = await client.userWhitelist({
        kycType: 'CORPORATE:BASIC_KYC',
        walletAddress: '0xaddressaddressaddressaddressaddressaddre', // User's address in Ethereum format
        country: 'US', // Alpha-2 country code
        city: 'Paris',
        residenceAddress: '1230 Ocean Avenue', // Street, Building, Apartment
        region: 'South/Latin America', // Optional
        postcode: '12000',
        companyName: 'Senia',
        dateOfIncorporation: '1970-01-01',
    });

    await wallet.sendTransaction({
      to: transaction.to,
      data: transaction.calldata,
    });
})();
```