@misofm/musicos 0.1.0

package/src/contracts/utils/index.ts

@@ -0,0 +1,428 @@
+
+import {
+	bcs,
+	type BcsType,
+	type TypeTag,
+	TypeTagSerializer,
+	BcsStruct,
+	BcsEnum,
+	BcsTuple,
+} from '@mysten/sui/bcs';
+import { normalizeStructTag, normalizeSuiAddress } from '@mysten/sui/utils';
+import {
+	type TransactionArgument,
+	type TransactionObjectArgument,
+	isArgument,
+} from '@mysten/sui/transactions';
+import { type ClientWithCoreApi, type SuiClientTypes } from '@mysten/sui/client';
+
+const MOVE_STDLIB_ADDRESS = normalizeSuiAddress('0x1');
+const SUI_FRAMEWORK_ADDRESS = normalizeSuiAddress('0x2');
+
+export type RawTransactionArgument<T> = T | TransactionArgument;
+
+export type GetOptions<Include extends Omit<SuiClientTypes.ObjectInclude, 'content'> = {}> =
+	SuiClientTypes.GetObjectOptions<Include> & { client: ClientWithCoreApi };
+
+export type GetManyOptions<Include extends Omit<SuiClientTypes.ObjectInclude, 'content'> = {}> =
+	SuiClientTypes.GetObjectsOptions<Include> & { client: ClientWithCoreApi };
+
+export function getPureBcsSchema(typeTag: string | TypeTag): BcsType<any> | null {
+	const parsedTag = typeof typeTag === 'string' ? TypeTagSerializer.parseFromStr(typeTag) : typeTag;
+
+	if ('u8' in parsedTag) {
+		return bcs.U8;
+	} else if ('u16' in parsedTag) {
+		return bcs.U16;
+	} else if ('u32' in parsedTag) {
+		return bcs.U32;
+	} else if ('u64' in parsedTag) {
+		return bcs.U64;
+	} else if ('u128' in parsedTag) {
+		return bcs.U128;
+	} else if ('u256' in parsedTag) {
+		return bcs.U256;
+	} else if ('address' in parsedTag) {
+		return bcs.Address;
+	} else if ('bool' in parsedTag) {
+		return bcs.Bool;
+	} else if ('vector' in parsedTag) {
+		const type = getPureBcsSchema(parsedTag.vector);
+		return type ? bcs.vector(type) : null;
+	} else if ('struct' in parsedTag) {
+		const structTag = parsedTag.struct;
+		const pkg = normalizeSuiAddress(structTag.address);
+
+		if (pkg === MOVE_STDLIB_ADDRESS) {
+			if (
+				(structTag.module === 'ascii' || structTag.module === 'string') &&
+				structTag.name === 'String'
+			) {
+				return bcs.String;
+			}
+
+			if (structTag.module === 'option' && structTag.name === 'Option') {
+				const inner = structTag.typeParams[0];
+				const type = inner ? getPureBcsSchema(inner) : null;
+				return type ? bcs.option(type) : null;
+			}
+		}
+
+		if (
+			pkg === SUI_FRAMEWORK_ADDRESS &&
+			structTag.module === 'object' &&
+			(structTag.name === 'ID' || structTag.name === 'UID')
+		) {
+			return bcs.Address;
+		}
+	}
+
+	return null;
+}
+
+export function normalizeMoveArguments(
+	args: unknown[] | object,
+	argTypes: readonly (string | null)[],
+	parameterNames?: string[],
+) {
+	const argLen = Array.isArray(args) ? args.length : Object.keys(args).length;
+	if (parameterNames && argLen !== parameterNames.length) {
+		throw new Error(
+			`Invalid number of arguments, expected ${parameterNames.length}, got ${argLen}`,
+		);
+	}
+
+	const normalizedArgs: TransactionArgument[] = [];
+
+	let index = 0;
+	for (const argType of argTypes) {
+		if (argType === '0x2::clock::Clock') {
+			normalizedArgs.push((tx) => tx.object.clock());
+			continue;
+		}
+
+		if (argType === '0x2::random::Random') {
+			normalizedArgs.push((tx) => tx.object.random());
+			continue;
+		}
+
+		if (argType === '0x2::deny_list::DenyList') {
+			normalizedArgs.push((tx) => tx.object.denyList());
+			continue;
+		}
+
+		if (argType === '0x2::accumulator::AccumulatorRoot') {
+			// Chain-wide shared singleton at a fixed address (SUI_ACCUMULATOR_ROOT_OBJECT_ID).
+			normalizedArgs.push((tx) => tx.object('0xacc'));
+			continue;
+		}
+
+		if (argType === '0x3::sui_system::SuiSystemState') {
+			normalizedArgs.push((tx) => tx.object.system());
+			continue;
+		}
+
+		let arg;
+		if (Array.isArray(args)) {
+			if (index >= args.length) {
+				throw new Error(
+					`Invalid number of arguments, expected at least ${index + 1}, got ${args.length}`,
+				);
+			}
+			arg = args[index];
+		} else {
+			if (!parameterNames) {
+				throw new Error(`Expected arguments to be passed as an array`);
+			}
+			const name = parameterNames[index];
+			arg =
+				name !== undefined && Object.prototype.hasOwnProperty.call(args, name)
+					? args[name as keyof typeof args]
+					: undefined;
+
+			if (arg === undefined) {
+				throw new Error(`Parameter ${name} is required`);
+			}
+		}
+
+		index += 1;
+
+		if (typeof arg === 'function' || isArgument(arg)) {
+			normalizedArgs.push(arg as TransactionArgument);
+			continue;
+		}
+
+		const bcsType = argType === null ? null : getPureBcsSchema(argType);
+
+		if (bcsType) {
+			const bytes = bcsType.serialize(arg as never);
+			normalizedArgs.push((tx) => tx.pure(bytes));
+			continue;
+		}
+
+		if (typeof arg === 'string') {
+			normalizedArgs.push((tx) => tx.object(arg));
+			continue;
+		}
+
+		throw new Error(`Invalid argument ${stringify(arg)} for type ${argType}`);
+	}
+
+	return normalizedArgs;
+}
+
+/* -------------------------- Config-mapped arguments -------------------------- */
+
+/** Context passed to config resolver functions. */
+export interface ConfigResolverContext {
+	/**
+	 * The matched parameter's own instantiated type arguments (not the whole function's type
+	 * argument tuple). Concrete instantiations are canonical type tags; generic positions pass
+	 * the caller's `typeArguments` strings through as provided.
+	 */
+	typeArguments: string[];
+	/** The package address the generated call will be sent to. */
+	packageAddress: string;
+	/** The Move module of the generated call. */
+	moduleName: string;
+	/** The Move function of the generated call. */
+	functionName: string;
+	/** The Move name of the matched parameter, when the summary includes parameter names. */
+	parameterName?: string;
+	/** The matched parameter's position in the generated function's arguments. */
+	parameterIndex: number;
+}
+
+/**
+ * A non-callback transaction argument in a generated config object, used for keys whose matched
+ * parameter can't be supplied as an object id string.
+ */
+export type ConfigObjectValue = Exclude<TransactionObjectArgument, (...args: never[]) => unknown>;
+
+/**
+ * A plain value in a generated config object: an object id or a non-callback transaction
+ * argument. Keys that can resolve multiple bindings are typed as resolver functions instead.
+ */
+export type ConfigValue = string | ConfigObjectValue;
+
+/* -------------------------- Move type tags -------------------------- */
+
+/** A type argument: a type tag string, or a BCS type whose name is a Move type. */
+export type TypeArgument = string | BcsType<any>;
+
+export interface TypeTagOptions {
+	package?: string;
+	typeArguments?: readonly TypeArgument[];
+}
+
+/**
+ * `typeArguments` is required when the type's name contains unfilled
+ * `phantom X` parameters (at any depth). Everything else — argument arity,
+ * position contents, and tag validity — is validated at runtime.
+ */
+type TypeTagParams<Name extends string> = Name extends `${string}phantom ${string}`
+	? [options: TypeTagOptions & { typeArguments: readonly TypeArgument[] }]
+	: [options?: TypeTagOptions];
+
+type ResolveTypeTagOptions<Name extends string> = { client: ClientWithCoreApi } & (
+	Name extends `${string}phantom ${string}`
+		? TypeTagOptions & { typeArguments: readonly TypeArgument[] }
+		: TypeTagOptions
+);
+
+const HAS_PHANTOM_REGEX = /phantom [A-Za-z_$][A-Za-z0-9_$]*/;
+
+function splitTopLevelTypeArgs(inner: string): string[] {
+	const parts: string[] = [];
+	let depth = 0;
+	let current = '';
+	for (const char of inner) {
+		if (char === ',' && depth === 0) {
+			parts.push(current.trim());
+			current = '';
+			continue;
+		}
+		if (char === '<') depth++;
+		if (char === '>') depth--;
+		current += char;
+	}
+	if (current) parts.push(current.trim());
+	return parts;
+}
+
+function buildTypeTag(name: string, options: TypeTagOptions | undefined): string {
+	const lt = name.indexOf('<');
+	const base = lt === -1 ? name : name.slice(0, lt);
+
+	if (base.split('::').length !== 3) {
+		throw new Error(`${name} is not a top-level Move type`);
+	}
+
+	let result = name;
+
+	if (options?.typeArguments) {
+		const baked = lt === -1 ? [] : splitTopLevelTypeArgs(name.slice(lt + 1, -1));
+		const supplied = options.typeArguments.map((arg) => {
+			if (typeof arg === 'string') {
+				return arg;
+			}
+			if (arg && typeof arg.serialize === 'function' && typeof arg.name === 'string') {
+				return arg.name;
+			}
+			throw new Error(`Invalid type argument ${stringify(arg)}`);
+		});
+
+		if (supplied.length !== baked.length) {
+			throw new Error(
+				`Expected ${baked.length} type arguments for ${base}, got ${supplied.length}`,
+			);
+		}
+
+		result = supplied.length === 0 ? base : `${base}<${supplied.join(', ')}>`;
+	}
+
+	if (HAS_PHANTOM_REGEX.test(result)) {
+		throw new Error(
+			options?.typeArguments
+				? `A type argument contains an unfilled phantom parameter in ${result}`
+				: `Missing type arguments for ${result}`,
+		);
+	}
+
+	if (options?.package) {
+		const [, ...rest] = result.split('::');
+		result = [options.package, ...rest].join('::');
+	}
+
+	// fully validate address-only tags (MVR names can't be parsed as type tags)
+	if (!HAS_PHANTOM_REGEX.test(result) && !/[@/]/.test(result)) {
+		TypeTagSerializer.parseFromStr(result);
+	}
+
+	return result;
+}
+
+async function resolveBuiltTypeTag(
+	name: string,
+	options: { client: ClientWithCoreApi } & TypeTagOptions,
+): Promise<string> {
+	const { client, ...rest } = options;
+	const { type } = await client.core.mvr.resolveType({
+		type: buildTypeTag(name, rest),
+	});
+	return normalizeStructTag(type);
+}
+
+export class MoveStruct<
+	T extends Record<string, BcsType<any>>,
+	const Name extends string = string,
+> extends BcsStruct<T, Name> {
+	/**
+	 * Build the type tag for this struct.
+	 *
+	 * `typeArguments` is the full positional list, in Move declaration order, and
+	 * is required when the struct has unfilled phantom parameters. The result may
+	 * contain MVR names: those are valid in transaction `typeArguments`, but for
+	 * queries or comparisons against on-chain data use `resolveTypeTag` instead.
+	 */
+	typeTag(...args: TypeTagParams<Name>): string {
+		return buildTypeTag(this.name, args[0] as TypeTagOptions | undefined);
+	}
+
+	/**
+	 * Build the type tag for this struct, then resolve any MVR names through the
+	 * client (using its configured overrides and the MVR API) and return the
+	 * normalized, address-only form suitable for queries and comparisons against
+	 * on-chain data.
+	 */
+	async resolveTypeTag(options: ResolveTypeTagOptions<Name>): Promise<string> {
+		return resolveBuiltTypeTag(this.name, options as { client: ClientWithCoreApi } & TypeTagOptions);
+	}
+
+	async get<Include extends Omit<SuiClientTypes.ObjectInclude, 'content' | 'json'> = {}>({
+		objectId,
+		...options
+	}: GetOptions<Include>): Promise<
+		SuiClientTypes.Object<Include & { content: true, json: true }> & { json: BcsStruct<T>['$inferType'] }
+	> {
+		const [res] = await this.getMany<Include>({
+			...options,
+			objectIds: [objectId],
+		});
+
+		if (!res) {
+			throw new Error(`No object found for id ${objectId}`);
+		}
+
+		return res;
+	}
+
+	async getMany<Include extends Omit<SuiClientTypes.ObjectInclude, 'content' | 'json'> = {}>({
+		client,
+		...options
+	}: GetManyOptions<Include>): Promise<
+		Array<SuiClientTypes.Object<Include & { content: true, json: true }> & { json: BcsStruct<T>['$inferType'] }>
+	> {
+		const response = (await client.core.getObjects({
+			...options,
+			include: {
+				...options.include,
+				content: true,
+			},
+		})) as SuiClientTypes.GetObjectsResponse<Include & { content: true }>;
+
+		return response.objects.map((obj) => {
+			if (obj instanceof Error) {
+				throw obj;
+			}
+
+			return {
+				...obj,
+				json: this.parse(obj.content),
+			};
+		});
+	}
+}
+
+export class MoveEnum<
+	T extends Record<string, BcsType<any> | null>,
+	const Name extends string,
+> extends BcsEnum<T, Name> {
+	/** Build the type tag for this enum. See `MoveStruct.typeTag` for semantics. */
+	typeTag(...args: TypeTagParams<Name>): string {
+		return buildTypeTag(this.name, args[0] as TypeTagOptions | undefined);
+	}
+
+	/** Build and resolve the type tag for this enum. See `MoveStruct.resolveTypeTag`. */
+	async resolveTypeTag(options: ResolveTypeTagOptions<Name>): Promise<string> {
+		return resolveBuiltTypeTag(this.name, options as { client: ClientWithCoreApi } & TypeTagOptions);
+	}
+}
+
+export class MoveTuple<
+	const T extends readonly BcsType<any>[],
+	const Name extends string,
+> extends BcsTuple<T, Name> {
+	/** Build the type tag for this struct. See `MoveStruct.typeTag` for semantics. */
+	typeTag(...args: TypeTagParams<Name>): string {
+		return buildTypeTag(this.name, args[0] as TypeTagOptions | undefined);
+	}
+
+	/** Build and resolve the type tag for this struct. See `MoveStruct.resolveTypeTag`. */
+	async resolveTypeTag(options: ResolveTypeTagOptions<Name>): Promise<string> {
+		return resolveBuiltTypeTag(this.name, options as { client: ClientWithCoreApi } & TypeTagOptions);
+	}
+}
+
+function stringify(val: unknown) {
+	if (typeof val === 'object') {
+		return JSON.stringify(val, (_key, value) =>
+			typeof value === 'bigint' ? value.toString() : value,
+		);
+	}
+	if (typeof val === 'bigint') {
+		return val.toString();
+	}
+
+	return val;
+}

