Skip to content
BranchesTags

Repository files navigation

ChainLojistic - Decentralized Supply Chain Tracking

🌍 Project Overview

ChainLojistic is an open-source, blockchain-based supply chain provenance tracker built on Stellar's Soroban platform. It enables transparent, tamper-proof tracking of products from origin to consumer, solving trust and verification issues in global supply chains.

Contract Address (Testnet)

The MVP is deployed as two wired instances built from one WASM. The frontend/backend point at MAIN:

# MAIN — ProductRegistry + ChainLogistics (this is NEXT_PUBLIC_CONTRACT_ID)
CDN45LYNJLEHVWLYAN34CFSBUT4RWTFWKG5I7LMDJS2QNC2L6RLLEZWR
# AUTH — AuthorizationContract
CCAPPFD5PERFZ6T66XPU74NZBZXHJBSQIFST4GOVMYIDZR4D54VYRXHQ

NEXT_PUBLIC_CONTRACT_ID=CDN45LYNJLEHVWLYAN34CFSBUT4RWTFWKG5I7LMDJS2QNC2L6RLLEZWR
NEXT_PUBLIC_STELLAR_NETWORK=testnet

Redeploy with smart-contract/scripts/deploy-testnet.sh (see DEPLOYMENT.md).

🎯 The Problem

Modern supply chains face critical trust challenges:

  • No Transparency: Consumers can't verify product claims (organic, fair-trade, sustainable)
  • Counterfeit Products: $4.5 trillion lost annually to fake goods
  • Broken Trust: 73% of consumers don't trust company sustainability claims
  • Paper Trail Failures: Documents are easily forged, lost, or altered
  • Data Silos: Each party maintains separate records, creating inconsistencies
  • Fraud & Waste: $40+ billion lost annually in supply chain fraud

Real Examples:

  • Coffee labeled "fair trade" but farmers received standard prices
  • "Organic" produce treated with pesticides
  • Electronics with conflict minerals despite "ethical sourcing" claims
  • Counterfeit medications killing 250,000+ people annually

💡 The Solution

ChainLojistic provides a decentralized, immutable ledger for supply chain tracking:

Core Features

1. Product Registration

  • Register products at origin with complete details
  • Cryptographic proof of authenticity
  • Unique blockchain ID for each item

2. Event Tracking

  • Record every step: harvest, processing, shipping, quality checks
  • Timestamp and location data
  • Multi-party authorization (farmers, processors, shippers, retailers)

3. Verification

  • QR code scanning for instant verification
  • Complete product journey visible to consumers
  • Tamper-proof records on blockchain

4. Transparency

  • All stakeholders see the same data
  • No single point of control
  • Immutable audit trail

🏗️ Architecture

Technology Stack

Smart Contracts (Rust + Soroban)

  • Product registration and storage
  • Event tracking and indexing
  • Access control and authorization
  • Deployed on Stellar blockchain

Frontend (Next.js 15 + React 19 + TypeScript)

  • User-friendly web interface
  • Wallet integration (Freighter)
  • Product registration forms
  • Visual timeline of product journey
  • QR code generation
  • Search and analytics

Backend (Rust + Axum + SQLx) - High-Performance API Server

  • REST API for integrations with 3-10x performance improvement
  • Async webhook system with Tokio runtime
  • PostgreSQL database with SQLx for type-safe queries
  • Real-time analytics and reporting
  • Third-party SDKs (Rust + Python via PyO3)
  • Comprehensive caching and rate limiting

Data Flow

Producer → Register Product → Blockchain
    ↓
Processor → Add Event → Blockchain
    ↓
Shipper → Add Event → Blockchain
    ↓
Retailer → Add Event → Blockchain
    ↓
Consumer → Scan QR → View Full History

🎨 User Interface

For Producers

  • Simple product registration form
  • Bulk import capabilities
  • Dashboard showing registered products
  • QR code generation and printing

For Supply Chain Partners

  • Add tracking events (location, timestamp, metadata)
  • Upload supporting documents/photos
  • View product history
  • Manage authorized actors

For Consumers

  • Scan QR code with phone camera
  • View complete product journey
  • Verify authenticity claims
  • Report issues or concerns

For Administrators

  • Analytics dashboard
  • Search and filter products
  • Export data for compliance
  • Manage access permissions

🌟 Key Benefits

For Producers

  • Build Trust: Prove your claims with blockchain evidence
  • Premium Pricing: Verified products command higher prices
  • Brand Protection: Combat counterfeits
  • Compliance: Automated regulatory reporting

For Consumers

  • Transparency: See exactly where products come from
  • Safety: Verify authenticity, especially for medications
  • Values Alignment: Support truly ethical/sustainable products
  • Empowerment: Make informed purchasing decisions

For Supply Chains

  • Efficiency: Reduce paperwork and manual verification
  • Traceability: Quickly trace issues back to source
  • Collaboration: Shared truth across all parties
  • Innovation: Enable new business models

📊 Use Cases

1. Food & Agriculture

Problem: Organic/fair-trade fraud is rampant Solution: Track coffee beans from Ethiopian farm to Seattle café

Example Flow:

