mycelium-cli 0.1.0__py3-none-any.whl

mycelium_cli/__init__.py

@@ -0,0 +1 @@
+# Mycelium CLI Package

mycelium_cli/commands/__init__.py

@@ -0,0 +1 @@
+# CLI subcommands package

mycelium_cli/commands/agent.py

@@ -0,0 +1,70 @@
+"""
+`mycelium agent` — run a Mycelium agent runtime script.
+
+Loads the developer's agent script (e.g. the scaffolded `agent.py`) as a module
+and runs it, binding the on-chain contract id into the environment as
+`MYCELIUM_CONTRACT_ID` so the script (and any `AgentContext` it builds) can read
+it. If the script exposes a `main()` callable it is invoked; otherwise importing
+the module is treated as running it (top-level code executes on import).
+"""
+
+import importlib.util
+import os
+import sys
+
+
+def _load_dotenv(path: str) -> None:
+    """Minimal .env loader: sets KEY=VALUE pairs into os.environ if not already set."""
+    if not os.path.exists(path):
+        return
+    with open(path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, value = line.partition("=")
+            key = key.strip()
+            if key.startswith("export "):
+                key = key[len("export "):].strip()
+            value = value.strip()
+            # Strip a single pair of matching surrounding quotes.
+            if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+                value = value[1:-1]
+            os.environ.setdefault(key, value)
+
+
+def run_agent(file_path: str, contract_id: str):
+    if not os.path.exists(file_path):
+        print(f"Error: agent runtime file {file_path} not found.")
+        sys.exit(1)
+
+    print(f"[Agent] Loading runtime script: {file_path}")
+    print(f"[Agent] Bound to on-chain contract: {contract_id}")
+
+    # Expose the bound contract id to the agent script and any SDK it constructs.
+    os.environ["MYCELIUM_CONTRACT_ID"] = contract_id
+
+    # Load a sibling .env (written by `mycelium init` with the provider API key)
+    # so the agent can authenticate without the key being hard-coded in source.
+    _load_dotenv(os.path.join(os.path.dirname(os.path.abspath(file_path)), ".env"))
+
+    module_name = os.path.splitext(os.path.basename(file_path))[0]
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    if spec is None or spec.loader is None:
+        print(f"Error: could not load {file_path} as a Python module.")
+        sys.exit(1)
+    module = importlib.util.module_from_spec(spec)
+    # Make the script's own directory importable (so it can import sibling files).
+    sys.path.insert(0, os.path.dirname(os.path.abspath(file_path)) or ".")
+
+    try:
+        spec.loader.exec_module(module)
+        if hasattr(module, "main") and callable(module.main):
+            print("[Agent] Running main()...")
+            module.main()
+        print("[Agent] Runtime finished.")
+    except KeyboardInterrupt:
+        print("\n[Agent] Execution halted by user request.")
+    except Exception as e:
+        print(f"❌ Agent runtime error: {e}")
+        sys.exit(1)

mycelium_cli/commands/call.py

@@ -0,0 +1,96 @@
+"""
+`mycelium call <fn> [args...]` — invoke a deployed contract function from the CLI.
+
+By default the call is read-only (simulated, no signature, no fee) — perfect for
+views and getters. Pass `--send` to sign and submit a state-changing transaction,
+which loads the project wallet and prompts for its passphrase.
+
+Argument widths are marshalled automatically from the contract spec (fetched
+once from RPC), so `mycelium call add 40` "just works" — no U64() wrapper needed.
+String tokens are interpreted as ints/bools/addresses where unambiguous and left
+as strings otherwise.
+"""
+
+import sys
+from typing import Any, List, Optional
+
+from mycelium_cli.config import get_value
+
+DEFAULT_WALLET_PATH = ".mycelium/wallet.json"
+
+
+def _parse_arg(token: str) -> Any:
+    """Best-effort coerce a CLI string token into a Python value.
+
+    Integers and bools are recognised; addresses/symbols/strings are left as
+    strings (AgentContext + the contract spec marshal them to the right SCVal).
+    Prefix a value with `s:` to force it to stay a string (e.g. `s:42`).
+    """
+    if token.startswith("s:"):
+        return token[2:]
+    low = token.lower()
+    if low == "true":
+        return True
+    if low == "false":
+        return False
+    try:
+        return int(token)
+    except ValueError:
+        return token
+
+
+def run_call(
+    function_name: str,
+    args: Optional[List[str]] = None,
+    contract: Optional[str] = None,
+    network: Optional[str] = None,
+    send: bool = False,
+    wallet_path: str = DEFAULT_WALLET_PATH,
+    passphrase: Optional[str] = None,
+) -> Any:
+    from mycelium_sdk import AgentContext
+
+    network = network or get_value("onchain", "network", "testnet")
+    contract = contract or get_value("onchain", "contract_id")
+    if not contract:
+        print(
+            "Error: no contract id. Pass --contract C..., or run inside a project "
+            "whose mycelium.toml has [onchain].contract_id (after `mycelium deploy`)."
+        )
+        sys.exit(1)
+
+    parsed = [_parse_arg(a) for a in (args or [])]
+
+    if send:
+        import os
+
+        if not os.path.exists(wallet_path):
+            print(f"Error: wallet {wallet_path} not found. Run `mycelium newwallet` first.")
+            sys.exit(1)
+        context = AgentContext(
+            keypair_path=wallet_path, network_type=network, passphrase=passphrase
+        )
+    else:
+        context = AgentContext.read_only(network_type=network)
+
+    print(
+        f"[call] {function_name}({', '.join(map(repr, parsed))}) on {contract} "
+        f"({'send' if send else 'read-only'})..."
+    )
+    try:
+        result = context.call_contract(
+            contract, function_name, parsed, read_only=not send
+        )
+    except Exception as e:
+        print(f"❌ Call failed: {e}")
+        sys.exit(1)
+
+    if send:
+        # call_contract returns a TxResult for state-changing calls.
+        tx_hash = getattr(result, "hash", None)
+        ret = getattr(result, "return_value", result)
+        print(f"✓ Submitted. Tx: {tx_hash}")
+        print(f"  return: {ret}")
+    else:
+        print(f"✓ {result}")
+    return result

mycelium_cli/commands/check.py

@@ -0,0 +1,21 @@
+import os
+import sys
+from mycelium_compiler.parser import parse_source
+from mycelium_compiler.validator import validate_ast
+
+def run_check(file_path: str):
+    print(f"Checking AST rules and type constraints for: {file_path}")
+    if not os.path.exists(file_path):
+        print(f"Error: File {file_path} not found.")
+        sys.exit(1)
+        
+    with open(file_path, "r") as f:
+        source_code = f.read()
+        
+    try:
+        visitor = parse_source(source_code)
+        validate_ast(visitor)
+        print("✓ All validation checks passed successfully!")
+    except Exception as e:
+        print(f"❌ Validation failed: {e}")
+        sys.exit(1)

mycelium_cli/commands/compile.py

@@ -0,0 +1,59 @@
+"""
+`mycelium compile` — compile the project's contract to Soroban WASM.
+
+Delegates directly to the compiler pipeline (parse → validate → generate_wasm),
+which builds via the pinned stellar-cli 27.0.0 toolchain.
+"""
+
+import os
+import sys
+
+from mycelium_compiler.parser import parse_source
+from mycelium_compiler.validator import validate_ast
+from mycelium_compiler.codegen import generate_wasm
+
+from mycelium_cli.config import get_value
+
+
+def run_compile(
+    file_path: str | None = None,
+    output_path: str | None = None,
+    optimize: bool = False,
+) -> str:
+    """
+    Compile `file_path` to `output_path`. When omitted, both are read from
+    mycelium.toml ([onchain].source_contract / [onchain].target_wasm). Prints
+    size telemetry. Returns the output path.
+    """
+    file_path = file_path or get_value("onchain", "source_contract", "contract.py")
+    output_path = output_path or get_value("onchain", "target_wasm", "build/contract.wasm")
+
+    print(f"Compiling contract {file_path} -> {output_path}...")
+    if not os.path.exists(file_path):
+        print(f"Error: File {file_path} not found.")
+        sys.exit(1)
+
+    with open(file_path, "r") as f:
+        source_code = f.read()
+
+    try:
+        visitor = parse_source(source_code)
+        validate_ast(visitor)
+        wasm_bytes = generate_wasm(visitor)
+    except Exception as e:
+        print(f"❌ Compilation failed: {e}")
+        sys.exit(1)
+
+    out_dir = os.path.dirname(output_path)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+    with open(output_path, "wb") as f_out:
+        f_out.write(wasm_bytes)
+
+    size = len(wasm_bytes)
+    print(f"✓ Compilation successful! Output: {output_path}")
+    print(f"  WASM size: {size:,} bytes ({size / 1024:.2f} KiB)")
+    # The release profile already optimizes for size (opt-level \"z\", LTO).
+    if optimize:
+        print("  (--optimize: size-optimized release profile is always applied)")
+    return output_path

mycelium_cli/commands/deploy.py

@@ -0,0 +1,140 @@
+"""
+`mycelium deploy` — publish the compiled WASM to Stellar/Soroban (sdk.md 2.4).
+
+Mirrors the proven flow in the IDE backend's /api/deploy:
+  - testnet: if the wallet has 0 XLM, fund it via Friendbot and poll.
+  - mainnet: refuse to deploy unless the wallet holds >= 5 XLM (no Friendbot).
+  - deploy via the pinned stellar-cli 27.0.0 binary (ensure_stellar_cli()).
+  - write the resulting contract_id + wallet public key back to mycelium.toml.
+"""
+
+import os
+import subprocess
+import sys
+import time
+
+from mycelium_compiler.codegen import ensure_stellar_cli
+from mycelium_sdk import crypto
+from mycelium_sdk.constants import (
+    FRIENDBOT_URL,
+    HORIZON_URLS,
+    MAINNET_MIN_XLM,
+    NETWORK_PASSPHRASES,
+    SOROBAN_RPC_URLS,
+    normalize_network,
+)
+
+from mycelium_cli.config import get_value, set_value
+
+DEFAULT_WALLET_PATH = os.path.join(".mycelium", "wallet.json")
+
+
+def _load_secret(wallet_path: str, passphrase: str | None) -> tuple[str, str]:
+    """Decrypt the wallet, returning (secret_seed, public_key)."""
+    import json
+
+    with open(wallet_path, "r") as f:
+        wallet = json.load(f)
+    pw = crypto.resolve_passphrase(passphrase)
+    secret = crypto.decrypt_secret(
+        wallet["encrypted_secret"], wallet["nonce"], wallet["salt"], pw
+    )
+    return secret, wallet["public_key"]
+
+
+def _native_balance(network: str, public_key: str) -> float:
+    """Return the account's native XLM balance, or 0.0 if the account is new."""
+    from stellar_sdk import Server
+    from stellar_sdk.exceptions import NotFoundError
+
+    server = Server(HORIZON_URLS[network])
+    try:
+        acct = server.accounts().account_id(public_key).call()
+    except NotFoundError:
+        return 0.0
+    for bal in acct.get("balances", []):
+        if bal.get("asset_type") == "native":
+            return float(bal["balance"])
+    return 0.0
+
+
+def _fund_with_friendbot(network: str, public_key: str) -> None:
+    import requests
+
+    print(f"[deploy] Wallet has 0 XLM — requesting Friendbot funding for {public_key}...")
+    res = requests.get(f"{FRIENDBOT_URL}/?addr={public_key}", timeout=20)
+    if not res.ok:
+        raise RuntimeError(f"Friendbot funding failed: HTTP {res.status_code}")
+
+    # Poll the ledger until the funding actually lands (spec: "Poll until confirmed").
+    deadline = time.time() + 30
+    while time.time() < deadline:
+        time.sleep(3)
+        if _native_balance(network, public_key) > 0.0:
+            print("[deploy] Friendbot funding confirmed on-chain.")
+            return
+    raise RuntimeError(
+        "Friendbot returned success but the account is still unfunded after 30s. "
+        "Retry the deploy, or fund the account manually."
+    )
+
+
+def run_deploy(
+    network: str = "testnet",
+    wasm_path: str | None = None,
+    wallet_path: str = DEFAULT_WALLET_PATH,
+    passphrase: str | None = None,
+    write_config: bool = True,
+) -> str:
+    """Deploy the compiled contract and return the new contract id."""
+    network = normalize_network(network)
+    wasm_path = wasm_path or get_value("onchain", "target_wasm", "build/contract.wasm")
+
+    if not os.path.exists(wasm_path):
+        print(f"Error: compiled WASM {wasm_path} not found. Run `mycelium compile` first.")
+        sys.exit(1)
+    if not os.path.exists(wallet_path):
+        print(f"Error: wallet {wallet_path} not found. Run `mycelium newwallet` first.")
+        sys.exit(1)
+
+    secret, public_key = _load_secret(wallet_path, passphrase)
+    print(f"[deploy] Deploying {wasm_path} to {network} as {public_key}...")
+
+    balance = _native_balance(network, public_key)
+    if network == "testnet":
+        if balance <= 0.0:
+            _fund_with_friendbot(network, public_key)
+    else:
+        if balance < MAINNET_MIN_XLM:
+            print(
+                f"[Error] Insufficient funds for live deployment. Mainnet operations "
+                f"require at least {int(MAINNET_MIN_XLM)} XLM sequence reserve. "
+                f"Balance must be deposited to: {public_key}."
+            )
+            sys.exit(1)
+
+    stellar_bin = ensure_stellar_cli()
+    cmd = [
+        stellar_bin, "contract", "deploy",
+        "--wasm", wasm_path,
+        "--source-account", secret,
+        "--rpc-url", SOROBAN_RPC_URLS[network],
+        "--network-passphrase", NETWORK_PASSPHRASES[network],
+    ]
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=90)
+    if res.returncode != 0:
+        print(f"❌ Deployment failed:\n{res.stdout}\n{res.stderr}")
+        sys.exit(1)
+
+    contract_id = res.stdout.strip().splitlines()[-1].strip()
+    print(f"✓ Deployment successful! Contract ID: {contract_id}")
+
+    if write_config:
+        try:
+            set_value("onchain", "contract_id", contract_id)
+            set_value("onchain", "wallet_public_key", public_key)
+            print("  Wrote contract_id + wallet_public_key to mycelium.toml")
+        except FileNotFoundError:
+            pass  # deploying outside a project dir is allowed
+
+    return contract_id

