@misonetwork/sdk 0.1.0

package/src/execute.ts

@@ -0,0 +1,141 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Transaction execution + effect extraction (the Signer-parameter pattern).
+//
+// Builders elsewhere only *append* to a caller-owned Transaction; this module is
+// where a transaction is actually submitted. `signAndExecute` submits over the
+// unified Core API, unwraps the `{ $kind: "Transaction", Transaction }` envelope,
+// waits for finality, and returns changed objects, the objectId→type map, balance
+// changes, and net gas for downstream extraction. Everything here is
+// transport-agnostic — it takes any `ClientWithCoreApi`, so gRPC / JSON-RPC /
+// GraphQL clients all work.
+//
+// `executeViaExecutor`, which submitted a non-idempotent PTB through a
+// `ParallelTransactionExecutor` exactly once, moved to `@misofm/sdk` along with
+// its only caller (`share.ts`'s batch currency publishing) — it builds on
+// `buildTx`/`toExecResult`/`FULL_INCLUDE` exported from this module.
+
+import { Transaction } from "@mysten/sui/transactions";
+import type { ClientWithCoreApi, SuiClientTypes } from "@mysten/sui/client";
+import type { Signer } from "@mysten/sui/cryptography";
+import type { TxThunk } from "./transactions.ts";
+
+/** The effect fields every submit path requests, so extraction is uniform. */
+export const FULL_INCLUDE = { effects: true, objectTypes: true, balanceChanges: true } as const;
+type FullInclude = typeof FULL_INCLUDE;
+
+export interface ExecResult {
+  digest: string;
+  /** Objects created/mutated/deleted by the transaction. */
+  changedObjects: SuiClientTypes.ChangedObject[];
+  /** Map of changed objectId → fully-qualified type. */
+  objectTypes: Record<string, string>;
+  /** Net coin balance deltas by address. */
+  balanceChanges: SuiClientTypes.BalanceChange[];
+  /** Net gas cost in MIST (computation + storage − rebate). */
+  gasUsed: number;
+}
+
+/** Builds a fresh Transaction from one or more thunks (awaiting async ones). */
+export async function buildTx(...thunks: TxThunk[]): Promise<Transaction> {
+  const tx = new Transaction();
+  for (const thunk of thunks) await thunk(tx);
+  return tx;
+}
+
+/** Normalizes the `{ $kind }` transaction-result envelope into an {@link ExecResult}. */
+export function toExecResult(res: SuiClientTypes.TransactionResult<FullInclude>): ExecResult {
+  if (res.$kind !== "Transaction") {
+    const failed = res.FailedTransaction;
+    const status = failed.effects?.status;
+    const err = status && !status.success ? JSON.stringify(status.error) : "unknown error";
+    throw new Error(`Transaction failed: ${err} (digest ${failed.digest})`);
+  }
+
+  const t = res.Transaction;
+  const effects = t.effects as SuiClientTypes.TransactionEffects;
+  if (!effects.status.success) {
+    throw new Error(`Transaction reverted: ${JSON.stringify(effects.status.error)} (digest ${t.digest})`);
+  }
+
+  return {
+    digest: t.digest,
+    changedObjects: effects.changedObjects,
+    objectTypes: (t.objectTypes as Record<string, string>) ?? {},
+    balanceChanges: (t.balanceChanges as SuiClientTypes.BalanceChange[]) ?? [],
+    gasUsed: netGas(effects.gasUsed),
+  };
+}
+
+/** Signs, executes, and waits for a transaction; returns changes, types, gas. */
+export async function signAndExecute(client: ClientWithCoreApi, signer: Signer, tx: Transaction): Promise<ExecResult> {
+  const res = await client.core.signAndExecuteTransaction({ transaction: tx, signer, include: FULL_INCLUDE });
+  const result = toExecResult(res);
+  await client.core.waitForTransaction({ digest: result.digest });
+  return result;
+}
+
+/** Convenience: build from thunks, then sign+execute in one call. */
+export async function execThunks(client: ClientWithCoreApi, signer: Signer, ...thunks: TxThunk[]): Promise<ExecResult> {
+  return signAndExecute(client, signer, await buildTx(...thunks));
+}
+
+// ── Object-change extractors ────────────────────────────────────────────────
+
+/** The package id from the (single) newly-published package. */
+export function publishedPackageId(r: ExecResult): string {
+  const pkg = r.changedObjects.find((c) => c.idOperation === "Created" && c.outputState === "PackageWrite");
+  if (!pkg) throw new Error("No published package found in object changes.");
+  return pkg.objectId;
+}
+
+/** All package ids newly published by the transaction (up to 5 per PTB). */
+export function allPublishedPackageIds(r: ExecResult): string[] {
+  return r.changedObjects
+    .filter((c) => c.idOperation === "Created" && c.outputState === "PackageWrite")
+    .map((c) => c.objectId);
+}
+
+/** The first newly-created object whose type contains `substr`. */
+export function createdByType(r: ExecResult, substr: string): string {
+  const id = maybeCreatedByType(r, substr);
+  if (!id) throw new Error(`No created object with type containing "${substr}" found in object changes.`);
+  return id;
+}
+
+/** Like {@link createdByType} but returns undefined instead of throwing. */
+export function maybeCreatedByType(r: ExecResult, substr: string): string | undefined {
+  for (const c of r.changedObjects) {
+    if (c.idOperation === "Created" && (r.objectTypes[c.objectId] ?? "").includes(substr)) return c.objectId;
+  }
+  return undefined;
+}
+
+/** The first newly-created object whose type is EXACTLY `type` (for non-generic types). */
+export function createdByExactType(r: ExecResult, type: string): string {
+  for (const c of r.changedObjects) {
+    if (c.idOperation === "Created" && r.objectTypes[c.objectId] === type) return c.objectId;
+  }
+  throw new Error(`No created object of exact type "${type}" found in object changes.`);
+}
+
+/** All newly-created objects whose type contains `substr`. */
+export function allCreatedByType(r: ExecResult, substr: string): { objectId: string; objectType: string }[] {
+  const out: { objectId: string; objectType: string }[] = [];
+  for (const c of r.changedObjects) {
+    const type = r.objectTypes[c.objectId] ?? "";
+    if (c.idOperation === "Created" && type.includes(substr)) out.push({ objectId: c.objectId, objectType: type });
+  }
+  return out;
+}
+
+/** The signed balance delta for `address` in `coinType`, or "0" if absent. */
+export function balanceDelta(r: ExecResult, address: string, coinType: string): string {
+  const change = r.balanceChanges.find((b) => b.address === address && b.coinType === coinType);
+  return change?.amount ?? "0";
+}
+
+function netGas(gasUsed: SuiClientTypes.GasCostSummary): number {
+  return Number(gasUsed.computationCost) + Number(gasUsed.storageCost) - Number(gasUsed.storageRebate);
+}

