Build Geo Location POC phase 1 tracker

[nikw9944]

Read rfcs/rfc16-geolocation-verification.md. Then look at the POC Requirements section of the doc, and use it to create an implementation plan. The plan should break down the work into manageable pieces and propose issues to create for each piece. The issue should include a reference to rfcs/rfc16-geolocation-verification.md. and so the the issues created do not need to include details that are already in the RFC, but should include clear goals and scope. The plan should also specify the order in which each piece should be built, and whether any pieces can be built in parallel without introducing merging headaches later.

[nikw9944]

Work Plan (Revision 1 — Phase 1 Only)

Geo-Location Verification: Phase 1 Implementation Plan

Summary

This plan covers Phase 1 only of the Geo-Location Verification RFC. Phase 1 is entirely CLI-arg driven — no onchain accounts or instructions are needed. Components use --additional-child-probes, --additional-parents, and --additional-targets flags to configure the measurement chain without ledger state.

Phase 2 (onchain configuration, CLI tool, Go SDK extensions) is out of scope for this plan.

Changes from Revision 0

• Removed all onchain work — Phase 1 uses CLI args, not ledger-based discovery
• Removed CLI tool and Go SDK issues — these are Phase 2
• geoProbe server is Go, located at controlplane/telemetry/cmd/geoprobe-agent/ and reusing shared modules from controlplane/telemetry/internal/geoprobe/ (RFC file paths and module reuse confirm Go)
• Added shared geoprobe library as a separate foundational issue
• Wire format details deferred to implementation time per discussion

Proposed Issues

#2898: Shared geoprobe library — LocationOffset types, signing, and UDP transport

RFC Reference: rfc16-geolocation-verification.md — LocationOffset struct, Offset signing

Goal: Create the shared Go package that all three Phase 1 binaries depend on: LocationOffset type definitions, Ed25519 offset signing/verification, and UDP offset transport.

Scope:

• New package controlplane/telemetry/internal/geoprobe/
• offset.go: LocationOffset struct (matching RFC definition — signature, pubkey, measurement slot, lat/lng, RTT fields, references chain), serialization/deserialization
• signer.go: Ed25519 offset signing (wrapping existing solana.PrivateKey patterns from internal/state/signer.go), signature verification
• transport.go: UDP send/receive helpers for LocationOffset datagrams
• Unit tests for signing round-trip, serialization round-trip, verification of invalid signatures

Files to create:

• controlplane/telemetry/internal/geoprobe/offset.go
• controlplane/telemetry/internal/geoprobe/signer.go
• controlplane/telemetry/internal/geoprobe/transport.go
• controlplane/telemetry/internal/geoprobe/offset_test.go
• controlplane/telemetry/internal/geoprobe/signer_test.go

Estimated scope: Small–Medium (~200–300 lines)

Parallelism: This is the foundation. Must complete before Issues #2899–#2901 can begin. No merge conflicts — entirely new directory.

---

#2899: Telemetry agent extensions — probe measurement and offset delivery

RFC Reference: rfc16-geolocation-verification.md — Phase 1, item 1 (Telemetry agent extensions)

Goal: Extend the existing telemetry agent to measure RTT to child geoProbes via TWAMP, generate signed Offset structures, and deliver them via UDP.

Scope:

