OpChan/packages/core/docs/INDEX.md

OpChan Core Documentation Index

Complete documentation for @opchan/core - the foundational SDK for building decentralized forums.

---

Quick Links

• Quick Start - Get started in 5 minutes
• README - Package overview and installation
• Getting Started Guide - Comprehensive tutorial
• API Reference - Complete API documentation
• Architecture Guide - System design and internals
• Sample Applications - Full working examples

---

Documentation Overview

For Beginners

Start here if you're new to OpChan:

1. Quick Start (5 min)

   • Minimal working example
   • Essential operations
   • Complete starter template

2. README (15 min)

   • Package overview
   • Core concepts
   • Quick start guide
   • Usage patterns

3. Getting Started Guide (30 min)

   • Step-by-step tutorial
   • All features explained
   • Best practices
   • Complete application skeleton

For Developers

Deep dive into building applications:

4. API Reference (Reference)

   • Complete API documentation
   • All classes and methods
   • Type definitions
   • Usage examples

5. Sample Applications (Templates)

   • Minimal forum
   • Anonymous-first forum
   • Moderation dashboard
   • Identity explorer
   • Bookmark manager
   • Real-time feed
   • CLI tool

For Advanced Users

Understanding the system:

6. Architecture Guide (Deep Dive)
   • System overview
   • Core architecture
   • Data flow
   • Key subsystems
   • Cryptographic design
   • Storage strategy
   • Network layer
   • Design patterns
   • Performance considerations
   • Security model

---

By Topic

Getting Started

• Installation
• Quick Start
• Basic Setup
• First Application

Client Setup

• OpChanClient Configuration
• Opening Database
• Message Synchronization
• Network Monitoring

Authentication & Identity

• Key Delegation (Wallet)
• Key Delegation (Anonymous)
• Identity Resolution
• User Profiles
• ENS Integration

Content Management

• Creating Cells
• Creating Posts
• Creating Comments
• Voting
• Reading Content

Moderation

• Moderating Posts
• Moderating Comments
• Moderating Users
• Moderation Dashboard Example

Advanced Features

• Relevance Scoring
• Bookmarks
• Pending State Management
• Message Validation

Architecture & Internals

• System Overview
• Core Architecture
• Data Flow
• Delegation Subsystem
• Storage Subsystem
• Identity Subsystem
• Relevance Subsystem
• Cryptographic Design
• Network Layer
• Security Model

---

API Documentation

Core Classes

• OpChanClient - Main entry point
• DelegationManager - Key delegation
• LocalDatabase - Storage and caching
• ForumActions - Content operations
• UserIdentityService - Identity resolution
• RelevanceCalculator - Content scoring
• MessageManager - Network layer
• BookmarkService - Bookmarks
• MessageValidator - Validation

Type Definitions

• Core Types
• User Types
• Message Types
• Forum Types
• Delegation Types

---

Sample Application

Complete Production-Ready Template

Complete Forum Application

A comprehensive, production-ready forum demonstrating all features:

• ✅ Client initialization and configuration
• ✅ Anonymous & wallet authentication
• ✅ Session persistence across reloads
• ✅ Content creation (cells, posts, comments)
• ✅ Voting system (upvote/downvote)
• ✅ Identity resolution (ENS, call signs)
• ✅ Real-time message synchronization
• ✅ Relevance scoring with breakdown
• ✅ Moderation tools (cell owners)
• ✅ Bookmark management
• ✅ Network health monitoring
• ✅ Optimistic UI with pending states
• ✅ Proper error handling
• ✅ Clean architecture

Use this as a foundation for building your decentralized forum application.

---

Usage Patterns

Common Workflows

• Anonymous User Flow
• Wallet User Flow
• Creating Content
• Identity Resolution
• Content Scoring
• Moderation
• Bookmarks

Best Practices

• Database Management
• Message Handling
• Network Monitoring
• Error Handling
• Performance Optimization
• Security Considerations

---

Additional Resources

External Links

• GitHub Repository: opchan
• React Package: @opchan/react
• Waku Protocol: Waku Docs
• Viem: Viem Docs

Related Documentation

• React Package Docs
• React Getting Started
• Project README

---

Quick Reference

Essential Imports

// Core client
import { OpChanClient } from '@opchan/core';

// Types
import {
  EVerificationStatus,
  EDisplayPreference,
  type User,
  type Cell,
  type Post,
  type Comment,
  type Bookmark
} from '@opchan/core';

// Utilities
import {
  transformPost,
  transformComment,
  transformCell,
  BookmarkService,
  MessageValidator
} from '@opchan/core';

// Services
import {
  DelegationManager,
  LocalDatabase,
  ForumActions,
  UserIdentityService,
  RelevanceCalculator
} from '@opchan/core';

Most Common Operations

// Initialize
const client = new OpChanClient({ wakuConfig });
await client.database.open();

// Anonymous session
const sessionId = await client.delegation.delegateAnonymous('7days');

// Create post
await client.forumActions.createPost(params, callback);

// Read posts
const posts = Object.values(client.database.cache.posts);

// Get identity
const identity = await client.userIdentityService.getIdentity(address);

---

Troubleshooting

Common Issues

• Messages not appearing
• Database not persisting
• Identity not resolving
• Delegation expired
• Network errors

Debug Tips

1. Check delegation status: await client.delegation.getStatus()
2. Monitor network health: client.messageManager.onHealthChange()
3. Validate messages: await validator.isValidMessage()
4. Check database: await client.database.open()
5. Review logs: Enable verbose logging in browser console

---

Contributing

Documentation improvements are welcome! Please see the main project README for contribution guidelines.

---

License

MIT License - See LICENSE for details.

---

Last Updated: December 2024

Version: 1.0.3

---