@misonetwork/sdk 0.1.0

package/src/transactions.ts

@@ -0,0 +1,290 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Transaction builders. Every builder adds commands to a caller-owned
+// `Transaction`, so flows compose in a single PTB, but they come in two shapes.
+// The `create*` primitives take the `Transaction` as their FIRST argument and
+// return their by-value results, so those results can be threaded into later
+// commands. `rejectDeal` has nothing to hand back, so it keeps the Sui SDK
+// thunk shape: `(params) => (tx: Transaction) => …`. Miso calls go through the
+// codegen-generated, type-safe call functions.
+//
+// This module keeps the bare protocol PRIMITIVES only. The rule is: do the
+// minimum the Move semantics FORCE, and return anything the caller could
+// legitimately route elsewhere.
+//
+// `createComposition`, `createRecording`, and `createRelease` 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.
+//
+// Each created object MUST still be consumed by its `publish` in the same PTB
+// (`Composition`, `Recording`, and `Release` are all `key`-only with no `drop`),
+// but that is a same-TRANSACTION requirement, not a same-FUNCTION one: a later
+// `finalize*` command on the same `tx` satisfies it. Keeping them apart is what
+// lets the intermediate value be used at all — borrowing a still-unshared
+// composition into `recording::new`, attaching a royalty pool via `uid_mut`, or
+// sending an admin cap somewhere other than a plain address (every admin cap is
+// `key, store`, so it is freely routable).
+//
+// The opinionated layers — track assembly, cap disposition, minato dispersal,
+// the share-currency lifecycle — live in `@misofm/sdk`
+// (`publishRelease`/`publishReleaseFromDeals`/`publishReleaseGraph`,
+// `finalizeComposition`/`finalizeRecording`/`finalizeRelease`,
+// `publishComposition`/`publishRecording`/`publishCompositionAndRecording`,
+// `share.ts`) as free functions taking `misoPackageId` explicitly. Those import
+// the primitives from here and build on top, same PTB composition pattern, just
+// crossing a package boundary.
+
+import { Transaction, type TransactionObjectArgument } from "@mysten/sui/transactions";
+
+import * as composition from "./contracts/miso/composition.ts";
+import * as recording from "./contracts/miso/recording.ts";
+import * as deal from "./contracts/miso/deal.ts";
+import * as release from "./contracts/miso/release.ts";
+
+/** A thunk that adds commands to a transaction. May be async (resolves at build time). */
+export type TxThunk = (tx: Transaction) => void | Promise<void>;
+
+// ============================================================================
+// Shared inputs
+// ============================================================================
+
+/**
+ * Share-currency binding for a work: the fully-qualified `share::Share` type, the
+ * `Currency<Share>` object, and the `TreasuryCap<Share>`. All three are known once
+ * the currency has been published + initialized, so builders take them explicitly
+ * rather than reading them from chain — keeping the thunks synchronous and
+ * composable (no RPC inside the transaction build).
+ */
+export interface ShareCurrencyBinding {
+  /** The `${packageId}::share::Share` type. */
+  shareType: string;
+  /** The `Currency<Share>` object id. */
+  shareCurrencyId: string;
+  /** The `TreasuryCap<Share>` object id (held by the caller, consumed by `new`). */
+  shareTreasuryCapId: string;
+}
+
+// ============================================================================
+// Composition
+// ============================================================================
+
+/** The three by-value results of `composition::new`, for threading onward in a PTB. */
+export interface CompositionParts {
+  composition: TransactionObjectArgument;
+  adminCap: TransactionObjectArgument;
+  /** The creator's freshly-minted share supply (a `Balance<Share>`). */
+  balance: TransactionObjectArgument;
+}
+
+export interface CreateCompositionParams extends ShareCurrencyBinding {
+  title: string;
+  royaltyRateBps: number;
+  misoPackageId: string;
+}
+
+/**
+ * PRIMITIVE. Appends `composition::new` and returns its by-value results without
+ * dispersing, sharing, or transferring anything — the caller decides what happens
+ * next (share it, keep it unshared to bundle with a recording, attach a dynamic
+ * field via `uid_mut`, …). Composes with anything in the same PTB.
+ */
+export function createComposition(tx: Transaction, params: CreateCompositionParams): CompositionParts {
+  const result = tx.add(
+    composition._new({
+      package: params.misoPackageId,
+      typeArguments: [params.shareType],
+      arguments: [tx.pure.string(params.title), tx.pure.u16(params.royaltyRateBps), tx.object(params.shareCurrencyId), tx.object(params.shareTreasuryCapId)],
+    }),
+  );
+  return { composition: result[0]!, adminCap: result[1]!, balance: result[2]! };
+}
+
+// ============================================================================
+// Recording
+// ============================================================================
+
+/** The three by-value results of `recording::new`, for threading onward in a PTB. */
+export interface RecordingParts {
+  recording: TransactionObjectArgument;
+  adminCap: TransactionObjectArgument;
+  /** The creator's remaining share supply after the composition's cut is split off. */
+  balance: TransactionObjectArgument;
+}
+
+/** The protocol's maximum composition royalty rate (`MAX_ROYALTY_RATE_BPS`). */
+export const PROTOCOL_MAX_ROYALTY_RATE_BPS = 2000;
+
+export interface CreateRecordingParams extends ShareCurrencyBinding {
+  /** Share type of the parent composition (the recording's `CompositionShare` phantom). */
+  compositionShareType: string;
+  /**
+   * Parent `Composition`, passed by immutable reference (`recording::new` reads only
+   * its id + royalty rate). May be an on-chain object (`tx.object(id)`) or a still-
+   * unshared, transaction-local `createComposition(...).composition` result.
+   */
+  composition: TransactionObjectArgument;
+  /**
+   * Slippage guard: the maximum composition royalty rate (bps) the recorder will
+   * grant — `recording::new` aborts if the composition's live rate exceeds it.
+   * Pass the rate you observed. Defaults to the protocol maximum (2000), which
+   * accepts any legal rate.
+   */
+  maxRoyaltyRateBps?: number;
+  misoPackageId: string;
+}
+
+/**
+ * PRIMITIVE. Appends `recording::new` and returns its by-value results without
+ * publishing/dispersing/transferring. Because it borrows the composition by
+ * reference, it can run against a composition that is still an unshared PTB-local
+ * value — the borrow-before-share pattern that lets a composition + recording share
+ * one PTB.
+ */
+export function createRecording(tx: Transaction, params: CreateRecordingParams): RecordingParts {
+  const result = tx.add(
+    recording._new({
+      package: params.misoPackageId,
+      typeArguments: [params.shareType, params.compositionShareType],
+      arguments: [params.composition, tx.object(params.shareCurrencyId), tx.object(params.shareTreasuryCapId), tx.pure.u16(params.maxRoyaltyRateBps ?? PROTOCOL_MAX_ROYALTY_RATE_BPS)],
+    }),
+  );
+  return { recording: result[0]!, adminCap: result[1]!, balance: result[2]! };
+}
+
+// ============================================================================
+// Deal
+// ============================================================================
+
+export interface CreateDealParams {
+  recordingId: string;
+  recordingAdminCapId?: string;
+  recordingAdminCap?: TransactionObjectArgument;
+  /** Share type of the recording (the deal's `RecordingShare` phantom). */
+  recordingShareType: string;
+  /** Share type of the parent composition (the deal's `CompositionShare` phantom). */
+  compositionShareType: string;
+  releaseId: string;
+  trackSplitBps: number;
+  misoPackageId: string;
+}
+
+/**
+ * PRIMITIVE. Appends `deal::new` and returns the `Deal` by value without routing
+ * it anywhere — the caller decides what happens next.
+ *
+ * LIFECYCLE NOTE — the returned `Deal` MUST be consumed in this same
+ * transaction. It is `key, store` with no `drop`, so it cannot be discarded, but
+ * it CAN go to either of two places, which is exactly why this does not choose:
+ *
+ *   1. `tx.transferObjects([deal], recipient)` — send it to whoever is
+ *      assembling the release, for them to redeem later. This is the
+ *      cross-party flow: a recording owner signs a deal for someone else's
+ *      release.
+ *   2. straight into `track::new(deal, &recording)` in this same PTB — the
+ *      same-party flow, where the deal is a transient authorization rather than
+ *      something anyone holds. `@misofm/sdk`'s `publishReleaseGraph` does this.
+ *
+ * Both are legitimate, and picking one for the caller would make the other
+ * awkward, so the disposition stays with the caller. `@misofm/sdk` layers the
+ * opinionated flows on top.
+ *
+ * The `recordingAdminCap` may be passed as an on-chain object id
+ * (`recordingAdminCapId`) or as a PTB-local argument (`recordingAdminCap`) —
+ * the latter lets a deal be signed against a recording created earlier in the
+ * same transaction, before its cap has been transferred anywhere.
+ */
+export function createDeal(tx: Transaction, params: CreateDealParams): TransactionObjectArgument {
+  if (!params.recordingAdminCap && !params.recordingAdminCapId) {
+    throw new Error("createDeal: recordingAdminCapId or recordingAdminCap required");
+  }
+  const adminCapArg = params.recordingAdminCap ?? tx.object(params.recordingAdminCapId!);
+  return tx.add(
+    deal._new({
+      package: params.misoPackageId,
+      typeArguments: [params.recordingShareType, params.compositionShareType],
+      arguments: [
+        adminCapArg,
+        tx.object(params.recordingId),
+        tx.pure.id(params.releaseId),
+        tx.pure.u16(params.trackSplitBps),
+      ],
+    }),
+  );
+}
+
+export interface RejectDealParams {
+  dealId: string;
+  /** Share type of the recording (the deal's `RecordingShare` phantom). */
+  recordingShareType: string;
+  /** Share type of the parent composition (the deal's `CompositionShare` phantom). */
+  compositionShareType: string;
+  misoPackageId: string;
+}
+
+/** Rejects (destroys) a deal without including it in a release. Emits `DealRejectedEvent`. */
+export function rejectDeal(params: RejectDealParams): TxThunk {
+  return (tx) => {
+    tx.add(deal.reject({
+      package: params.misoPackageId,
+      typeArguments: [params.recordingShareType, params.compositionShareType],
+      arguments: [tx.object(params.dealId)],
+    }));
+  };
+}
+
+// ============================================================================
+// Release
+// ============================================================================
+
+/** The two by-value results of `release::new`, for threading onward in a PTB. */
+export interface ReleaseParts {
+  release: TransactionObjectArgument;
+  adminCap: TransactionObjectArgument;
+}
+
+export interface CreateReleaseParams {
+  title: string;
+  /** u256 nonce as a decimal string (deterministic release id). */
+  nonce: string;
+  releaseRegistryId: string;
+  misoPackageId: string;
+}
+
+/**
+ * PRIMITIVE. Appends `release::new` over a caller-built `vector<Track>` and
+ * returns its by-value results without publishing (sharing) the release or
+ * routing the admin cap — the caller decides what happens next. Mirrors
+ * {@link createComposition}/{@link createRecording}.
+ *
+ * `trackVec` is supplied by the caller because track assembly is the part that
+ * genuinely varies between release flows: from recording admin caps, from
+ * pre-made deals, or from a mix of fresh and existing recordings (see
+ * `@misofm/sdk`'s `publishRelease`/`publishReleaseFromDeals`/
+ * `publishReleaseGraph`).
+ *
+ * LIFECYCLE NOTE — the returned `Release` MUST be consumed by
+ * `release::publish` in this same transaction. `Release` is `key`-only with no
+ * `drop`, and `publish` is its only by-value consumer, so an `Initialized`
+ * release cannot be transferred, wrapped, shared, or discarded, and cannot
+ * outlive its creating transaction; the protocol deliberately provides no keep
+ * function. That is a same-PTB requirement, NOT a same-function one — pairing
+ * this with a later `finalizeRelease` command in the same `tx` satisfies it.
+ * (`Composition` and `Recording` carry the identical requirement, which is why
+ * all three primitives have the same shape.) The admin cap has no such
+ * constraint: `ReleaseAdminCap` is `key, store` and `publish` only borrows it,
+ * so it is an ordinary transferable value the caller routes as it sees fit.
+ */
+export function createRelease(
+  tx: Transaction,
+  params: CreateReleaseParams,
+  trackVec: TransactionObjectArgument,
+): ReleaseParts {
+  const result = tx.add(
+    release._new({
+      package: params.misoPackageId,
+      arguments: [tx.pure.string(params.title), trackVec, tx.pure.u256(BigInt(params.nonce)), tx.object(params.releaseRegistryId)],
+    }),
+  );
+  return { release: result[0]!, adminCap: result[1]! };
+}

