diff --git a/docs/evidence/ste-50-tokens-error-names-2026-09-17.json b/docs/evidence/ste-50-tokens-error-names-2026-09-17.json new file mode 100644 index 0000000..c6c0611 --- /dev/null +++ b/docs/evidence/ste-50-tokens-error-names-2026-09-17.json @@ -0,0 +1,20 @@ +{ + "ticket": "STE-50", + "date": "2026-09-17", + "network": "testnet", + "tokens_contract": "CB6VK4EXEN7V6MXLOFUI2ECMLSDUXAUV5EZICWBICKJDL3WPPU3CTP3T", + "method": "read-only simulate against Tokens v2 of two calls the contract must refuse; nothing signed", + "calls": [ + { + "call": "mint_license(GAISQEDZDZO3ZODO6DRDD3DV5VKMVNOULTU7B4VASXSXH56BUOAIPXAG, com.fixtures.demo.release-notes, 2.0.0)", + "why_refused": "release-notes 2.0.0 is DANGEROUS on Registry v2, so it has no VERIFIED badge", + "main_before_fix": "mint_license failed: VersionAlreadyExists (#5, registry)", + "this_branch": "mint_license failed: NotVerified (#5, tokens)" + }, + { + "call": "mint_verified(com.fixtures.demo.release-notes, 2.0.0, GD73M4F7RN74KBLFGJP4WKBMCBJWBOA4SFNOP5HG4NBCDQUQCC2ARSZU)", + "why_refused": "the version is not SAFE", + "this_branch": "mint_verified failed: NotSafeVerdict (#4, tokens)" + } + ] +} diff --git a/pipeline/src/sterish_pipeline/onchain.py b/pipeline/src/sterish_pipeline/onchain.py index ef063e9..2d090a6 100644 --- a/pipeline/src/sterish_pipeline/onchain.py +++ b/pipeline/src/sterish_pipeline/onchain.py @@ -46,10 +46,22 @@ # once the caller says which contract answered: escrow #3 is NotOpen, registry #3 # is SkillNotFound. Labelling everything with the registry's names (as this module # first did) turns a real escrow failure into "Unknown". +# contracts/registry/src/data.rs::RegistryError (10-13 added by STE-44) REGISTRY_ERRORS = { 1: "NotInitialized", 2: "NotAuthorized", 3: "SkillNotFound", 4: "VersionNotFound", 5: "VersionAlreadyExists", 6: "HashAlreadyRegistered", 7: "InvalidInput", 8: "InvalidTrustScore", 9: "InvalidVerdict", + 10: "UpgradeabilityRenounced", 11: "NoPendingUpgrade", 12: "UpgradeAlreadyPending", + 13: "UpgradeNotReady", +} + +# contracts/tokens/src/data.rs::TokenError (STE-50). Before this table existed, a Tokens +# refusal was named from the registry's table: mint_license #5 NotVerified — the gate +# refusing to licence a DANGEROUS version — read as "VersionAlreadyExists". +TOKENS_ERRORS = { + 1: "NotInitialized", 2: "TokenNotFound", 3: "AlreadyMinted", 4: "NotSafeVerdict", + 5: "NotVerified", 6: "InvalidInput", 7: "UpgradeabilityRenounced", + 8: "NoPendingUpgrade", 9: "UpgradeAlreadyPending", 10: "UpgradeNotReady", } # contracts/escrow/src/data.rs @@ -69,7 +81,40 @@ ERROR_TABLES = { "registry": REGISTRY_ERRORS, "escrow": ESCROW_ERRORS, + "tokens": TOKENS_ERRORS, +} + +# Entrypoints per contract, from each contract's `pub fn` list. A name that belongs to one +# contract resolves by itself; a name several contracts export (`get_admin`, the STE-44 +# upgrade functions) cannot, so the caller has to say which contract it called. +_ENTRYPOINTS = { + "registry": ( + "register_skill", "submit_verdict", "lookup_by_hash", "get_version", "get_latest", + "is_verified", "query_skill", "query_all_skills", "set_auditor", + "update_trust_score_config", "get_trust_score_config", "get_auditor", "get_admin", + "get_skill_count", + ), + "tokens": ( + "mint_verified", "mint_license", "has_license", "is_verified_token", "owner_of", + "get_token", "total_supply", "get_admin", "get_registry", "get_auditor_role", + "get_minter_role", "set_auditor_role", "set_minter_role", + ), + "escrow": ( + "create_audit_request", "post_bond", "settle", "slash", "claim_forfeited", + "get_request", "get_usdc_token", "get_admin", "get_request_count", + ), } +_UPGRADE_ENTRYPOINTS = ( + "propose_upgrade", "execute_upgrade", "cancel_upgrade", "renounce_upgradeability", + "get_pending_upgrade", "get_upgrade_delay", "is_upgradeable", +) +_ENTRYPOINTS["registry"] += _UPGRADE_ENTRYPOINTS +_ENTRYPOINTS["tokens"] += _UPGRADE_ENTRYPOINTS + + +def contracts_exporting(function: str) -> tuple[str, ...]: + """Which of our contracts export `function`, in a stable order.""" + return tuple(name for name, fns in _ENTRYPOINTS.items() if function in fns) class OnChainError(Exception): @@ -84,17 +129,21 @@ class ContractCallError(OnChainError): reports the SAC's meaning when that is what came back. """ - _FUNCTION_CONTRACT = { - "register_skill": "registry", "submit_verdict": "registry", - "query_skill": "registry", "get_version": "registry", - "lookup_by_hash": "registry", "is_verified": "registry", - "create_audit_request": "escrow", "post_bond": "escrow", - "settle": "escrow", "slash": "escrow", "claim_forfeited": "escrow", - } - def __init__(self, code: int, function: str, raw: str = "", contract: str | None = None): - which = contract or self._FUNCTION_CONTRACT.get(function, "registry") - name = ERROR_TABLES.get(which, {}).get(code) or SAC_ERRORS.get(code) or "Unknown" + if contract is None: + owners = contracts_exporting(function) + # One owner: unambiguous. Several, or a function we do not know: say so, + # instead of silently borrowing the registry's names (the STE-50 bug). + contract = owners[0] if len(owners) == 1 else None + if contract is not None: + which = contract + name = ERROR_TABLES.get(which, {}).get(code) or SAC_ERRORS.get(code) or "Unknown" + else: + candidates = contracts_exporting(function) or tuple(ERROR_TABLES) + which = "contract not identified" + name = " / ".join( + f"{c} {ERROR_TABLES[c].get(code, 'Unknown')}" for c in candidates + ) super().__init__(f"{function} failed: {name} (#{code}, {which})") self.code = code self.function = function @@ -119,10 +168,10 @@ def _decode(xdr_str: str) -> Any: return scval.to_native(stellar_xdr.SCVal.from_xdr(xdr_str)) -def _raise_for_error(error: Any, function: str) -> None: +def _raise_for_error(error: Any, function: str, contract: str | None = None) -> None: match = _CONTRACT_ERR_RE.search(str(error)) if match: - raise ContractCallError(int(match.group(1)), function, str(error)) + raise ContractCallError(int(match.group(1)), function, str(error), contract) raise OnChainError(f"{function} simulation failed: {error}") @@ -153,8 +202,18 @@ def hash_scval(hex_hash: str) -> stellar_xdr.SCVal: # --- reads ------------------------------------------------------------------ -def simulate(cfg: PipelineConfig, contract_id: str, function: str, args: list | None = None) -> Any: - """Read-only contract call. Returns the decoded native value.""" +def simulate( + cfg: PipelineConfig, + contract_id: str, + function: str, + args: list | None = None, + *, + contract: str | None = None, +) -> Any: + """Read-only contract call. Returns the decoded native value. + + `contract` ("registry" / "tokens" / "escrow") names which ABI a typed error is read + against; only needed for a function several contracts export.""" try: tx = ( TransactionBuilder(Account(NULL_ACCOUNT, 0), cfg.network_passphrase, base_fee=100) @@ -167,7 +226,7 @@ def simulate(cfg: PipelineConfig, contract_id: str, function: str, args: list | raise OnChainError(f"RPC call to {function} failed: {exc}") from exc if sim.error: - _raise_for_error(sim.error, function) + _raise_for_error(sim.error, function, contract) if not sim.results: return None return _decode(sim.results[0].xdr) @@ -185,6 +244,7 @@ def invoke( *, timeout_s: int = 60, retries: int = 3, + contract: str | None = None, ) -> TxResult: """Sign, submit and confirm one contract call. Returns the transaction hash. @@ -198,7 +258,8 @@ def invoke( for attempt in range(1, retries + 1): try: return _invoke_once( - cfg, contract_id, function, args, keypair, timeout_s=timeout_s + cfg, contract_id, function, args, keypair, timeout_s=timeout_s, + contract=contract, ) except ContractCallError: raise @@ -233,6 +294,7 @@ def _invoke_once( keypair: Keypair, *, timeout_s: int, + contract: str | None = None, ) -> TxResult: server = _server(cfg) @@ -256,7 +318,7 @@ def _invoke_once( detail = _prepare_error_detail(exc) match = _CONTRACT_ERR_RE.search(detail) if match: - raise ContractCallError(int(match.group(1)), function, detail) from exc + raise ContractCallError(int(match.group(1)), function, detail, contract) from exc raise OnChainError(f"preparing {function} failed: {detail}") from exc prepared.sign(keypair) diff --git a/pipeline/tests/test_onchain_encoding.py b/pipeline/tests/test_onchain_encoding.py index 4e7afaf..d65c0fe 100644 --- a/pipeline/tests/test_onchain_encoding.py +++ b/pipeline/tests/test_onchain_encoding.py @@ -78,3 +78,96 @@ def test_sac_error_is_named_rather_than_reported_as_unknown(self): def test_an_unmapped_number_still_says_unknown(self): assert "Unknown" in str(onchain.ContractCallError(99, "settle")) + + +class TestTokensErrorNaming: + """STE-50: Tokens refusals were named from the registry's table.""" + + def test_mint_license_5_is_the_verified_gate_not_a_duplicate_version(self): + """Found by the STE-27 rehearsal: the contract refusing to licence a DANGEROUS + version was logged as `VersionAlreadyExists (#5, registry)`.""" + err = onchain.ContractCallError(5, "mint_license") + assert err.contract == "tokens" + assert str(err) == "mint_license failed: NotVerified (#5, tokens)" + + def test_mint_verified_4_is_not_safe_verdict(self): + err = onchain.ContractCallError(4, "mint_verified") + assert "NotSafeVerdict (#4, tokens)" in str(err) + + @pytest.mark.parametrize( + "function", ["has_license", "is_verified_token", "get_token", "total_supply", + "set_minter_role", "owner_of"], + ) + def test_every_tokens_entrypoint_resolves_to_the_tokens_abi(self, function): + assert onchain.ContractCallError(2, function).contract == "tokens" + + def test_the_tokens_table_matches_the_contract_source(self): + """The numbers are ABI; read them from the Rust enum instead of trusting a copy.""" + import re + from pathlib import Path + + src = (Path(__file__).resolve().parents[2] / "contracts/tokens/src/data.rs").read_text() + body = src[src.index("pub enum TokenError"):] + body = body[: body.index("}")] + from_rust = {int(n): name for name, n in re.findall(r"(\w+) = (\d+),", body)} + assert from_rust == onchain.TOKENS_ERRORS + + def test_the_registry_table_matches_the_contract_source(self): + """STE-44 added 10-13 to the registry; the table had stopped at 9.""" + import re + from pathlib import Path + + src = (Path(__file__).resolve().parents[2] / "contracts/registry/src/data.rs").read_text() + body = src[src.index("pub enum RegistryError"):] + body = body[: body.index("}")] + from_rust = {int(n): name for name, n in re.findall(r"(\w+) = (\d+),", body)} + assert from_rust == onchain.REGISTRY_ERRORS + + def test_the_escrow_table_matches_the_contract_source(self): + import re + from pathlib import Path + + src = (Path(__file__).resolve().parents[2] / "contracts/escrow/src/data.rs").read_text() + body = src[src.index("pub enum EscrowError"):] + body = body[: body.index("}")] + from_rust = {int(n): name for name, n in re.findall(r"(\w+) = (\d+),", body)} + assert from_rust == onchain.ESCROW_ERRORS + + +TOKENS_V2 = "CB6VK4EXEN7V6MXLOFUI2ECMLSDUXAUV5EZICWBICKJDL3WPPU3CTP3T" + + +class TestSharedEntrypoints: + """`get_admin` and the upgrade functions exist on several contracts.""" + + def test_a_shared_name_without_a_contract_says_it_cannot_tell(self): + msg = str(onchain.ContractCallError(11, "propose_upgrade")) + assert "contract not identified" in msg + assert "registry NoPendingUpgrade" in msg + assert "tokens Unknown" in msg # tokens has no #11: shown, not guessed away + + def test_naming_the_contract_resolves_a_shared_name(self): + err = onchain.ContractCallError(9, "propose_upgrade", contract="tokens") + assert str(err) == "propose_upgrade failed: UpgradeAlreadyPending (#9, tokens)" + + def test_an_unknown_function_is_not_labelled_as_registry(self): + err = onchain.ContractCallError(5, "some_future_fn") + assert err.contract == "contract not identified" + assert "registry VersionAlreadyExists" in str(err) + assert "tokens NotVerified" in str(err) + + def test_simulate_passes_the_named_contract_to_the_error(self, monkeypatch): + class Sim: + error = "HostError: Error(Contract, #10)" + results = None + + class Server: + def simulate_transaction(self, tx): + return Sim() + + monkeypatch.setattr(onchain, "_server", lambda cfg: Server()) + from sterish_pipeline.config import PipelineConfig + + with pytest.raises(onchain.ContractCallError) as info: + onchain.simulate(PipelineConfig(), TOKENS_V2, "execute_upgrade", contract="tokens") + assert "UpgradeNotReady (#10, tokens)" in str(info.value)