Skip to content

Commit 2bdc8da

Browse files
GaloisField2718GaloisField2718
committed
docs: several documentations for OPI developments
1 parent 4db4175 commit 2bdc8da

File tree

5 files changed

+1523
-16
lines changed

5 files changed

+1523
-16
lines changed

‎README.md‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# **Simplicity: An Universal BRC-20 Indexer & OPI Framework**
22

33
[![CI/CD Pipeline](https://github.com/The-Universal-BRC-20-Extension/simplicity/actions/workflows/ci.yml/badge.svg)](https://github.com/The-Universal-BRC-20-Extension/simplicity/actions/workflows/ci.yml)
4-
[![Test Coverage](https://img.shields.io/badge/coverage-67%25-brightgreen)](https://github.com/The-Universal-BRC20-Extension/simplicity)
4+
[![Test Coverage](https://img.shields.io/badge/coverage-68%25-brightgreen)](https://github.com/The-Universal-BRC20-Extension/simplicity)
55
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
66
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/release/python-3110/)
77

@@ -16,7 +16,7 @@ This indexer is the consensus engine that powers the entire ecosystem, transform
1616
## Key Features
1717

1818
- **High Performance:** Sub-20ms API response times for cached queries, optimized for real-time applications.
19-
- **Extensively Tested:** +80% test coverage with a comprehensive suite of unit, integration, and protocol-level tests.
19+
- **Extensively Tested:** 68% test coverage with 442 comprehensive tests across unit, integration, and functional test suites.
2020
- **Protocol-Complete:** Full implementation of the Universal BRC-20 standard and a growing list of OPIs.
2121
- **Modular OPI Framework:** A pluggable architecture that allows for the seamless addition of new operations like **OPI-1 (`swap`)** without disrupting core functionality.
2222
- **Dockerized:** One-command deployment with Docker Compose for ease of setup.
@@ -47,10 +47,30 @@ This plug-and-play architecture allows the community to propose and integrate ne
4747

4848
- `deploy`, `mint`, `transfer`: The foundational operations for creating and moving BRC-20 tokens, handled by the legacy processor.
4949

50-
### **OPI-0: `no_return`** [Next Update]
50+
### **OPI Framework: Extensible Protocol Architecture**
5151

52-
- **Purpose:** A specialized operation for scenarios requiring proof of token burn or specific on-chain interactions, involving Ordinals and witness data inscriptions.
53-
- **Processor Logic:** The OPI-0 processor validates a unique transaction structure, including checks on witness data and specific output addresses (e.g., transfers to a Satoshi address). It interacts with external services OPI-LC indexer for the validation.
52+
The OPI (Operation Proposal Improvement) framework allows for seamless integration of new protocols without modifying the core indexer. Each OPI is a self-contained module with its own validation logic and state management.
53+
54+
#### **Current OPIs:**
55+
56+
- **OPI-0: `no_return`** [In Development]
57+
- **Purpose:** Specialized operation for token burn scenarios and witness data validation
58+
- **Features:** Ordinals integration, witness data processing, external service validation
59+
- **Status:** Architecture complete, implementation in progress
60+
61+
#### **How to Add New OPIs:**
62+
63+
1. **Create OPI Module:** Implement `BaseProcessor` interface
64+
2. **Register OPI:** Add to `ENABLED_OPIS` configuration
65+
3. **Define Operations:** Specify supported operation types
66+
4. **Test Integration:** Use comprehensive test suite
67+
5. **Deploy:** Zero-downtime deployment via configuration
68+
69+
For detailed OPI development guide, see [OPI Developer Documentation](docs/architecture/OPI_DEVELOPER_GUIDE.md).
70+
71+
For OPI architecture diagrams and visual guides, see [OPI Architecture Diagrams](docs/architecture/OPI_ARCHITECTURE_DIAGRAM.md).
72+
73+
For maintainer-specific guidance, see [OPI Maintenance Guide](docs/architecture/OPI_MAINTENANCE_GUIDE.md).
5474

5575
---
5676

@@ -152,6 +172,7 @@ tests/
152172
│ ├── services/ # Service layer tests
153173
│ ├── models/ # Model tests
154174
│ ├── utils/ # Utility function tests
175+
│ ├── opi/ # OPI framework tests
155176
│ └── api/ # API unit tests
156177
├── integration/ # Integration tests (108 tests) - Database & API
157178
├── functional/ # Functional tests (34 tests) - End-to-end
@@ -213,8 +234,8 @@ pipenv run pytest tests/ -m bitcoin # Bitcoin-related tests
213234
### Test Coverage
214235

215236
The test suite provides comprehensive coverage:
216-
- **379 total tests** across all categories
217-
- **67% code coverage** with detailed reporting
237+
- **442 total tests** across all categories
238+
- **68% code coverage** with detailed reporting
218239
- **Zero breaking changes** - all existing tests preserved
219240

220241
### Development Workflow

‎docs/README.md‎

Lines changed: 81 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,85 @@
1-
# Simplicity Indexer Documentation
1+
# Simplicity Documentation
22

3-
Welcome to the documentation for Simplicity Indexer.
3+
Welcome to the Simplicity documentation hub. This directory contains comprehensive guides for developers, maintainers, and users of the Simplicity BRC-20 indexer and OPI framework.
44

5-
## Documentation Sections
5+
## 📚 Documentation Index
66

7-
- [API Reference](./api/README.md) <!-- TODO: Add API details -->
8-
- [System Architecture](./architecture/README.md) <!-- TODO: Add architecture overview and diagram -->
9-
- [Deployment Guide](./deployment/README.md) <!-- TODO: Add deployment and configuration instructions -->
10-
- [Development & Contribution Guide](./development/README.md) <!-- TODO: Add dev workflow and template usage -->
11-
- [Security Configuration](./SECURITY_CONFIG.md) <!-- TODO: Refocus on safe defaults and best practices -->
7+
### 🏗️ Architecture & Design
128

13-
For general usage and quick start, see the main [README.md](../README.md).
9+
- **[OPI Developer Guide](architecture/OPI_DEVELOPER_GUIDE.md)** - Complete guide for developers creating OPI modules
10+
- **[OPI Maintenance Guide](architecture/OPI_MAINTENANCE_GUIDE.md)** - Guide for maintainers managing OPI integrations
11+
- **[OPI Architecture Diagrams](architecture/OPI_ARCHITECTURE_DIAGRAM.md)** - Visual diagrams of OPI architecture and workflows
12+
- **[System Architecture](architecture/README.md)** - High-level system architecture overview
13+
14+
### 🚀 Getting Started
15+
16+
- **[Quick Start Guide](../README.md#quick-start)** - Get up and running in minutes
17+
- **[Installation Guide](deployment/README.md)** - Detailed installation instructions
18+
- **[Configuration Guide](configuration/README.md)** - Complete configuration reference
19+
20+
### 🔧 Development
21+
22+
- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute to the project
23+
- **[API Documentation](api/README.md)** - Complete API reference
24+
- **[Testing Guide](testing/README.md)** - Testing strategies and best practices
25+
26+
### 🛠️ Operations
27+
28+
- **[Deployment Guide](deployment/README.md)** - Production deployment procedures
29+
- **[Monitoring Guide](monitoring/README.md)** - System monitoring and observability
30+
- **[Troubleshooting Guide](troubleshooting/README.md)** - Common issues and solutions
31+
32+
### 📖 Reference
33+
34+
- **[API Reference](api/README.md)** - Complete API documentation
35+
- **[Configuration Reference](configuration/README.md)** - All configuration options
36+
- **[Changelog](../CHANGELOG.md)** - Version history and changes
37+
38+
## 🎯 Quick Navigation
39+
40+
### For Developers
41+
1. Start with [OPI Developer Guide](architecture/OPI_DEVELOPER_GUIDE.md)
42+
2. Review [System Architecture](architecture/README.md)
43+
3. Check [API Documentation](api/README.md)
44+
4. Follow [Contributing Guide](../CONTRIBUTING.md)
45+
46+
### For Maintainers
47+
1. Read [OPI Maintenance Guide](architecture/OPI_MAINTENANCE_GUIDE.md)
48+
2. Review [Deployment Guide](deployment/README.md)
49+
3. Check [Monitoring Guide](monitoring/README.md)
50+
4. Reference [Troubleshooting Guide](troubleshooting/README.md)
51+
52+
### For Users
53+
1. Follow [Quick Start Guide](../README.md#quick-start)
54+
2. Check [Installation Guide](deployment/README.md)
55+
3. Review [Configuration Guide](configuration/README.md)
56+
4. Reference [API Documentation](api/README.md)
57+
58+
## 📊 Project Status
59+
60+
- **Current Version**: 1.0.0
61+
- **Test Coverage**: 68% (442 tests)
62+
- **OPI Framework**: Fully implemented
63+
- **Documentation**: Complete
64+
65+
## 🤝 Contributing to Documentation
66+
67+
We welcome contributions to improve our documentation! Please see our [Contributing Guide](../CONTRIBUTING.md) for details on how to:
68+
69+
- Report documentation issues
70+
- Suggest improvements
71+
- Submit documentation updates
72+
- Add new guides or tutorials
73+
74+
## 📞 Support
75+
76+
If you need help with Simplicity or the OPI framework:
77+
78+
1. Check the [Troubleshooting Guide](troubleshooting/README.md)
79+
2. Search existing [GitHub Issues](https://github.com/The-Universal-BRC-20-Extension/simplicity/issues)
80+
3. Create a new issue with detailed information
81+
4. Join our community discussions
82+
83+
---
84+
85+
**Happy Building! 🚀**

‎docs/architecture/OPI_ARCHITECTURE_DIAGRAM.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# OPI Architecture Diagram
2+
3+
## High-Level OPI Flow
4+
5+
```mermaid
6+
graph TD
7+
A[Block Ingestion] --> B[Transaction Parsing]
8+
B --> C{OPI Router}
9+
C -->|op: "swap"| D[OPI-1 Processor]
10+
C -->|op: "no_return"| E[OPI-0 Processor]
11+
C -->|op: "deploy"| F[Legacy BRC20 Processor]
12+
D --> G[State Validation]
13+
E --> G
14+
F --> G
15+
G --> H[Atomic Commit]
16+
H --> I[Database Update]
17+
```
18+
19+
## OPI Component Architecture
20+
21+
```mermaid
22+
graph TB
23+
subgraph "OPI Framework"
24+
A[OPI Registry] --> B[Base Processor Interface]
25+
B --> C[OPI-0 Processor]
26+
B --> D[OPI-1 Processor]
27+
B --> E[Custom OPI Processor]
28+
end
29+
30+
subgraph "State Management"
31+
F[Context] --> G[Intermediate State]
32+
G --> H[State Update Commands]
33+
H --> I[Atomic State Changes]
34+
end
35+
36+
subgraph "Core Indexer"
37+
J[Block Parser] --> K[OPI Router]
38+
K --> A
39+
A --> F
40+
I --> L[Database]
41+
end
42+
```
43+
44+
## OPI Development Workflow
45+
46+
```mermaid
47+
graph LR
48+
A[Create OPI Module] --> B[Implement BaseProcessor]
49+
B --> C[Define Data Contracts]
50+
C --> D[Write Tests]
51+
D --> E[Register OPI]
52+
E --> F[Test Integration]
53+
F --> G[Deploy to Production]
54+
55+
H[Code Review] --> I[Security Audit]
56+
I --> J[Performance Testing]
57+
J --> K[Documentation Review]
58+
K --> G
59+
```
60+
61+
## State Management Flow
62+
63+
```mermaid
64+
sequenceDiagram
65+
participant T as Transaction
66+
participant P as Parser
67+
participant R as OPI Router
68+
participant OP as OPI Processor
69+
participant C as Context
70+
participant IS as Intermediate State
71+
participant DB as Database
72+
73+
T->>P: Raw Transaction Data
74+
P->>R: Parsed Operation
75+
R->>OP: Route to Processor
76+
OP->>C: Read Current State
77+
C->>IS: Get Intermediate State
78+
OP->>OP: Process Operation
79+
OP->>IS: Update Intermediate State
80+
IS->>DB: Atomic Commit
81+
DB-->>OP: Confirmation
82+
```
83+
84+
## OPI Testing Architecture
85+
86+
```mermaid
87+
graph TB
88+
subgraph "Test Suite"
89+
A[Unit Tests] --> B[OPI Processor Tests]
90+
A --> C[Contract Tests]
91+
A --> D[State Management Tests]
92+
93+
E[Integration Tests] --> F[End-to-End Tests]
94+
E --> G[Database Integration Tests]
95+
E --> H[API Integration Tests]
96+
97+
I[Functional Tests] --> J[Workflow Tests]
98+
I --> K[Performance Tests]
99+
I --> L[Security Tests]
100+
end
101+
102+
M[Test Runner] --> A
103+
M --> E
104+
M --> I
105+
```
106+
107+
## Deployment Architecture
108+
109+
```mermaid
110+
graph TB
111+
subgraph "Development"
112+
A[Local Development] --> B[Unit Tests]
113+
B --> C[Integration Tests]
114+
end
115+
116+
subgraph "Staging"
117+
D[Staging Environment] --> E[Full Test Suite]
118+
E --> F[Performance Tests]
119+
F --> G[Security Tests]
120+
end
121+
122+
subgraph "Production"
123+
H[Blue Environment] --> I[Health Checks]
124+
J[Green Environment] --> K[Health Checks]
125+
I --> L[Traffic Switch]
126+
K --> L
127+
end
128+
129+
C --> D
130+
G --> H
131+
G --> J
132+
```
133+
134+
## Monitoring and Observability
135+
136+
```mermaid
137+
graph TB
138+
subgraph "OPI Monitoring"
139+
A[Metrics Collection] --> B[Performance Metrics]
140+
A --> C[Error Metrics]
141+
A --> D[State Metrics]
142+
143+
E[Logging] --> F[Structured Logs]
144+
F --> G[Log Aggregation]
145+
146+
H[Alerting] --> I[Performance Alerts]
147+
H --> J[Error Alerts]
148+
H --> K[Security Alerts]
149+
end
150+
151+
L[OPI Processors] --> A
152+
L --> E
153+
M[Monitoring Dashboard] --> B
154+
M --> C
155+
M --> D
156+
```
157+
158+
## Security Architecture
159+
160+
```mermaid
161+
graph TB
162+
subgraph "Security Layers"
163+
A[Input Validation] --> B[Operation Validation]
164+
B --> C[State Validation]
165+
C --> D[Access Control]
166+
167+
E[Security Monitoring] --> F[Anomaly Detection]
168+
F --> G[Threat Detection]
169+
G --> H[Incident Response]
170+
end
171+
172+
I[OPI Operations] --> A
173+
J[Security Events] --> E
174+
K[Security Dashboard] --> F
175+
```
176+
177+
This comprehensive diagram set illustrates the complete OPI architecture, from high-level flow to detailed component interactions, testing strategies, deployment procedures, and security considerations.

0 commit comments

Comments
 (0)