Build Geo Location POC phase 2 tracker

[nikw9944]

We are implementing rfcs/rfc16-geolocation-verification.md in 2 phases (see the POC Requirements section of the doc). We already completed phase 1 using the plan in #2893. In this issue, let's create an implementation plan for phase 2.

The plan should break down the work into manageable pieces and propose issues to create for each piece. Each issue should include a reference to rfcs/rfc16-geolocation-verification.md, 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 0)

Geo-Location Verification: Phase 2 Implementation Plan

Summary

Phase 2 of RFC 16 — Geo-Location Verification transitions the geolocation system from CLI-arg-driven configuration (Phase 1) to onchain configuration. This involves: (1) adding Probe and GeolocationUser account types to the Serviceability program with instructions for managing them, (2) extending the telemetry agent and geoProbe server to discover their configuration from onchain state instead of CLI flags, (3) building a doublezero-geolocation CLI tool for managing probes, users, and targets, and (4) updating E2E tests to exercise the onchain configuration path. The Go SDK must also be extended to support the new account types and instructions.

Approach

Phase 2 follows the same layered pattern used by existing entities (Device, Exchange, User, etc.):

1. Onchain first: Add Rust state types, PDAs, instructions, and processors to the Serviceability program. This establishes the data model.
2. Go SDK second: Add Go types, PDA derivation, instruction builders, and client methods to the Go serviceability SDK. This enables all Go components to interact with the new onchain state.
3. CLI tool: Build a doublezero-geolocation CLI tool (or extend the existing doublezero CLI) for probe and user management.
4. Onchain discovery: Modify the telemetry agent and geoProbe server to query onchain state for probe/target configuration, falling back to CLI args for backwards compatibility.
5. E2E tests: Update Dockernet tests to create onchain probe/user accounts and verify the full flow.

Key Design Decisions

• Probe accounts live in Serviceability (not Telemetry), following the RFC and consistent with how Device/Exchange/Location are managed.
• GeolocationUser accounts also live in Serviceability, following the RFC pattern for user/target IP management.
• PDA seeds follow RFC: Probe uses ["doublezero", "probe", index.to_le_bytes()], GeolocationUser uses ["doublezero", "geolocation_user", code.as_bytes()].
• AccountType enum extension: Add Probe = 14 and GeolocationUser = 15 to the Serviceability AccountType enum.
• Backwards compatibility: CLI-arg-based configuration (--additional-child-probes, --additional-parents, --additional-targets) continues to work alongside onchain discovery. Onchain probes and CLI-arg probes are merged at runtime.

Proposed Issues

Issue A: Serviceability program — Probe account type and instructions

RFC Reference: rfc16-geolocation-verification.md — Probe Account, Smart Contract Changes

Goal: Add the Probe account type and 4 new instructions (InitializeProbe, UpdateProbe, AddParentDevice, RemoveParentDevice) to the Serviceability program.

Scope:

• Add Probe = 14 to AccountType enum in state/accounttype.rs
• Add SEED_PROBE constant to seeds.rs
• Create state/probe.rs with Probe struct (fields from RFC: owner, index, bump_seed, exchange_pk, public_ip, status, code, parent_devices, metrics_publisher_pk, reference_count)
• Create ProbeStatus enum (Pending/Activated/Suspended/Deleting)
• Add PDA derivation function get_probe_pda() to pda.rs
• Create processor files:
  • processors/probe/create.rs — InitializeProbe instruction
  • processors/probe/update.rs — UpdateProbe instruction
  • processors/probe/add_parent.rs — AddParentDevice instruction
  • processors/probe/remove_parent.rs — RemoveParentDevice instruction
• Add 4 new instruction variants to instructions.rs (next available indices after 93)
• Wire processors into processor.rs
• Unit tests for instruction pack/unpack, PDA derivation, processor logic

Files to change:

• smartcontract/programs/doublezero-serviceability/src/state/accounttype.rs
• smartcontract/programs/doublezero-serviceability/src/state/mod.rs
• smartcontract/programs/doublezero-serviceability/src/seeds.rs
• smartcontract/programs/doublezero-serviceability/src/pda.rs
• smartcontract/programs/doublezero-serviceability/src/instructions.rs
• smartcontract/programs/doublezero-serviceability/src/processor.rs

Files to create:

• smartcontract/programs/doublezero-serviceability/src/state/probe.rs
• smartcontract/programs/doublezero-serviceability/src/processors/probe/mod.rs
• smartcontract/programs/doublezero-serviceability/src/processors/probe/create.rs
• smartcontract/programs/doublezero-serviceability/src/processors/probe/update.rs
• smartcontract/programs/doublezero-serviceability/src/processors/probe/add_parent.rs
• smartcontract/programs/doublezero-serviceability/src/processors/probe/remove_parent.rs

Estimated scope: Large (~500–800 lines)

---

Issue B: Serviceability program — GeolocationUser account type and instructions

RFC Reference: rfc16-geolocation-verification.md — GeolocationUser Account

Goal: Add the GeolocationUser account type and 4 new instructions (InitializeGeolocationUser, AddTargetIp, RemoveTargetIp, DeleteGeolocationUser) to the Serviceability program.

Scope:

• Add GeolocationUser = 15 to AccountType enum
• Add SEED_GEOLOCATION_USER constant to seeds.rs
• Create state/geolocation_user.rs with GeolocationUser struct (fields from RFC: owner, index, bump_seed, code, exchange_pk, target_ips, status, reference_count)
• Create GeolocationUserStatus enum (Pending/Activated/Deleting)
• Add PDA derivation function get_geolocation_user_pda() to pda.rs using seeds ["doublezero", "geolocation_user", code.as_bytes()]
• Create processor files:
  • processors/geolocation_user/create.rs — InitializeGeolocationUser
  • processors/geolocation_user/add_target.rs — AddTargetIp
  • processors/geolocation_user/remove_target.rs — RemoveTargetIp
  • processors/geolocation_user/delete.rs — DeleteGeolocationUser
• Add 4 new instruction variants to instructions.rs
• Unit tests

Files to change:

• smartcontract/programs/doublezero-serviceability/src/state/accounttype.rs
• smartcontract/programs/doublezero-serviceability/src/state/mod.rs
• smartcontract/programs/doublezero-serviceability/src/seeds.rs
• smartcontract/programs/doublezero-serviceability/src/pda.rs
• smartcontract/programs/doublezero-serviceability/src/instructions.rs
• smartcontract/programs/doublezero-serviceability/src/processor.rs

Files to create:

• smartcontract/programs/doublezero-serviceability/src/state/geolocation_user.rs
• smartcontract/programs/doublezero-serviceability/src/processors/geolocation_user/mod.rs
• smartcontract/programs/doublezero-serviceability/src/processors/geolocation_user/create.rs
• smartcontract/programs/doublezero-serviceability/src/processors/geolocation_user/add_target.rs
• smartcontract/programs/doublezero-serviceability/src/processors/geolocation_user/remove_target.rs
• smartcontract/programs/doublezero-serviceability/src/processors/geolocation_user/delete.rs

Estimated scope: Large (~500–800 lines)

---

Issue C: Go SDK — Probe and GeolocationUser types and client methods

RFC Reference: rfc16-geolocation-verification.md

