doublezero-revenue-distribution 0.0.2__tar.gz

doublezero_revenue_distribution-0.0.2/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+uv.lock

doublezero_revenue_distribution-0.0.2/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: doublezero-revenue-distribution
+Version: 0.0.2
+Summary: DoubleZero Revenue Distribution SDK
+Requires-Python: >=3.10
+Requires-Dist: base58>=2.1
+Requires-Dist: borsh-incremental
+Requires-Dist: httpx>=0.27
+Requires-Dist: solana>=0.35
+Requires-Dist: solders>=0.21

doublezero_revenue_distribution-0.0.2/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "doublezero-revenue-distribution"
+version = "0.0.2"
+description = "DoubleZero Revenue Distribution SDK"
+requires-python = ">=3.10"
+dependencies = [
+    "borsh-incremental",
+    "solana>=0.35",
+    "solders>=0.21",
+    "httpx>=0.27",
+    "base58>=2.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["revdist/tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["revdist"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[tool.uv.sources]
+borsh-incremental = { path = "../../borsh-incremental/python", editable = true }

doublezero_revenue_distribution-0.0.2/revdist/__init__.py

@@ -0,0 +1,70 @@
+from revdist.client import Client
+from revdist.config import (
+    LEDGER_RPC_URLS,
+    ORACLE_URLS,
+    PROGRAM_ID,
+    SOLANA_RPC_URLS,
+)
+from revdist.oracle import OracleClient, SwapRate
+from revdist.rpc import new_rpc_client
+from revdist.discriminator import (
+    DISCRIMINATOR_CONTRIBUTOR_REWARDS,
+    DISCRIMINATOR_DISTRIBUTION,
+    DISCRIMINATOR_JOURNAL,
+    DISCRIMINATOR_PROGRAM_CONFIG,
+    DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT,
+)
+from revdist.pda import (
+    derive_config_pda,
+    derive_contributor_rewards_pda,
+    derive_distribution_pda,
+    derive_journal_pda,
+    derive_record_key,
+    derive_reward_share_record_key,
+    derive_validator_debt_record_key,
+    derive_validator_deposit_pda,
+)
+from revdist.state import (
+    ComputedSolanaValidatorDebt,
+    ComputedSolanaValidatorDebts,
+    ContributorRewards,
+    Distribution,
+    Journal,
+    ProgramConfig,
+    RewardShare,
+    ShapleyOutputStorage,
+    SolanaValidatorDeposit,
+)
+
+__all__ = [
+    "Client",
+    "LEDGER_RPC_URLS",
+    "ORACLE_URLS",
+    "OracleClient",
+    "PROGRAM_ID",
+    "SOLANA_RPC_URLS",
+    "SwapRate",
+    "ComputedSolanaValidatorDebt",
+    "ComputedSolanaValidatorDebts",
+    "ContributorRewards",
+    "Distribution",
+    "Journal",
+    "ProgramConfig",
+    "RewardShare",
+    "ShapleyOutputStorage",
+    "SolanaValidatorDeposit",
+    "DISCRIMINATOR_CONTRIBUTOR_REWARDS",
+    "DISCRIMINATOR_DISTRIBUTION",
+    "DISCRIMINATOR_JOURNAL",
+    "DISCRIMINATOR_PROGRAM_CONFIG",
+    "DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT",
+    "derive_config_pda",
+    "derive_contributor_rewards_pda",
+    "derive_distribution_pda",
+    "derive_journal_pda",
+    "derive_record_key",
+    "derive_reward_share_record_key",
+    "derive_validator_debt_record_key",
+    "derive_validator_deposit_pda",
+    "new_rpc_client",
+]

doublezero_revenue_distribution-0.0.2/revdist/client.py

@@ -0,0 +1,189 @@
+"""RPC client for fetching revenue distribution program accounts."""
+
+from __future__ import annotations
+
+import struct
+from typing import Protocol
+
+from solana.rpc.api import Client as SolanaHTTPClient  # type: ignore[import-untyped]
+
+from revdist.rpc import new_rpc_client
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+from solders.rpc.responses import GetAccountInfoResp  # type: ignore[import-untyped]
+
+from revdist.config import LEDGER_RPC_URLS, PROGRAM_ID, SOLANA_RPC_URLS
+from revdist.discriminator import (
+    DISCRIMINATOR_CONTRIBUTOR_REWARDS,
+    DISCRIMINATOR_DISTRIBUTION,
+    DISCRIMINATOR_JOURNAL,
+    DISCRIMINATOR_PROGRAM_CONFIG,
+    DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT,
+)
+from revdist.pda import (
+    RECORD_HEADER_SIZE,
+    derive_config_pda,
+    derive_contributor_rewards_pda,
+    derive_distribution_pda,
+    derive_journal_pda,
+    derive_reward_share_record_key,
+    derive_validator_debt_record_key,
+    derive_validator_deposit_pda,
+)
+from revdist.state import (
+    ComputedSolanaValidatorDebts,
+    ContributorRewards,
+    Distribution,
+    Journal,
+    ProgramConfig,
+    ShapleyOutputStorage,
+    SolanaValidatorDeposit,
+)
+
+
+class SolanaClient(Protocol):
+    def get_account_info(self, pubkey: Pubkey) -> GetAccountInfoResp: ...
+
+
+class Client:
+    """Read-only client for revenue distribution program accounts."""
+
+    def __init__(
+        self,
+        solana_rpc: SolanaClient,
+        ledger_rpc: SolanaClient,
+        program_id: Pubkey,
+    ) -> None:
+        self._solana_rpc = solana_rpc
+        self._ledger_rpc = ledger_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(SOLANA_RPC_URLS[env]),
+            new_rpc_client(LEDGER_RPC_URLS[env]),
+            Pubkey.from_string(PROGRAM_ID),
+        )
+
+    @classmethod
+    def mainnet_beta(cls) -> Client:
+        """Create a client configured for mainnet-beta."""
+        return cls.from_env("mainnet-beta")
+
+    @classmethod
+    def testnet(cls) -> Client:
+        """Create a client configured for testnet."""
+        return cls.from_env("testnet")
+
+    @classmethod
+    def devnet(cls) -> Client:
+        """Create a client configured for devnet."""
+        return cls.from_env("devnet")
+
+    @classmethod
+    def localnet(cls) -> Client:
+        """Create a client configured for localnet."""
+        return cls.from_env("localnet")
+
+    # -- Solana RPC (on-chain accounts) --
+
+    def fetch_config(self) -> ProgramConfig:
+        addr, _ = derive_config_pda(self._program_id)
+        data = self._fetch_solana_account_data(addr)
+        return ProgramConfig.from_bytes(data, DISCRIMINATOR_PROGRAM_CONFIG)
+
+    def fetch_distribution(self, epoch: int) -> Distribution:
+        addr, _ = derive_distribution_pda(self._program_id, epoch)
+        data = self._fetch_solana_account_data(addr)
+        return Distribution.from_bytes(data, DISCRIMINATOR_DISTRIBUTION)
+
+    def fetch_journal(self) -> Journal:
+        addr, _ = derive_journal_pda(self._program_id)
+        data = self._fetch_solana_account_data(addr)
+        return Journal.from_bytes(data, DISCRIMINATOR_JOURNAL)
+
+    def fetch_validator_deposit(
+        self, node_id: Pubkey
+    ) -> SolanaValidatorDeposit:
+        addr, _ = derive_validator_deposit_pda(self._program_id, node_id)
+        data = self._fetch_solana_account_data(addr)
+        return SolanaValidatorDeposit.from_bytes(
+            data, DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT
+        )
+
+    def fetch_contributor_rewards(
+        self, service_key: Pubkey
+    ) -> ContributorRewards:
+        addr, _ = derive_contributor_rewards_pda(self._program_id, service_key)
+        data = self._fetch_solana_account_data(addr)
+        return ContributorRewards.from_bytes(
+            data, DISCRIMINATOR_CONTRIBUTOR_REWARDS
+        )
+
+    def fetch_all_validator_deposits(self) -> list[SolanaValidatorDeposit]:
+        return self._fetch_all_by_discriminator(
+            DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT,
+            SolanaValidatorDeposit,
+        )
+
+    def fetch_all_contributor_rewards(self) -> list[ContributorRewards]:
+        return self._fetch_all_by_discriminator(
+            DISCRIMINATOR_CONTRIBUTOR_REWARDS,
+            ContributorRewards,
+        )
+
+    # -- DZ Ledger RPC (ledger records) --
+
+    def fetch_validator_debts(
+        self, epoch: int
+    ) -> ComputedSolanaValidatorDebts:
+        config = self.fetch_config()
+        addr = derive_validator_debt_record_key(config.debt_accountant_key, epoch)
+        data = self._fetch_ledger_record_data(addr)
+        return ComputedSolanaValidatorDebts.from_bytes(data[RECORD_HEADER_SIZE:])
+
+    def fetch_reward_shares(self, epoch: int) -> ShapleyOutputStorage:
+        config = self.fetch_config()
+        addr = derive_reward_share_record_key(config.rewards_accountant_key, epoch)
+        data = self._fetch_ledger_record_data(addr)
+        return ShapleyOutputStorage.from_bytes(data[RECORD_HEADER_SIZE:])
+
+    # -- Internal helpers --
+
+    def _fetch_solana_account_data(self, addr: Pubkey) -> bytes:
+        resp = self._solana_rpc.get_account_info(addr)
+        if resp.value is None:
+            raise ValueError(f"account not found: {addr}")
+        return bytes(resp.value.data)
+
+    def _fetch_ledger_record_data(self, addr: Pubkey) -> bytes:
+        resp = self._ledger_rpc.get_account_info(addr)
+        if resp.value is None:
+            raise ValueError(f"ledger record not found: {addr}")
+        return bytes(resp.value.data)
+
+    def _fetch_all_by_discriminator(
+        self,
+        disc: bytes,
+        cls: type,
+    ) -> list:
+        from solana.rpc.types import MemcmpOpts  # type: ignore[import-untyped]
+
+        import base58  # type: ignore[import-untyped]
+
+        filters = [MemcmpOpts(offset=0, bytes=base58.b58encode(disc).decode())]
+        resp = self._solana_rpc.get_program_accounts(
+            self._program_id,
+            encoding="base64",
+            filters=filters,
+        )
+        results = []
+        for acct in resp.value:
+            data = bytes(acct.account.data)
+            results.append(cls.from_bytes(data, disc))
+        return results

doublezero_revenue_distribution-0.0.2/revdist/config.py

@@ -0,0 +1,22 @@
+"""Network configuration for the revenue distribution program."""
+
+PROGRAM_ID = "dzrevZC94tBLwuHw1dyynZxaXTWyp7yocsinyEVPtt4"
+
+SOLANA_RPC_URLS = {
+    "mainnet-beta": "https://api.mainnet-beta.solana.com",
+    "testnet": "https://api.testnet.solana.com",
+    "devnet": "https://api.devnet.solana.com",
+    "localnet": "http://localhost:8899",
+}
+
+ORACLE_URLS = {
+    "mainnet-beta": "https://sol-2z-oracle-api-v1.mainnet-beta.doublezero.xyz",
+    "testnet": "https://sol-2z-oracle-api-v1.testnet.doublezero.xyz",
+}
+
+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",
+}

doublezero_revenue_distribution-0.0.2/revdist/discriminator.py

@@ -0,0 +1,31 @@
+import hashlib
+
+DISCRIMINATOR_SIZE = 8
+
+
+def _sha256_first8(s: str) -> bytes:
+    return hashlib.sha256(s.encode()).digest()[:8]
+
+
+DISCRIMINATOR_PROGRAM_CONFIG = _sha256_first8("dz::account::program_config")
+DISCRIMINATOR_DISTRIBUTION = _sha256_first8("dz::account::distribution")
+DISCRIMINATOR_SOLANA_VALIDATOR_DEPOSIT = _sha256_first8(
+    "dz::account::solana_validator_deposit"
+)
+DISCRIMINATOR_CONTRIBUTOR_REWARDS = _sha256_first8(
+    "dz::account::contributor_rewards"
+)
+DISCRIMINATOR_JOURNAL = _sha256_first8("dz::account::journal")
+
+
+def validate_discriminator(data: bytes, expected: bytes) -> None:
+    """Validate the 8-byte discriminator prefix. Raises ValueError on mismatch."""
+    if len(data) < DISCRIMINATOR_SIZE:
+        raise ValueError(
+            f"data too short: {len(data)} bytes, need at least {DISCRIMINATOR_SIZE}"
+        )
+    got = data[:DISCRIMINATOR_SIZE]
+    if got != expected:
+        raise ValueError(
+            f"invalid discriminator: got {got.hex()}, want {expected.hex()}"
+        )

