zkVerify XCM Library

A production-ready TypeScript library for cross-chain interactions between zkVerify Relay Chain and EVM parachains, featuring asset teleportation, remote EVM contract calls, and comprehensive testing infrastructure.

Features

• 🔄 Asset Teleportation: Bidirectional asset transfer between Relay Chain and EVM parachains
• 🚀 Remote EVM Calls: Execute smart contract functions on EVM parachains from Relay Chain via XCM
• 🎯 ABI Support: Execute contract calls using either source code compilation or direct ABI
• 🌐 Local Networks: Automated setup of local zkVerify networks for development and testing

Installation

npm install

Local Development Setup

Start Local Networks

For testing and development, you can run local zkVerify networks:

# First time setup (clones repos, builds relay chain, starts networks)
./scripts/local-networks.sh setup

# Start existing networks (after initial setup)
./scripts/local-networks.sh start

# Clean up all local network files
./scripts/local-networks.sh cleanup

Network Endpoints:

• Relay Chain: ws://127.0.0.1:8855
• Parachain: ws://127.0.0.1:8833

Configuration

The library uses a unified XcmConfig interface for all operations. You only provide the fields needed for your specific use case:

interface XcmConfig {
  // Endpoints - provide based on operation needs
  relayWsEndpoint?: string;
  evmParachainWsEndpoint?: string;
  evmParachainId?: number;
  
  // Private keys - provide based on operation type
  relayPrivateKey?: string;
  evmParachainPrivateKey?: string;
  
  // Optional XCM versions (with defaults)
  xcmRelayVersion?: string;      // defaults to V5
  xcmParachainVersion?: string;  // defaults to V2
}

Operation Requirements

• Relay→Parachain: Requires relayPrivateKey + relayWsEndpoint + evmParachainId
• Parachain→Relay: Requires evmParachainPrivateKey + evmParachainWsEndpoint
• Remote EVM Calls: Requires both endpoints + relayPrivateKey + evmParachainId

Usage Examples

1. Asset Teleportation

Relay to Parachain

import { XcmTeleportService } from './src/services/xcm-teleport';

const config = {
  relayWsEndpoint: 'ws://127.0.0.1:8855',
  evmParachainWsEndpoint: 'ws://127.0.0.1:8833', // For balance queries
  evmParachainId: 1,
  relayPrivateKey: 'e5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a'
};

const service = new XcmTeleportService(config);
await service.initialize();

const result = await service.teleportToEvmParachain({
  amount: '1000000000000',
  destinationAddress: '0x1234567890123456789012345678901234567890'
});

await service.disconnect();

Parachain to Relay

const config = {
  relayWsEndpoint: 'ws://127.0.0.1:8855',     // For balance queries
  evmParachainWsEndpoint: 'ws://127.0.0.1:8833',
  evmParachainPrivateKey: 'cea930a090279ff8f832e550e45fd6f7c3f88f729dcad79e2a9dcbc0514111df'
};

const service = new XcmTeleportService(config);
await service.initialize();

const result = await service.teleportFromEvmParachain({
  amount: '1000000000000',
  destinationAddress: '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY' // Substrate address
});

await service.disconnect();

2. Remote EVM Calls

Execute smart contract functions on EVM parachains from the Relay Chain via XCM:

Using Contract Source Code

import { ExecuteRemoteEvmCallService } from './src/services/execute-remote-evm-call';

const config = {
  relayWsEndpoint: 'ws://127.0.0.1:8855',
  evmParachainWsEndpoint: 'ws://127.0.0.1:8833',
  evmParachainId: 1,
  relayPrivateKey: 'e5be9a5092b81bca64be81d212e7f2f9eba183bb7a90954f7b76361f6edb5c0a'
};

const service = new ExecuteRemoteEvmCallService(config);
await service.initialize();

const result = await service.executeRemoteEvmCall(
  {
    contractAddress: '0x1234567890123456789012345678901234567890',
    functionName: 'doWork',
    args: [42],
    gasLimit: '100000',
    value: '0'
  },
  './contract/test_contract.sol'  // Contract source path
);

await service.disconnect();

Using Direct ABI (Faster)

const result = await service.executeRemoteEvmCall(
  {
    contractAddress: '0x1234567890123456789012345678901234567890',
    functionName: 'doWork',
    args: [42]
  },
  undefined,                          // No contract path
  './contract/test_contract_abi.json' // Direct ABI path (takes precedence)
);

Environment Configuration

The library provides example environment files for different use cases. Copy the appropriate example file and update the values as needed:

# For relay to parachain transfers
cp .env.example.relay-to-parachain .env.relay-to-parachain

# For parachain to relay transfers  
cp .env.example.parachain-to-relay .env.parachain-to-relay

# For remote EVM calls
cp .env.example.execute-remote-evm-call .env.execute-remote-evm-call

Each example file contains all the necessary configuration options with comments explaining their purpose.

Testing

Prerequisites

Start local networks before running tests:

./scripts/local-networks.sh setup

Run Tests

# Run all tests
npm test

# Run specific tests
npm test -- relay-to-evm.test.ts
npm test -- evm-to-relay.test.ts
npm test -- execute-remote-evm-call.test.ts

# Build project
npm run build

Requirements

• Node.js 18+
• Rust & Cargo (for building local relay chain)
• Git (for cloning repositories)