@misonetwork/sdk 0.3.1 → 0.5.0

package/README.md

@@ -1,17 +1,13 @@
 # @misonetwork/sdk
 
-TypeScript SDK for the [Miso](https://github.com/misonetwork/miso-protocol) protocol on [Sui](https://sui.io).
+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`.
 
-This package mirrors the on-chain ABI of the [`misonetwork/miso-protocol`](https://github.com/misonetwork/miso-protocol) Move package — the protocol core, and nothing else — regenerated from the live Move source via `bun run codegen`.
-
-Miso is a permissionless on-chain music protocol that models compositions, recordings, and releases — and their associated rights and royalties — as Sui objects. This SDK provides typed queries, composable transaction builders, BCS event parsers, and a client extension.
-
-Helpers for the first-party **extensions** — credits, cover art, royalty pools —
-live in [`@misofm/sdk`](https://github.com/misofm/sdk), not here. An extension is
-opinionated business logic hung off the protocol's `&mut UID` hook (which roles
-exist and what they are called, what a cover is, how royalties accumulate), so it
-ships with the platform layer. The protocol package stays the open thing anyone
-can build on without adopting Miso's opinions.
+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).
 
 ## Installation
 
@@ -19,555 +15,153 @@ can build on without adopting Miso's opinions.
 bun add @misonetwork/sdk @mysten/sui
 ```
 
-## Quick Start
+## Client extension
 
 ```ts
 import { SuiGrpcClient } from "@mysten/sui/grpc";
 import { miso } from "@misonetwork/sdk";
 
-const client = new SuiGrpcClient({ network: "testnet" })
+const client = new SuiGrpcClient({
+  network: "testnet",
+  baseUrl: "https://fullnode.testnet.sui.io:443",
+})
   .$extend(miso({ misoPackageId: "0x..." }));
 
-// Fetch a recording
 const recording = await client.miso.getRecordingById("0x...");
-console.log(recording.state); // display title comes from the parent composition
-
-// Derive an admin cap ID (pure, no network call)
 const adminCapId = client.miso.deriveRecordingAdminCapId("0x...");
 ```
 
-## Client Extension
-
-The SDK provides a `miso()` client extension that works with any Sui client implementing the Core API:
-
-```ts
-import { SuiGrpcClient } from "@mysten/sui/grpc";
-import { SuiGraphQLClient } from "@mysten/sui/graphql";
-import { miso } from "@misonetwork/sdk";
-
-const graphqlClient = new SuiGraphQLClient({
-  url: "https://sui-testnet.mystenlabs.com/graphql",
-  network: "testnet",
-});
-
-const client = new SuiGrpcClient({ network: "testnet" })
-  .$extend(miso({
-    misoPackageId: "0x...",
-    graphqlClient,            // Required for generic type-based queries (getByShareType, getOwnedCompositionAdminCaps, getOwnedRecordingAdminCaps, getReleaseRegistry, getAdministeredRecordings)
-  }));
-```
-
-### API Priority
-
-Methods use the most efficient transport available:
+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.
 
-| Transport | When Used | Examples |
-|-----------|-----------|----------|
-| **Core API** | Single-object fetch by ID, derivation | `getRecordingById`, `deriveCompositionAdminCapId` |
-| **Core API** | Non-generic type queries | `getOwnedReleaseAdminCaps` |
-| **GraphQL** | Generic type queries (partial type matching) | `getOwnedCompositionAdminCaps`, `getRecordingByShareType` |
+## Data model
 
-## Data Model
+- `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.
 
-Miso stores only protocol-verifiable state. Each entity follows a build-then-freeze
-lifecycle (`Initialized → Published`) and is immutable once published.
-
-- **Composition** — the underlying written work. Earns an immutable-floored `royaltyRate` from each recording. Backed by its own share currency.
-- **Recording** — an audio performance of a composition. Backed by its own share currency. Carries no name of its own — its display title is its composition's title; richer naming lives in the metadata extension.
-- **Release** — a flat, ordered tracklist of `Track`s (album, EP, or single), assembled from `Deal`s. Display grouping (discs/sides) lives in extensions.
-- **Deal** — a recording admin's transferable authorization to include the recording on one exact release id.
-
-Everything else — credits, cover art, royalty pools, masters, descriptive
-metadata — attaches to the frozen core objects as dynamic fields through
-extension packages (see [Extensions](#extensions)).
-
-On publish, each entity emits a single lean pointer event carrying just its identity;
-indexers subscribe to that pointer and fetch the immutable object by ID.
+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 available as standalone functions (taking the client
-explicitly) from the package root.
-
-### Compositions
-
-```ts
-// Core API (by ID)
-const comp = await client.miso.getCompositionById("0x...");
-const comps = await client.miso.getCompositionsByIds(["0x...", "0x..."]);
-const capId = client.miso.deriveCompositionAdminCapId("0x...");
-const cap = await client.miso.getCompositionAdminCapById(capId);
-const shareType = await client.miso.getCompositionShareType("0x...");
-
-// GraphQL (by type or owner)
-const comp2 = await client.miso.getCompositionByShareType("0x...::share::Share");
-const caps = await client.miso.getOwnedCompositionAdminCaps(ownerAddress);
-```
-
-### Recordings
+All client methods are also exported as standalone functions.
 
 ```ts
-// Core API (by ID)
-const rec = await client.miso.getRecordingById("0x...");
-const recs = await client.miso.getRecordingsByIds(["0x...", "0x..."]);
-const recCapId = client.miso.deriveRecordingAdminCapId("0x...");
-const recCap = await client.miso.getRecordingAdminCapById(recCapId);
-
-// A Recording is generic over two phantoms — Recording<RecordingShare, CompositionShare>.
-const recShareType = await client.miso.getRecordingShareType("0x...");  // the recording's OWN share type
-const [recShare, compShare] = await getRecordingShareTypes(client, "0x..."); // both, in that order
-
-// GraphQL (by type or owner)
-const rec2 = await client.miso.getRecordingByShareType("0x...::share::Share");
-const recCaps = await client.miso.getOwnedRecordingAdminCaps(ownerAddress);
-const administered = await client.miso.getAdministeredRecordings(ownerAddress);
-```
-
-`getRecordingShareType` returns the recording's own share type
-(`RecordingShare`) and is bound on the client. `getRecordingShareTypes` is the
-standalone query that returns both as `[RecordingShare, CompositionShare]` —
-reach for it when building anything generic over the pair, which is most of the
-protocol: `deal::new`, `track::new`, `recording::publish`, and the recording
-credit/royalty-pool extensions all take the two phantoms in exactly that order.
-
-### Deals
-
-```ts
-// Share types are read from the object's `Deal<RecordingShare, CompositionShare>` type parameters.
-const deal = await client.miso.getDealById("0x...");
-// { id, releaseId, trackSplitBps, recordingShareType, compositionShareType }
-```
-
-### Releases
-
-```ts
-// Core API (by ID)
 const release = await client.miso.getReleaseById("0x...");
-const releases = await client.miso.getReleasesByIds(["0x...", "0x..."]);
-const relCapId = client.miso.deriveReleaseAdminCapId("0x...");
-const relCap = await client.miso.getReleaseAdminCapById(relCapId);
-const relCaps = await client.miso.getOwnedReleaseAdminCaps(ownerAddress);
-
-// GraphQL
-const registryId = await client.miso.getReleaseRegistry();
-```
-
-### Share currencies
-
-```ts
-const shareType = await client.miso.getShareCurrencyType("0x...");  // Currency<T> object id → T
-// Takes the share TYPE (which builders already thread around), not the Currency
-// object id — so this is one call, not two.
-const treasuryCapId = await client.miso.getShareCurrencyTreasuryCap(shareType, ownerAddress);
+const caps = await client.miso.getOwnedReleaseAdminCaps(ownerAddress);
+const [recordingShare, compositionShare] = await getRecordingShareTypes(
+  client,
+  "0x...",
+);
 ```
 
-### Missing objects: null vs throw
-
-Core-object getters (`getCompositionById`, `getDealById`, …) **throw** when the
-object is missing — a miss means a broken reference. Extension readers
-(`getCompositionCredits`, `getReleaseCover`, … — now in `@misofm/sdk`) return
-**`null`** instead, because extension data is optional by design. The exported
-`isNotFound(e)` helper distinguishes a missing-object error from a transport
-failure across all Sui client transports, and `@misofm/sdk` re-exports it so
-both packages share one not-found taxonomy:
-
-```ts
-import { isNotFound } from "@misonetwork/sdk";
-
-try {
-  await client.miso.getReleaseById(id);
-} catch (e) {
-  if (isNotFound(e)) { /* no such object */ } else throw e;
-}
-```
-
-Also exported: `extractTypeParam("p::m::T<A>")` → `"A"` and
-`extractTypeParams2("p::m::T<A, B>")` → `["A", "B"]` for reading share types
-out of object type tags.
-
-## Transaction Builders
-
-This module exports five builders, in two shapes:
-
-| Builder | Shape |
-|---------|-------|
-| `createComposition(tx, params)` | takes the `Transaction` first, returns `CompositionParts` |
-| `createRecording(tx, params)` | takes the `Transaction` first, returns `RecordingParts` |
-| `createDeal(tx, params)` | takes the `Transaction` first, returns a `TransactionObjectArgument` |
-| `createRelease(tx, params, trackVec)` | takes the `Transaction` first, returns `ReleaseParts` |
-| `rejectDeal(params)` | returns a `TxThunk` |
-
-Only `rejectDeal` follows the thunk pattern — it returns a `TxThunk`
-(`(tx: Transaction) => void | Promise<void>`) that appends commands to a
-caller-owned `Transaction`. The four `create*` primitives take the
-`Transaction` as their **first argument** and return their by-value results, so
-those results can be threaded into later commands. Either way, everything
-composes inside a single caller-owned PTB.
-
-The client binds exactly one builder — `client.miso.tx.rejectDeal` — which
-injects the client's `misoPackageId`. The `create*` primitives have no thunk to
-bind, so they stay free functions: import them from the package root and pass
-`misoPackageId` explicitly.
-
-This SDK keeps the bare protocol primitives only. The four `create*` functions
-each append a single `::new` and hand back its by-value results — never
-dispersing a share supply, publishing (sharing) the object, or routing an admin
-cap. The opinionated layers — the finish (disperse via minato, publish,
-transfer), track assembly, cap disposition, and the share-currency lifecycle —
-live in [`@misofm/sdk`](https://github.com/misofm/sdk) as **free functions that
-take `misoPackageId` explicitly** (they are not bound onto any client's `tx`
-namespace): `finalizeComposition`/`finalizeRecording`/`finalizeRelease`,
-`publishComposition`/`publishRecording`/`publishCompositionAndRecording`,
-`publishRelease`/`publishReleaseFromDeals`/`publishReleaseGraph`,
-`disperseShares`, share-currency provisioning, and `executeViaExecutor`. Those
-import the primitives from here and build on top.
-
-Execute any thunk (from this SDK or composed with another) with `buildTx` +
-`signAndExecute` — see [Execution](#execution-executets):
-
-```ts
-import { buildTx, signAndExecute } from "@misonetwork/sdk";
+Core object getters throw for a missing object. The exported `isNotFound(error)`
+helper distinguishes that condition from transport failures.
 
-const tx = await buildTx(client.miso.tx.rejectDeal({ /* … */ }));
-await signAndExecute(client, signer, tx);
-```
+## Transaction primitives
 
-### Deals
+The core exports these synchronous builders, each operating on the caller's
+`Transaction`:
 
-`createDeal` is a primitive: it appends `deal::new` and returns the `Deal` for
-you to route. It is a free function (not on `client.tx`) because it takes the
-`Transaction` directly, so pass `misoPackageId` explicitly.
+| Builder | Result |
+| --- | --- |
+| `createComposition(tx, params)` | `CompositionParts` |
+| `createRecording(tx, params)` | `RecordingParts` |
+| `createTrack(tx, params)` | `TransactionObjectArgument` |
 
-The returned `Deal` MUST be consumed in the same transaction — it is
-`key, store` with no `drop` — but it can go to either of two places, which is
-why the SDK does not choose for you:
+`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`.
 
 ```ts
-import { createDeal } from "@misonetwork/sdk";
+import { createTrack } from "@misonetwork/sdk";
 
-const deal = createDeal(tx, {
+const track = createTrack(tx, {
   recordingId: "0x...",
-  recordingAdminCapId: "0x...", // or `recordingAdminCap` as an in-PTB argument
+  recordingAdminCapId: "0x...",
   recordingShareType: "0x...::share::Share",
   compositionShareType: "0x...::share::Share",
-  releaseId: "0x...", // pre-derived to match release::new — see view.deriveReleaseId
+  targetReleaseId: "0x...",
   trackSplitBps: 5000,
   misoPackageId,
 });
-
-// (1) cross-party: send it to whoever assembles the release, to redeem later
-tx.transferObjects([deal], releaseCreator);
-
-// (2) same-party: spend it immediately as authorization for a track
-// tx.add(contracts.track._new({ package: misoPackageId, typeArguments, arguments: [deal, recording] }));
-```
-
-`rejectDeal` is the one builder bound on the client. It destroys a deal without
-including it in a release, and emits `DealRejectedEvent`:
-
-```ts
-client.miso.tx.rejectDeal({
-  dealId: "0x...",
-  recordingShareType: "0x...::share::Share",
-  compositionShareType: "0x...::share::Share",
-});
-```
-
-### Releases
-
-The end-to-end release publishers are **not** on `client.miso.tx` — they are free
-functions in [`@misofm/sdk`](https://github.com/misofm/sdk) that take
-`misoPackageId` explicitly:
-
-```ts
-import { publishRelease, publishReleaseFromDeals } from "@misofm/sdk";
-
-// Sender holds every recording's admin cap (a deal is created inline per track).
-await buildTx(publishRelease({ title, tracks, releaseRegistryId, releaseId, releaseNonce, adminAddress, misoPackageId }));
-
-// Or assemble from pre-made Deals the sender already holds.
-await buildTx(publishReleaseFromDeals({ title, deals, releaseRegistryId, releaseNonce, adminAddress, misoPackageId }));
 ```
 
-`releaseId` is a field on `PublishReleaseParams` only — pre-derive it (see
-[Deriving the release id](#deriving-the-release-id-view)) so the inline deals
-pin the right release. `PublishReleaseFromDealsParams` has no `releaseId`: each
-pre-made deal already embeds it, so the from-deals variant derives it from them.
+`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.
 
-This package supplies the primitive underneath both: `createRelease(tx, params,
-trackVec)`, which appends `release::new` over a caller-built `vector<Track>` and
-returns the release plus its admin cap.
+### Release IDs
 
-### Deriving the release id (`view`)
-
-Deals embed the exact release id, which the chain derives from the full
-tracklist + nonce. Compute it up front via `simulateTransaction`:
+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.
 
 ```ts
-const releaseId = await client.miso.view.deriveReleaseId({
-  sender: ownerAddress,          // any address; not charged
-  recordingIds: ["0x...", "0x..."], // in track order
-  splitBps: [5000, 5000],           // aligned to recordingIds
+const targetReleaseId = await client.miso.view.deriveTargetReleaseId({
+  sender: ownerAddress,
+  recordingIds: ["0x...", "0x..."],
+  splitBps: [5000, 5000],
   nonce: "42",
-  releaseRegistryId: "0x...",
+  parentId: releaseRegistryId,
 });
 ```
 
-### Creating works (`createComposition` / `createRecording` / `createRelease`)
-
-Each `create*` appends a single `::new` and returns its by-value parts — the
-object, its admin cap, and for a work its freshly-minted share `Balance`. The
-caller decides what happens next.
-
-The key move is **borrow-before-share**: `recording::new` takes the parent
-composition by immutable reference, so you can pass a `createComposition(...)`
-result straight into `createRecording`'s `composition` param while it is still an
-unshared, transaction-local value. That is what lets a composition and its first
-recording be minted in one PTB.
-
-```ts
-import { Transaction } from "@mysten/sui/transactions";
-import { createComposition, createRecording } from "@misonetwork/sdk";
-
-const tx = new Transaction();
-
-// 1. Composition — returns { composition, adminCap, balance }.
-const comp = createComposition(tx, {
-  title: "Song Title",
-  royaltyRateBps: 1000,
-  shareType: compositionShareType,   // `${sharePkg}::share::Share`
-  shareCurrencyId: "0x...",          // Currency<Share>
-  shareTreasuryCapId: "0x...",       // TreasuryCap<Share>, consumed by `new`
-  misoPackageId,
-});
-
-// 2. Recording — borrow-before-share: hand the still-unshared composition
-//    straight in. No on-chain object id is needed for it.
-const rec = createRecording(tx, {
-  composition: comp.composition,     // or `tx.object(compositionId)` if already on chain
-  compositionShareType,
-  shareType: recordingShareType,
-  shareCurrencyId: "0x...",
-  shareTreasuryCapId: "0x...",
-  maxRoyaltyRateBps: 1000,           // slippage guard — see below
-  misoPackageId,
-});
+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.
 
-// 3. Both objects MUST still be consumed by their `publish` in THIS transaction
-//    — e.g. `finalizeComposition(tx, { ...comp, ... })` / `finalizeRecording(tx,
-//    { ...rec, ... })` from `@misofm/sdk`, which disperse the balances, publish
-//    the works, and route the admin caps.
-```
+### Generated bindings
 
-`createRelease` takes the `vector<Track>` as an argument, because track assembly
-is the part that genuinely varies between flows — from recording admin caps,
-from pre-made deals, or from a mix of fresh and existing recordings:
+`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.
 
 ```ts
-import { createRelease } from "@misonetwork/sdk";
-
-const trackVec = tx.makeMoveVec({ type: `${misoPackageId}::track::Track`, elements: trackArgs });
-const rel = createRelease(tx, { title: "Album Title", nonce: "42", releaseRegistryId, misoPackageId }, trackVec);
-// rel.release must be consumed by `release::publish` in this same tx.
+tx.add(client.miso.call.track._new({
+  typeArguments: [recordingShareType, compositionShareType],
+  arguments: [adminCap, tx.object(recordingId), tx.pure.id(targetReleaseId), tx.pure.u16(5000)],
+}));
 ```
 
-#### Royalty-rate slippage (`maxRoyaltyRateBps`)
-
-A composition's royalty rate is floored but can be **raised** by its admin. If it
-goes up between the moment you read it and the moment your transaction lands, a
-recording you thought owed 10% could land owing more. `CreateRecordingParams.maxRoyaltyRateBps`
-is the guard: it is the maximum composition royalty rate (in bps) the recorder is
-willing to grant, and `recording::new` aborts with `ERoyaltyRateAboveMax` if the
-composition's live rate exceeds it. Pass the rate you actually observed.
-
-It is optional, and defaults to the exported `PROTOCOL_MAX_ROYALTY_RATE_BPS`
-(`2000`, the protocol's `MAX_ROYALTY_RATE_BPS`) — which accepts any legal rate,
-i.e. no slippage protection. Set it explicitly whenever you are recording someone
-else's composition.
-
-```ts
-import { PROTOCOL_MAX_ROYALTY_RATE_BPS } from "@misonetwork/sdk";
-
-const comp = await client.miso.getCompositionById(compositionId);
-createRecording(tx, { /* … */ maxRoyaltyRateBps: comp.royaltyRate.value });
-```
-
-#### Result shapes
-
-```ts
-import type {
-  CompositionParts, RecordingParts, ReleaseParts, ShareCurrencyBinding,
-} from "@misonetwork/sdk";
-
-// CompositionParts { composition, adminCap, balance }  — balance is the creator's
-//                                                        freshly-minted share supply
-// RecordingParts   { recording,   adminCap, balance }  — balance is what remains
-//                                                        after the composition's cut
-// ReleaseParts     { release,     adminCap }
-// All fields are `TransactionObjectArgument`s, for threading onward in the PTB.
-```
-
-`ShareCurrencyBinding` is the trio every work-creating builder needs, extended by
-both `CreateCompositionParams` and `CreateRecordingParams`: `shareType` (the
-`${packageId}::share::Share` type), `shareCurrencyId` (the `Currency<Share>`
-object), and `shareTreasuryCapId` (the `TreasuryCap<Share>`, consumed by `new`).
-All three are passed explicitly rather than read from chain, which keeps the
-builders synchronous — no RPC inside the transaction build.
-
-**Lifecycle requirement.** `Composition`, `Recording`, and `Release` are all
-`key`-only with no `drop`, so each created object MUST be consumed by its
-`publish` in the same transaction — none can be transferred, wrapped, shared, or
-discarded, and none can outlive its creating PTB. That is a same-**transaction**
-requirement, not a same-**function** one: pairing a `create*` here with a
-`finalize*` from `@misofm/sdk` on the same `tx` satisfies it. Keeping them apart
-is what makes the intermediate value useful at all — borrowing a still-unshared
-composition into `recording::new`, attaching a royalty pool via `uid_mut`, or
-routing an admin cap somewhere other than a plain address (every admin cap is
-`key, store`, hence freely routable).
-
-Whole-graph orchestration lives in `@misofm/sdk` too: `publishReleaseGraph`
-mints every composition and recording, attaches optional royalty pools, builds
-the deals/tracks, and publishes the release — with the release id derived
-on-chain — all in one PTB, importing the primitives from here.
-
-```ts
-import { publishReleaseGraph } from "@misofm/sdk";
-```
-
-## Extensions (moved to `@misofm/sdk`)
-
-Extension helpers are no longer part of this package. As of **0.3.0**, credits,
-cover art, and royalty pools ship from [`@misofm/sdk`](https://github.com/misofm/sdk):
-
-| Was `@misonetwork/sdk` | Now `@misofm/sdk` |
-|---|---|
-| `attachCompositionCredit`, `attachRecordingCredit`, `addReleaseCredit`, `addRecordingPrimaryArtist`, `addRecordingFeaturedArtist`, `getCompositionCredits`, `getRecordingCredits`, `getReleaseCredits` | same names |
-| `setReleaseCover`, `getReleaseCover` | same names |
-| `attachCompositionRoyaltyPool`, `attachRecordingRoyaltyPool` | same names |
-| `contracts.compositionCredits`, `.recordingCredits`, `.releaseCredits`, `.compositionPartyRole`, `.recordingPartyRole`, `.releasePartyRole`, `.royaltyPool`, `.royaltyPoolStake`, `.compositionRoyaltyPool`, `.recordingRoyaltyPool`, `.coverArt`, `.releaseCoverArt` | `contracts.*`, same names |
-| types `CreditView`, `RecordingCreditsView`, `CompositionRole`, `RecordingRole`, `RecordingRoleLevel`, `RecordingLeveledRoleType`, `ReleaseRole`, `ReleaseCoverView`, `CoverImageRef` | same names |
+## Event parsers
 
-Signatures are unchanged — only the import specifier moves:
+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.
 
-```diff
--import { attachRecordingCredit, setReleaseCover } from "@misonetwork/sdk";
-+import { attachRecordingCredit, setReleaseCover } from "@misofm/sdk";
-```
-
-The reasoning is the split this package exists to hold. An extension is not part
-of what a Composition or Recording *is*; it is a choice about how to describe one
-— which roles exist and what they are called, what counts as a cover, whether
-royalties accumulate in a pool. The protocol offers a cap-gated `&mut UID` hook
-and takes no position on what hangs off it. Everything that *does* take a
-position is business logic, and business logic ships from the platform package.
-
-Share-currency provisioning (`createShareCurrency`, `publishShareCurrencies`,
-`initializeShareCurrencies`) moved to `@misofm/sdk` earlier for the same reason —
-every composition and recording is backed by its own fixed-supply share currency,
-and provisioning one is part of the opinionated publish flow, not a protocol
-primitive.
-
-## Execution (`execute.ts`)
-
-Builders only append to a `Transaction`; this module submits:
-
-```ts
-import { buildTx, signAndExecute, execThunks, publishedPackageId, createdByType, balanceDelta } from "@misonetwork/sdk";
-
-const result = await execThunks(client, signer, thunkA, thunkB); // build + sign + execute + wait
-// ExecResult: { digest, changedObjects, objectTypes, balanceChanges, gasUsed }
-
-// Object-change extractors:
-const pkgId = publishedPackageId(result);
-const currencyId = createdByType(result, "::coin_registry::Currency<");
-const delta = balanceDelta(result, address, "0x2::sui::SUI");
-```
-
-`@misofm/sdk` builds `executeViaExecutor(executor, ...thunks)` on top of this
-module's `buildTx`/`toExecResult` — it submits a non-idempotent PTB through a
-`ParallelTransactionExecutor` exactly once (no auto-retry), for its batched
-share-currency provisioning.
-
-## Event Parsers
-
-Miso uses a lean publish-only event model: published objects emit a single pointer event,
-and indexers fetch the immutable object by ID. Parse the BCS-encoded events from transaction
-results:
-
-```ts
-// Pointer events (carry only identities)
-const comp = client.miso.parse.compositionPublishedEvent(bcsBytes);  // { compositionId }
-const rec = client.miso.parse.recordingPublishedEvent(bcsBytes);     // { recordingId }
-const rel = client.miso.parse.releasePublishedEvent(bcsBytes);       // { releaseId }
-
-// Non-pointer events
-const royalty = client.miso.parse.compositionRoyaltySetEvent(bcsBytes); // { royaltyRateBps }
-const created = client.miso.parse.dealCreatedEvent(bcsBytes);   // { dealId, releaseId, trackSplitBps }
-const accepted = client.miso.parse.dealAcceptedEvent(bcsBytes); // { dealId, releaseId }
-const rejected = client.miso.parse.dealRejectedEvent(bcsBytes); // { dealId, releaseId }
-```
-
-The same functions are exported standalone as `parseCompositionPublishedEvent`, etc.
-
-## Types
-
-All Miso domain types are exported:
-
-```ts
-import type {
-  // Core entities
-  Composition, Recording, Release, Deal, Track, BPS,
-  // Admin caps
-  CompositionAdminCap, RecordingAdminCap, ReleaseAdminCap,
-  // State machines
-  CompositionState, RecordingState, ReleaseState, TrackState,
-  // Events
-  CompositionPublishedEvent, CompositionRoyaltySetEvent,
-  RecordingPublishedEvent, ReleasePublishedEvent,
-  DealCreatedEvent, DealAcceptedEvent, DealRejectedEvent,
-  // Transaction builder inputs & results (from ./transactions)
-  TxThunk, ShareCurrencyBinding,
-  CompositionParts, RecordingParts, ReleaseParts,
-  CreateCompositionParams, CreateRecordingParams, CreateDealParams,
-  CreateReleaseParams, RejectDealParams,
-} from "@misonetwork/sdk";
-```
-
-The credit and cover types (`CreditView`, `RecordingCreditsView`,
-`CompositionRole`, `RecordingRole`, `RecordingRoleLevel`,
-`RecordingLeveledRoleType`, `ReleaseRole`, `ReleaseCoverView`, `CoverImageRef`)
-moved to `@misofm/sdk` in 0.3.0 — see [Extensions](#extensions-moved-to-misofmsdk).
-
-The non-type value export `PROTOCOL_MAX_ROYALTY_RATE_BPS` (`2000`) is documented
-under [royalty-rate slippage](#royalty-rate-slippage-maxroyaltyratebps).
-
-## Generated Bindings (`contracts`)
-
-The codegen-generated, ABI-bound bindings (BCS structs + type-safe Move calls)
-are exported under the `contracts` namespace — the core protocol modules
-`composition`, `recording`, `release`, `deal`, and `track`. Bindings for the
-extension packages are in `@misofm/sdk`'s own `contracts` namespace:
-
-```ts
-import { contracts } from "@misonetwork/sdk";
-
-const parsed = contracts.composition.Composition.parse(bcsBytes);
-tx.add(contracts.deal.reject({ package: misoPackageId, typeArguments, arguments: [dealId] }));
-```
+## 0.4.0 → 0.5.0 migration
 
-On the client, `client.miso.call.*` exposes the core modules with the package
-id pre-bound, and `client.miso.bcs.*` the core BCS structs.
+| 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` |
 
-## Derived Objects
+Update `@misofm/sdk` in the same release window: it owns release-registry
+bindings and the callable release-construction flow.
 
-Miso uses Sui's derived object pattern for admin caps. The SDK provides pure derivation
-functions that compute object IDs without network calls:
+## Derived admin caps
 
-| Function | Derivation Key | Parent Object |
-|----------|---------------|---------------|
-| `deriveCompositionAdminCapId` | `CompositionAdminCapKey()` | Composition |
-| `deriveRecordingAdminCapId` | `RecordingAdminCapKey()` | Recording |
-| `deriveReleaseAdminCapId` | `ReleaseAdminCapKey()` | Release |
+| Function | Parent |
+| --- | --- |
+| `deriveCompositionAdminCapId` | Composition |
+| `deriveRecordingAdminCapId` | Recording |
+| `deriveReleaseAdminCapId` | Release |
 
 ## License