mycelium_cli/commands/discover.py

@@ -0,0 +1,67 @@
+"""
+`mycelium agents` — discover every agent registered on the Hive Registry.
+
+This is a read-only, wallet-free command: anyone can list the global agent
+directory without owning a wallet or spending fees. It scans the registry
+contract's `agent_registered` events over the RPC's retained ledger window and
+resolves each name to its current address, endpoint, and reputation.
+
+The registry address comes from `[registry].hive_registry_address` in
+mycelium.toml when run inside a project, falling back to the SDK default.
+"""
+
+import sys
+from typing import Optional
+
+
+def run_discover(
+    network: Optional[str] = None,
+    registry: Optional[str] = None,
+    start_ledger: Optional[int] = None,
+    resolve: bool = True,
+) -> list:
+    from mycelium_sdk import AgentContext, HiveClient
+    from mycelium_sdk.constants import HIVEMIND_REGISTRY_ADDRESS
+
+    from mycelium_cli.config import get_value
+
+    network = network or get_value("onchain", "network", "testnet")
+    registry = registry or get_value("registry", "hive_registry_address") or HIVEMIND_REGISTRY_ADDRESS
+
+    context = AgentContext.read_only(network_type=network)
+    hive = HiveClient(context, registry_address=registry)
+
+    print(f"[discover] Scanning Hive Registry {registry} on {network}...")
+    try:
+        agents = hive.discover_agents(start_ledger=start_ledger, resolve=resolve)
+    except Exception as e:
+        print(f"❌ Discovery failed: {e}")
+        sys.exit(1)
+
+    _print_agents(agents)
+    return agents
+
+
+def _print_agents(agents: list) -> None:
+    if not agents:
+        print(
+            "No agents found in the registry's retained event window.\n"
+            "  (Registrations older than the RPC's retention horizon are not "
+            "discoverable — pass --start-ledger to widen the scan.)"
+        )
+        return
+
+    print(f"\nFound {len(agents)} agent(s):\n")
+    name_w = max(len("NAME"), *(len(a.get("name", "")) for a in agents))
+    addr_w = max(len("ADDRESS"), *(len(a.get("public_key") or "") for a in agents))
+    header = f"  {'NAME':<{name_w}}  {'ADDRESS':<{addr_w}}  {'REP':>4}  ENDPOINT"
+    print(header)
+    print("  " + "-" * (len(header) - 2))
+    for a in agents:
+        name = a.get("name", "")
+        addr = a.get("public_key") or "—"
+        rep = a.get("reputation")
+        rep_str = str(rep) if rep is not None else "—"
+        endpoint = a.get("endpoint") or "—"
+        print(f"  {name:<{name_w}}  {addr:<{addr_w}}  {rep_str:>4}  {endpoint}")
+    print()

