From 2241ac470b37df71535962940c0498520baf1bca Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Tue, 21 Oct 2025 12:30:38 -0400 Subject: [PATCH] chore(docs): update README with new build commands and architecture information --- .github/README.md | 220 ++------------------------------------- .github/dependabot.yml | 81 +------------- .github/workflows/pr.yml | 3 +- Makefile | 13 ++- 4 files changed, 23 insertions(+), 294 deletions(-) diff --git a/.github/README.md b/.github/README.md index 4d930cfaa..841181e5e 100644 --- a/.github/README.md +++ b/.github/README.md @@ -106,10 +106,8 @@ make testnet-stop ### Building from Source ```bash -# Build all binaries -make build # snrd blockchain node -make build-hway # Highway service -make build-vault # Vault WASM plugin +# Build snrd blockchain node +make build # Build Docker image make docker @@ -162,38 +160,11 @@ make ipfs-status # Check IPFS connectivity ## πŸ—οΈ Architecture -Sonr consists of three primary components and three custom modules: - -### Service Architecture - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ Caddy │────▢│ snrd β”‚ β”‚ IPFS β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ β”‚ β”‚ - β”‚ β–Ό β–Ό - β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” - └─────────▢│ Highway │────▢│ Redis β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -- **Caddy**: Reverse proxy with gRPC-Web support (port 80) -- **Redis**: Task queue backend for Highway (port 6379) -- **Highway**: UCAN-based task processor (port 8090) -- **IPFS**: Distributed storage (API: 5001, Gateway: 8080) -- **snrd**: Blockchain node (gRPC: 9090, REST: 1317) - -### Cross-Platform Support - -The `localnet` target now automatically detects and uses the best available method: -1. Checks for local binary (built with `make install`) -2. Falls back to Docker if available -3. Handles permission issues on systems like Arch Linux -4. Supports systemd service installation (see `etc/systemd/`) +Sonr is a Cosmos SDK-based blockchain with integrated IPFS storage and three custom modules: ### Core Components -#### 1. **Blockchain Node (`snrd`)** +#### **Blockchain Node (`snrd`)** The main blockchain daemon built with Cosmos SDK v0.50.14, providing: @@ -201,22 +172,7 @@ The main blockchain daemon built with Cosmos SDK v0.50.14, providing: - EVM compatibility via Evmos integration - IBC for cross-chain communication - CosmWasm smart contract support - -#### 2. **Highway Service (`hway`)** - -An Asynq-based task processing service for vault operations: - -- Redis-backed job queue with priority levels -- Actor-based concurrency using Proto.Actor framework -- Processes cryptographic operations through WebAssembly enclaves - -#### 3. **Motor Plugin (`motr`)** - -WebAssembly-based vault system providing: - -- Secure execution environment for sensitive operations -- Hardware-backed key management -- Multi-party computation capabilities +- IPFS integration for decentralized storage ## πŸ“– Module Documentation @@ -291,7 +247,7 @@ snrd tx svc register-service my-service example.com \ ### Environment Variables -Environment variables can be configured via Docker Compose: +Environment variables can be configured for local development: ```bash # Chain configuration @@ -301,45 +257,12 @@ export BLOCK_TIME="1000ms" # Network selection for Starship export NETWORK="devnet" # or "testnet" -# Redis configuration -REDIS_URL=redis://redis:6379 -REDIS_DB=0 - -# Highway service -HIGHWAY_PORT=8090 -LOG_LEVEL=debug - # IPFS configuration -IPFS_API_URL=http://ipfs:5001 - -# Caddy configuration -CADDY_DOMAIN=localhost +IPFS_API_URL=http://127.0.0.1:5001 ``` Environment variables can be set directly or via a `.env` file in the project root. -### Docker Compose Services - -The project includes a comprehensive Docker Compose setup for running all backend services: - -```bash -# Start all services (Redis, Highway, Caddy, IPFS) -make docker-up - -# Stop all services -make docker-down - -# View service logs -make docker-logs # All services -make docker-logs-redis # Specific service - -# Check service health -make docker-status - -# Clean up Docker resources -make docker-clean -``` - ### Starship Configuration Edit `starship.yml` to configure multi-node testnets: @@ -353,147 +276,26 @@ chains: # ... additional configuration ``` -#### Troubleshooting - -**Services not starting:** -```bash -# Check service status -make docker-status - -# View detailed logs -make docker-logs - -# Ensure Docker network exists -docker network ls | grep sonr-network -``` - -**Redis connection issues:** -```bash -# Test Redis connectivity -docker exec redis redis-cli ping - -# Check Redis logs -make docker-logs-redis -``` - -**IPFS not accessible:** -```bash -# Verify IPFS is running -curl http://127.0.0.1:5001/api/v0/version - -# Check IPFS logs -docker compose -f etc/stack/compose.yml logs ipfs -``` - -**Port conflicts:** -- Caddy: 80 (HTTP) -- Redis: 6379 -- Highway: 8090 -- IPFS API: 5001 -- IPFS Gateway: 8080 - -Stop conflicting services or modify ports in `etc/stack/compose.yml`. - ## πŸ—οΈ Project Structure -Sonr uses a modern monorepo architecture with pnpm workspaces for JavaScript/TypeScript packages alongside the Go blockchain implementation: - -### Workspace Organization - ``` sonr/ β”œβ”€β”€ app/ # Application setup and module wiring β”œβ”€β”€ cmd/ # Binary entry points -β”‚ β”œβ”€β”€ snrd/ # Blockchain node -β”‚ β”œβ”€β”€ hway/ # Highway service -β”‚ └── motr/ # Motor WASM plugin +β”‚ └── snrd/ # Blockchain node β”œβ”€β”€ x/ # Custom chain modules β”‚ β”œβ”€β”€ did/ # W3C DID implementation β”‚ β”œβ”€β”€ dwn/ # Decentralized Web Nodes β”‚ └── svc/ # Service management β”œβ”€β”€ types/ # Internal packages -β”‚ β”œβ”€β”€ coins/ # Task processing -β”‚ └── ipfs/ # Authorization networks +β”‚ β”œβ”€β”€ coins/ # Coin utilities +β”‚ └── ipfs/ # IPFS integration β”œβ”€β”€ proto/ # Protobuf definitions β”œβ”€β”€ scripts/ # Utility scripts β”œβ”€β”€ test/ # Integration tests -β”œβ”€β”€ docs/ # Documentation site -β”‚ -# Monorepo Packages (pnpm workspaces) -β”œβ”€β”€ packages/ # Core JavaScript/TypeScript packages -β”‚ β”œβ”€β”€ es/ # @sonr.io/es - ES client library -β”‚ β”œβ”€β”€ sdk/ # @sonr.io/sdk - SDK package -β”‚ └── ui/ # @sonr.io/ui - Shared UI components -β”œβ”€β”€ cli/ # CLI tools -β”‚ β”œβ”€β”€ install/ # @sonr.io/install - Installation CLI -β”‚ └── join-testnet/# @sonr.io/join-testnet - Testnet CLI -└── web/ # Web applications - β”œβ”€β”€ auth/ # Authentication app (Next.js) - └── dash/ # Dashboard app (Next.js) +└── docs/ # Documentation site ``` -### Working with the Monorepo - -#### Installation - -```bash -# Install all dependencies for the monorepo -pnpm install - -# Build all packages -pnpm build - -# Run development mode for all packages -pnpm dev -``` - -#### Package Management - -```bash -# Run commands in specific packages -pnpm --filter @sonr.io/es build -pnpm --filter @sonr.io/sdk test - -# Add dependencies to specific packages -pnpm --filter @sonr.io/ui add react - -# Run commands in all packages -pnpm -r build # Build all packages -pnpm -r test # Test all packages -``` - -#### Versioning & Publishing - -The monorepo uses [Changesets](https://github.com/changesets/changesets) for package versioning: - -```bash -# Add a changeset for your changes -pnpm changeset - -# Version packages based on changesets -pnpm changeset version - -# Publish packages to npm -pnpm changeset publish -``` - -### Key Technologies - -- **pnpm workspaces**: Efficient dependency management with single lockfile -- **TypeScript project references**: Incremental builds and better IDE performance -- **Turbo**: Build orchestration and caching for faster builds -- **Changesets**: Automated versioning and changelog generation -- **Biome**: Fast, unified linting and formatting (replaces ESLint/Prettier) - -### Package Dependencies - -- `@sonr.io/es`: Core ES client library with protobuf types -- `@sonr.io/sdk`: High-level SDK (depends on @sonr.io/es) -- `@sonr.io/ui`: Shared UI components for web applications -- `@sonr.io/install`: CLI tool for installing Sonr -- `@sonr.io/join-testnet`: CLI tool for joining testnet -- Web apps use all three core packages (@sonr.io/es, @sonr.io/sdk, @sonr.io/ui) - ## 🀝 Community & Support - [GitHub Discussions](https://github.com/sonr-io/sonr/discussions) - Community forum diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 8f1261451..a2e3280fa 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,6 +1,6 @@ version: 2 updates: - # Go modules + # Go modules (main) - package-ecosystem: gomod directory: "/" schedule: @@ -14,88 +14,13 @@ updates: prefix: chore include: scope - # Go modules in subdirectories - - package-ecosystem: gomod - directory: "/cmd/hway" - schedule: - interval: weekly - day: monday - time: "02:00" - labels: - - dependencies - - hway - commit-message: - prefix: "chore(hway)" - - - package-ecosystem: gomod - directory: "/cmd/motr" - schedule: - interval: weekly - day: monday - time: "02:00" - labels: - - dependencies - - motr - commit-message: - prefix: "chore(motr)" - - - package-ecosystem: gomod - directory: "/cmd/vault" - schedule: - interval: weekly - day: monday - time: "02:00" - labels: - - dependencies - - vault - commit-message: - prefix: "chore(vault)" - - - package-ecosystem: gomod - directory: "/client" - schedule: - interval: weekly - day: monday - time: "02:00" - labels: - - dependencies - - client - commit-message: - prefix: "chore(client)" - - - package-ecosystem: gomod - directory: "/crypto" - schedule: - interval: weekly - day: monday - time: "02:00" - labels: - - dependencies - - crypto - commit-message: - prefix: "chore(crypto)" - - # JavaScript/TypeScript packages - - package-ecosystem: npm + # GitHub Actions + - package-ecosystem: github-actions directory: "/" schedule: interval: weekly day: monday time: "03:00" - labels: - - dependencies - - javascript - commit-message: - prefix: chore - include: scope - - # GitHub Actions - - package-ecosystem: github-actions - directory: "/" - schedule: - interval: weekly - day: monday - time: "04:00" labels: - dependencies - ci diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 445d1e2cb..2f6d98f8c 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -26,9 +26,8 @@ jobs: path: | ~/go/pkg/mod ~/.cache/go-build - ~/.local/share/pnpm/store ~/.devbox - key: deps-builder-${{ hashFiles('go.sum', 'pnpm-lock.yaml', 'devbox.json') }} + key: deps-builder-${{ hashFiles('go.sum', 'devbox.json') }} restore-keys: deps-builder- - name: Install Dependencies diff --git a/Makefile b/Makefile index 1f7f87f9f..9bf2c52a2 100644 --- a/Makefile +++ b/Makefile @@ -321,14 +321,17 @@ proto-gen: @gum log --level info "Auto-formatting generated protobuf files..." @$(MAKE) format -swagger-gen: - @$(MAKE) -C proto swagger-gen - @gum log --level info "βœ… Swagger generation complete. Output: client/docs/swagger-ui/swagger.yaml" +openapi-gen: + @$(MAKE) -C proto openapi-gen + @gum log --level info "βœ… OpenAPI generation complete. Output: docs/static/openapi.yml" + +# Backwards compatibility alias +swagger-gen: openapi-gen templ-gen: @docker run --rm -v `pwd`:/code -w=/code --user $(shell id -u):$(shell id -g) ghcr.io/a-h/templ:latest generate -.PHONY: proto-gen proto-swagger-gen swagger-gen proto-lint proto-check-breaking proto-publish +.PHONY: proto-gen proto-openapi-gen openapi-gen swagger-gen proto-lint proto-check-breaking proto-publish ############################################################################### ### Network Operations ### @@ -383,7 +386,7 @@ help: @gum log --level info "" @gum log --level info "πŸ“¦ Code Generation:" @gum log --level info " proto-gen Generate protobuf code" - @gum log --level info " swagger-gen Generate OpenAPI docs" + @gum log --level info " openapi-gen Generate OpenAPI documentation" @gum log --level info "" @gum log --level info "πŸ”§ Development Tools:" @gum log --level info " format Format code (Go + TypeScript)"