UTXOracle Kotlin Port: Parity Proof against Python v9.1

[FreeOnlineUser]

UTXOracle Kotlin Port — Parity Proof

This documents and proves that the Kotlin port of UTXOracle v9.1 in Bitcoin Pocket Node produces identical results to the original Python implementation by @stevesimple (@Unbesteveable).

Test Results

Tested against 144 real blocks (heights 937,665 to 937,808), processing 66,647 filtered transaction outputs:

Algorithm Step	Python	Kotlin	Match
Step 9 — Rough price estimate	$67,981	$67,981	✅
Step 10 — Filtered output count	59,274	59,274	✅
Step 11 — Final price (iterative convergence)	$68,170	$68,170	✅

Every intermediate value is identical. The Kotlin port is a faithful, line-for-line translation of Steps 5-11 of UTXOracle v9.1.

How to Reproduce

1. Generate test vectors (requires a Bitcoin node with RPC access):

cd tests/
python3 gen_vectors.py --rpcuser YOUR_USER --rpcpass YOUR_PASS --rpcport 8332
cp oracle_test_vectors.json ../app/src/test/resources/

This runs the Python UTXOracle algorithm (Steps 5-11) against real block data and saves the filtered outputs + expected prices as JSON.

2. Run the Kotlin parity test:

./gradlew testDebugUnitTest --tests "com.pocketnode.oracle.UTXOracleParityTest"

This feeds the same filtered outputs to the Kotlin implementation and asserts that rough price, output count, and final price match the Python output exactly (integer-level precision).

What the Test Verifies

The test is structured as a shared-input comparison:

1. gen_vectors.py fetches 144 blocks via RPC, applies the Python filtering logic (Step 6: coinbase removal, witness size checks, same-day tx detection, OP_RETURN filtering), and runs Steps 5-11 to produce a price
2. The filtered outputs are saved to JSON (66,647 doubles)
3. UTXOracleParityTest.kt reads those same outputs and runs the identical Steps 5-11 in Kotlin
4. The test asserts exact equality at three checkpoints: rough price, output count, and final price

This proves the core algorithm (histogram construction, stencil sliding, rough estimation, micro-round removal, iterative center-finding) is identical between implementations.

Source Files

• Kotlin implementation: app/src/main/java/com/pocketnode/oracle/UTXOracle.kt (815 lines)
• Parity test: app/src/test/java/com/pocketnode/oracle/UTXOracleParityTest.kt
• Vector generator: tests/gen_vectors.py
• License compliance: LICENSES/UTXORACLE-LICENSE.md (UTXOracle License v1.0)

About Bitcoin Pocket Node

Bitcoin Pocket Node turns an Android phone into a fully-validating Bitcoin full node. UTXOracle provides sovereign, exchange-free price discovery directly from on-chain data, with no external API calls.

YouTube explanation of UTXOracle: https://www.youtube.com/watch?v=LZgyVMFYo1U

---

UTXOracle is created by @stevesimple. The canonical name "UTXOracle" and all references comply with the UTXOracle License v1.0.