zkVerify-lz-bridge

This repository contains the tools and scripts necessary to bridge tokens between the zkVerify network and EVM-compatible chains using the LayerZero v2 protocol. The bridge leverages LayerZero's Omnichain Fungible Token (OFT) standard to enable seamless cross-chain token transfers.

Overview

The zkverify-lz-bridge is a TypeScript-based project that provides a client library and example scripts for facilitating token bridging. It supports two main operations:

1. Bridging to zkVerify: Transferring tokens from Base to the zkVerify network.
2. Bridging to Base: Transferring tokens from the zkVerify network back to an EVM chain.

The bridge architecture involves three key components:

• A Base Chain: An EVM-compatible network (e.g., Base, Base Sepolia).
• A Relay Chain: The main zkVerify network (or its testnet equivalent).
• A Parachain: The zkVerify VFlow network, which includes an EVM environment.

Communication between the Relay Chain and the Parachain is handled via Cross-Consensus Message Passing (XCM). Communication between the Parachain's EVM and the Base Chain is handled by LayerZero.

Features

• Bi-directional Bridging: Move tokens between zkVerify and EVM chains.
• LayerZero Integration: Utilizes the robust and widely-used LayerZero messaging protocol for bridging to/from Base.
• OFT Standard: Implements the Omnichain Fungible Token standard for interoperable tokens.
• TypeScript SDK: A simple client for easy integration into other projects.
• Command-Line Scripts: Ready-to-use scripts for performing bridge operations.

Supported Networks

Network Type	zkVerify Network	EVM Network
Mainnet	zkVerify Mainnet	Base
Testnet	zkVerify Volta Testnet	Base Sepolia
Devnet	Local Development Node	Local Devnet

Installation

1. Clone the repository:

   git clone https://github.com/zk-verify/zkverify-lz-bridge.git
   cd zkverify-lz-bridge

2. Install the dependencies:

   npm install

Usage

The primary way to use the bridge is via the provided scripts. Before running the scripts, you need to set up your environment variables.

Environment Setup

For bridging from zkVerify to Base: You'll need a mnemonic for a Substrate-based account on the zkVerify network that holds the tokens you want to bridge.

export MNEMONIC="your twelve or twenty-four word mnemonic phrase here"

For bridging from an EVM chain to zkVerify: You'll need the private key for an EVM account that holds the tokens.

export PRIVATE_KEY="0xYourPrivateKey"

Bridging from Base to zkVerify

This script transfers tokens from an EVM chain (Base Sepolia for testnet) to the zkVerify network.

Command:

tsx scripts/bridge-to-zkverify.ts --to <ZKVERIFY_ADDRESS> --amount <AMOUNT>

Arguments:

• --to or -t: The recipient's ss58 address on the zkVerify chain.
• --amount or -a: The amount of tokens to bridge (e.g., "10.5").
• --privateKey or -p (Optional): The sender's private key. It's recommended to use the PRIVATE_KEY environment variable for security.

Example (Testnet):

export PRIVATE_KEY="0x..."
tsx scripts/bridge-to-zkverify.ts \
  --to 5HpL4A3fGCo1dF8tE1aYmC5v5f1Yj3y3N2Fz7XyLqXjA9b1c \
  --amount "5"

Bridging from zkVerify to Base

This script transfers tokens from the zkVerify network to an EVM chain (Base Sepolia for testnet).

Command:

tsx scripts/bridge-to-base.ts --to <EVM_ADDRESS> --amount <AMOUNT>

Arguments:

• --to or -t: The recipient's 0x address on the EVM chain.
• --amount or -a: The amount of tokens to bridge (e.g., "10.5").
• --mnemonic or -m (Optional): The sender's mnemonic phrase. It's recommended to use the MNEMONIC environment variable for security.

Example (Testnet):

export MNEMONIC="..."
tsx scripts/bridge-to-base.ts \
  --to 0x1234567890123456789012345678901234567890 \
  --amount "20"

You can track the cross-chain transaction progress using the LayerZero Scan URL provided in the script output.

Development

The core logic is contained within the src directory. The main Client class can be imported and used in other TypeScript projects.

Building the Project

To compile the TypeScript code to JavaScript, run:

npm run build

This will output the compiled files to the dist directory.