package/src/extensions/royalty-pool.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// First-party royalty-pool extension.
+//
+// A RoyaltyPool<Share, Currency> is an accumulator-based royalty-distribution pool
+// bound to a composition or recording. It is created via the work's admin-gated
+// `uid_mut(&AdminCap)` derived-object hook (`initialize_pool`), then shared
+// (`pool::share`). Because `initialize_pool` borrows the work `&mut` (and the cap
+// `&`) — not a shared on-chain input — it composes INSIDE the work's publish PTB:
+// run it after `createComposition`/`createRecording` and before `finalize*` (which
+// consumes the work into `share_object` and transfers the cap to the owner).
+//
+// Scope here is create + share only. Stake registration, funding (receive/redeem/
+// deposit), and claiming are later owner/holder actions, not part of publishing.
+
+import type { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
+import * as compositionRoyaltyPool from "../contracts/composition_royalty_pool/composition_royalty_pool.ts";
+import * as recordingRoyaltyPool from "../contracts/recording_royalty_pool/recording_royalty_pool.ts";
+import * as pool from "../contracts/royalty_pool/pool.ts";
+
+export interface AttachCompositionRoyaltyPoolParams {
+  /** The Composition — an in-PTB `createComposition` result, borrowed `&mut`. */
+  composition: TransactionObjectArgument;
+  /** The CompositionAdminCap, borrowed `&`. */
+  adminCap: TransactionObjectArgument;
+  /** The composition's share type (the pool's `Share` phantom = CompositionShare). */
+  compositionShareType: string;
+  /** Fully-qualified coin type the pool accumulates (the `Currency` phantom). */
+  currency: string;
+  compositionRoyaltyPoolPackageId: string;
+  royaltyPoolPackageId: string;
+}
+
+/** Creates a royalty pool for a composition and shares it, appending to `tx`. */
+export function attachCompositionRoyaltyPool(tx: Transaction, params: AttachCompositionRoyaltyPoolParams): void {
+  const created = tx.add(
+    compositionRoyaltyPool.initializePool({
+      package: params.compositionRoyaltyPoolPackageId,
+      typeArguments: [params.compositionShareType, params.currency],
+      arguments: [params.composition, params.adminCap],
+    }),
+  );
+  tx.add(
+    pool.share({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.compositionShareType, params.currency],
+      arguments: [created],
+    }),
+  );
+}
+
+export interface AttachRecordingRoyaltyPoolParams {
+  /** The Recording — an in-PTB `createRecording` result, borrowed `&mut`. */
+  recording: TransactionObjectArgument;
+  /** The RecordingAdminCap, borrowed `&`. */
+  adminCap: TransactionObjectArgument;
+  /** The recording's own share type (the pool's `Share` phantom = RecordingShare). */
+  recordingShareType: string;
+  /** The parent composition's share type (the recording's `CompositionShare` phantom). */
+  compositionShareType: string;
+  /** Fully-qualified coin type the pool accumulates (the `Currency` phantom). */
+  currency: string;
+  recordingRoyaltyPoolPackageId: string;
+  royaltyPoolPackageId: string;
+}
+
+/** Creates a royalty pool for a recording and shares it, appending to `tx`. */
+export function attachRecordingRoyaltyPool(tx: Transaction, params: AttachRecordingRoyaltyPoolParams): void {
+  const created = tx.add(
+    recordingRoyaltyPool.initializePool({
+      package: params.recordingRoyaltyPoolPackageId,
+      typeArguments: [params.recordingShareType, params.compositionShareType, params.currency],
+      arguments: [params.recording, params.adminCap],
+    }),
+  );
+  // The pool is RoyaltyPool<RecordingShare, Currency> — Share is the recording's own share type.
+  tx.add(
+    pool.share({
+      package: params.royaltyPoolPackageId,
+      typeArguments: [params.recordingShareType, params.currency],
+      arguments: [created],
+    }),
+  );
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./types.ts";
+export * from "./schemas.ts";
+export * from "./transactions.ts";
+export * from "./execute.ts";
+export * from "./extensions/royalty-pool.ts";
+export * from "./queries.ts";
+export * from "./parsers.ts";
+export * from "./view.ts";
+export * from "./client.ts";
+
+// Generated, ABI-bound bindings (BCS structs + type-safe Move calls).
+export * as contracts from "./contracts.ts";
+export * from "./cover.ts";
+export * from "./credits.ts";

package/src/internal.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Internal shared helpers (not exported from the package root).
+//
+// 1) Mappers from the generated BCS-parse output (snake_case, with @mysten/bcs
+//    conventions: enums as `{ $kind, [Variant]: payload }`, tuples as arrays,
+//    VecMap as `{ contents: [{ key, value }] }`, u64/u256 as strings, Address as
+//    hex) into the public camelCase domain types in `./types`. These are the
+//    single boundary between codegen output and the public API, so when the
+//    generated shapes change, type errors surface here.
+//
+// 2) PTB building blocks — the `0x1::option` move-call targets used when a
+//    generated call needs an `Option` argument built inline. Consumed by
+//    `./cover` and `./credits`; `./transactions` does not use them.
+
+import type {
+  BPS,
+  Composition,
+  Recording,
+  Release as ReleaseType,
+  Track,
+  TrackState,
+} from "./types.ts";
+
+// === PTB building blocks ===
+
+/** `0x1::option::none` / `0x1::option::some` moveCall targets. */
+export const OPTION_NONE = "0x1::option::none";
+export const OPTION_SOME = "0x1::option::some";
+
+// === Mappers ===
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type Parsed = any;
+
+// === Primitives ===
+
+/** `BPS` is a Move tuple struct `(u16)`, parsed as `[number]`. */
+export function mapBps(d: Parsed): BPS {
+  return { value: Number(Array.isArray(d) ? d[0] : d) };
+}
+
+/** Lifecycle state enum (`Initialized | Published(u64)`). */
+export function mapState(
+  d: Parsed,
+): { type: "Initialized" } | { type: "Published"; timestampMs: number } {
+  if (d?.$kind === "Published") return { type: "Published", timestampMs: Number(d.Published) };
+  return { type: "Initialized" };
+}
+
+// === Objects ===
+
+export function mapComposition(id: string, d: Parsed): Composition {
+  return {
+    id,
+    state: mapState(d.state),
+    title: d.title,
+    royaltyRate: mapBps(d.royalty_rate),
+  };
+}
+
+export function mapRecording(id: string, d: Parsed): Recording {
+  return {
+    id,
+    state: mapState(d.state),
+  };
+}
+
+export function mapTrack(d: Parsed): Track {
+  return {
+    state: (d.state?.$kind ?? "Unassigned") as TrackState,
+    recordingId: d.recording_id,
+    splitBps: mapBps(d.split_bps),
+  };
+}
+
+export function mapRelease(id: string, d: Parsed): ReleaseType {
+  return {
+    id,
+    state: mapState(d.state),
+    title: d.title,
+    tracks: (d.tracks ?? []).map(mapTrack),
+  };
+}

package/src/parsers.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Event parsers. The BCS layouts come from the codegen-generated structs (so
+// they track the on-chain ABI automatically); these functions parse raw event
+// bytes and map them to the public camelCase event types.
+
+import {
+  CompositionPublishedEvent as CompositionPublishedEventBcs,
+  CompositionRoyaltySetEvent as CompositionRoyaltySetEventBcs,
+} from "./contracts/miso/composition.ts";
+import { RecordingPublishedEvent as RecordingPublishedEventBcs } from "./contracts/miso/recording.ts";
+import { ReleasePublishedEvent as ReleasePublishedEventBcs } from "./contracts/miso/release.ts";
+import {
+  DealCreatedEvent as DealCreatedEventBcs,
+  DealAcceptedEvent as DealAcceptedEventBcs,
+  DealRejectedEvent as DealRejectedEventBcs,
+} from "./contracts/miso/deal.ts";
+import type {
+  CompositionPublishedEvent,
+  CompositionRoyaltySetEvent,
+  RecordingPublishedEvent,
+  ReleasePublishedEvent,
+  DealCreatedEvent,
+  DealAcceptedEvent,
+  DealRejectedEvent,
+} from "./types.ts";
+
+// === Composition ===
+
+export function parseCompositionPublishedEvent(bytes: Uint8Array): CompositionPublishedEvent {
+  const e = CompositionPublishedEventBcs.parse(bytes);
+  return { compositionId: e.composition_id };
+}
+
+export function parseCompositionRoyaltySetEvent(bytes: Uint8Array): CompositionRoyaltySetEvent {
+  const e = CompositionRoyaltySetEventBcs.parse(bytes);
+  return { royaltyRateBps: e.royalty_rate_bps };
+}
+
+// === Recording ===
+
+export function parseRecordingPublishedEvent(bytes: Uint8Array): RecordingPublishedEvent {
+  const e = RecordingPublishedEventBcs.parse(bytes);
+  return { recordingId: e.recording_id };
+}
+
+// === Release ===
+
+export function parseReleasePublishedEvent(bytes: Uint8Array): ReleasePublishedEvent {
+  const e = ReleasePublishedEventBcs.parse(bytes);
+  return { releaseId: e.release_id };
+}
+
+// === Deal ===
+
+export function parseDealCreatedEvent(bytes: Uint8Array): DealCreatedEvent {
+  const e = DealCreatedEventBcs.parse(bytes);
+  return {
+    dealId: e.deal_id,
+    releaseId: e.release_id,
+    trackSplitBps: { value: e.track_split_bps_value },
+  };
+}
+
+export function parseDealAcceptedEvent(bytes: Uint8Array): DealAcceptedEvent {
+  const e = DealAcceptedEventBcs.parse(bytes);
+  return {
+    dealId: e.deal_id,
+    releaseId: e.release_id,
+  };
+}
+
+export function parseDealRejectedEvent(bytes: Uint8Array): DealRejectedEvent {
+  const e = DealRejectedEventBcs.parse(bytes);
+  return {
+    dealId: e.deal_id,
+    releaseId: e.release_id,
+  };
+}