Goal: Extend the Go Serviceability SDK with types, deserialization, PDA derivation, instruction builders, and client methods for the new Probe and GeolocationUser accounts.

Scope:

• Add Probe and GeolocationUser Go structs to state.go (matching Rust serialization layout)
• Add ProbeStatus and GeolocationUserStatus Go types
• Add PDA derivation functions (GetProbePDA, GetGeolocationUserPDA) to pda.go
• Add deserialization for new account types in deserialize.go
• Extend ProgramData struct with Probes []Probe and GeolocationUsers []GeolocationUser fields
• Add instruction builder functions for all 8 new instructions
• Add client methods: GetProbes(), GetGeolocationUsers(), etc.
• Unit tests for PDA derivation (must match Rust), serialization round-trip

Files to change:

• smartcontract/sdk/go/serviceability/state.go
• smartcontract/sdk/go/serviceability/pda.go
• smartcontract/sdk/go/serviceability/client.go
• smartcontract/sdk/go/serviceability/deserialize.go

Files to create:

• smartcontract/sdk/go/serviceability/initialize_probe.go
• smartcontract/sdk/go/serviceability/update_probe.go
• smartcontract/sdk/go/serviceability/add_parent_device.go
• smartcontract/sdk/go/serviceability/remove_parent_device.go
• smartcontract/sdk/go/serviceability/initialize_geolocation_user.go
• smartcontract/sdk/go/serviceability/add_target_ip.go
• smartcontract/sdk/go/serviceability/remove_target_ip.go
• smartcontract/sdk/go/serviceability/delete_geolocation_user.go

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

---

Issue D: CLI tool — Probe management commands

RFC Reference: rfc16-geolocation-verification.md — Phase 2, item 4

Goal: Add probe management CLI commands (doublezero probe list/create/update) to the existing Rust CLI tool, plus parent device management (add-parent/remove-parent).

Scope:

• New CLI module smartcontract/cli/src/probe/ following the Device module pattern
• Commands:
  • doublezero probe create — creates a Probe account (args: code, exchange, public-ip, port, metrics-publisher-pk)
  • doublezero probe update — updates Probe fields (public-ip, port, status)
  • doublezero probe list — lists all Probe accounts
  • doublezero probe get — gets a specific Probe by code or pubkey
  • doublezero probe add-parent — adds a parent DZD to a Probe
  • doublezero probe remove-parent — removes a parent DZD from a Probe
• Rust SDK instruction builders for all probe instructions (in smartcontract/sdk/rs/)
• Follow existing CLI patterns: clap derive macros, CliCommand trait, validators

Files to create:

• smartcontract/cli/src/probe/mod.rs
• smartcontract/cli/src/probe/create.rs
• smartcontract/cli/src/probe/update.rs
• smartcontract/cli/src/probe/list.rs
• smartcontract/cli/src/probe/get.rs
• smartcontract/cli/src/probe/add_parent.rs
• smartcontract/cli/src/probe/remove_parent.rs

Files to change:

• smartcontract/cli/src/lib.rs — add pub mod probe;
• Main CLI binary — add probe subcommand

Estimated scope: Medium (~300–500 lines)

---

Issue E: CLI tool — GeolocationUser and target IP management commands

RFC Reference: rfc16-geolocation-verification.md — Phase 2, item 4

Goal: Add geolocation user management CLI commands for managing users and their target IPs.

Scope:

• New CLI module smartcontract/cli/src/geolocation/ or integrate into existing user module
• Commands:
  • doublezero geolocation user create — creates a GeolocationUser account (args: code, exchange)
  • doublezero geolocation user list — lists all GeolocationUser accounts
  • doublezero geolocation user delete — deletes a GeolocationUser account
  • doublezero geolocation add-target — adds a target IP to a GeolocationUser
  • doublezero geolocation remove-target — removes a target IP from a GeolocationUser
• Also needs to expose probe/exchange/device/location list commands for context (per RFC: "Only needs to see exchanges, locations, devices, and probes")
• Payer account setup (follow existing CLI patterns with --keypair / identity.json)

Files to create:

• smartcontract/cli/src/geolocation/mod.rs
• smartcontract/cli/src/geolocation/user/create.rs
• smartcontract/cli/src/geolocation/user/list.rs
• smartcontract/cli/src/geolocation/user/delete.rs
• smartcontract/cli/src/geolocation/add_target.rs
• smartcontract/cli/src/geolocation/remove_target.rs

Files to change:

• smartcontract/cli/src/lib.rs — add pub mod geolocation;
• Main CLI binary — add geolocation subcommand

Estimated scope: Medium (~300–500 lines)

---

Issue F: Telemetry agent — onchain child geoProbe discovery

RFC Reference: rfc16-geolocation-verification.md — Phase 2, item 2

Goal: Extend the telemetry agent to discover its child geoProbes from onchain Probe accounts, replacing/supplementing the --additional-child-probes CLI flag.

Scope:

• New module controlplane/telemetry/internal/geoprobe/discovery.go (as specified in the RFC)
• Periodically query the Serviceability program for Probe accounts where parent_devices contains the local device's pubkey (60s interval per RFC)
• Convert discovered Probe accounts to ProbeAddress structs and send them to the Coordinator via ProbeUpdateCh
• Merge onchain-discovered probes with any --additional-child-probes CLI args
• The Coordinator already supports dynamic probe updates via the ProbeUpdateCh channel — this issue wires in the onchain discovery source
• Use the Go Serviceability SDK client from Issue C to query probes

Files to create:

• controlplane/telemetry/internal/geoprobe/discovery.go
• controlplane/telemetry/internal/geoprobe/discovery_test.go

Files to change:

• controlplane/telemetry/internal/telemetry/collector.go — start discovery goroutine alongside coordinator
• controlplane/telemetry/internal/telemetry/config.go — add ProbeDiscoveryInterval config field

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

---

Issue G: geoProbe server — onchain parent DZD and target discovery

RFC Reference: rfc16-geolocation-verification.md — Phase 2, item 3

Goal: Extend the geoProbe server (doublezero-geoprobe-agent) to discover its parent DZDs and target IPs from onchain data, replacing/supplementing the --additional-parents and --additional-targets CLI flags.

Scope:

• Parent DZD Discovery: Query the Serviceability program for the Probe account matching this server's pubkey, extract parent_devices list, resolve Device accounts to get their IP addresses and metrics_publisher_pk for signature verification
• Target Discovery: Query onchain GeolocationUser accounts whose exchange_pk matches this probe's exchange, extract target_ips from all matching users (30s interval per RFC)
• Merge onchain-discovered parents/targets with CLI-arg-based configuration
• Update the trusted parent pubkey whitelist dynamically as parent devices change
• Update the target list dynamically as GeolocationUser accounts are created/modified

Files to change:

• controlplane/telemetry/cmd/geoprobe-agent/main.go — add discovery goroutines, wire into existing cache/measurement components

Files to create:

• Discovery logic may reuse discovery.go from Issue F or create a separate module

Estimated scope: Medium (~300–400 lines)

---

Issue H: E2E tests — onchain configuration flow

RFC Reference: rfc16-geolocation-verification.md — Phase 2, item 6

Goal: Update/create E2E tests in Dockernet to verify the full geolocation flow using onchain configuration instead of CLI flags.

