@misofm/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,10 @@
 # @misofm/sdk
 
 Typed reads and transaction builders for the **Miso platform layer** on Sui: the
-record production line and the sale of copies off it, plus the opinionated
-publish flow (share economics, minato dispersal, whole-graph orchestration)
-built on top of `@misonetwork/sdk`'s bare protocol primitives.
+record production line and the sale of copies off it, the first-party protocol
+extensions (credits, cover art, royalty pools), and the opinionated publish flow
+(share economics, minato dispersal, whole-graph orchestration) built on top of
+`@misonetwork/sdk`'s bare protocol primitives.
 
 ## The split
 
@@ -13,7 +14,7 @@ holding:
 | Scope | Layer | Owns |
 | --- | --- | --- |
 | `@misonetwork/*` | **Protocol** | Composition, Recording, Release as bare primitives — mint a work, don't disperse/publish/transfer it. The permissionless layer anyone can build on |
-| `@misofm/*` | **Platform** | Pressing, Listing, Record (how Miso sells copies of a release) — plus the opinionated finish for publishing works: disperse share supply via minato, publish (share), transfer the admin cap, provision share currencies, and orchestrate a whole release graph in one PTB |
+| `@misofm/*` | **Platform** | Pressing, Listing, Record (how Miso sells copies of a release) — the first-party extensions (credits, cover art, royalty pools) — plus the opinionated finish for publishing works: disperse share supply via minato, publish (share), transfer the admin cap, provision share currencies, and orchestrate a whole release graph in one PTB |
 
 A release is protocol. Pressing a record off that release and selling it is
 platform. So is deciding *what to do* with a freshly-minted work's share
@@ -21,6 +22,15 @@ supply — the protocol only knows how to mint one. Keeping the boundary at the
 package line is what stops the open protocol from quietly growing a
 storefront (or an opinion about tokenomics).
 
+**Extensions are platform too.** An extension is not part of what a Composition
+or Recording *is* — it is a choice about how to describe one: which credit roles
+exist and what they are called, what counts as a cover, whether royalties
+accumulate in a pool. The protocol offers a cap-gated `&mut UID` hook and takes
+no position on what hangs off it; every module that *does* take a position is
+business logic, and ships from here. (They lived in `@misonetwork/sdk` through
+its 0.2.x line; `@misonetwork/sdk` 0.3.0 dropped them and `@misofm/sdk` 0.2.0
+picked them up, with signatures unchanged — only the import specifier moves.)
+
 This package depends on `@misonetwork/sdk` and imports its bare
 `createComposition`/`createRecording` primitives, composing them with its own
 minato-dispersal and share-currency logic in the same PTB — the
@@ -192,18 +202,130 @@ non-idempotent PTB through a `ParallelTransactionExecutor` exactly once (no
 auto-retry) — it's what the batched provisioning above builds on, layered over
 `@misonetwork/sdk`'s transport-agnostic `buildTx`/`toExecResult`.
 
