From 2373a29bc3cefdf79f8704ee17b3b9bf7a64c177 Mon Sep 17 00:00:00 2001 From: joan-bisbal Date: Mon, 27 Jul 2026 18:52:46 +0200 Subject: [PATCH 1/3] docs: add Trident framework architecture overview --- docs/trident_architecture_overview.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/trident_architecture_overview.md diff --git a/docs/trident_architecture_overview.md b/docs/trident_architecture_overview.md new file mode 100644 index 0000000..7580e36 --- /dev/null +++ b/docs/trident_architecture_overview.md @@ -0,0 +1,3 @@ +# Trident Architecture Overview + +High-level architectural overview of Trident contract framework components. From ed2ca7318cef13edb9c519f9aaf8815003ce1f10 Mon Sep 17 00:00:00 2001 From: joan-bisbal Date: Wed, 29 Jul 2026 21:51:37 +0200 Subject: [PATCH 2/3] docs: add comprehensive Trident architecture overview specification --- docs/trident_architecture_overview.md | 51 +++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 2 deletions(-) diff --git a/docs/trident_architecture_overview.md b/docs/trident_architecture_overview.md index 7580e36..1fc7f77 100644 --- a/docs/trident_architecture_overview.md +++ b/docs/trident_architecture_overview.md @@ -1,3 +1,50 @@ -# Trident Architecture Overview +# Trident Framework Architecture Overview -High-level architectural overview of Trident contract framework components. +## Overview + +Trident is a high-throughput event indexing and query infrastructure for Stellar and Soroban smart contract ecosystems. It ingests block headers, ledger metadata, and Soroban contract execution logs from Soroban RPC nodes, normalizes binary XDR events, persists relational state into PostgreSQL, caches hot stream buffers in Redis, and exposes query interfaces via gRPC and HTTP REST APIs with WebSockets/SSE streaming. + +--- + +## High-Level Architecture + +```mermaid +graph TD + RPC[Soroban RPC Node] -->|1. Ingest Events & Ledgers| Indexer[Rust Indexer Service / crates/indexer] + Indexer -->|2. Relational Persistence| DB[(PostgreSQL Database)] + Indexer -->|3. Event Stream PubSub| Redis[(Redis Cache & Stream Buffer)] + DB -->|4. Query Data| gRPC[gRPC Service / services/grpc-api] + Redis -->|5. Real-time Fanout| GoREST[Go REST & Stream Service / services/rest-api] + gRPC -->|gRPC Endpoints| Clients[External Clients & dApps] + GoREST -->|HTTP REST / WebSocket / SSE| WebClients[Frontend & Mobile Clients] +``` + +--- + +## Component Breakdown + +### 1. Ingest & Processing Engine (`crates/indexer`) +- **Streamer (`crates/indexer/src/streamer`)**: Polls Soroban RPC `getEvents` and `getLedgers` endpoints using configurable topic filters. Handlers mitigate network latency and handle transient RPC errors. +- **Parser (`crates/indexer/src/parser`)**: Decodes Soroban contract events from binary XDR format into structured domain models. Includes native Stellar Asset Contract (SAC) recognition and SEP-41 event parsing (`crates/indexer/src/parser/sac.rs`). +- **Store (`crates/indexer/src/store`)**: Manages transactional writes to PostgreSQL and publishes live event payloads to Redis Pub/Sub channels. + +### 2. Storage Tier +- **PostgreSQL**: Serves as the primary source of truth for historical ledger events, contract deployment registries, and asset metadata. +- **Redis**: Acts as an in-memory event buffer for real-time WebSocket fanout and temporary deduplication of block range processing. + +### 3. Service Tier +- **gRPC API (`services/grpc-api`)**: High-performance Rust gRPC service providing typed Protobuf contracts for contract event listing, ledger querying, and streaming. +- **Go REST API (`services/rest-api`)**: Go-based API server providing RESTful HTTP endpoints (`/v1/events`, `/v1/ledgers`), OpenAPI documentation, CORS middleware, and Server-Sent Events (SSE) / WebSocket endpoints for real-time updates. + +### 4. Client SDK (`sdk/`) +- Client libraries providing typed interfaces for consuming Trident gRPC and REST streams with automatic reconnection logic and signature verification. + +--- + +## Data Pipeline Flow + +1. **Poll**: The Indexer polls the target Soroban RPC endpoint for new ledger events matching registered topic filters. +2. **Decode**: Binary XDR event payloads are decoded, enriched with ledger sequence numbers and timestamps, and checked against the `SacRegistry`. +3. **Persist**: Decoded event records are written to PostgreSQL tables. +4. **Publish**: Event payloads are published to Redis channels. +5. **Serve**: External clients query historical data via REST/gRPC or subscribe to live WebSocket/SSE event streams. From 64f709f0d666e4f803ee30b82a68d248129e7657 Mon Sep 17 00:00:00 2001 From: joan-bisbal Date: Fri, 31 Jul 2026 17:16:04 +0200 Subject: [PATCH 3/3] docs: rename to kebab-case to match docs/ convention --- ..._architecture_overview.md => trident-architecture-overview.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{trident_architecture_overview.md => trident-architecture-overview.md} (100%) diff --git a/docs/trident_architecture_overview.md b/docs/trident-architecture-overview.md similarity index 100% rename from docs/trident_architecture_overview.md rename to docs/trident-architecture-overview.md