Submit

1. Get the exporter

Clone the repository (it contains the exporter, the validator, and the schema — no dependencies beyond Python 3.9+):

git clone https://git.catalystgroup.tech/herman/tokenmaxxing.git
cd tokenmaxxing

2. Export an anonymous snapshot

Run the exporter against your own Hermes database. It opens the database read-only, aggregates numbers, and refuses to write anything that fails the public allowlist:

python3 scripts/export_anonymous.py \
    --db "$HOME/.hermes/state.db" \
    --days 30 \
    --alias YourAlias \
    --instance-secret-file "$HOME/.config/tokenmaxxing/secret" --create-secret \
    --out data/submissions/my-instance.json

Flags that matter:

flag	effect
`--days {7,30}`	window length; the tower ranks 30-day windows
`--alias`	the display name shown on the tower (change it any time)
`--instance-secret-file` + `--create-secret`	creates a random local secret (mode 0600, refused inside a git repo) and derives a monthly-rotating pseudonym from it
`--public-id tmx-your-name`	alternative: a fixed public ID, if you want continuity
`--db`	path to your Hermes state database

3. Validate, then look at what you’re about to publish

python3 scripts/validate_snapshots.py data/submissions/my-instance.json
cat data/submissions/my-instance.json

The file you just read is exactly what becomes public — fifteen numeric aggregates, a daily series of numbers, your alias, a pseudonym, two dates, three version/label strings. If anything else is in there, the validator has a bug: please file it as a security issue.

4. Open the merge request

Add the file under data/submissions/, run the deterministic build, and push:

python3 scripts/build_leaderboard.py
python3 -m unittest discover -s tests
git checkout -b submit/your-alias
git add data/submissions/my-instance.json data/leaderboard.json static/data/leaderboard.json
git commit -m "submission: YourAlias, 30d window"
git push -u origin submit/your-alias

CI re-runs the validator and the build on every merge request; a maintainer merges when it’s green. Rejections come with the failing rule name and JSON path — never with your data echoed back.

Rules of the tower

One entry per instance per window length. A newer window replaces the older one (same public_id, or say so in the MR).
Verified rank requires the exporter. Hand-edited numbers that still validate are technically possible — see the anti-gaming notes on methodology; absurd magnitudes bounce off the schema.
Freshness is displayed with your entry. Stale windows fade; they are never silently deleted.
Want out? See privacy — deletion is an MR away.