package/src/contracts.ts

@@ -0,0 +1,29 @@
+// 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.
+
+// Every package here is generated from the current first-party Move source. The
+// generated default `@local-pkg/*` identities are source labels only: callers
+// must inject exact published addresses through `MisoDeployment` before building
+// a transaction. Do not use a historic package ID as a substitute for a fresh
+// deployment.
+
+type PublicModule<M extends object, K extends readonly (keyof M)[]> = Omit<M, K[number]>;
+function withoutUnsafeCalls<M extends object, K extends readonly (keyof M)[]>(
+  module: M,
+  keys: K,
+): PublicModule<M, K> {
+  return Object.fromEntries(Object.entries(module).filter(([key]) => !keys.includes(key as keyof M))) as PublicModule<M, K>;
+}
+
+import * as rawComposition from "./contracts/musicos/composition.ts";
+import * as rawRecording from "./contracts/musicos/recording.ts";
+import * as rawRelease from "./contracts/musicos/release.ts";
+
+// Object model core (BCS codecs remain available; PTB-inaccessible references do not).
+export const composition = withoutUnsafeCalls(rawComposition, ["title", "uid", "uidMut"] as const);
+export const recording = withoutUnsafeCalls(rawRecording, ["uid", "uidMut"] as const);
+export const release = withoutUnsafeCalls(rawRelease, ["title", "tracks", "uid", "uidMut"] as const);
+export * as track from "./contracts/musicos/track.ts";

