DM

Sup Chat

Decentralized, end‑to‑end encrypted group messaging on AO — rebuilt with a clean modular architecture and fully powered by HyperBEAM.

Updated: 2025-10 Docs Version: v1.0 Current Version: Alpha 0.4.0

---

Overview

DM ("Sup Chat") is a decentralized, end-to-end encrypted messenger built entirely on AO and HyperBEAM. The application recently underwent a major refactor into a clean, modular codebase that separates responsibilities across dedicated frontend modules for clarity, performance, and extensibility.

This version includes:

• Fully HyperBEAM-integrated messaging
• aoconnect 0.0.91 with polyfills (configured in Vite)
• Messaging style that currently uses compute-slot query returns (similar to LegacyNet execution)
• A coming evolution toward push-based messaging + endpoint-driven state fetch

---

Quick Start

# Install
npm install

# Run locally
npm run dev

1. Install the Wander Wallet browser extension.
2. Open the development server URL.
3. Connect your wallet.
4. Start messaging — all content is encrypted and decentralized.

---

Requirements

• Wander Wallet (browser extension)
• Modern browser with Web Crypto API
• HyperBEAM connectivity
• aoconnect 0.0.91 (with included polyfills)
• Any static server or Vite-dev workflow

---

Architecture Summary

DM uses a modular frontend architecture paired with a scalable master/child AO process system.

Frontend Responsibilities

• Wallet connection & AO signing
• Message encryption/decryption
• UI rendering, themes, toasts, reactions
• Session lifecycle, reconnection, timers
• Caching, local state, refresh logic

Backend Responsibilities (AO Processes)

• Master Process

  • Maps users → their child messaging processes
  • Spawns new child processes on login

• Child Process

  • Fully isolated per-user state and data
  • Handles chats, messages, contacts, reactions
  • Enforces owner validation

---

Data Flow

bootstrap.js → wallet-login.js → messaging.js
                     ↓                 ↓
                session.js        contacts.js
                     ↓                 ↓
                core-ui.js     emoji-reactions.js

---

Module Breakdown

A clean tree representation of the current frontend modules:

src/
├── bootstrap.js          # App entry point, initializes everything
├── wallet-login.js       # Wallet state, AO login, aliased exports
├── session.js            # Session lifecycle, timers, reconnection
├── messaging.js          # Message send/receive logic, refresh logic
├── contacts.js           # Contact management
├── emoji-reactions.js    # Emoji reactions + cached reaction state
└── core-ui.js            # Theme, toasts, UI helpers

---

Login Flow

1. User connects Wander Wallet → frontend obtains userAddress.
2. Frontend calls master process login → master returns (or spawns) the user's child process ID.
3. Frontend stores this ID and all messaging routes through the child process moving forward.

The login flow is designed to be instant and transparent, showing only a spinner until ready.

---

Messaging

DM currently uses a compute-slot messaging model, where messages are sent to AO and retrieved via query results.

Message Lifecycle

• AES‑256‑GCM shared chat key per room
• RSA‑OAEP encrypted key per member
• Per-message unique IV
• Cached decrypt results to reduce compute
• Reaction updates share the same flow

Message refresh logic runs through messaging.js, including:

• Per-member message counts
• State hash comparison
• Local cache invalidation

---

Reactions

Emoji reactions are handled in emoji-reactions.js.

• Reactions are cached
• Duplicates prevented at UI level
• Reaction metadata preserved per message

---

Contacts

contacts.js manages the local + remote contact list, including:

• Adding known users
• Syncing known contacts to the child process

---

Security Model

• End-to-end encryption across all chats
• Per-user AO child process provides isolation
• Owner validation enforced on every handler
• No cross-user state sharing

---

Versioning

DM uses a multi-part version tag:

MASTER_VERSION - USER_PROCESS_VERSION - FRONTEND_VERSION

Example: A01-A01-A01

The frontend displays the user's BUILD_VERSION and participates in update flows when backend or child processes change.

---

Roadmap

The next stages of development include:

• Endpoint-state fetching for minimal compute costs
• Custom emoji support (including themed packs)
• New UI skins / themes
• Richer message types (files, images, reactions v2)
• More performant local cache and sync logic

---

Development

Install & Run

npm install
npm run dev

Code Structure Principles

• Small, single-responsibility modules
• Clear data flow from bootstrap → wallet → session → messaging
• AO child process isolation ensures scalability

---

License

MIT License.