Memora CLI

A Bitcoin CLI application for sending and receiving OP_RETURN messages on the Bitcoin blockchain with comprehensive wallet management.

Features

• OP_RETURN Messaging: Send and receive messages embedded in Bitcoin transactions
• Bitcoin Payments: Send Bitcoin with customizable fees
• Composite Transactions: Send Bitcoin payments with embedded OP_RETURN messages
• Wallet Management: Multiple wallet support with WIF keys
• Contact Management: Address book with name-to-address resolution
• Transaction Labels: Categorize and label transactions
• UTXO Management: Freeze, preserve, or prioritize specific UTXOs
• Notes System: Add notes to transactions or addresses
• Data Export/Import: Backup and restore wallet data

Installation

1. Install Bun (if not already installed):

   curl -fsSL https://bun.sh/install | bash

2. Install dependencies:

   bun install

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Configure your wallet WIF keys:

# Primary wallet
WIF_KEY_1=your_wif_private_key_here

# Secondary wallet (optional)
WIF_KEY_2=your_second_wif_private_key_here

# Environment (development/production)
NODE_ENV=development

Getting Testnet Bitcoin

To get testnet Bitcoin for testing:

1. Visit a testnet faucet like https://coinfaucet.eu/en/btc-testnet/
2. Send testnet Bitcoin to your wallet address (run bun run dev -- balance to get your address)

Usage

Basic Commands

# Show help
bun run dev -- --help

# Check wallet balance
bun run dev -- balance

# Send an OP_RETURN message
bun run dev -- message "Hello Bitcoin!"

# List all messages from your wallet
bun run dev -- messages

# Read a message from transaction
bun run dev -- read <transaction_id>

# Send Bitcoin to an address
bun run dev -- send <address> <amount>

# Send Bitcoin with an embedded message
bun run dev -- send <address> <amount> --message="Thank you!"

Wallet Management

# Add a contact
bun run dev -- contacts add "João" "tb1qar0s..."

# List all contacts
bun run dev -- contacts list

# Send Bitcoin to a contact by name
bun run dev -- send "João" 1000

# Search contacts
bun run dev -- contacts search "João"

Transaction Labels

# Add a label to a transaction
bun run dev -- labels add <txid> "Freelance Payment" --category=income

# List all labels
bun run dev -- labels list

# Search labels
bun run dev -- labels search "payment"

UTXO Management

# Freeze a UTXO (prevent spending)
bun run dev -- utxo freeze <txid> <vout> "Save for future"

# List frozen UTXOs
bun run dev -- utxo frozen

# Unfreeze a UTXO
bun run dev -- utxo unfreeze <txid> <vout>

Notes Management

# Add a note to a transaction
bun run dev -- notes add "Important transaction" --txid=<txid>

# List all notes
bun run dev -- notes list

Data Management

# Export all wallet data
bun run dev -- export > wallet-backup.json

# Import wallet data
bun run dev -- import < wallet-backup.json

Development

Running in Development Mode

bun run dev -- <command>

Type Checking

npm run check-types

Watching for Type Errors

npm run check-types:watch

Architecture

The project follows clean architecture principles:

• Entities: Core business objects (Wallet, Transaction, UTXO, etc.)
• Application: Business logic and use cases (WalletService, etc.)
• Infrastructure: External services (BitcoinService, BlockstreamApiService, etc.)
• Storage: SQLite database for persistence
• View: CLI controller and user interface

Technology Stack

• Runtime: Bun (JavaScript/TypeScript)
• Bitcoin Library: bitcoinjs-lib
• Database: Bun's built-in SQLite
• Network: Bitcoin Testnet (development) / Mainnet (production)

Environment Variables

• WIF_KEY_1, WIF_KEY_2, etc. - Wallet private keys
• NODE_ENV - Environment (development/production)
• BLOCKCHAIN_API - Blockchain API endpoint
• BLOCKCHAIN_EXPLORER - Blockchain explorer URL

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run type checking: npm run check-types
5. Test your changes thoroughly
6. Submit a pull request

License

This project is open source and available under the MIT License.

Support

For issues and questions, please create an issue in the GitHub repository.