Farm (Ethiopia) → Harvest event + GPS + Organic cert
    ↓
Processing Plant → Washing/drying event + Quality check
    ↓
Export Warehouse → Packaging event + Fair-trade verification
    ↓
Shipping → Transit event + Temperature monitoring
    ↓
Roaster (USA) → Roasting event + Batch details
    ↓
Café → Final event
    ↓
Consumer → Scans QR code, sees entire journey

2. Pharmaceuticals

Problem: Counterfeit drugs kill 250,000+ annually Solution: Verify medication authenticity from factory to pharmacy

Tracking:

  • Manufacturing batch number
  • Quality control tests
  • Cold chain compliance (temperature logs)
  • Distribution checkpoints
  • Pharmacy receipt verification

3. Fashion & Textiles

Problem: "Sustainable" claims often unverified Solution: Prove ethical sourcing and manufacturing

Verification:

  • Organic cotton certification at farm
  • Fair wage documentation at factory
  • Carbon footprint calculations
  • Recycling/circular economy tracking

4. Electronics

Problem: Conflict minerals funding violence Solution: Verify conflict-free sourcing

Tracking:

  • Mine origin documentation
  • Smelter certifications
  • Component manufacturing
  • Assembly plant compliance
  • E-waste recycling

5. Luxury Goods

Problem: $450B+ lost to counterfeits annually Solution: Authenticate high-value items

Features:

  • Unique blockchain ID per item
  • Transfer of ownership tracking
  • Authentication certificates
  • Resale value protection

🔐 Security & Privacy

