quali-chat-core

A headless Matrix integration for quali.chat with token-gated access based on on-chain balances. It uses pluggable blockchain adapters (currently Ethereum via Alchemy) to stream native and ERC-20 balance updates, caches token metadata in Redis, and manages Matrix room creation, membership, and power levels via Synapse admin APIs with end-to-end encryption.

Local Setup

Requirements

• Up-to-date Node.js and Docker installed
• Alchemy API key (get one here)
• Matrix server setup as documented in quali-chat/synapse-homeserver-patch

Setup Guide

1. Install dependencies:

   npm i

2. Copy .env.example to .env and fill in ALCHEMY_API_KEY (and any other needed variables).
3. Start a local Redis instance:

   docker run --name redis -p 6379:6379 -d redis

4. Start the service with file watching:

   npm run dev

E2EE Support

The bot supports End-to-End Encrypted (E2EE) messages. For production, be sure to persist the following:

• BOT_STORAGE_FILE: Path to the file where the bot stores its encryption state.
• BOT_ENCRYPTION_DIR: Directory for additional encryption data.

Set these in your .env file to ensure encrypted message support and safe recovery after restarts or migrations.

Overview

This document provides a comprehensive guide on the integration with OIDC providers and the steps taken to ensure compatibility with multiple blockchain wallets.

Integration Architecture

Authentication Flow

1. User initiates authentication through quali.chat interface
2. User is redirected to the OIDC provider for wallet-based authentication
3. After successful authentication, OIDC provider returns tokens to quali.chat
4. quali.chat validates tokens and establishes a user session

Components Interaction

• quali-chat-core: Main application handling Matrix protocol integration
• oidc-provider: Authentication service supporting multiple wallet types
• Matrix Server: Backend messaging infrastructure
• Blockchain Wallets: End-user authentication method

Troubleshooting

Common Issues

• Invalid access token errors: Clear the data directory to remove outdated login information
• Password login disabled: Ensure password_config is set to enabled: true in Matrix server config
• Connection issues between services: Check network settings and ensure all services are running

Debugging Tips

• Check logs for both quali-chat-core and oidc-provider
• Verify Redis connection is active
• Ensure wallet connections are properly configured

References

• Matrix API Documentation
• OIDC Specifications