Public Client 1.0 Contract
Semver, deprecation, and conformance policy for Starkscan SDK, CLI, and MCP packages.
Public client 1.0 contract
Use this page when deciding whether a Starkscan package surface is safe to put
behind an unattended integration. The current public package line is still
0.1.x; this page defines the compatibility bar that must be true before a
future 1.0 promotion.
Machine-readable source:
public-client-surface-matrix.json,
field onePointZeroContract.
Related launch state: Launch matrix
Related package trust: Package trust
Stability labels
| Label | Contract |
|---|---|
stable | Semver-protected after 1.0; removals, required-input changes, response-envelope weakening, and renamed package entrypoints require a major version. |
beta | Supported for named clients or documented beta workflows, but not part of the 1.0 stable compatibility promise until promoted. |
experimental | Visible or exported for advanced use; may change in minor versions and should not be used in unattended production without a separate agreement. |
maintainer-only | Internal release or diagnostic surface; not a public package contract. |
deprecated | Still callable in the current line, but scheduled for removal under the deprecation policy. |
Stable 1.0 promise
The 1.0 stable promise covers:
- package names and executable entrypoints for
@starkscan/sdk,@starkscan/cli, and@starkscan/mcp - stable SDK top-level exports, client methods, low-level API methods, errors, and documented response envelopes
- stable CLI commands and JSON output/error shape
- stable MCP launcher behavior and advertised stable MCP tools
STARKSCAN_API_KEY, hosted default base URL behavior, request IDs, rate-limit headers, andRetry-Afterhandling
The machine matrix classifies every public SDK export, every chain-bound SDK method, every low-level SDK API method, every CLI command, every CLI MCP subcommand, and every advertised MCP tool. If source adds a public method or command without updating the matrix, validation fails.
Package surfaces
| Surface | Stable after 1.0 | Beta in the package |
|---|---|---|
| TypeScript SDK | Core status, block, transaction, address, token, search, contract metadata, contract read, HTTP client, and data-honesty helpers. | Live feed helpers, event pages, address-intelligence batches, contract verification, unsigned write-payload construction, strkBTC helpers, and protocol/message-oriented types. |
| Agent CLI | Setup, doctor, examples, status, search, block, tx, tx-details, address, address activity/transactions/holdings/attribution, contract entrypoints/read, token reads/transfers, feed, and MCP launcher commands. | Address batch intelligence, contract verification, and contract events. |
| MCP launcher/tools | Hosted launcher config plus status, block, tx, address summary/activity/holdings, contract entrypoints/read, token summary/reads/transfers, and search. | Contract verification, unsigned write payloads, and token holders. |
Hidden compatibility aliases are not public contracts. Their existence does not
make them safe to list in docs, advertise in tools/list, or depend on from a
new integration.
Semver policy
Before 1.0, the 0.1.x line may add fields, helpers, commands, and tools in
minor releases. Breaking removals should still be avoided for stable-labeled
package surfaces and must be called out in release notes.
After 1.0, stable surfaces follow semantic versioning:
- adding optional response fields is non-breaking
- adding optional request parameters with defaults is non-breaking
- adding a new beta helper, CLI command, or MCP tool is non-breaking
- removing or renaming a stable helper, command, tool, env var, package entrypoint, documented field, or stable error class is breaking
Deprecation policy
Stable surfaces get at least one minor release of documentation and runtime or help-text notice before removal, unless the old behavior is a security risk. Beta surfaces should get one minor release notice when practical. Experimental surfaces can change faster, but user-visible changes still need release notes.
Runtime support
The public contract targets Node.js 20 or newer. The SDK is ESM. CLI and MCP launch through npm package bins. The native CLI artifact set is:
darwin-aarch64darwin-x86_64linux-aarch64linux-x86_64
Supported package managers for install smoke are npm, pnpm, and bun. Do not run the CLI or MCP launcher with elevated OS privileges.
Conformance before 1.0
Before a 1.0 promotion, run both default-install and exact-pin checks:
@starkscan/sdk,@starkscan/cli, and@starkscan/mcpdefault installs resolve to the intended stable train- SDK clean install, Node ESM import,
createStarkscanClient, public status smoke, and request-id/error access pass - CLI
doctor,status, auth failure shape, JSON output, and request-id prefix pass - MCP
print-config,tools/list, hosted HTTP headers, and stdio newline framing pass - exact pins repeat the same checks before unattended customer rollout
MCP and CLI must use matching exact package versions. A rollback must pin the previous known-good exact version and rerun the same smoke set.
Non-claims
This contract is not a supply-chain provenance claim. Package trust remains separate and is tracked on Package trust. This contract is also not a promise that every beta route is certified for every customer workload; route certification remains in the OpenAPI metadata and launch matrix.