@misonetwork/sdk 0.6.0 → 0.8.0

package/README.md

@@ -1,172 +1,229 @@
 # @misonetwork/sdk
 
-TypeScript SDK for the [Miso](https://github.com/misonetwork/protocol) protocol
-core on [Sui](https://sui.io). Bindings are regenerated from the local
-`misonetwork/protocol` Move source with `bun run codegen`.
+TypeScript bindings, Core API queries, event decoders, and composable PTB
+builders for the current Miso Move sources on Sui:
 
-Miso models compositions, recordings, releases, their rights, and royalties as
-Sui objects. This package provides core queries, PTB primitives, generated BCS
-bindings, event parsers, and a client extension. First-party policy and
-extension helpers live in [`@misofm/sdk`](https://github.com/misofm/sdk).
+- core `miso`, including its canonical `release::ReleaseRegistry`;
+- all first-party `protocol-extensions` packages;
+- generic `royalty_pool` and `routed_stake` primitives.
+
+The SDK does not publish packages, select gas, sign transactions, or request
+faucet funds. Publishing is an operational step performed with the configured
+`admin-cli` signer (Ledger or a securely supplied private key); this SDK is
+updated only after the resulting package addresses are verified.
+
+## 0.8.0 release boundary
+
+`0.8.0` is the coordinated breaking protocol SDK release consumed by
+`@misofm/sdk@0.10.0`. Platform consumers install this package as a peer, so an
+application owns one verified protocol SDK instance rather than accepting a
+nested, stale protocol copy through the platform package.
 
 ## Installation
 
-```bash
+```sh
 bun add @misonetwork/sdk @mysten/sui
 ```
 
-## Client extension
+The package is ESM-only and uses `@mysten/sui` v2 APIs.
 
-```ts
-import { SuiGrpcClient } from "@mysten/sui/grpc";
-import { miso } from "@misonetwork/sdk";
+### Pre-publish Git-head workflow
 
-const client = new SuiGrpcClient({
-  network: "testnet",
-  baseUrl: "https://fullnode.testnet.sui.io:443",
-})
-  .$extend(miso());
+Before these versions are published, an application consuming the immutable Git
+heads must let Bun run both source-package `prepare` scripts. Its root
+`package.json` must include exactly these SDK entries in `trustedDependencies`:
 
-const recording = await client.miso.getRecordingById("0x...");
-const adminCapId = client.miso.deriveRecordingAdminCapId("0x...");
+```json
+{
+  "trustedDependencies": ["@misonetwork/sdk", "@misofm/sdk"]
+}
 ```
 
-Pass a `SuiGraphQLClient` as `graphqlClient` only for generic type discovery,
-such as `getCompositionByShareType` and `getRecordingByShareType`. ID reads and
-owned-cap queries use the Core API.
+Then install both SDKs by their exact Git commit IDs at the application root.
+Without those trusted entries, Bun blocks the source `prepare` scripts and the
+Git packages have no `dist` artifact to import. This requirement is only for
+the pre-publish source-Git workflow. Published npm packages and packed tarballs
+already contain `dist`; install those normally, with this package satisfying
+`@misofm/sdk`'s `^0.8.0` peer at the application root.
 
-The current Testnet package is bundled with the SDK and selected from the Sui
-client's network. Mainnet fails closed until this protocol ABI is deployed there;
-custom deployments can be supplied explicitly with `miso({ deployment })`.
+## Deployment manifests fail closed
 
-## Data model
+There are intentionally no bundled package IDs in this release. The previously
+bundled Testnet core ID was removed because it does not prove compatibility with
+the fresh source ABI. Calling `miso()` without a deployment therefore throws on
+every network until a verified manifest is released.
 
-- `Composition`: the written work, with a share currency and royalty rate.
-- `Recording`: an audio performance of a composition, with its own share currency.
-- `Track`: a recording admin's consent to an exact target release ID and split.
-- `Release`: a flat ordered sequence of tracks. Disc/side grouping is extension
-  presentation data, not core state.
-
-Core objects are built then published. Credits, cover art, royalty pools, and
-release coordination are extension-layer concerns in `@misofm/sdk`.
-
-## Queries
-
-All client methods are also exported as standalone functions.
+After the Ledger-backed publishes complete, copy the exact IDs from the publish
+record into the one `MISO_DEPLOYMENTS.<network>` entry in
+[`src/deployments.ts`](./src/deployments.ts). A manifest is complete by design:
 
 ```ts
-const release = await client.miso.getReleaseById("0x...");
-const caps = await client.miso.getOwnedReleaseAdminCaps(ownerAddress);
-const [recordingShare, compositionShare] = await getRecordingShareTypes(
-  client,
-  "0x...",
-);
+import type { MisoDeployment } from "@misonetwork/sdk";
+
+const deployment: MisoDeployment = {
+  miso: "0x…",
+  compositionCredits: "0x…",
+  recordingAdvisory: "0x…",
+  recordingCredits: "0x…",
+  recordingLanguage: "0x…",
+  recordingMasterReference: "0x…",
+  recordingPreview: "0x…",
+  releaseCoverArt: "0x…",
+  releaseCredits: "0x…",
+  releaseDescription: "0x…",
+  releaseDspLink: "0x…",
+  releaseGenre: "0x…",
+  releaseKind: "0x…",
+  releaseSnapshotBundle: "0x…",
+  royaltyPool: "0x…",
+  routedStake: "0x…",
+};
 ```
 
-Core object getters throw for a missing object. The exported `isNotFound(error)`
-helper distinguishes that condition from transport failures.
+Do not substitute an address from an older source release. `assertMisoDeployment`
+rejects partial manifests, making the follow-up address update mechanical and
+reviewable.
 
-## Transaction primitives
+## Client extension and generated calls
 
-The core exports these synchronous builders, each operating on the caller's
-`Transaction`:
+Use a complete manifest to make every generated package call address-safe. The
+generated wrappers accept typed Move arguments and append commands to a
+caller-owned `Transaction`; they do not execute it.
 
-| Builder | Result |
-| --- | --- |
-| `createComposition(tx, params)` | `CompositionParts` |
-| `createRecording(tx, params)` | `RecordingParts` |
-| `createTrack(tx, params)` | `TransactionObjectArgument` |
+```ts
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+import { miso, type MisoDeployment } from "@misonetwork/sdk";
 
-`createTrack` adds cap-gated `track::new`; it accepts either an on-chain
-`recordingAdminCapId` or a PTB-local `recordingAdminCap` result. A `Track` has
-`drop, store`, so leaving it unconsumed is valid. To create a release, collect
-tracks with `tx.makeMoveVec({ type: `${misoPackageId}::track::Track`, elements })`
-and call the extension's `release_registry::new_release` via `@misofm/sdk`.
+declare const deployment: MisoDeployment;
+declare const recordingId: string;
+declare const recordingAdminCapId: string;
+declare const recordingShareType: string;
+declare const compositionShareType: string;
 
-```ts
-import { createTrack } from "@misonetwork/sdk";
-
-const track = createTrack(tx, {
-  recordingId: "0x...",
-  recordingAdminCapId: "0x...",
-  recordingShareType: "0x...::share::Share",
-  compositionShareType: "0x...::share::Share",
-  targetReleaseId: "0x...",
-  trackSplitBps: 5000,
-  misoPackageId,
-});
+const client = new SuiGrpcClient({
+  network: "testnet",
+  baseUrl: "https://fullnode.testnet.sui.io:443",
+}).$extend(miso({ deployment }));
+
+const tx = new Transaction();
+tx.add(
+  client.miso.packages.call.extensions.recordingAdvisory.unsetRating({
+    typeArguments: [recordingShareType, compositionShareType],
+    arguments: [tx.object(recordingId), tx.object(recordingAdminCapId)],
+  }),
+);
 ```
 
-`createComposition` and `createRecording` return their by-value components so
-they can be composed in the same PTB. `recording::new` borrows its composition,
-so a fresh composition can be passed directly into `createRecording` before it
-is published.
+`client.miso.call` remains the core-only compatibility surface. Use
+`client.miso.packages.call` for core, extension, utility, and primitive calls
+bound to the full manifest. The raw codegen surface mirrors public Move
+functions; the package-bound call surface excludes return-by-reference views,
+because a PTB command result cannot carry a reference. Read those values through
+object or dynamic-field queries instead.
+
+The `contracts` namespace exposes the same unbound generated modules and BCS
+codecs for advanced callers. Its `@local-pkg/*` names are source labels, never
+deployment addresses.
 
-### Release IDs
+## PTB builders
 
-Release IDs are derived on chain by simulation. `parentId` is a pure object ID,
-not an object input—for example, the shared `ReleaseRegistry` owned by the
-extension package.
+The hand-maintained builders cover the values that must remain inside the same
+PTB and make their ownership explicit:
+
+| Builder | Result / rule |
+| --- | --- |
+| `createComposition`, `createRecording` | Return object, admin cap, and share balance by value. |
+| `createTrack` | Returns a `Track` for later release assembly. |
+| `createRelease` | Calls core `release::new` with the shared registry as its first object argument; returns release and cap to publish. |
+| `publishComposition`, `publishRecording`, `publishRelease` | Consume and share an initialized core object. |
+| `createRoyaltyStake`, `destroyRoyaltyStake` | Convert a `Balance<Share>` to/from a stake; each non-drop result must be registered, destroyed, or transferred in that PTB. |
+| `registerRoyaltyStake`, `claimRoyaltyRewards` | Operate against a shared royalty pool; claimed balance must be consumed. |
+| `sweepRoutedStake` | Permissionlessly routes accrued rewards into the parent pool. |
+
+Some generic functions intentionally have no standalone PTB helper: creating a
+royalty pool or a routed stake requires a parent module's `&mut UID`. Those
+operations belong in a cap-gated parent/authority Move module. Vault custody
+and authority plugins are intentionally owned by `@misofm/sdk`; their `entry`
+functions still compose as normal commands in a multi-command PTB.
+
+For example, create and publish a release entirely in one transaction:
 
 ```ts
-const targetReleaseId = await client.miso.view.deriveTargetReleaseId({
-  sender: ownerAddress,
-  recordingIds: ["0x...", "0x..."],
-  splitBps: [5000, 5000],
-  nonce: "42",
-  parentId: releaseRegistryId,
+const release = createRelease(tx, {
+  releaseRegistryId,
+  title: "Release title",
+  tracks: [track],
+  nonce: 42n,
+  misoPackageId: deployment.miso,
+});
+publishRelease(tx, {
+  release: release.release,
+  adminCap: release.adminCap,
+  misoPackageId: deployment.miso,
 });
 ```
 
-Generated `contracts.release._new` is intentionally exposed because codegen
-mirrors the ABI, but it is not PTB-callable: its final parameter is `&mut UID`.
-Release construction therefore belongs in `@misofm/sdk`, whose
-`release_registry::new_release` already owns that UID.
-
-### Generated bindings
+## Queries and events
 
-`contracts` and `client.miso.call` expose generated `composition`, `recording`,
-`release`, and `track` modules. Do not edit `src/contracts/`; run `bun run
-codegen` after updating protocol source.
+Core reads use the transport-neutral `ClientWithCoreApi` and BCS object content:
 
 ```ts
-tx.add(client.miso.call.track._new({
-  typeArguments: [recordingShareType, compositionShareType],
-  arguments: [adminCap, tx.object(recordingId), tx.pure.id(targetReleaseId), tx.pure.u16(5000)],
-}));
+const release = await client.miso.getReleaseById(releaseId);
+const pool = await getRoyaltyPoolById(client, poolId);
+const routedStake = await getRoutedStakeById(client, routedStakeId);
 ```
 
-## Event parsers
-
-Core emits only publish/royalty events. Parse them with
-`client.miso.parse.compositionPublishedEvent`,
-`compositionRoyaltySetEvent`, `recordingPublishedEvent`, and
-`releasePublishedEvent`. Track creation has no core event; pre-publish
-observability is an extension concern.
+`getExtensionField` reads optional fieldless-key extension data from a core
+object's UID. Supply the fresh extension package ID, module name, and generated
+value codec; an absent field returns `null` while RPC failures still throw.
+`release_dsp_link` is intentionally different: use `getReleaseDspLink` and
+`getTrackDspLinks`, which query `ReleaseLinkKey(platform)` and
+`TrackLinksKey(platform)` rather than `ExtensionKey`.
+
+`eventParsers` decodes the raw BCS payloads for the core registry, every current
+extension, `royalty_pool`, and `routed_stake` event. The legacy
+camel-case helpers remain available as
+`parseCompositionPublishedEvent`, `parseRecordingPublishedEvent`,
+`parseCompositionSharesGrantedEvent`, `parseReleasePublishedEvent`, and
+`parseReleaseRegistryCreatedEvent`.
+
+## Regenerating bindings
+
+The source checkout layout is expected to be:
+
+```text
+misonetwork/
+  sdk/
+  protocol/
+  protocol-extensions/
+  royalty-pool/
+  routed-stake/
+```
 
-## 0.4.0 → 0.5.0 migration
+Run:
 
-| Previous API | 0.5.0 |
-| --- | --- |
-| `createDeal` | `createTrack`; use `targetReleaseId` rather than `releaseId` |
-| `rejectDeal`, `getDealById`, Deal event parsers/types, `contracts.deal` | removed; offer/withdrawal policy is extension-layer |
-| `createRelease` | removed; use `@misofm/sdk` `release_registry::new_release` |
-| `deriveReleaseId({ releaseRegistryId })` | `deriveTargetReleaseId({ parentId })`; the parent is pure |
-| `getReleaseRegistry`, `MisoOptions.releaseRegistryId` | removed; extension registry is a different package type |
-| `client.miso.tx` | removed; no core thunk builders remain |
-| deployed disc-shaped release fallback | removed; reads parse only canonical flat `Release.tracks` |
+```sh
+bun run codegen
+bun run codegen:check
+bun run typecheck
+bun test
+bun run build
+```
 
-Update `@misofm/sdk` in the same release window: it owns release-registry
-bindings and the callable release-construction flow.
+`bun run codegen` creates each Move summary in a temporary directory, then
+updates only `src/contracts/`; it does not write `package_summaries/` into any
+sibling source worktree. When testing an isolated SDK copy, set
+`MISO_SDK_CODEGEN_SOURCE_ROOT` to the SDK checkout whose sibling Move sources
+should be read.
 
-## Derived admin caps
+## Legacy compatibility
 
-| Function | Parent |
-| --- | --- |
-| `deriveCompositionAdminCapId` | Composition |
-| `deriveRecordingAdminCapId` | Recording |
-| `deriveReleaseAdminCapId` | Release |
+`miso({ misoPackageId })` and `MisoProtocolDeployment` remain available for a
+core-only caller that supplies its own verified package address. The deprecated
+`MISO_PROTOCOL_DEPLOYMENTS` name is an empty alias of `MISO_DEPLOYMENTS`; it
+does not retain the removed address map.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](./LICENSE)