package/src/types.ts

@@ -0,0 +1,244 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// ============================================================================
+// Common
+// ============================================================================
+
+/** Basis points value (0-10000, where 10000 = 100%). */
+export interface BPS {
+  value: number;
+}
+
+// ============================================================================
+// Composition
+// ============================================================================
+
+/** Lifecycle state of a composition. */
+export type CompositionState =
+  | { type: "Initialized" }
+  | { type: "Published"; timestampMs: number };
+
+/**
+ * A musical composition representing the underlying written work.
+ *
+ * Compositions are the written musical works (songs, instrumentals) that
+ * recordings are based on. Each composition has its own share token for
+ * ownership distribution.
+ *
+ * State machine: Initialized -> Published (immutable after publish)
+ */
+export interface Composition {
+  /** Unique identifier for this composition. */
+  id: string;
+  /** Current lifecycle state. */
+  state: CompositionState;
+  /** Primary title of the composition. */
+  title: string;
+  /** Royalty rate this composition earns from each recording's revenue (basis points, 0-2000). */
+  royaltyRate: BPS;
+}
+
+/**
+ * Emitted once when a composition is published. A pure pointer carrying only the
+ * composition's identity — an indexer fetches the full immutable object by
+ * `compositionId`.
+ */
+export interface CompositionPublishedEvent {
+  compositionId: string;
+}
+
+/**
+ * Emitted when a composition's royalty rate is set or changed. The composition
+ * is identified by the event's `CompositionShare` phantom type, not a field.
+ */
+export interface CompositionRoyaltySetEvent {
+  royaltyRateBps: number;
+}
+
+/**
+ * Admin cap for a Composition, derived deterministically from the Composition object ID.
+ *
+ * The share type parameter T is extracted from the on-chain type
+ * `CompositionAdminCap<T>` where T is the composition's share token type.
+ */
+export interface CompositionAdminCap {
+  /** The object ID of the admin cap. */
+  id: string;
+  /** The share type parameter T from CompositionAdminCap<T>. */
+  shareType: string;
+}
+
+// ============================================================================
+// Recording
+// ============================================================================
+
+/** Lifecycle state of a recording. */
+export type RecordingState =
+  | { type: "Initialized" }
+  | { type: "Published"; timestampMs: number };
+
+/**
+ * An audio recording of a composition.
+ *
+ * Recordings are the audio performances that are distributed and played.
+ * Each recording has its own share token for ownership distribution.
+ *
+ * A recording carries no name of its own: its display title is its
+ * composition's title, resolved through the recording's `CompositionShare`
+ * type parameter. Richer naming ("(Live)", localized titles) lives in the
+ * metadata extension.
+ *
+ * State machine: Initialized -> Published (immutable after publish)
+ */
+export interface Recording {
+  /** Unique identifier for this recording. */
+  id: string;
+  /** Current lifecycle state. */
+  state: RecordingState;
+}
+
+/**
+ * Emitted once when a recording is published. A pure pointer carrying only the
+ * recording's identity — an indexer fetches the full immutable object by
+ * `recordingId`.
+ */
+export interface RecordingPublishedEvent {
+  recordingId: string;
+}
+
+/**
+ * Admin cap for a Recording, derived deterministically from the Recording object ID.
+ *
+ * The share type parameter T is extracted from the on-chain type
+ * `RecordingAdminCap<T>` where T is the recording's share token type.
+ */
+export interface RecordingAdminCap {
+  /** The object ID of the admin cap. */
+  id: string;
+  /** The share type parameter T from RecordingAdminCap<T>. */
+  shareType: string;
+}
+
+// ============================================================================
+// Deal
+// ============================================================================
+
+/**
+ * A deal authorizing a recording's inclusion in a specific release. Created by
+ * the recording's admin, held (transferably) by whoever assembles the release,
+ * and consumed by `track::new`. The recording/composition identities ride on
+ * the object's type parameters; the recording's object id is NOT stored.
+ */
+export interface Deal {
+  /** The object ID of the deal. */
+  id: string;
+  /** The exact release id this deal authorizes (a digest of the full tracklist + nonce). */
+  releaseId: string;
+  /** The agreed track split for this recording within the release. */
+  trackSplitBps: BPS;
+  /** The recording's share type (first type parameter of `Deal<R, C>`). */
+  recordingShareType: string;
+  /** The parent composition's share type (second type parameter of `Deal<R, C>`). */
+  compositionShareType: string;
+}
+
+// ============================================================================
+// Track
+// ============================================================================
+
+/** Lifecycle state of a track on a release. */
+export type TrackState = "Unassigned" | "Assigned";
+
+/**
+ * A track on a release, linking a recording to its position in the tracklist.
+ * The recording is the handle through which all other metadata (share types,
+ * composition lineage, and — via the composition — the display title) is
+ * reached.
+ */
+export interface Track {
+  /** Current state of the track (Unassigned until the release claims it, then Assigned). */
+  state: TrackState;
+  /** ID of the recording on this track. */
+  recordingId: string;
+  /** Revenue split for this track within the release (in basis points). */
+  splitBps: BPS;
+}
+
+// ============================================================================
+// Release
+// ============================================================================
+
+/** Lifecycle state of a release. */
+export type ReleaseState =
+  | { type: "Initialized" }
+  | { type: "Published"; timestampMs: number };
+
+/**
+ * A music release (album, EP, or single).
+ *
+ * A release is a flat, ordered tracklist with per-track revenue distribution
+ * configuration. Display grouping (discs, vinyl sides), cover art, and edition
+ * naming live in extensions — the stored tracklist has the same shape as the
+ * digest pre-image every deal consented to.
+ *
+ * State machine: Initialized -> Published (immutable after publish)
+ */
+export interface Release {
+  /** Unique identifier for this release. */
+  id: string;
+  /** Current lifecycle state. */
+  state: ReleaseState;
+  /** Title of the release. */
+  title: string;
+  /** The ordered tracklist. */
+  tracks: Track[];
+}
+
+/**
+ * Emitted once when a release is published. A pure pointer carrying only the
+ * release's identity — an indexer fetches the full immutable object (discs,
+ * tracks) by `releaseId`.
+ */
+export interface ReleasePublishedEvent {
+  releaseId: string;
+}
+
+/**
+ * Admin cap for a Release, derived deterministically from the Release object ID.
+ *
+ * Unlike Composition and Recording admin caps, ReleaseAdminCap is not generic
+ * (Release has no share type parameter) and stores a reference to its Release.
+ */
+export interface ReleaseAdminCap {
+  /** The object ID of the admin cap. */
+  id: string;
+  /** The object ID of the Release this cap administers. */
+  releaseId: string;
+}
+
+// ============================================================================
+// Deal Events
+// ============================================================================
+
+export interface DealCreatedEvent {
+  dealId: string;
+  releaseId: string;
+  trackSplitBps: BPS;
+}
+
+/**
+ * Emitted when a deal is accepted: consumed by `track::new` into a track for
+ * its target release. Treat as provisional until the release publishes (in the
+ * honest path both land in the same transaction).
+ */
+export interface DealAcceptedEvent {
+  dealId: string;
+  releaseId: string;
+}
+
+/** Emitted when a deal is rejected: destroyed without inclusion in a release. Terminal. */
+export interface DealRejectedEvent {
+  dealId: string;
+  releaseId: string;
+}

