@starkscan/cli 0.2.0 → 0.4.0

package/README.md

@@ -3,9 +3,11 @@
 Command-line Starkscan client for status checks, explorer reads, local exports,
 and agent setup.
 
-Status: public `0.2.0` stable release. The npm `latest` tag points to the real
-CLI package. Use the untagged install for normal setup and pin `0.2.0` for
-unattended agents or production services that need reproducible installs.
+Release target: `0.4.0`. This release adds the public asynchronous exact
+contract-verification workflow, including deterministic source preparation,
+job control, and offline receipt validation. Use the untagged install only
+after the live `latest` verifier passes; pin `0.4.0` for reproducible installs
+after that promotion.
 
 ## Install
 
@@ -23,11 +25,11 @@ npx -y @starkscan/cli init --agent --output-format json
 Exact pin for unattended services:
 
 ```bash
-npx -y @starkscan/cli@0.2.0 init --agent --output-format json
+npx -y @starkscan/cli@0.4.0 init --agent --output-format json
 ```
 
 Prerelease tags such as `@beta` are maintainer-directed test channels only.
-Normal users and agents should use the default package or the exact `0.2.0`
+Normal users and agents should use the default package or the exact `0.4.0`
 pin above.
 
 ## First commands
@@ -44,13 +46,57 @@ starkscan tx 0x1234abcd
 starkscan search 0x1234abcd
 starkscan wallet-asset-discovery 0xWALLET --limit 25
 starkscan wallet-state 0xWALLET --mode require_complete --limit 25
+starkscan token-holder-screening 0xTOKEN --limit 100 --output-format json
+starkscan token-holders 0xTOKEN --limit 100 --output-format json
+starkscan verify prepare --help
+starkscan verify submit --help
+starkscan verify status --help
+starkscan verify receipt-check --help
 ```
 
+`token-holder-screening` walks the address-keyed policy Top-N and never claims
+population completeness, even when `nextCursor` is null. Historical source
+corrections can invalidate an unexpired generation's proof without changing
+its immutable rows. Recheck `populationComplete`, `exact`, and certification
+on every JSON page; a previously certified page does not authorize later
+pages. `token-holders`
+requests holder pages; do not present an exact census unless its JSON has the
+sealed finalized source with `freshness=finalized_generation`, valid immutable generation/block/hash/digest IDs, an
+unexpired `expiresAt`, `populationComplete=true` with
+`populationReasonCode=complete_canonical_transfer_coverage`, `exact=true`,
+`truncated=false`, and `completeness.reasonCode=materialized_snapshot`; plus
+`certification.status=certified`,
+`validatedAgainst=starknet_rpc_balanceOf`,
+`certification.reasonCode=materialized_snapshot`, and a valid `checkedAt` no
+earlier than `updatedAt`. Pass each opaque `nextCursor` back with `--cursor`
+unchanged.
+An intentionally redacted holder `200`, including the address-keyed priority
+case, contains `holderCount=0`, `holderBalanceTotalRaw=null`, no rows,
+`nextCursor=null`, `populationComplete=false`, `exact=false`, and
+`Cache-Control: no-store`; JSON automation must treat it as unavailable proof,
+not an empty population or a cacheable zero.
+
+If either holder command receives HTTP `422` with
+`code=unqualified_token_policy`, the token has no current explicit
+address-keyed holder policy. This is terminal, non-retryable eligibility state,
+not an uncaptured generation: the CLI exits with the stable `usage` class and
+JSON output includes `error.apiCode="unqualified_token_policy"`. A qualified
+priority token without a current certificate still returns the redacted `200`
+tuple above; an eligible token whose prepared data is temporarily unavailable
+uses retryable `503` and `Retry-After` instead.
+
 The CLI defaults to `https://api.starkscan.co`, sends `X-Starkscan-Api-Key`,
 and uses the same REST API contract as the SDK. MCP uses a separate
 transport: `POST https://api.starkscan.co/mcp` on the API domain, or
 `POST {appBaseUrl}/api/mcp` on app-origin deployments.
 