Blockchain Security

  • Immutable records (can't be altered or deleted)
  • Cryptographic signatures for authenticity
  • Decentralized storage (no single point of failure)
  • Transparent audit trail

Access Control

  • Role-based permissions
  • Only authorized actors can add events
  • Private data encryption options
  • Selective disclosure (show only what's needed)

Privacy Features

  • Personal data kept off-chain
  • Zero-knowledge proofs for sensitive info
  • GDPR compliant design
  • Consumer privacy protected

🌍 Impact

Environmental

  • Reduce fraud in carbon offset markets
  • Enable circular economy tracking
  • Verify sustainable sourcing claims
  • Reduce waste through better traceability

Social

  • Protect workers through fair-trade verification
  • Combat child labor with supply chain visibility
  • Empower small producers
  • Build consumer trust

Economic

  • Reduce supply chain fraud ($40B+ annually)
  • Enable premium pricing for verified products
  • Lower insurance costs through traceability
  • Create new verification business models

🚀 Project Status

Current Phase: MVP Development

  • ✅ Smart contract architecture designed
  • ✅ Frontend scaffolded
  • ✅ Project documentation complete
  • 🔄 Core features in development
  • 📅 Beta launch: Q2 2024
  • 📅 Mainnet deployment: Q3 2024

Roadmap

Phase 1 - MVP (Q1 2024)

  • Product registration
  • Event tracking
  • Basic UI
  • Wallet integration
  • QR code generation

Phase 2 - Security (Q2 2024)

  • Access control implementation
  • Security audit
  • E2E testing
  • Rate limiting

Phase 3 - User Experience (Q2-Q3 2024)

  • Timeline visualization
  • Search and filters
  • Analytics dashboard
  • Mobile app

Phase 4 - Integrations (Q3 2024)

  • REST API
  • Webhooks
  • Third-party integrations
  • SDK development

Phase 5 - Scale (Q4 2024)

  • Performance optimization
  • Multi-language support
  • Enterprise features
  • Mainnet launch

🚀 Project Startup

If you're a new contributor looking to run the project locally, follow these steps to get started:

Prerequisites

  • Rust 1.84+: Required for both smart contracts and backend (soroban-sdk 25 needs the wasm32v1-none target). curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Soroban CLI: stellar CLI >= 27 (soroban-sdk 25 targets protocol 27). Install: curl --proto '=https' --tlsv1.2 -sSf https://stellar.org/install.sh | sh
  • WASM Target: rustup target add wasm32v1-none (NOT wasm32-unknown-unknown, which soroban-sdk 25 rejects on Rust 1.82+)
  • Node.js 18+ & npm/yarn: For the frontend.
  • PostgreSQL 14+ & Redis 6+: For the backend database and caching.

Quick Start Guide

# 1. Clone the repository
git clone https://github.com/ChainLojistics/ChainLogistics.git
cd ChainLogistics

# 2. Build Smart Contracts
cd smart-contract
cargo build --target wasm32v1-none --release
cargo test

# 3. Start Frontend
cd ../frontend
npm install
npm run dev  # Runs on http://localhost:3000

# 4. Start Backend Server
cd ../backend
cp .env.example .env
cargo build
cargo run  # Runs on http://localhost:3001

For more comprehensive guidelines on contributing to this project, including detailed workflows and issue labels, see our CONTRIBUTING.md.

🤝 Contributing

We welcome contributors of all skill levels! This project offers opportunities to:

  • Learn blockchain development (Soroban/Stellar)
  • Build modern web applications (Next.js/React)
  • Solve real-world problems
  • Join a growing community

Ways to Contribute:

  • Code (smart contracts, frontend, backend - Rust/Axum)
  • Documentation
  • Design (UI/UX)
  • Testing
  • Community support
  • Translations

See CONTRIBUTING.md for detailed guide.

📈 Success Metrics

Adoption

  • Products tracked: Target 10,000 by EOY 2024
  • Active supply chain partners: Target 100
  • Consumer verifications: Target 50,000/month

Technical

  • Transaction throughput: >1000 TPS
  • API uptime: 99.9%
  • Response time: <2 seconds
  • Test coverage: >80%

Community

  • Contributors: 50+
  • GitHub stars: 1000+
  • Active users: 5000+

🏆 Why Stellar/Soroban?

We chose Stellar's Soroban platform because:

  1. Fast: 3-5 second finality (perfect for supply chain)
  2. Cheap: Fractions of a cent per transaction
  3. Scalable: Thousands of TPS
  4. Sustainable: Energy-efficient consensus
  5. Global: Built for cross-border use cases
  6. Developer-Friendly: Rust + modern tooling

🔄 Comparison to Alternatives

vs. Paper-Based Systems

  • ✅ Tamper-proof vs ❌ Easy to forge
  • ✅ Instant verification vs ❌ Slow manual checks
  • ✅ Always available vs ❌ Can be lost
  • ✅ Transparent vs ❌ Opaque

vs. Centralized Databases

  • ✅ No single point of failure vs ❌ Vendor lock-in
  • ✅ Multi-party trust vs ❌ Single authority
  • ✅ Transparent vs ❌ Black box
  • ✅ Immutable vs ❌ Can be altered

vs. Other Blockchains

  • ✅ Fast (3-5s) vs ❌ Slow (minutes/hours on Bitcoin/Ethereum)
  • ✅ Cheap ($0.00001) vs ❌ Expensive ($10-100 on Ethereum)
  • ✅ Sustainable vs ❌ Energy-intensive
  • ✅ Built for payments vs ❌ General purpose

📚 Technical Details

Smart Contract Functions

// Register a new product
register_product(id, name, origin, owner) -> Product

// Add tracking event
add_tracking_event(product_id, location, event_type, metadata) -> Event

// Get product details
get_product(id) -> Product

// Get all events for a product
get_tracking_events(product_id) -> Vec<Event>

// Transfer ownership
transfer_ownership(product_id, new_owner) -> Success

// Authorize actor to add events
add_authorized_actor(product_id, actor_address) -> Success

API Endpoints

GET    /api/products              # List products
POST   /api/products              # Register product
GET    /api/products/:id          # Get product
GET    /api/products/:id/events   # Get events
POST   /api/products/:id/events   # Add event
GET    /api/analytics             # Analytics data

Data Models

Product

{
  id: string;              // Unique identifier
  name: string;            // Product name
  origin: string;          // Origin location
  owner: Address;          // Current owner
  timestamp: number;       // Registration time
  authorized_actors: Address[];  // Who can update
}

TrackingEvent

{
  product_id: string;      // Product reference
  location: string;        // Current location
  actor: Address;          // Who created event
  timestamp: number;       // Event time
  event_type: string;      // HARVEST, SHIPPING, etc.
  metadata: string;        // Additional info (JSON)
}

🎓 Educational Value

This project is excellent for learning:

Blockchain Development

  • Smart contract patterns
  • Soroban SDK
  • Stellar network
  • Cryptographic verification

Web3 Frontend

  • Wallet integration
  • Transaction signing
  • Blockchain data queries
  • Real-time updates

Full-Stack Development

  • Rust REST API design with Axum
  • PostgreSQL optimization with SQLx
  • Redis caching strategies
  • Async security best practices

System Design

  • Distributed systems
  • Data modeling
  • Access control
  • Scalability patterns

💰 Sustainability Model

Open Source First

  • Core platform: Free and open source
  • Community-driven development
  • Transparent governance

Revenue Streams (Optional)

  • Hosted SaaS version for enterprises
  • White-label solutions
  • Premium features (advanced analytics, integrations)
  • Consulting and support services
  • Grant funding from Stellar Foundation

🔗 Links & Resources

📧 Contact

📄 License

MIT License - Free to use, modify, and distribute

🌟 Vision Statement

"Making supply chains transparent, trustworthy, and traceable for everyone."

We envision a world where:

  • Consumers know exactly what they're buying
  • Producers are rewarded for ethical practices
  • Fraud and counterfeits are eliminated
  • Trust is built through transparency, not marketing
  • Supply chains benefit everyone, not just corporations

Join us in building the future of transparent commerce! 🚀

⭐ Star This Project

If you find ChainLojistic valuable, please give us a star on GitHub! It helps others discover the project and motivates our community.

⭐ Star on GitHub

Built with ❤️ by the ChainLojistic community Powered by Stellar & Soroban

About

ChainLojistic is an open-source, blockchain-based supply chain provenance tracker built on Stellar's Soroban platform. It enables transparent, tamper-proof tracking of products from origin to consumer, solving trust and verification issues in global supply chains.

chain-logistics-olive.vercel.app

Resources

Readme

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

44 forks
Report repository

Releases

Packages

Contributors

Languages