🧮 MAX Prime Challenge

Rust GUI + CLI for distributed probable-prime search, Miller-Rabin primality testing and reproducible computational number theory experiments

MAX Prime Challenge is a public distributed-computing project for finding large probable primes generated by a structured mathematical family.

It combines deterministic work units, Miller-Rabin probable-prime testing, distributed computation and reproducible local verification.

It is not a random search.

The Challenge comes from the MAX Prime Theory research line: affine-related quadratic polynomials, index pre-sieves, CRT-based modular partitions and constant modular signatures.

Public research background:

https://www.max-russo.com/papers.php

---

✨ What this project is

MAX Prime Challenge turns a mathematical research idea into a public computation challenge.

Participants run a Rust client on their own computer.

The client receives small work units, computes them locally, and submits the result to the official MAX Prime server.

The goal is twofold:

1. discover large probable primes;
2. measure whether the structured MAX Prime candidate family produces more probable primes than a comparable random baseline would suggest.

This measured effect is called enrichment.

---

🧠 Why this is not a random search

A random prime search simply samples numbers and tests them.

MAX Prime Challenge instead uses deterministic work units generated from a structured formula.

Each official work unit is reproducible.

The same work unit can be recomputed and checked by an independent verifier.

The conceptual flow is:

Campaign -> Work Units -> Run -> Verify -> Report

This structure makes the project suitable for:

• public participation;
• independent inspection;
• repeatable computation;
• progress tracking;
• probable-prime hit verification;
• enrichment measurement.

---

📦 What this repository contains

This repository contains the public Rust participant client.

It includes:

• graphical user interface;
• command-line client;
• local demo mode;
• official challenge mode;
• work-unit computation;
• result submission;
• third-party license notes.

The GUI is the recommended way to participate.

The CLI is available for technical users who prefer the terminal.

---

🔓 Source-first distribution

MAX Prime Challenge is distributed as source code first.

This repository is meant to let technical users inspect the Rust code, verify the formula, build the client locally, run local experiments, and reproduce exported hit data without trusting a black-box executable.

Prebuilt binaries are not included in this repository.

This is intentional. The source code is the reference implementation. Future convenience packages may be provided separately through GitHub Releases, but the public source remains the primary trust layer.

---

🖥️ CLI and GUI build options

MAX Prime Challenge includes both a command-line client and a graphical interface.

The CLI is the best starting point for technical users who want to inspect the project, run local experiments, script executions, or reproduce exported hit data.

The GUI is intended for a cleaner user experience, especially for official participation workflows and exporting official winning hit data.

For normal GUI use and official participation, use the full build:

cargo build --release

This builds both:

target/release/max_prime_public_gui
target/release/max_prime_public_client

The GUI uses max_prime_public_client internally for some official participation functions, including MAX Login. For that reason, compiling only the GUI binary is not sufficient for the complete official GUI workflow.

CLI-only build, for terminal-only use:

cargo build --release --bin max_prime_public_client

GUI-only build, for development or limited GUI testing:

cargo build --release --bin max_prime_public_gui

If you want to use MAX Login or participate officially through the GUI, use the full build instead.

---

⏳ Build-time note

The first GUI build can take several minutes because Rust has to compile native GUI dependencies.

This is normal and does not mean that the MAX Prime computation is slow. It is the one-time cost of compiling the graphical interface and its native dependencies.

The CLI build is lighter and can be useful for technical users who want a faster first check from the terminal.

---

📱 MAX Login, MAX App and privacy

Official participation requires MAX Login authorization.

Authorization connects this client installation to a public MAX identity, so the official server can assign work, receive results, prevent duplicate or fake submissions, and credit valid hits.

The registration flow uses MAX Login and is confirmed through the MAX App.

The client does NOT require:

• e-mail address;
• phone number;
• real name;
• surname;
• postal address;
• identity documents;
• traditional account password.

The public identity used by the Challenge is the MAX ID.

Local demo mode does not require registration.

The goal is to keep the mathematical challenge separated from unnecessary personal data.

For detailed explanations of MAX ID, MAX Login, MAX App and MX², see the official MAX website:

https://www.max-russo.com

---

🔐 MAX App, MAX Login and MX²

MAX Login is the authentication flow used to connect this Rust client to a public MAX identity.

The MAX App is used to confirm the registration securely.

The underlying portable identity material is based on an MX² code, which can be represented as text or as a QR Code.

Open MX² repository:

https://github.com/max-russo-com/mx2

In practice:

1. a participant has or creates an MX² identity code;
2. the MAX App imports or holds that identity;
3. this Rust client starts the MAX Login registration flow;
4. the participant confirms the registration with MAX App;
5. this client installation becomes authorized to request official MAX Prime work.

The public Rust client does not contain the private MAX App code or the private server-side login system. It only connects to the official public endpoints needed for participation.

---

📲 Do you need to own an iPhone?

Not necessarily.

The MAX App is currently the practical way to confirm MAX Login registration.

However, the important identity material is the MX² code.

A participant who does not own an iPhone is not automatically excluded. The MAX App may be used temporarily on another iPhone to import the MX² code, confirm the computer registration, and then remove the imported identity from that device.

The participant should still keep the MX² code private and under personal control.

If you're temporarily using someone else's iPhone just to confirm MAX access, remove the imported MAX identity from that device when you're finished using it by simply clicking the "Clear All Session Data" button.

Official information for downloading and configuring the MAX App is available on the official MAX website:

https://www.max-russo.com

---

🧪 Local mode vs official mode

Local mode

Local mode runs only on your computer.

It is useful for:

• trying the software;
• understanding the search;
• testing the engine;
• seeing how candidates are generated;
• reproducing exported hit data.

