npm package: @lfi-cloudx/wallet-services
Description: wallet service for partners
Author: VAI
Latest version: 1.0.1

# Wallet Service Provider

This service provides a flexible solution for managing both centralized and decentralized wallet systems. It supports the creation of user wallets, feed wallets, and the integration of hot wallets within the system.

## Features

### Multi-Entity Support

- **Partners:** Use the partner parameter to identify different entities involved in wallet creation, enabling support for multiple entities within the same application.

### Wallet Creation

- **User Wallets:** Create individual wallets for users.
- **Feed Wallets:** Set up wallets dedicated to specific feeds.
- **Hot Wallets:** Save and manage hot wallets within the system for operational convenience.

### Web3 Account Operations

Perform basic Web3 operations on both user and feed wallets, such as:

- Retrieving token balances.
- Transferring tokens.

### Token Management

To manage and interact with tokens using the generated wallets, tokens must be added to the system. This is done by providing:

- The token address.
- The chain ID.

## Installation

To install the package, run:

```bash
npm install wallet-services
```

## Usage

### Create 'Provider' Instance & Connect to DB and Add Default Chains

Follow these steps to create a `Provider` instance, connect to the database, and add default blockchain networks to the system.

```javascript
const { Provider } = require("wallet-services");

// Create 'provider' instance
const walletServiceProvider = new Provider({
  MONGO_URI: "mongodb://127.0.0.1:27017/wallet-service", // MongoDB connection string
  WALLET_ENCRYPT_PASSWORD: "your_password", // Password to encrypt wallet data
  API_KEY_ENCRYPT_PASSWORD: "your_password", // Password to encrypt API keys
  ALCHEMY_API_KEY: "your_alchemyApiKey", // Alchemy API key for blockchain interactions
  PROD_MODE: true, // Use true for mainnet; default is false for testnets
});

// Initialize 'provider' to connect to DB and add default chains

/*
 Default Chains:
 Testnet:
  - 11155111: Sepolia
  - 97: BNB Smart Chain Testnet
  - 80001: Mumbai
 Mainnet (PROD_MODE):
  - 1: Ethereum Mainnet
  - 56: BNB Smart Chain Mainnet
  - 137: Polygon Mainnet
*/

await walletServiceProvider.init();
```

- **MONGO_URI**: The connection string for your MongoDB instance where wallet data will be stored.
- **WALLET_ENCRYPT_PASSWORD**: A password used to encrypt wallet data for security.
- **API_KEY_ENCRYPT_PASSWORD**: A password used to encrypt API keys for added security.
- **ALCHEMY_API_KEY**: Your Alchemy API key, which allows the service to interact with blockchain networks.
- **PROD_MODE**: A boolean flag indicating whether to use mainnet (true) or testnets (false).

The `init` method connects to the database and sets up the default blockchain networks that the service will interact with.

### Create 'Chain'

Use this function to add a new blockchain network to the service. This is essential for enabling wallet operations on different blockchain networks.

```javascript
const chain = await walletServiceProvider.Chain.create({
  chainId: 1,
  coinType: "ERC20",
  testnet: false,
});
```

- **chainId**: The unique identifier for the blockchain network. For example, `1` for Ethereum mainnet.
- **coinType**: The type of coins/tokens supported by this chain. In this case, `"ERC20"` indicates that the chain supports ERC20 tokens.
- **testnet**: A boolean indicating whether this is a testnet (true) or a mainnet (false).

This example adds the Ethereum mainnet as a supported chain in the wallet service provider.

### Create 'Partner'

Use this function to create a new partner entity within the wallet service. Partners are used to identify and manage different entities within the same application.

```javascript
const partner = await walletServiceProvider.Partner.create({
  name: "Partner Name",
  email: "partner@gmail.com",
});
```

- **name**: The name of the partner.
- **email**: The email address of the partner.

This example creates a partner named "Partner Name" with the email "partner@gmail.com". Partners allow for the organization and management of multiple entities, each with its own set of wallets and configurations.

### Create 'ChainConfig' for Partners

