block-chatr
v1.0.1
Published
Privacy-focused CLI Web3 chat on Sepolia Scroll Testnet
Downloads
4
Maintainers
techyarnavReadme
BlockChatr
A Web3 messaging system on Scroll Sepolia featuring a CLI and React frontend, secured with XChaCha20-Poly1305 encryption and supporting self-destructing messages.
Features - Installation - Usage - Architecture - Contributing
Overview
BlockChatr is a cutting-edge Web3 messaging CLI built on the Scroll Sepolia testnet, delivering uncompromised privacy through XChaCha20-Poly1305 encryption, ephemeral session contracts, and self-destructing messages. With its dual-layer privacy architecture, BlockChatr sets a new standard for secure, decentralized communication.
Beyond the CLI, BlockChatr also provides a React-based frontend, offering an intuitive web interface for sending and receiving encrypted, self-destructing messages. This ensures accessibility for both power users who prefer the CLI and everyday users who benefit from a sleek, user-friendly UI — all while maintaining the same robust privacy guarantees.
Features
End-to-End Encryption with XChaCha20-Poly1305 - Ensures robust, modern, and efficient encryption for secure message transmission.
Disposable Session Contracts - Messages are exchanged via ephemeral smart contracts that vanish after use.
Self-Destructing Messages - Messages expire after a defined block interval, ensuring time-bound confidentiality.
Built on Scroll Sepolia - Operates on Ethereum's Scroll testnet, providing rollup-level scalability and EVM compatibility.
CLI-First Experience - Minimalist, terminal-native interface built for privacy-focused developers and power users.
React frontend for end users (send/receive, view ephemeral messages, key management)
🛠 Tech Stack
| Category | Technology | Purpose | |----------------------|----------------------------------|---------------------------------------------| | Runtime | Node.js 18+ | JavaScript runtime environment | | Blockchain | Solidity ^0.8.19 | Smart contract development | | Development | Hardhat | Ethereum development framework | | Blockchain Library | Ethers.js v6 | Blockchain interaction | | Encryption | @stablelib/xchacha20poly1305 | Military-grade encryption | | Key Derivation | @stablelib/x25519 | ECDH key exchange | | CLI Interface | yargs | Command-line interface | | Styling | chalk | Terminal output formatting | | Network | Sepolia Scroll Testnet | Layer 2 testing environment |
📁 Project Structure
BlockChatr
│
├── contracts
│ ├── ChatContract.sol
│ └── ChatFactory.sol
├── hardhat.config.js
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── scripts
│ └── deploy.js
└── src
├── commands
│ ├── replay.js
│ ├── saved.js
│ └── send.js
├── config
│ └── networks.js
├── index.js
├── services
│ ├── blockchain.js
│ ├── encryption.js
│ ├── privacyManager.js
│ ├── sessionManager.js
│ └── wallet.js
└── utils
└── logger.jsGet Testnet ETH (Scroll Sepolia)
You can get Scroll Sepolia ETH from the following faucets:
Installation (via NPM)
Setup
# Install BlockChatr globally (recommended)
npm install -g block-chatr
# Or install locally in your project
npm install block-chatrEnvironment Configuration
# Contract addresses (pre-configured for Sepolia Scroll)
MAIN_CONTRACT_ADDRESS=0x47E0cc6b3Be7459e06f7a175771BfCD227E38A99
FACTORY_CONTRACT_ADDRESS=0x627C28aD9885951e3B1ffB2701B25f17d39bc33e
# Network configuration
DEFAULT_NETWORK=sepolia-scroll
# RPC Endpoint Options (Choose one - Remove # from your preferred option)
# Option 1: Alchemy (requires API key)
SCROLL_SEPOLIA_RPC=https://scroll-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY
# Option 2: PublicNode (free, no API key required)
# SCROLL_SEPOLIA_RPC=https://scroll-sepolia-rpc.publicnode.com/
# Option 3: Chainstack
# SCROLL_SEPOLIA_RPC=https://scroll-sepolia.chainstacklabs.com
# Option 4: Blast API
# SCROLL_SEPOLIA_RPC=https://scroll-sepolia.public.blastapi.io
# Option 5: dRPC
# SCROLL_SEPOLIA_RPC=https://scroll-sepolia.drpc.org
# Optional: Hardcode private key (not recommended)
# PRIVATE_KEY=your_private_key_here- Alternative: Environment Variables (No .env file needed)
export MAIN_CONTRACT_ADDRESS=0xA5E1D617229F3bd385AD6d71DcFf53e623dF6caA
export FACTORY_CONTRACT_ADDRESS=0xc533a69D28f2Ecdad06797DCa200a749eDf781dd
export DEFAULT_NETWORK="sepolia-scroll"Help Command
block-chatr --helpSend a standard message
block-chatr --to "0x742d35..." --message "Hello World"Send a private session message
block-chatr --to "0x742d35..." --message "Hello World , Session Message" --sessionSend an expiring message (5 minutes)
block-chatr --to "0x742d35..." --message "This message expires in 5 minutes" --expiry 120Replay Messages
List Wallets
block-chatr --list-wallets- Interactive Wallet Management - BlockChatr automatically launches an interactive wallet selection when no saved wallets are found:
🔐 BlockChatr Wallet Selection
💼 No saved wallets found
1. Enter private key
2. Generate new wallet
Select option: 1
🔑 Enter your private key (input will be hidden):
💾 Save this wallet? (y/N): y
📝 Enter wallet alias: wallet1
💾 Wallet saved as "wallet1"- Example Session Flow - Sender (Wallet1) → Recipient (Wallet2):
# 1. Send messages from sender
export SCROLL_SEPOLIA_RPC="https://scroll-sepolia.g.alchemy.com/v2/YOUR_KEY"
block-chatr --to "0xRecipient..." --message "Testing npm package with env vars"
block-chatr --to "0xRecipient..." --message "Secret npm package message" --session
block-chatr --to "0xRecipient..." --message "This expires in 2 minutes" --expiry 120
# 2. View from recipient perspective
block-chatr --replay "0xSender..."
Expected Output:- Network Configuration - The package is pre-configured for Sepolia Scroll Testnet
Usage
Basic Commands
- Send a standard message
block-chatr --to "0x742d35..." --message "Hello, Web3!"- Send a private session message
block-chatr --to "0x742d35..." --message "Private Session message" --session- Send an expiring message (5 minutes)
block-chatr --to "0x742d35..." --message "This will self-destruct in 5 minutes" --expiry 300- Send a session message that expires in 2 minutes
block-chatr --to "0x742d35..." --message "Message expires in 2 mins and session will self destruct in one hour" --session --expiry 120- View conversation history
block-chatr --replay "0x742d35..."- List saved wallets
block-chatr --list-wallets- Delete a saved wallet
block-chatr --delete-wallet myWallet- Display help
block-chatr --help🏗 Architecture
System Overview
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CLI Client │ │ Smart Contracts│ │ Scroll Network │
│ │ │ │ │ │
│ • Wallet Mgmt │◄──►│ • ChatContract │◄──►│ • Sepolia L2 │
│ • Encryption │ │ • ChatFactory │ │ • Gas Optimized │
│ • Session Mgmt │ │ • ChatSession │ │ • Fast Finality │
└─────────────────┘ └─────────────────┘ └─────────────────┘Core Components
1. Smart Contracts
ChatContract: Main messaging contract for standard messages
ChatFactory: Creates and manages disposable session contracts
ChatSession: Individual private session with 1-hour auto-expiry
2. Encryption Layer
XChaCha20-Poly1305: Authenticated encryption for message content
ECDH Key Exchange: Secure shared secret generation
3. Session Management
1-Hour Auto-Expiry: Sessions automatically become inactive
Smart Reuse: Existing sessions used if under 1 hour old
Automatic Cleanup: New sessions created when old ones expire
4. Privacy Layers
Message Privacy Stack:
├── 🔐 XChaCha20-Poly1305 Encryption
├── 🕐 Session Contract Isolation (1-hour disposal)
├── ⏰ Message-Level Expiry (custom timeframes)
└── 🌐 Scroll Layer 2 (enhanced privacy)🤝 Contributing - We welcome contributions! Please see our Contributing Guide for details.
Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add features')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
⭐️ Star this repository if you find it useful!
Built with ❤️ for Web3 Privacy
Powered by XChaCha20-Poly1305 encryption, Solidity smart contracts , React and Node.js
