doublezero-telemetry 0.0.2__py3-none-any.whl

doublezero_telemetry-0.0.2.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: doublezero-telemetry
+Version: 0.0.2
+Summary: DoubleZero Telemetry SDK
+Requires-Python: >=3.10
+Requires-Dist: borsh-incremental
+Requires-Dist: httpx>=0.27
+Requires-Dist: solana>=0.35
+Requires-Dist: solders>=0.21

doublezero_telemetry-0.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+telemetry/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+telemetry/client.py,sha256=gImIz7ozpXb87wfYMQrKVplakQ1CSLYvNKZXgAYYf9o,2728
+telemetry/config.py,sha256=Vhn6wJjhEsODjGOGXll_ypZQstwHqYdb-9huG6pWs0Y,685
+telemetry/pda.py,sha256=vlentmvAFyvRLYbS65pGxY7oqSCkbHjn8hrwjVaIK28,1416
+telemetry/rpc.py,sha256=G7GPRl0DM3x3p6B3NTdIgjDJTljwCat9-C_XKL5wXwM,1548
+telemetry/state.py,sha256=J0dHUKLG6-AZTnRrEjRRuGm3ACX9tPFoB8POrjsKQFM,4603
+telemetry/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+telemetry/tests/test_fixtures.py,sha256=2cDoa5pGcKziDR-eNhrtJ-XCuRMexvnYiv402De-ClU,2985
+telemetry/tests/test_pda.py,sha256=zFzEWbw_UVEppL4W75Lquf3t_4Sob3cbXo0l2Ow3hvM,1340
+doublezero_telemetry-0.0.2.dist-info/METADATA,sha256=6kIU1xJN0nPwcN4oL0MbBuKZuHPFZUl-nntJSN2yCig,239
+doublezero_telemetry-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+doublezero_telemetry-0.0.2.dist-info/RECORD,,

doublezero_telemetry-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

telemetry/client.py