Use this function to configure a specific blockchain network (chain) for a partner. This configuration includes necessary details like the scanner API and RPC URL required for blockchain interactions.

```javascript
const chainConfig = await walletServiceProvider.ChainConfig.create({
  chainId: chain._id,
  partnerId: partner._id,
  scannerAPIEndpoint: "https://api.etherscan.io/api",
  scannerAPIKey: "your_scanner_api_key",
  rpcUrl: "https://mainnet.infura.io/v3/your_infura_project_id",
});
```

- **chainId**: The ID of the chain you are configuring for the partner. This should match the ID of a chain previously created in the system.
- **partnerId**: The ID of the partner for whom you are creating this configuration.
- **scannerAPIEndpoint**: The endpoint of the blockchain scanner API (e.g., Etherscan API).
- **scannerAPIKey**: The API key for accessing the scanner API.
- **rpcUrl**: The RPC URL for interacting with the blockchain network.

This example creates a chain configuration for a partner, specifying the scanner API endpoint, API key, and RPC URL required to interact with the Ethereum mainnet.

### Create 'Token'

Use this function to add a new token to the system for a specific blockchain network and partner. This enables wallet operations involving this token, such as checking balances and making transfers.

```javascript
const token = await walletServiceProvider.Token.create({
  chainId: 97,
  address: "token_address",
  partnerId: partner._id,
});
```

- **chainId**: The ID of the chain on which the token exists. For example, `97` for the BNB Smart Chain testnet.
- **address**: The contract address of the token.
- **partnerId**: The ID of the partner for whom the token is being added.

This example adds a token to the BNB Smart Chain testnet for a specific partner, allowing that partner to manage and interact with this token within their wallets.

### Create 'UserWallet'

Use this function to create a new user wallet on a specific blockchain network for a partner. User wallets are essential for storing and managing users' cryptocurrency assets.

```javascript
const userWallet = await walletServiceProvider.UserWallet.create({
  chainId: chain._id,
  partnerId: partner._id,
});
```

- **chainId**: The ID of the chain on which the user wallet will be created. This should correspond to an existing chain configuration.
- **partnerId**: The ID of the partner for whom the user wallet is being created.

This example creates a user wallet on a specified blockchain network (identified by `chain._id`) for a particular partner (identified by `partner._id`). This wallet can then be used to store, transfer, and manage the partner's users' cryptocurrency assets.

### Create a 'FeedWallet'

Use this function to create a new feed wallet on a specific blockchain network for a partner. Feed wallets are specialized wallets that can be used for specific purposes, such as handling particular types of transactions or managing specific funds.

```javascript
const feedWallet = await walletServiceProvider.FeedWallet.create({
  chainId: chain._id,
  partnerId: partner._id,
  tokenId: token._id,
});
```

- **chainId**: The ID of the chain on which the feed wallet will be created. This should correspond to an existing chain configuration.
- **partnerId**: The ID of the partner for whom the feed wallet is being created.
- **tokenId**: The ID of the token that this feed wallet will manage or interact with.

This example creates a feed wallet on a specified blockchain network (identified by `chain._id`) for a particular partner (identified by `partner._id`). The feed wallet is associated with a specific token (identified by `token._id`), enabling it to manage and interact with that token within the wallet service.

### Create a 'HotWallet'

This function creates a hot wallet, which is a cryptocurrency wallet that is connected to the internet and used for managing funds in real-time operations. Hot wallets are often used for operational convenience, such as facilitating frequent transactions.

```javascript
const hotWallet = await walletServiceProvider.HotWallet.create({
  chainId: chain._id,
  partnerId: partner._id,
  tokenId: token._id,
  address: "hot_wallet_address",
});
```

- **chainId**: The ID of the chain on which the hot wallet will be created. This should correspond to an existing chain configuration.
- **partnerId**: The ID of the partner for whom the hot wallet is being created.
- **tokenId**: The ID of the token that this hot wallet will manage or interact with.
- **address**: The address of the hot wallet.