Scope:

• Extend existing geolocation E2E test (or create new test file) to:
  1. Create a Probe account onchain via the CLI/SDK
  2. Create a GeolocationUser account onchain with target IPs
  3. Add parent devices to the Probe account
  4. Start telemetry agent, geoProbe server, and target listener without CLI-arg configuration
  5. Verify: agents discover configuration from onchain state
  6. Verify: full DZD → Probe → Target measurement chain works
  7. Verify: adding/removing target IPs onchain is reflected in probe behavior
• Use the doublezero CLI (via manager container) for onchain setup, following patterns in sdk_device_telemetry_test.go
• Test in DevNet as well (lighter environment)

Files to change/create:

• e2e/geolocation_test.go — update/extend existing E2E test
• e2e/internal/devnet/ — extend for Probe/GeolocationUser account setup if needed

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

---

Build Order and Parallelism

Phase A (Foundation — Onchain):
  Issue A: Serviceability — Probe account  ──────┐
  Issue B: Serviceability — GeolocationUser  ────┼── Can build in parallel
                                                  │   (separate state/processor files,
                                                  │   but both touch accounttype.rs,
                                                  │   seeds.rs, instructions.rs, pda.rs.
                                                  │   Coordinate merges for shared files.)
                                                  │
Phase B (SDK — depends on A+B):                   │
  Issue C: Go SDK extensions  ───────────────────←┘

Phase C (CLI + Discovery — depends on C):
  Issue D: CLI — Probe commands  ────────────────┐
  Issue E: CLI — GeolocationUser commands  ──────┼── Can build in parallel
  Issue F: Telemetry agent — onchain discovery  ─┤   (D+E are separate CLI modules,
  Issue G: geoProbe server — onchain discovery  ─┘    F+G are separate Go packages)

Phase D (Integration — depends on all above):
  Issue H: E2E tests

Critical Path

Issue A → Issue C → Issue F + Issue G → Issue H

Parallelism Notes

• Issues A and B can be built in parallel since they add separate account types (Probe vs GeolocationUser) with separate state and processor files. However, both modify accounttype.rs, seeds.rs, instructions.rs, and pda.rs — the second to merge will need to resolve conflicts in these shared files. This is manageable because the changes are additive (new enum variants, new seed constants, new PDA functions, new instruction variants).
• Issues D, E, F, and G can all proceed in parallel once Issue C is complete:
  • D and E are separate CLI modules (probe/ and geolocation/) in the Rust CLI
  • F modifies the Go telemetry agent's collector
  • G modifies the Go geoprobe-agent binary
  • No overlapping file changes between these four issues
• Issue H must wait for all other issues since it exercises the full onchain-configured flow.

Risks & Considerations

1. Account size limits: The Probe.parent_devices and GeolocationUser.target_ips fields are Vecs that grow the account size. Need to set reasonable maximum sizes and handle reallocation if accounts grow beyond their initial allocation. Follow the pattern used by existing accounts with variable-length fields.

2. Serviceability program upgrade: Adding new account types and instructions requires a program upgrade on testnet/devnet. This must be coordinated with any other pending Serviceability changes to avoid upgrade conflicts.

3. Backwards compatibility: The --additional-child-probes, --additional-parents, and --additional-targets CLI flags must continue to work. Onchain discovery should supplement, not replace, these flags during the transition period.

4. Discovery polling frequency: The RFC specifies 60s for probe discovery and 30s for target discovery. These intervals need to be tested for responsiveness vs. RPC load. The Go SDK's GetProgramData() fetches all accounts — for production, a more targeted query pattern may be needed.

5. PDA seed consistency: The Rust and Go PDA derivations must produce identical addresses. Cross-language PDA tests are critical.

6. Merge coordination for shared files: Issues A and B both modify accounttype.rs, instructions.rs, seeds.rs, and pda.rs. If built in parallel, whichever merges second must rebase. The changes are strictly additive so conflicts should be straightforward to resolve.

Testing Strategy

• Unit tests (Issues A, B, C): Instruction pack/unpack, PDA derivation (Rust + Go cross-validation), processor logic, state serialization round-trips
• Integration tests (Issues D, E): CLI command execution against a local validator
• E2E tests (Issue H): Full Dockernet test with onchain-configured measurement chain
• Manual testing: Deploy to DevNet and verify onchain configuration works end-to-end

Estimated Scope

Overall: Large (1,500–3,500+ lines across all issues)

Issue	Scope	Lines (est.)
A: Probe onchain	Large	500–800
B: GeolocationUser onchain	Large	500–800
C: Go SDK	Medium–Large	400–600
D: CLI — Probe	Medium	300–500
E: CLI — GeolocationUser	Medium	300–500
F: Telemetry agent discovery	Small–Medium	200–300
G: geoProbe server discovery	Medium	300–400
H: E2E tests	Medium–Large	400–600

Documentation Updates

• RFC 16 itself does not need changes (the plan already describes Phase 2)
• CLAUDE.md may need updates if new make targets or test commands are added
• DEVELOPMENT.md may need updates for new CLI commands or E2E test instructions
• No CHANGELOG.md or README.md changes needed at this planning stage (those would be per-issue)

[ben-dz]

Geolocation Phase 2 — Implementation Plan

RFC: rfc16-geolocation-verification.md
Updated Smart Contract Design: PR #2950

Key Design Decision: New Geolocation Program

Per PR #2950, Phase 2 introduces a new doublezero-geolocation onchain program (separate from Serviceability and Telemetry). It manages GeoProbe infrastructure and GeolocationUser accounts, referencing the Serviceability Program's GlobalState via CPI for foundation allowlist checks. This replaces the original plan to add account types to Serviceability.

Proposed Issues (8 total)

Issue A: Geolocation Program — Account types, instructions, and processors

Goal: Create a new doublezero-geolocation onchain program with 3 account types and 15 instructions per PR #2950.

Account types: ProgramConfig, GeoProbe, GeolocationUser

Instructions (15 variants):

• Program: InitProgramConfig (0)
• GeoProbe (foundation-gated): CreateGeoProbe (1), UpdateGeoProbe (2), DeleteGeoProbe (6), AddParentDevice (7), RemoveParentDevice (8)
• GeolocationUser (self-service): CreateGeolocationUser (9), UpdateGeolocationUser (10), DeleteGeolocationUser (11), AddTarget (12), RemoveTarget (13)
• Billing (foundation-gated): UpdatePaymentStatus (14)

Scope: Large (~800–1200 lines). New Cargo crate under smartcontract/programs/doublezero-geolocation/.

---

Issue B: Go SDK — Geolocation program types and client methods

Goal: New Go SDK package smartcontract/sdk/go/geolocation/ with types, PDA derivation, instruction builders, and client methods for all 15 instructions. Follows patterns from the existing telemetry and serviceability SDKs.

Scope: Medium–Large (~500–700 lines)

---

Issue C: Rust SDK — Geolocation instruction builders

Goal: Rust SDK instruction builders for the Geolocation program to support CLI commands and integration tests.

Scope: Small–Medium (~200–300 lines)

---

Issue D: CLI tool — GeoProbe management commands

Goal: Add doublezero probe create/update/delete/list/get/add-parent/remove-parent commands to the existing CLI. Foundation-gated operations.