+## Extensions
+
+An extension attaches data to a protocol work through that work's cap-gated
+`uid_mut` hook. The work stays a protocol object; the opinion hanging off it is
+ours.
+
+### Credits (`credits.ts`)
+
+Contributor credits pair a party with a display name and one or more
+domain-specific roles, attached to a work as a dynamic field and gated by the
+work's admin cap. Three role vocabularies:
+
+- **Composition** (writing, 1–5 roles, no level): `Adapter`, `Arranger`, `Composer`, `Lyricist`, `Songwriter`, `Translator`, or `{ type: "Custom", name }`.
+- **Recording** (production/performance, 1–10 roles): 28 leveled roles (`Producer`, `Vocalist`, `Engineer`, …) each with an optional seniority `level` (`Lead`, `Featured`, `Executive`, …), plus `{ type: "Instrumentalist", instrument, level? }`, `{ type: "Custom", name, level? }`, and the unleveled `ArtistsAndRepertoire` / `Copyist`.
+- **Release** (top-line billing, exactly one role): `"Primary"` or `"Featured"`.
+
+Writers validate client-side, mirroring the Move aborts: display name
+non-empty and ≤200 UTF-8 bytes; role counts within the caps above; no
+duplicate roles.
+
+```ts
+import {
+  attachCompositionCredit, attachRecordingCredit, addReleaseCredit,
+  addRecordingPrimaryArtist, addRecordingFeaturedArtist,
+  getCompositionCredits, getRecordingCredits, getReleaseCredits,
+} from "@misofm/sdk";
+
+const thunk = attachRecordingCredit({
+  recordingId: "0x...",
+  recordingAdminCapId: "0x...",
+  partyId: "0x...",
+  displayName: "Jane Doe",
+  roles: [{ type: "Vocalist", level: "Lead" }, { type: "Instrumentalist", instrument: "Guitar" }],
+  recordingShareType: "0x...::share::Share",
+  compositionShareType: "0x...::share::Share",
+  recordingCreditsPackageId: "0x...",
+  misoCreditPackageId: "0x...",
+});
+
+// Designate an already-credited party (same params minus displayName/roles/misoCreditPackageId):
+addRecordingPrimaryArtist({ recordingId, recordingAdminCapId, partyId, recordingShareType, compositionShareType, recordingCreditsPackageId });
+
+// Reads return null when no credits field is attached.
+const credits = await getCompositionCredits(client, compositionId, compositionCreditsPackageId);
+// CreditView[]: { partyId, displayName, roles: string[] } — e.g. "Producer (Lead)", "Instrumentalist: Guitar"
+const rc = await getRecordingCredits(client, recordingId, recordingCreditsPackageId);
+// { credits: CreditView[], primaryArtistIds: string[], featuredArtistIds: string[] }
+```
+
+`attachCompositionCredit` takes `compositionId`/`compositionAdminCapId`/`compositionShareType`/`compositionCreditsPackageId`;
+`addReleaseCredit` takes `releaseId`/`releaseAdminCapId` and a single `role`.
+
+A recording is `Recording<RecordingShare, CompositionShare>` — the recording's
+OWN share type comes first, its parent composition's second. The recording
+writers take both as separate named params for that reason; passing them in the
+wrong order still typechecks (both are `string`) and resolves to the wrong
+on-chain type.
+
+### Cover art (`cover.ts`)
+
+A release's cover is a Walrus blob referenced on-chain via `ori::WalrusData`,
+attached under the `release_cover_art` extension:
+
+```ts
+import { setReleaseCover, getReleaseCover } from "@misofm/sdk";
+
+const thunk = setReleaseCover({
+  releaseId: "0x...",
+  releaseAdminCapId: "0x...",
+  stillBlobId: "987654321",   // Walrus blob id as u256 (decimal string or bigint)
+  animatedBlobId: null,        // optional animated cover
+  coverArtPackageId: "0x...",
+  releaseCoverArtPackageId: "0x...",
+  oriPackageId: "0x...",
+});
+
+const cover = await getReleaseCover(client, releaseId, releaseCoverArtPackageId);
+// ReleaseCoverView | null: { still, animated } as normalized Walrus refs
+// ({ kind: "blob", blobId } | { kind: "quiltPatch", quiltId, version, startIndex, endIndex })
+```
+
+### Royalty pools (`extensions/royalty-pool.ts`)
+
+`attachCompositionRoyaltyPool(tx, params)` / `attachRecordingRoyaltyPool(tx, params)`
+create and share a `RoyaltyPool<Share, Currency>` for a work inside its publish
+PTB — after `@misonetwork/sdk`'s `createComposition`/`createRecording`, before
+this package's opinionated finish. `publishReleaseGraph` accepts them as
+`royaltyPool` nodes and does the sequencing for you.
+
+### Extension types
+
+```ts
+import type {
+  CreditView, RecordingCreditsView,
+  CompositionRole, RecordingRole, RecordingRoleLevel, RecordingLeveledRoleType,
+  ReleaseRole,
+  ReleaseCoverView, CoverImageRef,
+} from "@misofm/sdk";
+```
+
+`RecordingLeveledRoleType` is the union of the 28 recording role base names that
+carry an optional `RecordingRoleLevel` (`Producer`, `Vocalist`, `Engineer`,
+`Conductor`, …) — the leveled arm of `RecordingRole`. The other arms
+(`Instrumentalist`, `Custom`, and the unleveled `ArtistsAndRepertoire` /
+`Copyist`) are spelled out separately in `RecordingRole`.
+
 ## Layout
 
 ```
 src/
   client.ts              the client extension — misoPlatform({ packageId, settingsId, misoPackageId?, minatoPackageId? })
   pressing.ts            facade: builders, readers, and the id derivations
-  queries.ts             shared read plumbing (isNotFound)
+  queries.ts             shared read plumbing (isNotFound, re-exported from @misonetwork/sdk)
   transactions.ts        the TxThunk contract + the opinionated publish flow (disperse/finalize/publish*)
   release-graph.ts        whole release graph in one PTB (publishReleaseGraph)
   share.ts               share-currency provisioning (createShareCurrency, batched variants)
   share-template.ts      embedded `share` package bytecode
+  credits.ts             EXTENSION: contributor credits + the three role vocabularies
+  cover.ts               EXTENSION: release cover art (Walrus blob via ori)
+  extensions/
+    royalty-pool.ts      EXTENSION: create + share a RoyaltyPool<Share, Currency>
   execute.ts              executeViaExecutor, layered on @misonetwork/sdk's buildTx/toExecResult
+  internal.ts            private helpers (the 0x1::option moveCall targets) — NOT exported
+  contracts.ts           barrel re-exporting the generated bindings as `contracts`
   contracts/             GENERATED — do not edit by hand
 ```
 
