@scuro/sdk 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -1,51 +1,37 @@
 # Scuro SDK
 
-Bun-first TypeScript SDK for the Scuro protocol.
+Server-side TypeScript SDK for the Scuro protocol.
 
-This package is aimed at Node/Bun integrators who need to:
+This package is for backend applications and services that need to:
 
-- load Scuro protocol metadata and ABIs
+- load checked-in Scuro protocol metadata and ABIs
 - normalize deployment outputs into typed addresses and ids
-- build typed `viem` contract reads and transaction requests
-- use higher-level gameplay and staking helpers
-- run coordinator-style poker and blackjack proof workflows
+- prepare typed `viem` contract reads and transaction requests
+- use higher-level gameplay, settlement, and staking helpers
+- run coordinator-style poker and blackjack proof submission loops
 
-The SDK currently targets Bun first and standard Node server runtimes second. Browser support is out of scope for this version.
+The SDK supports standard Node.js and Bun server runtimes. It ships ESM output and is not intended for browser clients in this version.
 
 ## Status
 
-This is an early v1 scaffold with a working package surface, generated metadata pipeline, unit tests, and build output.
+This is an early v1 SDK with a working package surface, generated metadata pipeline, unit tests, and publishable build output.
 
-What is included:
+Included today:
 
 - root client via `createScuroClient(...)`
-- subpath-ready modules for `manifest`, `registry`, `contracts`, `flows`, `coordinator`, and `types`
+- subpath exports for `manifest`, `registry`, `contracts`, `flows`, `coordinator`, and `types`
 - generated protocol manifest, enum labels, event signatures, proof-input metadata, and ABI constants
 - typed tx builders for staking, governance, gameplay, settlement, engine-registry admin actions, proof submission, and supported factory deployments
 - runtime helpers for NumberPicker, Slot Machine, Super Baccarat, Chemin de Fer, poker, and blackjack
 - slot preset admin helpers and GameEngineRegistry read/write helpers
 - poker and blackjack coordinator executors with injected proof providers
 
-What is not included yet:
+Not included yet:
 
 - bundled proof generation or witness tooling
-- automatic fetching of AWS beta release manifests or actors records
+- automatic fetching of hosted beta release manifests or actor records
 - full live integration tests against a running local Scuro deployment
 
-## Package layout
-
-The package exports these entrypoints:
-
-- `@scuro/sdk`
-- `@scuro/sdk/manifest`
-- `@scuro/sdk/registry`
-- `@scuro/sdk/contracts`
-- `@scuro/sdk/flows`
-- `@scuro/sdk/coordinator`
-- `@scuro/sdk/types`
-
-The root entrypoint re-exports the main client constructor and the support modules.
-
 ## Install
 
 Use the prerelease channel while the SDK is aligned to the hosted beta network snapshot:
@@ -60,52 +46,98 @@ Use the stable channel only after a version has been intentionally promoted:
 npm install @scuro/sdk
 ```
 
-## Quick start
+## Runtime Expectations
+
+- Server-side runtime only: Node.js 18.14+ or Bun 1.3+
+- Package format: ESM
+- Primary transport/client dependency: [`viem`](https://viem.sh/)
+- Browser support: out of scope for this release
+
+## Quick Start
+
+### Read-only client
+
+Use a read-only client when you only need metadata, chain reads, or tx preparation.
 
 ```ts
-import { createPublicClient, createWalletClient, http } from "viem";
+import { createPublicClient, http } from "viem";
 import { foundry } from "viem/chains";
-import { privateKeyToAccount } from "viem/accounts";
 import { createScuroClient, getDeploymentProfile } from "@scuro/sdk";
 
