Metadata-Version: 2.4
Name: attested-relay-timelock
Version: 0.2.0a1
Summary: Native RandomX solver and checkpoint manager for attested relay archives
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: RANDOMX-LICENSE
Provides-Extra: follow
Requires-Dist: attested-relay<0.3,>=0.2.0a1; extra == "follow"
Dynamic: license-file

# attested-relay-timelock

This package bundles the native Rust RandomX v2.0.1 generator, solver, checkpoint
journal, calibration, and archive decryption commands in a platform wheel.
It has no Python substitute for RandomX. Build the wheel from this complete
repository with `pip wheel --no-deps ./python/attested-relay-timelock` (Rust,
CMake, and a C++ compiler are required). Source-only PyPI installation is not
supported; publish the platform wheels after native validation on each platform.

```
attested-relay-timelock calibrate --mode full --samples 10000
attested-relay-timelock solve --manifest puzzle.json \
  --service-public-key ATTESTATION_VERIFIED_ED25519_HEX \
  --checkpoint epoch.jsonl --key-out epoch.key
attested-relay-timelock decrypt-record --manifest puzzle.json \
  --service-public-key ATTESTATION_VERIFIED_ED25519_HEX \
  --epoch-key epoch.key --record ciphertext.json --plaintext-out record.json
```

Re-run the identical solve command after a restart to resume. The append-only
journal preserves completed entries after interrupted writes. Checkpoint digests
detect accidental corruption; checkpoints are local progress hints, and a malicious
writer can waste computation but cannot produce a returned key without passing
the segment AEAD and published epoch-key commitment. Protect the journal directory.

The public key is a required independent trust pin, obtained from verified
attestation or a previously verified archived identity. A manifest's self-reported
signer does not establish trust.

`light` mode uses the genuine RandomX algorithm with a 256 MiB cache and computes
dataset items as needed. `full` uses a shared 2080 MiB dataset for faster execution.
Both produce identical hashes. Production iteration counts must be calibrated in
full mode on the reference CPU, compiled into the enclave image, and measured
under seven-worker load. Short tests never establish a seven-day delay.

Continuous solving uses verified historical bundles and the paginated all-artifact
index, restarting discovery from its first page each poll so newly inserted hashes
are not missed:

```
attested-relay-timelock follow https://relay.example --expected-pcr0 PCR0_HEX \
  --state-dir ./solver-state --max-workers 7
```

Install the `follow` extra (and the matching `attested-relay` package). Each bundle
must pass archived Nitro identity verification before its independently authenticated
service key is handed to the native solver. Seven full-mode solvers require roughly
16 GiB for datasets/caches plus process overhead. Existing verified keys are reused;
failed solvers preserve checkpoints and are retried on later discovery scans. Keys
are stored locally; this command does not publish them to an external service.
