🌿 Raíz Protocol

Decentralized Attestation & AI Oracle Infrastructure for Agricultural Provenance, Fair Escrow & Real-World Assets (RWA) on Stellar & Soroban

Open-source decentralized public goods infrastructure on Stellar: Connecting unbanked smallholder coffee growers, beekeepers, and indigenous artisans from the Mixteca region of Oaxaca with global ethical buyers through verifiable on-chain attestations.
Researched, designed, and engineered by indigenous Computer Systems Engineering student-researchers at Instituto Tecnológico de Tlaxiaco (Oaxaca, Mexico)

Overview • Empirical Field Research • Architecture & Engineering Status • Unified Settlement Stack • Quickstart • Documentation Center

---

📌 Overview

Raíz is an open-source decentralized protocol for Traceability, Visibility, and Verifiable Provenance (RWA) built on the Stellar Network and Soroban Smart Contracts.

Conceived in the mountainous Mixteca Highlands of Oaxaca (Heroica Ciudad de Tlaxiaco, San José Xochixtlán, San Pablo Tijaltepec, San Juan Mixtepec, San Juan Ñumí, and San Antonio Nduaxico), Raíz eliminates digital and financial exclusion for smallholders and ancestral artisans through an Offline-First PWA operated by voice in their native language (Tu'un Savi / Mixteco).

---

⚡ Executive Summary in 60 Seconds

• The Problem: Smallholder indigenous coffee farmers, beekeepers, and textile artisans in Oaxaca lose up to 70% of their product value to predatory middlemen (coyotes), face systematic counterfeiting from industrial knockoffs, and are 100% excluded from digital banking (no internet in parcels, no credit cards, language barriers in Tu'un Savi).
• The Solution: An Offline-First Voice PWA that allows an elder artisan to register a harvest by voice without typing. The system computes a cryptographic SHA-256 digest, prints a physical ISO/IEC 18004 hang-tag QR, anchors verifiable attestations on Stellar/Soroban, and locks purchase funds in milestone-based escrow.
• The Impact: When delivered, funds are converted from on-chain USDC directly into local Mexican Pesos (MXN) via Banxico SPEI into Banco del Bienestar debit cards or cash via local transport cooperatives (MicoPay)—with 0% exploitative fees to the producer.

---

🗺️ End-to-End User Journey Map

How a coffee grower or textile artisan interacts with Raíz—step by step, with direct links to the implementation code:

┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 1. PARCEL REGISTRATION ──▶ 2. CRYPTOGRAPHIC TWIN ──▶ 3. ESCROW FUNDING ──▶ 4. SETTLEMENT & PAYOUT      │
│ (Offline / Voice)          (Hang-Tag QR & Ledger)     (Soroban Milestone)     (Banxico SPEI / Cash)    │
└────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Step	User & System Action	Technical Component & Direct Code Link
1	Oral Harvest Log (Offline): Don Juan presses the 112px voice button in Yucuhiti, speaking in Tu'un Savi: "Kuni yu kiti 120 kilos café pergamino". Audio is encoded at 24kbps Opus without cell signal.	src/components/VoiceAssistantModal.tsx src/core/sync/IndexedDbOutbox.ts
2	Cryptographic Digital Twin: The system extracts metadata, computes the canonical SHA-256 Community Digest, and generates a printable vector SVG hang-tag QR for the physical coffee sack.	src/core/crypto/CryptoEngine.ts src/components/PhysicalQRCard.tsx
3	B2B Escrow Lock (Soroban): A specialty coffee buyer in Zurich or CDMX inspects the digital lot passport and locks $10,000 MXNe in an audited milestone escrow contract.	contracts/fair_escrow/ src/core/blockchain/TrustlessWorkEscrowAdapter.ts
4	Milestone 1 Release (30%): The Tlaxiaco Cooperative Oracle signs the origin & quality attestation conforming to the SEP-RWA standard. A 30% advance ($3,000 MXN) is released to the producer.	docs/standards/SEP_RWA_ATTESTATION_DRAFT.md src/core/ai/RaizAIOracles.ts
5	Physical Delivery & Final Payout (70%): Sacks are delivered to the Tlaxiaco warehouse. Scanning the physical QR triggers the release of the remaining 70% ($7,000 MXN) directly to Don Juan's card or in cash via MicoPay.	src/core/blockchain/MultiAnchorSettlementRouter.ts docs/adr/ADR-001-TRUSTLESS-WORK-ESCROW.md

---

🏛️ Interactive Architecture Map (With Codebase Links)

Architecture Layer	Responsibilities	Key Files & Modules in Repo
Layer 1: Rural Client (PWA)	Voice-first accessible UI ("Modo Abuelo"), 112px touch targets, zero-seed authentication, offline caching.	src/App.tsx src/components/MainMenuScreen.tsx src/components/VoiceAssistantModal.tsx
Layer 2: Core Domain Engine	ACID outbox persistence, reactive sync listeners, canonical SHA-256 hashing, ISO/IEC 18004 vector QR generation.	src/core/crypto/CryptoEngine.ts src/core/sync/IndexedDbOutbox.ts src/core/policy/FairTradeEngine.ts
Layer 3: Autonomous AI Oracles	Multimodal acoustic parser (Tu'un Savi), SCAA quality vision scoring, EUDR satellite anti-deforestation proof.	src/core/ai/RaizAIOracles.ts src/components/ProtocolInfrastructureModal.tsx
Layer 4: Soroban Smart Contracts	Immutable lot registry, verifiable RWA attestation registry, and Trustless Work milestone escrow on Stellar.	contracts/lot_passport/ contracts/fair_escrow/ docs/standards/SEP_RWA_ATTESTATION_DRAFT.md
Layer 5: Fiat Settlement Rails	Atomic swap from on-chain USDC/MXNe to Banxico SPEI interbank transfers and rural cash-in-hand parcel network.	src/core/blockchain/MultiAnchorSettlementRouter.ts docs/adr/ADR-001-TRUSTLESS-WORK-ESCROW.md

---

💳 Unified 3-Tier Settlement Architecture

To resolve ambiguity between on-chain escrow, off-ramps, and cash distribution:

┌─────────────────────────────────────────────────────────────────────────────┐
│ TIER 1: ON-CHAIN ESCROW CUSTODY (Soroban Smart Contract)                    │
│ Buyer locks funds in USDC using the Trustless Work milestone standard:     │
│  • Milestone 1 (30%): Disbursed upon origin attestation verification.       │
│  • Milestone 2 (70%): Disbursed upon physical delivery confirmation.        │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TIER 2: LAST-MILE PARCEL CASH NETWORK (MicoPay Community Nodes)            │
│ For unbanked indigenous elders with zero bank accounts:                      │
│ Local cooperatives and certified transport drivers disburse physical cash   │
│ in parcel/depot upon verifying the hang-tag QR attestation.                 │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TIER 3: REGULATED FIAT BANKING RAILS (Etherfuse SPEI / MoneyGram Access)    │
│ For banked producers, cooperatives, and commercial entities:               │
│ Atomic conversion from USDC to local currency (MXNe via Etherfuse SPEI,     │
│ cash pickup via MoneyGram Stellar Access, or Banco del Bienestar debit).    │
└─────────────────────────────────────────────────────────────────────────────┘

---

🚀 Quickstart

Clone, install, and run Raíz locally:

# 1. Clone the repository
git clone https://github.com/Open-Hub-Tec/raiz.git
cd raiz

# 2. Install dependencies
npm install

# 3. Launch local development server
npm run dev

Open your browser at http://localhost:3000.

Verification & Quality Assurance:

# Run the complete test suite (79 automated tests, 0 failures)
npm run test

# Compile production bundle
npm run build

---

📚 Documentation Center

Technical architecture, field evidence, and academic standards are organized modularly in docs/:

• Architecture Document: 5-layer decoupled architecture, sequence diagrams, and cryptographic verification flow.
• ADR-001: Trustless Work Escrow: Milestone custody specification and rationale.
• ADR-002: Offline-First PWA & Rural Identity: W3C PWA standards vs. proprietary messaging platforms.
• SEP-XXXX Attestation Draft: Verifiable RWA Attestation Standard proposed for Soroban.
• Field Research Dossier: Complete field interviews, transcripts, audio recordings, and pain-point validations (Hito 1.1).
• UX Usability Testing: Timed field tests with indigenous elders and friction audit reports (Hito 1.2).

---

👥 Academic Governance & Team

• Institution: Instituto Tecnológico de Tlaxiaco (TecNM - Oaxaca, Mexico).
• Department: Ingeniería en Sistemas Computacionales.
• Faculty Advisor: Mtro. José Alfredo Román Cruz.
• Student Research Fellows: Open Hub TecNM Campus Tlaxiaco.
• License: MIT Open Source.