-const deployment = getDeploymentProfile("anvil-local");
-if (!deployment) {
+const profile = getDeploymentProfile("anvil-local");
+if (!profile?.rpcUrl) {
   throw new Error("missing anvil-local profile");
 }
 
 const publicClient = createPublicClient({
   chain: foundry,
-  transport: http(deployment.rpcUrl)
+  transport: http(profile.rpcUrl)
+});
+
+const scuro = createScuroClient({
+  publicClient,
+  deployment: profile
+});
+
+const manifest = scuro.manifest.getProtocolManifest();
+const governorDelay = await scuro.flows.governance.readConfig();
+const approveTx = scuro.contracts.encode.approveSettlement(1000n);
+```
+
+### Signer-enabled client
+
+Add `walletClient` when you want the SDK to submit writes for you. Read and encode helpers still work without it.
+
+```ts
+import { createPublicClient, createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { foundry } from "viem/chains";
+import { createScuroClient, getDeploymentProfile } from "@scuro/sdk";
+
+const profile = getDeploymentProfile("anvil-local");
+if (!profile?.rpcUrl || !profile.privateKeys?.Admin) {
+  throw new Error("missing anvil-local signer config");
+}
+
+const transport = http(profile.rpcUrl);
+const account = privateKeyToAccount(profile.privateKeys.Admin);
+
+const publicClient = createPublicClient({
+  chain: foundry,
+  transport
 });
 
 const walletClient = createWalletClient({
   chain: foundry,
-  transport: http(deployment.rpcUrl),
-  account: privateKeyToAccount(deployment.privateKeys!.Admin!)
+  transport,
+  account
 });
 
 const scuro = createScuroClient({
   publicClient,
   walletClient,
-  deployment
+  deployment: profile
 });
 
-const manifest = scuro.manifest.getProtocolManifest();
-const approveTx = scuro.contracts.encode.approveSettlement(1000n);
+const txHash = await scuro.contracts.write.approveSettlement(1000n);
 ```
 
 Built-in deployment profiles currently include:
 
 - `anvil-local` for local Foundry/Anvil development
-- `testnet-beta` for the hosted private AWS beta pinned to the March 30, 2026 release handoff
+- `testnet-beta` for the hosted private beta pinned to the March 30, 2026 release handoff
+
+Beta package releases should only move the checked-in `testnet-beta` snapshot intentionally when a new hosted deployment is promoted.
 
-Beta package releases should only move this checked-in `testnet-beta` snapshot intentionally when a new hosted deployment is promoted.
+## Entrypoints
 
-## Core concepts
+### `@scuro/sdk`
 
-### `manifest`
+The root entrypoint exports the main client constructor plus the support modules.
 
-Use manifest helpers when you need checked-in protocol metadata, not chain state.
+### `@scuro/sdk/manifest`
+
+Use manifest helpers when you need checked-in protocol metadata instead of chain state.
 
 ```ts
 import { getAbi, getContractMetadata, getProtocolManifest } from "@scuro/sdk/manifest";
@@ -115,15 +147,32 @@ const settlementMeta = getContractMetadata("ProtocolSettlement");
 const settlementAbi = getAbi("ProtocolSettlement");
 ```
 
-### `registry`
+### `@scuro/sdk/registry`
 
-Use registry helpers to work with built-in deployment profiles or normalize your own chain-specific deployment records.
+Use registry helpers for built-in deployment profiles or to register and normalize your own deployment records.
 
 ```ts
-import { getDeploymentProfile, normalizeDeploymentLabels } from "@scuro/sdk/registry";
+import {
+  defineDeploymentProfile,
+  getDeploymentProfile,
+  normalizeDeploymentLabels
+} from "@scuro/sdk/registry";
 
 const hostedBeta = getDeploymentProfile("testnet-beta");
 
+defineDeploymentProfile({
+  key: "staging",
+  name: "Staging",
+  chainId: 31337,
+  rpcUrl: "https://staging-rpc.example.com",
+  labels: {
+    ScuroToken: "0x1000000000000000000000000000000000000001",
+    GameCatalog: "0x1000000000000000000000000000000000000005",
+    NumberPickerModuleId: "1",
+    NumberPickerExpressionTokenId: "1"
+  }
+});
+
 const deployment = normalizeDeploymentLabels({
   ScuroToken: "0x1000000000000000000000000000000000000001",
   GameCatalog: "0x1000000000000000000000000000000000000005",
@@ -132,11 +181,9 @@ const deployment = normalizeDeploymentLabels({
 });
 ```
 
-The built-in `testnet-beta` profile is a checked-in snapshot of the March 30, 2026 private AWS beta release record. The canonical source of truth remains the protocol release artifacts, and SDK updates should only change this profile intentionally when a new deployment is promoted.
-
-### `contracts`
+### `@scuro/sdk/contracts`
 
-Use contract helpers when you want typed transaction preparation, direct reads, and low-level control over write submission.
+Use contract helpers when you want typed transaction preparation, direct reads, and explicit write submission.
 
 ```ts
 const tx = scuro.contracts.encode.startBlackjackHand({
@@ -148,15 +195,15 @@ const tx = scuro.contracts.encode.startBlackjackHand({
 const session = await scuro.contracts.read.blackjack.session(1n);
 ```
 
-### `flows`
+### `@scuro/sdk/flows`
 
-Use flow helpers when you want documented workflow steps with some state guards already applied.
+Use flow helpers when you want workflow-oriented helpers with useful state guards already applied.
 
 ```ts
 const stakingTxs = scuro.flows.staking.prepareApproveAndStake({
   approveAmount: 1000n,
   stakeAmount: 1000n,
-  delegatee: deployment.labels.Admin
+  delegatee: scuro.deployment.actors.Admin
 });
 
 const blackjackActionTx = await scuro.flows.blackjack.prepareAction(7n, "doubleDown");
@@ -168,11 +215,11 @@ const slotTx = scuro.flows.slotMachine.prepareSpin({
 });
 ```
 
-### `coordinator`
+### `@scuro/sdk/coordinator`
 
-Use coordinator helpers for operational proof submission loops.
+Use coordinator helpers for operational proof submission loops in backend services.
 
-Proof generation stays outside the SDK. You inject proof providers that return the concrete calldata fields each engine expects.
+Proof generation stays outside the SDK. You inject proof providers that return the calldata each engine expects.
 
 ```ts
 const blackjackCoordinator = scuro.coordinator.blackjack({
@@ -189,106 +236,16 @@ const blackjackCoordinator = scuro.coordinator.blackjack({
 await blackjackCoordinator.runUntilIdle(3n);
 ```
 
-More detail is in [docs/coordinators.md](./docs/coordinators.md).
-
-## Supported helpers in this version
-
-### Gameplay and protocol helpers
-
-- staking approvals, stake, unstake, and delegation
-- governance reads for threshold, delay, period, quorum, and state
-- catalog reads for module metadata and launchability checks
-- GameEngineRegistry reads and admin writes
-- NumberPicker play/finalize helpers
-- Slot Machine spin/settle helpers and slot preset admin helpers
-- Super Baccarat play/settle helpers
-- Chemin de Fer table lifecycle helpers
-- PvP poker session create/settle helpers
-- tournament poker create/start/report helpers
-- blackjack start/action/timeout/settle helpers
-- settlement tx builders
-- event decoding through protocol ABIs
-
-### Factory deployment helpers
-
-Typed deployment-param encoders are included for:
-
-- NumberPicker
-- Blackjack
-- Super Baccarat
-- Slot Machine
-- Poker Single Draw 2-7
-- Chemin de Fer Baccarat
-
-Unsupported or underdocumented families should use the raw factory escape hatches. For the new solo and chemin modules, gameplay helpers require explicit `expressionTokenId` values rather than relying on built-in local profile defaults.
-
-## Generated metadata
-
-The SDK does not read the sibling Scuro repo at runtime.
-
-Instead, `bun run generate-protocol` uses the checked-in upstream generated metadata as a base, then supplements missing module surfaces from sibling protocol artifacts:
-
-- `../scuro/docs/generated/protocol-manifest.json`
-- `../scuro/docs/generated/enum-labels.json`
-- `../scuro/docs/generated/event-signatures.json`
-- `../scuro/docs/generated/proof-inputs.json`
-- `../scuro/docs/generated/contracts/*.abi.json`
-- `../scuro/out/SlotMachine*.json`
-- `../scuro/out/SuperBaccarat*.json`
-- `../scuro/out/CheminDeFer*.json`
-- `../scuro/out/ICheminDeFerEngine.sol/ICheminDeFerEngine.json`
-
-The generated output is written into [`src/generated`](./src/generated).
-
-## Development
-
-Install dependencies:
-
-```bash
-bun install
-```
-
-Regenerate protocol metadata:
-
-```bash
-bun run generate-protocol
-```
-
-Run checks:
-
-```bash
-bun test
-bun run typecheck
-bun run build
-bun run smoke:node
-bun run release:check
-```
-
-More detail is in [docs/development.md](./docs/development.md).
-The maintainer release playbook lives in [docs/releasing.md](./docs/releasing.md).
-
-## Release preparation
-
-The package is set up to publish from built `dist/` output only.
-
-Useful preflight commands:
-
-```bash
-bun run release:check
-bun run release:pack
-```
-
-`bun run release:check` runs tests, typechecking, a fresh build, and a local release verification pass that confirms the exported files exist.
-`bun run release:pack` writes the tarball to `.artifacts/releases/` so release artifacts stay out of the repo root.
-
-GitHub Actions workflows are included for:
+## Deeper Guides
 
-- CI on pull requests and pushes to `main`
-- npm publish on GitHub Release publication, with prereleases publishing to the npm `beta` dist-tag and stable releases publishing to `latest`
-- optional beta testnet RPC smoke checks when `ENABLE_BETA_RPC_SMOKE=true`
+- Integration guide: [docs/integration.md](./docs/integration.md)
+- Coordinator operations: [docs/coordinators.md](./docs/coordinators.md)
+- Contributor development workflow: [docs/development.md](./docs/development.md)
+- Maintainer release workflow: [docs/releasing.md](./docs/releasing.md)
 
-## Notes and caveats
+## Notes and Caveats
 
 - The built-in registry currently ships `anvil-local` and the pinned `testnet-beta` hosted profile.
+- `walletClient` is optional on `createScuroClient(...)`, but write helpers require a signer and will fail without one.
 - The coordinator layer is designed for server-side orchestration, not browser automation.
 - Public helper types are intentionally lightweight in this revision to keep declaration output stable while the API is still settling.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@scuro/sdk",
-  "version": "0.1.0-beta.1",
-  "description": "Bun-first TypeScript SDK for the Scuro protocol",
+  "version": "0.1.0-beta.2",
+  "description": "Server-side TypeScript SDK for the Scuro protocol",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",