@misonetwork/sdk 0.6.0 → 0.8.0

package/src/queries.ts

@@ -12,10 +12,8 @@
 //     they obtained from the chain, so a miss means a broken reference — an
 //     exceptional state, not a normal one.
 //   - Extension dynamic-field readers return `null` — extension data is optional
-//     by design, and "not attached" is a normal, expected state. Those readers
-//     live in `@misofm/sdk` now (`getCompositionCredits`, `getRecordingCredits`,
-//     `getReleaseCredits`, `getReleaseCover`) and re-import {@link isNotFound}
-//     from here to keep one not-found taxonomy across both packages.
+//     by design, and "not attached" is a normal, expected state. Use
+//     `getExtensionField` with the generated BCS codec for the extension.
 // All null-returning readers use {@link isNotFound} to distinguish a missing
 // object from a transport failure (which still throws).
 
@@ -26,7 +24,13 @@ import { deriveObjectID, normalizeSuiAddress } from "@mysten/sui/utils";
 
 import { Composition as CompositionBcs } from "./contracts/miso/composition.ts";
 import { Recording as RecordingBcs } from "./contracts/miso/recording.ts";
-import { Release as ReleaseBcs } from "./contracts/miso/release.ts";
+import {
+  Release as ReleaseBcs,
+  ReleaseRegistry as ReleaseRegistryBcs,
+} from "./contracts/miso/release.ts";
+import { RoyaltyPool as RoyaltyPoolBcs } from "./contracts/royalty_pool/pool.ts";
+import { Stake as RoyaltyStakeBcs } from "./contracts/royalty_pool/stake.ts";
+import { RoutedStake as RoutedStakeBcs } from "./contracts/routed_stake/routed_stake.ts";
 import {
   mapBps,
   mapComposition,
@@ -117,6 +121,35 @@ export function isNotFound(e: unknown): boolean {
 /** Key bytes for Move unit structs (single `0x00` for `dummy_field: bool = false`). */
 const UNIT_STRUCT_KEY_BYTES = new Uint8Array([0x00]);
 
+/** Any generated BCS codec with a `parse` method. */
+export interface BcsParser<T> {
+  parse(bytes: Uint8Array): T;
+}
+
+/** Exhaust every Core owned-object page; cap discovery must not truncate. */
+async function listAllOwnedObjects(
+  client: ClientWithCoreApi,
+  input: Record<string, unknown>,
+): Promise<Array<{ objectId: string; type?: string; json?: unknown }>> {
+  const objects: Array<{ objectId: string; type?: string; json?: unknown }> = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await (client.core.listOwnedObjects as (args: unknown) => Promise<{
+      objects: Array<{ objectId: string; type?: string; json?: unknown }>;
+      pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+      hasNextPage?: boolean;
+      cursor?: string | null;
+    }>)(cursor ? { ...input, cursor } : input);
+    objects.push(...page.objects);
+    cursor = page.pageInfo?.hasNextPage
+      ? page.pageInfo.endCursor
+      : page.hasNextPage
+        ? page.cursor
+        : null;
+  } while (cursor);
+  return objects;
+}
+
 /** Fetches one object's BCS content bytes (or null if absent). */
 async function getContent(
   client: ClientWithCoreApi,
@@ -129,6 +162,168 @@ async function getContent(
   return object.content ?? null;
 }
 
+/**
+ * Fetch and parse an object through the transport-neutral Core API. Object
+ * content is BCS; never pass the full `objectBcs` envelope to a Move codec.
+ */
+export async function getObjectByBcs<T>(
+  client: ClientWithCoreApi,
+  objectId: string,
+  codec: BcsParser<T>,
+): Promise<T> {
+  const content = await getContent(client, objectId);
+  if (!content) throw new Error(`Object not found: ${objectId}`);
+  return codec.parse(content);
+}
+
+export interface ExtensionFieldParams<T> {
+  /** Freshly published package address for the extension. */
+  packageId: string;
+  /** Move module declaring the fieldless `ExtensionKey`. */
+  module: string;
+  /** Generated codec for the dynamic-field value. */
+  codec: BcsParser<T>;
+}
+
+/**
+ * Read an optional first-party extension field from a core object's UID. Every
+ * current extension uses a fieldless `ExtensionKey`, whose BCS is one false
+ * boolean byte. Absence returns `null`; transport errors still propagate.
+ */
+export async function getExtensionField<T>(
+  client: ClientWithCoreApi,
+  parentId: string,
+  params: ExtensionFieldParams<T>,
+): Promise<T | null> {
+  try {
+    const { dynamicField } = await client.core.getDynamicField({
+      parentId,
+      name: {
+        type: `${params.packageId}::${params.module}::ExtensionKey`,
+        bcs: UNIT_STRUCT_KEY_BYTES,
+      },
+    });
+    return params.codec.parse(dynamicField.value.bcs);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+export interface ReleaseDspFieldParams<T> {
+  /** Freshly published `release_dsp_link` package address. */
+  packageId: string;
+  /** Numeric DSP discriminator (`DspLinkData::platform()`). */
+  platform: number;
+  /** Generated codec for `DspLinkData` or `PerTrack<Option<DspLinkData>>`. */
+  codec: BcsParser<T>;
+}
+
+async function getReleaseDspField<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  key: "ReleaseLinkKey" | "TrackLinksKey",
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  if (!Number.isInteger(params.platform) || params.platform < 0 || params.platform > 255) {
+    throw new Error("DSP platform must be a u8 discriminator");
+  }
+  try {
+    const { dynamicField } = await client.core.getDynamicField({
+      parentId: releaseId,
+      name: {
+        type: `${params.packageId}::release_dsp_link::${key}`,
+        bcs: Uint8Array.of(params.platform),
+      },
+    });
+    return params.codec.parse(dynamicField.value.bcs);
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
+/** Read a release-level DSP link stored under `ReleaseLinkKey(platform)`. */
+export function getReleaseDspLink<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  return getReleaseDspField(client, releaseId, "ReleaseLinkKey", params);
+}
+
+/** Read the per-track DSP-link array stored under `TrackLinksKey(platform)`. */
+export function getTrackDspLinks<T>(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  params: ReleaseDspFieldParams<T>,
+): Promise<T | null> {
+  return getReleaseDspField(client, releaseId, "TrackLinksKey", params);
+}
+
+// ============================================================================
+// Core registry and generic primitive reads
+// ============================================================================
+
+/** Parse the shared canonical core `miso::release::ReleaseRegistry` by ID. */
+export async function getReleaseRegistryById(
+  client: ClientWithCoreApi,
+  registryId: string,
+) {
+  return getObjectByBcs(client, registryId, ReleaseRegistryBcs);
+}
+
+/** Parse a royalty pool by object ID. Phantom type arguments do not affect BCS. */
+export async function getRoyaltyPoolById(
+  client: ClientWithCoreApi,
+  poolId: string,
+) {
+  return getObjectByBcs(client, poolId, RoyaltyPoolBcs);
+}
+
+/** Parse an owned `Stake<Share>` by object ID. */
+export async function getRoyaltyStakeById(
+  client: ClientWithCoreApi,
+  stakeId: string,
+) {
+  return getObjectByBcs(client, stakeId, RoyaltyStakeBcs);
+}
+
+/** Parse a shared routed stake by object ID. */
+export async function getRoutedStakeById(
+  client: ClientWithCoreApi,
+  routedStakeId: string,
+) {
+  return getObjectByBcs(client, routedStakeId, RoutedStakeBcs);
+}
+
+/** Deterministically derive the royalty-pool ID for a parent and type pair. */
+export function deriveRoyaltyPoolId(
+  parentId: string,
+  shareType: string,
+  currencyType: string,
+  royaltyPoolPackageId: string,
+): string {
+  return deriveObjectID(
+    parentId,
+    `${royaltyPoolPackageId}::pool::RoyaltyPoolKey<${shareType}, ${currencyType}>`,
+    UNIT_STRUCT_KEY_BYTES,
+  );
+}
+
+/** Deterministically derive the routed-stake ID for a parent and stake share. */
+export function deriveRoutedStakeId(
+  parentId: string,
+  stakeShareType: string,
+  routedStakePackageId: string,
+): string {
+  return deriveObjectID(
+    parentId,
+    `${routedStakePackageId}::routed_stake::RoutedStakeKey<${stakeShareType}>`,
+    UNIT_STRUCT_KEY_BYTES,
+  );
+}
+
 // ============================================================================
 // GraphQL discovery queries
 // ============================================================================
@@ -465,10 +660,7 @@ export async function getOwnedCompositionAdminCaps(
   misoPackageId: string,
 ): Promise<CompositionAdminCap[]> {
   const capType = `${misoPackageId}::composition::CompositionAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
-    owner,
-    type: capType,
-  });
+  const objects = await listAllOwnedObjects(client, { owner, type: capType });
   const caps: CompositionAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
@@ -590,10 +782,7 @@ export async function getOwnedRecordingAdminCaps(
   misoPackageId: string,
 ): Promise<RecordingAdminCap[]> {
   const capType = `${misoPackageId}::recording::RecordingAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
-    owner,
-    type: capType,
-  });
+  const objects = await listAllOwnedObjects(client, { owner, type: capType });
   const caps: RecordingAdminCap[] = [];
   for (const obj of objects) {
     const match = obj.type?.match(/<(.+)>$/);
@@ -666,7 +855,7 @@ export async function getOwnedReleaseAdminCaps(
   misoPackageId: string,
 ): Promise<ReleaseAdminCap[]> {
   const capType = `${misoPackageId}::release::ReleaseAdminCap`;
-  const { objects } = await client.core.listOwnedObjects({
+  const objects = await listAllOwnedObjects(client, {
     owner,
     type: capType,
     include: { json: true },
@@ -724,7 +913,7 @@ export async function getShareCurrencyTreasuryCap(
   shareType: string,
   owner: string,
 ): Promise<string> {
-  const { objects } = await client.core.listOwnedObjects({
+  const objects = await listAllOwnedObjects(client, {
     owner,
     type: `0x2::coin::TreasuryCap<${shareType}>`,
   });
@@ -766,15 +955,28 @@ async function addressOfRecordingWithShareType(
   misoPackageId: string,
   shareType: string,
 ): Promise<string | null> {
-  const result = await client.query({
-    query: AddressesAndTypesByTypeQuery,
-    variables: { type: `${misoPackageId}::recording::Recording` },
-  });
-  for (const node of result.data?.objects?.nodes ?? []) {
-    const repr = node?.asMoveObject?.contents?.type?.repr;
-    if (!repr || !node.address) continue;
-    const [recordingShareType] = extractTypeParams2(repr);
-    if (recordingShareType === shareType) return node.address;
-  }
+  let cursor: string | null | undefined;
+  do {
+    const result = await client.query<
+      { objects?: WorkAddressConnection | null },
+      { type: string; cursor?: string | null }
+    >({
+      query: `query RecordingAddress($type: String!, $cursor: String) {
+        objects(first: 50, after: $cursor, filter: { type: $type }) {
+          pageInfo { hasNextPage endCursor }
+          nodes { address asMoveObject { contents { type { repr } } } }
+        }
+      }`,
+      variables: { type: `${misoPackageId}::recording::Recording`, cursor },
+    });
+    const page = result.data?.objects;
+    for (const node of page?.nodes ?? []) {
+      const repr = node?.asMoveObject?.contents?.type?.repr;
+      if (!repr || !node.address) continue;
+      const [recordingShareType] = extractTypeParams2(repr);
+      if (recordingShareType === shareType) return node.address;
+    }
+    cursor = page?.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
+  } while (cursor);
   return null;
 }

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>;
@@ -110,9 +114,6 @@ export interface RecordingParts {
   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;
@@ -122,13 +123,6 @@ export interface CreateRecordingParams extends ShareCurrencyBinding {
    * 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;
 }
 
@@ -144,7 +138,7 @@ export function createRecording(tx: Transaction, params: CreateRecordingParams):
     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)],
+      arguments: [params.composition, tx.object(params.shareCurrencyId), tx.object(params.shareTreasuryCapId)],
     }),
   );
   return { recording: result[0]!, adminCap: result[1]!, balance: result[2]! };
@@ -155,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). */
@@ -171,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`) —
@@ -182,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),
+      ],
+    }),
+  );
+}