Scope: Medium (~300–500 lines)

---

Issue E: CLI tool — GeolocationUser and target management commands

Goal: Add doublezero geolocation user create/update/delete/list and doublezero geolocation add-target/remove-target/update-payment commands. Mix of self-service and foundation-gated operations.

Scope: Medium (~300–500 lines)

---

Issue F: Telemetry agent — onchain child geoProbe discovery

Goal: Extend the telemetry agent to discover child geoProbes from onchain GeoProbe accounts (60s polling), supplementing the --additional-child-probes CLI flag.

Scope: Small–Medium (~200–300 lines)

---

Issue G: geoProbe server — onchain parent DZD and target discovery

Goal: Extend doublezero-geoprobe-agent to discover parent DZDs from onchain GeoProbe.parent_devices and targets from GeolocationUser.targets (30s polling). Only measures targets from users with payment_status: Paid.

Scope: Medium (~300–400 lines)

---

Issue H: E2E tests — onchain geolocation configuration flow

Goal: E2E test in Dockernet verifying the full flow: deploy program → create probe → add parents → create user → add targets → verify agents discover config from onchain → verify measurement chain works.

Scope: Medium–Large (~400–600 lines)

---

Build Order

Phase 1: Issue A (Geolocation Program)
    │
Phase 2: Issue B (Go SDK) ── can build in parallel ── Issue C (Rust SDK)
    │                                                       │
Phase 3: Issue F (telemetry discovery) ─┐    Issue D (CLI probe) ─┐
         Issue G (geoprobe discovery)  ─┤    Issue E (CLI user)   ─┤
                                        │                          │
         (F,G depend on B)              │    (D,E depend on C)     │
         All 4 can run in parallel ─────┴──────────────────────────┘
    │
Phase 4: Issue H (E2E tests) — depends on all above

Critical path: A → B → F + G → H

Risks & Considerations

