diff --git a/docs/G5_8_HISTORICAL_REWARD_ENGINE.md b/docs/G5_8_HISTORICAL_REWARD_ENGINE.md index 9050410..e14f568 100644 --- a/docs/G5_8_HISTORICAL_REWARD_ENGINE.md +++ b/docs/G5_8_HISTORICAL_REWARD_ENGINE.md @@ -41,6 +41,29 @@ The method is practical when `chain_blocks` or wallet history supplies a verified height, but it cannot recover transactions whose block location is not known and cannot prove completeness beyond the wallet-history limit. +## Reward normalization RPC cache + +Reward normalization may reuse successful verified prevout and +address classifications only within one call to `normalize_reward_transaction`. +Prevout reuse requires the TXID, VOUT, and verified block-context hash to match. +Address reuse requires the exact address and RPC result to be unambiguous. +Transient RPC failures, malformed prevout responses, INVALID classifications, +and missing `ismine`/ownership evidence are not cached. +Caches are local variables and are discarded after the block; they are never +persisted or shared across block plans, worker cycles, or normalization calls. + +The synthetic duplicate-prevout fixture previously made two `gettxout` calls +and four `getaddressinfo` calls for two repeated inputs and two repeated +outputs. The block-scoped cache reduces those repeated lookups while preserving +the normalized values and conservative evidence classifications. + +| Synthetic metric | Before | After | +|---|---:|---:| +| `gettxout` calls | 2 | 1 | +| `getaddressinfo` calls | 4 | 1 | +| `getrawtransaction` calls | 0 | 0 | +| Total RPC calls | 6 | 2 | + ## Tests Run the offline suite with: diff --git a/ghostnode/intelligence/reward_adapter.py b/ghostnode/intelligence/reward_adapter.py index 2d89030..c349425 100644 --- a/ghostnode/intelligence/reward_adapter.py +++ b/ghostnode/intelligence/reward_adapter.py @@ -127,25 +127,46 @@ def _addresses(script: dict[str, Any] | None, key: str) -> tuple[str, ...]: return tuple(value for value in values if isinstance(value, str)) if isinstance(values, list) else () -def _ownership(rpc: RPC, addresses: tuple[str, ...]) -> tuple[OwnershipStatus, str | None]: +def _ownership(rpc: RPC, addresses: tuple[str, ...], + address_cache: dict[str, tuple[OwnershipStatus, str | None]] | None = None) -> tuple[OwnershipStatus, str | None]: if not addresses: return OwnershipStatus.UNKNOWN, None saw_unknown = False for address in addresses: - info, error = rpc("getaddressinfo", [address]) - if error or not isinstance(info, dict): - saw_unknown = True - continue - if info.get("ismine") is True: - return OwnershipStatus.CONFIRMED, "getaddressinfo.ismine" - if info.get("ismine") is False: - continue - saw_unknown = True + cached = address_cache.get(address) if address_cache is not None else None + if cached is not None: + status, source = cached + else: + info, error = rpc("getaddressinfo", [address]) + if error or not isinstance(info, dict): + saw_unknown = True + continue + if info.get("ismine") is True: + status, source = OwnershipStatus.CONFIRMED, "getaddressinfo.ismine" + if address_cache is not None: + address_cache[address] = (status, source) + elif info.get("ismine") is False: + status, source = OwnershipStatus.NOT_OWNED, "getaddressinfo" + if address_cache is not None: + address_cache[address] = (status, source) + else: + saw_unknown = True + continue + if status is OwnershipStatus.CONFIRMED: + return OwnershipStatus.CONFIRMED, source return (OwnershipStatus.UNKNOWN if saw_unknown else OwnershipStatus.NOT_OWNED), "getaddressinfo" def _prevout(rpc: RPC, txid: str, vout: int, - block_context: dict[str, str] | None = None) -> tuple[int | None, dict[str, Any] | None, OwnershipStatus, str | None]: + block_context: dict[str, str] | None = None, + prevout_cache: dict[tuple[str, int, str | None], tuple[int | None, dict[str, Any] | None, OwnershipStatus, str | None]] | None = None, + address_cache: dict[str, tuple[OwnershipStatus, str | None]] | None = None) -> tuple[int | None, dict[str, Any] | None, OwnershipStatus, str | None]: + context_hash = block_context.get(txid) if isinstance(block_context, dict) else None + cache_key = (txid, vout, context_hash) + if prevout_cache is not None: + cached = prevout_cache.get(cache_key) + if cached is not None: + return cached try: result = PrevoutResolver(rpc).resolve(txid, vout, block_context) except AssertionError: @@ -153,32 +174,46 @@ def _prevout(rpc: RPC, txid: str, vout: int, # Production callers use the verified block context and never take this # path; an actual RPC failure is not converted into a fallback. if block_context is not None: - return None, None, OwnershipStatus.UNKNOWN, None + resolved = (None, None, OwnershipStatus.UNKNOWN, None) + return resolved transaction, error = rpc("getrawtransaction", [txid, 1]) if error or not isinstance(transaction, dict) or transaction.get("txid") not in (None, txid): - return None, None, OwnershipStatus.UNKNOWN, None + resolved = (None, None, OwnershipStatus.UNKNOWN, None) + return resolved outputs = transaction.get("vout") if not isinstance(outputs, list) or not 0 <= vout < len(outputs) or not isinstance(outputs[vout], dict): - return None, None, OwnershipStatus.UNKNOWN, None + resolved = (None, None, OwnershipStatus.UNKNOWN, None) + return resolved output = outputs[vout] script = output.get("scriptPubKey") if isinstance(output.get("scriptPubKey"), dict) else None value = _atomic(output.get("value")) - ownership, source = _ownership(rpc, _addresses(script, "addresses")) - return value, script, ownership, source + ownership, source = _ownership(rpc, _addresses(script, "addresses"), address_cache) + resolved = (value, script, ownership, source) + if value is not None and prevout_cache is not None: + prevout_cache[cache_key] = resolved + return resolved if result.status is not PrevoutStatus.VERIFIED or not isinstance(result.transaction, dict): - return None, None, OwnershipStatus.UNKNOWN, result.source + resolved = (None, None, OwnershipStatus.UNKNOWN, result.source) + return resolved if result.source == "gettxout": script = result.transaction.get("scriptPubKey") script = script if isinstance(script, dict) else None - ownership, source = _ownership(rpc, _addresses(script, "addresses")) - return _atomic(result.value), script, ownership, source or result.source + ownership, source = _ownership(rpc, _addresses(script, "addresses"), address_cache) + resolved = (_atomic(result.value), script, ownership, source or result.source) + if resolved[0] is not None and prevout_cache is not None: + prevout_cache[cache_key] = resolved + return resolved outputs = result.transaction.get("vout") if not isinstance(outputs, list) or not 0 <= vout < len(outputs) or not isinstance(outputs[vout], dict): - return None, None, OwnershipStatus.UNKNOWN, result.source + resolved = (None, None, OwnershipStatus.UNKNOWN, result.source) + return resolved output = outputs[vout] script = output.get("scriptPubKey") if isinstance(output.get("scriptPubKey"), dict) else None - ownership, source = _ownership(rpc, _addresses(script, "addresses")) - return _atomic(result.value), script, ownership, source or result.source + ownership, source = _ownership(rpc, _addresses(script, "addresses"), address_cache) + resolved = (_atomic(result.value), script, ownership, source or result.source) + if resolved[0] is not None and prevout_cache is not None: + prevout_cache[cache_key] = resolved + return resolved def normalize_reward_transaction(block: dict[str, Any], rpc: RPC, @@ -190,12 +225,19 @@ def normalize_reward_transaction(block: dict[str, Any], rpc: RPC, empty = attribute_reward([], []) return NormalizedRewardTransaction(None, None, None, (), (), EvidenceStatus.UNKNOWN, empty) + prevout_cache: dict[tuple[str, int, str | None], + tuple[int | None, dict[str, Any] | None, OwnershipStatus, str | None]] = {} + address_cache: dict[str, tuple[OwnershipStatus, str | None]] = {} + normalized_inputs: list[NormalizedInput] = [] for item in tx.get("vin", []): if not isinstance(item, dict) or not isinstance(item.get("txid"), str) or not isinstance(item.get("vout"), int): normalized_inputs.append(NormalizedInput(None, None, None, None, OwnershipStatus.UNKNOWN, None, EvidenceStatus.UNKNOWN)) continue - value, script, owner, source = _prevout(rpc, item["txid"], item["vout"], block_context) + value, script, owner, source = _prevout( + rpc, item["txid"], item["vout"], block_context, + prevout_cache, address_cache, + ) normalized_inputs.append(NormalizedInput(item["txid"], item["vout"], value, script, owner, source, EvidenceStatus.VERIFIED if value is not None else EvidenceStatus.UNKNOWN)) normalized_outputs: list[NormalizedOutput] = [] @@ -206,7 +248,7 @@ def normalize_reward_transaction(block: dict[str, Any], rpc: RPC, data_output = _is_ghost_data_output(item) addresses = _addresses(script, "addresses") owner, source = ((OwnershipStatus.UNKNOWN, "getblock") if data_output - else _ownership(rpc, addresses)) + else _ownership(rpc, addresses, address_cache)) output_class = item.get("output_class") if isinstance(item.get("output_class"), str) else None if output_class is None: output_class = "data" if data_output else "unknown" diff --git a/tests/test_reward_adapter.py b/tests/test_reward_adapter.py index 065688d..911a761 100644 --- a/tests/test_reward_adapter.py +++ b/tests/test_reward_adapter.py @@ -120,3 +120,223 @@ def rpc(method, args): assert result.outputs[0].output_class == "data" assert result.outputs[0].value_atomic is None assert result.attribution.completeness is DataCompleteness.COMPLETE + + +def test_duplicate_prevouts_and_addresses_use_block_scoped_rpc_cache(): + prev_tx = "a" * 64 + block = { + "hash": "b", + "height": 10, + "tx": [{ + "txid": "c" * 64, + "vin": [{"txid": prev_tx, "vout": 0}, {"txid": prev_tx, "vout": 0}], + "vout": [ + {"n": 0, "value": 10, "scriptPubKey": {"addresses": ["mine"]}}, + {"n": 1, "value": 1, "scriptPubKey": {"addresses": ["mine"]}}, + ], + }], + } + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return {"value": 10, "scriptPubKey": {"addresses": ["mine"]}}, None + if method == "getaddressinfo": + return {"ismine": True}, None + raise AssertionError(method) + + result = normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("gettxout") == 1 + assert [method for method, _ in calls].count("getaddressinfo") == 1 + assert [method for method, _ in calls].count("getrawtransaction") == 0 + assert len(calls) == 2 + assert len(result.inputs) == 2 + assert all(item.value_atomic == 1_000_000_000 for item in result.inputs) + + +def test_unique_prevouts_and_addresses_are_not_deduplicated(): + block = { + "tx": [{ + "txid": "t", + "vin": [ + {"txid": "a" * 64, "vout": 0}, + {"txid": "b" * 64, "vout": 1}, + ], + "vout": [ + {"n": 0, "value": 10, "scriptPubKey": {"addresses": ["mine-a"]}}, + {"n": 1, "value": 10, "scriptPubKey": {"addresses": ["mine-b"]}}, + ], + }], + } + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return {"value": 10, "scriptPubKey": {"addresses": [f"mine-{len(calls)}"]}}, None + if method == "getaddressinfo": + return {"ismine": True}, None + raise AssertionError(method) + + normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("gettxout") == 2 + assert [method for method, _ in calls].count("getaddressinfo") >= 2 + + +def test_cache_isolated_between_normalization_calls(): + prev_tx = "a" * 64 + block = {"tx": [{ + "txid": "t", + "vin": [{"txid": prev_tx, "vout": 0}], + "vout": [{"n": 0, "value": 10, "scriptPubKey": {"addresses": ["mine"]}}], + }]} + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return {"value": 10, "scriptPubKey": {"addresses": ["mine"]}}, None + if method == "getaddressinfo": + return {"ismine": True}, None + raise AssertionError(method) + + normalize_reward_transaction(block, rpc) + normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("gettxout") == 2 + assert [method for method, _ in calls].count("getaddressinfo") == 2 + + +def test_duplicate_historical_prevout_reuses_verified_transaction(): + prev_tx = "a" * 64 + prev_block = "b" * 64 + block = {"tx": [{ + "txid": "t", + "vin": [{"txid": prev_tx, "vout": 0}, {"txid": prev_tx, "vout": 0}], + "vout": [{"n": 0, "value": 10, "scriptPubKey": {"addresses": ["external"]}}], + }]} + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return None, None + if method == "getrawtransaction": + return {"txid": prev_tx, "blockhash": prev_block, + "vout": [{"value": 10, "scriptPubKey": {"addresses": ["external"]}}]}, None + if method == "getaddressinfo": + return {"ismine": False}, None + raise AssertionError(method) + + result = normalize_reward_transaction(block, rpc, {prev_tx: prev_block}) + + assert [method for method, _ in calls].count("gettxout") == 1 + assert [method for method, _ in calls].count("getrawtransaction") == 1 + assert [method for method, _ in calls].count("getaddressinfo") == 1 + assert all(item.value_atomic == 1_000_000_000 for item in result.inputs) + + +def test_ambiguous_address_result_remains_unknown(): + block = {"tx": [{ + "txid": "t", + "vin": [], + "vout": [ + {"n": 0, "value": 10, "scriptPubKey": {"addresses": ["ambiguous"]}}, + {"n": 1, "value": 10, "scriptPubKey": {"addresses": ["ambiguous"]}}, + ], + }]} + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return {"value": 10, "scriptPubKey": {"addresses": ["ambiguous"]}}, None + if method == "getaddressinfo": + return {"ismine": None, "solvable": None}, None + raise AssertionError(method) + + result = normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("getaddressinfo") == 2 + assert all(output.ownership_status is OwnershipStatus.UNKNOWN for output in result.outputs) + + +def test_transient_address_error_is_retried_and_not_cached(): + block = {"tx": [{ + "txid": "t", + "vin": [], + "vout": [ + {"n": 0, "value": 10, "scriptPubKey": {"addresses": ["recovering"]}}, + {"n": 1, "value": 10, "scriptPubKey": {"addresses": ["recovering"]}}, + ], + }]} + calls = [] + address_results = iter((("RPC temporary failure", True), ({"ismine": False}, False))) + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return {"value": 10, "scriptPubKey": {"addresses": ["recovering"]}}, None + if method == "getaddressinfo": + result, is_error = next(address_results) + return (None, result) if is_error else (result, None) + raise AssertionError(method) + + result = normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("getaddressinfo") == 2 + assert result.outputs[0].ownership_status is OwnershipStatus.UNKNOWN + assert result.outputs[1].ownership_status is OwnershipStatus.NOT_OWNED + + +def test_malformed_invalid_prevout_is_retried_not_cached(): + prev_tx = "a" * 64 + block = {"tx": [{ + "txid": "t", + "vin": [{"txid": prev_tx, "vout": 0}, {"txid": prev_tx, "vout": 0}], + "vout": [], + }]} + calls = [] + malformed = {"value": -1, "scriptPubKey": {"addresses": []}} + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return malformed, None + raise AssertionError(method) + + result = normalize_reward_transaction(block, rpc) + + assert [method for method, _ in calls].count("gettxout") == 2 + assert all(item.value_atomic is None for item in result.inputs) + assert all(item.ownership_status is OwnershipStatus.UNKNOWN for item in result.inputs) + + +def test_distinct_verified_block_context_hashes_do_not_share_prevout_cache(): + prev_tx = "a" * 64 + block = {"tx": [{ + "txid": "t", + "vin": [{"txid": prev_tx, "vout": 0}], + "vout": [], + }]} + calls = [] + + def rpc(method, args): + calls.append((method, args)) + if method == "gettxout": + return None, None + if method == "getrawtransaction": + blockhash = args[2] + return {"txid": prev_tx, "blockhash": blockhash, + "vout": [{"value": 10 if blockhash == "b" * 64 else 20}]}, None + raise AssertionError(method) + + first = normalize_reward_transaction(block, rpc, {prev_tx: "b" * 64}) + second = normalize_reward_transaction(block, rpc, {prev_tx: "c" * 64}) + + assert [method for method, _ in calls].count("getrawtransaction") == 2 + assert first.inputs[0].value_atomic == 1_000_000_000 + assert second.inputs[0].value_atomic == 2_000_000_000