sol-parser-sdk-python 0.4.4__py3-none-any.whl

sol_parser/entries_decode.py

@@ -0,0 +1,186 @@
+"""gRPC ShredStream ``Entry.entries`` 负载解码（对齐 Node ``entries_decode.ts`` / Go ``DecodeEntriesBincode``）。"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import List, Optional
+
+MAX_VEC_ENTRIES = 100_000
+
+
+def read_u64_le(buf: bytes, offset: int) -> int:
+    return struct.unpack_from("<Q", buf, offset)[0]
+
+
+def bincode_vec_entry_count(entries_bytes: bytes) -> int:
+    if len(entries_bytes) < 8:
+        raise ValueError("shredstream: entries payload too short for vec length")
+    n = read_u64_le(entries_bytes, 0)
+    if n > MAX_VEC_ENTRIES:
+        raise ValueError(f"shredstream: corrupt entry_count {n} exceeds limit")
+    return n
+
+
+def decode_compact_u16(buf: bytes, pos: int) -> Optional[tuple[int, int]]:
+    if pos >= len(buf):
+        return None
+    b0 = buf[pos]
+    if b0 < 0x80:
+        return (b0, 1)
+    if pos + 1 >= len(buf):
+        return None
+    b1 = buf[pos + 1]
+    if b1 < 0x80:
+        return ((b0 & 0x7F) | (b1 << 7), 2)
+    if pos + 2 >= len(buf):
+        return None
+    b2 = buf[pos + 2]
+    return ((b0 & 0x7F) | ((b1 & 0x7F) << 7) | (b2 << 14), 3)
+
+
+@dataclass
+class _ParsedTx:
+    tx_len: int
+    signatures: List[bytes]
+
+
+def parse_transaction_wire(buf: bytes, pos: int) -> Optional[_ParsedTx]:
+    start = pos
+    if pos >= len(buf):
+        return None
+    sig_count_enc = decode_compact_u16(buf, pos)
+    if not sig_count_enc:
+        return None
+    p = pos + sig_count_enc[1]
+    sig_count = sig_count_enc[0]
+    sigs_end = p + sig_count * 64
+    if sigs_end > len(buf):
+        return None
+    sigs: List[bytes] = []
+    for _ in range(sig_count):
+        sigs.append(buf[p : p + 64])
+        p += 64
+    if p >= len(buf):
+        return None
+    msg_first = buf[p]
+    is_v0 = msg_first >= 0x80
+    if is_v0:
+        p += 1
+    p += 3
+    if p > len(buf):
+        return None
+    acct_enc = decode_compact_u16(buf, p)
+    if not acct_enc:
+        return None
+    p += acct_enc[1]
+    p += acct_enc[0] * 32
+    if p > len(buf):
+        return None
+    ix_count_enc = decode_compact_u16(buf, p)
+    if not ix_count_enc:
+        return None
+    p += ix_count_enc[1]
+    ix_count = ix_count_enc[0]
+    for _ in range(ix_count):
+        p += 1
+        if p > len(buf):
+            return None
+        acct_len_enc = decode_compact_u16(buf, p)
+        if not acct_len_enc:
+            return None
+        p += acct_len_enc[1]
+        p += acct_len_enc[0]
+        if p > len(buf):
+            return None
+        data_len_enc = decode_compact_u16(buf, p)
+        if not data_len_enc:
+            return None
+        p += data_len_enc[1]
+        p += data_len_enc[0]
+        if p > len(buf):
+            return None
+    if is_v0:
+        if p >= len(buf):
+            return None
+        atl_count_enc = decode_compact_u16(buf, p)
+        if not atl_count_enc:
+            return None
+        p += atl_count_enc[1]
+        atl_count = atl_count_enc[0]
+        for _ in range(atl_count):
+            p += 32
+            if p > len(buf):
+                return None
+            w_len_enc = decode_compact_u16(buf, p)
+            if not w_len_enc:
+                return None
+            p += w_len_enc[1]
+            p += w_len_enc[0]
+            if p > len(buf):
+                return None
+            r_len_enc = decode_compact_u16(buf, p)
+            if not r_len_enc:
+                return None
+            p += r_len_enc[1]
+            p += r_len_enc[0]
+            if p > len(buf):
+                return None
+    return _ParsedTx(tx_len=p - start, signatures=sigs)
+
+
+class _BatchDecoder:
+    def __init__(self) -> None:
+        self.buffer = bytearray()
+        self.expected_entry_count = 0
+        self.entries_yielded = 0
+        self.cursor = 0
+
+    def append(self, payload: bytes) -> None:
+        self.buffer.extend(payload)
+
+    def try_decode_entry(self) -> Optional[List[bytes]]:
+        pos = self.cursor
+        buf = self.buffer
+        if pos + 48 > len(buf):
+            return None
+        p = pos + 8 + 32
+        tx_count = read_u64_le(buf, p)
+        p += 8
+        txs: List[bytes] = []
+        for _ in range(tx_count):
+            tx_start = p
+            parsed = parse_transaction_wire(buf, p)
+            if not parsed:
+                raise ValueError("shredstream: truncated transaction in entry")
+            raw = bytes(buf[tx_start : tx_start + parsed.tx_len])
+            txs.append(raw)
+            p = tx_start + parsed.tx_len
+        self.cursor = p
+        return txs
+
+    def push_flat(self, payload: bytes) -> List[bytes]:
+        self.append(payload)
+        if self.expected_entry_count == 0 and self.entries_yielded == 0 and self.cursor == 0:
+            if len(self.buffer) < 8:
+                raise ValueError("shredstream: entries payload too short for vec length")
+            count = read_u64_le(self.buffer, 0)
+            if count > MAX_VEC_ENTRIES:
+                raise ValueError(f"shredstream: corrupt entry_count {count} exceeds limit")
+            self.expected_entry_count = int(count)
+            self.cursor = 8
+        out: List[bytes] = []
+        while self.entries_yielded < self.expected_entry_count:
+            entry_txs = self.try_decode_entry()
+            if entry_txs is None:
+                raise ValueError(f"shredstream: incomplete entry at offset {self.cursor}")
+            out.extend(entry_txs)
+            self.entries_yielded += 1
+        return out
+
+
+def decode_entries_bincode_flat(entries_bytes: bytes) -> List[bytes]:
+    if not entries_bytes:
+        return []
+    dec = _BatchDecoder()
+    return dec.push_flat(entries_bytes)

sol_parser/env_config.py

@@ -0,0 +1,215 @@
+"""Environment and CLI helpers aligned with sol-parser-sdk-nodejs (GRPC_URL, .env, flags)."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional, Sequence, Tuple
+
+
+def load_dotenv_silent(dotenv_path: Optional[str] = None) -> bool:
+    """Load ``.env`` from the current working directory (or ``dotenv_path``).
+
+    Does **not** override variables already set in the process environment
+    (same idea as ``dotenv`` on Node). Returns ``False`` if ``python-dotenv``
+    is not installed.
+    """
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return False
+    load_dotenv(dotenv_path, override=False)
+    return True
+
+
+def _first_nonempty(*values: Optional[str]) -> str:
+    for v in values:
+        if v is None:
+            continue
+        s = str(v).strip()
+        if s:
+            return s
+    return ""
+
+
+def _parse_grpc_cli(argv: Sequence[str]) -> tuple[Optional[str], Optional[str]]:
+    """Parse ``--grpc-url``, ``--grpc-token``, and short aliases from *argv*."""
+    url: Optional[str] = None
+    token: Optional[str] = None
+    i = 0
+    n = len(argv)
+    while i < n:
+        a = argv[i]
+        if a in ("--grpc-url", "--grpc-endpoint", "-g") and i + 1 < n:
+            url = argv[i + 1].strip()
+            i += 2
+            continue
+        if a.startswith("--grpc-url="):
+            url = a.split("=", 1)[1].strip()
+            i += 1
+            continue
+        if a.startswith("--grpc-endpoint="):
+            url = a.split("=", 1)[1].strip()
+            i += 1
+            continue
+        if a in ("--grpc-token", "--token", "-t") and i + 1 < n:
+            token = argv[i + 1].strip()
+            i += 2
+            continue
+        if a.startswith("--grpc-token="):
+            token = a.split("=", 1)[1].strip()
+            i += 1
+            continue
+        if a.startswith("--token="):
+            token = a.split("=", 1)[1].strip()
+            i += 1
+            continue
+        i += 1
+    return url, token
+
+
+def parse_grpc_credentials(
+    argv: Optional[Sequence[str]] = None,
+    *,
+    default_endpoint: str = "solana-yellowstone-grpc.publicnode.com:443",
+    require_token: bool = False,
+) -> Tuple[str, str]:
+    """Resolve Yellowstone gRPC URL and x-token.
+
+    **Precedence (each field):** CLI flags > ``GRPC_URL`` / ``GRPC_ENDPOINT`` /
+    ``GRPC_AUTH_TOKEN`` / ``GRPC_TOKEN`` > legacy ``GEYSER_*`` >
+    *default_endpoint* (URL only).
+
+    Call :func:`load_dotenv_silent` first so a project-local ``.env`` is applied.
+
+    :param require_token: If ``True``, print an error and ``sys.exit(1)`` when the
+        token is still empty after resolution.
+    """
+    load_dotenv_silent()
+    cli_url, cli_token = _parse_grpc_cli(list(argv) if argv is not None else [])
+    url = _first_nonempty(
+        cli_url,
+        os.environ.get("GRPC_URL"),
+        os.environ.get("GRPC_ENDPOINT"),
+        os.environ.get("GEYSER_ENDPOINT"),
+        default_endpoint,
+    )
+    token = _first_nonempty(
+        cli_token,
+        os.environ.get("GRPC_AUTH_TOKEN"),
+        os.environ.get("GRPC_TOKEN"),
+        os.environ.get("GEYSER_API_TOKEN"),
+    )
+    if require_token and not token:
+        print(
+            "Error: GRPC_AUTH_TOKEN / GRPC_TOKEN is required (x-token for the gRPC endpoint).\n"
+            "  Copy .env.example to .env in the package root and set GRPC_AUTH_TOKEN or GRPC_TOKEN, or:\n"
+            "  export GRPC_AUTH_TOKEN=<your_token>\n"
+            "  You can also pass: --grpc-token <token>  or  --token=<token>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return url, token
+
+
+def require_grpc_env(argv: Optional[Sequence[str]] = None) -> Tuple[str, str]:
+    """Require both gRPC URL and token (same contract as Node ``scripts/grpc_env.ts``).
+
+    No default URL: set ``GRPC_URL`` / ``GEYSER_ENDPOINT`` or ``--grpc-url``.
+    """
+    load_dotenv_silent()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cli_url, cli_token = _parse_grpc_cli(argv)
+    url = _first_nonempty(
+        cli_url,
+        os.environ.get("GRPC_URL"),
+        os.environ.get("GRPC_ENDPOINT"),
+        os.environ.get("GEYSER_ENDPOINT"),
+    )
+    token = _first_nonempty(
+        cli_token,
+        os.environ.get("GRPC_AUTH_TOKEN"),
+        os.environ.get("GRPC_TOKEN"),
+        os.environ.get("GEYSER_API_TOKEN"),
+    )
+    if not url:
+        print(
+            "Error: GRPC_URL / GRPC_ENDPOINT is required.\n"
+            "  Copy .env.example to .env in the package root and set GRPC_URL (and GRPC_AUTH_TOKEN), or:\n"
+            "  export GRPC_URL=https://your-yellowstone-host:443\n"
+            "  CLI: --grpc-url <url>  or  -g <url>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    if not token:
+        print(
+            "Error: GRPC_AUTH_TOKEN / GRPC_TOKEN is required (x-token header for the gRPC endpoint).\n"
+            "  Copy .env.example to .env in the package root and set GRPC_AUTH_TOKEN, or:\n"
+            "  export GRPC_AUTH_TOKEN=<your_token>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return url, token
+
+
+def parse_shredstream_url(
+    argv: Optional[Sequence[str]] = None,
+    *,
+    default_url: str = "http://127.0.0.1:10800",
+) -> str:
+    """ShredStream HTTP endpoint: ``--url`` / ``-u`` / ``--endpoint=`` > ``SHREDSTREAM_URL`` / ``SHRED_URL`` > default."""
+    load_dotenv_silent()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    for i, a in enumerate(argv):
+        if a in ("--url", "-u", "--endpoint") and i + 1 < len(argv):
+            v = argv[i + 1].strip()
+            if v:
+                return v
+        if a.startswith("--url="):
+            return a[6:].strip()
+        if a.startswith("--endpoint="):
+            return a[11:].strip()
+    env_url = _first_nonempty(os.environ.get("SHREDSTREAM_URL"), os.environ.get("SHRED_URL"))
+    return env_url or default_url
+
+
+def parse_optional_rpc_url(
+    argv: Optional[Sequence[str]] = None,
+    *,
+    default_rpc: str = "https://api.mainnet-beta.solana.com",
+) -> str:
+    """``--rpc`` / ``-r`` / ``--rpc=`` > ``RPC_URL`` > *default_rpc*."""
+    load_dotenv_silent()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    for i, a in enumerate(argv):
+        if a in ("--rpc", "-r") and i + 1 < len(argv):
+            v = argv[i + 1].strip()
+            if v:
+                return v
+        if a.startswith("--rpc="):
+            return a[6:].strip()
+    return _first_nonempty(os.environ.get("RPC_URL"), os.environ.get("SOLANA_RPC_URL")) or default_rpc
+
+
+def _parse_sig_cli(argv: Sequence[str]) -> Optional[str]:
+    for i, a in enumerate(argv):
+        if a in ("--sig", "-s") and i + 1 < len(argv):
+            v = argv[i + 1].strip()
+            if v:
+                return v
+        if a.startswith("--sig="):
+            return a[6:].strip()
+    return None
+
+
+def parse_rpc_and_tx_signature(
+    argv: Optional[Sequence[str]] = None,
+    *,
+    default_signature: str,
+) -> Tuple[str, str]:
+    """For ``parse_tx_by_signature``-style tools: RPC URL + transaction signature."""
+    load_dotenv_silent()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    rpc = parse_optional_rpc_url(argv)
+    sig = _first_nonempty(_parse_sig_cli(argv), os.environ.get("TX_SIGNATURE"), default_signature)
+    return rpc, sig