mycelium_cli/commands/doctor.py

@@ -0,0 +1,106 @@
+"""
+`mycelium doctor` — verify the local toolchain and print fixes.
+
+Checks the things that silently break a compile/deploy:
+  - stellar-cli present and at the version Mycelium pins (we hit a 25-vs-27
+    mismatch in the field),
+  - a Rust toolchain with the wasm32 target installed,
+  - the Soroban RPC for the configured network is reachable.
+
+Each failed check prints the exact command that fixes it. Exit code is non-zero
+if anything is wrong, so it can gate CI.
+"""
+
+import re
+import shutil
+import subprocess
+import sys
+from typing import Optional
+
+from mycelium_sdk.constants import SOROBAN_RPC_URLS, normalize_network
+
+from mycelium_cli.config import get_value
+
+# Must track compiler/.../core.py::ensure_stellar_cli (the version we bundle).
+PINNED_STELLAR_VERSION = "27.0.0"
+WASM_TARGET = "wasm32-unknown-unknown"
+
+_OK = "✓"
+_NO = "✗"
+_WARN = "⚠"
+
+
+def _run(cmd: list[str]) -> Optional[str]:
+    """Run `cmd`, returning stripped stdout, or None if it isn't runnable."""
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, timeout=20)
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return None
+    if res.returncode != 0:
+        return None
+    return (res.stdout or res.stderr).strip()
+
+
+def _check_stellar_cli() -> bool:
+    binary = shutil.which("stellar")
+    if not binary:
+        print(f"  {_NO} stellar-cli   not found on PATH")
+        print(f"       fix: cargo install --locked stellar-cli@{PINNED_STELLAR_VERSION}")
+        return False
+    out = _run(["stellar", "--version"]) or ""
+    m = re.search(r"(\d+)\.(\d+)\.(\d+)", out)
+    version = m.group(0) if m else "unknown"
+    major = int(m.group(1)) if m else 0
+    pinned_major = int(PINNED_STELLAR_VERSION.split(".")[0])
+    if major == pinned_major:
+        print(f"  {_OK} stellar-cli   {version} ({binary})")
+        return True
+    print(f"  {_WARN} stellar-cli   {version} — Mycelium pins v{PINNED_STELLAR_VERSION}")
+    print(f"       fix: cargo install --locked stellar-cli@{PINNED_STELLAR_VERSION}")
+    return False
+
+
+def _check_rust() -> bool:
+    rustc = _run(["rustc", "--version"])
+    if not rustc:
+        print(f"  {_NO} rust          rustc not found")
+        print("       fix: curl https://sh.rustup.rs -sSf | sh")
+        return False
+    print(f"  {_OK} rust          {rustc}")
+
+    installed = _run(["rustup", "target", "list", "--installed"]) or ""
+    if WASM_TARGET in installed:
+        print(f"  {_OK} wasm target   {WASM_TARGET} installed")
+        return True
+    print(f"  {_NO} wasm target   {WASM_TARGET} missing")
+    print(f"       fix: rustup target add {WASM_TARGET}")
+    return False
+
+
+def _check_rpc(network: str) -> bool:
+    url = SOROBAN_RPC_URLS[network]
+    try:
+        from stellar_sdk import SorobanServer
+
+        seq = SorobanServer(url).get_latest_ledger().sequence
+        print(f"  {_OK} rpc           {network} reachable (ledger {seq})")
+        return True
+    except Exception as e:
+        print(f"  {_NO} rpc           {network} unreachable: {e}")
+        print(f"       fix: check connectivity to {url}")
+        return False
+
+
+def run_doctor(network: Optional[str] = None) -> bool:
+    network = normalize_network(network or get_value("onchain", "network", "testnet"))
+    print("\nMycelium doctor — toolchain check\n")
+    results = [
+        _check_stellar_cli(),
+        _check_rust(),
+        _check_rpc(network),
+    ]
+    ok = all(results)
+    print(f"\n{'✓ All checks passed.' if ok else '✗ Some checks failed — see fixes above.'}\n")
+    if not ok:
+        sys.exit(1)
+    return ok

