README.md

Web3Tokens

Web3Tokens is designed to simplify the interaction with Ethereum Virtual Machine (EVM) tokens, including ERC20, ERC721, and ERC1155 standards. This library aims to make it easier for new developers to engage with smart contracts, offering an accessible entry point into blockchain development.

Vision and Goals

The primary goal of Web3Tokens is to simplify the use of smart contracts, specifically focusing on token interactions. By providing a user-friendly interface and abstracting the complexities of smart contracts, ABIs, and signatures, Web3Tokens empowers developers—especially those who are new to blockchain development—to jump right in and start building.

Prerequisites

Before you start using Web3Tokens, you should have a basic understanding of Viem. This knowledge is essential for correctly instantiating the client and making the most of the library's features.

Installation

To install the package, run the following command:

npm i @lunarislab/web3tokens

Example Setup

import { Web3Tokens } from '@lunarislab/web3tokens';
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

// Create an account using a private key
const account = privateKeyToAccount(process.env.PRIVATE_KEY);

// Configuration for initializing clients
const config = {
    chain: sepolia,
    transport: http(),
    account
};

// Initialize the library
const tokens = new Web3Tokens({
    public: createPublicClient(config),
    wallet: createWalletClient(config)
});

// Ready to use!

ERC20

ERC20 is the most commonly used token standard. Below are examples of how to interact with ERC20 tokens.

Getting a Token Contract Instance

// Retrieve the token contract instance
const token = tokens.erc20().get('0x...');

// Add extensions if needed
const token = tokens.erc20()
    .setMintable()
    .setOwnable()
    .get('0x...');

// fetch contract metadata (name, symbol and decimals)
await token.fetch();

console.log(token)

Calling Contract Methods

Reading from the Contract

const balance = await token.balanceOf(account.address);

Writing to the Contract

// Simulate a transaction
const transaction = await token.transfer({
    to: "0x...",
    value: 50000
}).simulate();

// Execute a transaction
const transaction = await token.transfer({
    to: "0x...",
    value: 50000
}).execute();

// Retrieve the transaction hash
console.log(transaction.hash);

// Wait for the transaction receipt (4 confirmations by default)
const receipt = await transaction.waitForReceipt(4);

Batch Transactions

If using a smart client with a similar interface to Viem, you can batch functions. Here's an example using zerodev batch transactions:

const transaction1 = await token.transfer({
    to: "0x...",
    value: 50000
}).getTxData();

const transaction2 = await token.transfer({
    to: "0x...",
    value: 50000
}).getTxData();

// Send batch transactions using a smart account client
const txHash = await kernelClient.sendTransactions({
  transactions: [
    transaction1,
    transaction2
  ],
});

Listening to Contract Events

token.on('Transfer', (data) => {
    console.log(data);
    // Additional logic here
});

ERC721 and ERC1155

ERC721 and ERC1155 follow a similar approach to ERC20.

Example Setup

const erc721 = tokens.erc721().get('0x...');
const erc1155 = tokens.erc1155().get('0x...');

await erc721.fetch(); // fetch name and symbol
console.log(erc721)

you can also add extensions to the tokens:

// add ERC721 extensions if needed
const erc721Burnable = tokens.erc721().setBurnable().get('0x...');

// add ERC1155 extensions if needed
const erc1155Access = tokens.erc1155().setAccessControl().get('0x...');

Contribution and Community

Web3Tokens is an open-source project, and all contributions are welcome. Whether you’re a seasoned developer or just starting, your ideas and code improvements are valuable. Feel free to open issues or pull requests on our GitHub repository.

Documentation

For more detailed information, please refer to the Web3Tokens Documentation.