+`starkscan verify` is the public asynchronous contract-verification workflow.
+It deterministically packages a locked Cairo source tree, streams the bounded
+archive to Starkscan's isolated networkless verifier, reports typed job state,
+and authenticates a portable Ed25519 receipt offline. See the complete
+[contract-verification guide](https://starkscan.co/docs/api/contract-verification)
+before submitting private or publishable source.
+
 ## Why use it
 
 - No Rust toolchain or private repository access required.
@@ -60,15 +106,19 @@ transport: `POST https://api.starkscan.co/mcp` on the API domain, or
 - `--output-format json` keeps stdout parseable for agents and CI.
 - Stable exit classes make automation predictable: success, usage, auth,
   rate-limit, timeout, and not-found errors are distinct.
+- The remote MCP proxy preserves holder errors in `structuredContent`: terminal
+  policy review is `errorCode="unqualified_token_policy"` with
+  `retryable=false`, while eligible-token lifecycle `503` is
+  `errorCode="temporary_unavailable"` with `retryable=true`.
 - MCP helpers print ready-to-paste Codex, Claude Code, Cursor, Claude Desktop,
   and Cline configs with environment placeholders, not secret values.
 
 ## Agent setup
 
 ```bash
-npx -y @starkscan/cli@0.2.0 init --agent --output-format json
-npx -y @starkscan/cli@0.2.0 mcp print-config --transport remote
-npx -y @starkscan/cli@0.2.0 mcp start --transport remote
+npx -y @starkscan/cli@0.4.0 init --agent --output-format json
+npx -y @starkscan/cli@0.4.0 mcp print-config --transport remote
+npx -y @starkscan/cli@0.4.0 mcp start --transport remote
 ```
 
 `print-config` emits machine-readable snippets. Keep `STARKSCAN_API_KEY` in the
@@ -79,7 +129,7 @@ host shell, CI secret store, or MCP client secret store.
 Agents can inspect the launcher decision without executing the native binary:
 
 ```bash
-npx -y @starkscan/cli@0.2.0 --launcher-json
+npx -y @starkscan/cli@0.4.0 --launcher-json
 ```
 
 The JSON includes the package version, resolved binary path, release tag,

package/artifacts/{v0.2.0 → v0.4.0}/starkscan-cli-manifest.json

@@ -1,34 +1,34 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-19T06:51:05Z",
+  "generatedAt": "2026-09-24T05:05:09Z",
   "artifacts": [
     {
       "name": "starkscan-darwin-aarch64.tar.gz",
       "platform": "darwin-aarch64",
       "target": "darwin-aarch64",
       "archive": "starkscan-darwin-aarch64.tar.gz",
-      "sha256": "e12e2f38f46eecadb6b1a19bc8bf7cbd028b051fd46f87c52eeede752da4b844"
+      "sha256": "7e36da90db80cc546f65000bce4241fe09d196278c6d322a9c5b0479800cfd6a"
     },
     {
       "name": "starkscan-darwin-x86_64.tar.gz",
       "platform": "darwin-x86_64",
       "target": "darwin-x86_64",
       "archive": "starkscan-darwin-x86_64.tar.gz",
-      "sha256": "7bba139654743ed8a3c2247296207a217dbbfad52ca42fd5b04f84ef615f9378"
+      "sha256": "092f80c43b0e0f952c8727682873c5ee028ba7476dcedfe1a4883c8387a1f963"
     },
     {
       "name": "starkscan-linux-aarch64.tar.gz",
       "platform": "linux-aarch64",
       "target": "linux-aarch64",
       "archive": "starkscan-linux-aarch64.tar.gz",
-      "sha256": "3168a88eee1c97bd626e1100fe027a469a20ba9078ef75bc011c49198103e379"
+      "sha256": "300b5966af0dc68b01f5dc7f402c866b0d18221ab94a112eeaa67cf58eb9a6b5"
     },
     {
       "name": "starkscan-linux-x86_64.tar.gz",
       "platform": "linux-x86_64",
       "target": "linux-x86_64",
       "archive": "starkscan-linux-x86_64.tar.gz",
-      "sha256": "2bcb0f83fa9dca13bc4448085f054261ff0ab421414c6e5812aba361424ce88e"
+      "sha256": "f566a84cd3f5bb8cbfe7317e2e788ec8849daa17ae7638a263273ae5296e083a"
     }
   ]
 }

package/artifacts/v0.4.0/starkscan-darwin-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+7e36da90db80cc546f65000bce4241fe09d196278c6d322a9c5b0479800cfd6a  starkscan-darwin-aarch64.tar.gz

package/artifacts/v0.4.0/starkscan-darwin-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+092f80c43b0e0f952c8727682873c5ee028ba7476dcedfe1a4883c8387a1f963  starkscan-darwin-x86_64.tar.gz

package/artifacts/v0.4.0/starkscan-linux-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+300b5966af0dc68b01f5dc7f402c866b0d18221ab94a112eeaa67cf58eb9a6b5  starkscan-linux-aarch64.tar.gz

package/artifacts/v0.4.0/starkscan-linux-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+f566a84cd3f5bb8cbfe7317e2e788ec8849daa17ae7638a263273ae5296e083a  starkscan-linux-x86_64.tar.gz

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starkscan/cli",
   "private": false,
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Command-line launcher for Starkscan API, export, and agent workflows.",
   "license": "MIT",
   "type": "module",

package/artifacts/v0.2.0/starkscan-darwin-aarch64.tar.gz.sha256

@@ -1 +0,0 @@
-e12e2f38f46eecadb6b1a19bc8bf7cbd028b051fd46f87c52eeede752da4b844  starkscan-darwin-aarch64.tar.gz

package/artifacts/v0.2.0/starkscan-darwin-x86_64.tar.gz.sha256

@@ -1 +0,0 @@
-7bba139654743ed8a3c2247296207a217dbbfad52ca42fd5b04f84ef615f9378  starkscan-darwin-x86_64.tar.gz

package/artifacts/v0.2.0/starkscan-linux-aarch64.tar.gz.sha256

@@ -1 +0,0 @@
-3168a88eee1c97bd626e1100fe027a469a20ba9078ef75bc011c49198103e379  starkscan-linux-aarch64.tar.gz

package/artifacts/v0.2.0/starkscan-linux-x86_64.tar.gz.sha256

@@ -1 +0,0 @@
-2bcb0f83fa9dca13bc4448085f054261ff0ab421414c6e5812aba361424ce88e  starkscan-linux-x86_64.tar.gz