@@ -216,11 +338,17 @@ the on-chain ABI:
 bun run codegen   # reads sui-codegen.config.ts → src/contracts/
 ```
 
-`sui-codegen.config.ts` lists **platform packages only** (currently just
-`miso_pressing`). Protocol packages (`miso`/composition/recording/release and
-its extensions) generate into `@misonetwork/sdk` instead, which this package
-depends on for their typed bindings — adding a protocol package here to save
-an import is how the split this package exists to enforce gets undone.
+`sui-codegen.config.ts` lists the **platform** package (`miso_pressing`) and the
+first-party **extension** packages (`royalty_pool`, `composition_royalty_pool`,
+`recording_royalty_pool`, `cover_art`, `release_cover_art`,
+`composition_credits`, `recording_credits`, `release_credits`). The protocol
+CORE (`miso` — composition/recording/release/deal/track) generates into
+`@misonetwork/sdk` instead, which this package depends on for those bindings —
+adding the core here to save an import is how the split this package exists to
+enforce gets undone.
+
+Paths resolve against sibling checkouts, so regenerating requires
+`~/Documents/GitHub/misofm/{sdk, pressing, protocol-extensions}`.
 
 ## Dependency on `@misonetwork/sdk`
 

package/dist/contracts/composition_credits/composition_credits.d.ts

@@ -0,0 +1,181 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+/**
+ * First-party credits extension for compositions.
+ *
+ * Attribution (writing credits) is display-oriented and varies across platforms,
+ * so it lives here as a dynamic field on the composition rather than in immutable
+ * core. The data is attached under `ExtensionKey()` via the composition's
+ * cap-gated `uid_mut`, so every mutation is authorized by the composition's admin
+ * and credits survive into any lifecycle state (they may be attached before or
+ * after the composition is published).
+ *
+ * This is Miso's canonical credits standard; because it is an extension, other
+ * parties may publish their own composition-credits standard against the same
+ * `Composition`. Credits are NOT read by the economics — they are attribution.
+ */
+import { MoveTuple, MoveStruct, type RawTransactionArgument } from '../utils/index.js';
+import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
+export declare const ExtensionKey: MoveTuple<readonly [import("@mysten/sui/bcs").BcsType<boolean, boolean, "bool">], "@local-pkg/composition_credits::composition_credits::ExtensionKey">;
+export declare const CompositionCredits: MoveStruct<{
+    /** Map of party IDs to their credit (display name + roles). */
+    credits: MoveStruct<{
+        contents: import("@mysten/sui/bcs").BcsType<{
+            key: string;
+            value: {
+                display_name: string;
+                roles: import("@mysten/bcs").EnumOutputShapeWithKeys<{
+                    Adapter: true;
+                    Arranger: true;
+                    Composer: true;
+                    Lyricist: true;
+                    Songwriter: true;
+                    Translator: true;
+                    Custom: string;
+                }, "Adapter" | "Arranger" | "Composer" | "Lyricist" | "Songwriter" | "Translator" | "Custom">[];
+            };
+        }[], Iterable<{
+            key: string | Uint8Array<ArrayBufferLike>;
+            value: {
+                display_name: string;
+                roles: Iterable<import("@mysten/bcs").EnumInputShape<{
+                    Adapter: boolean | object | null;
+                    Arranger: boolean | object | null;
+                    Composer: boolean | object | null;
+                    Lyricist: boolean | object | null;
+                    Songwriter: boolean | object | null;
+                    Translator: boolean | object | null;
+                    Custom: string;
+                }>> & {
+                    length: number;
+                };
+            };
+        }> & {
+            length: number;
+        }, string>;
+    }, "0x2::vec_map::VecMap<bytes[32], miso_credit::credit::Credit<@local-pkg/composition_credits::composition_party_role::CompositionPartyRole>>">;
+}, "@local-pkg/composition_credits::composition_credits::CompositionCredits">;
+export declare const CreditAddedEvent: MoveStruct<{
+    composition_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    party_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    credit: MoveStruct<{
+        display_name: import("@mysten/sui/bcs").BcsType<string, string, "string">;
+        roles: import("@mysten/sui/bcs").BcsType<import("@mysten/bcs").EnumOutputShapeWithKeys<{
+            Adapter: true;
+            Arranger: true;
+            Composer: true;
+            Lyricist: true;
+            Songwriter: true;
+            Translator: true;
+            Custom: string;
+        }, "Adapter" | "Arranger" | "Composer" | "Lyricist" | "Songwriter" | "Translator" | "Custom">[], Iterable<import("@mysten/bcs").EnumInputShape<{
+            Adapter: boolean | object | null;
+            Arranger: boolean | object | null;
+            Composer: boolean | object | null;
+            Lyricist: boolean | object | null;
+            Songwriter: boolean | object | null;
+            Translator: boolean | object | null;
+            Custom: string;
+        }>> & {
+            length: number;
+        }, string>;
+    }, "miso_credit::credit::Credit<@local-pkg/composition_credits::composition_party_role::CompositionPartyRole>">;
+}, "@local-pkg/composition_credits::composition_credits::CreditAddedEvent">;
+export declare const CreditRemovedEvent: MoveStruct<{
+    composition_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    party_id: import("@mysten/sui/bcs").BcsType<string, string | Uint8Array<ArrayBufferLike>, "bytes[32]">;
+    credit: MoveStruct<{
+        display_name: import("@mysten/sui/bcs").BcsType<string, string, "string">;
+        roles: import("@mysten/sui/bcs").BcsType<import("@mysten/bcs").EnumOutputShapeWithKeys<{
+            Adapter: true;
+            Arranger: true;
+            Composer: true;
+            Lyricist: true;
+            Songwriter: true;
+            Translator: true;
+            Custom: string;
+        }, "Adapter" | "Arranger" | "Composer" | "Lyricist" | "Songwriter" | "Translator" | "Custom">[], Iterable<import("@mysten/bcs").EnumInputShape<{
+            Adapter: boolean | object | null;
+            Arranger: boolean | object | null;
+            Composer: boolean | object | null;
+            Lyricist: boolean | object | null;
+            Songwriter: boolean | object | null;
+            Translator: boolean | object | null;
+            Custom: string;
+        }>> & {
+            length: number;
+        }, string>;
+    }, "miso_credit::credit::Credit<@local-pkg/composition_credits::composition_party_role::CompositionPartyRole>">;
+}, "@local-pkg/composition_credits::composition_credits::CreditRemovedEvent">;
+export interface AddCreditArguments {
+    self: RawTransactionArgument<string>;
+    cap: RawTransactionArgument<string>;
+    party: RawTransactionArgument<string>;
+    credit: TransactionArgument;
+}
+export interface AddCreditOptions {
+    package?: string;
+    arguments: AddCreditArguments | [
+        self: RawTransactionArgument<string>,
+        cap: RawTransactionArgument<string>,
+        party: RawTransactionArgument<string>,
+        credit: TransactionArgument
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/**
+ * Adds a credit for a party on the composition, lazily creating the credits record
+ * on first use. Each credit must have 1-5 roles, and a party may hold at most one
+ * credit. Requires the composition's admin capability.
+ */
+export declare function addCredit(options: AddCreditOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface RemoveCreditArguments {
+    self: RawTransactionArgument<string>;
+    cap: RawTransactionArgument<string>;
+    partyId: RawTransactionArgument<string>;
+}
+export interface RemoveCreditOptions {
+    package?: string;
+    arguments: RemoveCreditArguments | [
+        self: RawTransactionArgument<string>,
+        cap: RawTransactionArgument<string>,
+        partyId: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Removes a party's credit. Requires the composition's admin capability. */
+export declare function removeCredit(options: RemoveCreditOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface HasCreditsArguments {
+    self: RawTransactionArgument<string>;
+}
+export interface HasCreditsOptions {
+    package?: string;
+    arguments: HasCreditsArguments | [
+        self: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Returns whether a credits record has been attached to this composition yet. */
+export declare function hasCredits(options: HasCreditsOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface CreditsArguments {
+    self: RawTransactionArgument<string>;
+}
+export interface CreditsOptions {
+    package?: string;
+    arguments: CreditsArguments | [
+        self: RawTransactionArgument<string>
+    ];
+    typeArguments: [
+        string
+    ];
+}
+/** Returns the party-to-credit map. Aborts if no credits are attached. */
+export declare function credits(options: CreditsOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+//# sourceMappingURL=composition_credits.d.ts.map

package/dist/contracts/composition_credits/composition_credits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition_credits.d.ts","sourceRoot":"","sources":["../../../src/contracts/composition_credits/composition_credits.ts"],"names":[],"mappings":"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"}

package/dist/contracts/composition_credits/composition_credits.js

@@ -0,0 +1,109 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+/**
+ * First-party credits extension for compositions.
+ *
+ * Attribution (writing credits) is display-oriented and varies across platforms,
+ * so it lives here as a dynamic field on the composition rather than in immutable
+ * core. The data is attached under `ExtensionKey()` via the composition's
+ * cap-gated `uid_mut`, so every mutation is authorized by the composition's admin
+ * and credits survive into any lifecycle state (they may be attached before or
+ * after the composition is published).
+ *
+ * This is Miso's canonical credits standard; because it is an extension, other
+ * parties may publish their own composition-credits standard against the same
+ * `Composition`. Credits are NOT read by the economics — they are attribution.
+ */
+import { MoveTuple, MoveStruct, normalizeMoveArguments } from '../utils/index.js';
+import { bcs } from '@mysten/sui/bcs';
+import {} from '@mysten/sui/transactions';
+import * as vec_map from './deps/sui/vec_map.js';
+import * as credit from './deps/miso_credit/credit.js';
+import * as composition_party_role from './composition_party_role.js';
+const $moduleName = '@local-pkg/composition_credits::composition_credits';
+export const ExtensionKey = new MoveTuple({ name: `${$moduleName}::ExtensionKey`, fields: [bcs.bool()] });
+export const CompositionCredits = new MoveStruct({ name: `${$moduleName}::CompositionCredits`, fields: {
+        /** Map of party IDs to their credit (display name + roles). */
+        credits: vec_map.VecMap(bcs.Address, credit.Credit(composition_party_role.CompositionPartyRole))
+    } });
+export const CreditAddedEvent = new MoveStruct({ name: `${$moduleName}::CreditAddedEvent`, fields: {
+        composition_id: bcs.Address,
+        party_id: bcs.Address,
+        credit: credit.Credit(composition_party_role.CompositionPartyRole)
+    } });
+export const CreditRemovedEvent = new MoveStruct({ name: `${$moduleName}::CreditRemovedEvent`, fields: {
+        composition_id: bcs.Address,
+        party_id: bcs.Address,
+        credit: credit.Credit(composition_party_role.CompositionPartyRole)
+    } });
+/**
+ * Adds a credit for a party on the composition, lazily creating the credits record
+ * on first use. Each credit must have 1-5 roles, and a party may hold at most one
+ * credit. Requires the composition's admin capability.
+ */
+export function addCredit(options) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null,
+        null,
+        null,
+        null
+    ];
+    const parameterNames = ["self", "cap", "party", "credit"];
+    return (tx) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'add_credit',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+/** Removes a party's credit. Requires the composition's admin capability. */
+export function removeCredit(options) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null,
+        null,
+        '0x2::object::ID'
+    ];
+    const parameterNames = ["self", "cap", "partyId"];
+    return (tx) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'remove_credit',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+/** Returns whether a credits record has been attached to this composition yet. */
+export function hasCredits(options) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null
+    ];
+    const parameterNames = ["self"];
+    return (tx) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'has_credits',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+/** Returns the party-to-credit map. Aborts if no credits are attached. */
+export function credits(options) {
+    const packageAddress = options.package ?? '@local-pkg/composition_credits';
+    const argumentsTypes = [
+        null
+    ];
+    const parameterNames = ["self"];
+    return (tx) => tx.moveCall({
+        package: packageAddress,
+        module: 'composition_credits',
+        function: 'credits',
+        arguments: normalizeMoveArguments(options.arguments, argumentsTypes, parameterNames),
+        typeArguments: options.typeArguments
+    });
+}
+//# sourceMappingURL=composition_credits.js.map

package/dist/contracts/composition_credits/composition_credits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition_credits.js","sourceRoot":"","sources":["../../../src/contracts/composition_credits/composition_credits.ts"],"names":[],"mappings":"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"}

package/dist/contracts/composition_credits/composition_party_role.d.ts

@@ -0,0 +1,119 @@
+/**************************************************************
+ * THIS FILE IS GENERATED AND SHOULD NOT BE MANUALLY MODIFIED *
+ **************************************************************/
+/**
+ * Defines the roles that parties can hold on a composition. Compositions are the
+ * underlying musical works (melody + lyrics), and these roles represent the
+ * writing and adaptation contributions to them.
+ *
+ * ### Design
+ *
+ * `CompositionPartyRole` is a closed enum: variants can only be constructed and
+ * matched inside this module, so the `new_*_role` constructors are the external
+ * write-API and `name()` is the external read-API.
+ *
+ * - **No seniority axis.** Unlike recording roles, composition roles carry no
+ *   level — a writer either contributed in a given capacity or did not.
+ * - **`Custom` is the escape hatch.** The canonical variants cover the common
+ *   writing vocabulary; anything outside it is a `Custom(name)` whose name is
+ *   validated. Prefer a canonical variant when one fits.
+ * - **`name()` is the canonical identifier**, returned as a stable PascalCase
+ *   token (e.g. `"Songwriter"`). For `Custom`, `name()` returns the user-supplied
+ *   string.
+ *
+ * These identifiers are Miso's own canonical vocabulary; any overlap with an
+ * external standard (e.g. DDEX) is coincidental, not a reproduction of it.
+ */
+import { MoveEnum, type RawTransactionArgument } from '../utils/index.js';
+import { type Transaction, type TransactionArgument } from '@mysten/sui/transactions';
+/** Represents a party's role on a composition. */
+export declare const CompositionPartyRole: MoveEnum<{
+    /** Adapted an existing work into this composition. */
+    Adapter: null;
+    /** Arranged the musical parts of the composition. */
+    Arranger: null;
+    /** Composed the music of the composition. */
+    Composer: null;
+    /** Wrote the lyrics of the composition. */
+    Lyricist: null;
+    /** Wrote both music and lyrics of the composition. */
+    Songwriter: null;
+    /** Translated the lyrics of the composition. */
+    Translator: null;
+    /**
+     * A user-defined role not covered by a canonical variant. Carries the role name
+     * (validated). An escape hatch — prefer a canonical variant when one fits.
+     */
+    Custom: import("@mysten/sui/bcs").BcsType<string, string, "string">;
+}, "@local-pkg/composition_credits::composition_party_role::CompositionPartyRole">;
+export interface NewAdapterRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Adapter role. */
+export declare function newAdapterRole(options?: NewAdapterRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewArrangerRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Arranger role. */
+export declare function newArrangerRole(options?: NewArrangerRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewComposerRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Composer role. */
+export declare function newComposerRole(options?: NewComposerRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewLyricistRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Lyricist role. */
+export declare function newLyricistRole(options?: NewLyricistRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewSongwriterRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Songwriter role. */
+export declare function newSongwriterRole(options?: NewSongwriterRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewTranslatorRoleOptions {
+    package?: string;
+    arguments?: [
+    ];
+}
+/** Creates a new Translator role. */
+export declare function newTranslatorRole(options?: NewTranslatorRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NewCustomRoleArguments {
+    roleName: RawTransactionArgument<string>;
+}
+export interface NewCustomRoleOptions {
+    package?: string;
+    arguments: NewCustomRoleArguments | [
+        roleName: RawTransactionArgument<string>
+    ];
+}
+/**
+ * Creates a new Custom role with a user-defined name. The name freezes into
+ * credits, so it is validated here. Prefer a canonical variant when one fits.
+ */
+export declare function newCustomRole(options: NewCustomRoleOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+export interface NameArguments {
+    self: TransactionArgument;
+}
+export interface NameOptions {
+    package?: string;
+    arguments: NameArguments | [
+        self: TransactionArgument
+    ];
+}
+/**
+ * Returns the canonical identifier of the role as a stable PascalCase token. For
+ * `Custom`, returns the user-supplied name.
+ */
+export declare function name(options: NameOptions): (tx: Transaction) => import("@mysten/sui/transactions").TransactionResult;
+//# sourceMappingURL=composition_party_role.d.ts.map

package/dist/contracts/composition_credits/composition_party_role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition_party_role.d.ts","sourceRoot":"","sources":["../../../src/contracts/composition_credits/composition_party_role.ts"],"names":[],"mappings":"AAAA;;gEAEgE;AAGhE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,QAAQ,EAA0B,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAElG,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEtF,kDAAkD;AAClD,eAAO,MAAM,oBAAoB;IACzB,sDAAsD;;IAEtD,qDAAqD;;IAErD,6CAA6C;;IAE7C,2CAA2C;;IAE3C,sDAAsD;;IAEtD,gDAAgD;;IAEhD;;;OAGG;;kFAEH,CAAC;AACT,MAAM,WAAW,qBAAqB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,kCAAkC;AAClC,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,IAEtD,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,IAExD,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,IAExD,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,IAExD,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,wBAAwB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,qCAAqC;AACrC,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,IAE5D,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,wBAAwB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE;KACX,CAAC;CACL;AACD,qCAAqC;AACrC,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,IAE5D,IAAI,WAAW,0DAK1B;AACD,MAAM,WAAW,sBAAsB;IACnC,QAAQ,EAAE,sBAAsB,CAAC,MAAM,CAAC,CAAC;CAC5C;AACD,MAAM,WAAW,oBAAoB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,sBAAsB,GAAG;QAChC,QAAQ,EAAE,sBAAsB,CAAC,MAAM,CAAC;KAC3C,CAAC;CACL;AACD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,IAM/C,IAAI,WAAW,0DAM1B;AACD,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,mBAAmB,CAAC;CAC7B;AACD,MAAM,WAAW,WAAW;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,GAAG;QACvB,IAAI,EAAE,mBAAmB;KAC5B,CAAC;CACL;AACD;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,IAM7B,IAAI,WAAW,0DAM1B"}