@tool_blox/plugin

A JavaScript Web3 integration library designed for Toolblox plugins, enabling Web3 capabilities in no-code platforms like Bubble™ and Weweb™. Provides wallet connections, blockchain interactions, and comprehensive Toolblox workflow utilities.

Installation

npm install @tool_blox/plugin

Features

• Web3Auth Integration - Passwordless authentication and social login
• Wallet Connect Support - Mobile wallet connections via QR codes
• Coinbase Wallet Support - Browser extension integration
• Ethereum Provider - Complete provider management
• Ethers.js Integration - Smart contract interactions
• Universal Module Support - ESM and CommonJS compatibility
• ToolbloxUtils - Complete Toolblox workflow interaction toolkit

Basic Usage

Node.js (CommonJS)

const { Web3AuthNoModal, ethers, ToolbloxUtils } = require('@tool_blox/plugin');

Node.js (ESM) / Browser

import { Web3AuthNoModal, ethers, ToolbloxUtils } from '@tool_blox/plugin';

Browser (Script Tag)

<script type="module">
  import { Web3AuthNoModal, ethers, ToolbloxUtils } from './node_modules/@tool_blox/plugin/dist/index.esm.js';
</script>

ToolbloxUtils API

The ToolbloxUtils class provides a comprehensive toolkit for interacting with Toolblox smart contracts.

Quick Start

import { ToolbloxUtils, ethers } from '@tool_blox/plugin';

const toolblox = new ToolbloxUtils();
const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');

// Get contract address from service locator
const contractAddress = await toolblox.getAddress(provider, 'liquidity_workflow');

// Get an item
const item = await toolblox.getItem(provider, contractAddress, 1);

// Get latest 10 items
const latestItems = await toolblox.getLatest(provider, contractAddress, 10);

Core Methods

Service Discovery

getTixAddress(provider)

// Get TIX service locator address for current network
const tixAddress = await toolblox.getTixAddress(provider);

getAddress(provider, workflow)

// Get contract address from TIX service locator (automatically detects chain)
const address = await toolblox.getAddress(provider, 'liquidity_workflow');

Data Retrieval

getItem(provider, address, id)

// Get a specific item by ID
const item = await toolblox.getItem(provider, contractAddress, 123);
console.log(item); // { id: "123", status: "0", owner: "0x...", ... }

getItemIdBy(provider, address, property, propertyValue)

// Find item ID by property value
const itemId = await toolblox.getItemIdBy(provider, contractAddress, 'owner', '0x1234...');

getPage(provider, address, cursor, howMany)

// Get paginated items
const items = await toolblox.getPage(provider, contractAddress, 1, 10);

getLatest(provider, address, count)

// Get latest items
const latestItems = await toolblox.getLatest(provider, contractAddress, 5);

Generic Contract Interaction

view(provider, address, methodName, orderedParams)

// Call any view method
const status = await toolblox.view(provider, contractAddress, 'getStatus', [itemId]);
const balance = await toolblox.view(provider, contractAddress, 'balanceOf', [userAddress]);

update(signer, address, methodName, orderedParams, value)

// Call any state-changing method
const tx = await toolblox.update(signer, contractAddress, 'buy', [itemId, amount]);
await tx.wait(); // Wait for confirmation

History & Provenance

getHistory(provider, address, id)

// Get complete transaction history for an item
const history = await toolblox.getHistory(provider, contractAddress, itemId);

history.forEach(event => {
    console.log(`${event.methodName} - ${event.timestamp}`);
    console.log(`Status: ${event.status}`);
    console.log(`Parameters:`, event.parameters);
});

Complete Example with Web3Auth

import { 
    Web3AuthNoModal, 
    EthereumPrivateKeyProvider,
    CHAIN_NAMESPACES,
    WEB3AUTH_NETWORK,
    ethers,
    ToolbloxUtils 
} from '@tool_blox/plugin';

class ToolbloxApp {
    constructor() {
        this.toolblox = new ToolbloxUtils();
        this.provider = null;
        this.signer = null;
    }

    async initialize() {
        // Setup Web3Auth
        const privateKeyProvider = new EthereumPrivateKeyProvider({
            config: {
                chainConfig: {
                    chainNamespace: CHAIN_NAMESPACES.EIP155,
                    chainId: "0x89", // Polygon Mainnet
                    rpcTarget: "https://polygon-rpc.com/",
                },
            },
        });

        const web3auth = new Web3AuthNoModal({
            clientId: "YOUR_CLIENT_ID",
            web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
            privateKeyProvider,
        });

        await web3auth.init();
        const web3authProvider = await web3auth.connect();
        
        this.provider = new ethers.BrowserProvider(web3authProvider);
        this.signer = await this.provider.getSigner();
    }

    async workWithLiquidityPool() {
        // 1. Get contract address (automatically uses correct TIX for chain)
        const contractAddress = await this.toolblox.getAddress(
            this.provider, 
            'liquidity_workflow'
        );

        // 2. Get latest pools
        const pools = await this.toolblox.getLatest(this.provider, contractAddress, 5);
        console.log('Latest pools:', pools);

        // 3. Buy tokens for pool 1
        const tx = await this.toolblox.update(
            this.signer,
            contractAddress,
            'buy',
            [1, ethers.parseEther('100')] // Buy 100 tokens for pool ID 1
        );

        console.log('Transaction sent:', tx.hash);
        await tx.wait();
        console.log('Purchase confirmed!');

        // 4. Get transaction history
        const history = await this.toolblox.getHistory(this.provider, contractAddress, 1);
        console.log('Pool history:', history);
    }
}

