ZeroRequiem

Privacy-preserving BNB transfers with gasless withdrawals on BNB Smart Chain

---

ZeroRequiem is a Privacy Layer on BSC smart chain which lets users send and receive BNB without creating a traceable on-chain link between sender and recipient. It combines ECDH stealth addresses with ERC-4337 account abstraction so that stealth wallets never need to receive gas from a known source.

---

Architecture & Workflow

How It Works:

1. Register — Recipient publishes stealth public keys to an on-chain registry (one-time)
2. Send — Sender deposits BNB into a shared vault targeting a one-time stealth address derived via ECDH
3. Scan — Recipient decrypts on-chain announcements with their viewing key to discover payments
4. Withdraw — Recipient submits an ERC-4337 UserOp; the Paymaster sponsors gas so the stealth wallet stays anonymous
5. Receive — BNB arrives in the recipient's wallet with zero on-chain link to the sender

---

Screenshots

Dashboard — wallet status, stealth key registration, relayer health, quick actions

Developer Documentation — tabbed SDK docs with code examples, API reference, and self-host guide

---

Documentation

Document	Contents
docs/PROJECT.md	Problem statement, solution, ecosystem impact, roadmap
docs/TECHNICAL.md	Architecture diagrams, setup instructions, demo guide
bsc.address	All deployed contract addresses with BSCScan links
sdk/README.md	SDK installation, API reference, integration examples
.env.example	Environment variable template with all required keys
docs/EXTRAS.md	Demo video and presentation links

---

Quick Start

cp .env.example .env              # Add deployer + relayer private keys

cd contracts && npm install
npx hardhat compile
npx hardhat run scripts/deploy.ts --network bscTestnet   # Deploy & copy addresses to .env

cd ../relayer && npm install
npx ts-node src/index.ts          # Start relayer on port 3001

cd ../frontend && npm install
npm run dev                       # Open http://localhost:5173

See docs/TECHNICAL.md for full setup and demo walkthrough.

---

SDK

Add private stealth payments to any dApp:

npm install zerorequiem-sdk

import { ZeroRequiem } from "zerorequiem-sdk";

const zr = new ZeroRequiem({ rpcUrl, chainId, vaultAddress, registryAddress,
  factoryAddress, entryPointAddress, paymasterAddress, relayerUrl });

await zr.registerKeys(signer, keys);                     // one-time setup
await zr.send(signer, recipientAddress, "0.01");          // send privately
const payments = await zr.scan(spendKey, viewKey);        // find payments
await zr.withdraw(stealthPrivKey, myWallet, "0.01");      // gasless withdraw

---

Project Structure

ZeroRequiem/
├── contracts/          Solidity: PrivacyVault, Paymaster, Registry, SimpleAccount
├── sdk/                TypeScript SDK: stealth addresses, ECDH, ERC-4337 UserOps
├── cli/                CLI tool: terminal-based stealth payments
├── relayer/            Express.js: Paymaster signer + ERC-4337 bundler
├── frontend/           React dashboard: send, receive, withdraw, activity
├── docs/               Project & technical documentation
├── assets/             Screenshots and logo
└── bsc.address         Deployed contract addresses (JSON)

---

CLI

Run stealth payments from your terminal:

cd cli && npm install && npm run build

Tip: Run node dist/index.js --help to see all available commands, or node dist/index.js <command> --help for detailed usage of any command.

Command	Description	Example
--help	List all commands and global options	node dist/index.js --help
status	Relayer health, Paymaster deposit, contract addresses	node dist/index.js status
register	Generate & register stealth keys on-chain (one-time)	node dist/index.js register -k 0xYOUR_KEY
send	Send BNB privately to a registered recipient	node dist/index.js send -t 0xTO -a 0.01 -k 0xKEY
scan	Scan for incoming stealth payments addressed to you	node dist/index.js scan --spend-key 0x... --view-key 0x...
withdraw	Gasless withdrawal from a stealth account via Paymaster	node dist/index.js withdraw --stealth-key 0x... -t 0xWALLET -a 0.01
balance	Check vault / wallet balance for any address	node dist/index.js balance --address 0xADDRESS

Global options (work with every command):

Flag	Description	Default
--rpc-url <url>	Custom BSC RPC endpoint	BSC Testnet public RPC
--relayer-url <url>	Custom relayer URL	https://zerorequiem-relayer.vercel.app
--help	Show help for any command	—

Full end-to-end example

# 1. Check system is healthy
node dist/index.js status

# 2. Recipient registers stealth keys (one-time)
node dist/index.js register -k 0xRECIPIENT_KEY
#    → Save the spending key and viewing key from the output!

# 3. Sender sends 0.01 BNB privately
node dist/index.js send -t 0xRECIPIENT_ADDR -a 0.01 -k 0xSENDER_KEY

# 4. Recipient scans for payments
node dist/index.js scan --spend-key 0xSPEND --view-key 0xVIEW

# 5. Recipient withdraws (gasless — Paymaster pays gas)
node dist/index.js withdraw --stealth-key 0xSTEALTH --to 0xWALLET -a 0.01

# 6. Verify balance
node dist/index.js balance --address 0xWALLET

---

Deployed Contracts (BSC Testnet)

Contract	Address
PrivacyVault	0xc02cE66D57b7dC05446c041864aCdCc23B94Ad48
StealthKeyRegistry	0x867E1c09B0aa3C79A171de8d20CA0C14Dd21fcAb
SimpleAccountFactory	0xaB885C2db018E3690269a91c9bDbdf53a5DC0614
ZeroRequiemPaymaster	0xe0fdDfa9f06c9E35eCDec67f2c7AFCB3Af0E439C
EntryPoint v0.6	0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789

---

Tech Stack

Smart Contracts	Backend	Frontend	Cryptography