mycelium_cli/commands/events.py

@@ -0,0 +1,116 @@
+"""
+`mycelium events` — show (or stream) a contract's on-chain events from RPC.
+
+Defaults to the project's deployed contract (`[onchain].contract_id`). It scans
+the RPC's retained ledger window and prints each event's topics + value decoded
+to native Python. With `--follow` it polls for new events and prints them as they
+land, until interrupted.
+
+Soroban RPC only retains events for a bounded number of ledgers; registrations or
+calls older than that horizon are not visible here.
+"""
+
+import sys
+import time
+from typing import Optional
+
+from mycelium_cli.config import get_value
+
+_PAGE_LIMIT = 100
+_LEDGER_WINDOW = 16000
+_FOLLOW_INTERVAL_SECONDS = 4
+
+
+def _decode(event, scval, stellar_xdr):
+    """Decode an event's topics and value to native Python, tolerating bad XDR."""
+    def _native(x):
+        try:
+            return scval.to_native(stellar_xdr.SCVal.from_xdr(x))
+        except (ValueError, AttributeError):
+            return "<undecodable>"
+
+    topics = [_native(t) for t in (event.topic or [])]
+    value = _native(event.value) if event.value else None
+    return topics, value
+
+
+def _print_event(event, scval, stellar_xdr) -> None:
+    topics, value = _decode(event, scval, stellar_xdr)
+    ledger = getattr(event, "ledger", "?")
+    topic_str = ", ".join(map(str, topics)) or "—"
+    print(f"  [ledger {ledger}] {topic_str}  ->  {value}")
+
+
+def run_events(
+    contract: Optional[str] = None,
+    network: Optional[str] = None,
+    start_ledger: Optional[int] = None,
+    follow: bool = False,
+) -> None:
+    from mycelium_sdk import AgentContext
+    from stellar_sdk import scval
+    from stellar_sdk import xdr as stellar_xdr
+    from stellar_sdk.soroban_rpc import EventFilter, EventFilterType
+
+    network = network or get_value("onchain", "network", "testnet")
+    contract = contract or get_value("onchain", "contract_id")
+    if not contract:
+        print("Error: no contract id. Pass --contract C..., or deploy first.")
+        sys.exit(1)
+
+    rpc = AgentContext.read_only(network_type=network).soroban_rpc
+    event_filter = EventFilter(
+        event_type=EventFilterType.CONTRACT,
+        contract_ids=[contract],
+        topics=[["*"]],
+    )
+
+    latest = rpc.get_latest_ledger().sequence
+    if start_ledger is None:
+        probe = rpc.get_events(start_ledger=max(1, latest - 1), filters=[event_filter], limit=1)
+        start_ledger = probe.oldest_ledger or max(1, latest - _LEDGER_WINDOW)
+
+    print(f"[events] Scanning {contract} on {network} from ledger {start_ledger}...\n")
+    cursor = _scan(rpc, event_filter, start_ledger, latest, scval, stellar_xdr)
+
+    if not follow:
+        return
+
+    print("\n[events] Following new events (Ctrl-C to stop)...")
+    try:
+        while True:
+            time.sleep(_FOLLOW_INTERVAL_SECONDS)
+            page = rpc.get_events(cursor=cursor, filters=[event_filter], limit=_PAGE_LIMIT)
+            for event in page.events or []:
+                _print_event(event, scval, stellar_xdr)
+                cursor = event.id
+    except KeyboardInterrupt:
+        print("\n[events] Stopped.")
+
+
+def _scan(rpc, event_filter, lo, latest, scval, stellar_xdr) -> Optional[str]:
+    """Print every event from `lo`..`latest`, returning the last cursor seen."""
+    cursor = None
+    count = 0
+    while lo <= latest:
+        hi = min(lo + _LEDGER_WINDOW - 1, latest)
+        page_cursor = None
+        while True:
+            kwargs = {"filters": [event_filter], "limit": _PAGE_LIMIT}
+            if page_cursor is None:
+                kwargs["start_ledger"] = lo
+                kwargs["end_ledger"] = hi
+            else:
+                kwargs["cursor"] = page_cursor
+            page = rpc.get_events(**kwargs)
+            events = page.events or []
+            for event in events:
+                _print_event(event, scval, stellar_xdr)
+                page_cursor = cursor = event.id
+                count += 1
+            if len(events) < _PAGE_LIMIT:
+                break
+        lo = hi + 1
+    if count == 0:
+        print("  (no events in the retained window)")
+    return cursor