// Usage
const app = new ToolbloxApp();
await app.initialize();
await app.workWithLiquidityPool();

Complete Example with WalletConnect v2

import { 
    EthereumProvider,
    ethers,
    ToolbloxUtils 
} from '@tool_blox/plugin';

class WalletConnectApp {
    constructor() {
        this.toolblox = new ToolbloxUtils();
        this.provider = null;
        this.signer = null;
    }

    async initialize() {
        // Setup WalletConnect v2
        this.provider = await EthereumProvider.init({
            projectId: 'YOUR_WALLETCONNECT_PROJECT_ID', // Get from https://cloud.walletconnect.com
            chains: [137, 8453, 56], // Polygon, Base, Binance
            showQrModal: true,
            metadata: {
                name: 'Toolblox DApp',
                description: 'Toolblox Web3 Integration',
                url: 'https://toolblox.net',
                icons: ['https://toolblox.net/favicon.ico']
            }
        });

        // Connect wallet
        await this.provider.enable();
        
        const ethersProvider = new ethers.BrowserProvider(this.provider);
        this.signer = await ethersProvider.getSigner();
    }

    async switchToPolygon() {
        await this.provider.request({
            method: 'wallet_switchEthereumChain',
            params: [{ chainId: '0x89' }], // Polygon
        });
    }

    async workWithMultipleChains() {
        // Work on Polygon
        await this.switchToPolygon();
        const polygonWorkflow = await this.toolblox.getAddress(
            new ethers.BrowserProvider(this.provider), 
            'liquidity_workflow'
        );
        
        // Switch to Base
        await this.provider.request({
            method: 'wallet_switchEthereumChain',
            params: [{ chainId: '0x2105' }], // Base
        });
        
        const baseWorkflow = await this.toolblox.getAddress(
            new ethers.BrowserProvider(this.provider), 
            'liquidity_workflow'
        );
        
        console.log('Polygon workflow:', polygonWorkflow);
        console.log('Base workflow:', baseWorkflow);
    }
}

// Usage
const app = new WalletConnectApp();
await app.initialize();
await app.workWithMultipleChains();

Error Handling

try {
    const item = await toolblox.getItem(provider, contractAddress, invalidId);
} catch (error) {
    if (error.message.includes('Cannot find item')) {
        console.log('Item does not exist');
    } else {
        console.error('Unexpected error:', error.message);
    }
}

Event Monitoring

// Monitor contract events in real-time
const contract = new ethers.Contract(contractAddress, [
    "event ItemUpdated(uint256 indexed id, uint64 status)"
], provider);

contract.on("ItemUpdated", async (id, status) => {
    console.log(`Item ${id} updated to status ${status}`);
    
    // Get updated item details
    const item = await toolblox.getItem(provider, contractAddress, id.toString());
    console.log('Updated item:', item);
});

Performance & Caching

The ToolbloxUtils class includes built-in contract instance caching for better performance:

// Clear cache when switching providers/networks
toolblox.clearCache();

Supported Workflows

This plugin works with all Toolblox-generated smart contracts that follow the standard patterns:

• Liquidity Pools - Buy, sell, borrow, repay functionality
• NFT Collections - Minting, trading, metadata management
• Supply Chain - Item tracking, ownership transfers
• DeFi Protocols - Staking, rewards, governance
• Custom Workflows - Any Toolblox-generated contract

Multi-Chain Support

The plugin automatically detects the connected network and uses the correct TIX service locator address. Supported networks include:

Mainnet Networks

• Polygon (0x89) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• Binance Smart Chain (0x38) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Base (0x2105) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• Avalanche (0xA86A) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Aurora (0x4e454152) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Scroll (0x82750) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• BitTorrent Chain (0xC7) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• Taraxa (0x349) - TIX: 0x16d214EDD17861009dE32B84F3e10c122172f55f
• Evmos (0x2329) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672

Testnet Networks

• Ethereum Sepolia (0xaa36a7) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Polygon Amoy (0x13882) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• Binance Testnet (0x61) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Base Sepolia (0x14A34) - TIX: 0x9B3AD2533a7Db882C72E4C403e45c64F4A7E3F5b
• Avalanche Fuji (0xA869) - TIX: 0xBE1B2722cBC114299C2C15F2dc57D362a7681575
• Aurora Testnet (0x4E454153) - TIX: 0x7EeC85Ce685e2d0A6856b23aA31b23EB06b38B24
• Scroll Sepolia (0x8274f) - TIX: 0x2C089696c412E0F52AA2f96494B314edeF4A5E1D
• Hedera Testnet (0x128) - TIX: 0xABD5F9cFB2C796Bbd1647023ee2BEA74B23bf672
• Redbelly Testnet (0x99) - TIX: 0x42e3806cb4092D0cD7ABEBe8D8Ad76AB8324CCf6
• Taraxa Testnet (0x34A) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• BTTC Testnet (0x405) - TIX: 0x6994199717e1396ad91Bf12B41FbEFcD218e25A7
• Evmos Testnet (0x2328) - TIX: 0x865e1aeaD8e6e0fE4cF72bd670DCD768368a8d8e

Multi-Chain Example

import { ToolbloxUtils, ethers } from '@tool_blox/plugin';

const toolblox = new ToolbloxUtils();

// Automatically detects network and uses correct TIX address
const workflowAddress = await toolblox.getAddress(provider, 'my_workflow');

// Manual TIX address lookup
const tixAddress = await toolblox.getTixAddress(provider);
console.log('Using TIX service locator:', tixAddress);

License

MIT