/zkRamp

🏆 Winner Project at AlephZero Hackathon: zkRamp is a protocol that aims to quickly and efficiently provide onramp/offramp solutions using zero-knowledge proofs.

Primary LanguageTypeScriptGNU General Public License v3.0GPL-3.0

◦ Don't waste your time with KYC, use ZKRamp.

📖 Table of Contents

📍 Overview

The goal is to create a liquidity marketplace where users can directly transfer funds without the requirement of KYC, based on ZK-Email technology. This eliminates the need for the ramp to function as an intermediary.

The steps are simple:

  • The seller escrows funds to the smart contract, sets a price, and adds their payment key (Wise). A collateral is collected to ensure the token transfer to the buyer.
  • The buyer selects a liquidity pool to make a purchase. An intermediate state is established, and the buyer has 1 hour to make the off-chain payment.
  • Upon receiving the email notification, the buyer uploads the email notification, creates the ZK proof, and submits it via our ZK API process.
  • The ZK API verifies the proof and the funds are transferred to the buyer.

Architecture

ZKRamp uses Zero-Knowledge (ZK) proofs to verify DKIM signatures in payment confirmation emails. Therefore, users must have notification emails enabled in their payment providers. This technology is powered by ZK-Email, a new technology that utilizes regex and other email features to create ZK proofs. Currently, we do not store the ZK proof on-chain. The entire ZK process is conducted through an API.

Tech Stack:

  • Circuits: Responsible for verifying transaction details, and preserving the confidentiality of confidential information.
  • Smart Contracts: Smart contracts enable trustless transactions and handle the protocol's logic.
  • Front-end: The UI serves as the front end that enables users to interact with the protocol.

🛣 Roadmap

  • ℹ️ Implement ZKEmail circuit
  • ℹ️ Implement AlephZero smart contract
  • ℹ️ Implement front-end UI
  • ℹ️ Implement support to Wise
  • [] ℹ️ Implement ZK validator on-chain
  • [] ℹ️ Implement support to Brazil PIX
  • [] ℹ️ Implement support to Vemno
  • [] ℹ️ Implement support to Canada Interac

🚀 Getting started

1. Run the frontend

The frontend works out of the box, without a local node running, as the sample contract is pre-deployed on certain live testnets (i.e. alephzero-testnet and shibuya). Necessary deployment metadata and addresses are provided under contracts/deployments/.

Pre-requisites:

  • Setup Node.js v18+ (recommended via nvm with nvm install 18)
  • Install pnpm (recommended via Node.js Corepack or npm i -g pnpm)
  • Clone this repository
Special Instructions for Windows Users

[!IMPORTANT]
Windows users must either use WSL (recommended) or a custom shell like Git Bash. PowerShell is not supported.

Pre-requisites when using WSL for Linux:

  • Install WSL and execute all commands in the WSL terminal
  • Setup Node.js v18+ (recommended via nvm with nvm install 18)
  • Install the following npm packages globally:
  • npm i -g npm
  • npm i -g pnpm node-gyp make
  • Clone this repository into the WSL file system (e.g. /home/<user>/inkathon).

Tip: You can enter \\wsl$\ in the top bar of the Windows Explorer to access the WSL file system visually.

# Install dependencies (once)
# NOTE: This automatically creates an `.env.local` file
pnpm install

# Start Next.js frontend
pnpm run dev

Optionally, to enable simple-git-hooks (for automatic linting & formatting when committing), you can run the following command once: pnpm simple-git-hooks.

2. Build & deploy contracts on a local node

The contracts/package.json file contains shorthand scripts for building, testing, and deploying your contracts. To run these scripts, you need to set contracts/ as the active working directory in your terminal.

Pre-requisites:

# Build contracts and move artifacts to `contracts/deployments/{contract}/` folders
pnpm run build

# Start local node with persistence (contracts stay deployed after restart)
# NOTE: When using Brave, shields have to be taken down for the UIs
pnpm run node

## IMPORTANT: Open a separate terminal window and keep the node running

# Deploy the contracts on the local node
pnpm run deploy

Contract Deployment

In the Getting Started section above, we've already deployed the sample Greeter contract on a local node. To target a live network, we can use the CHAIN environment variable when running the deploy script.

CHAIN=alephzero-testnet pnpm run deploy

Further, dynamically loaded environment files with the .env.{chain} naming convention can be used to add additional configuration about the deployer account.

# .env.alephzero-testnet
ACCOUNT_URI=bottom drive obey lake curtain smoke basket hold race lonely fit walk//Alice

When running the same script again, this deployer account defined there will be used to sign the extrinsic.

Warning

These files are gitignored by default, but you should still be extra cautious when adding sensitive information to them.

Acknowledgments

This project was inspired by the idea from ZKP2P.