Skip to content

telemetry: add timestamp index for latency sample gap correction#3237

Open
snormore wants to merge 1 commit intomainfrom
snor/telemetry-timestamp-index
Open

telemetry: add timestamp index for latency sample gap correction#3237
snormore wants to merge 1 commit intomainfrom
snor/telemetry-timestamp-index

Conversation

@snormore
Copy link
Copy Markdown
Contributor

@snormore snormore commented Mar 11, 2026

Summary of Changes

  • Add a companion TimestampIndex PDA account that records per-write-batch timestamps, enabling accurate wall-clock reconstruction even when agents experience downtime gaps
  • Implement onchain program (new instruction + write-time updates), Go SDK instruction builders, device telemetry and internet latency collector submitters, and read-only deserialization in Go/Python/TypeScript SDKs
  • Include timestamp reconstruction helpers using binary search (single sample, O(log m)) and single-pass cursor (batch, O(n+m)) in all three SDK languages

RFC: rfcs/rfc18-telemetry-write-timestamp-index.md

Closes #877

Diff Breakdown

Category Files Lines (+/-) Net
Core logic 28 +1378 / -7 +1371
Tests 10 +337 / -5 +332
Docs/RFC 2 +232 / -0 +232
Other 1 +5 / -0 +5

~70% core logic, ~17% tests, ~12% RFC/docs. Note: this PR exceeds the ~500-line guideline due to cross-language SDK parity (Go + Python + TypeScript) and the onchain program changes — splitting further would leave incomplete functionality.

Key files (click to expand)
  • smartcontract/programs/doublezero-telemetry/src/state/timestamp_index.rs — New TimestampIndex account type: header struct, serialization, and 10K-entry ring buffer
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/initialize_timestamp_index.rs — New instruction: creates the companion PDA derived from the samples account
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/write_timestamp_index.rs — Appends a (sample_index, timestamp) entry on each write batch
  • smartcontract/programs/doublezero-telemetry/src/processors/telemetry/write_device_latency_samples.rs — Optionally accepts 4th account (timestamp index) for backward compat
  • sdk/telemetry/go/state.go — Go read-only SDK: DeserializeTimestampIndex + ReconstructTimestamp(s)
  • sdk/telemetry/python/telemetry/state.py — Python read-only SDK: TimestampIndex.from_bytes + reconstruct helpers
  • sdk/telemetry/typescript/telemetry/state.ts — TypeScript read-only SDK: deserializeTimestampIndex + reconstruct helpers
  • controlplane/telemetry/internal/telemetry/submitter.go — Device telemetry submitter: derives timestamp index PDA, passes on writes, initializes after new account creation

Testing Verification

  • Rust onchain program tests cover initialization, write-time appending, ring buffer wrap-around, and backward compatibility (writes without timestamp index account)
  • Cross-language fixture tests verify binary compatibility: Rust generates .bin/.json fixtures, Go/Python/TypeScript deserialize and assert field values match
  • Timestamp reconstruction unit tests in all three SDK languages validate binary search, single-pass cursor, entry boundary transitions, and empty-entries fallback

@snormore snormore force-pushed the snor/telemetry-timestamp-index branch 5 times, most recently from eea0f20 to 4b0384c Compare March 21, 2026 14:56
Comment thread smartcontract/programs/doublezero-telemetry/src/error.rs Outdated
@martinsander00
Copy link
Copy Markdown
Contributor

In both submitters, when InitializeTimestampIndex fails, the code logs "writes will proceed without it" but retries the write with TimestampIndexPK` still set

@martinsander00
Copy link
Copy Markdown
Contributor

martinsander00 commented Mar 23, 2026

will approve, not sure if nik or karl want to take a looks since they were involved in the initial convo in #877

@snormore snormore marked this pull request as ready for review March 23, 2026 13:20
@snormore snormore requested review from karl-dz and nikw9944 March 23, 2026 13:20
@snormore snormore force-pushed the snor/telemetry-timestamp-index branch from cbc657b to 32569cd Compare March 24, 2026 23:20
@snormore snormore requested a review from ben-dz March 27, 2026 17:21
Comment thread smartcontract/programs/doublezero-telemetry/src/state/timestamp_index.rs Outdated
Comment thread smartcontract/programs/doublezero-telemetry/tests/timestamp_index_tests.rs Outdated
@snormore snormore force-pushed the snor/telemetry-timestamp-index branch 2 times, most recently from cc8e5f1 to 1c6f316 Compare April 9, 2026 18:34
@snormore snormore force-pushed the snor/telemetry-timestamp-index branch from 1c6f316 to 3a930d3 Compare April 10, 2026 19:23
Add a TimestampIndex account that tracks sample index → timestamp
mappings as a companion to device and internet latency sample accounts.

- New onchain account type (AccountTypeTimestampIndex = 5) with PDA
  derived from samples account PK
- InitializeTimestampIndex and WriteLatencySamples instructions updated
  to optionally append index entries
- Read-only deserialization in Go, Python, and TypeScript SDKs with
  fixture generation and cross-language compat tests
- Timestamp reconstruction helpers using binary search and single-pass
  for efficient sample timestamp lookups
- Timestamp index full condition is non-fatal in write path
@snormore snormore force-pushed the snor/telemetry-timestamp-index branch from 3a930d3 to 7f2746d Compare April 17, 2026 15:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

device/telemetry: consider storing timestamps with samples

3 participants