Royalty splitting for Nigeria's creative economy, powered by Stellar and Soroban.

SplitNaira is in active development. This repo currently contains: ..

• contracts/ Soroban smart contract and tests
• frontend/ Next.js + Tailwind scaffold
• backend/ Express API scaffold
• demo/ Static HTML flow prototype

• Frontend: Next.js (App Router), TailwindCSS, TypeScript
• Backend: Node.js, Express, TypeScript
• Smart contracts: Soroban (Rust)
• Blockchain: Stellar (testnet + mainnet)

# Copy the environment template
cp .env.compose.example .env.local

# Start the entire stack (Postgres + Backend + Frontend)
docker compose up

# Access the services:
# - Frontend: http://localhost:3000
# - Backend API: http://localhost:3001
# - API Docs: http://localhost:3001/api/docs

# Install all dependencies
npm run setup

# Development (all services)
npm run dev

# Build all projects
npm run build

# Run tests
npm run test

Prerequisites:

• Node.js >= 18
• Rust (latest stable)
• Docker (optional, but recommended for compose setup)

Use npm scripts from the root to run commands across all projects:

The docker-compose.yml provides a complete local stack for development and smoke testing:

Services:

• Postgres (postgres:16-alpine): Database with automatic initialization
• Backend (Express + TypeScript): API server with health checks
• Frontend (Next.js): Web application

Features:

• Postgres volume persistence
• Service health checks with ordered startup
• Environment variable templating via .env.compose.example
• Bridge networking for inter-service communication
• Production-ready multi-stage Docker builds

Quick Commands:

# Start the stack
docker compose up

# Start in background
docker compose up -d

# View logs
docker compose logs -f backend    # Backend logs
docker compose logs -f frontend   # Frontend logs
docker compose logs -f postgres   # Database logs

# Stop services
docker compose down

# Reset database (remove volumes)
docker compose down -v

# Rebuild images
docker compose up --build

Environment Configuration:

Copy .env.compose.example to customize the stack:

cp .env.compose.example .env.local
# Edit .env.local as needed
docker compose --env-file .env.local up

Accessing Services:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• API Documentation: http://localhost:3001/api/docs
• Database: localhost:5432 (user: splitnaira, password: splitnaira)

For production wallet and payment operations, configure PAYMENTS_ADMIN_API_KEY on the backend before exposing /splits/admin/*. If payout-impacting admin actions need to be frozen during an incident or rollback, set PAYMENTS_ADMIN_WRITE_ENABLED=false and redeploy or restart the backend with the updated environment.

Run these commands from the repository root. npm workspace commands use the workspace path (-w frontend or -w backend) so that they work without changing directories.

migration:run and migration:revert act on the database configured in backend/.env; use them only with the intended environment. The dry-run command has a separate, destructive-but-isolated database target.

cd frontend
npm install
npm run dev

cd backend
npm install
npm run dev

cd contracts
cargo test --locked
rustup target add wasm32v1-none
cargo build --release --target wasm32v1-none --locked

SplitNaira/
├── backend/         # Express API
├── contracts/      # Soroban smart contracts
├── frontend/       # Next.js application
└── demo/           # Static prototype

Used for Kubernetes, Docker Swarm, and cloud deployment monitoring.

GET /metrics

All requests include:

X-Correlation-Id

Structured JSON logs are emitted for production monitoring.

Endpoint:

GET /ops/mainnet-readiness

Purpose:

• Deployment validation
• Launch verification
• Configuration auditing
• Mainnet configuration and readiness audit before traffic cutover

This endpoint performs a lightweight operational check that includes:

• environment configuration validation
• database connectivity verification
• cache and runtime capacity metrics
• production secret audit and contract ID consistency check

Use it as a pre-deployment gate during release and rollback planning.

npm install
npm run verify:env
npm run dev

npm run lint
npm run test

npm run analyze

• Architecture Overview
• Split Lifecycle Architecture
• Deployment Runbook
• Operational Runbooks (contracts, CI/CD, ops, frontend)
• Local Postgres Migration Dry-Run
• Windows npm Dependency Installation
• Contributing Guide
• Contract Setup
• Contract Release & Upgrade
• Backend CD
• API Docs
• Mainnet Launch Runbook
• User Onboarding Runbook
• API Evolution Runbook
• Stuck Payouts Incident Response Runbook
• Data Deletion and Account Closure
• Changelog

SplitNaira uses v0.x.y git tags for release traceability. A tag identifies the exact source state for backend, frontend, and smart contract code.

• Draft GitHub Releases are created automatically when a v0.x.y tag is pushed, using the release notes from CHANGELOG.md.
• The contract WASM built from the tagged commit is the versioned smart contract artifact. The canonical build output is:
  • contracts/target/wasm32v1-none/release/splitnaira_contract.wasm
  • contracts/target/wasm32v1-none/release/release-info.json
• CONTRACT_ID is the deployed contract address for the target network; it is recorded separately from the repo release tag.
• Keep CHANGELOG.md up to date before tagging a release so GitHub Releases reflect the correct notes.

Use the local Postgres migration dry-run runbook to configure an isolated database safely before running npm run migration:dry-run.

SplitNaira is built for royalty splitting in Nigeria's creative economy and is structured to be reviewable by grant programs.

• Transparent on-chain split logic on Stellar Soroban.
• Wallet-enabled frontend and API backend for a production workflow.
• Contract, backend, and frontend tests wired into CI/CD.
• Deployment and rollback runbooks already documented.

See GrantFox brief for the application-ready summary.

MIT