Public Client 1.0 Contract
Semver, deprecation, and conformance policy for Starkscan SDK and CLI 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 public package train remains 0.x; resolve
the active exact version from npm. 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/sdkand@starkscan/cli - stable SDK top-level exports, client methods, low-level API methods, errors, and documented response envelopes
- stable CLI commands and JSON output/error shape
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, and every CLI command. 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, and feed. | Address batch intelligence, contract verification, and contract events. |
Hidden compatibility aliases are not public contracts. Their existence does not make them safe to list in docs, advertise in help output, or depend on from a new integration.
Semver policy
Before 1.0, the active 0.x line may add fields, helpers, and commands 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 or CLI command is non-breaking
- removing or renaming a stable helper, command, 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. The CLI launches 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 with elevated OS privileges.
Conformance before 1.0
Before a 1.0 promotion, run both default-install and exact-pin checks:
@starkscan/sdkand@starkscan/clidefault 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 - exact pins repeat the same checks before unattended customer rollout
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.