@elizaos/plugin-zksync-era

A plugin for integrating ZKSync Era blockchain operations with your application, providing token transfer capabilities and transaction management.

Overview

This plugin provides functionality to:

• Execute token transfers on ZKSync Era
• Handle smart account operations
• Manage transaction signing and submission
• Support multiple token standards
• Process transaction receipts and confirmations

Installation

npm install @elizaos/plugin-zksync-era

Configuration

The plugin requires the following environment variables:

ZKSYNC_ADDRESS=your_address           # Required: Your ZKSync wallet address
ZKSYNC_PRIVATE_KEY=your_private_key  # Required: Your wallet's private key

Usage

Basic Setup

import { zksyncEraPlugin } from "@elizaos/plugin-zksync-era";

const plugin = zksyncEraPlugin;

Token Transfers

// Transfer tokens
await transfer.handler(
    runtime,
    {
        content: {
            tokenAddress: "0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4", // USDC
            recipient: "0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62",
            amount: "100",
        },
    },
    state
);

Features

Supported Tokens

The plugin includes pre-configured addresses for common tokens:

const TOKENS = {
    ZK: "0x5A7d6b2F92C77FAD6CCaBd7EE0624E64907Eaf3E",
    ETH: "0x000000000000000000000000000000000000800A",
    USDC: "0x1d17CBcF0D6D143135aE902365D2E5e2A16538D4",
};

Smart Account Integration

const web3 = new Web3();
web3.registerPlugin(
    new ZKsyncPlugin(
        Web3ZKsyncL2.initWithDefaultProvider(types.Network.Mainnet)
    )
);

const smartAccount = new web3.ZKsync.SmartAccount({
    address: PUBLIC_KEY,
    secret: PRIVATE_KEY,
});

Error Handling

The plugin includes comprehensive error handling:

try {
    const transferTx = await smartAccount.transfer({
        to: recipient,
        token: tokenAddress,
        amount: amount,
    });
    const receipt = await transferTx.wait();
} catch (error) {
    console.error("Transfer failed:", error.message);
}

Common error cases:

• Invalid configuration
• Insufficient balance
• Network issues
• Invalid addresses
• Failed transactions

Best Practices

1. Always validate addresses before transactions
2. Keep private keys secure
3. Monitor transaction status
4. Implement proper error handling
5. Use appropriate gas settings
6. Keep track of transaction receipts

API Reference

Core Interfaces

interface TransferContent {
    tokenAddress: string;
    recipient: string;
    amount: string | number;
}

interface ZKsyncConfig {
    ZKSYNC_ADDRESS: string;
    ZKSYNC_PRIVATE_KEY: string;
}

Plugin Methods

• transfer: Execute token transfers
• validateZKsyncConfig: Validate configuration
• Transaction status monitoring
• Receipt handling

Development

Building

npm run build

Testing

npm run test

Security Best Practices

• Store private keys securely using environment variables
• Validate all addresses before transactions
• Implement proper error handling
• Keep dependencies updated
• Monitor transaction status
• Use secure RPC endpoints
• Implement proper gas management

Example Usage

// Initialize plugin
const zksync = zksyncEraPlugin;

// Execute transfer
try {
    await transfer.handler(
        runtime,
        {
            content: {
                tokenAddress: TOKENS.USDC,
                recipient: "0xCCa8009f5e09F8C5dB63cb0031052F9CB635Af62",
                amount: "100",
            },
        },
        state
    );
} catch (error) {
    console.error("Transfer failed:", error.message);
}

Validation

The plugin includes validation for:

• Wallet addresses
• Token addresses
• Transaction amounts
• Configuration parameters
• Network status

Dependencies

• @elizaos/core: Core Eliza functionality
• web3: Web3 library for blockchain interaction
• web3-plugin-zksync: ZKSync Era integration
• Other standard dependencies listed in package.json

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits

This plugin integrates with and builds upon several key technologies:

• ZKSync Era: Layer 2 scaling solution for Ethereum
• Web3.js: Ethereum JavaScript API
• web3-plugin-zksync: Official ZKSync plugin for Web3.js

Special thanks to:

• The Eliza community for their contributions and feedback

For more information about ZKSync Era and its capabilities, visit:

• ZKSync Documentation
• Matter Labs Blog
• ZKSync GitHub

License

This plugin is part of the Eliza project. See the main project repository for license information.