xcm-lib-zkverify/README.md

XCM asset teleportation and remote EVM calls for ZKVerify

# 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

```bash
npm install
```

## Local Development Setup

### Start Local Networks

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

```bash
# 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:

```typescript
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
```typescript
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
```typescript
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
```typescript
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)
```typescript
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:

```bash
# 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:
```bash
./scripts/local-networks.sh setup
```

### Run Tests
```bash
# 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)