Local mode does not submit official results.

Local mode does not require registration.

Official mode

Official mode participates in the public MAX Prime Challenge.

It can:

• authorize the client with MAX Login;
• request assigned work units;
• compute work locally;
• submit results;
• contribute to public challenge progress;
• report probable-prime hits to the official system.

Official mode requires MAX Login registration.

Official contribution controls

The GUI provides three clear participation controls:

• Run 1 package performs one short official work unit;
• Run 5 packages performs a controlled batch of five work units;
• Start contributing keeps requesting one package at a time until the participant stops it or the Challenge ends.

Stop after current package does not interrupt a calculation halfway through. It lets the active package finish and then stops before requesting another one.

The GUI keeps separate and clearly labelled counters:

• Accepted this session counts packages accepted by the official server since the GUI was opened;
• Current run shows the size and progress of the latest Run command;
• Current package identifies the package currently being processed;
• Challenge Progress shows the permanent global state reported by the server.

The local session counter increases only after the server confirms Accepted: true. It does not increase for interrupted calculations, expired assignments or rejected submissions. Closing and reopening the GUI resets only this local session counter; accepted results remain permanently stored by the official server.

Renewable work-unit lease

Every official work-unit assignment uses a renewable server lease.

While a package is being computed, the client sends periodic heartbeat messages. Each valid heartbeat moves the assignment expiration time forward, so long calculations can continue safely even when they take more than the initial lease period.

If the GUI is closed, the computer is switched off, the connection is lost or the client stops unexpectedly, heartbeat messages stop. After the lease expires, the abandoned assignment can be marked expired and the same work unit can be assigned again as a new attempt.

The server rejects results belonging to assignments that are expired, inactive or superseded by a newer attempt. This prevents abandoned or late submissions from being counted twice.

---

🔢 Mathematical construction

For each iteration:

n_raw = n0 + i * step

If no CRT filter is active:

n_effective = n_raw

If a CRT filter is active:

n_effective = R + M * n_raw

Then:

x = 25 + 5*n_effective*(n_effective+1)
raw_N = 6*x + 5
raw_d = x
g = gcd(raw_N, raw_d)
N = raw_N / g
d = raw_d / g

The public client currently focuses mainly on N candidates, because they showed the strongest enrichment signal in local experiments.

---

🚀 Quick start

Clone the repository:

git clone https://github.com/max-russo-com/max-prime-challenge.git
cd max-prime-challenge

Build the complete project:

cargo build --release

Run the GUI:

./target/release/max_prime_public_gui

The full build is recommended for GUI use because the GUI invokes the CLI client internally for functions such as MAX Login.

Run the CLI directly, if preferred:

./target/release/max_prime_public_client

---

🧭 Optional CLI commands

These commands are optional and mainly useful for technical users who want to inspect the client from the terminal.

./target/release/max_prime_public_client welcome
./target/release/max_prime_public_client modes
./target/release/max_prime_public_client privacy
./target/release/max_prime_public_client local-demo
./target/release/max_prime_public_client official-explain

---

🏆 Official winning hit export

When an official probable-prime hit is found, the GUI can export the winning hit data as JSON.

The exported file is designed for public inspection and local reproducibility. It includes:

• candidate type;
• index i;
• n_raw;
• n_effective;
• candidate value;
• digit count;
• SHA-256 hash;
• available official result payload.

Operational identifiers and local tokens are redacted from the public export because they are not required for mathematical reproducibility.

A reviewer can use the exported data to recompute the candidate locally and check that the SHA-256 hash matches the published result.

---

🧮 Prime status

The current client uses Miller-Rabin probable-prime testing.

That means discovered hits are probable primes.

A probable prime is not the same thing as a final public mathematical certificate unless it is later certified by a stronger verification process.

---

🛡️ Security model

The official challenge does not trust the local client blindly.

Official validity depends on:

• authenticated registration;
• server-assigned work units;
• assignment checks;
• submitted result checks;
• verifier checks.

A modified local client cannot make an unofficial result official by itself.

More technical notes are available in:

• SECURITY.md;
• LICENSE_AUDIT_NOTES.md;
• THIRD_PARTY_LICENSES.md.

---

📁 Repository contents

src/bin/max_prime_public_gui.rs          GUI client
src/bin/max_prime_public_client.rs       CLI client
src/bin/max_prime_public_runner_gui.rs   Runner GUI helper
examples/                                Public example configs
Cargo.toml                               Rust package definition
Cargo.lock                               Locked dependency versions
SECURITY.md                              Security notes
THIRD_PARTY_LICENSES.md                  Third-party crate license list
LICENSE_AUDIT_NOTES.md                   License audit notes
LICENSE                                  Repository license

---

🧾 Dependency and license notes

The public client uses the Rust dependencies listed in Cargo.toml and locked in Cargo.lock.

Third-party license notes are available in:

THIRD_PARTY_LICENSES.md
LICENSE_AUDIT_NOTES.md

---

💻 Supported platforms

The Rust client is intended to be portable across:

• macOS;
• Linux;
• Windows.

Platform-specific build requirements may depend on Rust, Cargo and native GUI dependencies.

---

🌐 MAX ecosystem

MAX Prime Challenge is part of the broader MAX ecosystem.

The MAX App is used for privacy-preserving participant identity and registration confirmation.

MX² provides a portable identity/secret container layer.

The public Rust client is open for inspection so participants and technical reviewers can verify how work units are computed locally.

Private server-side systems, MAX App internals and administrative tools are not part of this repository.

---

📄 License

See LICENSE.

---

✍️ Author

Massimo Russo

https://www.max-russo.com