1. New program deployment — requires generating a program ID and deploying to devnet/testnet
2. Serviceability CPI — foundation allowlist checks cross program boundaries; needs careful testing
3. Backwards compatibility — Phase 1 CLI flags must continue working alongside onchain discovery
4. Billing — UpdatePaymentStatus is foundation-gated; the billing sentinel/oracle is future work
5. MVP constraint — each exchange has 0 or 1 probe (per PR rfc16: define geolocation program smart contract changes #2950)
6. Cross-language PDA consistency — Rust and Go PDA derivations must match

Total Estimated Scope

~3,000–4,500 lines across all 8 issues.

---

Full plan document: docs/geolocation-phase2-plan.md

[ben-dz]

Architecture review findings:

• Critical: 0
• High: 3
• Medium: 5
• Low: 3

Architecture Review

Critical

None.

High

1. PDA seed scheme diverges from the RFC and existing codebase conventions -- plan and RFC are internally inconsistent.

The implementation plan proposes code-based PDA seeds for GeoProbe and GeolocationUser:

• GeoProbe: ["doublezero", "probe", code.as_bytes()]
• GeolocationUser: ["doublezero", "geouser", code.as_bytes()]

However, the RFC itself (lines 155 and 452 of rfcs/rfc16-geolocation-verification.md) specifies index-based PDA seeds:

• Probe: ["doublezero", "probe", index.to_le_bytes()]
• GeolocationUser: ["doublezero", "geolocation_user", code.as_bytes()]

Moreover, the existing Serviceability program uses index.to_le_bytes() for nearly all entity PDAs (Device, Exchange, Location, Link, MulticastGroup, Contributor -- see smartcontract/programs/doublezero-serviceability/src/pda.rs), with only Tenant using code-based derivation. The implementation plan opts for code-based seeds without discussing this inconsistency or the migration implications. This ambiguity between the RFC and the plan needs to be resolved before implementation begins, as it affects the Go SDK, Rust SDK, CLI, and all discovery logic.

Additionally, the plan uses the seed "geouser" while the RFC uses "geolocation_user". These must be reconciled, because the cross-language PDA consistency requirement (risk #6 in the plan) makes any seed mismatch a showstopper.

2. The plan proposes a separate "doublezero-geolocation" program, but the RFC specifies modifications to the existing Serviceability and Telemetry programs.

The plan proposes a brand-new doublezero-geolocation program, while the RFC's Phase 2 section explicitly states "Serviceability program changes" with instructions added to the existing Serviceability and Telemetry programs. The plan even says "The Geolocation Program is separate from Serviceability but references it via CPI for foundation allowlist checks", introducing a CPI dependency that the RFC does not envision.

This is a significant architectural decision that should be discussed more explicitly. Creating a new program has real tradeoffs: it requires deploying a new program ID, adds CPI complexity for allowlist checks, increases transaction size (extra program account), and diverges from the existing pattern of extending Serviceability. The plan mentions CPI as Risk #2 but treats it as a testing concern rather than an architectural choice requiring justification. The document should either get explicit buy-in for the separate-program approach with rationale, or align with the RFC's original design of extending existing programs.

3. Instruction variant numbering has gaps and is incomplete.

The plan lists instruction variants 0, 1, 2, 6, 7, 8, 9, 10, 11, 12, 13, 14 but omits variants 3, 4, and 5. If these are reserved for future use, that should be stated. If they are instructions that were accidentally omitted from the plan, the scope is underestimated. Either way, the document claims "15 instructions" but only lists 12 instruction names. The implementer will be confused about what variants 3-5 should be.

Medium

4. Typo in Go SDK function name: DeriveGeoGrobePDA should be DeriveGeoProbePDA.

The plan lists DeriveGeoGrobePDA() -- this is a typo for DeriveGeoProbePDA(). While this is a naming issue in documentation, function names in SDKs tend to propagate widely once shipped.

5. Account size limits and reallocation strategy are identified as a risk but not addressed in any issue scope.

Risk #5 correctly identifies that GeoProbe.parent_devices and GeolocationUser.targets are Vec fields that grow Solana accounts. However, none of the 8 issues include explicit scope for defining maximum sizes, implementing reallocation logic, or handling the MAX_PERMITTED_DATA_INCREASE constraint (10KB per transaction in Solana). This is a non-trivial Solana-specific concern that should be explicitly scoped into Issue A. The existing Serviceability program does not appear to have dynamically growing Vec fields in its core account types, so this would be new territory for this codebase.

6. Issue F and G have overlapping file concerns that the parallelism section claims don't exist.

The parallelism notes state "No overlapping file changes between these four issues" (D, E, F, G). However, both Issues F and G create files under controlplane/telemetry/internal/geoprobe/, and both would need to share types and interfaces for onchain account querying. The geoprobe-agent/main.go already has a stub for discovery, so Issues F and G are not fully independent.

7. Missing explicit scope for InitProgramConfig instruction and program deployment bootstrapping.

Issue A mentions InitProgramConfig (variant 0) but the scope section does not discuss how the Geolocation program discovers or stores the Serviceability program ID needed for CPI calls. Since this is a one-time bootstrap operation that gates all other functionality, it should be explicitly called out in Issue A's scope, including who signs the transaction and how it integrates with the devnet/testnet deployment process.

8. No issue for the Geolocation program deployment pipeline.

Risk #1 correctly notes "Program ID must be generated and registered," but none of the 8 issues include scope for generating the program keypair, updating Cargo.toml with the program ID, adding the program to the Makefile build targets, or updating the devnet/testnet deployment scripts. This infrastructure work blocks all SDK and E2E work and should either be part of Issue A or a separate Issue 0.

Low

9. CLI command hierarchy inconsistency between Issues D and E.

Issue D proposes top-level doublezero probe create/update/delete/list/get, while Issue E proposes doublezero geolocation user create/update/delete/list. This creates an inconsistent CLI hierarchy: probe management is at the top level while user/target management is nested under geolocation. Consider either doublezero geolocation probe ... for consistency with the geolocation namespace, or a flat-entity approach.

10. The plan references the RFC's geoprobe-agent as a Go component, but the RFC says it's Rust.

The RFC states the geoProbe Server language is "Rust", but the actual implementation at controlplane/telemetry/cmd/geoprobe-agent/main.go is in Go, and the plan correctly treats it as Go. The RFC should be updated to reflect the actual language choice.

11. The "Estimated Total Scope" table could note which issues are on the critical path.

The scope table lists all 8 issues by estimated line count, but it would be more useful for planning if the critical path items were marked.

Summary

The implementation plan is well-structured with a clear issue breakdown and reasonable build-order dependency graph. However, there are high-severity concerns that need resolution before implementation: (1) the PDA seed scheme is inconsistent between the plan and the RFC, (2) the decision to create a separate Geolocation program rather than extending Serviceability needs explicit justification, and (3) the instruction variant numbering gaps need clarification.

[ben-dz]

Security review findings:

• Critical: 0
• High: 0
• Medium: 3
• Low: 3

Security Review

Critical

None

High

None

Medium

1. Unbounded Vec growth on GeoProbe.parent_devices and GeolocationUser.targets could lead to denial-of-service via account inflation

The plan document acknowledges this in its "Risks & Considerations" section (item 5: "Account size limits"), but does not specify concrete maximum sizes. The existing codebase's resize_account_if_needed function (at smartcontract/programs/common/src/resize_account.rs) will automatically resize Solana accounts to accommodate growing Vec fields, but Solana imposes a hard 10 MB per-account limit and a 10 KB per-transaction reallocation limit. Without explicit maximum element counts enforced in the onchain program processors, a foundation-allowlisted caller could repeatedly call AddParentDevice or a self-service user could repeatedly call AddTarget to grow an account to the reallocation limit. The implementation should define and enforce MAX_PARENT_DEVICES and MAX_TARGETS constants onchain.

2. Self-service GeolocationUser creation without rate limiting or payment validation at creation time

Per the plan, user operations are self-service (signer = owner), while billing operations are foundation-gated. The UpdatePaymentStatus instruction is a separate foundation-only call. This means any Solana account holder can create a GeolocationUser and add target IPs that probes will begin measuring before payment status is set to Paid. While the plan mentions that geoProbe target discovery (Issue G) should "only measure targets from users with payment_status: Paid", this is enforced only at the discovery/reading layer, not at the onchain program level. An attacker could create many GeolocationUser accounts with targets, and any buggy or outdated probe that does not filter on payment status would perform measurements against attacker-controlled IPs. The onchain program should ideally enforce that targets cannot be added until payment is active, or the plan should explicitly document that the payment filter is a critical security invariant at the probe discovery layer.

3. CPI trust boundary: Geolocation Program trusts Serviceability for allowlist checks without verifying program ownership

The plan states that the Geolocation Program "references [Serviceability] via CPI for foundation allowlist checks." When implementing the CPI, the Geolocation Program must verify that the Serviceability program account passed into the instruction matches the expected program ID stored in ProgramConfig.serviceability_program_id. If the implementation fails to verify the program ID of the CPI target, an attacker could pass a malicious program that always returns "allowed." This is a well-known Solana CPI vulnerability pattern. The plan should explicitly call out the verification step as a security requirement.

Low

4. PDA seed uses code.as_bytes() with no length constraint on code

The PDA derivation seeds use code.as_bytes() directly. Solana PDA seed inputs have a maximum total length of 32 bytes per individual seed component. An excessively long code string would cause find_program_address to fail at the Solana runtime level (not a vulnerability per se), but it would produce confusing errors rather than a clean validation failure. The plan should specify a maximum code length (the existing codebase already has a 32-byte convention). This should be validated both in the CLI and the onchain processor.

5. No explicit IP address validation rules for target IPs

The plan specifies that users can add target IPs via AddTarget and the CLI doublezero geolocation add-target. There is no mention of validating that the submitted IPv4 addresses are routable public IPs. Without validation, users could submit private/reserved ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback (127.0.0.0/8), multicast (224.0.0.0/4), or broadcast addresses. If probes attempt TWAMP measurements to such addresses, this could cause probes to send traffic to internal network addresses (a form of server-side request forgery) or waste resources on unmeasurable targets. The implementation should validate that target IPs are in publicly routable ranges.

6. No mention of keypair file permission hardening for geoProbe keys

The RFC mentions geoProbe keys are stored at /etc/probe/keypair.json. The plan inherits this design but does not specify file permission requirements. The keypair file should be readable only by the geoProbe service account (e.g., mode 0600). Given that probe keys sign LocationOffset messages used as cryptographic proofs of location, compromise of these keys would allow forging location attestations.

Summary

This is a documentation-only change describing a well-structured implementation plan. The proposed architecture has sound access control fundamentals (foundation-gated probe management, self-service user operations, CPI-based allowlist verification). The primary security considerations for implementers are: enforcing maximum sizes on the unbounded Vec fields to prevent account inflation, ensuring the CPI to Serviceability verifies the target program ID, validating that target IPs are publicly routable to prevent SSRF-like behavior from probes, and ensuring the payment status filter is treated as a hard security requirement at the probe discovery layer.

[ben-dz]

Roadbike Operator Feedback

Action: Plan revision requested (Revision 1)
Instance: #7

Address some of the concerns from the reviewers:
For Architecture, address:
3. Some instructions were removed I PR2950 was updated. Please update the work plan numbering.
4. Please fix this.
5. Please update issue A to include a plan for handling the vectors in the account.
7. Please address this.
8. Make this part of issue A.
9. please make all geolocation commands start with doublezero geolocation
10. geoprobe-agent is a go program. The RFC has been updated in PR2950.

For Security, address:

1. Tie this into the work for Issue 5 above. A GeoProbe can only have 5 parents. A GeolocationUser can only support 4096 targets.
2. Please add this to the plan.
3. Please add this to the plan.
4. Please add this to the plan.

When you re-request reviews, be sure to tell the reviewers to use the RFC in PR2950 as their reference, not the version in main.

[ben-dz]

Work Plan (Revision 1)

Work Plan (Revision 1)

Geolocation Verification Phase 2 — Implementation Plan (Revision 1)

Tracker Issue: #2943
RFC: rfc16-geolocation-verification.md
Updated Smart Contract Design: PR #2950

Overview

Phase 2 transitions the geolocation system from CLI-arg-driven configuration (Phase 1) to onchain configuration. The updated RFC (PR #2950) introduces a new Geolocation Program deployed separately from Serviceability, with three account types (GeolocationProgramConfig, GeoProbe, GeolocationUser) and 12 instruction variants (0–11).

Key Changes from Phase 1

Aspect	Phase 1	Phase 2
Probe discovery	--additional-child-probes CLI flag	Onchain GeoProbe accounts
Target discovery	--additional-targets CLI flag	Onchain GeolocationUser.targets
Parent DZD config	--additional-parent CLI flag	Onchain GeoProbe.parent_devices
Program	N/A (no onchain)	New doublezero-geolocation program
Billing	N/A	GeolocationPaymentStatus + token account

Architecture (from PR #2950)

The Geolocation Program is a new, separate program deployed independently from Serviceability. It manages GeoProbe infrastructure and GeolocationUser accounts. It references the Serviceability Program's GlobalState via CPI for foundation allowlist checks. GeoProbe management is foundation-gated; GeolocationUser creation is self-service.

Proposed Issues

Issue A: Geolocation Program — Account types, instructions, processors, and deployment

RFC Reference: rfc16 — Smart Contract Changes (as updated by PR #2950)

Goal: Create a new doublezero-geolocation onchain program with all 3 account types and 12 instructions defined in the updated RFC (PR #2950), plus all deployment infrastructure.

Scope:

New Cargo Crate

• New crate smartcontract/programs/doublezero-geolocation/
• Follow existing patterns: crate-type = ["cdylib", "lib"], [package.metadata.solana] with generated program ID
• Add to workspace Cargo.toml and Makefile build targets (cargo build-sbf)
• Generate program keypair and register program ID

Account Types

• GeolocationProgramConfig — singleton program config

  • Fields: account_type, bump_seed, version, min_compatible_version, serviceability_program_id
  • PDA: ["doublezero", "programconfig"]
  • The serviceability_program_id field stores the expected Serviceability program ID. All CPI calls to Serviceability must verify that the passed program account matches this stored ID to prevent malicious program substitution.

• GeoProbe — probe infrastructure

  • Fields: account_type, owner, bump_seed, exchange_pk, public_ip, port, code, parent_devices, metrics_publisher_pk, latency_threshold_ns, reference_count
  • PDA: ["doublezero", "probe", code.as_bytes()]
  • parent_devices: Vec<Pubkey> — maximum 5 entries (MAX_PARENT_DEVICES = 5). Enforced in AddParentDevice processor. Account reallocation via resize_account_if_needed on add; shrink on remove.
  • code — maximum 32 bytes. Validated in CreateGeoProbe processor and CLI.

• GeolocationUser — user accounts

  • Fields: account_type, owner, bump_seed, code, token_account, payment_status, billing, status, targets
  • PDA: ["doublezero", "geouser", code.as_bytes()]
  • targets: Vec<GeolocationTarget> — maximum 4096 entries (MAX_TARGETS = 4096). Enforced in AddTarget processor. Each GeolocationTarget contains target_ip: Ipv4Addr, target_port: u16, probe_pk: Pubkey (~38 bytes each). Account reallocation via resize_account_if_needed on add; shrink on remove.
  • code — maximum 32 bytes. Validated in CreateGeolocationUser processor and CLI.

Vec Handling and Account Reallocation Strategy

Both GeoProbe.parent_devices and GeolocationUser.targets are variable-length vectors that cause the account to grow. The strategy:

1. Hard maximums enforced onchain: MAX_PARENT_DEVICES = 5, MAX_TARGETS = 4096. Processors return a descriptive error if the limit is exceeded.
2. Reallocation on add: When adding an element, compute the new serialized size, call resize_account_if_needed (from smartcontract/programs/common/) to grow the account and transfer additional rent from the payer. Solana's per-transaction reallocation limit is 10KB; a single AddTarget adds ~38 bytes, well within this limit.
3. Shrink on remove: When removing an element, swap-remove from the vec, reserialize, and shrink the account via realloc. Return excess rent to the payer.
4. Initial allocation: CreateGeoProbe allocates space for the base struct + 0 parents. CreateGeolocationUser allocates space for the base struct + 0 targets. Growth happens incrementally via add instructions.

Instructions (12 variants, 0–11)

Variant	Name	Access Control
0	InitProgramConfig	Program deploy authority (one-time)
1	CreateGeoProbe	Foundation allowlist (via Serviceability CPI)
2	UpdateGeoProbe	Foundation allowlist (via Serviceability CPI)
3	DeleteGeoProbe	Foundation allowlist (via Serviceability CPI)
4	AddParentDevice	Foundation allowlist (via Serviceability CPI)
5	RemoveParentDevice	Foundation allowlist (via Serviceability CPI)
6	CreateGeolocationUser	Any signer (self-service, signer becomes owner)
7	UpdateGeolocationUser	GeolocationUser owner
8	DeleteGeolocationUser	GeolocationUser owner (requires targets is empty)
9	AddTarget	GeolocationUser owner
10	RemoveTarget	GeolocationUser owner
11	UpdatePaymentStatus	Foundation allowlist (via Serviceability CPI)

InitProgramConfig Bootstrapping

InitProgramConfig (variant 0) is a one-time instruction that creates the GeolocationProgramConfig PDA account. It accepts a serviceability_program_id parameter and stores it for subsequent CPI calls. The signer must be the program deploy authority. This instruction must be called before any other Geolocation instruction can work (all foundation-gated instructions depend on it for CPI resolution).

The deployment sequence is:

1. Generate program keypair (solana-keygen grind)
2. Add program ID to Cargo.toml [package.metadata.solana]
3. Build with cargo build-sbf
4. Deploy to validator/devnet/testnet
5. Call InitProgramConfig with the Serviceability program ID

CPI Security: Program ID Verification

All foundation-gated instructions perform a CPI call to the Serviceability program to check the foundation allowlist. The processor must:

1. Read serviceability_program_id from GeolocationProgramConfig
2. Compare it against the program account passed in the instruction's account list
3. Return an error if they don't match

This prevents an attacker from passing a malicious program that always returns "allowed."

Input Validation

• Code length: Both CreateGeoProbe and CreateGeolocationUser must validate that code.len() <= 32. Solana PDA seeds have a 32-byte-per-component limit; exceeding it causes a confusing runtime error. Return a clean InvalidCodeLength error instead.
• IP address validation: AddTarget must validate that target_ip is a publicly routable IPv4 address. Reject private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback (127.0.0.0/8), multicast (224.0.0.0/4), and broadcast (255.255.255.255). This prevents probes from sending measurement traffic to internal network addresses (SSRF-like behavior). The same validation should be applied to CreateGeoProbe.public_ip.

Unit Tests

• Instruction pack/unpack for all 12 variants
• PDA derivation for all 3 account types
• Processor logic for each instruction (happy path + access control failures)
• Vec growth/shrink and reallocation behavior
• Code length validation (boundary: 32 bytes, 33 bytes)
• IP validation (private ranges, loopback, multicast, valid public IPs)
• CPI program ID verification (correct ID, wrong ID)

Key files to create:

• smartcontract/programs/doublezero-geolocation/Cargo.toml
• smartcontract/programs/doublezero-geolocation/src/lib.rs
• smartcontract/programs/doublezero-geolocation/src/entrypoint.rs
• smartcontract/programs/doublezero-geolocation/src/error.rs
• smartcontract/programs/doublezero-geolocation/src/instructions.rs
• smartcontract/programs/doublezero-geolocation/src/processor.rs
• smartcontract/programs/doublezero-geolocation/src/pda.rs
• smartcontract/programs/doublezero-geolocation/src/seeds.rs
• smartcontract/programs/doublezero-geolocation/src/validation.rs (IP validation, code length)
• smartcontract/programs/doublezero-geolocation/src/state/ (accounttype.rs, program_config.rs, geo_probe.rs, geolocation_user.rs)
• smartcontract/programs/doublezero-geolocation/src/processors/ (program_config/, geo_probe/, geolocation_user/)
• Makefile updates for cargo build-sbf

Estimated scope: Large (~1000–1400 lines, increased from prior estimate due to deployment infra, validation, and reallocation logic)

---

Issue B: Go SDK — Geolocation program types and client methods

RFC Reference: rfc16-geolocation-verification.md (as updated by PR #2950)

Goal: Create a new Go SDK package for the Geolocation program with types, deserialization, PDA derivation, instruction builders, and client methods.

Scope:

• New Go package smartcontract/sdk/go/geolocation/
• Go structs matching Rust serialization layout:
  • GeolocationProgramConfig, GeoProbe, GeolocationUser, GeolocationTarget
  • GeolocationUserStatus, GeolocationPaymentStatus, GeolocationBillingConfig
• PDA derivation functions:
  • DeriveProgramConfigPDA()
  • DeriveGeoProbePDA() using seeds ["doublezero", "probe", code]
  • DeriveGeolocationUserPDA() using seeds ["doublezero", "geouser", code]
• Instruction builder functions for all 12 instructions
• Client methods:
  • GetProgramConfig(), GetGeoProbes(), GetGeolocationUsers()
  • GetGeoProbeByCode(), GetGeolocationUserByCode()
  • Transaction builders for all instructions
• Deserialization for all account types
• Unit tests for PDA derivation (must match Rust), serialization round-trip

Key files to create:

• smartcontract/sdk/go/geolocation/client.go
• smartcontract/sdk/go/geolocation/constants.go
• smartcontract/sdk/go/geolocation/state.go
• smartcontract/sdk/go/geolocation/pda.go
• smartcontract/sdk/go/geolocation/deserialize.go
• smartcontract/sdk/go/geolocation/executor.go
• smartcontract/sdk/go/geolocation/rpc.go
• Instruction builder files (one per instruction group)
• smartcontract/sdk/go/geolocation/*_test.go

Estimated scope: Medium–Large (~500–700 lines)

---

Issue C: Rust SDK — Geolocation instruction builders

RFC Reference: rfc16-geolocation-verification.md (as updated by PR #2950)

Goal: Add Rust SDK instruction builders for the Geolocation program to support CLI commands and integration tests.

Scope:

• New module or extend existing smartcontract/sdk/rs/ with geolocation instruction builders
• Builder functions for all 12 instructions
• PDA derivation functions (reuse from the program crate or create SDK-side helpers)
• Instruction serialization matching the program's GeolocationInstruction enum

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

---

Issue D: CLI tool — GeoProbe management commands

RFC Reference: rfc16 — Phase 2, item 4 (as updated by PR #2950)

Goal: Add probe management CLI commands under the doublezero geolocation namespace.

Scope:

• New CLI module smartcontract/cli/src/geolocation/probe/
• Commands (all under doublezero geolocation probe):
  • doublezero geolocation probe create — creates a GeoProbe account (args: code, exchange, public-ip, port, latency-threshold-ns, metrics-publisher-pk)
  • doublezero geolocation probe update — updates GeoProbe fields (public-ip, port, latency-threshold-ns, metrics-publisher-pk)
  • doublezero geolocation probe delete — deletes a GeoProbe account
  • doublezero geolocation probe list — lists all GeoProbe accounts
  • doublezero geolocation probe get — gets a specific GeoProbe by code
  • doublezero geolocation probe add-parent — adds a parent DZD to a GeoProbe
  • doublezero geolocation probe remove-parent — removes a parent DZD from a GeoProbe
  • doublezero geolocation init-config — initializes the GeolocationProgramConfig (one-time)
• CLI-side validation:
  • Code length <= 32 bytes
  • IP address is publicly routable (same rules as onchain)
• Follow existing CLI patterns: clap derive macros, CliCommand trait, validators
• Depends on Rust SDK (Issue C)

Estimated scope: Medium (~300–500 lines)

---

Issue E: CLI tool — GeolocationUser and target management commands

RFC Reference: rfc16 — Phase 2, item 4 (as updated by PR #2950)

Goal: Add geolocation user and target management CLI commands under the doublezero geolocation namespace.

Scope:

• New CLI module smartcontract/cli/src/geolocation/user/
• Commands (all under doublezero geolocation):
  • doublezero geolocation user create — creates a GeolocationUser account (args: code, token-account)
  • doublezero geolocation user update — updates GeolocationUser (token-account)
  • doublezero geolocation user delete — deletes a GeolocationUser account (requires targets is empty)
  • doublezero geolocation user list — lists all GeolocationUser accounts
  • doublezero geolocation user get — gets a specific GeolocationUser by code
  • doublezero geolocation add-target — adds a target to a user (args: user-code, target-ip, target-port, exchange)
  • doublezero geolocation remove-target — removes a target from a user (args: user-code, target-ip, exchange)
  • doublezero geolocation update-payment — updates payment status (foundation-only)
• CLI-side validation:
  • Code length <= 32 bytes
  • Target IP is publicly routable
• Follow existing CLI patterns
• Depends on Rust SDK (Issue C)

Estimated scope: Medium (~300–500 lines)

---

Issue F: Telemetry agent — onchain child geoProbe discovery

RFC Reference: rfc16 — Phase 2, item 2 (as updated by PR #2950)

Goal: Extend the telemetry agent to discover its child geoProbes from onchain GeoProbe accounts, replacing/supplementing the --additional-child-probes CLI flag.

Scope:

• New or extended module in controlplane/telemetry/internal/geoprobe/discovery.go
• Periodically query the Geolocation program for GeoProbe accounts where parent_devices contains the local device's pubkey (60s interval per RFC)
• Convert discovered GeoProbe accounts to ProbeAddress structs and send them to the Coordinator via ProbeUpdateCh
• Merge onchain-discovered probes with any --additional-child-probes CLI args
• Use the Go Geolocation SDK (Issue B) to query probes
• The --additional-child-probes flag continues to work for backwards compatibility

Key files to change/create:

• controlplane/telemetry/internal/geoprobe/discovery.go (new)
• controlplane/telemetry/internal/geoprobe/discovery_test.go (new)
• controlplane/telemetry/internal/telemetry/collector.go — start discovery goroutine
• controlplane/telemetry/internal/telemetry/config.go — add ProbeDiscoveryInterval field

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

---

Issue G: geoProbe agent — onchain parent DZD and target discovery

RFC Reference: rfc16 — Phase 2, item 3 (as updated by PR #2950)

Goal: Extend the geoProbe agent (Go program at controlplane/telemetry/cmd/geoprobe-agent/) to discover parent DZDs and targets from onchain data.

Note: The geoProbe agent is implemented in Go (consistent with other controlplane infrastructure). The RFC has been updated in PR #2950 to reflect this.

Scope:

• Parent DZD Discovery: Query the Geolocation program for the GeoProbe account matching this server's code/pubkey, extract parent_devices, resolve Device accounts from Serviceability to get IPs and metrics_publisher_pk for signature verification
• Target Discovery: Query onchain GeolocationUser accounts, filter for targets where probe_pk matches this probe, extract target IPs (30s interval per RFC). Only measure targets from users with payment_status: Paid. The payment status filter is a critical security invariant — without it, unpaid users could direct probe traffic to arbitrary IPs.
• Merge onchain-discovered parents/targets with CLI-arg-based configuration
• Update trusted parent pubkey whitelist dynamically
• Update target list dynamically

Key files to change/create:

• controlplane/telemetry/cmd/geoprobe-agent/main.go — add discovery goroutines
• controlplane/telemetry/internal/geoprobe/onchain_discovery.go (new — shared discovery logic for both telemetry agent and geoprobe agent)
• controlplane/telemetry/internal/geoprobe/onchain_discovery_test.go (new)

Note on file overlap with Issue F: Both Issues F and G create files under controlplane/telemetry/internal/geoprobe/. They share the Go Geolocation SDK dependency and may share some query helpers. Coordinate to avoid conflicts: Issue F owns discovery.go (telemetry-agent-side child probe discovery), Issue G owns onchain_discovery.go (geoprobe-agent-side parent/target discovery). Shared types should go in the SDK (Issue B).

Estimated scope: Medium (~300–400 lines)

---

Issue H: E2E tests — onchain configuration flow

RFC Reference: rfc16 — Phase 2, item 6 (as updated by PR #2950)

Goal: Create E2E tests verifying the full geolocation flow using onchain configuration.

Scope:

• New E2E test file e2e/geolocation_test.go (or extend existing):
  1. Deploy the Geolocation program
  2. Initialize GeolocationProgramConfig with Serviceability program ID
  3. Create a GeoProbe account onchain via CLI/SDK
  4. Add parent devices to the GeoProbe
  5. Create a GeolocationUser account with target IPs
  6. Start telemetry agent, geoProbe agent, and target listener without CLI-arg configuration
  7. Verify: agents discover configuration from onchain state
  8. Verify: full DZD → Probe → Target measurement chain works
  9. Verify: adding/removing target IPs onchain is reflected in probe behavior
• Extend devnet infrastructure for Geolocation program deployment
• Test both Dockernet and DevNet

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

---

Build Order and Parallelism

Phase 1 (Foundation — Onchain Program + Deployment):
  Issue A: Geolocation Program + Deployment ─────────┐
                                                      │
Phase 2 (SDKs — depends on A):                       │
  Issue B: Go SDK  ──────────────┐                    │
  Issue C: Rust SDK ─────────────┼── Can build in    ←┘
                                 │   parallel (Go vs Rust,
                                 │   no shared files)
                                 │
Phase 3 (CLI + Discovery — depends on B+C):          │
  Issue D: CLI — Probe commands ─┐                   ←┘
  Issue E: CLI — User commands  ─┤── Can build in parallel
  Issue F: Telemetry discovery  ─┤   (D+E are Rust CLI modules,
  Issue G: geoProbe discovery  ──┘    F+G are Go packages)
                                      Note: F and G share the
                                      geoprobe/ directory — see
                                      coordination note in Issue G.

Phase 4 (Integration — depends on all above):
  Issue H: E2E tests

Critical Path

Issue A → Issue B + Issue C → Issue F + Issue G → Issue H

Parallelism Notes

• Issues B and C can be built in parallel (Go SDK vs Rust SDK, completely separate codebases)
• Issues D and E can be built in parallel (separate CLI modules, both depend on Issue C)
• Issues F and G can be built in parallel but require coordination: both create files under controlplane/telemetry/internal/geoprobe/. Issue F owns telemetry-agent-side discovery, Issue G owns geoprobe-agent-side discovery. Shared types belong in the Go SDK (Issue B).
• Issue H must wait for all other issues

Risks & Considerations

1. New program deployment: Unlike adding to Serviceability, this requires deploying an entirely new program to devnet/testnet. Program ID must be generated and registered. This is addressed in Issue A's deployment scope.

2. Serviceability CPI: The Geolocation program calls into Serviceability to verify foundation allowlist membership. The CPI must verify the Serviceability program ID matches what's stored in GeolocationProgramConfig to prevent malicious program substitution. This is a security-critical requirement addressed in Issue A.

3. Backwards compatibility: Phase 1 CLI flags (--additional-child-probes, --additional-parents, --additional-targets) must continue to work alongside onchain discovery.

4. Billing integration: GeolocationPaymentStatus and GeolocationBillingConfig are new concepts. The UpdatePaymentStatus instruction is foundation-gated, but the billing sentinel/oracle is not yet built. For phase 2, manual billing updates via CLI may suffice.

5. Account size limits: GeoProbe.parent_devices (max 5) and GeolocationUser.targets (max 4096) are Vec fields that grow accounts. Hard maximums are enforced onchain. Reallocation uses the existing resize_account_if_needed utility. See Issue A for the detailed strategy.

6. PDA seed consistency: Rust and Go PDA derivations must produce identical addresses. Cross-language PDA tests are critical.

7. MVP constraint: Each exchange has 0 or 1 probe. The CLI and discovery logic should enforce this.

8. Input validation: Code length (max 32 bytes) and IP address validation (publicly routable only) must be enforced both onchain and in the CLI to prevent confusing runtime errors and SSRF-like measurement behavior.

Testing Strategy

• Unit tests (Issues A, B, C): Instruction pack/unpack, PDA derivation (cross-language), processor logic, access control, vec reallocation, input validation (code length, IP ranges), CPI program ID verification
• Integration tests (Issues D, E): CLI commands against a local validator
• E2E tests (Issue H): Full Dockernet test with onchain-configured measurement chain

Estimated Total Scope

Issue	Scope	Lines (est.)	Critical Path
A: Geolocation Program + Deployment	Large	1000–1400	Yes
B: Go SDK	Medium–Large	500–700	Yes
C: Rust SDK	Small–Medium	200–300	No
D: CLI — Probe	Medium	300–500	No
E: CLI — User/Target	Medium	300–500	No
F: Telemetry discovery	Small–Medium	200–300	Yes
G: geoProbe discovery	Medium	300–400	Yes
H: E2E tests	Medium–Large	400–600	Yes
Total		3,200–4,700

Revision History

Rev	Date	Changes
0	2026-02-12	Initial plan
1	2026-02-12	Addressed reviewer feedback: updated instruction count to 12 (variants 0–11) per updated PR #2950; fixed DeriveGeoProbePDA typo; added vec handling strategy with MAX_PARENT_DEVICES=5 and MAX_TARGETS=4096 to Issue A; added InitProgramConfig bootstrapping and deployment pipeline scope to Issue A; added CPI program ID verification as security requirement; unified all CLI commands under doublezero geolocation namespace; corrected geoProbe agent language to Go; added code length validation (32 bytes max); added IP address validation (publicly routable only); noted file overlap coordination between Issues F and G; added critical path column to scope table