blockmachine 0.21.0__tar.gz → 0.22.0__tar.gz

{blockmachine-0.21.0 → blockmachine-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockmachine
-Version: 0.21.0
+Version: 0.22.0
 Summary: Blockmachine CLI - Miner and validator operator interface
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/taostat/blockmachine

{blockmachine-0.21.0 → blockmachine-0.22.0}/blockmachine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blockmachine
-Version: 0.21.0
+Version: 0.22.0
 Summary: Blockmachine CLI - Miner and validator operator interface
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/taostat/blockmachine

{blockmachine-0.21.0 → blockmachine-0.22.0}/blockmachine.egg-info/SOURCES.txt

@@ -25,11 +25,13 @@ blockmachine.egg-info/requires.txt
 blockmachine.egg-info/top_level.txt
 commands/__init__.py
 commands/auth.py
+commands/epoch.py
 commands/leaderboard.py
 commands/miner.py
 commands/validator.py
 tests/test_cli_config.py
 tests/test_cli_endpoints_and_testing.py
+tests/test_epoch_payout_cli.py
 tests/test_leaderboard_cli.py
 tests/test_miner_add_class.py
 tests/test_miner_ban_line.py

blockmachine-0.22.0/commands/epoch.py

@@ -0,0 +1,191 @@
+"""Epoch commands: what every miner will be paid for a finalized epoch."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from cli.client import RegistryClient
+from cli.config import load_config
+
+app = typer.Typer(help="Epoch payouts")
+
+console = Console()
+
+# Rows on the summary table before the rest are folded into one line, and
+# breakdown entries shown per row before "+N more".
+TOP_MINERS = 12
+TOP_BREAKDOWN = 6
+
+
+def _fmt_time(iso: Optional[str]) -> str:
+    """``2026-09-16T20:21:59+00:00`` -> ``16 Sep 20:22 UTC``."""
+    if not iso:
+        return "?"
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+    except ValueError:
+        return iso
+    # Round to the minute rather than truncate: 20:21:59 reads as 20:22.
+    dt = dt.astimezone(timezone.utc) + timedelta(seconds=30)
+    return f"{dt.day} {dt.strftime('%b %H:%M')} UTC"
+
+
+def _fmt_usd(value: Optional[float]) -> str:
+    if value is None:
+        return "-"
+    return f"{value:,.0f}"
+
+
+def _breakdown_summary(entries: list[dict], limit: int = TOP_BREAKDOWN) -> str:
+    shown = [
+        f"{e.get('chain')}/{e.get('node_class')} {float(e.get('alpha') or 0):.1f}"
+        for e in entries[:limit]
+    ]
+    more = len(entries) - limit
+    if more > 0:
+        shown.append(f"+{more} more")
+    return ", ".join(shown)
+
+
+def render_payout(body: dict, top: int = TOP_MINERS) -> list[str]:
+    """The summary table as lines of plain text."""
+    # The registry omits zero-alpha miners; a zero row is nothing to show.
+    miners = [m for m in body.get("miners") or [] if float(m.get("alpha") or 0) > 0]
+    pool_alpha = body.get("pool_alpha")
+    price = body.get("alpha_price_usd")
+    lines = [
+        f"Epoch {body.get('epoch_number')} — finalized "
+        f"{_fmt_time(body.get('finalized_at'))}, paid out by the boundary "
+        f"~{_fmt_time(body.get('pays_at_estimate'))}",
+    ]
+    pool = (
+        f"miner pool {pool_alpha:,.0f} α (${_fmt_usd(body.get('pool_usd'))})"
+        if pool_alpha is not None
+        else "miner pool ?"
+    )
+    price_txt = f"α price ${price:.2f}" if price is not None else "α price ?"
+    lines.append(f"{price_txt}   {pool}   {len(miners)} miners paid")
+    if body.get("caveat"):
+        lines.append(f"Note: {body['caveat']}.")
+    lines.append("")
+
+    if not miners:
+        burn = body.get("burn_pct")
+        if burn is not None and burn >= 1.0:
+            lines.append("No miners paid this epoch: the whole pool burns.")
+        else:
+            lines.append("No miners paid this epoch.")
+        return lines
+
+    lines.append(
+        f" {'UID':<4} {'alpha':>9} {'USD':>9}   {'share':>5}   "
+        "breakdown (chain/class → α)"
+    )
+    for m in miners[:top]:
+        lines.append(
+            f" {m.get('uid', '?'):<4} {float(m.get('alpha') or 0):>9.1f} "
+            f"{_fmt_usd(m.get('usd')):>9}   {float(m.get('share') or 0) * 100:>4.1f}%   "
+            f"{_breakdown_summary(m.get('breakdown') or [])}"
+        )
+    rest = miners[top:]
+    if rest:
+        rest_alpha = sum(float(m.get("alpha") or 0) for m in rest)
+        lines.append(f"  …  {len(rest)} more miners, {rest_alpha:.1f} α between them")
+    lines.append("")
+    lines.append(
+        "USD is an estimate at the α price the finalizer recorded; the chain pays in α."
+    )
+    return lines
+
+
+def render_miner(body: dict, miner: dict) -> list[str]:
+    """One miner with every (chain, class) line."""
+    header = render_payout(body)
+    lines = header[: header.index("")]
+    lines.append("")
+    lines.append(
+        f"UID {miner.get('uid')}  {miner.get('hotkey')}\n"
+        f"  {float(miner.get('alpha') or 0):.1f} α  "
+        f"(${_fmt_usd(miner.get('usd'))}, "
+        f"{float(miner.get('share') or 0) * 100:.1f}% of the pool, "
+        f"{int(miner.get('cu_total') or 0):,} CU)"
+    )
+    lines.append("")
+    lines.append(f"  {'chain/class':<18} {'CU':>15} {'alpha':>9} {'USD':>9}")
+    for e in miner.get("breakdown") or []:
+        node = f"{e.get('chain')}/{e.get('node_class')}"
+        lines.append(
+            f"  {node:<18} {int(e.get('cu') or 0):>15,} "
+            f"{float(e.get('alpha') or 0):>9.1f} {_fmt_usd(e.get('usd')):>9}"
+        )
+    lines.append("")
+    lines.append(
+        "USD is an estimate at the α price the finalizer recorded; the chain pays in α."
+    )
+    return lines
+
+
+@app.command("payout")
+def payout(
+    epoch: Optional[int] = typer.Option(
+        None, "--epoch", "-e", help="Epoch number (default: the latest finalized)"
+    ),
+    uid: Optional[int] = typer.Option(
+        None, "--uid", "-u", help="Show one miner with its full breakdown"
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw response"),
+) -> None:
+    """Show what every miner will be paid for a finalized epoch.
+
+    Per UID: alpha, USD (an estimate at the price recorded when the epoch
+    was finalized), share of the miner pool, and the alpha split by chain
+    and node class. Available the moment an epoch finalizes; the chain pays
+    it out over the following epoch.
+    """
+    path = "/epochs/latest/payout" if epoch is None else f"/epochs/{epoch}/payout"
+    with RegistryClient(load_config()) as client:
+        response = client.get(path)
+
+    if response.status_code == 404:
+        which = f"Epoch {epoch}" if epoch is not None else "No epoch"
+        console.print(f"[yellow]{which} is not finalized yet, or is unknown.[/yellow]")
+        raise typer.Exit(1)
+    if response.status_code == 503:
+        console.print(
+            "[yellow]Epoch payouts are not available on this registry.[/yellow]"
+        )
+        raise typer.Exit(1)
+    if response.status_code != 200:
+        detail = ""
+        try:
+            detail = str(response.json().get("detail", ""))
+        except Exception:
+            detail = response.text
+        console.print(f"[red]Error:[/red] {response.status_code} {detail}")
+        raise typer.Exit(1)
+
+    body = response.json()
+
+    if uid is not None:
+        matches = [m for m in body.get("miners") or [] if m.get("uid") == uid]
+        if not matches:
+            console.print(
+                f"[yellow]UID {uid} is not paid for epoch "
+                f"{body.get('epoch_number')}.[/yellow]"
+            )
+            raise typer.Exit(1)
+        if as_json:
+            typer.echo(json.dumps(matches[0], indent=2))
+            return
+        typer.echo("\n".join(render_miner(body, matches[0])))
+        return
+
+    if as_json:
+        typer.echo(json.dumps(body, indent=2))
+        return
+    typer.echo("\n".join(render_payout(body)))

{blockmachine-0.21.0 → blockmachine-0.22.0}/main.py

@@ -7,6 +7,7 @@ import typer
 from rich.console import Console
 
 from cli import settings
+from cli.commands.epoch import app as epoch_app
 from cli.commands.leaderboard import app as leaderboard_app
 from cli.commands.miner import app as miner_app
 from cli.commands.validator import app as validator_app
@@ -31,6 +32,7 @@ def _global_options(
 
 app.add_typer(miner_app, name="miner", help="Miner node management")
 app.add_typer(leaderboard_app, name="leaderboard", help="Miner leaderboard")
+app.add_typer(epoch_app, name="epoch", help="Epoch payouts")
 app.add_typer(validator_app, name="validator", help="Validator authentication")
 
 

{blockmachine-0.21.0 → blockmachine-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "blockmachine"
-version = "0.21.0"
+version = "0.22.0"
 description = "Blockmachine CLI - Miner and validator operator interface"
 requires-python = ">=3.10"
 license = "MIT"

blockmachine-0.22.0/tests/test_epoch_payout_cli.py

@@ -0,0 +1,206 @@
+"""``bm epoch payout``: the table every miner reads to see what they will be
+paid for the epoch that just finalized.
+
+Rendering only — the numbers are the registry's. What is pinned: the
+layout Ben signed off (UID, alpha, USD, share, breakdown with "+N more"),
+zero rows never appear, the fold line for the long tail, ``--uid`` shows
+every chain/class line, ``--json`` is the body untouched, and each failure
+status gets a sentence rather than a traceback.
+"""
+
+from __future__ import annotations
+
+import json
+
+from typer.testing import CliRunner
+
+from cli.commands import epoch as epoch_mod
+from cli.main import app
+
+runner = CliRunner()
+
+HK = "5F" + "a" * 46
+
+
+def _miner(uid, alpha, share, breakdown, usd=None, hotkey=HK, cu=1000):
+    return {
+        "uid": uid,
+        "hotkey": hotkey,
+        "alpha": alpha,
+        "usd": alpha * 2.15 if usd is None else usd,
+        "share": share,
+        "cu_total": cu,
+        "breakdown": [
+            {"chain": c, "node_class": k, "cu": 10, "alpha": a, "usd": a * 2.15}
+            for c, k, a in breakdown
+        ],
+    }
+
+
+BODY = {
+    "epoch_number": 9075361,
+    "finalized_at": "2026-09-16T20:21:59.117368+00:00",
+    "pays_at_estimate": "2026-09-17T20:21:59.117368+00:00",
+    "alpha_price_usd": 2.15009611114,
+    "pool_alpha": 2952.0,
+    "pool_usd": 6347.08,
+    "burn_pct": 0.0,
+    "miner_count": 3,
+    "miners": [
+        _miner(
+            129,
+            776.3,
+            0.263,
+            [
+                ("tao", "arch", 197.3),
+                ("polygon", "arch", 165.7),
+                ("base", "arch", 146.0),
+                ("arbitrum", "arch", 95.6),
+                ("eth", "arch", 43.1),
+                ("robinhood", "arch", 34.8),
+                ("scroll", "arch", 20.0),
+                ("mantle", "full", 1.0),
+            ],
+        ),
+        _miner(178, 708.3, 0.240, [("polygon", "arch", 700.0), ("tao", "full", 8.3)]),
+        _miner(237, 327.0, 0.111, [("bsc", "arch", 327.0)]),
+    ],
+}
+
+
+class _Resp:
+    def __init__(self, payload, status_code=200, text=""):
+        self._payload = payload
+        self.status_code = status_code
+        self.text = text
+
+    def json(self):
+        return self._payload
+
+
+class _Client:
+    calls: list[str] = []
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return None
+
+    def get(self, path, params=None):
+        _Client.calls.append(path)
+        return _Client.response
+
+
+def _run(monkeypatch, response, *args):
+    _Client.response = response
+    _Client.calls = []
+    monkeypatch.setattr(epoch_mod, "RegistryClient", _Client)
+    monkeypatch.setattr(epoch_mod, "load_config", lambda: None)
+    return runner.invoke(app, ["epoch", "payout", *args])
+
+
+def test_table_matches_the_signed_off_layout(monkeypatch):
+    result = _run(monkeypatch, _Resp(BODY))
+    assert result.exit_code == 0, result.output
+    assert _Client.calls == ["/epochs/latest/payout"]
+    out = result.output
+    assert out.startswith(
+        "Epoch 9075361 — finalized 16 Sep 20:22 UTC, paid out by the boundary "
+        "~17 Sep 20:22 UTC\n"
+    )
+    assert "α price $2.15   miner pool 2,952 α ($6,347)   3 miners paid" in out
+    assert " UID      alpha       USD   share   breakdown (chain/class → α)" in out
+    assert (
+        " 129      776.3     1,669   26.3%   tao/arch 197.3, polygon/arch 165.7, "
+        "base/arch 146.0, arbitrum/arch 95.6, eth/arch 43.1, robinhood/arch 34.8, "
+        "+2 more"
+    ) in out
+    assert (
+        " 178      708.3     1,523   24.0%   polygon/arch 700.0, tao/full 8.3\n" in out
+    )
+    assert "more miners" not in out  # three rows fit; nothing folded
+    assert "USD is an estimate" in out
+
+
+def test_long_tail_is_folded_into_one_line():
+    miners = [_miner(i, 100.0 - i, 0.01, [("tao", "arch", 1.0)]) for i in range(15)]
+    lines = epoch_mod.render_payout({**BODY, "miners": miners})
+    assert sum(1 for line in lines if line.startswith(" 1")) >= 1
+    fold = [line for line in lines if "more miners" in line]
+    assert fold == ["  …  3 more miners, 261.0 α between them"]
+    assert sum(1 for line in lines if line.startswith(" ") and "%" in line) == 12
+
+
+def test_epoch_option_targets_that_epoch(monkeypatch):
+    result = _run(monkeypatch, _Resp(BODY), "--epoch", "9068161")
+    assert result.exit_code == 0, result.output
+    assert _Client.calls == ["/epochs/9068161/payout"]
+
+
+def test_uid_shows_every_breakdown_line(monkeypatch):
+    result = _run(monkeypatch, _Resp(BODY), "--uid", "129")
+    assert result.exit_code == 0, result.output
+    out = result.output
+    assert f"UID 129  {HK}" in out
+    assert "776.3 α  ($1,669, 26.3% of the pool, 1,000 CU)" in out
+    for chain in ("tao", "polygon", "base", "arbitrum", "eth", "robinhood", "scroll"):
+        assert f"{chain}/arch" in out
+    assert "mantle/full" in out
+    assert "+" not in out.split("chain/class")[1]  # nothing elided
+
+
+def test_uid_not_paid_is_a_sentence(monkeypatch):
+    result = _run(monkeypatch, _Resp(BODY), "--uid", "5")
+    assert result.exit_code == 1
+    assert "UID 5 is not paid for epoch 9075361" in result.output
+
+
+def test_json_dumps_the_body_untouched(monkeypatch):
+    result = _run(monkeypatch, _Resp(BODY), "--json")
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.output) == BODY
+
+    result = _run(monkeypatch, _Resp(BODY), "--json", "--uid", "237")
+    assert json.loads(result.output) == BODY["miners"][2]
+
+
+def test_burn_epoch_says_so(monkeypatch):
+    body = {**BODY, "miners": [], "miner_count": 0, "burn_pct": 1.0}
+    result = _run(monkeypatch, _Resp(body))
+    assert result.exit_code == 0, result.output
+    assert "0 miners paid" in result.output
+    assert "the whole pool burns" in result.output
+
+
+def test_failure_statuses_get_a_sentence(monkeypatch):
+    result = _run(monkeypatch, _Resp({"detail": "not found"}, 404), "--epoch", "1")
+    assert result.exit_code == 1
+    assert "Epoch 1 is not finalized yet, or is unknown." in result.output
+
+    result = _run(monkeypatch, _Resp({"detail": "x"}, 503))
+    assert result.exit_code == 1
+    assert "not available on this registry" in result.output
+
+    result = _run(monkeypatch, _Resp({"detail": "epoch 5 has no price snapshot"}, 422))
+    assert result.exit_code == 1
+    assert "422 epoch 5 has no price snapshot" in result.output
+
+
+def test_zero_alpha_rows_never_render():
+    body = {**BODY, "miners": [*BODY["miners"], _miner(1, 0.0, 0.0, [])]}
+    lines = epoch_mod.render_payout(body)
+    assert not any(line.startswith(" 1 ") for line in lines)
+    assert "3 miners paid" in lines[1]
+
+
+def test_caveat_is_printed_when_the_registry_sends_one():
+    body = {**BODY, "caveat": "computed late"}
+    lines = epoch_mod.render_payout(body)
+    assert "Note: computed late." in lines
+    one = epoch_mod.render_miner(body, BODY["miners"][0])
+    assert "Note: computed late." in one
+    assert "miners paid" not in epoch_mod.render_miner(BODY, BODY["miners"][0])[-1]