go/sonr
1
0
Fork 0
mirror of https://github.com/sonr-io/sonr.git synced 2026-08-02 09:21:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update README with new build commands and architecture information

Browse Source
This commit is contained in:
Prad Nukala
2025-10-21 12:30:38 -04:00
parent cf1712c2d8
commit 2241ac470b
4 changed files with 23 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/README.md
+11 -209
View File
@@ -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
.github/dependabot.yml
+3 -78
View File
@@ -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
.github/workflows/pr.yml
+1 -2
View File
@@ -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
Makefile
+8 -5
View File
@@ -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)"