This example creates a hot wallet on a specified blockchain network (identified by `chain._id`) for a particular partner (identified by `partner._id`). The hot wallet is associated with a specific token (identified by `token._id`), enabling it to manage and interact with that token within the wallet service.

### Web3 Functions on 'FeedWallet' / 'UserWallet'

These functions allow you to perform various Web3 operations on feed or user wallets, such as checking token balances, transferring tokens, and retrieving native token balances.

#### Get Token Balance of a User Wallet

Use this function to retrieve the balance of a specific token for a given user wallet.

```javascript
const tokenBalance = await walletServiceProvider.UserWallet.getTokenBalance({
  tokenId: token._id,
  walletAddress: userWallet.address,
  partnerId: userWallet.partner,
});
```

- **tokenId**: The ID of the token you want to check the balance for.
- **walletAddress**: The address of the user's wallet.
- **partnerId**: The ID of the partner associated with this wallet.

#### Transfer Tokens to Another Address

Transfer tokens from a user wallet to another address.

```javascript
const res = await walletServiceProvider.UserWallet.transferTokens({
  tokenId: token._id,
  walletAddress: userWallet.address,
  partnerId: userWallet.partner,
  amount: "0.001",
  to: "recipient_address",
});
```

- **tokenId**: The ID of the token you want to transfer.
- **walletAddress**: The address of the user's wallet.
- **partnerId**: The ID of the partner associated with this wallet.
- **amount**: The amount of tokens to transfer.
- **to**: The recipient address.

#### Get Wallet Native Token Balance

Retrieve the native token balance of a user wallet.

```javascript
const res = await walletServiceProvider.UserWallet.getBalance({
  tokenId: token._id,
  walletAddress: userWallet.address,
  partnerId: userWallet.partner,
});
```

- **tokenId**: The ID of the token you want to check the balance for.
- **walletAddress**: The address of the user's wallet.
- **partnerId**: The ID of the partner associated with this wallet.

These functions enable you to perform essential Web3 operations on user wallets, facilitating token management and transactions within the wallet service.

#### Transfer Native Tokens to Another Address

This function allows you to transfer native tokens (the primary cryptocurrency of the blockchain network) from a user wallet to another address.

```javascript
const res = await walletServiceProvider.UserWallet.transferNativeTokens({
  chainId: chain._id,
  walletAddress: userWallet.address,
  partnerId: userWallet.partner,
  amount: "0.001",
  to: "recipient_address",
});
```

- **chainId**: The ID of the chain on which the transfer will occur.
- **walletAddress**: The address of the user's wallet.
- **partnerId**: The ID of the partner associated with this wallet.
- **amount**: The amount of native tokens to transfer.
- **to**: The recipient address.

This function is useful for transferring the primary cryptocurrency of the blockchain network, such as Ether for Ethereum or BNB for Binance Smart Chain.

#### Get Transaction Receipt

Retrieve the receipt of a transaction by providing its hash.

```javascript
const receipt = await walletServiceProvider.Transaction.getTransactionReceipt({
  transactionHash: "txhash",
  chainId: chain.chainId,
  partnerId: partner._id,
});
```

- **transactionHash**: The hash of the transaction whose receipt you want to retrieve.
- **chainId**: The ID of the chain on which the transaction occurred.
- **partnerId**: The ID of the partner associated with the transaction.

This function allows you to obtain detailed information about a transaction, such as its status, gas used, and block number, providing insights into its execution on the blockchain network.

### Create 'Webhook'

This function creates a webhook, allowing you to configure real-time notifications and updates for wallet addresses.

```javascript
const response = await walletServiceProvider.Webhook.create({
  addresses: ["address1", "address2"],
  webhookUrl: "webhook_url",
  partnerId: partner._id,
  chainId: 11155111,
});
```

- **addresses**: An array of wallet addresses for which the webhook will trigger notifications.
- **webhookUrl**: The URL that will receive the webhook notifications.
- **partnerId**: The ID of the partner associated with this webhook.
- **chainId**: The ID of the chain for which the webhook is configured.

This function enables you to set up custom webhook configurations, allowing your application to receive real-time updates about wallet activities, such as incoming transactions or token transfers.