web3/README.md

LetheanWallet

lethean_web3 is a TypeScript library for interacting with the LetheanWallet extension in the browser. It allows you to connect to a user's LetheanWallet, handle authentication, and manage wallet credentials.

Features

• Easy Integration: Simplifies the process of connecting to the LetheanWallet extension.
• Local Storage Support: Optionally store wallet credentials in local storage.
• Customizable: Offers hooks for various connection lifecycle events.
• Error Handling: Provides a structured way to handle errors during the connection process.
• Alias Management: Allows retrieving and creating aliases.

Installation

To install lethean_web3, use npm or yarn:

npm install lethean_web3

or

yarn add lethean_web3

WEB API (extension):

Usage

Importing the Library

import LetheanWallet from 'lethean_web3/web';

Creating a LetheanWallet Instance

To create a LetheanWallet instance, you need to provide configuration options via the LetheanWalletParams interface.

const letheanWallet = new LetheanWallet({
    authPath: '/api/auth', // Custom server path for authentication
    useLocalStorage: true, // Store wallet credentials in local storage (default: true)
    aliasRequired: false,  // Whether an alias is required (optional)
    customLocalStorageKey: 'myWalletKey', // Custom key for local storage (optional)
    customNonce: 'customNonceValue', // Custom nonce for signing (optional)
    disableServerRequest: false, // Disable server request after signing (optional)

    onConnectStart: () => {
        console.log('Connecting to LetheanWallet...');
    },
    onConnectEnd: (data) => {
        console.log('Connected:', data);
    },
    onConnectError: (error) => {
        console.error('Connection error:', error);
    },
    beforeConnect: async () => {
        console.log('Preparing to connect...');
    },
    onLocalConnectEnd: (data) => {
        console.log('Local connection established:', data);
    }
});

React / Next.js

For React or Next.js projects, you can use the useLetheanWallet hook to create a LetheanWallet instance:

import { useLetheanWallet } from 'lethean_web3/web';

const MyComponent = () => {
    const letheanWallet = useLetheanWallet({
        // same options as for LetheanWallet constructor
    });

    return (
        <div>
            <button onClick={() => letheanWallet.connect()}>Connect to LetheanWallet</button>
        </div>
    );
};

Connecting to LetheanWallet

To initiate the connection process, call the connect method:

await letheanWallet.connect();

Handling Wallet Credentials

You can manually manage wallet credentials using getSavedWalletCredentials and setWalletCredentials methods:

const credentials = letheanWallet.getSavedWalletCredentials();
if (credentials) {
    console.log('Stored credentials:', credentials);
}

letheanWallet.setWalletCredentials({
    nonce: 'newNonce',
    signature: 'newSignature',
    publicKey: 'newPublicKey'
});

Retrieving Wallet Data

You can retrieve the wallet data using the getWallet method:

const wallet = await letheanWallet.getWallet();
console.log('Wallet data:', wallet);

Getting Address by Alias

To get an address by alias, use the getAddressByAlias method:

const address = await letheanWallet.getAddressByAlias('exampleAlias');
console.log('Address:', address);

Creating an Alias

To create a new alias, use the createAlias method:

const newAliasData = await letheanWallet.createAlias('newAlias');
console.log('Alias created:', newAliasData);

Exported Types

The following TypeScript interfaces are exported by the lethean_web3 library. You can import them directly from library:

import { Wallet, Asset, Transfer, Transaction } from 'lethean_web3';

export interface Asset {
    name: string;
    ticker: string;
    assetId: string;
    decimalPoint: number;
    balance: string;
    unlockedBalance: string;
}

export interface Transfer {
    amount: string;
    assetId: string;
    incoming: boolean;
}

export interface Transaction {
    isConfirmed: boolean;
    txHash: string;
    blobSize: number;
    timestamp: number;
    height: number;
    paymentId: string;
    comment: string;
    fee: string;
    isInitiator: boolean;
    transfers: Transfer[];
}

export interface Wallet {
    address: string;
    alias: string;
    balance: string;
    assets: Asset[];
    transactions: Transaction[];
}

Requirements

• LetheanWallet browser extension must be installed.

Server api (Wallet RPC, Daemon):

Methods