package/src/view.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Simulate-based reads (the `view` surface). These build a transaction and run it
+// through the Core `simulateTransaction` API to read a computed value without
+// changing state — used where the value is a pure function of inputs the chain
+// derives (e.g. the deterministic release id).
+
+import { Transaction } from "@mysten/sui/transactions";
+import { bcs } from "@mysten/sui/bcs";
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import * as release from "./contracts/miso/release.ts";
+
+export interface DeriveReleaseIdParams {
+  /** Sender for the simulation (any address; not charged). */
+  sender: string;
+  /** Recording object ids, in track order. */
+  recordingIds: string[];
+  /** Per-track split basis points, aligned to `recordingIds`. */
+  splitBps: number[];
+  /** The release nonce (u256 as a decimal string). */
+  nonce: string;
+  /** The shared ReleaseRegistry object id. */
+  releaseRegistryId: string;
+}
+
+/**
+ * Derives the release id the on-chain `release::new` will produce for these
+ * inputs, via a `simulateTransaction` call to `release::derive_release_id`. The
+ * deals embedded in a release must reference this exact id, so it is computed up
+ * front and threaded into the release publish builder.
+ */
+export async function deriveReleaseId(
+  client: ClientWithCoreApi,
+  misoPackageId: string,
+  params: DeriveReleaseIdParams,
+): Promise<string> {
+  if (params.recordingIds.length !== params.splitBps.length) {
+    throw new Error(`deriveReleaseId: recordingIds (${params.recordingIds.length}) and splitBps (${params.splitBps.length}) length mismatch.`);
+  }
+
+  const tx = new Transaction();
+  tx.setSender(params.sender);
+  tx.add(
+    release.deriveReleaseId({
+      package: misoPackageId,
+      arguments: [params.recordingIds, params.splitBps.map((v) => BigInt(v)), BigInt(params.nonce), params.releaseRegistryId],
+    }),
+  );
+
+  // gRPC/Core equivalent of devInspect: simulate with per-command return values.
+  const res = await client.core.simulateTransaction({ transaction: tx, include: { commandResults: true } });
+  if (res.$kind !== "Transaction") {
+    throw new Error(`derive_release_id simulation failed: ${JSON.stringify(res.FailedTransaction.status)}`);
+  }
+  const returned = res.commandResults?.[0]?.returnValues?.[0]?.bcs;
+  if (!returned) throw new Error("derive_release_id returned no value.");
+  return bcs.Address.parse(returned);
+}