🌾 Amana: Trust as a Service for Agricultural Products

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.

---

🚀 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): A mandatory video-based verification protocol involving the buyer and the driver to confirm the state of goods.
• 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)
• contracts/ → Rust/Soroban smart contract environment

Frontend setup

1. cd frontend
2. cp .env.example .env.local
3. npm run dev

Backend setup

1. cd backend
2. cp .env.example .env
3. cp .env.tracing.example .env (for distributed tracing configuration)
4. npm install (to install new OpenTelemetry dependencies)
5. npm run dev

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.

• Frontend Required Gate: npm ci, npm run lint, npm run build in frontend/
• Backend Required Gate: npm ci, npm run build, npm test in backend/
• 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 DISTRIBUTED_TRACING_GUIDE.md for detailed setup and usage instructions.

---

🤝 Contributing

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

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.

📄 License

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