@misonetwork/sdk 0.4.0 → 0.6.0

package/src/client.ts

@@ -6,15 +6,16 @@ import type {
   SuiClientRegistration,
 } from "@mysten/sui/client";
 import type { SuiGraphQLClient } from "@mysten/sui/graphql";
-import type { TxThunk } from "./transactions.ts";
+import {
+  getMisoProtocolDeployment,
+  type MisoProtocolDeployment,
+} from "./deployments.ts";
 import * as parsers from "./parsers.ts";
 import * as queries from "./queries.ts";
-import * as transactions from "./transactions.ts";
 import * as view from "./view.ts";
 import type {
   Composition,
   CompositionAdminCap,
-  Deal,
   Recording,
   RecordingAdminCap,
   Release,
@@ -25,46 +26,27 @@ import type {
 import * as composition from "./contracts/miso/composition.ts";
 import * as recording from "./contracts/miso/recording.ts";
 import * as release from "./contracts/miso/release.ts";
-import * as deal from "./contracts/miso/deal.ts";
 import * as track from "./contracts/miso/track.ts";
 
 export interface MisoOptions<Name extends string = "miso"> {
   /** Name for the client extension. Defaults to "miso". */
   name?: Name;
-  /** The Miso package ID. Required for type-based queries and derivation. */
-  misoPackageId: string;
   /**
-   * The `ReleaseRegistry` object ID for this deployment.
-   *
-   * Created once in `release::init` and shared, so it is FIXED for the lifetime
-   * of a published package — deployment config, not runtime state. Supply it
-   * (alongside `misoPackageId`, from the same deployment manifest) and
-   * `getReleaseRegistry()` needs no network call at all. Omit it and the SDK
-   * falls back to a GraphQL scan, which is why this is worth configuring.
+   * Complete custom deployment. Omit for bundled Mainnet/Testnet addresses,
+   * selected from the Sui client's `network`.
    */
-  releaseRegistryId?: string;
+  deployment?: MisoProtocolDeployment;
+  /** @deprecated Use `deployment`. Retained for compatibility with pre-0.4 callers. */
+  misoPackageId?: string;
   /**
    * Optional GraphQL client, required ONLY for the global type-discovery reads
    * the Core API cannot express: `getCompositionByShareType`,
-   * `getRecordingByShareType`, and `getReleaseRegistry` when
-   * `releaseRegistryId` is not configured. Everything else — including every
+   * `getRecordingByShareType`. Everything else — including every
    * `getOwned*AdminCaps` — goes over the Core API.
    */
   graphqlClient?: SuiGraphQLClient;
 }
 
-/**
- * Wraps a builder so the client's `misoPackageId` is injected, dropping it from
- * the caller's params. Explicit call-sites (the free functions in
- * `./transactions`) remain available for full control.
- */
-function bindPackages<P extends { misoPackageId: string }>(
-  fn: (params: P) => TxThunk,
-  misoPackageId: string,
-): (params: Omit<P, "misoPackageId">) => TxThunk {
-  return (params) => fn({ misoPackageId, ...params } as unknown as P);
-}
-
 /** Defaults `options.package` to `pkg` for every call-function in a generated module. */
 function bindModulePackage<M extends object>(mod: M, pkg: string): M {
   const out: Record<string, unknown> = {};
@@ -84,31 +66,53 @@ function bindModulePackage<M extends object>(mod: M, pkg: string): M {
  * @example
  * ```ts
  * const client = new SuiGrpcClient({ network: 'testnet' })
- *   .$extend(miso({ misoPackageId: '0x...' }));
+ *   .$extend(miso());
  * const composition = await client.miso.getCompositionById('0x...');
  * ```
  */
 export function miso<const Name extends string = "miso">(
-  options: MisoOptions<Name>,
-): SuiClientRegistration<ClientWithCoreApi, Name, MisoClient> {
+  options: MisoOptions<Name> = {},
+): SuiClientRegistration<ClientWithCoreApi, Name, MisoProtocolClient> {
   const name = (options.name ?? "miso") as Name;
   return {
     name,
-    register: (client) => new MisoClient(client, options),
+    register: (client) => {
+      const deployment =
+        options.deployment ??
+        (options.misoPackageId
+          ? { packageId: options.misoPackageId }
+          : getMisoProtocolDeployment(client.network));
+      return new MisoProtocolClient(client, {
+        deployment,
+        graphqlClient: options.graphqlClient,
+      });
+    },
   };
 }
 
-export class MisoClient {
+export interface MisoProtocolClientOptions {
+  deployment: MisoProtocolDeployment;
+  graphqlClient?: SuiGraphQLClient;
+}
+
+export class MisoProtocolClient {
   #client: ClientWithCoreApi;
   #graphqlClient?: SuiGraphQLClient;
-  #misoPackageId: string;
-  #releaseRegistryId?: string;
+  #deployment: MisoProtocolDeployment;
 
-  constructor(client: ClientWithCoreApi, options: Omit<MisoOptions, "name">) {
+  constructor(client: ClientWithCoreApi, options: MisoProtocolClientOptions) {
     this.#client = client;
     this.#graphqlClient = options.graphqlClient;
-    this.#misoPackageId = options.misoPackageId;
-    this.#releaseRegistryId = options.releaseRegistryId;
+    this.#deployment = options.deployment;
+  }
+
+  /** The exact deployment selected for this client. */
+  get deployment(): MisoProtocolDeployment {
+    return this.#deployment;
+  }
+
+  get #misoPackageId(): string {
+    return this.#deployment.packageId;
   }
 
   // === Composition ===
@@ -202,12 +206,6 @@ export class MisoClient {
     return queries.deriveRecordingAdminCapId(recordingId, this.#misoPackageId);
   }
 
-  // === Deal ===
-
-  async getDealById(dealId: string): Promise<Deal> {
-    return queries.getDealById(this.#client, dealId);
-  }
-
   // === Release ===
 
   async getReleaseById(releaseId: string): Promise<Release> {
@@ -229,23 +227,6 @@ export class MisoClient {
       this.#misoPackageId,
     );
   }
-  /**
-   * The deployment's `ReleaseRegistry` object ID.
-   *
-   * Returns the configured `releaseRegistryId` with no network call. Only when
-   * it was not configured does this fall back to a GraphQL scan — a one-time
-   * bootstrap for a fresh deployment whose id you have not recorded yet. Prefer
-   * configuring it: the registry is created once in `release::init` and never
-   * changes, so scanning for it on every call is pure overhead.
-   */
-  async getReleaseRegistry(): Promise<string> {
-    if (this.#releaseRegistryId) return this.#releaseRegistryId;
-    return queries.getReleaseRegistry(
-      this.#requireGraphQL(),
-      this.#misoPackageId,
-    );
-  }
-
   // === Share Currency ===
 
   async getShareCurrencyType(shareCurrencyId: string): Promise<string> {
@@ -263,29 +244,14 @@ export class MisoClient {
     return queries.getShareCurrencyTreasuryCap(this.#client, shareType, owner);
   }
 
-  // === Transaction builders (thunks) ===
-
-  // Only the `(params) => TxThunk` builders bind here. The primitives that take
-  // a `Transaction` directly and return values (`createComposition`,
-  // `createRecording`, `createRelease`, `createDeal`) are free functions by
-  // design — they thread results into a caller-owned PTB, so there is nothing
-  // to bind. Import them from the package root and pass `misoPackageId`
-  // explicitly.
-  get tx() {
-    const miso = this.#misoPackageId;
-    return {
-      rejectDeal: bindPackages(transactions.rejectDeal, miso),
-    };
-  }
-
   // === Simulate-based reads (view) ===
 
   get view() {
     const client = this.#client;
     const misoPackageId = this.#misoPackageId;
     return {
-      deriveReleaseId: (params: view.DeriveReleaseIdParams) =>
-        view.deriveReleaseId(client, misoPackageId, params),
+      deriveTargetReleaseId: (params: view.DeriveTargetReleaseIdParams) =>
+        view.deriveTargetReleaseId(client, misoPackageId, params),
     };
   }
 
@@ -297,7 +263,6 @@ export class MisoClient {
       composition: bindModulePackage(composition, pkg),
       recording: bindModulePackage(recording, pkg),
       release: bindModulePackage(release, pkg),
-      deal: bindModulePackage(deal, pkg),
       track: bindModulePackage(track, pkg),
     };
   }
@@ -309,15 +274,11 @@ export class MisoClient {
       Composition: composition.Composition,
       Recording: recording.Recording,
       Release: release.Release,
-      Deal: deal.Deal,
       Track: track.Track,
       CompositionPublishedEvent: composition.CompositionPublishedEvent,
       CompositionRoyaltySetEvent: composition.CompositionRoyaltySetEvent,
       RecordingPublishedEvent: recording.RecordingPublishedEvent,
       ReleasePublishedEvent: release.ReleasePublishedEvent,
-      DealCreatedEvent: deal.DealCreatedEvent,
-      DealAcceptedEvent: deal.DealAcceptedEvent,
-      DealRejectedEvent: deal.DealRejectedEvent,
     };
   }
 
@@ -329,9 +290,6 @@ export class MisoClient {
       compositionRoyaltySetEvent: parsers.parseCompositionRoyaltySetEvent,
       recordingPublishedEvent: parsers.parseRecordingPublishedEvent,
       releasePublishedEvent: parsers.parseReleasePublishedEvent,
-      dealCreatedEvent: parsers.parseDealCreatedEvent,
-      dealAcceptedEvent: parsers.parseDealAcceptedEvent,
-      dealRejectedEvent: parsers.parseDealRejectedEvent,
     };
   }
 
@@ -344,3 +302,6 @@ export class MisoClient {
     return this.#graphqlClient;
   }
 }
+
+/** @deprecated Prefer the layer-specific `MisoProtocolClient` name. */
+export { MisoProtocolClient as MisoClient };

package/src/contracts/miso/release.ts

@@ -38,14 +38,22 @@
  * 
  * ### Consent scope
  * 
- * The release digest — and therefore the derived release id every `Deal` commits
- * to — binds the economics and membership of the release: the ordered list of
- * `(recording, split)` pairs and the creator's nonce. It deliberately binds
- * nothing else. The title — the one embedded field outside the digest — and
+ * The release digest — and therefore the derived release id every `Track` commits
+ * to at creation — binds the economics and membership of the release: the ordered
+ * list of `(recording, split)` pairs and the creator's nonce. It deliberately
+ * binds nothing else. The title — the one embedded field outside the digest — and
  * everything in the extension layer (artwork, credits, display grouping) are
- * chosen by the release creator, before or after deals are signed, and are trusted
- * and publicly attributable rather than cryptographically committed. See
- * `deal::new` for the signer-side statement of this boundary.
+ * chosen by the release creator, before or after tracks are created, and are
+ * trusted and publicly attributable rather than cryptographically committed. See
+ * `track::new` for the signer-side statement of this boundary.
+ * 
+ * The derived id commits to a `(parent, digest)` pair, not the digest alone — so
+ * targeting an id also consents to that namespace's liveness. If the parent object
+ * is deleted, or its `&mut UID` becomes permanently unreachable, the release can
+ * never exist and every track or offer targeting it is stranded — the same
+ * blast-radius class as a release that simply never publishes. A coordinator meant
+ * to serve as the default parent namespace should therefore be shared and
+ * undeletable.
  * 
  * ### Lifecycle and trust model
  * 
@@ -65,12 +73,11 @@
  * holder as able to mutate or delete any extension data, forever.
  */
 
-import { MoveTuple, MoveEnum, MoveStruct, normalizeMoveArguments, type RawTransactionArgument } from '../utils/index.js';
+import { MoveEnum, MoveStruct, MoveTuple, normalizeMoveArguments, type RawTransactionArgument } from '../utils/index.js';
 import { bcs } from '@mysten/sui/bcs';
 import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
 import * as track from './track.js';
 const $moduleName = '@local-pkg/miso::release';
-export const RELEASE = new MoveTuple({ name: `${$moduleName}::RELEASE`, fields: [bcs.bool()] });
 /** Lifecycle state of a release. */
 export const ReleaseState = new MoveEnum({ name: `${$moduleName}::ReleaseState`, fields: {
         /** Release is initialized but not yet published. */
@@ -86,15 +93,12 @@ export const Release = new MoveStruct({ name: `${$moduleName}::Release`, fields:
         /** Title of the release. */
         title: bcs.string(),
         /**
-         * The ordered tracklist. Same shape as the digest pre-image every deal consented
-         * to; display grouping lives in the metadata extension.
+         * The ordered tracklist. Same shape as the digest pre-image every track's creator
+         * consented to; display grouping lives in the metadata extension.
          */
         tracks: bcs.vector(track.Track)
     } });
 export const ReleaseKey = new MoveTuple({ name: `${$moduleName}::ReleaseKey`, fields: [bcs.vector(bcs.u8())] });
-export const ReleaseRegistry = new MoveStruct({ name: `${$moduleName}::ReleaseRegistry`, fields: {
-        id: bcs.Address
-    } });
 export const ReleaseAdminCap = new MoveStruct({ name: `${$moduleName}::ReleaseAdminCap`, fields: {
         /** Unique identifier for this capability. */
         id: bcs.Address,
@@ -102,10 +106,6 @@ export const ReleaseAdminCap = new MoveStruct({ name: `${$moduleName}::ReleaseAd
         release_id: bcs.Address
     } });
 export const ReleaseAdminCapKey = new MoveTuple({ name: `${$moduleName}::ReleaseAdminCapKey`, fields: [bcs.bool()] });
-export const ReleaseRegistryCreatedEvent = new MoveStruct({ name: `${$moduleName}::ReleaseRegistryCreatedEvent`, fields: {
-        registry_id: bcs.Address,
-        created_by: bcs.Address
-    } });
 export const ReleasePublishedEvent = new MoveStruct({ name: `${$moduleName}::ReleasePublishedEvent`, fields: {
         release_id: bcs.Address
     } });
@@ -113,7 +113,7 @@ export interface NewArguments {
     title: RawTransactionArgument<string>;
     tracks: TransactionArgument;
     nonce: RawTransactionArgument<number | bigint>;
-    registry: RawTransactionArgument<string>;
+    parent: RawTransactionArgument<string>;
 }
 export interface NewOptions {
     package?: string;
@@ -121,12 +121,15 @@ export interface NewOptions {
         title: RawTransactionArgument<string>,
         tracks: TransactionArgument,
         nonce: RawTransactionArgument<number | bigint>,
-        registry: RawTransactionArgument<string>
+        parent: RawTransactionArgument<string>
     ];
 }
 /**
- * Creates a new release with the given configuration. Returns the release and
- * admin capability.
+ * Creates a new release with the given configuration. Claims the release's UID as
+ * a derived child of `parent`, keyed by the release digest (see the module doc's
+ * "Consent scope" section) — so contention is per-parent, and which object serves
+ * as parent is entirely the caller's choice. Returns the release and admin
+ * capability.
  */
 export function _new(options: NewOptions) {
     const packageAddress = options.package ?? '@local-pkg/miso';
@@ -134,9 +137,9 @@ export function _new(options: NewOptions) {
         '0x1::string::String',
         'vector<null>',
         'u256',
-        null
+        '0x2::object::ID'
     ] satisfies (string | null)[];
-    const parameterNames = ["title", "tracks", "nonce", "registry"];
+    const parameterNames = ["title", "tracks", "nonce", "parent"];
     return (tx: Transaction) => tx.moveCall({
         package: packageAddress,
         module: 'release',
@@ -203,39 +206,39 @@ export function authorize(options: AuthorizeOptions) {
         arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
     });
 }
-export interface DeriveReleaseIdArguments {
+export interface DeriveTargetReleaseIdArguments {
     recordingIds: RawTransactionArgument<Array<string>>;
     trackSplitValues: RawTransactionArgument<Array<number | bigint>>;
     nonce: RawTransactionArgument<number | bigint>;
-    registry: RawTransactionArgument<string>;
+    parent: RawTransactionArgument<string>;
 }
-export interface DeriveReleaseIdOptions {
+export interface DeriveTargetReleaseIdOptions {
     package?: string;
-    arguments: DeriveReleaseIdArguments | [
+    arguments: DeriveTargetReleaseIdArguments | [
         recordingIds: RawTransactionArgument<Array<string>>,
         trackSplitValues: RawTransactionArgument<Array<number | bigint>>,
         nonce: RawTransactionArgument<number | bigint>,
-        registry: RawTransactionArgument<string>
+        parent: RawTransactionArgument<string>
     ];
 }
 /**
- * Derives the release ID that `new()` would produce for the given inputs, without
- * creating the object. This is the on-chain equivalent of the client-side
- * `deriveReleaseId()` function.
+ * Derives the target release ID that `new()` would produce for the given inputs
+ * and parent, without creating the object. This is the on-chain equivalent of the
+ * client-side `deriveReleaseId()` function.
  */
-export function deriveReleaseId(options: DeriveReleaseIdOptions) {
+export function deriveTargetReleaseId(options: DeriveTargetReleaseIdOptions) {
     const packageAddress = options.package ?? '@local-pkg/miso';
     const argumentsTypes = [
         'vector<0x2::object::ID>',
         'vector<u64>',
         'u256',
-        null
+        '0x2::object::ID'
     ] satisfies (string | null)[];
-    const parameterNames = ["recordingIds", "trackSplitValues", "nonce", "registry"];
+    const parameterNames = ["recordingIds", "trackSplitValues", "nonce", "parent"];
     return (tx: Transaction) => tx.moveCall({
         package: packageAddress,
         module: 'release',
-        function: 'derive_release_id',
+        function: 'derive_target_release_id',
         arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
     });
 }

package/src/contracts/miso/track.ts

@@ -14,8 +14,8 @@
  *   recording/composition share-type identities) is reached.
  * - `split_bps` — this track's share of the release's revenue; genuinely
  *   release-specific and not derivable from the recording.
- * - `state` — the assign-once lifecycle that carries (then sheds) each deal's
- *   target release commitment; see `TrackState`.
+ * - `state` — the assign-once lifecycle that carries (then sheds) the recording
+ *   admin's target release commitment, made at creation; see `TrackState`.
  * 
  * `Track` is intentionally monomorphic: a `Release` holds a `vector<Track>` of
  * tracks from many different recordings/compositions, so it cannot be generic over
@@ -30,16 +30,16 @@ import * as bps from './deps/bps/bps.js';
 const $moduleName = '@local-pkg/miso::track';
 /**
  * Lifecycle state of a track within a release. A track is born `Unassigned`,
- * carrying the target `release_id` its originating `Deal` committed to (the
- * release id is a digest of the whole tracklist, so this is the recording owner's
- * consent to the exact release configuration). At publish the release verifies the
- * match and transitions the track to `Assigned`, which carries no id — shedding
- * the 32-byte commitment once it has served its purpose.
+ * carrying the target release id the consent committed to at creation (the release
+ * id is a digest of the whole tracklist, so this is the recording owner's consent
+ * to the exact release configuration). At publish the release verifies the match
+ * and transitions the track to `Assigned`, which carries no id — shedding the
+ * 32-byte commitment once it has served its purpose.
  */
 export const TrackState = new MoveEnum({ name: `${$moduleName}::TrackState`, fields: {
         /**
           * Track has been created but not yet assigned to a release. Carries the target
-          * release id the originating deal committed to.
+          * release id the consent committed to at creation.
           */
         Unassigned: bcs.Address,
         /** Track has been assigned to its target release. */
@@ -63,14 +63,18 @@ export const Track = new MoveStruct({ name: `${$moduleName}::Track`, fields: {
         split_bps: bps.BPS
     } });
 export interface NewArguments {
-    deal: RawTransactionArgument<string>;
+    _: RawTransactionArgument<string>;
     recording: RawTransactionArgument<string>;
+    targetReleaseId: RawTransactionArgument<string>;
+    trackSplitBpsValue: RawTransactionArgument<number>;
 }
 export interface NewOptions {
     package?: string;
     arguments: NewArguments | [
-        deal: RawTransactionArgument<string>,
-        recording: RawTransactionArgument<string>
+        _: RawTransactionArgument<string>,
+        recording: RawTransactionArgument<string>,
+        targetReleaseId: RawTransactionArgument<string>,
+        trackSplitBpsValue: RawTransactionArgument<number>
     ];
     typeArguments: [
         string,
@@ -78,25 +82,52 @@ export interface NewOptions {
     ];
 }
 /**
- * Creates a new track by accepting a deal. The deal is the authorization — created
- * by the recording's admin, carrying the target release and the agreed split.
- * Emits a `DealAcceptedEvent`.
+ * Creates a new track: the recording admin's consent to that recording's inclusion
+ * in a specific future release with an agreed split. Requires the recording admin
+ * capability. No event: a `Track` has `drop` and is not an object, so a creation
+ * event could announce a consent that is then silently discarded, and indexers
+ * would be unable to distinguish pending from dead. Pre-publish observability is
+ * the responsibility of whatever wraps the track (see below).
  *
- * The deal's `RecordingShare`/`CompositionShare` phantoms are erased here: a
- * `Track` is monomorphic so it can live in a release's heterogeneous
- * `vector<Track>`. Identity rides on those phantoms up to this point, but the
- * monomorphic `Track` must store the recording's _address_ for revenue routing —
- * and an address can't come from a phantom. So the matching `Recording` is passed
- * in (the deal's phantoms force it to be the right one) purely to read its id; the
- * deal no longer stores it.
+ * The composition is identified by the recording's `CompositionShare` phantom, so
+ * the recording↔composition pairing is compile-time enforced — there is no
+ * `Composition` argument and no runtime ID check.
+ *
+ * ### What creating a track consents to
+ *
+ * `target_release_id` is derived from the release digest, so targeting it consents
+ * to that release's exact economics and membership: the ordered list of
+ * `(recording, split)` pairs and the creator's nonce, nothing more. The release's
+ * title, artwork, credits, and display grouping are chosen by the release creator
+ * — before or after this track is created — and are not bound by the digest.
+ * Presentation is trusted and publicly attributable, not cryptographically
+ * committed.
+ *
+ * The recording need not be `Published`: its admin can create tracks inside the
+ * recording's own creating transaction (an `Initialized` recording cannot escape
+ * that transaction, so across transactions tracks always reference `Published`,
+ * shared recordings).
+ *
+ * A `Track` has `store`, not `key`: it carries no identity of its own, so it may
+ * be exercised synchronously in the same transaction that creates it, or handed to
+ * an offer extension that wraps it in a real object with its own identity.
+ * Withdrawal, expiry, and rejection are then whatever that wrapping extension
+ * encodes — visible in its type, not in core.
+ *
+ * `recording` compile-time-binds the `RecordingShare`/`CompositionShare` phantom
+ * pairing, and is read for its id: the monomorphic `Track` must store the
+ * recording's _address_ for revenue routing, and an address cannot come from a
+ * phantom.
  */
 export function _new(options: NewOptions) {
     const packageAddress = options.package ?? '@local-pkg/miso';
     const argumentsTypes = [
         null,
-        null
+        null,
+        '0x2::object::ID',
+        'u16'
     ] satisfies (string | null)[];
-    const parameterNames = ["deal", "recording"];
+    const parameterNames = ["_", "recording", "targetReleaseId", "trackSplitBpsValue"];
     return (tx: Transaction) => tx.moveCall({
         package: packageAddress,
         module: 'track',
@@ -150,4 +181,31 @@ export function splitBps(options: SplitBpsOptions) {
         function: 'split_bps',
         arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
     });
+}
+export interface TargetReleaseIdArguments {
+    self: TransactionArgument;
+}
+export interface TargetReleaseIdOptions {
+    package?: string;
+    arguments: TargetReleaseIdArguments | [
+        self: TransactionArgument
+    ];
+}
+/**
+ * Returns the target release id this track's creator consented to. Aborts if the
+ * track is `Assigned`: an assigned track only exists inside a published release,
+ * so its release is the object you fetched it from.
+ */
+export function targetReleaseId(options: TargetReleaseIdOptions) {
+    const packageAddress = options.package ?? '@local-pkg/miso';
+    const argumentsTypes = [
+        null
+    ] satisfies (string | null)[];
+    const parameterNames = ["self"];
+    return (tx: Transaction) => tx.moveCall({
+        package: packageAddress,
+        module: 'track',
+        function: 'target_release_id',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+    });
 }