HWCW Bot - Matrix Financial Transaction Bot

A Matrix bot designed to handle financial transaction templates (上押/加押/下押) with automatic data storage and management capabilities. Built with simplematrixbotlib for easy setup without encryption dependencies.

🚀 Features

• Template Processing: Supports three types of financial transaction templates:
  • 🟢 上押 (Initial Deposit)
  • 🟡 加押 (Additional Deposit)
  • 🔵 下押 (Withdrawal)
• Automatic Data Storage: All transactions are automatically saved in JSON format
• Manual Management: Automatically pins usage instructions to the Matrix room
• Expense Tracking: Built-in expense tracking system
• Data Export: Export all transaction data with !导出 command
• Data Management: Clear data with !清除 command
• Session Persistence: Maintains Matrix session across restarts
• No Encryption Required: Uses simplematrixbotlib - no libolm or encryption dependencies
• Easy Setup: Simple configuration with minimal dependencies

📋 Prerequisites

• Python 3.11 or higher
• A Matrix homeserver account (e.g., matrix.org, element.io)
• Access to a Matrix room where the bot will operate
• No encryption setup required (bot uses simplematrixbotlib)

🛠️ Installation

Quick Setup (Recommended)

Run the automated setup script:

git clone https://github.com/your-username/hwcw-bot.git
cd hwcw-bot
./setup.sh

The script will:

• Check Python version requirements
• Create a virtual environment
• Install dependencies (simplematrixbotlib and requests)
• Set up configuration template
• Provide next steps

Method 1: Local Setup

1. Clone the repository

   git clone https://github.com/your-username/hwcw-bot.git
   cd hwcw-bot

2. Create virtual environment

   python3 -m venv .venv
   source ./.venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

   Note: This bot uses simplematrixbotlib which has minimal dependencies and doesn't require encryption libraries like libolm or _libolm that can cause installation issues.

4. Configure environment

   cp .env.example .env
   # Edit .env with your Matrix credentials

5. Run the bot

   python bot.py

Method 2: Docker

1. Clone and build

   git clone https://github.com/your-username/hwcw-bot.git
   cd hwcw-bot
   docker build -t hwcw-bot .

2. Run with Docker

   docker run -d --env-file .env --name hwcw-bot hwcw-bot

⚙️ Configuration

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

# Matrix homeserver URL
MATRIX_HOMESERVER=https://matrix.org

# Your bot's Matrix user ID
MATRIX_USER_ID=@your-bot:matrix.org

# Bot's password
MATRIX_PASSWORD=your-secure-password

# Room ID where the bot operates
MATRIX_ROOM_ID=!your-room-id:matrix.org

Getting Matrix Credentials

1. Create a Matrix account on your preferred homeserver (e.g., matrix.org)
2. Get Room ID: In Element (or your Matrix client), go to Room Settings → Advanced → Copy "Internal room ID"
3. Invite the bot to your room and give it appropriate permissions

Security Note: The bot uses password authentication for simplicity. For production deployments, consider using access tokens instead.

📝 Usage Templates

🟢 上押 (Initial Deposit)

#工号 123
#群号 专群 456
#上押 1000U 供方
请查收
用户TGid：123456789

🟡 加押 (Additional Deposit)

#工号 123
#群号 专群 456
#加押 500U 需方
请查收
用户TGid：987654321

🔵 下押 (Withdrawal)

#工号 123
#群号 专群 456
#手续费 10U 供方
#下押 1000U 供方
#地址 T9xxxxxxxxxxxxxxxxxxxxxx

🤖 Bot Commands

Command	Description
!导出	Export all transaction data
!清除	Clear all expense records
!更新说明	Update and re-pin usage manual (admin only)

📊 Data Structure

The bot stores transaction data in the following format:

{
  "时间": "2025-01-01 12:00",
  "发送者": "@user:matrix.org",
  "类型": "上押",
  "工号": "123",
  "群号": "456",
  "金额": 1000.0,
  "角色": "供方",
  "用户TGid": "123456789"
}

🗂️ File Structure

hwcw-bot/
├── bot.py              # Main bot application
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker configuration
├── .env.example       # Environment template
├── .gitignore         # Git ignore rules
├── LICENSE            # MIT License
├── README.md          # This file
├── MANUAL.md          # Usage manual (Chinese)
├── START.md           # Quick start guide
├── data.json          # Transaction data (auto-generated)
├── expenses.json      # Expense data (auto-generated)
├── session.json       # Matrix session (auto-generated)
├── sync_token.json    # Sync token (auto-generated)
└── manual.json        # Manual state (auto-generated)

🔒 Security Considerations

• Never commit .env files - Contains sensitive credentials
• Session files are automatically generated and should not be shared
• Data files contain transaction information and should be backed up securely
• Use strong passwords for Matrix accounts
• Consider using Matrix access tokens instead of passwords for production

🛠️ Development

Dependencies

This project uses:

• simplematrixbotlib: Lightweight Matrix bot library without encryption dependencies
• requests: HTTP library for API calls
• python-dotenv: Environment variable management

Adding New Features

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Style

• Follow PEP 8 Python style guidelines
• Use meaningful variable names
• Add comments for complex logic
• Update documentation when adding features

🐛 Troubleshooting

Common Issues

1. Login Failed

   • Check Matrix credentials in .env
   • Verify homeserver URL is correct
   • Ensure bot account exists and password is correct

2. Room Access Denied

   • Verify the bot is invited to the room
   • Check room ID format: !roomid:homeserver.com
   • Ensure bot has necessary permissions

3. Template Not Recognized

   • Check template format matches examples exactly
   • Ensure all required fields are present
   • Verify amounts end with 'U' (e.g., 1000U)

4. Installation Issues

   • This bot uses simplematrixbotlib to avoid encryption dependencies
   • If you encounter issues, try creating a fresh virtual environment
   • Ensure Python 3.11+ is installed

Why simplematrixbotlib?

This project switched from matrix-nio[e2e] to simplematrixbotlib to avoid common installation issues:

• No libolm dependency: Eliminates complex C library compilation
• No encryption setup: Simpler for basic bot functionality
• Fewer dependencies: Easier installation and deployment
• Better cross-platform support: Works reliably on macOS, Linux, and Windows

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📞 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section
2. Search existing GitHub issues
3. Create a new issue with detailed information

🙏 Acknowledgments

• Built with simplematrixbotlib for easy Matrix bot development
• Inspired by the need for automated financial transaction tracking
• Thanks to the Matrix community for the excellent protocol and tools

---

Note: This bot is designed for specific financial transaction workflows. Please ensure compliance with your organization's policies and applicable regulations when handling financial data.