@misonetwork/sdk 0.7.0 → 0.9.0

package/src/transactions.ts

@@ -25,20 +25,24 @@
 // 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`
-// (`release_registry::new_release`, `publishRelease`/`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.
+// 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 {
+  Transaction,
+  type TransactionArgument,
+  type TransactionObjectArgument,
+} from "@mysten/sui/transactions";
 
 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 { asU256, type UnsignedInput } from "./numeric.ts";
 import * as track from "./contracts/miso/track.ts";
+import * as royaltyPool from "./contracts/royalty_pool/pool.ts";
+import * as royaltyStake from "./contracts/royalty_pool/stake.ts";
+import * as routedStake from "./contracts/routed_stake/routed_stake.ts";
 
 /** A thunk that adds commands to a transaction. May be async (resolves at build time). */
 export type TxThunk = (tx: Transaction) => void | Promise<void>;
@@ -145,7 +149,10 @@ export function createRecording(tx: Transaction, params: CreateRecordingParams):
 // ============================================================================
 
 export interface CreateTrackParams {
-  recordingId: string;
+  /** 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). */
@@ -161,7 +168,8 @@ export interface CreateTrackParams {
  * 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 call `release_registry::new_release` from `@misofm/sdk`.
+ * 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`) —
@@ -172,17 +180,251 @@ export function createTrack(tx: Transaction, params: CreateTrackParams): Transac
   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,
-        tx.object(params.recordingId),
+        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]! };
+}
+
+// ============================================================================
+// Generic royalty primitives
+// ============================================================================
+
+/** Create an owned `Stake<Share>` from a by-value `Balance<Share>`. */
+export function createRoyaltyStake(
+  tx: Transaction,
+  params: {
+    balance: TransactionArgument;
+    shareType: string;
+    royaltyPoolPackageId: string;
+  },
+): TransactionObjectArgument {
+  return tx.add(
+    royaltyStake._new({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.shareType],
+      arguments: [params.balance],
+    }),
+  );
+}
+
+/** Destroy an unregistered stake and return its principal `Balance<Share>`. */
+export function destroyRoyaltyStake(
+  tx: Transaction,
+  params: {
+    stake: TransactionObjectArgument;
+    shareType: string;
+    royaltyPoolPackageId: string;
+  },
+): TransactionObjectArgument {
+  return tx.add(
+    royaltyStake.destroy({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.shareType],
+      arguments: [params.stake],
+    }),
+  );
+}
+
+/** Register an owned stake against a shared royalty pool. */
+export function registerRoyaltyStake(
+  tx: Transaction,
+  params: {
+    poolId: string;
+    stakeId?: string;
+    /** A `Stake` created earlier in this same PTB. */
+    stake?: TransactionObjectArgument;
+    shareType: string;
+    currencyType: string;
+    royaltyPoolPackageId: string;
+  },
+): void {
+  if (!params.stake && !params.stakeId) {
+    throw new Error("registerRoyaltyStake: stakeId or stake required");
+  }
+  tx.add(
+    royaltyPool.registerStake({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.shareType, params.currencyType],
+      arguments: [tx.object(params.poolId), params.stake ?? tx.object(params.stakeId!)],
+    }),
+  );
+}
+
+/** Claim rewards. The returned `Balance<Currency>` must be consumed in this PTB. */
+export function claimRoyaltyRewards(
+  tx: Transaction,
+  params: {
+    poolId: string;
+    stakeId: string;
+    shareType: string;
+    currencyType: string;
+    royaltyPoolPackageId: string;
+  },
+): TransactionObjectArgument {
+  return tx.add(
+    royaltyPool.claimRewards({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.shareType, params.currencyType],
+      arguments: [tx.object(params.poolId), tx.object(params.stakeId)],
+    }),
+  );
+}
+
+/**
+ * Permissionlessly route rewards from a shared routed stake into its parent
+ * pool. Pool/routed-stake creation and lifecycle operations take `&mut UID` and
+ * belong in the parent authority module, not in a client-side PTB helper.
+ */
+export function sweepRoutedStake(
+  tx: Transaction,
+  params: {
+    routedStakeId: string;
+    stakePoolId: string;
+    routedPoolId: string;
+    parentId: string;
+    stakeShareType: string;
+    poolShareType: string;
+    currencyType: string;
+    routedStakePackageId: string;
+  },
+): void {
+  tx.add(
+    routedStake.sweep({
+      package: params.routedStakePackageId,
+      typeArguments: [
+        params.stakeShareType,
+        params.poolShareType,
+        params.currencyType,
+      ],
+      arguments: [
+        tx.object(params.routedStakeId),
+        tx.object(params.stakePoolId),
+        tx.object(params.routedPoolId),
+        tx.pure.id(params.parentId),
+      ],
+    }),
+  );
+}

package/src/types.ts

@@ -108,6 +108,20 @@ 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.
  *
@@ -188,6 +202,12 @@ 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.
  *

package/src/view.ts

@@ -10,6 +10,7 @@ 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";
+import { asU256, asU64, type UnsignedInput } from "./numeric.ts";
 
 export interface DeriveTargetReleaseIdParams {
   /** Sender for the simulation (any address; not charged). */
@@ -17,18 +18,18 @@ export interface DeriveTargetReleaseIdParams {
   /** Recording object ids, in track order. */
   recordingIds: string[];
   /** Per-track split basis points, aligned to `recordingIds`. */
-  splitBps: number[];
+  splitBps: UnsignedInput[];
   /** The release nonce (u256 as a decimal string). */
-  nonce: string;
-  /** The derivation parent's object ID, e.g. an extension's shared ReleaseRegistry. */
-  parentId: 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 extension-layer release builder.
+ * up front and threaded into the core release builder.
  */
 export async function deriveTargetReleaseId(
   client: ClientWithCoreApi,
@@ -44,7 +45,12 @@ export async function deriveTargetReleaseId(
   tx.add(
     release.deriveTargetReleaseId({
       package: misoPackageId,
-      arguments: [params.recordingIds, params.splitBps.map((v) => BigInt(v)), BigInt(params.nonce), params.parentId],
+      arguments: [
+        params.releaseRegistryId,
+        params.recordingIds,
+        params.splitBps.map((v) => asU64("track split bps", v)),
+        asU256("release nonce", params.nonce),
+      ],
     }),
   );