• updateWalletRpcUrl(rpcUrl: string): Updates the wallet RPC URL.
• updateDaemonRpcUrl(rpcUrl: string): Updates the daemon RPC URL.
• getAssetsList(): Retrieves the list of assets.
• getAssetDetails(assetId: string): Retrieves details of a specific asset.
• getAssetInfo(assetId: string): Retrieves info of a specific asset.
• sendTransfer(assetId: string, address: string, amount: string): Sends a transfer to an address.
• getBalances(): Retrieves the balances.
• validateWallet(rpcUrl: string, authData: AuthData): Validates the wallet.
• getAliasDetails(alias:string) : Retrieves information about a specific address alias.
• fetchDaemon(method: string, params: any): Fetches daemon with given method & params and returns an AxiosResponse object.
• fetchWallet(method: string, params: any): Fetches wallet with given method & params and returns an AxiosResponse object.

1. Updating Wallet RPC URL

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Update the wallet RPC URL
    await letheanServerAPI.updateWalletRpcUrl("http://new_wallet_url:36944/json_rpc");

    console.log("Wallet RPC URL updated.");
})();

2. Updating Daemon RPC URL

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Update the daemon RPC URL
    await letheanServerAPI.updateDaemonRpcUrl("http://new_daemon_url:36941/json_rpc");

    console.log("Daemon RPC URL updated.");
})();

3. Getting the List of Assets

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Get the list of assets
    const assets = await letheanServerAPI.getAssetsList();

    console.log("Assets List:", assets);
})();

4. Getting Asset Details

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Get details of a specific asset by ID
    const assetId = "example-asset-id";
    const assetDetails = await letheanServerAPI.getAssetDetails(assetId);

    console.log(`Details for Asset ID ${assetId}:`, assetDetails);
})();

5. Getting Asset Info

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Get info for a specific asset by ID
    const assetId = "example-asset-id";
    const assetInfo = await letheanServerAPI.getAssetInfo(assetId);

    console.log(`Info for Asset ID ${assetId}:`, assetInfo);
})();

6. Sending a Transfer

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Send a transfer
    const assetId = "example-asset-id";
    const address = "recipient-address";
    const amount = "10.5"; // in asset units

    try {
        const transferResult = await letheanServerAPI.sendTransfer(assetId, address, amount);
        console.log("Transfer successful:", transferResult);
    } catch (error) {
        console.error("Transfer failed:", error.message);
    }
})();

7. Getting Balances

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Get the balances
    const balances = await letheanServerAPI.getBalances();

    console.log("Balances:", balances);
})();

8. Validating a Wallet

import { ServerWallet } from "lethean_web3/server";
import { AuthData } from "./types";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    // Validate wallet using AuthData
    const authData: AuthData = {
        message: "message to sign",
        address: "wallet-address",
        signature: "signature",
        alias: "wallet-alias"
    };

    try {
        const isValid = await letheanServerAPI.validateWallet(authData);
        console.log("Wallet validation:", isValid ? "Valid" : "Invalid");
    } catch (error) {
        console.error("Validation failed:", error.message);
    }
})();

9. Get Alias details

import { ServerWallet } from "lethean_web3/server";

const alias = "alias";

(async (alias) => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    try {
        const aliasDetails = await letheanServerAPI.getAliasDetails(alias);
        console.log(aliasDetails);
    } catch (error) {
        console.error(error.message);
    }
})(alias);

10. Fetch Daemon

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    try {
        // Fetch daemon and retrieve a response (e.g., the getinfo method)
        const getInfoResponse = await letheanServerAPI.fetchDaemon("getinfo", {
            "flags": 1048575
        });

        console.log("Info:", getInfoResponse.data.result);
    } catch (error) {
        console.error('Error fetching getinfo:', error);
    }
    
})();

11. Fetch Wallet

import { ServerWallet } from "lethean_web3/server";

(async () => {
    const letheanServerAPI = new ServerWallet({
        walletUrl: "http://127.0.0.1:36941/json_rpc",
        daemonUrl: "http://127.0.0.1:36941/json_rpc"
    });

    try {
        // Fetch wallet and retrieve a response (e.g., the getaddress method)
        const getAddressResponse = await letheanServerAPI.fetchWallet("getaddress", {});

        console.log("Address Info:", getAddressResponse.data.result);
    } catch (error) {
        console.error('Error fetching getaddress:', error);
    }
    
})();

Requirements

• Correct RPC URLs for the wallet and daemon.

Shared logic

Usage

validateTokensInput util

validateTokensInput function checks whether a numeric or string value can be used as an amount for an asset with the specified DP.

import { validateTokensInput } from "lethean_web3/shared";

let isValidAmount = validateTokensInput("18446744.073709551615", 12); // true

isValidAmount = validateTokensInput("18446744.073709551616", 12); // false