@@ -0,0 +1,92 @@
+"""RPC client for fetching telemetry program accounts."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+from solders.rpc.responses import GetAccountInfoResp  # type: ignore[import-untyped]
+
+from telemetry.config import PROGRAM_IDS, LEDGER_RPC_URLS
+from telemetry.rpc import new_rpc_client
+from telemetry.pda import (
+    derive_device_latency_samples_pda,
+    derive_internet_latency_samples_pda,
+)
+from telemetry.state import DeviceLatencySamples, InternetLatencySamples
+
+
+class SolanaClient(Protocol):
+    def get_account_info(self, pubkey: Pubkey) -> GetAccountInfoResp: ...
+
+
+class Client:
+    """Read-only client for telemetry program accounts."""
+
+    def __init__(
+        self,
+        solana_rpc: SolanaClient,
+        program_id: Pubkey,
+    ) -> None:
+        self._solana_rpc = solana_rpc
+        self._program_id = program_id
+
+    @classmethod
+    def from_env(cls, env: str) -> Client:
+        """Create a client configured for the given environment.
+
+        Args:
+            env: Environment name ("mainnet-beta", "testnet", "devnet", "localnet")
+        """
+        return cls(
+            new_rpc_client(LEDGER_RPC_URLS[env]),
+            Pubkey.from_string(PROGRAM_IDS[env]),
+        )
+
+    @classmethod
+    def mainnet_beta(cls) -> Client:
+        return cls.from_env("mainnet-beta")
+
+    @classmethod
+    def testnet(cls) -> Client:
+        return cls.from_env("testnet")
+
+    @classmethod
+    def devnet(cls) -> Client:
+        return cls.from_env("devnet")
+
+    @classmethod
+    def localnet(cls) -> Client:
+        return cls.from_env("localnet")
+
+    def get_device_latency_samples(
+        self,
+        origin_device_pk: Pubkey,
+        target_device_pk: Pubkey,
+        link_pk: Pubkey,
+        epoch: int,
+    ) -> DeviceLatencySamples:
+        addr, _ = derive_device_latency_samples_pda(
+            self._program_id, origin_device_pk, target_device_pk, link_pk, epoch
+        )
+        resp = self._solana_rpc.get_account_info(addr)
+        return DeviceLatencySamples.from_bytes(resp.value.data)
+
+    def get_internet_latency_samples(
+        self,
+        collector_oracle_pk: Pubkey,
+        data_provider_name: str,
+        origin_location_pk: Pubkey,
+        target_location_pk: Pubkey,
+        epoch: int,
+    ) -> InternetLatencySamples:
+        addr, _ = derive_internet_latency_samples_pda(
+            self._program_id,
+            collector_oracle_pk,
+            data_provider_name,
+            origin_location_pk,
+            target_location_pk,
+            epoch,
+        )
+        resp = self._solana_rpc.get_account_info(addr)
+        return InternetLatencySamples.from_bytes(resp.value.data)

telemetry/config.py

@@ -0,0 +1,15 @@
+"""Network configuration for the telemetry program."""
+
+PROGRAM_IDS = {
+    "mainnet-beta": "tE1exJ5VMyoC9ByZeSmgtNzJCFF74G9JAv338sJiqkC",
+    "testnet": "3KogTMmVxc5eUHtjZnwm136H5P8tvPwVu4ufbGPvM7p1",
+    "devnet": "C9xqH76NSm11pBS6maNnY163tWHT8Govww47uyEmSnoG",
+    "localnet": "C9xqH76NSm11pBS6maNnY163tWHT8Govww47uyEmSnoG",
+}
+
+LEDGER_RPC_URLS = {
+    "mainnet-beta": "https://doublezero-mainnet-beta.rpcpool.com/db336024-e7a8-46b1-80e5-352dd77060ab",
+    "testnet": "https://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16",
+    "devnet": "https://doublezerolocalnet.rpcpool.com/8a4fd3f4-0977-449f-88c7-63d4b0f10f16",
+    "localnet": "http://localhost:8899",
+}

telemetry/pda.py

@@ -0,0 +1,55 @@
+"""PDA derivation for telemetry program accounts."""
+
+import struct
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from telemetry.state import (
+    TELEMETRY_SEED_PREFIX,
+    DEVICE_LATENCY_SAMPLES_SEED,
+    INTERNET_LATENCY_SAMPLES_SEED,
+)
+
+
+def derive_device_latency_samples_pda(
+    program_id: Pubkey,
+    origin_device_pk: Pubkey,
+    target_device_pk: Pubkey,
+    link_pk: Pubkey,
+    epoch: int,
+) -> tuple[Pubkey, int]:
+    epoch_bytes = struct.pack("<Q", epoch)
+    return Pubkey.find_program_address(
+        [
+            TELEMETRY_SEED_PREFIX,
+            DEVICE_LATENCY_SAMPLES_SEED,
+            bytes(origin_device_pk),
+            bytes(target_device_pk),
+            bytes(link_pk),
+            epoch_bytes,
+        ],
+        program_id,
+    )
+
+
+def derive_internet_latency_samples_pda(
+    program_id: Pubkey,
+    collector_oracle_pk: Pubkey,
+    data_provider_name: str,
+    origin_location_pk: Pubkey,
+    target_location_pk: Pubkey,
+    epoch: int,
+) -> tuple[Pubkey, int]:
+    epoch_bytes = struct.pack("<Q", epoch)
+    return Pubkey.find_program_address(
+        [
+            TELEMETRY_SEED_PREFIX,
+            INTERNET_LATENCY_SAMPLES_SEED,
+            bytes(collector_oracle_pk),
+            data_provider_name.encode("utf-8"),
+            bytes(origin_location_pk),
+            bytes(target_location_pk),
+            epoch_bytes,
+        ],
+        program_id,
+    )

telemetry/rpc.py

@@ -0,0 +1,48 @@
+"""RPC client helpers with retry on rate limiting."""
+
+import time
+
+import httpx
+from solana.rpc.api import Client as SolanaHTTPClient  # type: ignore[import-untyped]
+
+_DEFAULT_MAX_RETRIES = 5
+
+
+class _RetryTransport(httpx.BaseTransport):
+    """HTTP transport that retries on 429 Too Many Requests."""
+
+    def __init__(
+        self,
+        wrapped: httpx.BaseTransport | None = None,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._wrapped = wrapped or httpx.HTTPTransport()
+        self._max_retries = max_retries
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            response = self._wrapped.handle_request(request)
+            if response.status_code != 429 or attempt >= self._max_retries:
+                return response
+            response.close()
+            time.sleep((attempt + 1) * 2)
+        return response  # unreachable, but satisfies type checker
+
+
+def new_rpc_client(
+    url: str,
+    timeout: float = 30,
+    max_retries: int = _DEFAULT_MAX_RETRIES,
+) -> SolanaHTTPClient:
+    """Create a Solana RPC client with automatic retry on 429 responses."""
+    client = SolanaHTTPClient(url, timeout=timeout)
+    # Replace the underlying httpx session with one using retry transport.
+    transport = _RetryTransport(
+        wrapped=httpx.HTTPTransport(),
+        max_retries=max_retries,
+    )
+    client._provider.session = httpx.Client(
+        timeout=timeout,
+        transport=transport,
+    )
+    return client

telemetry/state.py

@@ -0,0 +1,141 @@
+"""On-chain account data structures for the telemetry program.
+
+Binary layout: 1-byte AccountType discriminator followed by Borsh-serialized
+header fields, then raw u32 LE sample values (not a Borsh Vec — count is
+determined by next_sample_index).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from borsh_incremental import IncrementalReader
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+
+TELEMETRY_SEED_PREFIX = b"telemetry"
+DEVICE_LATENCY_SAMPLES_SEED = b"dzlatency"
+INTERNET_LATENCY_SAMPLES_SEED = b"inetlatency"
+
+MAX_DEVICE_LATENCY_SAMPLES_PER_ACCOUNT = 35_000
+MAX_INTERNET_LATENCY_SAMPLES_PER_ACCOUNT = 3_000
+
+DEVICE_LATENCY_HEADER_SIZE = 1 + 8 + 32 * 6 + 8 + 8 + 4 + 128
+
+
+def _read_pubkey(r: IncrementalReader) -> Pubkey:
+    return Pubkey.from_bytes(r.read_pubkey_raw())
+
+
+@dataclass
+class DeviceLatencySamples:
+    account_type: int
+    epoch: int
+    origin_device_agent_pk: Pubkey
+    origin_device_pk: Pubkey
+    target_device_pk: Pubkey
+    origin_device_location_pk: Pubkey
+    target_device_location_pk: Pubkey
+    link_pk: Pubkey
+    sampling_interval_microseconds: int
+    start_timestamp_microseconds: int
+    next_sample_index: int
+    samples: list[int] = field(default_factory=list)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> DeviceLatencySamples:
+        if len(data) < DEVICE_LATENCY_HEADER_SIZE:
+            raise ValueError(
+                f"data too short for device latency header: {len(data)} < {DEVICE_LATENCY_HEADER_SIZE}"
+            )
+
+        r = IncrementalReader(data)
+
+        account_type = r.read_u8()
+        epoch = r.read_u64()
+        origin_device_agent_pk = _read_pubkey(r)
+        origin_device_pk = _read_pubkey(r)
+        target_device_pk = _read_pubkey(r)
+        origin_device_location_pk = _read_pubkey(r)
+        target_device_location_pk = _read_pubkey(r)
+        link_pk = _read_pubkey(r)
+        sampling_interval = r.read_u64()
+        start_timestamp = r.read_u64()
+        next_sample_index = r.read_u32()
+
+        r.read_bytes(128)  # reserved
+
+        count = min(next_sample_index, MAX_DEVICE_LATENCY_SAMPLES_PER_ACCOUNT)
+        samples: list[int] = []
+        for _ in range(count):
+            if r.remaining < 4:
+                break
+            samples.append(r.read_u32())
+
+        return cls(
+            account_type=account_type,
+            epoch=epoch,
+            origin_device_agent_pk=origin_device_agent_pk,
+            origin_device_pk=origin_device_pk,
+            target_device_pk=target_device_pk,
+            origin_device_location_pk=origin_device_location_pk,
+            target_device_location_pk=target_device_location_pk,
+            link_pk=link_pk,
+            sampling_interval_microseconds=sampling_interval,
+            start_timestamp_microseconds=start_timestamp,
+            next_sample_index=next_sample_index,
+            samples=samples,
+        )
+
+
+@dataclass
+class InternetLatencySamples:
+    account_type: int
+    epoch: int
+    data_provider_name: str
+    oracle_agent_pk: Pubkey
+    origin_exchange_pk: Pubkey
+    target_exchange_pk: Pubkey
+    sampling_interval_microseconds: int
+    start_timestamp_microseconds: int
+    next_sample_index: int
+    samples: list[int] = field(default_factory=list)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> InternetLatencySamples:
+        if len(data) < 10:
+            raise ValueError("data too short")
+
+        r = IncrementalReader(data)
+
+        account_type = r.read_u8()
+        epoch = r.read_u64()
+        data_provider_name = r.read_string()
+        oracle_agent_pk = _read_pubkey(r)
+        origin_exchange_pk = _read_pubkey(r)
+        target_exchange_pk = _read_pubkey(r)
+        sampling_interval = r.read_u64()
+        start_timestamp = r.read_u64()
+        next_sample_index = r.read_u32()
+
+        r.read_bytes(128)  # reserved
+
+        count = min(next_sample_index, MAX_INTERNET_LATENCY_SAMPLES_PER_ACCOUNT)
+        samples: list[int] = []
+        for _ in range(count):
+            if r.remaining < 4:
+                break
+            samples.append(r.read_u32())
+
+        return cls(
+            account_type=account_type,
+            epoch=epoch,
+            data_provider_name=data_provider_name,
+            oracle_agent_pk=oracle_agent_pk,
+            origin_exchange_pk=origin_exchange_pk,
+            target_exchange_pk=target_exchange_pk,
+            sampling_interval_microseconds=sampling_interval,
+            start_timestamp_microseconds=start_timestamp,
+            next_sample_index=next_sample_index,
+            samples=samples,
+        )

