@misofm/musicos 0.1.0

package/src/transactions.ts

@@ -0,0 +1,305 @@
+// 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.
+// 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. 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` and `createRecording` 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).
+//
+// This package exposes the complete low-level current ABI. The platform SDK
+// should own product-specific orchestration (cap disposition, currency
+// lifecycle, authority-package workflows) on top of these composable calls.
+
+import {
+  Transaction,
+  type TransactionObjectArgument,
+} from "@mysten/sui/transactions";
+
+import * as composition from "./contracts/musicos/composition.ts";
+import * as recording from "./contracts/musicos/recording.ts";
+import * as release from "./contracts/musicos/release.ts";
+import { asU256, type UnsignedInput } from "./numeric.ts";
+import * as track from "./contracts/musicos/track.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;
+}
+
+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;
+  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)],
+    }),
+  );
+  return { recording: result[0]!, adminCap: result[1]!, balance: result[2]! };
+}
+
+// ============================================================================
+// Track
+// ============================================================================
+
+export interface CreateTrackParams {
+  /** Shared recording object ID, unless `recording` is PTB-local. */
+  recordingId?: string;
+  /** A recording returned by `createRecording` earlier in this same PTB. */
+  recording?: TransactionObjectArgument;
+  recordingAdminCapId?: string;
+  recordingAdminCap?: TransactionObjectArgument;
+  /** Share type of the recording (the track's `RecordingShare` phantom). */
+  recordingShareType: string;
+  /** Share type of the parent composition (the track's `CompositionShare` phantom). */
+  compositionShareType: string;
+  targetReleaseId: string;
+  trackSplitBps: number;
+  misoPackageId: string;
+}
+
+/**
+ * PRIMITIVE. Appends `track::new` and returns its by-value `Track`. A track has
+ * `drop, store`, so callers may leave it unused; to assemble a release, pass
+ * returned tracks to `tx.makeMoveVec({ type: `${misoPackageId}::track::Track`,
+ * elements })` and then pass that vector to `createRelease` with its shared
+ * `ReleaseRegistry` object.
+ *
+ * The `recordingAdminCap` may be passed as an on-chain object id
+ * (`recordingAdminCapId`) or as a PTB-local argument (`recordingAdminCap`) —
+ * the latter lets a track be created against a recording created earlier in the
+ * same transaction, before its cap has been transferred anywhere.
+ */
+export function createTrack(tx: Transaction, params: CreateTrackParams): TransactionObjectArgument {
+  if (!params.recordingAdminCap && !params.recordingAdminCapId) {
+    throw new Error("createTrack: recordingAdminCapId or recordingAdminCap required");
+  }
+  if (!params.recording && !params.recordingId) {
+    throw new Error("createTrack: recordingId or recording required");
+  }
+  const adminCapArg = params.recordingAdminCap ?? tx.object(params.recordingAdminCapId!);
+  const recordingArg = params.recording ?? tx.object(params.recordingId!);
+  return tx.add(
+    track._new({
+      package: params.misoPackageId,
+      typeArguments: [params.recordingShareType, params.compositionShareType],
+      arguments: [
+        adminCapArg,
+        recordingArg,
+        tx.pure.id(params.targetReleaseId),
+        tx.pure.u16(params.trackSplitBps),
+      ],
+    }),
+  );
+}
+
+// ============================================================================
+// Publish finalizers
+// ============================================================================
+
+/** Consume and share an initialized composition. The generated call supplies Clock. */
+export function publishComposition(
+  tx: Transaction,
+  params: {
+    composition: TransactionObjectArgument;
+    adminCap: TransactionObjectArgument;
+    shareType: string;
+    misoPackageId: string;
+  },
+): void {
+  tx.add(
+    composition.publish({
+      package: params.misoPackageId,
+      typeArguments: [params.shareType],
+      arguments: [params.composition, params.adminCap],
+    }),
+  );
+}
+
+/** Consume and share an initialized recording. The generated call supplies Clock. */
+export function publishRecording(
+  tx: Transaction,
+  params: {
+    recording: TransactionObjectArgument;
+    adminCap: TransactionObjectArgument;
+    recordingShareType: string;
+    compositionShareType: string;
+    misoPackageId: string;
+  },
+): void {
+  tx.add(
+    recording.publish({
+      package: params.misoPackageId,
+      typeArguments: [params.recordingShareType, params.compositionShareType],
+      arguments: [params.recording, params.adminCap],
+    }),
+  );
+}
+
+/** Consume and share an initialized release. The generated call supplies Clock. */
+export function publishRelease(
+  tx: Transaction,
+  params: {
+    release: TransactionObjectArgument;
+    adminCap: TransactionObjectArgument;
+    misoPackageId: string;
+  },
+): void {
+  tx.add(
+    release.publish({
+      package: params.misoPackageId,
+      arguments: [params.release, params.adminCap],
+    }),
+  );
+}
+
+// ============================================================================
+// Core release registry
+// ============================================================================
+
+/** The by-value result of core `release::new`. Publish it in this PTB. */
+export interface ReleaseParts {
+  release: TransactionObjectArgument;
+  adminCap: TransactionObjectArgument;
+}
+
+export interface CreateReleaseParams {
+  /** Shared, canonical `miso::release::ReleaseRegistry` object ID. */
+  releaseRegistryId: string;
+  title: string;
+  /** `Track` values returned by {@link createTrack}; all are consumed. */
+  tracks: readonly TransactionObjectArgument[];
+  nonce: UnsignedInput;
+  /** Freshly published core `miso` package ID. */
+  misoPackageId: string;
+}
+
+/**
+ * Assemble a release through core `miso::release::new`. The registry is the
+ * first object argument; there is no arbitrary-parent or utility-package path.
+ * Both returned values are non-drop and must be published or otherwise consumed
+ * in this PTB.
+ */
+export function createRelease(
+  tx: Transaction,
+  params: CreateReleaseParams,
+): ReleaseParts {
+  const tracks = tx.makeMoveVec({
+    type: `${params.misoPackageId}::track::Track`,
+    elements: [...params.tracks],
+  });
+  const result = tx.add(
+    release._new({
+      package: params.misoPackageId,
+      arguments: [
+        tx.object(params.releaseRegistryId),
+        tx.pure.string(params.title),
+        tracks,
+        tx.pure.u256(asU256("release nonce", params.nonce)),
+      ],
+    }),
+  );
+  return { release: result[0]!, adminCap: result[1]! };
+}