package/src/deployments.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+
+/** Sui networks for which this SDK may bundle a verified deployment. */
+export type MisoNetwork = "mainnet" | "testnet";
+
+/**
+ * The single independently published package required by this SDK surface:
+ * the `musicos` object-model package (modules composition, recording,
+ * release, track).
+ *
+ * This name is a stable deployment-manifest key, not a Move module name. Its
+ * value is never inferred from a source label or a previous publish.
+ */
+const CANONICAL_MISO_PACKAGE_NAMES = ["musicos"] as const;
+
+/** Public immutable copy; validation always uses the private canonical tuple. */
+export const MISO_PACKAGE_NAMES = Object.freeze([
+  ...CANONICAL_MISO_PACKAGE_NAMES,
+]) as readonly [...typeof CANONICAL_MISO_PACKAGE_NAMES];
+
+export type MisoPackageName = (typeof CANONICAL_MISO_PACKAGE_NAMES)[number];
+
+/**
+ * Exact package address from one compatible publish.
+ *
+ * A complete manifest is intentional: a caller cannot accidentally combine
+ * generated bindings for a fresh ABI with a stale package ID. Fill this only
+ * from the verified immutable `admin-cli` publish record after the
+ * dependency-ordered release is complete.
+ */
+export type MisoDeployment = Readonly<Record<MisoPackageName, string>>;
+
+/** A minimal core-only deployment, retained for callers that use only `miso()`. */
+export interface MisoProtocolDeployment {
+  /** The published `musicos` package used for calls, types, and derived IDs. */
+  readonly packageId: string;
+}
+
+/** Validate and freeze a core-only package binding at a client boundary. */
+export function normalizeMisoProtocolDeployment(
+  deployment: unknown,
+): MisoProtocolDeployment {
+  if (!deployment || typeof deployment !== "object" || Array.isArray(deployment)) {
+    throw new Error("@misofm/musicos: core deployment must be an object with a normalized Miso package ID.");
+  }
+  const packageId = (deployment as { packageId?: unknown }).packageId;
+  if (typeof packageId !== "string") {
+    throw new Error("@misofm/musicos: core deployment is missing a Miso package ID.");
+  }
+  let normalized: string;
+  try {
+    normalized = normalizeSuiAddress(packageId);
+  } catch {
+    throw new Error("@misofm/musicos: core deployment package ID is not a valid Sui address.");
+  }
+  if (packageId !== normalized) {
+    throw new Error(
+      `@misofm/musicos: core deployment package ID must be normalized (${normalized}).`,
+    );
+  }
+  return Object.freeze({ packageId });
+}
+
+/** Verified immutable deployments bundled with this SDK release. */
+export const MISO_DEPLOYMENTS = Object.freeze({
+  testnet: Object.freeze({
+    musicos: "0x95bb43d650fe582caba27d4ead2c3f9939c38125943f8716c5baf5af528bc671",
+  } as const),
+} as const) satisfies Partial<
+  Record<MisoNetwork, MisoDeployment>
+>;
+
+/**
+ * @deprecated Use `MISO_DEPLOYMENTS`. This alias preserves source compatibility
+ * for callers that still use the former protocol-only constant name.
+ */
+export const MISO_PROTOCOL_DEPLOYMENTS = MISO_DEPLOYMENTS;
+
+/** Resolve a verified full manifest, failing closed for unbundled networks. */
+export function getMisoDeployment(network: string): MisoDeployment {
+  const deployment = (
+    MISO_DEPLOYMENTS as Partial<Record<string, MisoDeployment>>
+  )[network];
+  if (!deployment) {
+    throw new Error(
+      `@misofm/musicos: no verified Miso deployment is bundled for network "${network}". ` +
+        "Inject the exact post-publish manifest or pass an explicit deployment; historic package IDs are rejected.",
+    );
+  }
+  return normalizeMisoDeployment(deployment);
+}
+
+/** Extract the core package identity from a complete deployment manifest. */
+export function protocolDeployment(
+  deployment: MisoDeployment,
+): MisoProtocolDeployment {
+  return normalizeMisoProtocolDeployment({ packageId: normalizeMisoDeployment(deployment).musicos });
+}
+
+/** Resolve the core package only, preserving the established `miso()` default API. */
+export function getMisoProtocolDeployment(
+  network: string,
+): MisoProtocolDeployment {
+  return protocolDeployment(getMisoDeployment(network));
+}
+
+/**
+ * Validates an explicit manifest before any Move target is constructed. This is
+ * useful at configuration boundaries such as environment-file loading.
+ */
+export function assertMisoDeployment(
+  deployment: unknown,
+): asserts deployment is MisoDeployment {
+  if (!deployment || typeof deployment !== "object" || Array.isArray(deployment)) {
+    throw new Error(
+      `@misofm/musicos: deployment must be an object with exactly ${CANONICAL_MISO_PACKAGE_NAMES.length} Miso package IDs.`,
+    );
+  }
+  const entries = deployment as Record<string, unknown>;
+  const keys = Object.keys(entries);
+  const unexpected = keys.filter((key) => !CANONICAL_MISO_PACKAGE_NAMES.includes(key as MisoPackageName));
+  if (unexpected.length > 0 || keys.length !== CANONICAL_MISO_PACKAGE_NAMES.length) {
+    throw new Error(
+      `@misofm/musicos: deployment must contain exactly these package IDs: ${CANONICAL_MISO_PACKAGE_NAMES.join(", ")}.`,
+    );
+  }
+  const seenPackageIds = new Set<string>();
+  for (const name of CANONICAL_MISO_PACKAGE_NAMES) {
+    const packageId = entries[name];
+    if (typeof packageId !== "string") {
+      throw new Error(
+        `@misofm/musicos: deployment is missing package ID for "${name}". ` +
+          "Use a complete manifest from the fresh verified immutable admin-cli publish record.",
+      );
+    }
+    let normalized: string;
+    try {
+      normalized = normalizeSuiAddress(packageId);
+    } catch {
+      throw new Error(`@misofm/musicos: deployment package ID for "${name}" is not a valid Sui address.`);
+    }
+    if (packageId !== normalized) {
+      throw new Error(
+        `@misofm/musicos: deployment package ID for "${name}" must be normalized (${normalized}).`,
+      );
+    }
+    if (seenPackageIds.has(packageId)) {
+      throw new Error(
+        `@misofm/musicos: deployment package ID for "${name}" duplicates another package. ` +
+          "A publish manifest must bind every package to its own address.",
+      );
+    }
+    seenPackageIds.add(packageId);
+  }
+}
+
+/** Validate and snapshot an untrusted manifest so later caller mutation is inert. */
+export function normalizeMisoDeployment(deployment: unknown): MisoDeployment {
+  assertMisoDeployment(deployment);
+  return Object.freeze(
+    Object.fromEntries(CANONICAL_MISO_PACKAGE_NAMES.map((name) => [name, deployment[name]])),
+  ) as MisoDeployment;
+}

package/src/events.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * BCS decoders for object-model execution events outside the legacy core
+ * convenience parsers. Each decoder preserves the generated Move field names
+ * and nested layouts exactly, which is the safe indexer boundary.
+ */
+
+import * as release from "./contracts/musicos/release.ts";
+import type { BcsParser } from "./queries.ts";
+
+/** Decode raw event BCS with the corresponding generated codec. */
+export function decodeEvent<T>(codec: BcsParser<T>, bytes: Uint8Array): T {
+  return codec.parse(bytes);
+}
+
+function decoder<T>(codec: BcsParser<T>) {
+  return (bytes: Uint8Array): T => decodeEvent(codec, bytes);
+}
+
+/**
+ * Event decoder registry grouped by package responsibility. Core publication
+ * events retain camel-case wrappers in `parsers.ts`.
+ */
+export const eventParsers = {
+  core: {
+    releaseRegistryCreated: decoder(release.ReleaseRegistryCreatedEvent),
+  },
+} as const;