docs(miner): Proof + Bounty A→Z at 2000/8000

[echobt]

Summary

Miner-facing Proof + Bounty docs (and ctx help/submit flags) so a miner can go from zero → submit → see status without placeholders.

Live emission documented as bounty 2000 bps / proof 8000 bps (20/80). Not 7000/3000, and not a 5000/5000 retune waiting on a digest.

Docs-only of the pin/image/ceremony path: this PR does not touch config/proof-pin.toml, proof-eval image/CI, topic-publish/harvest code, or emission ceremony keys. Those stay with Développeur.

Gaps closed

• Proof unit of work is a signed topic; miner submits claim + reproducible recipe + declared_flops vs topic_id
• Required POST JSON now documented (miner_hotkey, topic_id, artifact_digest, claim, declared_flops, architecture, manifest); artifact_uri optional
• Artifact = code + lockfile/entry under FLOP/wall budget, not a weight dump; RLM checks the claim against public numbers + code
• Dynamic topics: operators inject via admin POST; miners discover with ctx proof topics
• Topic fields: payout_mode = wta | discovery; English validation {score_on, accept_if, reject_if}; discovery ≈30% pass floor + ≈70% novelty
• 400 vs 503 table; contamination / empty manifest → reject, no rent
• Agent verdict (clean|suspicious|reject) and cheat codes
• NLL vs throughput pass rules; lattice = mean over open topics
• Pin floors from config/proof-pin.toml; a topic may tighten only
• Empty eval_image_digest → honest 503 (pre-launch)
• ctx proof submit now requires --claim and --declared-flops; help text is 2000/8000
• Bounty A→Z with real gateway URLs (https://network.cortex.foundation)

What still blocks Proof can_score=true

These are not this PR. Submits stay 503 until they land:

1. Empty eval_image_digest in config/proof-pin.toml (awaiting first green ghcr.io/cortexlm/proof-eval@sha256:… — do not invent a digest)
2. Empty proxy_model (submit would 400 proxy not baked even after a digest)
3. No open signed topic with a sealed baseline (script_sha256 + metrics_commitment)
4. Live harvest not wired (live_harvest_wired: false)

Doc paths miners should read

1. docs/external-miner/README.md — install ctx, live ids, 20/80
2. docs/external-miner/proof.md — Proof A→Z
3. docs/external-miner/bounty.md — Bounty A→Z
4. docs/external-miner/troubleshoot.md — 400 vs 503

Gateway: https://network.cortex.foundation. CLI: ctx.

Greptile

Every PR is reviewed by Greptile before merge. Config: .greptile/.

• Greptile has reviewed this PR; findings are fixed or answered
• If the bot was silent, I commented @greptileai review

Test plan

• cargo test -p ctx
• cargo test -p xtask external_docs
• cargo run -p xtask -- external-docs-check
• cargo clippy -p ctx --all-targets -- -D warnings
• cargo test --workspace not run (docs + miner CLI only)

Risk

Miner-facing docs and ctx catalog/help/submit flags only. No trust-root, pin digest, image, or ceremony change. ctx challenges now prints 2000/8000; that is the documented live split, independent of the ceremony file Développeur owns.

Naming

I did not rename BASE_* environment variables, deployed host paths
(/opt/base, /run/base, …), GHCR baseintelligence/base package names, or
base-*-v1 cryptographic domain tags.

  

[echobt]

Review (Développeur) — Docs-only LGTM for miner A→Z: gateway https://network.cortex.foundation, claim+declared_flops+recipe, 400/503, WTA/discovery notes, no pin/image edits.

Nit / ship gate: docs + ctx catalog already say live emission 2000/8000, but config/challenges.toml on main is still 7000/3000 until Architecte ceremony PR lands. Merge #219 only after (or stacked with) the trust-root emission retune, or miners will be told a split the sealed root does not pay.

Empty digest / no open topic → 503 remains honest.

[greptile-apps]

Greptile Summary

The Proof operator guide adds a topic-publication URL that the public gateway rejects. Update the guide to direct operators to the authenticated master-local endpoint before merging.

Confidence Score: 4/5

Not safe to merge until the topic-publication instruction uses an endpoint operators can reach.

The documented topic-publication request was exercised against the enforced gateway and service route contracts: the gateway rejects it, while the master-local endpoint accepts a valid authenticated request.

Files Needing Attention: docs/external-miner/proof.md

T-Rex Logs

What T-Rex did

• Ran the digest directive check script to verify the README digest matches the published pin and to confirm the parent instruction pins the digest, and the script exited with code 0 (proof 0).
• T-Rex produced a proof for the posted P1 finding and linked it to the corresponding review comment (proof 1).
• T-Rex produced an additional proof for the posted P1 finding to cover another aspect (proof 2).
• Authored and executed the admin route contract check script, and captured before and after states showing that the PR adds the gateway admin URL while the gateway 403 and master-local service route remain unchanged (proof 3).

_{Ran code and verified through T-Rex}

Comments Outside Diff (1)

1. General comment

   Proof miner guide directs operators to a gateway-blocked admin endpoint

   • Bug
     • docs/external-miner/proof.md:81 instructs POST /challenge/proof/v1/admin/proof/topics. Gateway proxy handling identifies v1/admin/proof/topics as an admin path and responds 403 Forbidden: admin API is not exposed via gateway; use master-local challenge port. The proof router instead mounts authenticated publishing at POST /v1/admin/proof/topics, which returns 401 Unauthorized without a bearer and 201 Created for a valid authenticated signed request.
   • Cause
     • The documentation applies the public miner gateway prefix to an admin-only operation even though gateway policy makes all /challenge/{id}/v1/admin/* endpoints master-local only.
   • Fix
     • Replace the gateway-prefixed instruction with the master-local POST /v1/admin/proof/topics endpoint and explicitly state that it requires the operator bearer and is unavailable through the public gateway.

   _{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(miner): Proof + Bounty A→Z at 2000/..." | Re-trigger Greptile}

[greptile-apps]

Gateway admin URL fails

This instruction sends operators to POST /challenge/proof/v1/admin/proof/topics, but the gateway rejects proxied admin paths with 403 Forbidden. As a result, an operator following the new guide cannot publish a topic. Use the authenticated master-local POST /v1/admin/proof/topics endpoint instead, and state that it is unavailable through the public gateway.

Knowledge Base Used: Gateway and public API services

Artifacts

Evidence from the check

• The authored shell script captures the parent/current documentation and route source, then performs the no-credential gateway request and focused in-process tests; it is the executed source for the verification.

Command output from the check

• Executed capture against `HEAD^` shows the prior documentation did not include the new gateway admin instruction, while the gateway was already coded to reject admin proxy paths and the proof service exposed the master-local route.

Command output from the check

• Executed capture against `HEAD` shows line 81 instructs the gateway admin URL, while gateway route tests and proof service endpoint tests pass; the takeaway is that the added documentation contradicts the enforced route contract.

_{Ran code and verified through T-Rex}