Skip to main content

@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:

Special thanks to:

  • The Eliza community for their contributions and feedback

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

License​

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