SplitNaira

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

Status

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

Tech Stack

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

Quick Start

Option 1: Docker Compose (Recommended for demos and pre-deployment checks)

# Copy the environment template, then set CONTRACT_ID and SIMULATOR_ACCOUNT.
# The backend will not start without them, and the frontend waits for it.
cp .env.compose.example .env.local

# Start the entire stack (Postgres + Backend + Frontend)
docker compose --env-file .env.local up --build

# Access the services:
# - Website:     http://localhost:3000            (redirects to /en)
# - Application: http://localhost:3000/en/app
# - Backend API: http://localhost:3001
# - API Docs:    http://localhost:3001/api/docs

The repository does not record a live contract deployment (contracts/deployments.json is a placeholder). Deploy the contract to testnet first — see Contract Setup — and use its ID.

Option 2: Local Development

# Install all dependencies
npm run setup

# Development (all services)
npm run dev

# Build all projects
npm run build

# Run tests
npm run test

Getting Started

Prerequisites:

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

Root Commands

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

Command	Description
npm run setup	Install all dependencies for frontend, backend, and contracts
npm run dev	Start frontend and backend development servers
npm run dev:frontend	Start only frontend dev server
npm run dev:backend	Start only backend dev server
npm run build	Build all projects (frontend, backend, contracts)
npm run build:frontend	Build frontend
npm run build:backend	Build backend
npm run build:contracts	Build smart contracts
npm run test	Run all tests
npm run test:frontend	Run frontend tests
npm run test:backend	Run backend tests
npm run test:contracts	Run contract tests
npm run lint	Lint all projects
npm run clean	Clean build artifacts
npm run migration:dry-run	Recreate a dedicated local database and verify all backend migrations

Docker Compose

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.

Individual Project Commands

Workspace-specific command reference

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.

Workspace	Command	Purpose
Frontend	npm run dev -w frontend	Start the Next.js development server.
Frontend	npm run build -w frontend	Create the production frontend build.
Frontend	npm run start -w frontend	Serve the built frontend.
Frontend	npm run lint -w frontend	Lint frontend source with zero warnings allowed.
Frontend	npm run test -w frontend	Run frontend Vitest tests.
Frontend	npm run check:i18n -w frontend	Verify every locale has the same message keys as English.
Backend	npm run dev -w backend	Start the API in watch mode.
Backend	npm run build -w backend	Type-check and build the API.
Backend	npm run start -w backend	Start the built API.
Backend	npm run lint -w backend	Lint backend source.
Backend	npm run format:check -w backend	Check backend TypeScript formatting without writing files.
Backend	npm run test -w backend	Run the backend Vitest suite.
Backend	npm run test:compat -w backend	Run split-route compatibility tests only.
Backend	npm run test:integration -w backend	Run the testnet integration suite.
Backend	npm run test:shutdown -w backend	Run graceful-shutdown integration tests.
Backend	npm run deps:check -w backend	Validate the backend dependency tree without optional packages.
Backend	npm run generate:openapi -w backend	Regenerate the backend OpenAPI output.
Backend	npm run validate:deploy-config -w backend	Validate backend deployment configuration.

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.

Frontend

cd frontend
npm install
npm run dev

Backend

cd backend
npm install
npm run dev

Smart Contracts

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

Project Structure

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

Operational Health Checks

Endpoint	Purpose
/health/live	Liveness probe
/health/ready	Readiness probe
/health/startup	Startup probe

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

Observability

Metrics

GET /metrics

Request Tracing

All requests include:

X-Correlation-Id

Logging

Structured JSON logs are emitted for production monitoring.

Mainnet Readiness

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.

Developer Setup

npm install
cp backend/.env.example backend/.env      # fill in CONTRACT_ID, SIMULATOR_ACCOUNT, DATABASE_URL
cp frontend/.env.example frontend/.env.local
npm run dev

The backend validates its environment at startup and prints every missing or invalid variable. CONTRACT_ID is checked against its StrKey checksum, so a mistyped ID fails fast instead of on the first RPC call.

Application routes

Route	What it is
/{locale}	Public website (en, fr)
/{locale}/app	Wallet-connected application: dashboard, create, manage & distribute, projects
/{locale}/dashboard/settings	Account settings
/{locale}/receipts/{txHash}	Printable transaction receipt

Amounts and precision

Token amounts are handled as integers of stroops (1 token = 10,000,000 stroops). The frontend parses user input with bigint (frontend/src/lib/amounts.ts) and the backend stores amounts as validated decimal strings (backend/src/lib/decimal-amounts.ts); floating-point maths is never used to compute what is sent on-chain. The payout preview mirrors the contract rule: each collaborator receives floor(balance × bps / 10000) and the last collaborator receives the remainder.

Transaction states

Every wallet-signed action resolves only after the network confirms it. A transaction whose outcome is unknown (poll timeout or malformed RPC response) is shown as unconfirmed, and the same action stays blocked until "Check status" finds a final result, so a retry cannot pay twice.

Code Quality

npm run lint
npm run test

Bundle Analysis

npm run analyze:bundle -w frontend

Known limitations

• No recorded deployment. contracts/deployments.json is a placeholder; deploy the contract and set CONTRACT_ID yourself.
• Token presets. The token picker only lists the native XLM asset contract for each network (derived, verifiable IDs). Add issued assets such as USDC only after verifying their contract ID.
• Project edit history records intent. project_edit_history rows for lock, metadata and collaborator changes are written when the unsigned transaction is prepared, not when it confirms on-chain.
• Off-chain ownership transfer is advisory. POST /collaboration/projects/:id/transfer-ownership re-syncs the owner from chain and does not submit the contract's transfer_project_ownership; the on-chain owner remains authoritative.
• Light theme. The interface ships a single dark theme.
• Windows paths containing &. npm's .cmd shims break when the checkout path contains &. Install with npm ci --ignore-scripts and invoke tools with node node_modules/<tool>/..., or use a path without &.

Documentation

• 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
• Stellar RPC Response Validation
• API Docs
• Mainnet Launch Runbook
• User Onboarding Runbook

Release Versioning

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.

Local Migration Dry-Run

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

Grant Readiness

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.

CI/CD Pipelines

Workflow	Trigger	Purpose
ci.yml	push/PR to main	Full suite: data integrity, frontend, backend, contracts, security audit
backend-deploy.yml	CI success on main / manual	Deploy backend to staging or production via Render
mainnet-deploy.yml	Manual only	Production mainnet deploy with pre-flight validation gate
user-onboarding-ci.yml	push/PR touching onboarding files	Validate register/login/profile routes end-to-end
frontend-ci.yml	push/PR to main/develop	Frontend lint, test, build
frontend-quality.yml	PR	Frontend quality gate (lint, test, build)
contract-testnet-deploy.yml	push to main (contracts path)	Deploy Soroban contract to testnet
smoke-testnet.yml	Manual	Post-deploy smoke test on testnet
dependency-audit.yml	Weekly / manual	npm audit for high-severity vulnerabilities

License

MIT