telemetry/tests/test_fixtures.py

@@ -0,0 +1,77 @@
+"""Fixture-based compatibility tests."""
+
+import json
+from pathlib import Path
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from telemetry.state import DeviceLatencySamples, InternetLatencySamples
+
+FIXTURES_DIR = Path(__file__).resolve().parent.parent.parent.parent / "testdata" / "fixtures"
+
+
+def _load_fixture(name: str) -> tuple[bytes, dict]:
+    bin_data = (FIXTURES_DIR / f"{name}.bin").read_bytes()
+    meta = json.loads((FIXTURES_DIR / f"{name}.json").read_text())
+    return bin_data, meta
+
+
+def _assert_fields(expected_fields: list[dict], got: dict) -> None:
+    for f in expected_fields:
+        name = f["name"]
+        if name not in got:
+            continue
+        typ = f["typ"]
+        raw = f["value"]
+        actual = got[name]
+        if typ in ("u8", "u16", "u32", "u64"):
+            assert actual == int(raw), f"{name}: expected {raw}, got {actual}"
+        elif typ == "pubkey":
+            expected = Pubkey.from_string(raw)
+            assert actual == expected, f"{name}: expected {expected}, got {actual}"
+        elif typ == "string":
+            assert actual == raw, f"{name}: expected {raw}, got {actual}"
+
+
+class TestFixtureDeviceLatencySamples:
+    def test_deserialize(self):
+        data, meta = _load_fixture("device_latency_samples")
+        d = DeviceLatencySamples.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": d.account_type,
+                "Epoch": d.epoch,
+                "OriginDeviceAgentPK": d.origin_device_agent_pk,
+                "OriginDevicePK": d.origin_device_pk,
+                "TargetDevicePK": d.target_device_pk,
+                "OriginDeviceLocationPK": d.origin_device_location_pk,
+                "TargetDeviceLocationPK": d.target_device_location_pk,
+                "LinkPK": d.link_pk,
+                "SamplingIntervalMicroseconds": d.sampling_interval_microseconds,
+                "StartTimestampMicroseconds": d.start_timestamp_microseconds,
+                "NextSampleIndex": d.next_sample_index,
+                "SamplesCount": len(d.samples),
+            },
+        )
+
+
+class TestFixtureInternetLatencySamples:
+    def test_deserialize(self):
+        data, meta = _load_fixture("internet_latency_samples")
+        d = InternetLatencySamples.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": d.account_type,
+                "Epoch": d.epoch,
+                "DataProviderName": d.data_provider_name,
+                "OracleAgentPK": d.oracle_agent_pk,
+                "OriginExchangePK": d.origin_exchange_pk,
+                "TargetExchangePK": d.target_exchange_pk,
+                "SamplingIntervalMicroseconds": d.sampling_interval_microseconds,
+                "StartTimestampMicroseconds": d.start_timestamp_microseconds,
+                "NextSampleIndex": d.next_sample_index,
+                "SamplesCount": len(d.samples),
+            },
+        )

