doublezero-serviceability 0.0.2__py3-none-any.whl

serviceability/tests/test_compat.py

@@ -0,0 +1,145 @@
+"""Mainnet compatibility tests.
+
+These tests fetch live mainnet-beta data and verify that our struct
+deserialization works against real on-chain accounts.
+
+Run with:
+    SERVICEABILITY_COMPAT_TEST=1 cd sdk/serviceability/python && uv run pytest -k compat -v
+
+Requires network access to Solana mainnet RPC.
+"""
+
+import os
+import struct
+
+import pytest
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from serviceability.config import PROGRAM_IDS, LEDGER_RPC_URLS
+from serviceability.pda import (
+    derive_global_config_pda,
+    derive_global_state_pda,
+    derive_program_config_pda,
+)
+from serviceability.state import GlobalConfig, GlobalState, ProgramConfig
+
+
+def skip_unless_compat() -> None:
+    if not os.environ.get("SERVICEABILITY_COMPAT_TEST"):
+        pytest.skip("set SERVICEABILITY_COMPAT_TEST=1 to run compatibility tests against mainnet")
+
+
+def _rpc_url() -> str:
+    return os.environ.get("SOLANA_RPC_URL", LEDGER_RPC_URLS["mainnet-beta"])
+
+
+def _program_id() -> Pubkey:
+    return Pubkey.from_string(PROGRAM_IDS["mainnet-beta"])
+
+
+def fetch_raw_account(addr: Pubkey) -> bytes:
+    from serviceability.rpc import new_rpc_client
+
+    rpc = new_rpc_client(_rpc_url())
+    resp = rpc.get_account_info(addr)
+    assert resp.value is not None, f"account not found: {addr}"
+    return bytes(resp.value.data)
+
+
+def read_u8(raw: bytes, offset: int) -> int:
+    return raw[offset]
+
+
+def read_u16(raw: bytes, offset: int) -> int:
+    return struct.unpack_from("<H", raw, offset)[0]
+
+
+def read_u32(raw: bytes, offset: int) -> int:
+    return struct.unpack_from("<I", raw, offset)[0]
+
+
+def read_pubkey(raw: bytes, offset: int) -> Pubkey:
+    return Pubkey.from_bytes(raw[offset : offset + 32])
+
+
+class TestCompatProgramConfig:
+    def test_deserialize(self) -> None:
+        skip_unless_compat()
+
+        program_id = _program_id()
+        addr, _ = derive_program_config_pda(program_id)
+        raw = fetch_raw_account(addr)
+
+        pc = ProgramConfig.from_bytes(raw)
+
+        # ProgramConfig layout (all fixed-size):
+        # offset 0: AccountType (u8)
+        # offset 1: BumpSeed (u8)
+        # offset 2: Version.Major (u32)
+        # offset 6: Version.Minor (u32)
+        # offset 10: Version.Patch (u32)
+        # offset 14: MinCompatVersion.Major (u32)
+        # offset 18: MinCompatVersion.Minor (u32)
+        # offset 22: MinCompatVersion.Patch (u32)
+        assert pc.account_type == read_u8(raw, 0), "AccountType"
+        assert pc.bump_seed == read_u8(raw, 1), "BumpSeed"
+        assert pc.version.major == read_u32(raw, 2), "Version.Major"
+        assert pc.version.minor == read_u32(raw, 6), "Version.Minor"
+        assert pc.version.patch == read_u32(raw, 10), "Version.Patch"
+        assert pc.min_compat_version.major == read_u32(raw, 14), "MinCompatVersion.Major"
+        assert pc.min_compat_version.minor == read_u32(raw, 18), "MinCompatVersion.Minor"
+        assert pc.min_compat_version.patch == read_u32(raw, 22), "MinCompatVersion.Patch"
+
+        assert pc.account_type == 9
+
+
+class TestCompatGlobalConfig:
+    def test_deserialize(self) -> None:
+        skip_unless_compat()
+
+        program_id = _program_id()
+        addr, _ = derive_global_config_pda(program_id)
+        raw = fetch_raw_account(addr)
+
+        gc = GlobalConfig.from_bytes(raw)
+
+        # GlobalConfig layout (all fixed-size):
+        # offset 0: AccountType (u8)
+        # offset 1: Owner (32 bytes)
+        # offset 33: BumpSeed (u8)
+        # offset 34: LocalASN (u32)
+        # offset 38: RemoteASN (u32)
+        # offset 57: NextBGPCommunity (u16)
+        assert gc.account_type == read_u8(raw, 0), "AccountType"
+        assert gc.owner == read_pubkey(raw, 1), "Owner"
+        assert gc.bump_seed == read_u8(raw, 33), "BumpSeed"
+        assert gc.local_asn == read_u32(raw, 34), "LocalASN"
+        assert gc.remote_asn == read_u32(raw, 38), "RemoteASN"
+        assert gc.next_bgp_community == read_u16(raw, 57), "NextBGPCommunity"
+
+        assert gc.account_type == 2
+        assert gc.local_asn > 0, "LocalASN should be > 0 on mainnet"
+
+
+class TestCompatGlobalState:
+    def test_deserialize(self) -> None:
+        skip_unless_compat()
+
+        program_id = _program_id()
+        addr, _ = derive_global_state_pda(program_id)
+        raw = fetch_raw_account(addr)
+
+        gs = GlobalState.from_bytes(raw)
+
+        # GlobalState fixed layout (first 18 bytes before variable-length vecs):
+        # offset 0: AccountType (u8)
+        # offset 1: BumpSeed (u8)
+        assert gs.account_type == read_u8(raw, 0), "AccountType"
+        assert gs.bump_seed == read_u8(raw, 1), "BumpSeed"
+
+        assert gs.account_type == 1
+
+        # Sanity checks.
+        assert gs.activator_authority_pk != Pubkey.default(), "ActivatorAuthorityPK is zero"
+        assert gs.sentinel_authority_pk != Pubkey.default(), "SentinelAuthorityPK is zero"
+        # health_oracle_pk may be zero on mainnet

