@misofm/platform 0.0.0 → 0.18.0

package/src/contracts.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Barrel for the codegen-generated, ABI-bound bindings (BCS structs + type-safe
+// Move calls). Re-exported from the package root as the `contracts` namespace.
+//
+// PLATFORM + EXTENSION packages. The protocol core (`miso`: Composition,
+// Recording, Release, Track) generates into `@misofm/protocol` and is
+// re-exported from ITS `contracts` namespace — import it from there rather than
+// mirroring it here.
+
+// Record identity/issuance and Record Shop primary-sale mechanics. The
+// package-restricted witness constructor is intentionally not exported here.
+export * as record from "@misofm/protocol/contracts/miso_record/record";
+export * as pressing from "@misofm/protocol/contracts/miso_record/pressing";
+export * as listing from "@misofm/protocol/contracts/miso_record_shop/listing";
+
+// Generic royalty-pool primitive, raw-cap Actions, and the three safe crank plugins.
+export * as royaltyPool from "@misofm/protocol/contracts/royalty_pool/pool";
+export * as royaltyPoolStake from "@misofm/protocol/contracts/royalty_pool/stake";
+export * as vault from "@misofm/protocol/contracts/vault/vault";
+export * as compositionRoyaltyPool from "@misofm/protocol/contracts/composition_royalty_pool/composition_royalty_pool";
+export * as recordingRoyaltyPool from "@misofm/protocol/contracts/recording_royalty_pool/recording_royalty_pool";
+export * as partyWallet from "@misofm/protocol/contracts/party_wallet/party_wallet";
+export * as routedStake from "@misofm/protocol/contracts/routed_stake/routed_stake";
+export * as compositionRoutedStake from "@misofm/protocol/contracts/composition_routed_stake/composition_routed_stake";
+export * as compositionRoyaltyPoolPlugin from "@misofm/protocol/contracts/composition_royalty_pool_plugin/composition_royalty_pool_plugin";
+export * as recordingRoyaltyPoolPlugin from "@misofm/protocol/contracts/recording_royalty_pool_plugin/recording_royalty_pool_plugin";
+export * as releaseRevenueDistributorPlugin from "@misofm/protocol/contracts/release_revenue_distributor_plugin/release_revenue_distributor_plugin";
+
+// Cover art (the CoverArt value type + the release attachment extension).
+export * as coverArt from "@misofm/protocol/contracts/cover_art/cover_art";
+export * as releaseCoverArt from "@misofm/protocol/contracts/release_cover_art/release_cover_art";
+
+// Release presentation, discovery, buyer-content, and runtime economics.
+export * as genre from "@misofm/protocol/contracts/genre/genre";
+export * as releaseDescription from "@misofm/protocol/contracts/release_description/release_description";
+export * as releaseDspLink from "@misofm/protocol/contracts/release_dsp_link/release_dsp_link";
+export * as releaseGenre from "@misofm/protocol/contracts/release_genre/release_genre";
+export * as releaseKind from "@misofm/protocol/contracts/release_kind/release_kind";
+export * as releaseRevenueDistributor from "@misofm/protocol/contracts/release_revenue_distributor/release_revenue_distributor";
+export * as recordingAdvisory from "@misofm/protocol/contracts/recording_advisory/recording_advisory";
+export * as recordingLanguage from "@misofm/protocol/contracts/recording_language/recording_language";
+export * as recordingMasterReference from "@misofm/protocol/contracts/recording_master_reference/recording_master_reference";
+export * as recordingStreamingTranscode from "@misofm/protocol/contracts/recording_streaming_transcode/recording_streaming_transcode";
+export * as recordingPreview from "@misofm/protocol/contracts/recording_preview/recording_preview";
+
+// Credits extensions (per-work credit stores + their role vocabularies).
+export * as compositionCredits from "@misofm/protocol/contracts/composition_credits/composition_credits";
+export * as compositionPartyRole from "@misofm/protocol/contracts/composition_credits/composition_party_role";
+export * as recordingCredits from "@misofm/protocol/contracts/recording_credits/recording_credits";
+export * as recordingPartyRole from "@misofm/protocol/contracts/recording_credits/recording_party_role";
+export * as releaseCredits from "@misofm/protocol/contracts/release_credits/release_credits";
+export * as releasePartyRole from "@misofm/protocol/contracts/release_credits/release_party_role";

package/src/cover.ts

@@ -0,0 +1,240 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Release cover art. A cover is a still image (optionally an animation) stored as
+// a Walrus blob and referenced on-chain via `ori::WalrusData`. We build the ref
+// (`ori::walrus_data::new_blob`, a raw call — ori is an external dep), wrap it in a
+// `cover_art::CoverArt`, and attach it to the Release with
+// `release_cover_art::set_cover` (gated by the ReleaseAdminCap).
+//
+// Blob ids are passed as `u256` (decimal string or bigint) — the CLI converts the
+// base64url Walrus blob id to u256 before calling.
+//
+// The `Release` being covered is a protocol object; the cover is a platform
+// opinion attached to it through the release's cap-gated `uid_mut` hook, which is
+// why this module ships from `@misofm/platform` rather than the protocol SDK.
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import { bcs } from "@mysten/sui/bcs";
+import { deriveDynamicFieldID } from "@mysten/sui/utils";
+import type { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
+import type { TxThunk } from "./transactions.ts";
+import { asU64, directAdminCap, invokeWithAdminCap, type AdminCapAuthority, type ObjectInput, type U64Input } from "./vault.ts";
+import { OPTION_NONE, OPTION_SOME } from "./internal.ts";
+import * as coverArt from "@misofm/protocol/contracts/cover_art/cover_art";
+import * as releaseCoverArt from "@misofm/protocol/contracts/release_cover_art/release_cover_art";
+
+type ReleaseAuthorityInput =
+  | { readonly authority: AdminCapAuthority; readonly releaseAdminCapId?: never }
+  | { readonly authority?: never; readonly releaseAdminCapId: string };
+function releaseAuthorityOf(input: ReleaseAuthorityInput): AdminCapAuthority {
+  if (input.authority !== undefined) return input.authority;
+  if (input.releaseAdminCapId !== undefined) return directAdminCap(input.releaseAdminCapId);
+  throw new Error("release authority is required");
+}
+
+interface SetReleaseCoverParamsBase {
+  /** The `Release` object to attach the cover to. */
+  releaseId: ObjectInput;
+  /** Walrus blob id of the still cover image, as `u256` (decimal string or bigint). */
+  stillBlobId: bigint | string;
+  /** Optional animated-cover Walrus blob id (`u256`); omit for a still-only cover. */
+  animatedBlobId?: bigint | string | null;
+  /** `cover_art` package — home of the `CoverArt` value type (`cover_art::new`). */
+  coverArtPackageId: string;
+  /** `release_cover_art` package — home of the `set_cover` extension entry point. */
+  releaseCoverArtPackageId: string;
+  /** `ori` package (home of `walrus_data::new_blob` / the `WalrusData` type). */
+  oriPackageId: string;
+}
+
+function object(tx: Transaction, value: ObjectInput): TransactionObjectArgument {
+  return typeof value === "string" ? tx.object(value) : value;
+}
+export type SetReleaseCoverParams = SetReleaseCoverParamsBase & ReleaseAuthorityInput;
+
+export type SetReleaseTrackCoverParams = SetReleaseCoverParams & {
+  /** Zero-based index in the release's flattened tracklist. */
+  trackIndex: U64Input;
+};
+
+function buildCover(tx: Parameters<TxThunk>[0], p: SetReleaseCoverParams) {
+  const walrusType = `${p.oriPackageId}::walrus_data::WalrusData`;
+  const blob = (id: bigint | string) =>
+    tx.moveCall({
+      target: `${p.oriPackageId}::walrus_data::new_blob`,
+      arguments: [tx.pure.u256(id)],
+    });
+
+  const still = blob(p.stillBlobId);
+  const animated =
+    p.animatedBlobId == null
+      ? tx.moveCall({ target: OPTION_NONE, typeArguments: [walrusType] })
+      : tx.moveCall({
+          target: OPTION_SOME,
+          typeArguments: [walrusType],
+          arguments: [blob(p.animatedBlobId)],
+        });
+
+  return tx.add(
+    coverArt._new({
+      package: p.coverArtPackageId,
+      arguments: [still, animated],
+    }),
+  );
+}
+
+/** Sets (or replaces) a release's album-level cover from Walrus blob ids. */
+export function setReleaseCover(p: SetReleaseCoverParams): TxThunk {
+  return (tx) => {
+    const cover = buildCover(tx, p);
+    invokeWithAdminCap(tx, releaseAuthorityOf(p), {
+      target: `${p.releaseCoverArtPackageId}::release_cover_art::set_cover`,
+      arguments: [object(tx, p.releaseId), cover],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+/** Sets (or replaces) one track's cover from Walrus blob ids. */
+export function setReleaseTrackCover(p: SetReleaseTrackCoverParams): TxThunk {
+  return (tx) => {
+    const cover = buildCover(tx, p);
+    invokeWithAdminCap(tx, releaseAuthorityOf(p), {
+      target: `${p.releaseCoverArtPackageId}::release_cover_art::set_track_cover`,
+      arguments: [object(tx, p.releaseId), tx.pure.u64(asU64("trackIndex", p.trackIndex)), cover],
+      adminCapIndex: 1,
+    });
+  };
+}
+
+// ── Reads ────────────────────────────────────────────────────────────────────
+
+/**
+ * A normalized reference to a cover image's Walrus data. Blob ids are returned as
+ * `u256` decimal strings (the on-chain form); callers convert to a base64url
+ * aggregator URL with `@unconfirmed/ori` (`u256ToB64Url` / `walrusDataUrl`).
+ */
+export type CoverImageRef =
+  | { kind: "blob"; blobId: string }
+  | {
+      kind: "quiltPatch";
+      quiltId: string;
+      version: number;
+      startIndex: number;
+      endIndex: number;
+    };
+
+/** A release's album-level cover: a still image and an optional animation. */
+export interface ReleaseCoverView {
+  still: CoverImageRef;
+  animated: CoverImageRef | null;
+}
+
+// The cover is a dynamic field on the release UID under an empty `ExtensionKey()`
+// (Move's implicit `dummy_field: bool` → one `false` byte). The stored value is a
+// `Field { id, name: ExtensionKey, value: ReleaseCoverArt }`.
+const CoverArtField = bcs.struct("Field", {
+  id: bcs.Address,
+  name: releaseCoverArt.ExtensionKey,
+  value: releaseCoverArt.ReleaseCoverArt,
+});
+const COVER_ART_KEY_BYTES = releaseCoverArt.ExtensionKey.serialize([
+  false,
+]).toBytes();
+
+/** A parsed `ori::WalrusData` value (a MoveEnum: `Blob` or `QuiltPatch`). */
+type ParsedWalrusData =
+  | { $kind: "Blob"; Blob: [string | number | bigint, unknown] }
+  | {
+      $kind: "QuiltPatch";
+      QuiltPatch: [string | number | bigint, number, number, number];
+    };
+
+function toCoverImageRef(wd: ParsedWalrusData): CoverImageRef {
+  if (wd.$kind === "Blob") return { kind: "blob", blobId: String(wd.Blob[0]) };
+  const [quiltId, version, startIndex, endIndex] = wd.QuiltPatch;
+  return {
+    kind: "quiltPatch",
+    quiltId: String(quiltId),
+    version,
+    startIndex,
+    endIndex,
+  };
+}
+
+/**
+ * Reads a release's album-level cover (the `release_cover_art` extension), or
+ * `null` if no cover is attached. Derives the `ExtensionKey` dynamic field on the
+ * release, parses the `ReleaseCoverArt`, and returns the still (+ optional
+ * animation) as normalized Walrus refs for release displays.
+ */
+export async function getReleaseCover(
+  client: ClientWithCoreApi,
+  releaseId: string,
+  releaseCoverArtPackageId: string,
+): Promise<ReleaseCoverView | null> {
+  return (
+    (
+      await getReleaseCoversByIds(client, [releaseId], releaseCoverArtPackageId)
+    )[releaseId] ?? null
+  );
+}
+
+export function parseReleaseCoverContent(
+  content: Uint8Array,
+): ReleaseCoverView | null {
+  const cover = CoverArtField.parse(content).value.cover as {
+    still: ParsedWalrusData;
+    animated: ParsedWalrusData | null;
+  } | null;
+  if (!cover) return null;
+
+  return {
+    still: toCoverImageRef(cover.still),
+    animated: cover.animated ? toCoverImageRef(cover.animated) : null,
+  };
+}
+
+/** Deterministic dynamic-field id for the configured release-cover package. */
+export function releaseCoverFieldId(
+  releaseId: string,
+  releaseCoverArtPackageId: string,
+): string {
+  return deriveDynamicFieldID(
+    releaseId,
+    `${releaseCoverArtPackageId}::release_cover_art::ExtensionKey`,
+    COVER_ART_KEY_BYTES,
+  );
+}
+
+/**
+ * Read covers for many releases from the configured package in one Core request.
+ */
+export async function getReleaseCoversByIds(
+  client: ClientWithCoreApi,
+  releaseIdsInput: readonly string[],
+  releaseCoverArtPackageId: string,
+): Promise<Partial<Record<string, ReleaseCoverView>>> {
+  const releaseIds = [...new Set(releaseIdsInput)];
+  const targets = releaseIds.map((releaseId) => ({
+    releaseId,
+    fieldId: releaseCoverFieldId(releaseId, releaseCoverArtPackageId),
+  }));
+  if (targets.length === 0) return {};
+
+  const { objects } = await client.core.getObjects({
+    objectIds: targets.map((target) => target.fieldId),
+    include: { content: true },
+  });
+  const out: Partial<Record<string, ReleaseCoverView>> = {};
+  objects.forEach((object, index) => {
+    const target = targets[index];
+    if (!target || object instanceof Error || !object.content) return;
+    const cover = parseReleaseCoverContent(object.content);
+    if (cover) {
+      out[target.releaseId] = cover;
+    }
+  });
+  return out;
+}