doublezero_revenue_distribution-0.0.2/revdist/oracle.py

@@ -0,0 +1,38 @@
+"""SOL/2Z oracle client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass
+class SwapRate:
+    rate: float
+    timestamp: int
+    signature: str
+    sol_price_usd: str
+    twoz_price_usd: str
+    cache_hit: bool
+
+
+class OracleClient:
+    """Fetches SOL/2Z swap rates from the oracle API."""
+
+    def __init__(self, base_url: str) -> None:
+        self._base_url = base_url
+        self._http = httpx.Client(timeout=30)
+
+    def fetch_swap_rate(self) -> SwapRate:
+        resp = self._http.get(f"{self._base_url}/swap-rate")
+        resp.raise_for_status()
+        data = resp.json()
+        return SwapRate(
+            rate=data["swapRate"],
+            timestamp=data["timestamp"],
+            signature=data["signature"],
+            sol_price_usd=data["solPriceUsd"],
+            twoz_price_usd=data["twozPriceUsd"],
+            cache_hit=data["cacheHit"],
+        )

doublezero_revenue_distribution-0.0.2/revdist/pda.py

@@ -0,0 +1,85 @@
+"""PDA and record key derivation for revenue distribution program accounts."""
+
+import hashlib
+import struct
+
+import base58  # type: ignore[import-untyped]
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+SEED_PROGRAM_CONFIG = b"program_config"
+SEED_DISTRIBUTION = b"distribution"
+SEED_SOLANA_VALIDATOR_DEPOSIT = b"solana_validator_deposit"
+SEED_CONTRIBUTOR_REWARDS = b"contributor_rewards"
+SEED_JOURNAL = b"journal"
+SEED_SOLANA_VALIDATOR_DEBT = b"solana_validator_debt"
+SEED_DZ_CONTRIBUTOR_REWARDS = b"dz_contributor_rewards"
+SEED_SHAPLEY_OUTPUT = b"shapley_output"
+
+RECORD_PROGRAM_ID = Pubkey.from_string("dzrecxigtaZQ3gPmt2X5mDkYigaruFR1rHCqztFTvx7")
+RECORD_HEADER_SIZE = 33
+
+
+def derive_config_pda(program_id: Pubkey) -> tuple[Pubkey, int]:
+    return Pubkey.find_program_address([SEED_PROGRAM_CONFIG], program_id)
+
+
+def derive_distribution_pda(
+    program_id: Pubkey, epoch: int
+) -> tuple[Pubkey, int]:
+    epoch_bytes = struct.pack("<Q", epoch)
+    return Pubkey.find_program_address(
+        [SEED_DISTRIBUTION, epoch_bytes], program_id
+    )
+
+
+def derive_journal_pda(program_id: Pubkey) -> tuple[Pubkey, int]:
+    return Pubkey.find_program_address([SEED_JOURNAL], program_id)
+
+
+def derive_validator_deposit_pda(
+    program_id: Pubkey, node_id: Pubkey
+) -> tuple[Pubkey, int]:
+    return Pubkey.find_program_address(
+        [SEED_SOLANA_VALIDATOR_DEPOSIT, bytes(node_id)], program_id
+    )
+
+
+def derive_contributor_rewards_pda(
+    program_id: Pubkey, service_key: Pubkey
+) -> tuple[Pubkey, int]:
+    return Pubkey.find_program_address(
+        [SEED_CONTRIBUTOR_REWARDS, bytes(service_key)], program_id
+    )
+
+
+def _create_record_seed_string(seeds: list[bytes]) -> str:
+    """Hash seeds with SHA256, encode as base58, truncate to 32 chars."""
+    h = hashlib.sha256()
+    for s in seeds:
+        h.update(s)
+    return base58.b58encode(h.digest()).decode()[:32]
+
+
+def derive_record_key(payer_key: Pubkey, seeds: list[bytes]) -> Pubkey:
+    """Derive a ledger record address using create-with-seed."""
+    seed_str = _create_record_seed_string(seeds)
+    return Pubkey.create_with_seed(payer_key, seed_str, RECORD_PROGRAM_ID)
+
+
+def derive_validator_debt_record_key(
+    debt_accountant_key: Pubkey, epoch: int
+) -> Pubkey:
+    epoch_bytes = struct.pack("<Q", epoch)
+    return derive_record_key(
+        debt_accountant_key, [SEED_SOLANA_VALIDATOR_DEBT, epoch_bytes]
+    )
+
+
+def derive_reward_share_record_key(
+    rewards_accountant_key: Pubkey, epoch: int
+) -> Pubkey:
+    epoch_bytes = struct.pack("<Q", epoch)
+    return derive_record_key(
+        rewards_accountant_key,
+        [SEED_DZ_CONTRIBUTOR_REWARDS, epoch_bytes, SEED_SHAPLEY_OUTPUT],
+    )

doublezero_revenue_distribution-0.0.2/revdist/reserved.py

@@ -0,0 +1,19 @@
+"""Wrapper for reserved / padding bytes in on-chain account layouts."""
+
+from __future__ import annotations
+
+
+class Reserved(bytes):
+    """Thin wrapper around ``bytes`` that marks padding or storage-gap fields.
+
+    Behaves exactly like ``bytes`` but makes the intent explicit when used as
+    a type annotation in dataclasses::
+
+        reserved0: Reserved  # [3]u8 padding
+    """
+
+    def __new__(cls, data: bytes) -> Reserved:
+        return super().__new__(cls, data)
+
+    def __repr__(self) -> str:
+        return f"Reserved({len(self)})"

doublezero_revenue_distribution-0.0.2/revdist/rpc.py

@@ -0,0 +1,49 @@
+"""RPC client helpers with retry on rate limiting."""
+
+import time
+
+import httpx
+from solana.rpc.api import Client as SolanaHTTPClient  # type: ignore[import-untyped]
+from solana.rpc.providers.http import HTTPProvider  # 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