@starkscan/cli 0.3.0 → 0.4.0

package/README.md

@@ -3,10 +3,11 @@
 Command-line Starkscan client for status checks, explorer reads, local exports,
 and agent setup.
 
-Release target: `0.3.0`. This release carries the address-activity truth
-contract and its typed nullable output through the native CLI. Use the untagged
-install only after the live `latest` verifier passes; pin `0.3.0` for
-reproducible installs after that promotion.
+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
 
@@ -24,11 +25,11 @@ npx -y @starkscan/cli init --agent --output-format json
 Exact pin for unattended services:
 
 ```bash
-npx -y @starkscan/cli@0.3.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.3.0`
+Normal users and agents should use the default package or the exact `0.4.0`
 pin above.
 
 ## First commands
@@ -45,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.
@@ -61,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.3.0 init --agent --output-format json
-npx -y @starkscan/cli@0.3.0 mcp print-config --transport remote
-npx -y @starkscan/cli@0.3.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
@@ -80,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.3.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.3.0 → v0.4.0}/starkscan-cli-manifest.json

@@ -1,34 +1,34 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-23T10:59:46Z",
+  "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": "64bca370039c26deb950e0f3aaabb5854dda2e2605e66c98eb5e21ef0aa7eada"
+      "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": "e8f870c07168ce0150565121f3ce2e8bee7ae4fbf333c0f7dcd7d4c5f271fc79"
+      "sha256": "092f80c43b0e0f952c8727682873c5ee028ba7476dcedfe1a4883c8387a1f963"
     },
     {
       "name": "starkscan-linux-aarch64.tar.gz",
       "platform": "linux-aarch64",
       "target": "linux-aarch64",
       "archive": "starkscan-linux-aarch64.tar.gz",
-      "sha256": "73dd78b4adb56aa38e0e0ed5154d5e6f9866ae9d749967ebad64df8154984cdd"
+      "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": "c7378ba211aedaf57c46a1fc73d6113c7dc3a407f2a7b230edd06d30f4a2b4b9"
+      "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.3.0",
+  "version": "0.4.0",
   "description": "Command-line launcher for Starkscan API, export, and agent workflows.",
   "license": "MIT",
   "type": "module",

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

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

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

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

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

@@ -1 +0,0 @@
-73dd78b4adb56aa38e0e0ed5154d5e6f9866ae9d749967ebad64df8154984cdd  starkscan-linux-aarch64.tar.gz

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

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