DOC: Missing documentation for spending_proof validation boundary

[geldbert]

Issue Type: Documentation Gap / Potential Security Gap
Component: UTXO Layer (node/utxo_db.py)
Severity: Low (documentation) to Medium (if exploited)

Description:
The spending_proof field in transactions is accepted by the UTXO layer without any validation or parsing. While this is clearly intentional (signature verification happens at the endpoint layer), there's no documentation or code comments explaining this architectural decision.

In PR #2073, the test test_spending_proof_not_verified_in_utxo_layer explicitly documents this behavior with the comment: "The UTXO layer does NOT verify spending proofs — by design. Signature verification is the endpoint layer's responsibility."

Problem:
This architectural boundary is implied but not explicitly specified in the codebase. A future developer might:

1. Assume the UTXO layer validates proofs and introduce redundant validation
2. Rely on the UTXO layer for security properties it doesn't provide
3. Misunderstand where in the stack verification actually happens

Suggested Fix:

1. Add a comment in UTXODatabase.apply_transaction() at the spending_proof handling line
2. Consider adding a docstring to the class that explicitly notes: "This module handles UTXO state transitions only. Signature verification is the caller's responsibility."

Impact:
Better developer experience, reduced risk of security assumptions being violated.

References:

• Related test file: node/test_utxo_db.py test added in PR [UTXO-BUG] LOW: Duplicate input dedup, missing validations, and test coverage gaps #2073
• Code location: node/utxo_db.py around line 320 (post-PR merge)

[Scottcjn]

Valid observation. The spending_proof field is indeed accepted without validation at the UTXO layer -- signature verification happens at the endpoint layer as an intentional architectural separation. A code comment documenting this decision would be a good contribution. If you want to submit a PR adding that documentation, 5 RTC for the fix.

[Scottcjn]

Good catch — spending_proof validation documentation is missing from the UTXO reference. This is a real gap.

The spending_proof flow is: Ed25519 signature over the canonical input box ID + output commitments, verified in validate_spending_proofs() in utxo_db.py. Documentation should cover the canonical serialization format and the verification algorithm.

Would you like to submit a PR documenting this? 3-5 RTC for a clear technical doc.

[geldbert]

PR submitted: #2180 — adds architectural boundary documentation for spending_proof validation in node/utxo_db.py