geoprobe: shared library — LocationOffset types, signing, and UDP transport

[nikw9944]

RFC Reference: rfc16-geolocation-verification.md — LocationOffset struct, Offset signing
Tracking issue: #2893

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)

Dependencies

None — this is the foundation issue.

[ben-dz]

Work Plan (Revision 0)

Estimated Scope: Small

Work Plan: Issue #2898 - geoprobe: shared library

Issue: #2898
RFC Reference: RFC16 - Geolocation Verification
Branch: ben-dz/doublezero-2898

Summary

Create the foundational Go package for Phase 1 of the geolocation verification system. This package provides the core data structures, cryptographic signing/verification, and UDP transport mechanisms that will be used by all three Phase 1 binaries: the telemetry agent (DZD), the geoprobe agent, and the target test tool. The LocationOffset struct matches the RFC specification and uses Ed25519 signatures compatible with Solana keypairs for cryptographic verification of the measurement chain.

Approach

This implementation will follow existing patterns in the doublezero codebase:

1. LocationOffset Type Definition (offset.go):

   • Define the LocationOffset struct matching RFC16 specification exactly
   • Support nested references to enable DZD→Probe→Target measurement chains
   • Use Borsh serialization (via github.com/gagliardetto/binary) for consistency with existing telemetry code
   • Implement marshal/unmarshal methods for binary serialization
   • The struct will include signature, pubkey, measurement slot, lat/lng, RTT fields, and a recursive References slice

2. Ed25519 Signing (signer.go):

   • Wrap existing solana.PrivateKey patterns from controlplane/telemetry/internal/state/signer.go
   • Implement SignOffset to create cryptographically signed LocationOffset messages
   • Implement VerifyOffset to validate signatures from DZDs or Probes
   • Follow the same signing approach used in telemetry state collection
   • Use Ed25519 signatures compatible with Solana's signature format (64 bytes)

3. UDP Transport (transport.go):

   • Create helpers for sending/receiving LocationOffset datagrams over UDP
   • Implement SendOffset(conn *net.UDPConn, addr *net.UDPAddr, offset *LocationOffset) error
   • Implement ReceiveOffset(conn *net.UDPConn) (*LocationOffset, *net.UDPAddr, error)
   • Handle serialization/deserialization within transport layer
   • Use standard library net package (no external dependencies needed)

