@lunarislab/web3tokens
v1.0.24
Published
A library for interacting with EVM tokens such as ERC20, ERC721 and ERC1155.
Downloads
37
Maintainers
Readme
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.