Djowda Interconnected Food Protocol — gRPC Transport Profile
Specification v0.4 · Skull Implementation

This repository contains the gRPC transport implementation of DIFP v0.4 — the Djowda Interconnected Food Protocol. It is an official working preview, not a production release. Every placeholder is clearly marked for incremental replacement.

DIFP-gRPC/
│
├── proto/
│   └── difp.proto                          ← Single source of truth for the entire protocol
│
├── server/
│   └── java/
│       └── examples/                       ← Gradle project root (build.gradle lives here)
│           ├── build.gradle
│           ├── gradlew.bat
│           └── src/main/
│               ├── java/io/grpc/examples/helloworld/
│               │   └── DifpNodeServer.java
│               └── proto/                  ← symlink → ../../../../proto/difp.proto
│
├── examples/
│   └── android/                            ← Android test client — open this in Android Studio
│       ├── build.gradle
│       ├── settings.gradle
│       └── app/src/main/
│           ├── java/com/djowda/difp/
│           │   └── MainActivity.java
│           └── res/layout/
│               └── activity_difp_test.xml
│
├── docs/
│   ├── architecture.md                     ← Skull roadmap & next iteration targets
│   └── proto-guide.md                      ← Wire format notes & message type reference
│
└── .github/
    └── workflows/build.yml                 ← CI: compile proto → build server → build android

The proto/ directory is the single source of truth. Both the server and the Android example symlink difp.proto from there — no copies, no drift.

Every DB interaction is a clearly named placeholder:

db_queryPresenceByCell()   // → replace with PostGIS / Firebase spatial query
db_createTrade()           // → replace with §9.1 atomic fan-out write
db_updateTradeStatus()     // → replace with §9.2 atomic fan-out write
db_registerComponent()     // → replace with auth provider + persistent store
db_upsertRegistryEntry()   // → replace with Redis SADD or registry DB

Navigate to the Gradle project root and build the distribution:

cd server\java\examples
.\gradlew.bat installDist

Then launch the node:

.\build\install\examples\bin\Difp-Node-Server
# INFO: Server started, listening on 50051
# INFO: [DB] Seeded 3 dummy presence records (Algiers cell 1,711,767,603)

Open the folder examples\android\ as a project in Android Studio.

Default connection settings (pre-filled in the UI):

Select a flow from the spinner and tap Run Flow:

The Android emulator runs in an isolated network. You must forward the gRPC port from the emulator back to your machine after the emulator boots.

Open a terminal inside Android Studio and run:

adb reverse tcp:50051 tcp:50051

If you have multiple devices or see a port conflict, find the emulator's ADB port first (shown in the emulator window title, e.g. 5554) and use the specific serial:

# Find connected devices
adb devices

# Forward for a specific emulator serial
adb -s emulator-5554 reverse tcp:50051 tcp:50051

If the connection still fails after the first launch, try running the command again — the emulator sometimes resets port rules between boots. Run the app again after re-forwarding.

• JDK 17+
• Gradle 8+ (or use the included gradlew.bat wrapper — no install needed)
• Android Studio Hedgehog+ (for the Android example)
• protoc is not required locally — the Gradle protobuf plugin downloads it automatically

cd server\java\examples

.\gradlew.bat installDist          # compile proto + build distribution
.\gradlew.bat test                 # run reference vector tests

# Run the built distribution
.\build\install\examples\bin\Difp-Node-Server

Open examples\android\ in Android Studio and run via the IDE, or build from the command line:

cd examples\android
.\gradlew.bat assembleDebug
# APK: app\build\outputs\apk\debug\app-debug.apk

When difp.proto changes:

# 1. Edit the canonical file
notepad proto\difp.proto   # or your editor of choice

# 2. Rebuild both projects — symlinks mean no manual copy needed
cd server\java\examples  ; .\gradlew.bat generateProto ; cd ..\..\..
cd examples\android      ; .\gradlew.bat generateProto ; cd ..\..

# 3. Commit everything together
git add proto\difp.proto server\ examples\android\
git commit -m "proto: <describe the change>"

1. Stream broadcasting — push trade.ask to all connected clients in the same cell
2. Ed25519 signing — §15.3 canonical hashing + signature verification
3. Real DB — replace placeholder functions with your storage backend
4. Federation — registry.announce to external registry nodes on startup (§25.4)
5. PAD endpoints — /.well-known/difp/pad/latest for catalog distribution (§22.5)
6. TradeEngine — accept/reject/complete flows with atomic §9 fan-out writes

See docs/architecture.md for the full skull-to-production roadmap.

DIFP is an open protocol (CC-BY 4.0). Contributions to the gRPC transport profile are welcome:

• Bug reports and spec clarifications → open an Issue
• Client implementations in other languages → open a PR adding examples/{language}/
• Protocol questions → spec@djowda.com

CC-BY 4.0 — free to implement, fork, and commercialize with attribution.
See LICENSE · djowda.com/difp