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
23 changes: 23 additions & 0 deletions docs/G5_8_HISTORICAL_REWARD_ENGINE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
90 changes: 66 additions & 24 deletions ghostnode/intelligence/reward_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -127,58 +127,93 @@ 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:
# Compatibility with legacy offline RPC doubles that predate gettxout.
# 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,
Expand All @@ -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] = []
Expand All @@ -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"
Expand Down
220 changes: 220 additions & 0 deletions tests/test_reward_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading