TraceRoot is an on-chain supply chain provenance protocol that creates tamper-proof records of a product's journey from raw material to end consumer. Every checkpoint — manufacturing, quality inspection, shipping, customs, warehousing, retail — is logged as an immutable event on the blockchain, giving consumers and regulators a single source of truth.
Built for industries where authenticity matters: pharmaceuticals, agriculture, luxury goods, and food safety.
Counterfeit pharmaceuticals account for over $200 billion in global trade annually. In West Africa, the WHO estimates that 1 in 10 medical products is substandard or falsified. Agricultural exports lose value when provenance can't be verified. Consumers have no way to confirm that what they're buying is what the label says it is.
Existing supply chain solutions are either centralized (controlled by one company, easily manipulated), expensive (enterprise licensing fees that exclude SMEs), or incomplete (only tracking part of the chain).
TraceRoot is different. It's open, permissionless, and built on public infrastructure — making verifiable provenance accessible to businesses of any size.
MANUFACTURER DISTRIBUTOR LOGISTICS RETAILER CONSUMER
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ │ │ │ │ │ │ │ │
│ Register │──────►│ Receive │─────►│ Ship │────►│ Receive │─────►│ Scan │
│ Product │ │ & Verify │ │ & Track │ │ & Stock │ │ & View │
│ │ │ │ │ │ │ │ │ History │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌────────────────────────────────────────────────────────────────────────────────┐
│ │
│ TraceRoot Protocol (Soroban) │
│ │
│ product_registry · checkpoint_logger · actor_registry · verifier │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
Each product registered on TraceRoot has a unique on-chain identity:
Product {
product_id: BytesN<32>, // SHA-256 hash of batch + serial
manufacturer: Address, // registered manufacturer wallet
category: ProductCategory, // Pharmaceutical | Agriculture | Luxury | Food
metadata: ProductMeta {
name: String, // "Amoxicillin 500mg"
batch_number: String, // "BATCH-2026-0411"
manufacture_date: u64, // unix timestamp
expiry_date: Option<u64>, // optional expiry
origin_country: String, // "NG"
certifications: Vec<String>,// ["NAFDAC/A1-2345", "WHO-GMP"]
},
status: ProductStatus, // InProduction | InTransit | Delivered | Recalled
checkpoint_count: u32,
registered_at: u64,
}Every time a product changes hands or passes through a control point, a checkpoint is recorded:
Checkpoint {
checkpoint_id: u32,
product_id: BytesN<32>,
actor: Address, // who logged this checkpoint
action: CheckpointAction, // Manufactured | QualityChecked | Shipped |
// CustomsCleared | Received | Stored | Sold
location: Location {
latitude: i64, // fixed-point (× 1_000_000)
longitude: i64,
facility_name: String, // "Lagos Port Authority Warehouse B"
},
evidence: Option<String>, // IPFS hash of supporting docs (CoA, BoL, etc.)
temperature: Option<i32>, // cold chain tracking (× 100 for precision)
notes: String,
timestamp: u64,
}Supply chain participants must be registered and verified before they can log checkpoints:
Actor {
wallet: Address,
role: ActorRole, // Manufacturer | Distributor | Transporter |
// Inspector | Retailer | Regulator
organization: String, // "Emzor Pharmaceutical Industries"
license_number: String, // regulatory license/permit
verified: bool, // verified by a Regulator actor
registered_at: u64,
}Handles product registration and lifecycle management.
fn register_product(manufacturer: Address, meta: ProductMeta) -> BytesN<32>;
fn update_status(actor: Address, product_id: BytesN<32>, status: ProductStatus);
fn recall_product(manufacturer: Address, product_id: BytesN<32>, reason: String);
fn get_product(product_id: BytesN<32>) -> Product;
fn get_manufacturer_products(manufacturer: Address) -> Vec<Product>;Records and queries provenance checkpoints.
fn log_checkpoint(actor: Address, product_id: BytesN<32>, data: CheckpointInput);
fn get_checkpoints(product_id: BytesN<32>) -> Vec<Checkpoint>;
fn get_latest_checkpoint(product_id: BytesN<32>) -> Checkpoint;
fn get_checkpoint_count(product_id: BytesN<32>) -> u32;Manages supply chain participant identities and permissions.
fn register_actor(wallet: Address, role: ActorRole, org: String, license: String);
fn verify_actor(regulator: Address, actor_wallet: Address);
fn revoke_actor(regulator: Address, actor_wallet: Address);
fn get_actor(wallet: Address) -> Actor;
fn is_verified(wallet: Address) -> bool;Consumer-facing verification logic.
fn verify_product(product_id: BytesN<32>) -> VerificationResult;
fn get_full_journey(product_id: BytesN<32>) -> ProductJourney;
fn check_expiry(product_id: BytesN<32>) -> ExpiryStatus;
fn flag_suspicious(reporter: Address, product_id: BytesN<32>, reason: String);End consumers interact with TraceRoot through a simple scan-and-verify experience:
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ │ │ │ │ │
│ Scan QR on │────────►│ TraceRoot │────────►│ Product Journey │
│ product │ │ Lookup │ │ │
│ packaging │ │ │ │ ✓ Manufactured: │
│ │ │ │ │ Emzor, Lagos │
└──────────────┘ └──────────────┘ │ 2026-03-15 │
│ │
│ ✓ Quality Check: │
│ NAFDAC Inspector │
│ 2026-03-18 │
│ │
│ ✓ Shipped: │
│ DHL Express │
│ Lagos → Abuja │
│ │
│ ✓ Received: │
│ HealthPlus Pharmacy│
│ Wuse 2, Abuja │
│ 2026-03-22 │
│ │
│ Status: AUTHENTIC ✓ │
└──────────────────────┘
| Component | Technology | Purpose |
|---|---|---|
| Smart Contracts | Rust / Soroban SDK | On-chain provenance logic |
| Backend API | NestJS, TypeORM, PostgreSQL | Off-chain indexing, caching, search |
| Web Dashboard | Next.js 14, TypeScript, Tailwind CSS | Manufacturer & distributor portal |
| Consumer App | Next.js PWA | Mobile-first scan & verify |
| QR Generation | qrcode library + contract address encoding |
Product-level QR codes |
| Document Storage | IPFS / Filecoin | Certificates, bills of lading, lab reports |
| Cold Chain | IoT webhook integration | Temperature logging for perishables |
traceroot/
│
├── contracts/
│ ├── product-registry/
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── product.rs
│ │ ├── storage.rs
│ │ └── events.rs
│ │
│ ├── checkpoint-logger/
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── checkpoint.rs
│ │ └── validation.rs
│ │
│ ├── actor-registry/
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── actor.rs
│ │ └── permissions.rs
│ │
│ └── verifier/
│ └── src/
│ ├── lib.rs
│ ├── verify.rs
│ └── reporting.rs
│
├── dashboard/ # Manufacturer & distributor web app
│ ├── app/
│ │ ├── products/ # Product management
│ │ ├── checkpoints/ # Checkpoint logging
│ │ ├── actors/ # Team management
│ │ └── analytics/ # Supply chain analytics
│ ├── components/
│ └── lib/
│
├── consumer-app/ # PWA for consumers
│ ├── app/
│ │ ├── scan/ # QR scanner
│ │ ├── verify/[id]/ # Product verification page
│ │ └── report/ # Flag suspicious products
│ └── components/
│
├── backend/
│ ├── src/
│ │ ├── modules/
│ │ │ ├── indexer/ # Blockchain event indexer
│ │ │ ├── products/ # Product API
│ │ │ ├── checkpoints/ # Checkpoint API
│ │ │ ├── qr/ # QR code generation
│ │ │ └── alerts/ # Anomaly detection & alerts
│ │ └── services/
│ └── migrations/
│
└── docs/
├── architecture.md
├── onboarding-guide.md
├── api-reference.md
├── regulatory-compliance.md
└── iot-integration.md
- Rust 1.77+ with
wasm32-unknown-unknowntarget - Soroban CLI
- Node.js 20+
- PostgreSQL 15+
- Docker (optional, for local development)
git clone https://github.com/your-org/traceroot.git
cd traceroot
# Build smart contracts
cd contracts
cargo build --target wasm32-unknown-unknown --release
cargo test
# Start backend
cd ../backend
cp .env.example .env
npm install
npm run migration:run
npm run start:dev
# Start dashboard
cd ../dashboard
npm install
npm run dev
# Start consumer app
cd ../consumer-app
npm install
npm run dev# Backend
DATABASE_URL=postgresql://user:pass@localhost:5432/traceroot
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
IPFS_GATEWAY_URL=https://gateway.pinata.cloud
PINATA_API_KEY=your-pinata-key
# Contracts
PRODUCT_REGISTRY_ID=CAAAA...
CHECKPOINT_LOGGER_ID=CBBBB...
ACTOR_REGISTRY_ID=CCCCC...
VERIFIER_ID=CDDDD...Pharmaceuticals — Track drugs from factory to pharmacy. Verify NAFDAC registration numbers on-chain. Flag counterfeits before they reach patients.
Agriculture — Prove origin and quality of export crops. Link lab test results (mycotoxin levels, pesticide residue) to specific batches. Enable premium pricing for verified organic produce.
Food & Beverages — Cold chain monitoring for perishables. Recall management with instant batch identification. Halal/Kosher certification verification.
Luxury Goods — Authenticate high-value items with immutable provenance records. Prevent grey market diversion. Enable verified resale markets.
- Protocol architecture and data model
- Product registry contract
- Checkpoint logger contract
- Actor registry and verification
- Consumer verification contract
- Backend API and blockchain indexer
- Manufacturer dashboard
- Consumer PWA with QR scanning
- QR code generation service
- IPFS document storage integration
- IoT cold chain webhook support
- NAFDAC pilot partnership
- Mainnet deployment
We're building critical infrastructure for product safety. Contributions from developers, supply chain professionals, and regulatory experts are all valuable.
- Fork the repository
- Create your feature branch (
git checkout -b feature/checkpoint-validation) - Write tests for your changes
- Commit (
git commit -m 'feat: add checkpoint validation rules') - Push (
git push origin feature/checkpoint-validation) - Open a Pull Request
Please read CONTRIBUTING.md before submitting.
GNU General Public License v3.0 — See LICENSE
TraceRoot — Every product has a story. We make it verifiable.