4. Testing Strategy:

   • Unit tests following existing patterns in controlplane/telemetry/internal/state/*_test.go
   • Use github.com/stretchr/testify/require for assertions
   • Test signing round-trip: sign an offset, verify signature succeeds
   • Test serialization round-trip: marshal to bytes, unmarshal, compare equality
   • Test invalid signature detection: modify signed data, verify signature fails
   • Test reference chain verification: create multi-hop offsets with nested references
   • Mock UDP connections not needed initially; focus on serialization and crypto

Files to Change

New Files to Create

1. controlplane/telemetry/internal/geoprobe/offset.go (~80-100 lines)

   • LocationOffset struct definition with all RFC-specified fields
   • Marshal() ([]byte, error) method for binary serialization
   • Unmarshal([]byte) error method for deserialization
   • Helper methods for accessing reference chain information

2. controlplane/telemetry/internal/geoprobe/signer.go (~60-80 lines)

   • OffsetSigner struct wrapping solana.PrivateKey
   • NewOffsetSigner(keypair solana.PrivateKey) *OffsetSigner constructor
   • SignOffset(offset *LocationOffset) error - signs and populates signature field
   • VerifyOffset(offset *LocationOffset) error - validates signature matches data
   • GetSigningBytes(offset *LocationOffset) ([]byte, error) - extracts signable bytes

3. controlplane/telemetry/internal/geoprobe/transport.go (~60-80 lines)

   • SendOffset(conn *net.UDPConn, addr *net.UDPAddr, offset *LocationOffset) error
   • ReceiveOffset(conn *net.UDPConn) (*LocationOffset, *net.UDPAddr, error)
   • NewUDPListener(port int) (*net.UDPConn, error) - helper for creating listeners
   • Error handling for network failures and oversized datagrams

4. controlplane/telemetry/internal/geoprobe/offset_test.go (~80-100 lines)

   • TestLocationOffset_MarshalUnmarshal - round-trip serialization
   • TestLocationOffset_WithReferences - nested reference chain serialization
   • TestLocationOffset_EmptyReferences - DZD-generated offset (no references)
   • TestLocationOffset_MarshalError - invalid data handling

5. controlplane/telemetry/internal/geoprobe/signer_test.go (~100-120 lines)

   • TestSignOffset_Success - sign and verify valid offset
   • TestVerifyOffset_InvalidSignature - tampered data detection
   • TestVerifyOffset_WrongPublicKey - signature from wrong keypair
   • TestSignOffset_WithReferences - sign offset containing reference chain
   • TestVerifyOffset_ChainValidation - validate entire DZD→Probe chain

No Existing Files Modified

This is a greenfield package with no modifications to existing code.

Technical Details

LocationOffset Structure

Based on RFC16, the Go struct will be:

type LocationOffset struct {
    Signature       [64]byte         // Ed25519 signature
    Pubkey          [32]byte         // Signer's public key
    MeasurementSlot uint64           // Current DoubleZero Slot
    Lat             float64          // Reference point latitude (WGS84)
    Lng             float64          // Reference point longitude (WGS84)
    MeasuredRttNs   uint64           // Measured RTT in nanoseconds
    RttNs           uint64           // Accumulated RTT to target in ns
    NumReferences   uint8            // Number of reference offsets
    References      []LocationOffset // Reference offsets (recursive)
}

Serialization Format

Use Borsh encoding via github.com/gagliardetto/binary for consistency with existing telemetry code. The signing bytes will be the serialized form of all fields except the Signature field itself (following standard practice where signatures are computed over unsigned data).

Signing Process

1. Create LocationOffset with all fields populated except Signature
2. Serialize the offset (excluding the Signature field)
3. Sign the serialized bytes using Ed25519 with the signer's private key
4. Populate the Signature field with the resulting 64-byte signature
5. Transmit the complete signed offset

Verification Process

1. Extract the Signature and Pubkey from received offset
2. Serialize the offset (excluding Signature field)
3. Verify the signature using Ed25519 with the extracted public key
4. For chain verification, recursively verify all References

Risks & Considerations

1. Serialization Format Compatibility: Using Borsh encoding ensures consistency with existing telemetry code, but we need to ensure the format is stable for network transmission between different binaries.

   • Mitigation: Follow exact patterns from smartcontract/sdk/go/telemetry/state.go

2. Signature Field Ordering: The signature must be computed over consistent bytes regardless of where it's stored in the struct.

   • Mitigation: Clearly document that signing excludes the Signature field, following standard cryptographic practice

3. UDP Packet Size: LocationOffset with nested references could exceed typical UDP MTU (1500 bytes).

   • Mitigation: RFC specifies this is acceptable for Phase 1 POC. Future work may add fragmentation if needed
   • For reference: each LocationOffset is ~240 bytes; 5-level chain = ~1200 bytes (within MTU)

4. Reference Chain Depth: Unlimited recursion in References could cause stack overflow.

   • Mitigation: For Phase 1 POC, chains will be shallow (DZD→Probe→Target = 2 levels max). Add depth validation in future work if needed

5. Endianness: Binary serialization must be consistent across all platforms.

   • Mitigation: Borsh encoding uses little-endian by default, which matches the existing codebase

Testing Strategy

Unit Tests

1. Serialization Tests:

   • Marshal/unmarshal round-trip with various field values
   • Empty references vs non-empty references
   • Large reference chains (stress test)
   • Invalid data handling

2. Signing Tests:

   • Sign offset, verify succeeds
   • Modify signed data, verify fails
   • Wrong public key, verify fails
   • Reference chain signature validation

3. Integration Tests (not in this issue, but planned):

   • UDP send/receive round-trip (requires actual network stack)
   • Multi-process communication tests

Test Data

Use realistic values from RFC examples:

• Lat/Lng: Amsterdam (52.3676°N, 4.9041°E)
• RTT: 0.8ms = 800,000 ns (DZD to Probe)
• RTT: 12.5ms = 12,500,000 ns (cumulative to target)
• MeasurementSlot: realistic epoch values

Estimated Scope

Small-to-Medium (~250-300 lines total including tests)

Breakdown:

• Production code: ~200-240 lines across 3 files
• Test code: ~180-220 lines across 2 test files
• Total: ~380-460 lines

This is a foundational library with no external dependencies beyond what's already in go.mod. Implementation should be straightforward following existing patterns.

Dependencies

Upstream: None - this is the foundation issue for Phase 1

Downstream: The following issues will depend on this package:

• Telemetry agent extensions (DZD→Probe measurements)
• geoprobe-agent implementation (Probe→Target measurements)
• geoprobe-target test tool (receive and log offsets)

Open Questions

None at this time. The RFC16 specification is clear and complete for this component.

Acceptance Criteria

1. ✅ LocationOffset struct matches RFC16 specification exactly
2. ✅ Marshal/unmarshal methods work correctly for all field types
3. ✅ Ed25519 signing using Solana keypairs works correctly
4. ✅ Signature verification detects tampered data
5. ✅ Reference chain serialization works with nested offsets
6. ✅ UDP transport helpers can send/receive offsets
7. ✅ All unit tests pass with >90% coverage
8. ✅ Code follows existing doublezero Go conventions
9. ✅ No external dependencies added (all use existing go.mod packages)

Implementation Notes

• Follow naming conventions from existing telemetry code
• Use github.com/gagliardetto/solana-go for keypair operations
• Use github.com/gagliardetto/binary for Borsh serialization
• Use github.com/stretchr/testify/require for test assertions
• No need to add entries to CHANGELOG.md yet (wait until full feature is complete)
• No need to update CLAUDE.md (no new conventions introduced)

[ben-dz]

Approved Work Plan (Revision 0)

Estimated Scope: Small

Work Plan: Issue #2898 - geoprobe: shared library

Issue: #2898
RFC Reference: RFC16 - Geolocation Verification
Branch: ben-dz/doublezero-2898

Summary

Create the foundational Go package for Phase 1 of the geolocation verification system. This package provides the core data structures, cryptographic signing/verification, and UDP transport mechanisms that will be used by all three Phase 1 binaries: the telemetry agent (DZD), the geoprobe agent, and the target test tool. The LocationOffset struct matches the RFC specification and uses Ed25519 signatures compatible with Solana keypairs for cryptographic verification of the measurement chain.

Approach

This implementation will follow existing patterns in the doublezero codebase:

1. LocationOffset Type Definition (offset.go):

   • Define the LocationOffset struct matching RFC16 specification exactly
   • Support nested references to enable DZD→Probe→Target measurement chains
   • Use Borsh serialization (via github.com/gagliardetto/binary) for consistency with existing telemetry code
   • Implement marshal/unmarshal methods for binary serialization
   • The struct will include signature, pubkey, measurement slot, lat/lng, RTT fields, and a recursive References slice

2. Ed25519 Signing (signer.go):

   • Wrap existing solana.PrivateKey patterns from controlplane/telemetry/internal/state/signer.go
   • Implement SignOffset to create cryptographically signed LocationOffset messages
   • Implement VerifyOffset to validate signatures from DZDs or Probes
   • Follow the same signing approach used in telemetry state collection
   • Use Ed25519 signatures compatible with Solana's signature format (64 bytes)

3. UDP Transport (transport.go):

   • Create helpers for sending/receiving LocationOffset datagrams over UDP
   • Implement SendOffset(conn *net.UDPConn, addr *net.UDPAddr, offset *LocationOffset) error
   • Implement ReceiveOffset(conn *net.UDPConn) (*LocationOffset, *net.UDPAddr, error)
   • Handle serialization/deserialization within transport layer
   • Use standard library net package (no external dependencies needed)

4. Testing Strategy:

   • Unit tests following existing patterns in controlplane/telemetry/internal/state/*_test.go
   • Use github.com/stretchr/testify/require for assertions
   • Test signing round-trip: sign an offset, verify signature succeeds
   • Test serialization round-trip: marshal to bytes, unmarshal, compare equality
   • Test invalid signature detection: modify signed data, verify signature fails
   • Test reference chain verification: create multi-hop offsets with nested references
   • Mock UDP connections not needed initially; focus on serialization and crypto

Files to Change

New Files to Create

1. controlplane/telemetry/internal/geoprobe/offset.go (~80-100 lines)

   • LocationOffset struct definition with all RFC-specified fields
   • Marshal() ([]byte, error) method for binary serialization
   • Unmarshal([]byte) error method for deserialization
   • Helper methods for accessing reference chain information

2. controlplane/telemetry/internal/geoprobe/signer.go (~60-80 lines)

   • OffsetSigner struct wrapping solana.PrivateKey
   • NewOffsetSigner(keypair solana.PrivateKey) *OffsetSigner constructor
   • SignOffset(offset *LocationOffset) error - signs and populates signature field
   • VerifyOffset(offset *LocationOffset) error - validates signature matches data
   • GetSigningBytes(offset *LocationOffset) ([]byte, error) - extracts signable bytes

3. controlplane/telemetry/internal/geoprobe/transport.go (~60-80 lines)

   • SendOffset(conn *net.UDPConn, addr *net.UDPAddr, offset *LocationOffset) error
   • ReceiveOffset(conn *net.UDPConn) (*LocationOffset, *net.UDPAddr, error)
   • NewUDPListener(port int) (*net.UDPConn, error) - helper for creating listeners
   • Error handling for network failures and oversized datagrams

4. controlplane/telemetry/internal/geoprobe/offset_test.go (~80-100 lines)

   • TestLocationOffset_MarshalUnmarshal - round-trip serialization
   • TestLocationOffset_WithReferences - nested reference chain serialization
   • TestLocationOffset_EmptyReferences - DZD-generated offset (no references)
   • TestLocationOffset_MarshalError - invalid data handling

5. controlplane/telemetry/internal/geoprobe/signer_test.go (~100-120 lines)

   • TestSignOffset_Success - sign and verify valid offset
   • TestVerifyOffset_InvalidSignature - tampered data detection
   • TestVerifyOffset_WrongPublicKey - signature from wrong keypair
   • TestSignOffset_WithReferences - sign offset containing reference chain
   • TestVerifyOffset_ChainValidation - validate entire DZD→Probe chain

No Existing Files Modified

This is a greenfield package with no modifications to existing code.

Technical Details

LocationOffset Structure

Based on RFC16, the Go struct will be:

type LocationOffset struct {
    Signature       [64]byte         // Ed25519 signature
    Pubkey          [32]byte         // Signer's public key
    MeasurementSlot uint64           // Current DoubleZero Slot
    Lat             float64          // Reference point latitude (WGS84)
    Lng             float64          // Reference point longitude (WGS84)
    MeasuredRttNs   uint64           // Measured RTT in nanoseconds
    RttNs           uint64           // Accumulated RTT to target in ns
    NumReferences   uint8            // Number of reference offsets
    References      []LocationOffset // Reference offsets (recursive)
}

Serialization Format

Use Borsh encoding via github.com/gagliardetto/binary for consistency with existing telemetry code. The signing bytes will be the serialized form of all fields except the Signature field itself (following standard practice where signatures are computed over unsigned data).

Signing Process

1. Create LocationOffset with all fields populated except Signature
2. Serialize the offset (excluding the Signature field)
3. Sign the serialized bytes using Ed25519 with the signer's private key
4. Populate the Signature field with the resulting 64-byte signature
5. Transmit the complete signed offset

Verification Process

1. Extract the Signature and Pubkey from received offset
2. Serialize the offset (excluding Signature field)
3. Verify the signature using Ed25519 with the extracted public key
4. For chain verification, recursively verify all References

Risks & Considerations

1. Serialization Format Compatibility: Using Borsh encoding ensures consistency with existing telemetry code, but we need to ensure the format is stable for network transmission between different binaries.

   • Mitigation: Follow exact patterns from smartcontract/sdk/go/telemetry/state.go

2. Signature Field Ordering: The signature must be computed over consistent bytes regardless of where it's stored in the struct.

   • Mitigation: Clearly document that signing excludes the Signature field, following standard cryptographic practice

3. UDP Packet Size: LocationOffset with nested references could exceed typical UDP MTU (1500 bytes).

   • Mitigation: RFC specifies this is acceptable for Phase 1 POC. Future work may add fragmentation if needed
   • For reference: each LocationOffset is ~240 bytes; 5-level chain = ~1200 bytes (within MTU)

4. Reference Chain Depth: Unlimited recursion in References could cause stack overflow.

   • Mitigation: For Phase 1 POC, chains will be shallow (DZD→Probe→Target = 2 levels max). Add depth validation in future work if needed

5. Endianness: Binary serialization must be consistent across all platforms.

   • Mitigation: Borsh encoding uses little-endian by default, which matches the existing codebase

Testing Strategy

Unit Tests

1. Serialization Tests:

   • Marshal/unmarshal round-trip with various field values
   • Empty references vs non-empty references
   • Large reference chains (stress test)
   • Invalid data handling

2. Signing Tests:

   • Sign offset, verify succeeds
   • Modify signed data, verify fails
   • Wrong public key, verify fails
   • Reference chain signature validation

3. Integration Tests (not in this issue, but planned):

   • UDP send/receive round-trip (requires actual network stack)
   • Multi-process communication tests

Test Data

Use realistic values from RFC examples:

• Lat/Lng: Amsterdam (52.3676°N, 4.9041°E)
• RTT: 0.8ms = 800,000 ns (DZD to Probe)
• RTT: 12.5ms = 12,500,000 ns (cumulative to target)
• MeasurementSlot: realistic epoch values

Estimated Scope

Small-to-Medium (~250-300 lines total including tests)

Breakdown:

• Production code: ~200-240 lines across 3 files
• Test code: ~180-220 lines across 2 test files
• Total: ~380-460 lines

This is a foundational library with no external dependencies beyond what's already in go.mod. Implementation should be straightforward following existing patterns.

Dependencies

Upstream: None - this is the foundation issue for Phase 1

Downstream: The following issues will depend on this package:

• Telemetry agent extensions (DZD→Probe measurements)
• geoprobe-agent implementation (Probe→Target measurements)
• geoprobe-target test tool (receive and log offsets)

Open Questions

None at this time. The RFC16 specification is clear and complete for this component.

Acceptance Criteria

1. ✅ LocationOffset struct matches RFC16 specification exactly
2. ✅ Marshal/unmarshal methods work correctly for all field types
3. ✅ Ed25519 signing using Solana keypairs works correctly
4. ✅ Signature verification detects tampered data
5. ✅ Reference chain serialization works with nested offsets
6. ✅ UDP transport helpers can send/receive offsets
7. ✅ All unit tests pass with >90% coverage
8. ✅ Code follows existing doublezero Go conventions
9. ✅ No external dependencies added (all use existing go.mod packages)

Implementation Notes

• Follow naming conventions from existing telemetry code
• Use github.com/gagliardetto/solana-go for keypair operations
• Use github.com/gagliardetto/binary for Borsh serialization
• Use github.com/stretchr/testify/require for test assertions
• No need to add entries to CHANGELOG.md yet (wait until full feature is complete)
• No need to update CLAUDE.md (no new conventions introduced)

[ben-dz]

See Commit 26777a1 on branch https://github.com/malbeclabs/doublezero/tree/feature/geolocation