Reticulum/tests/stamps.py
2026-10-29 16:49:39 +01:00

469 lines
20 KiB
Python

# Generated with lc/glm5.3_flash_q6_k_xl
# Reviewed and approved by Mark Qvist
import unittest
import os
import time
import math
import random
import shutil
import tempfile
import threading
from unittest import skipIf
import RNS
from RNS import Stamps
import RNS.vendor.umsgpack as msgpack
# The stamper itself is intentionally seeded from os.urandom, but the
# value and target layers are pure deterministic math. Seeded test
# vectors therefore make the statistical tests exact and repeatable
# on any platform and any hash backend.
rng = random.Random(28411)
def rb(n):
return bytes(rng.getrandbits(8) for _ in range(n))
def fp_of(value):
# stamp_value returns cost_from_fp(value_fp), and division by
# COST_FP (a power of two) is exact in binary floating point,
# so the fixed-point representation can be recovered losslessly.
fp = round(value * Stamps.COST_FP)
assert fp == int(value * Stamps.COST_FP)
return fp
class TestStampFixedPoint(unittest.TestCase):
@classmethod
def setUpClass(cls):
# A shared pool of deterministic workblock/stamp samples,
# used to lock in the value layer invariants.
cls.samples = []
for _ in range(3000):
wb = rb(rng.randint(0, 48))
stamp = rb(rng.choice((RNS.Identity.STAMPLENGTH, Stamps.STAMP_SIZE)))
hn = int.from_bytes(RNS.Identity.full_hash(wb+stamp), byteorder="big")
vleg = Stamps.stamp_value_legacy(wb, stamp)
v = Stamps.stamp_value(wb, stamp)
exact = 256 - math.log2(hn)
cls.samples.append((wb, stamp, hn, vleg, v, exact))
def test_00_fixed_point_conversions(self):
cap = RNS.Transport.STAMP_COST_CAP
for cost in range(0, cap+1):
self.assertEqual(Stamps.cost_to_fp(cost), cost*Stamps.COST_FP)
self.assertEqual(Stamps.cost_from_fp(Stamps.cost_to_fp(cost)), cost)
self.assertEqual(Stamps.cost_to_fp(8.5), 8.5*Stamps.COST_FP)
self.assertEqual(Stamps.cost_from_fp(8.5*Stamps.COST_FP), 8.5)
self.assertEqual(Stamps.cost_to_fp(0.5), 128)
self.assertEqual(Stamps.cost_to_fp(-1), 0)
self.assertEqual(Stamps.cost_to_fp(cap+1), cap*Stamps.COST_FP)
for fp in list(range(0, 65536, 97)) + [0, 255, 256, 65535]:
packed = Stamps.fp_to_bytes(fp)
self.assertEqual(len(packed), 2)
self.assertEqual(Stamps.fp_from_bytes(packed), fp)
for cost in (0, 1, 4, 8.5, 64, 100):
self.assertEqual(Stamps.cost_from_bytes(Stamps.cost_to_bytes(cost)), cost)
self.assertEqual(Stamps.cost_int(8*Stamps.COST_FP + 128), 8)
self.assertEqual(Stamps.cost_str(8*Stamps.COST_FP), "8")
self.assertEqual(Stamps.cost_str(8*Stamps.COST_FP + 128), "8.5")
self.assertEqual(Stamps.cost_str(0), "0")
def test_01_target_for_integer_costs(self):
cap = RNS.Transport.STAMP_COST_CAP
for cost in range(0, cap+1):
self.assertEqual(Stamps.target_from_cost(cost), 2**(256-cost))
self.assertEqual(Stamps.target_from_fp(0), 2**256)
self.assertRaises(AssertionError, Stamps.target_from_fp, -1)
self.assertRaises(AssertionError, Stamps.target_from_fp, cap*Stamps.COST_FP + 1)
def test_02_target_monotonic_and_exact(self):
# Targets must strictly decrease as cost increases
cap = RNS.Transport.STAMP_COST_CAP
last = None
for fp in range(0, cap*Stamps.COST_FP + 1):
target = Stamps.target_from_fp(fp)
if last != None:
self.assertLess(target, last)
last = target
# Independent verification of the whole mantissa/shift
# construction against floor(2^(256 - fp/256)), computed
# with exact integer arithmetic: The 256th root of
# 2^(33*256+f), obtained by a Newton iteration, is exactly
# floor(2^(33+f/256)), and shifting by the integer part of
# the exponent yields the exact target for every step.
def iroot(n, k):
x = 1 << ((n.bit_length() + k - 1)//k)
while True:
y = ((k-1)*x + n//x**(k-1))//k
if y >= x:
return x
x = y
roots = [iroot(1 << (Stamps.MANTISSA_BITS*Stamps.COST_FP + f), Stamps.COST_FP) for f in range(Stamps.COST_FP)]
for fp in range(0, cap*Stamps.COST_FP + 1):
i, f = divmod(256*Stamps.COST_FP - fp, Stamps.COST_FP)
self.assertEqual(Stamps.target_from_fp(fp), roots[f] << (i - Stamps.MANTISSA_BITS))
def test_03_value_matches_legacy_integer_value(self):
# The compatibility invariant: old clients parse fractional
# stamps at their integer value. The legacy value function
# must therefore always be the integer floor of the new one.
for wb, stamp, hn, vleg, v, exact in self.samples:
self.assertEqual(vleg, 256 - hn.bit_length())
self.assertLessEqual(vleg, v)
self.assertLess(v, vleg + 1)
self.assertEqual(fp_of(v) // Stamps.COST_FP, vleg)
# Empty and None workblocks are handled identically
wb, stamp, hn, vleg, v, exact = self.samples[0]
self.assertEqual(Stamps.stamp_value(None, stamp), Stamps.stamp_value(b"", stamp))
self.assertEqual(Stamps.stamp_value_legacy(None, stamp), Stamps.stamp_value_legacy(b"", stamp))
self.assertTrue(Stamps.stamp_valid(stamp, 0, None))
def test_04_value_never_overreports(self):
# The reported value must never exceed the exact value of
# the stamp product, and must be within one quantisation
# step (1/256th) below it.
step = 1.0 / Stamps.COST_FP
for wb, stamp, hn, vleg, v, exact in self.samples:
self.assertLessEqual(v, exact + 1e-9)
self.assertLessEqual(exact, v + step + 1e-9)
def test_05_value_monotone_in_stamp_product(self):
# A smaller stamp product (numerically) always means a more
# rare hash, and must never yield a smaller value.
ordered = sorted(self.samples, key=lambda sample: sample[2])
last = None
for wb, stamp, hn, vleg, v, exact in ordered:
fp = fp_of(v)
if last != None:
self.assertLessEqual(fp, last)
last = fp
def test_06_validity_boundaries(self):
cap = RNS.Transport.STAMP_COST_CAP
for wb, stamp, hn, vleg, v, exact in self.samples:
# Any stamp is always valid at its legacy integer value,
# and always invalid at exactly one step above it. This
# locks stamp_valid and stamp_value into one scheme.
if vleg <= cap:
self.assertTrue(Stamps.stamp_valid(stamp, vleg, wb))
if vleg + 1 <= cap:
self.assertFalse(Stamps.stamp_valid(stamp, vleg + 1, wb))
# Directional consistency between value and validity
for wb, stamp, hn, vleg, v, exact in self.samples[:500]:
fp = fp_of(v)
for cost in (1, 2, 3):
if fp >= cost * Stamps.COST_FP:
self.assertTrue(Stamps.stamp_valid(stamp, cost, wb))
if Stamps.stamp_valid(stamp, cost, wb):
self.assertGreaterEqual(fp, (cost - 1) * Stamps.COST_FP)
def test_07_target_probability_calibration(self):
# The defining semantic of cost: a random stamp is valid for
# cost c with probability exactly 2^-c.
for cost in (2, 4):
trials = 20000
wb = rb(32)
valid = sum(1 for _ in range(trials) if Stamps.stamp_valid(rb(14), cost, wb))
fraction = valid / trials
expected = 2.0**-cost
sigma = math.sqrt(expected * (1-expected) / trials)
self.assertLess(abs(fraction - expected), 5*sigma)
def test_08_value_deterministic(self):
for wb, stamp, hn, vleg, v, exact in self.samples[:100]:
self.assertEqual(Stamps.stamp_value(wb, stamp), v)
self.assertEqual(Stamps.stamp_value_legacy(wb, stamp), vleg)
class TestStampWorkblock(unittest.TestCase):
def test_00_no_expand(self):
material = rb(64)
self.assertIs(Stamps.stamp_workblock(material, no_expand=True), material)
self.assertIs(Stamps.stamp_workblock(material, expand_rounds=0), material)
self.assertEqual(Stamps.stamp_workblock(material, expand_rounds=16, no_expand=True), material)
def test_01_expansion(self):
material = rb(32)
wb1 = Stamps.stamp_workblock(material, expand_rounds=16)
wb2 = Stamps.stamp_workblock(material, expand_rounds=16)
self.assertEqual(len(wb1), 16*256)
self.assertEqual(wb1, wb2)
self.assertNotEqual(wb1, Stamps.stamp_workblock(rb(32), expand_rounds=16))
def test_02_default_expansion(self):
material = rb(32)
wb = Stamps.stamp_workblock(material)
self.assertEqual(len(wb), Stamps.WORKBLOCK_EXPAND_ROUNDS*256)
self.assertEqual(wb, Stamps.stamp_workblock(material))
class TestStampGeneration(unittest.TestCase):
def _wait_registered(self, mid, timeout=15):
for _ in range(int(timeout/0.05)):
if mid in Stamps.active_jobs:
return True
time.sleep(0.05)
return False
def test_00_generate_stamp_low_costs(self):
for cost in (0, 4, 8):
mid = rb(32)
stamp, value = Stamps.generate_stamp(mid, cost, no_expand=True)
self.assertNotEqual(stamp, None)
self.assertIsInstance(stamp, bytes)
self.assertEqual(len(stamp), Stamps.STAMP_SIZE)
# The generation contract: the stamp must validate at
# the requested cost, and the reported value must be
# within one quantisation step of the requested cost.
self.assertTrue(Stamps.stamp_valid(stamp, cost, mid))
self.assertGreaterEqual(fp_of(value), (cost - 1) * Stamps.COST_FP)
# Old clients parse the fractional value at its integer
# value, so that must always be at least cost - 1, and
# must match the legacy value function exactly.
vleg = Stamps.stamp_value_legacy(mid, stamp)
self.assertGreaterEqual(vleg, cost - 1)
self.assertEqual(fp_of(value) // Stamps.COST_FP, vleg)
self.assertLess(value, 256)
self.assertEqual(value, Stamps.stamp_value(mid, stamp))
def test_01_generate_stamp_expanded_workblock(self):
mid = rb(32)
stamp, value = Stamps.generate_stamp(mid, 4, expand_rounds=16)
wb = Stamps.stamp_workblock(mid, expand_rounds=16)
self.assertEqual(len(wb), 16*256)
self.assertTrue(Stamps.stamp_valid(stamp, 4, wb))
self.assertEqual(value, Stamps.stamp_value(wb, stamp))
def test_02_generate_stamp_default_workblock(self):
mid = rb(32)
stamp, value = Stamps.generate_stamp(mid, 4)
wb = Stamps.stamp_workblock(mid)
self.assertEqual(len(wb), Stamps.WORKBLOCK_EXPAND_ROUNDS*256)
self.assertTrue(Stamps.stamp_valid(stamp, 4, wb))
def test_03_generate_stamped_key(self):
material = rb(32)
keypair, value = Stamps.generate_stamped_key(material, 4)
private, public = keypair
self.assertEqual(len(private), 32)
self.assertEqual(len(public), 32)
self.assertEqual(RNS.Cryptography.X25519PrivateKey.from_private_bytes(private).public_key().public_bytes(), public)
# Keystamp validation uses the public key bytes as the stamp
self.assertTrue(Stamps.stamp_valid(public, 4, material))
self.assertEqual(value, Stamps.stamp_value(material, public))
self.assertGreaterEqual(fp_of(value), 3 * Stamps.COST_FP)
def test_04_generate_stamped_key_empty_material(self):
keypair, value = Stamps.generate_stamped_key(None, 2)
private, public = keypair
self.assertTrue(Stamps.stamp_valid(public, 2, b""))
self.assertEqual(value, Stamps.stamp_value(b"", public))
def test_05_invalid_costs_rejected(self):
cap = RNS.Transport.STAMP_COST_CAP
mid = rb(16)
for cost in (-1, cap + 1):
with self.assertRaises(ValueError):
Stamps.generate_stamp(mid, cost, no_expand=True)
with self.assertRaises(ValueError):
Stamps.generate_stamped_key(mid, cost)
def test_06_duplicate_job_rejected(self):
mid = rb(16)
Stamps.active_jobs[mid] = False
try:
with self.assertRaises(RuntimeError):
Stamps.generate_stamp(mid, 4, no_expand=True)
with self.assertRaises(RuntimeError):
Stamps.generate_stamped_key(mid, 4)
finally:
del Stamps.active_jobs[mid]
def test_07_cancel_unknown_job(self):
# Cancelling a job that was never started must be a safe no-op
Stamps.cancel_work(rb(16))
def test_08_cancel_simple_job(self):
mid = rb(16)
wb = rb(32)
result = {}
def work():
result["r"] = Stamps.job_simple(30*Stamps.COST_FP, wb, mid, Stamps.STAMP_SIZE)
worker = threading.Thread(target=work, daemon=True)
worker.start()
self.assertTrue(self._wait_registered(mid))
time.sleep(0.2)
self.assertIs(Stamps.active_jobs[mid], False) # Still running
Stamps.cancel_work(mid)
worker.join(timeout=10)
self.assertFalse(worker.is_alive())
# Cost 30 can never complete, so a timely return with no
# stamp proves cancellation worked, and that work was done.
self.assertEqual(result["r"][0], None)
self.assertGreater(result["r"][1], 0)
self.assertNotIn(mid, Stamps.active_jobs)
def test_09_cancel_generation_job(self):
mid = rb(16)
result = {}
def work():
result["r"] = Stamps.generate_stamp(mid, 30, no_expand=True)
worker = threading.Thread(target=work, daemon=True)
worker.start()
self.assertTrue(self._wait_registered(mid))
time.sleep(0.3)
Stamps.cancel_work(mid)
worker.join(timeout=30)
self.assertFalse(worker.is_alive())
stamp, value = result["r"]
self.assertEqual(stamp, None)
self.assertNotIn(mid, Stamps.active_jobs)
@skipIf(not RNS.vendor.platformutils.is_linux(), "Direct multiprocess dispatchers are Linux-only paths")
def test_10_direct_multiprocess_dispatch(self):
# generate_stamp only routes to the multiprocess dispatchers
# at cost >= POOLING_THRESHOLD_COST, so they are exercised
# directly here at a trivial cost. This covers both the
# classic and managed worker mechanisms regardless of the
# Python version in use.
wb = rb(32)
mid1 = rb(16)
mid2 = rb(16)
stamp, rounds = Stamps.job_linux(4*Stamps.COST_FP, wb, mid1, Stamps.STAMP_SIZE)
self.assertNotEqual(stamp, None)
self.assertTrue(Stamps.stamp_valid(stamp, 4, wb))
self.assertGreater(rounds, 0)
self.assertNotIn(mid1, Stamps.active_jobs)
stamp, rounds = Stamps.job_linux_managed(5*Stamps.COST_FP, wb, mid2, Stamps.STAMP_SIZE)
self.assertNotEqual(stamp, None)
self.assertTrue(Stamps.stamp_valid(stamp, 5, wb))
self.assertGreater(rounds, 0)
self.assertNotIn(mid2, Stamps.active_jobs)
class TestStampPersistence(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls.tmpdir = None
cls.owns_instance = False
# The full test suite shares one Reticulum instance, created
# by whichever test needed it first. If none is running, a
# temporary instance is created for this class only, and
# cleanly detached again afterwards.
if not RNS.Reticulum.storagepath:
cls.tmpdir = tempfile.mkdtemp(prefix="rns_stamp_tests_")
RNS.Reticulum(configdir=cls.tmpdir, loglevel=RNS.LOG_CRITICAL)
cls.owns_instance = True
@classmethod
def tearDownClass(cls):
if cls.owns_instance:
RNS.Reticulum._Reticulum__instance = None
RNS.Reticulum.configpath = ""
RNS.Reticulum.storagepath = ""
RNS.Reticulum.cachepath = ""
RNS.Reticulum.interfacepath = ""
if cls.tmpdir:
shutil.rmtree(cls.tmpdir, ignore_errors=True)
def _make_stamp(self, dest, cost=4):
# Destination stamps are STAMPLENGTH bytes, and are generated
# without workblock expansion, since the persistence layer
# recomputes the workblock as the unexpanded material.
return Stamps.generate_stamp(dest, cost, no_expand=True, size=RNS.Identity.STAMPLENGTH)
def _cleanup(self, dest):
path = Stamps.destination_stamp_file(dest)
if path and os.path.isfile(path):
os.remove(path)
def test_00_store_load_roundtrip(self):
dest = rb(16)
self.addCleanup(self._cleanup, dest)
stamp, value = self._make_stamp(dest)
self.assertTrue(Stamps.store_destination_stamp(dest, stamp, value))
loaded = Stamps.load_destination_stamp(dest, dest, 4)
self.assertNotEqual(loaded, None)
lstamp, lvalue = loaded
self.assertEqual(lstamp, stamp)
self.assertEqual(lvalue, value)
def test_01_load_value_boundaries(self):
dest = rb(16)
self.addCleanup(self._cleanup, dest)
stamp, value = self._make_stamp(dest)
Stamps.store_destination_stamp(dest, stamp, value)
# A stamp is always valid at its legacy integer value
vleg = Stamps.stamp_value_legacy(dest, stamp)
loaded = Stamps.load_destination_stamp(dest, dest, vleg)
self.assertNotEqual(loaded, None)
self.assertEqual(loaded[0], stamp)
# ... and never at a full step above its own value
self.assertEqual(Stamps.load_destination_stamp(dest, dest, value + 1), None)
def test_02_load_nonexistent(self):
self.assertEqual(Stamps.load_destination_stamp(rb(16), rb(16), 1), None)
def test_03_load_corrupt_file(self):
dest = rb(16)
self.addCleanup(self._cleanup, dest)
stamp, value = self._make_stamp(dest)
Stamps.store_destination_stamp(dest, stamp, value)
with open(Stamps.destination_stamp_file(dest), "wb") as file:
file.write(rb(64))
self.assertEqual(Stamps.load_destination_stamp(dest, dest, 1), None)
def test_04_load_wrong_version(self):
dest = rb(16)
self.addCleanup(self._cleanup, dest)
stamp, value = self._make_stamp(dest)
Stamps.store_destination_stamp(dest, stamp, value)
with open(Stamps.destination_stamp_file(dest), "wb") as file:
file.write(msgpack.packb({"v": 99, "stamp": stamp, "value": value, "generated": time.time()}))
self.assertEqual(Stamps.load_destination_stamp(dest, dest, 1), None)
def test_05_load_wrong_stamp_length(self):
dest = rb(16)
self.addCleanup(self._cleanup, dest)
stamp, value = self._make_stamp(dest)
Stamps.store_destination_stamp(dest, stamp, value)
with open(Stamps.destination_stamp_file(dest), "wb") as file:
file.write(msgpack.packb({"v": Stamps.STAMP_FILE_VERSION, "stamp": rb(8), "value": value, "generated": time.time()}))
self.assertEqual(Stamps.load_destination_stamp(dest, dest, 1), None)
def test_06_stamp_paths(self):
directory = Stamps.stamps_dir(create=True)
self.assertNotEqual(directory, None)
self.assertTrue(os.path.isdir(directory))
dest = rb(16)
path = Stamps.destination_stamp_file(dest)
self.assertEqual(os.path.dirname(path), directory)
self.assertTrue(path.endswith(RNS.hexrep(dest, delimit=False) + Stamps.DESTINATION_STAMP_EXTENSION))
if __name__ == '__main__':
unittest.main(verbosity=2)