- Demo Videos
- Introduction
- System Architecture
- Key Components
- Cryptographic Workflows
- Technical Implementation
- Cross-Chain Functionality
- Getting Started
- Benchmarks
- User Story
- Contributing
- License
- Acknowledgements
zk-lokomotive is an advanced, zero-knowledge proof-based file transfer system designed to operate seamlessly across multiple blockchain networks, including EVM-compatible chains, Solana, and Sui. By leveraging state-of-the-art zero-knowledge cryptography, Arweave for decentralized storage, and Wormhole for cross-chain interoperability, zk-lokomotive provides an unparalleled solution for secure, private, and efficient file transfers in a trustless environment.
The zk-lokomotive system architecture is designed with modularity, scalability, and cross-chain interoperability at its core. Below is a detailed breakdown of the system components and their interactions:
Our system is built on three core components:
- Key Derivation Service (KDS): This service generates deterministic Curve25519 keypairs from BIP-39 mnemonics.
- Cross-chain Identity Registry (CCIR): This serves as a decentralized identity and public key management system.
- Encrypted File Storage (EFS): We use Arweave to provide decentralized and persistent file storage.
Our file transfer process works as follows:
- The user encrypts and uploads the file.
- The file hash is transmitted to the target chain via Wormhole.
- The recipient receives the file hash and verifies the signature.
- The recipient reads and decrypts the file from Arweave.
Our project is capable of operating across different blockchains such as Ethereum, Solana, and Sui, leveraging Wormhole for cross-chain functionality.
The KDS is a crucial component that provides:
- A deterministic Curve25519 keypair generator derived from BIP-39 mnemonics
- A pseudo-random BIP-39 mnemonic generator utilizing the web-bip-39 package
This service ensures consistent and secure key generation across different platforms and devices.
The CCIR serves as a decentralized identity and public key management system. It allows:
- Lookup of identities across different blockchain networks
- Retrieval of corresponding public keys for secure communications
The EFS is a distributed storage solution that:
- Allows recipients to retrieve encrypted payloads uploaded for them
- Utilizes Arweave for decentralized and persistent file storage
- Ensures data privacy through encryption before storage
The client component is responsible for:
- Generating encrypted payloads for recipients
- Retrieving recipient public keys via the CCIR
- Initiating the file transfer process
The process of sending an encrypted file involves several cryptographic operations to ensure security and privacy. Below is a detailed workflow:
Symbol | Description |
---|---|
K_r | Recipient's public key on Curve25519 |
K_e | A symmetric key derived for the file to be sent (256 bits) |
E(K_e) | The symmetric key, encrypted using ECIES |
F | The file contents, in plaintext |
F_c | The file contents, in ciphertext |
IV | The initialization vector required for AES-GCM-256 |
P | The payload, what is sent to the recipient |
- Retrieve the recipient's public key (K_r) from the CCIR.
- Generate a random symmetric key (K_e) for the file (F).
- Encrypt the file (F) using AES-GCM-256 with the encryption key (K_e) and a randomly generated initialization vector (IV), resulting in ciphertext (F_c).
- Encrypt the symmetric key (K_e) using ECIES, resulting in E(K_e).
- Create the payload (P) by concatenating F_c, IV, and E(K_e).
- Upload the payload (P) to the Encrypted File Storage (EFS).
Elliptic Curve Integrated Encryption Scheme (ECIES) is used for secure key exchange. The process involves:
- Generate an ephemeral key pair on Curve25519.
- Perform Diffie-Hellman key exchange with the recipient's public key.
- Derive a shared secret using HKDF-SHA256.
- Encrypt the symmetric key using AES-GCM with the derived shared secret.
pragma solidity ^0.8.13;
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "./interfaces/IWormhole.sol";
contract WormholeMessenger is Ownable {
using SafeERC20 for IERC20;
IWormhole public wormhole;
uint16 public targetChain;
uint256 public nextSequence;
IERC20 public wormholeToken;
event HashSent(address indexed sender, bytes32 hash, uint64 sequence);
event BridgeContractSet(uint16 chainId, bytes32 newBridgeContract);
mapping(uint16 => bytes32) public bridgeContracts;
constructor(address _wormhole, uint16 _targetChain, address _wormholeToken) {
wormhole = IWormhole(_wormhole);
targetChain = _targetChain;
wormholeToken = IERC20(_wormholeToken);
}
'use client';
import { useState } from 'react';
import Arweave from 'arweave';
const arweave = Arweave.init({
host: 'arweave.net',
port: 443,
protocol: 'https',
});
export default function FileUpload({ onUpload, walletKey }) {
const [file, setFile] = useState(null);
const [loading, setLoading] = useState(false);
const handleFileChange = (e) => {
setFile(e.target.files[0]);
};
const handleUpload = async () => {
if (!file || !walletKey) return;
setLoading(true);
const reader = new FileReader();
reader.readAsArrayBuffer(file);
reader.onloadend = async () => {
const data = new Uint8Array(reader.result);
const transaction = await arweave.createTransaction({ data }, walletKey);
transaction.addTag('Content-Type', file.type);
await arweave.transactions.sign(transaction, walletKey);
const response = await arweave.transactions.post(transaction);
if (response.status === 200) {
const txId = transaction.id;
const imageUrl = `https://arweave.net/${txId}`;
onUpload(imageUrl);
} else {
console.error('Failed to upload file to Arweave');
}
setLoading(false);
};
};
return (
<div>
<input type="file" onChange={handleFileChange} />
<button onClick={handleUpload} disabled={!file || loading}>
{loading ? 'Uploading...' : 'Upload to Arweave'}
</button>
</div>
);
}
zk-lokomotive leverages Wormhole for seamless cross-chain file transfers. Here's an overview of the process:
- File Tokenization: The encrypted file is tokenized on the source chain.
- Wormhole Bridge: The tokenized file is transferred through Wormhole's bridge.
- Cross-Chain Verification: ZK proofs are verified on the destination chain.
- File Retrieval: The recipient retrieves and decrypts the file using their private key.
- Node.js (v14+)
- Rust (latest stable) or
nightly
- Solana CLI
- Anchor Framework
- Ethereum development environment (Hardhat or Truffle)
-
Clone the repository:
git clone https://github.com/zk-Lokomotive/zk-lokomotive.git cd zk-lokomotive
-
Install dependencies:
npm install
-
Set up Solana environment:
sh -c "$(curl -sSfL https://release.solana.com/v1.18.4/install)" solana --version
-
Install Anchor:
cargo install --git https://github.com/coral-xyz/anchor anchor-cli --locked anchor --version
-
Build the project:
cd tokenswap_contract anchor build
-
Run tests:
anchor test
To run cryptographic benchmarks:
git clone https://github.com/briansmith/crypto-bench && cd crypto-bench
cargo update && cargo +nightly bench
Implementation | ECDH (Suite B) key exchange |
---|---|
ring | ✅ |
rust-crypto | |
rust-nettle | |
rust-openssl | |
sodiumoxide | |
Windows CNG | |
Common Crypto |
As a user of the ZKL-Last platform, I want to securely transfer tokens and send messages between Ethereum and Solana blockchains using Wormhole's cross-chain interoperability protocol.
-
Ethereum to Solana Transfer:
- I can connect my Ethereum wallet (e.g., MetaMask) to the ZKL-Last dApp.
- I can select an ERC20 token and specify an amount to transfer.
- I can enter a Solana recipient address.
- I can include an optional message with my transfer.
- The dApp initiates a Wormhole core bridge contract call on Ethereum.
- A Verifiable Action Approval (VAA) is generated by the Guardian network.
- The transfer is completed on Solana, with the recipient receiving equivalent SPL tokens.
-
Solana to Ethereum Transfer:
- I can connect my Solana wallet (e.g., Phantom) to the ZKL-Last dApp.
- I can select an SPL token and specify an amount to transfer.
- I can enter an Ethereum recipient address.
- I can include an optional message with my transfer.
- The dApp initiates a Wormhole core bridge program call on Solana.
- A VAA is generated by the Guardian network.
- The transfer is completed on Ethereum, with the recipient receiving equivalent ERC20 tokens.
-
Message Passing:
- I can send arbitrary messages between Ethereum and Solana without token transfers.
- Messages are securely transmitted and verified using Wormhole's VAA mechanism.
-
Transaction Monitoring:
- I can view the status of my cross-chain transactions in real-time.
- The dApp shows me when the VAA is generated and when it's redeemed on the target chain.
-
Security Features:
- All transactions require my explicit approval through wallet signatures.
- The dApp uses Wormhole's consistency levels to ensure finality before completing transfers.
- I receive clear warnings about the irreversibility of cross-chain transactions.
-
Error Handling:
- If a transaction fails at any stage, I receive a clear error message explaining the issue.
- The dApp provides guidance on how to resolve common errors (e.g., insufficient gas, network congestion).
-
Smart Contract Integration:
- Deploy ZKL-Last contracts on Ethereum that interact with Wormhole's core bridge contract.
- Implement a Solana program that interacts with Wormhole's core bridge program.
- Use Wormhole's
publishMessage
function to emit cross-chain messages.
-
Token Bridge Usage:
- Integrate Wormhole's token bridge for asset transfers between chains.
- Implement token locking on the source chain and minting on the target chain.
-
VAA Handling:
- Implement VAA retrieval from Wormhole's Guardian network.
- Verify VAA signatures using Wormhole's
parseAndVerifyVM
function.
-
Relayer Integration:
- Implement a relayer service to automatically submit VAAs to the target chain.
- Use Wormhole's Generic Relayer for standard transfers.
- Implement a specialized relayer for custom logic if required.
-
Wormhole Connect Integration:
- Integrate Wormhole Connect UI components for a seamless user experience.
- Customize Wormhole Connect to fit ZKL-Last's branding and specific requirements.
-
Chain-Specific Implementations:
- For Ethereum: Use ethers.js for contract interactions and transaction signing.
- For Solana: Use @solana/web3.js and @project-serum/anchor for program interactions.
-
Security Considerations:
- Implement proper access controls in smart contracts and Solana programs.
- Use Wormhole's emitter filtering to ensure messages are only accepted from trusted sources.
- Implement replay protection to prevent double-spending attacks.
-
Testing and Auditing:
- Develop comprehensive test suites for both Ethereum and Solana components.
- Conduct thorough security audits of all smart contracts and programs.
- Perform end-to-end testing of the entire cross-chain transfer process.
- Baturalp Güvenç - Fullstack Blockchain Developer
This project is licensed under the MIT License - see the LICENSE.md file for details.
Encode Project ID: f8zlq506ekpdpdnjxf8zlysubo9pi2a0
- Wormhole for cross-chain interoperability
- Arweave for decentralized storage
- Solana for high-performance blockchain infrastructure
- Ethereum for smart contract capabilities
- Celestia for data availability solutions
- Solana Renaissance Hackathon Wormhole Best Multichain Track Winner (1st Place) - April 2024 🥇
- Sui Overflow Local Track Winner (1st Place) - May 2024 🥇
- Solana Minihackathon (1st Place) - March 2024 🥇
- Solana Demoday (2nd Place) - March 2024 🥈
- EDCON Japan (Finalist) - May 2024
- Maybe Encode Hackathon - Aug 2024 🤫
For more information, please visit our official website