@misonetwork/sdk 0.1.0

package/README.md

@@ -0,0 +1,644 @@
+# @misonetwork/sdk
+
+TypeScript SDK for the [Miso](https://github.com/misonetwork/miso-protocol) protocol on [Sui](https://sui.io).
+
+This package mirrors the on-chain ABI of the [`misonetwork/miso-protocol`](https://github.com/misonetwork/miso-protocol) Move package (plus its first-party extensions), 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, Zod validation schemas, extension helpers (credits, cover art, royalty pools), and a client extension.
+
+## Installation
+
+```bash
+bun add @misonetwork/sdk @mysten/sui
+```
+
+## Quick Start
+
+```ts
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { miso } from "@misonetwork/sdk";
+
+const client = new SuiGrpcClient({ network: "testnet" })
+  .$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:
+
+| 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
+
+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.
+
+## 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
+
+```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);
+```
+
+### 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`, …) return **`null`** — 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:
+
+```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";
+
+const tx = await buildTx(client.miso.tx.rejectDeal({ /* … */ }));
+await signAndExecute(client, signer, tx);
+```
+
+### Deals
+
+`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.
+
+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:
+
+```ts
+import { createDeal } from "@misonetwork/sdk";
+
+const deal = createDeal(tx, {
+  recordingId: "0x...",
+  recordingAdminCapId: "0x...", // or `recordingAdminCap` as an in-PTB argument
+  recordingShareType: "0x...::share::Share",
+  compositionShareType: "0x...::share::Share",
+  releaseId: "0x...", // pre-derived to match release::new — see view.deriveReleaseId
+  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.
+
+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.
+
+### 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`:
+
+```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
+  nonce: "42",
+  releaseRegistryId: "0x...",
+});
+```
+
+### 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,
+});
+
+// 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.
+```
+
+`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:
+
+```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.
+```
+
+#### 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
+
+### Credits (`credits.ts`)
+
+Contributor credits pair a party with a display name and one or more
+domain-specific roles, attached to a work as a dynamic field and gated by the
+work's admin cap. Three role vocabularies:
+
+- **Composition** (writing, 1–5 roles, no level): `Adapter`, `Arranger`, `Composer`, `Lyricist`, `Songwriter`, `Translator`, or `{ type: "Custom", name }`.
+- **Recording** (production/performance, 1–10 roles): 28 leveled roles (`Producer`, `Vocalist`, `Engineer`, …) each with an optional seniority `level` (`Lead`, `Featured`, `Executive`, …), plus `{ type: "Instrumentalist", instrument, level? }`, `{ type: "Custom", name, level? }`, and the unleveled `ArtistsAndRepertoire` / `Copyist`.
+- **Release** (top-line billing, exactly one role): `"Primary"` or `"Featured"`.
+
+Writers validate client-side, mirroring the Move aborts: display name
+non-empty and ≤200 UTF-8 bytes; role counts within the caps above; no
+duplicate roles.
+
+```ts
+import {
+  attachCompositionCredit, attachRecordingCredit, addReleaseCredit,
+  addRecordingPrimaryArtist, addRecordingFeaturedArtist,
+  getCompositionCredits, getRecordingCredits, getReleaseCredits,
+} from "@misonetwork/sdk";
+
+const thunk = attachRecordingCredit({
+  recordingId: "0x...",
+  recordingAdminCapId: "0x...",
+  partyId: "0x...",
+  displayName: "Jane Doe",
+  roles: [{ type: "Vocalist", level: "Lead" }, { type: "Instrumentalist", instrument: "Guitar" }],
+  recordingShareType: "0x...::share::Share",
+  compositionShareType: "0x...::share::Share",
+  recordingCreditsPackageId: "0x...",
+  misoCreditPackageId: "0x...",
+});
+
+// Designate an already-credited party (same params minus displayName/roles/misoCreditPackageId):
+addRecordingPrimaryArtist({ recordingId, recordingAdminCapId, partyId, recordingShareType, compositionShareType, recordingCreditsPackageId });
+
+// Reads return null when no credits field is attached.
+const credits = await getCompositionCredits(client, compositionId, compositionCreditsPackageId);
+// CreditView[]: { partyId, displayName, roles: string[] } — e.g. "Producer (Lead)", "Instrumentalist: Guitar"
+const rc = await getRecordingCredits(client, recordingId, recordingCreditsPackageId);
+// { credits: CreditView[], primaryArtistIds: string[], featuredArtistIds: string[] }
+```
+
+`attachCompositionCredit` takes `compositionId`/`compositionAdminCapId`/`compositionShareType`/`compositionCreditsPackageId`;
+`addReleaseCredit` takes `releaseId`/`releaseAdminCapId` and a single `role`.
+
+### Cover art (`cover.ts`)
+
+A release's cover is a Walrus blob referenced on-chain via `ori::WalrusData`,
+attached under the `release_cover_art` extension:
+
+```ts
+import { setReleaseCover, getReleaseCover } from "@misonetwork/sdk";
+
+const thunk = setReleaseCover({
+  releaseId: "0x...",
+  releaseAdminCapId: "0x...",
+  stillBlobId: "987654321",   // Walrus blob id as u256 (decimal string or bigint)
+  animatedBlobId: null,        // optional animated cover
+  coverArtPackageId: "0x...",
+  releaseCoverArtPackageId: "0x...",
+  oriPackageId: "0x...",
+});
+
+const cover = await getReleaseCover(client, releaseId, releaseCoverArtPackageId);
+// ReleaseCoverView | null: { still, animated } as normalized Walrus refs
+// ({ kind: "blob", blobId } | { kind: "quiltPatch", quiltId, version, startIndex, endIndex })
+```
+
+### Royalty pools (`extensions/royalty-pool.ts`)
+
+`attachCompositionRoyaltyPool(tx, params)` / `attachRecordingRoyaltyPool(tx, params)`
+create and share a `RoyaltyPool<Share, Currency>` for a work inside its publish
+PTB (after `createComposition`/`createRecording`, before the opinionated
+finish). `@misofm/sdk`'s
+`publishReleaseGraph` accepts them as `royaltyPool` nodes.
+
+Share-currency provisioning (`createShareCurrency`, `publishShareCurrencies`,
+`initializeShareCurrencies`) also moved to `@misofm/sdk` — 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.
+
+## Validation Schemas
+
+Zod schemas for validating Miso domain types and parsed events:
+
+```ts
+import {
+  CompositionSchema, RecordingSchema, ReleaseSchema, TrackSchema,
+  CompositionStateSchema, RecordingStateSchema, ReleaseStateSchema,
+  CompositionPublishedEventSchema, CompositionRoyaltySetEventSchema,
+  RecordingPublishedEventSchema, ReleasePublishedEventSchema,
+  DealCreatedEventSchema, DealAcceptedEventSchema, DealRejectedEventSchema,
+} from "@misonetwork/sdk/schemas";
+
+const result = RecordingSchema.safeParse(data);
+```
+
+## 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,
+  // Credits & roles (from ./credits)
+  CreditView, RecordingCreditsView,
+  CompositionRole, RecordingRole, RecordingRoleLevel, ReleaseRole,
+  RecordingLeveledRoleType,
+  // Extension views
+  ReleaseCoverView, CoverImageRef,
+  // Transaction builder inputs & results (from ./transactions)
+  TxThunk, ShareCurrencyBinding,
+  CompositionParts, RecordingParts, ReleaseParts,
+  CreateCompositionParams, CreateRecordingParams, CreateDealParams,
+  CreateReleaseParams, RejectDealParams,
+} from "@misonetwork/sdk";
+```
+
+`RecordingLeveledRoleType` is the union of the 28 recording role base names that
+carry an optional `RecordingRoleLevel` (`Producer`, `Vocalist`, `Engineer`,
+`Conductor`, …) — the leveled arm of `RecordingRole`. The other arms
+(`Instrumentalist`, `Custom`, and the unleveled `ArtistsAndRepertoire` /
+`Copyist`) are spelled out separately in `RecordingRole`.
+
+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 — core protocol modules
+(`composition`, `recording`, `release`, `deal`, `track`) plus the extension
+packages (`royaltyPool`, `royaltyPoolStake`, `compositionRoyaltyPool`,
+`recordingRoyaltyPool`, `coverArt`, `releaseCoverArt`, `compositionCredits`,
+`compositionPartyRole`, `recordingCredits`, `recordingPartyRole`,
+`releaseCredits`, `releasePartyRole`):
+
+```ts
+import { contracts } from "@misonetwork/sdk";
+
+const parsed = contracts.composition.Composition.parse(bcsBytes);
+tx.add(contracts.deal.reject({ package: misoPackageId, typeArguments, arguments: [dealId] }));
+```
+
+On the client, `client.miso.call.*` exposes the core modules with the package
+id pre-bound, and `client.miso.bcs.*` the core BCS structs.
+
+## Derived Objects
+
+Miso uses Sui's derived object pattern for admin caps. The SDK provides pure derivation
+functions that compute object IDs without network calls:
+
+| Function | Derivation Key | Parent Object |
+|----------|---------------|---------------|
+| `deriveCompositionAdminCapId` | `CompositionAdminCapKey()` | Composition |
+| `deriveRecordingAdminCapId` | `RecordingAdminCapKey()` | Recording |
+| `deriveReleaseAdminCapId` | `ReleaseAdminCapKey()` | Release |
+
+## License
+
+Apache-2.0