Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/evidence/ste-50-tokens-error-names-2026-09-17.json
Original file line number Diff line number Diff line change
@@ -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)"
}
]
}
96 changes: 79 additions & 17 deletions pipeline/src/sterish_pipeline/onchain.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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):
Expand All @@ -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
Expand All @@ -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}")


Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -233,6 +294,7 @@ def _invoke_once(
keypair: Keypair,
*,
timeout_s: int,
contract: str | None = None,
) -> TxResult:
server = _server(cfg)

Expand All @@ -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)
Expand Down
93 changes: 93 additions & 0 deletions pipeline/tests/test_onchain_encoding.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading