@flop-labs/cli 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,90 @@ and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-11-12
+
+### Added
+
+- `flop miner capacity-rate show [address]` prints the miner's D-0542 reservation rate and free
+  capacity at the finalized head; `flop miner capacity-rate set <rate> | --whole-cap [--dry-run]`
+  submits `set_capacity_reservation_rate`, or prints the encoded call without signing.
+
+- `flop model mirrors set --model-hash <hash> --source <mirror>...` submits
+  `modelRegistry.setModelMirrors`, which replaces a model's mirror hint list. Sources are
+  `https://`, `hf:<owner>/<model>`, `modelscope:<owner>/<model>` and `da:<commitment>`. A `da:`
+  source must be a live Leased DA blob; its provider comes from finalized state. Input is
+  checked before signing: each entry is at most 512 bytes, there are no duplicates, and the
+  final list holds 1 to 8 entries. `--clear` sends the empty list that removes every mirror.
+  The signer must be the model's publisher. The pallet admits no one else, so neither a
+  registrar nor Root can set mirrors. `--append` keeps the finalized list verbatim and is a
+  no-op once every source is present; a DA entry counts as present only at the same commitment
+  and provider. Every run reports the finalized list it read as `registered`. `--dry-run` prints
+  the encoded call without signing.
+  `--json` prints the result.
+
+- `flop model onboard` and `flop model preflight` report the model's paid throughput
+  ceiling: the completion tokens per second one channel can be paid for at a live accepted
+  calibration cap (`hwCalibration.benchmarkBurstCaps` at finality, `cap × 1e9 × 1000 /
+  (babe.expectedBlockTime × 2 × active parameters)`). The per-token work is not rounded up
+  to whole G_n, because the meter truncates only after summing a turn; `gnPerToken` is that
+  exact value. The median live cap is used unless
+  `--miner <address>` names one (`capSource`); the best live cap is reported beside it but
+  never gated. It appears as `throughputCeiling`
+  (onboard) or `throughput_ceiling` (preflight) in JSON output and as a stderr line.
+  `preflight` reads the chain only with an explicit `--rpc`; otherwise the ceiling is
+  `unknown (no chain connection)`, never a default. `--min-tokens-per-second <n>` makes it a
+  gate: a ceiling below `n`, or unknown, exits non-zero, and `onboard` fails before any chain
+  write. Without the flag it only warns.
+- `flop miner doctor --running` checks a miner that is already serving, from a release
+  pack or another host, instead of its setup prerequisites. `--address` checks that the
+  account is registered, active and holds an accepted calibration cap at finality.
+  `--endpoint https://host` checks that the public name refuses anonymous
+  `/session/info` and answers a fresh `/session/info-proof` challenge with a ready proof
+  signed by the worker's own session key for its own model identity, as read on
+  `--session-url` with `SESSION_AUTH_TOKEN`. `--endpoint` needs `--session-url`, and none
+  of these run with `--offline`.
+
+### Changed
+
+- Depends on `@flop-labs/sdk` 0.6.0, so every `flop` command connects to runtimes `1014015`
+  through `1014020`, including `flop miner capacity-rate` on the capacity-reservation runtime.
+
+- `flop model onboard --approve` now works on a metadata-only run (a Hugging Face
+  `--source` without `--download`) once its DA backup is bound. That means after
+  `flop model backup`, `flop model upload --commitment` and
+  `flop model mirrors set --append --source da:<table>`. Approval runs the same finalized
+  checks as before: a Leased image of the packed size, a live lease, and a file table that
+  hashes to `model_hash` and is named by a DA mirror. Without a bound image the flag is
+  refused before capture or any chain write. Before, it was refused even after the backup was
+  bound. `--paid-admission` still fails closed at `independent-audit-unavailable`.
+  Because a metadata run never packed the image, it then spot-checks 2 random chunks of the
+  bound image before approving, using `da-validator retrieve --chunk` (each chunk checked
+  against the DA commitment). Whole files must match their sha256, files cut by a chunk edge
+  must equal the hub's bytes at the pinned revision, and padding must be zero. It then rereads
+  the evidence and refuses if the bound image or file table changed. The result is reported as
+  `daSpotCheck`. It is a sample, not a proof. It needs a `da-validator` with `--chunk`.
+- Approval now reads `ModelMirrors` strictly: a failed read reports
+  `cannot read ModelMirrors at finality` instead of a missing file-table mirror.
+- `flop model backup` now ends by printing the `flop model mirrors set` command, not the raw
+  call.
+
+### Fixed
+
+- `flop gateway renew` now checks up to four miner identities and deployments at
+  once, so slow endpoints delay the next paid tools probe less. Paid probes
+  still run one at a time in the original miner order.
+- `flop model fetch` and `flop model upload --source hf:<repo>` no longer download a
+  Hugging Face mirror from `main` into memory. They take `--revision <40-hex sha>`,
+  read that commit's published sha256 table, and stream every file at that one commit,
+  each held to its SHA-256. Without `--revision`, `main` is used only when its table
+  reproduces the registered `content-v1` root. Any other result is refused before any
+  weight byte moves, and the error names the resolved commit. With `--revision`, a
+  `verity-v1` root is measured after the transfer. `fetch` writes into an empty
+  `--output-dir` only once the bytes verify.
+- `flop model onboard --hf-repo` checks the repo's sha256 table against the local
+  content root before downloading anything. It then pins the download to that commit.
+  A local source now accepts `--revision` together with `--hf-repo`.
+
 ## [0.4.4] - 2026-11-10
 
 ### Fixed

