🌾 EziAgric: Trust as a Service for Agricultural Products

EziAgric 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.

---

🚀 The Mission

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.

🛠 Features

• 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.

🏗 Technical Stack

• 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.

🧪 Local Environments (Folder-Based)

• 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

Frontend setup

1. cd frontend
2. cp .env.example .env.local
3. pnpm install (frontend is pnpm-managed — do not run npm install here, it creates a stray package-lock.json)
4. pnpm dev

Backend setup

1. cd backend
2. cp .env.example .env
3. cp .env.tracing.example .env.tracing (for distributed tracing configuration)
4. pnpm install (backend is pnpm-managed — do not run npm install here)
5. pnpm dev

Mobile setup

1. cd mobile
2. cp .env.example .env.local
3. pnpm install (mobile is pnpm-managed — do not run npm install here)
4. pnpm start

Backend API docs

• 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

The backend writes backend/src/docs/openapi.json from the YAML spec in non-production runs so reviewers can inspect either format.

Contracts setup

1. cd contracts/amana_escrow
2. cargo build

🔒 Required PR CI Gates

Amana enforces stack-level CI gates on pull requests through .github/workflows/ci.yml.

• Lockfile Drift Check: ./scripts/check-lockfile-drift.sh — fails fast if a pnpm-lock.yaml/package-lock.json is out of sync with its package.json, or if a stray package-lock.json reappears in pnpm-managed frontend//backend//mobile/
• Frontend Required Gate: pnpm install --frozen-lockfile, pnpm lint, pnpm build, pnpm test in frontend/
• Backend Required Gate: pnpm install --frozen-lockfile, pnpm build, pnpm test in backend/
• Mobile Required Gate: pnpm install --frozen-lockfile, pnpm type-check, pnpm lint in mobile/
• Contracts Required Gate: cargo test in contracts/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.

Branch protection setup (GitHub)

For the protected branch (main), set these required status checks:

• Frontend Required Gate
• Backend Required Gate
• Contracts Required Gate

---

---

🔄 How It Works (The Amana Flow)

1. Initiate: The Seller lists products. The Buyer initiates a trade, depositing funds that are converted to cNGN via a Stellar Path Payment.
2. Lock: The Smart Contract locks the funds and stores the agreed-upon Loss_Ratio.
3. Dispatch: The Seller provides the driver's name, phone number, and vehicle manifest.
4. 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.
5. Settlement: Based on the outcome, funds are distributed (either 100% to one party or split via the Loss_Ratio).

---

🗺 Roadmap

Phase 1: The Vault (MVP)

• Develop core Soroban contract logic (deposit, release, refund).
• Implement basic Next.js UI for trade creation.

Phase 2: The Agreement Engine

• Integrate Loss_Ratio variables into the smart contract.
• Build the "Mediator" dashboard for dispute resolution.

Phase 3: Evidence & Logistics

• IPFS integration for video evidence uploads.
• Driver manifest logging and tracking interface.

Phase 4: Mainnet & Scale

• Public pilot program with regional agricultural cooperatives.
• Implementation of a "Trust Score" reputation system.

---

🔍 Distributed Tracing

Amana includes comprehensive distributed tracing with OpenTelemetry for end-to-end request visibility and faster incident triage.

Features

• 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

Quick Start

1. Configure tracing environment variables (see backend/.env.tracing.example)
2. Start Jaeger for trace visualization: docker run -p 16686:16686 jaegertracing/all-in-one
3. View traces at http://localhost:16686
4. Check metrics at http://localhost:9464/metrics

Documentation

See docs/distributed-tracing.md for detailed setup and usage instructions.

---

📐 Architecture Decision Records

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

🔐 Security & Operations

• Threat Model — reviewed quarterly and on trigger events; see §8 for cadence/ownership and docs/threat-model-review-checklist.md for the reviewer checklist.
• Secrets Policy & Rotation — secrets inventory (owner, location, max-age), rotation automation, and verification. Rotation reminders are opened automatically by .github/workflows/secrets-rotation-reminder.yml.
• PII Encryption at Rest — classified PII column inventory, app-layer envelope encryption design, blind-index search, key rotation procedure, and decrypt access logging.
• Software Bill of Materials (SBOM) — CycloneDX SBOM generated for every release artifact via .github/workflows/sbom.yml, attached to GitHub Releases, with a weekly vulnerability diff scan.
• Golden Signals Dashboard — Grafana dashboard stored as code (infra/grafana/) covering API latency/traffic/errors and DB/queue saturation, with deploy annotations wired into staging deploys.
• Alert Routing Policy — page-vs-ticket severity rubric, runbook linkage enforced in CI, per-alert dedup windows, and the monthly alert review log.
• Synthetic Probes Policy — hourly staging probe of the core escrow journey (auth → create → deposit → release), with failure alerting and a results dashboard log.
• Incident Response — severity levels, incident roles, and channel/ticket conventions; see the postmortem template, the postmortem archive, and a worked tabletop exercise.

🤝 Contributing

EziAgric is an open-source project aimed at improving food security and trade efficiency. We welcome developers, designers, and agricultural experts!

Please read and follow our Code of Conduct. By participating in this project you agree to abide by its terms.

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/NewFeature).
3. Commit your Changes (git commit -m 'Add NewFeature').
4. Push to the Branch (git push origin feature/NewFeature).
5. Open a Pull Request (see Code Ownership Policy for automated review routing).

Admin route development

If you are adding or modifying admin routes, see the Admin Route Contribution Guide for architecture details, middleware requirements, testing expectations, and a step-by-step example.

📄 License

Distributed under the MIT License. See LICENSE for more information.

// setting up and starting out