telemetry/tests/test_pda.py

@@ -0,0 +1,38 @@
+"""PDA derivation tests."""
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from telemetry.pda import (
+    derive_device_latency_samples_pda,
+    derive_internet_latency_samples_pda,
+)
+
+PROGRAM_ID = Pubkey.from_string("tE1exJ5VMyoC9ByZeSmgtNzJCFF74G9JAv338sJiqkC")
+
+
+class TestDeriveDeviceLatencySamplesPDA:
+    def test_deterministic(self):
+        origin = Pubkey.from_string("11111111111111111111111111111112")
+        target = Pubkey.from_string("11111111111111111111111111111113")
+        link = Pubkey.from_string("11111111111111111111111111111114")
+
+        addr1, bump1 = derive_device_latency_samples_pda(
+            PROGRAM_ID, origin, target, link, 42
+        )
+        addr2, bump2 = derive_device_latency_samples_pda(
+            PROGRAM_ID, origin, target, link, 42
+        )
+        assert addr1 == addr2
+        assert bump1 == bump2
+
+
+class TestDeriveInternetLatencySamplesPDA:
+    def test_deterministic(self):
+        oracle = Pubkey.from_string("11111111111111111111111111111112")
+        origin = Pubkey.from_string("11111111111111111111111111111113")
+        target = Pubkey.from_string("11111111111111111111111111111114")
+
+        addr1, _ = derive_internet_latency_samples_pda(
+            PROGRAM_ID, oracle, "RIPE Atlas", origin, target, 42
+        )
+        assert addr1 != Pubkey.default()