• New CLI flag --additional-child-probes (comma-separated host:port list) on the telemetry agent binary (controlplane/telemetry/cmd/telemetry/main.go)
• New module controlplane/telemetry/internal/geoprobe/pinger.go: periodic TWAMP measurement to configured probes, reusing existing twamplight.Sender interface from tools/twamp/pkg/light/
• New module controlplane/telemetry/internal/geoprobe/publisher.go: generates signed Offset (using DZD's metrics_publisher_pk keypair, lat/lng from device config) and sends via UDP to each probe
• Integration into collector.go: add a new goroutine alongside the existing pinger/submitter goroutines, gated on --additional-child-probes being non-empty
• Unit tests for the probe pinger and publisher modules

Integration points:

• collector.go (lines ~83-168): Add goroutine for geoprobe measurement loop, similar to existing pinger goroutine pattern
• cmd/telemetry/main.go: Add CLI flags, pass config to collector
• Reuses twamplight.NewSender for TWAMP probing (same interface as existing device probing)
• Reuses existing solana.PrivateKey (loaded from --keypair) for offset signing

Dependencies: Requires #2898 (shared geoprobe library).

Files to change:

• controlplane/telemetry/cmd/telemetry/main.go — new flags, wire up geoprobe config
• controlplane/telemetry/internal/telemetry/collector.go — new goroutine for probe measurement
• controlplane/telemetry/internal/telemetry/config.go — new config fields

Files to create:

• controlplane/telemetry/internal/geoprobe/pinger.go
• controlplane/telemetry/internal/geoprobe/publisher.go
• controlplane/telemetry/internal/geoprobe/pinger_test.go
• controlplane/telemetry/internal/geoprobe/publisher_test.go

Estimated scope: Medium (~300–500 lines)

Parallelism: Can proceed in parallel with Issues #2900 and #2901 once #2898 is complete. Touches different files than #2900 (this modifies the existing telemetry agent; #2900 creates a new binary).

---

#2900: geoProbe server (doublezero-geoprobe-agent)

RFC Reference: rfc16-geolocation-verification.md — Phase 1, item 2 (geoProbe server)

Goal: Build a new Go service that acts as the intermediary Probe: reflects TWAMP from DZDs, receives DZD Offsets, measures RTT to targets, generates composite Offsets with DZD references, and delivers them to targets.

Scope:

• New binary at controlplane/telemetry/cmd/geoprobe-agent/main.go
• CLI flags: --additional-parents (DZD pubkeys + addresses), --additional-targets (target IPs), -verbose
• TWAMP Reflector: reuse twamplight.Reflector from tools/twamp/pkg/light/ to respond to DZD probes
• UDP Listener (port 8923): receive signed LocationOffset datagrams from DZDs
• Signature Verifier: validate Ed25519 signatures on incoming DZD Offsets using the shared geoprobe library
• Offset Cache: store recent DZD Offsets keyed by DZD pubkey in memory, with configurable TTL (max_offset_age_seconds) and max size
• Target Measurement: measure RTT to targets via TWAMP (for Phase 1 POC per RFC)
• Composite Offset Generation: create new LocationOffset with DZD Offset(s) as references, sign with probe's keypair
• UDP Sender: post composite Offset to targets on port 8923
• Key management:* should follow the pattern established in controlplane/telemetry

Components (internal to the binary or in shared modules):

• main.go — flag parsing, component wiring, goroutine management (following patterns from existing cmd/telemetry/main.go)
• Offset cache — in-memory map with TTL eviction
• TWAMP pinger for targets — reuse TWAMP implementation in controlplane/telemtry
• Composite offset builder — attaches DZD offset references and computes total RttNs
  • RttNs is the sum of the reference plus measured
  • lat/lng is copied from the reference (in this POC phase there will only be 1 reference)

Dependencies: Requires #2898 (shared geoprobe library). Independent of #2899.

Files to create:

• controlplane/telemetry/cmd/geoprobe-agent/main.go

Estimated scope: Large (~500+ lines)

Parallelism: Can proceed in parallel with Issues #2899 and #2901 once #2898 is complete. Entirely new directory — no merge conflicts with #2899.

---

#2901: Example target listener (TWAMP reflector + UDP offset receiver)

RFC Reference: rfc16-geolocation-verification.md — Phase 1, item 3 (Example Target Software)

Goal: Build a lightweight Go test tool that responds to probe TWAMP/ICMP measurements, receives composite Offsets from probes, verifies the full signature chain, and logs the geolocation results.

Scope:

• New binary at controlplane/telemetry/cmd/geoprobe-target/
• TWAMP Reflector: reuse twamplight.Reflector to respond to probe measurements
• UDP Listener (port 8923): reuse UDP Listener from geoprobe-agent
• Signature Verification: reuse signature verification from geoprobe-agent, and also then validate referenced DZD→Probe offset signatures (full chain verification)
• Logging: output offset contents in JSON or text format, including: probe identity, reference point lat/lng, RTT to target, max distance interpretation, DZD reference chain details, signature validity (matching RFC example output)
• CLI flags for custom ports, log format

Dependencies: Requires #2898 (shared geoprobe library for offset deserialization and verification). Independent of Issues #2899 and #2900.

Files to create:

• controlplane/telemetry/cmd/geoprobe-target/main.go

Estimated scope: Small–Medium (~200–400 lines)

Parallelism: Can proceed in parallel with Issues #2899 and #2900 once #2898 is complete. Entirely separate directory — no merge conflicts.

---

#2902: E2E test in Dockernet

RFC Reference: rfc16-geolocation-verification.md — Phase 1, item 4 (Deployment)

Goal: Validate the full DZD → Probe → Target chain end-to-end in Dockernet

Scope:

Dockernet E2E test:

• New test file following existing patterns in e2e/device_telemetry_test.go (uses testcontainers-go, devnet.New(), require.Eventually())
• Spin up: 1 DZD device + 1 geoProbe server + 1 target listener in Docker
• Configure via CLI flags (no onchain setup needed):
  • Telemetry agent: --additional-child-probes=<probe-addr>
  • geoProbe: --additional-parents=<dzd-pubkey>:<dzd-addr>, --additional-targets=<target-ip>
• Verify: DZD sends TWAMP + Offset to probe → probe caches offset, measures target, sends composite offset → target receives and verifies signature chain
• Assert: target logs show valid signature chain and plausible RTT values
• Add Dockerfile for geoprobe-agent and geprobe-target (or build inline as existing tests do)

Dependencies: Requires #2899, #2900, and #2901 to be complete.

Files to change/create:

• e2e/geolocation_test.go — new E2E test file
• e2e/internal/devnet/ — extend DeviceSpec or add ProbeSpec for geoProbe container support
• Dockerfiles for new binaries (if needed beyond existing Go build patterns)

Estimated scope: Medium–Large (~400–600 lines)

Parallelism: Must wait for Issues #2899–#2901. Can begin incrementally as components land.

#2903: testnet deployment

RFC Reference: rfc16-geolocation-verification.md — Phase 1, item 4 (Deployment)

Goal: Deploy snapshot builds to testnet.

Scope:

Testnet deployment (documentation):

• Manual deployment steps for:
  • Snapshot telemetry agent on fra-dz001 with --additional-child-probes pointing to probe
  • Snapshot geoProbe agent on fra-tn-bm1 with --additional-parents and --additional-targets
  • Snapshot target listener on fra-tn-qa01
• Keypair generation steps for probe

Dependencies: Requires #2899, #2900, and #2901 to be complete.

Estimated scope: Small (no code changes needed)

Parallelism: Must wait for Issues #2899–#2901. Can begin incrementally as components land.

---

Build Order and Parallelism

Phase A (Foundation):
  #2898: Shared geoprobe library

Phase B (Parallel — Core Components):
  #2899: Telemetry agent extensions ──┐
  #2900: geoProbe server ─────────────┼── All proceed in parallel
  #2901: Target listener ─────────────┘   (separate directories)

Phase C (Integration):
  #2902: E2E test
  #2903: testnet deployment

Critical path: #2898 → #2900 (largest component) → #2902

Why Phase B is safe to parallelize:

• geoprobe: telemetry agent extensions — probe measurement and offset delivery #2899 modifies controlplane/telemetry/cmd/telemetry/ and internal/telemetry/ (existing agent)
• geoprobe: geoProbe server (doublezero-geoprobe-agent) #2900 creates controlplane/telemetry/cmd/geoprobe-agent/ (new directory)
• geoprobe: example target listener (TWAMP reflector + UDP offset receiver) #2901 creates controlplane/geolocation-target-listener/ (new directory)
• All three import from controlplane/telemetry/internal/geoprobe/ (created in geoprobe: shared library — LocationOffset types, signing, and UDP transport #2898, read-only in Phase B)
• No overlapping file changes between Issues geoprobe: telemetry agent extensions — probe measurement and offset delivery #2899, geoprobe: geoProbe server (doublezero-geoprobe-agent) #2900, and geoprobe: example target listener (TWAMP reflector + UDP offset receiver) #2901