package/src/types.ts

@@ -0,0 +1,222 @@
+// 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-10000). Immutable for the composition's lifetime.
+   */
+  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;
+}
+
+/**
+ * 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;
+  /**
+   * Object ID of the parent composition. An identity/membership handle — not a
+   * revenue routing target: the composition is paid via its recording-share
+   * ownership, settled at recording creation. Immutable.
+   */
+  compositionId: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Emitted when recording creation grants the composition its immutable royalty
+ * rate's share of the new recording currency.
+ */
+export interface CompositionSharesGrantedEvent {
+  recordingId: string;
+  compositionId: string;
+  /** Recording-share base units sent to the composition address. */
+  value: string;
+  /** The immutable composition royalty rate applied at recording creation. */
+  rateBps: number;
+  grantedBy: 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;
+}
+
+// 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 composition underlying this track's recording. An identity/
+   * membership handle — not a revenue routing target: the composition is paid
+   * via its recording-share ownership, and a track routes its full split to the
+   * recording.
+   */
+  compositionId: string;
+  /** 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 track 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 by
+ * `releaseId`.
+ */
+export interface ReleasePublishedEvent {
+  releaseId: string;
+}
+
+/** Emitted when package initialization shares the canonical release registry. */
+export interface ReleaseRegistryCreatedEvent {
+  registryId: string;
+  createdBy: 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;
+}

package/src/view.ts

@@ -0,0 +1,65 @@
+// 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/musicos/release.ts";
+import { asU256, asU64, type UnsignedInput } from "./numeric.ts";
+
+export interface DeriveTargetReleaseIdParams {
+  /** 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: UnsignedInput[];
+  /** The release nonce (u256 as a decimal string). */
+  nonce: UnsignedInput;
+  /** Shared canonical core `miso::release::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_target_release_id`.
+ * Tracks embedded in a release must reference this exact ID, so it is computed
+ * up front and threaded into the core release builder.
+ */
+export async function deriveTargetReleaseId(
+  client: ClientWithCoreApi,
+  misoPackageId: string,
+  params: DeriveTargetReleaseIdParams,
+): Promise<string> {
+  if (params.recordingIds.length !== params.splitBps.length) {
+    throw new Error(`deriveTargetReleaseId: recordingIds (${params.recordingIds.length}) and splitBps (${params.splitBps.length}) length mismatch.`);
+  }
+
+  const tx = new Transaction();
+  tx.setSender(params.sender);
+  tx.add(
+    release.deriveTargetReleaseId({
+      package: misoPackageId,
+      arguments: [
+        params.releaseRegistryId,
+        params.recordingIds,
+        params.splitBps.map((v) => asU64("track split bps", v)),
+        asU256("release nonce", params.nonce),
+      ],
+    }),
+  );
+
+  // 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_target_release_id simulation failed: ${JSON.stringify(res.FailedTransaction.status)}`);
+  }
+  const returned = res.commandResults?.[0]?.returnValues?.[0]?.bcs;
+  if (!returned) throw new Error("derive_target_release_id returned no value.");
+  return bcs.Address.parse(returned);
+}