v431 release

sdk/python/bittensor/cli/main.py

@@ -22,6 +22,7 @@
 from .. import __version__, wallets
 from .._generated.errors import ERRORS
 from ..config import get as config_default
+from ..error_descriptions import DESCRIPTIONS
 from ..intents import list_tools
 from ..result import EXPLANATIONS, REMEDIATION, ErrorCode, classify_error
 from ..settings import DEFAULT_NETWORK
@@ -326,6 +327,7 @@ def _chain_error_matches(query: str) -> list[dict[str, str]]:
                 "name": info.name,
                 "code": code.value,
                 "docs": info.docs,
+                "description": DESCRIPTIONS.get(info.name, ""),
                 "help": REMEDIATION[code],
             }
         )

sdk/python/bittensor/cli/output.py

@@ -1496,6 +1496,8 @@ def _print_failure(self, result: ExtrinsicResult) -> None:
             return
         if error.name:
             self._sub_diag("note", f"the chain rejected the call with `{error.name}`")
+        if error.description:
+            self._sub_diag("note", error.description)
         self._sub_diag("help", error.remediation)
         if result.explorer_url:
             self._sub_diag("see", result.explorer_url)
@@ -1554,8 +1556,10 @@ def error_catalog(self, title: str, records: list[dict[str, str]]) -> None:
         self._out.print(f"[dim]{len(records)} {suffix}[/dim]")
 
     def explain_chain(self, matches: list[dict[str, str]]) -> None:
-        """Explain exact chain error names: the on-chain docs plus the semantic
-        code each classifies to. One block per pallet when a name collides."""
+        """Explain exact chain error names: the researched description (trigger
+        plus where to check) with the on-chain docs as fallback, and the
+        semantic code each classifies to. One block per pallet when a name
+        collides."""
         if self.json_mode:
             self._json(matches[0] if len(matches) == 1 else matches)
             return
@@ -1568,7 +1572,8 @@ def explain_chain(self, matches: list[dict[str, str]]) -> None:
             header.append(f"{match['pallet']}.{match['name']}")
             self._out.print(header)
             self._out.print()
-            self._out.print(_prose(_diagnostic(match["docs"] or match["name"])))
+            body = match.get("description") or match["docs"] or match["name"]
+            self._out.print(_prose(_diagnostic(body)))
             self._out.print()
             self._sub_diag("help", match["help"], console=self._out)
         for code in dict.fromkeys(match["code"] for match in matches):

sdk/python/bittensor/result.py

@@ -12,6 +12,7 @@
 from typing import Any, Optional
 
 from ._generated.errors import ERRORS
+from .error_descriptions import DESCRIPTIONS as _DESCRIPTIONS
 from .error_map import NAME_TO_CODE as _NAME_TO_CODE
 from .error_map import ErrorCode
 
@@ -311,13 +312,23 @@ def remediation(self) -> str:
                 return help_text
         return REMEDIATION[self.code]
 
+    @property
+    def description(self) -> Optional[str]:
+        """What triggered this exact chain error and where to check, from the
+        per-name table in :mod:`bittensor.error_descriptions`. ``None`` when the
+        failure carried no module error name (e.g. a pool rejection)."""
+        return _DESCRIPTIONS.get(self.name) if self.name else None
+
     def to_dict(self) -> dict[str, Any]:
-        return {
+        payload = {
             "message": self.message,
             "name": self.name,
             "code": self.code.value,
             "remediation": self.remediation,
         }
+        if self.description:
+            payload["description"] = self.description
+        return payload
 
 
 def chain_error_from_substrate_request(error: Exception) -> ChainError:

sdk/python/codegen/check.py

@@ -329,24 +329,37 @@ def check_coverage() -> int:
 
 def check_names() -> int:
     from bittensor._generated.errors import ERRORS
+    from bittensor.error_descriptions import DESCRIPTIONS
     from bittensor.error_map import NAME_TO_CODE, ErrorCode
     from bittensor.result import classify_error
 
     catalog = {info.name for info in ERRORS.values()}
     stale = sorted(name for name in NAME_TO_CODE if name not in catalog)
     unclassified = sorted(name for name in catalog if classify_error("", name) is ErrorCode.UNKNOWN)
+    undescribed = sorted(name for name in NAME_TO_CODE if name not in DESCRIPTIONS)
+    orphan_descriptions = sorted(name for name in DESCRIPTIONS if name not in NAME_TO_CODE)
     if stale:
         print(f"STALE: error names classified by the SDK but absent from chain: {stale}")
     if unclassified:
         print(
             "UNCLASSIFIED: chain error names with no semantic code "
             f"(add them to bittensor/error_map.py): {unclassified}"
         )
-    if stale or unclassified:
+    if undescribed:
+        print(
+            "UNDESCRIBED: classified error names with no description "
+            f"(add them to bittensor/error_descriptions.py): {undescribed}"
+        )
+    if orphan_descriptions:
+        print(
+            "ORPHANED: described error names no longer classified "
+            f"(remove them from bittensor/error_descriptions.py): {orphan_descriptions}"
+        )
+    if stale or unclassified or undescribed or orphan_descriptions:
         return 1
     print(
-        f"names ok: all {len(catalog)} chain error names classify to a semantic code "
-        "and no mapped name is stale"
+        f"names ok: all {len(catalog)} chain error names classify to a semantic code, "
+        "every classified name is described, and no mapped name is stale"
     )
     return 0