-orange?style=for-the-badge){kind=icon}
Amana is a decentralized escrow protocol designed to secure agricultural trade across different regions. By leveraging Soroban Smart Contracts, Amana eliminates the "Trust Gap" between buyers and sellers, ensuring fair trade even when parties are hundreds of miles apart.
This is the main repository containing the smart contracts and orchestration logic. Backend, frontend, and mobile applications are maintained in this monorepo for simpler development and unified deployment.
To provide a programmable safety net for regional commodity trading. Amana ensures that the risk of "sending first" is eliminated, replaced by a secure, neutral vault that only releases funds when delivery is verified.
- Smart Escrow: Secure funds holding using cNGN/stablecoins on the Stellar network.
- Dynamic Loss Sharing: Negotiable risk-sharing ratios (e.g., 50/50, 70/30) hardcoded into every trade to handle transit accidents or theft.
- Proof-of-Delivery (PoD): An optional video-based verification protocol involving the buyer and the driver to confirm the state of goods. Video evidence can be submitted and stored on IPFS for dispute resolution.
- Volatility Protection: Utilizes Stellar Path Payments to allow users to pay in local currency (NGN) while locking value in cNGN.
- Automated Settlement: A flat 1% platform fee is automatically deducted upon successful trade completion.
- Frontend: Next.js (App Router)
- Smart Contracts: Soroban (Rust)
- Blockchain: Stellar Network
- Wallet Connection: Freighter / Albedo
- Storage: IPFS (via Pinata) for decentralized storage of video evidence.
- Database: Supabase (Off-chain metadata, driver logs, and user profiles).
- Observability: OpenTelemetry distributed tracing with correlation IDs for end-to-end request tracking.
frontend/→ Next.js app environment (UI + wallet + Supabase/Pinata client integration)backend/→ Node.js/TypeScript API environment (Supabase + Pinata + integration endpoints)mobile/→ React Native Expo environment (mobile wallet, notification, and trade UX)contracts/→ Rust/Soroban smart contract environment
Amana uses pnpm as the package manager. Install it globally:
npm install -g pnpmcd frontend
cp .env.example .env.local
pnpm install
pnpm run devcd backend
cp .env.example .env
cp .env.tracing.example .env.tracing # for distributed tracing configuration
pnpm install
pnpm run devcd mobile
cp .env.example .env.local
pnpm install
pnpm start- Source of truth:
backend/src/docs/openapi.yaml - Dev Swagger UI:
http://localhost:4000/api/docs - JSON export:
http://localhost:4000/api/docs/openapi.json - API contract examples:
backend/docs/api-contract-examples.md— JS/TypeScript snippets for authentication and all trade operations - SDK usage guide:
backend/docs/sdk-usage.md— typed client wrapper for frontend, mobile, and Node.js
The backend writes backend/src/docs/openapi.json from the YAML spec in non-production runs so reviewers can inspect either format.
cd contracts/amana_escrowcargo build
Amana enforces stack-level CI gates on pull requests through .github/workflows/ci.yml.
- Frontend Required Gate:
pnpm install --frozen-lockfile,pnpm run lint,pnpm run build,pnpm testinfrontend/ - Backend Required Gate:
pnpm install --frozen-lockfile,pnpm run build,pnpm testinbackend/ - Mobile Required Gate:
pnpm install --frozen-lockfile,pnpm run type-check,pnpm run lintinmobile/ - Contracts Required Gate:
cargo testincontracts/amana_escrow/
Path-aware execution is enabled to avoid unnecessary runtime. If a stack has no changed files, the gate reports a skip-note and passes.
For the protected branch (main), set these required status checks:
Frontend Required GateBackend Required GateContracts Required Gate
- Initiate: The Seller lists products. The Buyer initiates a trade, depositing funds that are converted to cNGN via a Stellar Path Payment.
- Lock: The Smart Contract locks the funds and stores the agreed-upon
Loss_Ratio. - Dispatch: The Seller provides the driver's name, phone number, and vehicle manifest.
- Verification: - Success: Buyer receives goods and uploads a confirmation video. Funds release to Seller.
- Dispute: Buyer uploads a video of loss/damage with driver affirmation. A mediator reviews the evidence.
- Settlement: Based on the outcome, funds are distributed (either 100% to one party or split via the
Loss_Ratio).
- Develop core Soroban contract logic (
deposit,release,refund). - Implement basic Next.js UI for trade creation.
- Integrate
Loss_Ratiovariables into the smart contract. - Build the "Mediator" dashboard for dispute resolution.
- IPFS integration for video evidence uploads.
- Driver manifest logging and tracking interface.
- Public pilot program with regional agricultural cooperatives.
- Implementation of a "Trust Score" reputation system.
Amana includes comprehensive distributed tracing with OpenTelemetry for end-to-end request visibility and faster incident triage.
- Correlation IDs: Unique identifiers spanning frontend-backend requests
- Request Tracing: Complete request lifecycle tracking
- Service Integration: Automatic tracing for external services (IPFS, Stellar)
- Observability: Jaeger, Zipkin, and Prometheus integration
- Configure tracing environment variables (see
backend/.env.tracing.example) - Start Jaeger for trace visualization:
docker run -p 16686:16686 jaegertracing/all-in-one - View traces at
http://localhost:16686 - Check metrics at
http://localhost:9464/metrics
See DISTRIBUTED_TRACING_GUIDE.md for detailed setup and usage instructions.
Application Metrics & Monitoring:
- Prometheus Metrics — Trade throughput, dispute counts, and processing latency metrics exposed at
/metrics
- System Architecture — High-level architecture overview, component interactions, and deployment topology
- Sequence Diagrams — Detailed workflow sequences for trade creation, dispute resolution, audit trails, and more
- Audit Logging — Tamper-evident audit trail with cryptographic signatures and verification
- Mediator Dashboard Spec — Complete specification for mediator dashboard including user stories, UI mockups, and implementation tasks
Testing & Quality Assurance:
- Visual Regression Testing — Frontend UI regression tests using Playwright with multi-viewport support
Key architectural decisions are documented as ADRs in docs/adr/:
- ADR-001: Stellar Path Payment Architecture
- ADR-002: Escrow Loss-Sharing Model
- ADR-003: Off-chain vs. On-chain Data Partitioning
- ADR-004: Idempotency and Retry Strategy
- ADR-005: Frontend State Management
Amana is an open-source project aimed at improving food security and trade efficiency. We welcome developers, designers, and agricultural experts!
New to the project? Start with the Contributor Onboarding Guide for setup instructions and development workflows.
Full guidelines: See CONTRIBUTING.md for code standards, testing requirements, and PR process.
Quick start:
- Fork the Project.
- Create your Feature Branch (
git checkout -b feature/NewFeature). - Commit your Changes (
git commit -m 'Add NewFeature'). - Push to the Branch (
git push origin feature/NewFeature). - Open a Pull Request.
Distributed under the MIT License. See LICENSE for more information.
// setting up and starting out