serviceability/tests/test_enum_strings.py

@@ -0,0 +1,110 @@
+"""Test that enum __str__ outputs match the shared fixture file."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from serviceability.state import (
+    AccessPassStatus,
+    AccessPassTypeTag,
+    ContributorStatus,
+    CyoaType,
+    DeviceDesiredStatus,
+    DeviceDeviceType,
+    DeviceHealth,
+    DeviceStatus,
+    ExchangeStatus,
+    InterfaceStatus,
+    InterfaceType,
+    LinkDesiredStatus,
+    LinkHealth,
+    LinkLinkType,
+    LinkStatus,
+    LocationStatus,
+    LoopbackType,
+    MulticastGroupStatus,
+    UserStatus,
+    UserUserType,
+)
+
+FIXTURE_PATH = Path(__file__).resolve().parent.parent.parent.parent / "testdata" / "enum_strings.json"
+
+ENUM_MAP = {
+    "LocationStatus": LocationStatus,
+    "ExchangeStatus": ExchangeStatus,
+    "DeviceDeviceType": DeviceDeviceType,
+    "DeviceStatus": DeviceStatus,
+    "DeviceHealth": DeviceHealth,
+    "DeviceDesiredStatus": DeviceDesiredStatus,
+    "InterfaceStatus": InterfaceStatus,
+    "InterfaceType": InterfaceType,
+    "LoopbackType": LoopbackType,
+    "LinkLinkType": LinkLinkType,
+    "LinkStatus": LinkStatus,
+    "LinkHealth": LinkHealth,
+    "LinkDesiredStatus": LinkDesiredStatus,
+    "ContributorStatus": ContributorStatus,
+    "UserUserType": UserUserType,
+    "CyoaType": CyoaType,
+    "UserStatus": UserStatus,
+    "MulticastGroupStatus": MulticastGroupStatus,
+    "AccessPassTypeTag": AccessPassTypeTag,
+    "AccessPassStatus": AccessPassStatus,
+}
+
+
+def _load_fixture() -> dict:
+    return json.loads(FIXTURE_PATH.read_text())
+
+
+def _enum_test_cases() -> list[tuple[str, int, str]]:
+    """Yield (enum_name, int_value, expected_string) tuples."""
+    fixture = _load_fixture()
+    cases = []
+    for enum_name, mappings in fixture.items():
+        if enum_name not in ENUM_MAP:
+            continue
+        for str_value, expected in mappings.items():
+            cases.append((enum_name, int(str_value), expected))
+    return cases
+
+
+@pytest.mark.parametrize(
+    "enum_name,int_value,expected",
+    _enum_test_cases(),
+    ids=lambda x: str(x),
+)
+def test_enum_str(enum_name: str, int_value: int, expected: str) -> None:
+    enum_cls = ENUM_MAP[enum_name]
+    try:
+        instance = enum_cls(int_value)
+    except ValueError:
+        # Unknown value not defined as a member; skip since Python IntEnum
+        # cannot instantiate undefined members. Go/TS tests cover this case.
+        pytest.skip(f"{enum_name}({int_value}) is not a valid member")
+        return
+    assert str(instance) == expected, (
+        f"{enum_name}({int_value}): expected {expected!r}, got {str(instance)!r}"
+    )
+
+
+def test_all_enum_members_in_fixture() -> None:
+    """Every Python IntEnum member must appear in the fixture.
+
+    This catches the case where a variant is added in Python but not in
+    enum_strings.json. Since the fixture is shared across Go, Python, and
+    TypeScript, updating it will cause the other languages' tests to fail
+    until they add the new variant too.
+    """
+    fixture = _load_fixture()
+    missing = []
+    for enum_name, enum_cls in ENUM_MAP.items():
+        fixture_values = fixture.get(enum_name, {})
+        for member in enum_cls:
+            if str(member.value) not in fixture_values:
+                missing.append(f"{enum_name}.{member.name} ({member.value})")
+    assert not missing, (
+        "Enum members missing from enum_strings.json fixture — add them so "
+        "other languages stay in sync:\n  " + "\n  ".join(missing)
+    )

serviceability/tests/test_fixtures.py

@@ -0,0 +1,330 @@
+"""Fixture-based compatibility tests."""
+
+import json
+from pathlib import Path
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from serviceability.state import (
+    AccessPass,
+    Contributor,
+    Device,
+    Exchange,
+    GlobalConfig,
+    GlobalState,
+    Link,
+    Location,
+    MulticastGroup,
+    ProgramConfig,
+    User,
+)
+
+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!r}, got {actual!r}"
+        elif typ == "bool":
+            expected = raw == "true"
+            assert actual == expected, f"{name}: expected {expected}, got {actual}"
+        elif typ == "ipv4":
+            import ipaddress
+
+            expected_bytes = ipaddress.IPv4Address(raw).packed
+            assert actual == expected_bytes, f"{name}: expected {raw}, got {actual}"
+        elif typ == "networkv4":
+            import ipaddress
+
+            net = ipaddress.IPv4Network(raw)
+            expected_bytes = net.network_address.packed + bytes([net.prefixlen])
+            assert actual == expected_bytes, f"{name}: expected {raw}, got {actual}"
+        elif typ == "u128":
+            assert actual == int(raw), f"{name}: expected {raw}, got {actual}"
+
+
+class TestFixtureGlobalState:
+    def test_deserialize(self):
+        data, meta = _load_fixture("global_state")
+        gs = GlobalState.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": gs.account_type,
+                "BumpSeed": gs.bump_seed,
+                "ContributorAirdropLamports": gs.contributor_airdrop_lamports,
+                "UserAirdropLamports": gs.user_airdrop_lamports,
+                "ActivatorAuthorityPk": gs.activator_authority_pk,
+                "SentinelAuthorityPk": gs.sentinel_authority_pk,
+                "HealthOraclePk": gs.health_oracle_pk,
+            },
+        )
+
+
+class TestFixtureGlobalConfig:
+    def test_deserialize(self):
+        data, meta = _load_fixture("global_config")
+        gc = GlobalConfig.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": gc.account_type,
+                "Owner": gc.owner,
+                "BumpSeed": gc.bump_seed,
+                "LocalAsn": gc.local_asn,
+                "RemoteAsn": gc.remote_asn,
+                "NextBgpCommunity": gc.next_bgp_community,
+            },
+        )
+
+
+class TestFixtureLocation:
+    def test_deserialize(self):
+        data, meta = _load_fixture("location")
+        loc = Location.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": loc.account_type,
+                "Owner": loc.owner,
+                "BumpSeed": loc.bump_seed,
+                "LocId": loc.loc_id,
+                "Status": loc.status,
+                "ReferenceCount": loc.reference_count,
+            },
+        )
+
+
+class TestFixtureExchange:
+    def test_deserialize(self):
+        data, meta = _load_fixture("exchange")
+        ex = Exchange.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": ex.account_type,
+                "Owner": ex.owner,
+                "BumpSeed": ex.bump_seed,
+                "BgpCommunity": ex.bgp_community,
+                "Status": ex.status,
+                "ReferenceCount": ex.reference_count,
+                "Device1Pk": ex.device1_pk,
+                "Device2Pk": ex.device2_pk,
+            },
+        )
+
+
+class TestFixtureDevice:
+    def test_deserialize(self):
+        data, meta = _load_fixture("device")
+        dev = Device.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": dev.account_type,
+                "Owner": dev.owner,
+                "Index": dev.index,
+                "BumpSeed": dev.bump_seed,
+                "DeviceType": dev.device_type,
+                "PublicIp": dev.public_ip,
+                "Status": dev.status,
+                "Code": dev.code,
+                "MgmtVrf": dev.mgmt_vrf,
+                "ReferenceCount": dev.reference_count,
+                "UsersCount": dev.users_count,
+                "MaxUsers": dev.max_users,
+                "DeviceHealth": dev.device_health,
+                "DesiredStatus": dev.device_desired_status,
+                "MetricsPublisherPk": dev.metrics_publisher_pub_key,
+                "ContributorPk": dev.contributor_pub_key,
+            },
+        )
+        # Verify interfaces
+        assert len(dev.interfaces) == 2
+        assert dev.interfaces[0].name == "Loopback0"
+        assert dev.interfaces[1].name == "Ethernet1"
+        # Verify dz_prefixes
+        import ipaddress
+
+        assert len(dev.dz_prefixes) == 1
+        net = ipaddress.IPv4Network("10.10.0.0/24")
+        expected_prefix = net.network_address.packed + bytes([net.prefixlen])
+        assert dev.dz_prefixes[0] == expected_prefix
+        # Verify code, mgmt_vrf, public_ip, index
+        assert dev.code == "dz1"
+        assert dev.mgmt_vrf == "mgmt"
+        assert dev.public_ip == ipaddress.IPv4Address("203.0.113.1").packed
+        assert dev.index == 7
+
+
+class TestFixtureLink:
+    def test_deserialize(self):
+        data, meta = _load_fixture("link")
+        lk = Link.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": lk.account_type,
+                "Owner": lk.owner,
+                "BumpSeed": lk.bump_seed,
+                "LinkType": lk.link_type,
+                "Bandwidth": lk.bandwidth,
+                "Mtu": lk.mtu,
+                "DelayNs": lk.delay_ns,
+                "JitterNs": lk.jitter_ns,
+                "TunnelId": lk.tunnel_id,
+                "Status": lk.status,
+                "ContributorPk": lk.contributor_pub_key,
+                "DelayOverrideNs": lk.delay_override_ns,
+                "LinkHealth": lk.link_health,
+                "DesiredStatus": lk.link_desired_status,
+            },
+        )
+
+
+class TestFixtureUser:
+    def test_deserialize(self):
+        data, meta = _load_fixture("user")
+        u = User.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": u.account_type,
+                "Owner": u.owner,
+                "BumpSeed": u.bump_seed,
+                "UserType": u.user_type,
+                "TenantPk": u.tenant_pub_key,
+                "DevicePk": u.device_pub_key,
+                "CyoaType": u.cyoa_type,
+                "TunnelId": u.tunnel_id,
+                "Status": u.status,
+                "ValidatorPubkey": u.validator_pub_key,
+            },
+        )
+
+
+class TestFixtureMulticastGroup:
+    def test_deserialize(self):
+        data, meta = _load_fixture("multicast_group")
+        mg = MulticastGroup.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": mg.account_type,
+                "Owner": mg.owner,
+                "BumpSeed": mg.bump_seed,
+                "TenantPk": mg.tenant_pub_key,
+                "MaxBandwidth": mg.max_bandwidth,
+                "Status": mg.status,
+                "PublisherCount": mg.publisher_count,
+                "SubscriberCount": mg.subscriber_count,
+            },
+        )
+
+
+class TestFixtureContributor:
+    def test_deserialize(self):
+        data, meta = _load_fixture("contributor")
+        c = Contributor.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": c.account_type,
+                "Owner": c.owner,
+                "BumpSeed": c.bump_seed,
+                "Status": c.status,
+                "ReferenceCount": c.reference_count,
+                "OpsManagerPk": c.ops_manager_pk,
+            },
+        )
+
+
+class TestFixtureProgramConfig:
+    def test_deserialize(self):
+        data, meta = _load_fixture("program_config")
+        pc = ProgramConfig.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": pc.account_type,
+                "BumpSeed": pc.bump_seed,
+                "VersionMajor": pc.version.major,
+                "VersionMinor": pc.version.minor,
+                "VersionPatch": pc.version.patch,
+            },
+        )
+
+
+class TestFixtureAccessPass:
+    def test_deserialize(self):
+        data, meta = _load_fixture("access_pass")
+        ap = AccessPass.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": ap.account_type,
+                "Owner": ap.owner,
+                "BumpSeed": ap.bump_seed,
+                "AccessPassType": ap.access_pass_type_tag,
+                "UserPayer": ap.user_payer,
+                "LastAccessEpoch": ap.last_access_epoch,
+                "ConnectionCount": ap.connection_count,
+                "Status": ap.status,
+                "Flags": ap.flags,
+            },
+        )
+
+
+class TestFixtureAccessPassValidator:
+    def test_deserialize(self):
+        data, meta = _load_fixture("access_pass_validator")
+        ap = AccessPass.from_bytes(data)
+        _assert_fields(
+            meta["fields"],
+            {
+                "AccountType": ap.account_type,
+                "Owner": ap.owner,
+                "BumpSeed": ap.bump_seed,
+                "AccessPassType": ap.access_pass_type_tag,
+                "AccessPassTypeValidatorPubkey": ap.validator_pub_key,
+                "ClientIp": ap.client_ip,
+                "UserPayer": ap.user_payer,
+                "LastAccessEpoch": ap.last_access_epoch,
+                "ConnectionCount": ap.connection_count,
+                "Status": ap.status,
+                "Flags": ap.flags,
+            },
+        )
+        assert ap.account_type == 11
+        assert ap.bump_seed == 243
+        assert ap.access_pass_type_tag == 1
+        assert ap.validator_pub_key == Pubkey.from_string(
+            "BuP3jEYfnTCfB4UqQk9L37k2vaXsNuVsbWxrYbGDmL6s"
+        )
+        import ipaddress
+
+        assert ap.client_ip == ipaddress.IPv4Address("10.0.0.50").packed
+        assert ap.last_access_epoch == 1000
+        assert ap.connection_count == 1
+        assert ap.status == 1
+        assert len(ap.mgroup_pub_allowlist) == 1
+        assert len(ap.mgroup_sub_allowlist) == 1
+        assert ap.flags == 3

serviceability/tests/test_pda.py

@@ -0,0 +1,36 @@
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from serviceability.pda import (
+    derive_global_config_pda,
+    derive_global_state_pda,
+    derive_program_config_pda,
+)
+
+PROGRAM_ID = Pubkey.from_string("ser2VaTMAcYTaauMrTSfSrxBaUDq7BLNs2xfUugTAGv")
+
+
+def test_derive_global_state_pda():
+    addr, bump = derive_global_state_pda(PROGRAM_ID)
+    assert addr != Pubkey.default()
+    addr2, bump2 = derive_global_state_pda(PROGRAM_ID)
+    assert addr == addr2
+    assert bump == bump2
+
+
+def test_derive_global_config_pda():
+    addr, _ = derive_global_config_pda(PROGRAM_ID)
+    assert addr != Pubkey.default()
+
+
+def test_derive_program_config_pda():
+    addr, _ = derive_program_config_pda(PROGRAM_ID)
+    assert addr != Pubkey.default()
+
+
+def test_pdas_are_different():
+    gs, _ = derive_global_state_pda(PROGRAM_ID)
+    gc, _ = derive_global_config_pda(PROGRAM_ID)
+    pc, _ = derive_program_config_pda(PROGRAM_ID)
+    assert gs != gc
+    assert gs != pc
+    assert gc != pc