package/README.md

@@ -93,6 +93,9 @@ flop agent session create --delegate <address>
 # Miners: sim first, measured TDX for verified production, cloud is non-attested.
 flop miner init --mode sim
 flop miner doctor --mode sim
+# A serving miner: chain state plus the public proof gateway admission checks.
+# SESSION_AUTH_TOKEN comes from the environment, never the command line.
+flop miner doctor --running --session-url http://127.0.0.1:8645/session/info --endpoint https://<miner-host>
 flop miner status [address]
 flop --signer <MINER-URI> miner register --commission 10
 flop --signer <MINER-URI> miner calibrate-start
@@ -172,6 +175,19 @@ A registered miner publishes the GPUs it runs as a signed `flop.gpu-inventory.v1
 self-reported and display-only: calibration caps, SKU ceilings and rewards never read it. The CLI
 image cannot run the host's `nvidia-smi`, so pass its output with `--nvidia-smi` (`-` reads stdin).
 
+#### Capacity reservation rate
+```bash
+flop miner capacity-rate show [address]      # rate, cap, reserved and free G_n/s at the finalized head
+flop --keystore miner.json --password-env FLOP_KEY_PASSWORD miner capacity-rate set 25 --dry-run   # encoded call only
+flop --keystore miner.json --password-env FLOP_KEY_PASSWORD miner capacity-rate set 25
+flop --keystore miner.json --password-env FLOP_KEY_PASSWORD miner capacity-rate set --whole-cap   # clear it
+```
+
+Each channel opened against a miner reserves this rate from its accepted cap until the channel
+lapses; unset, it reserves the whole cap, so only one channel fits at a time. `miner-worker` keeps
+it at `floor(cap / MINER_MAX_CONCURRENT_SESSIONS)` unless you set a lower one. The call exists only
+on a runtime with capacity reservations; elsewhere the command refuses.
+
 #### Stake Info
 ```bash
 flop info 5Grwva8...  # Get miner stake info
@@ -212,7 +228,9 @@ flop model list
 flop model get <hash-or-name> --precision FP16
 flop model fetch <hash-or-name> --output-dir ./weights
 flop model fetch <hash> --source hf:org/repo --precision INT8
+flop model fetch <hash> --revision <40-hex sha> --output-dir ./weights
 flop --signer <PUBLISHER> model upload --model-hash <hash> --path ./weights
+flop --signer <PUBLISHER> model mirrors set --model-hash <hash> --append --source da:<table> --dry-run
 BASE=http://miner:8000 DECODE_POLICY_HASH=0x<hash> \
   flop --network local model onboard --source org/model --precision BF16
 
@@ -222,7 +240,10 @@ flop --signer <PUBLISHER> model upload \
 ```
 
 Fetch accepts `hf:`, `modelscope:`, HTTPS, and `da:` sources and writes only
-after dm-verity matches the registered root. Full upload builds the canonical
+after dm-verity matches the registered root. A Hugging Face mirror streams at one
+commit: `--revision <sha>` pins it, and without it `main` is used only when its
+sha256 table reproduces a `content-v1` root (`upload --source hf:` likewise; see
+`docs/onboarding/model.md`). Full upload builds the canonical
 image, runs `da-validator submit`, registers its leased blob, and binds it.
 Onboard additionally registers the model, mirrors, per-precision measured root,
 and decode policy, but only after the serving endpoint passes capture replay,