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:

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.

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.

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.

const partner = await walletServiceProvider.Partner.create({
  name: "Partner Name",
  email: "[email protected]",
});

• name: The name of the partner.
• email: The email address of the partner.

This example creates a partner named "Partner Name" with the email "[email protected]". 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.