@misofm/sdk 0.1.0

package/src/release-graph.ts

@@ -0,0 +1,279 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Single-PTB publisher for a whole release graph: creates every composition and
+// recording, optionally attaches royalty pools, derives the release id ON-CHAIN
+// (so recordings need not be shared first), builds the deals/tracks/release,
+// then shares everything and transfers the admin caps — all in ONE transaction.
+//
+// Share currencies must already be published + initialized (their Currency objects
+// shared on-chain); their ids/types are passed in. Ordering is load-bearing:
+//   1. composition::new → recording::new(&comp)  (borrow-before-share) + pool attach
+//   2. release::derive_release_id(<recording::id results>) → deal::new(cap, &rec,
+//      derivedId, split) → track::new → release::new
+//   3. publish (share) comps + recs + release, disperse supply, transfer caps
+// Steps 1–2 borrow the works; step 3 consumes them into share_object.
+//
+// Release tracks come in three shapes (see TrackNode): recordings created in
+// THIS PTB, existing recordings authorized by their admin cap (deal created
+// inline), and existing recordings authorized by a pre-made Deal in hand.
+// Pre-made deals pin the release id, so they cannot coexist with fresh
+// recordings — the builder rejects that mix up front.
+//
+// This is the whole-graph orchestration half of the opinionated publish flow —
+// it composes `@misonetwork/sdk`'s bare `composition`/`recording`/`deal`/`track`/
+// `release` call bindings, its `createRelease` primitive and
+// `attachCompositionRoyaltyPool`/`attachRecordingRoyaltyPool`, plus this
+// package's own `disperseShares`/`finalizeRelease`, into one PTB.
+
+import { Transaction, type TransactionObjectArgument } from "@mysten/sui/transactions";
+import {
+  contracts,
+  attachCompositionRoyaltyPool,
+  attachRecordingRoyaltyPool,
+  createRelease,
+  PROTOCOL_MAX_ROYALTY_RATE_BPS,
+} from "@misonetwork/sdk";
+import { disperseShares, finalizeRelease, type ShareRecipient } from "./transactions.ts";
+
+const { composition, recording, deal, track, release } = contracts;
+
+/** A royalty pool to attach to a work, in the same PTB. */
+export interface RoyaltyPoolNode {
+  currency: string;
+  /** `composition_royalty_pool` / `recording_royalty_pool` package id. */
+  extensionPackageId: string;
+  /** Base `royalty_pool` lib package id. */
+  royaltyPoolPackageId: string;
+}
+
+export interface CompositionNode {
+  shareType: string;
+  shareCurrencyId: string;
+  shareTreasuryCapId: string;
+  title: string;
+  royaltyRateBps: number;
+  shareRecipients: ShareRecipient[];
+  /** Recipient of the CompositionAdminCap (the owner). */
+  adminAddress: string;
+  royaltyPool?: RoyaltyPoolNode;
+}
+
+export interface RecordingNode {
+  shareType: string;
+  shareCurrencyId: string;
+  shareTreasuryCapId: string;
+  /** The parent composition's share type. */
+  compositionShareType: string;
+  /** Index into `compositions[]` if the parent is created in THIS PTB… */
+  parentCompositionIndex?: number;
+  /** …or the on-chain composition object id if the parent already exists. */
+  parentCompositionId?: string;
+  shareRecipients: ShareRecipient[];
+  adminAddress: string;
+  /**
+   * Slippage guard for `recording::new` against an EXISTING on-chain parent —
+   * pass the composition rate you observed (default: protocol max). Ignored for
+   * parents created in this PTB, whose exact known rate is pinned automatically.
+   */
+  maxRoyaltyRateBps?: number;
+  royaltyPool?: RoyaltyPoolNode;
+}
+
+/** A track whose recording is created in THIS PTB (its deal is created inline). */
+export interface FreshTrackNode {
+  /** Index into `recordings[]`. */
+  recordingIndex: number;
+  splitBps: number;
+}
+
+/**
+ * A track over an EXISTING recording, authorized by its admin cap (held by the
+ * sender) — the deal is created inline against the on-chain-derived release id.
+ * This is the only way to mix existing recordings with ones created in this PTB.
+ */
+export interface CapTrackNode {
+  recordingId: string;
+  recordingAdminCapId: string;
+  recordingShareType: string;
+  compositionShareType: string;
+  splitBps: number;
+}
+
+/**
+ * A track over an EXISTING recording, authorized by a pre-made `Deal` held by
+ * the sender. A deal pins the exact release id — a digest over ALL track
+ * recording ids — so deal-backed tracks cannot coexist with `FreshTrackNode`s
+ * (a fresh recording's id is unknowable when the deal was created).
+ * `splitBps` must be the value stored in the deal (read it from the object).
+ */
+export interface DealTrackNode {
+  dealId: string;
+  recordingId: string;
+  recordingShareType: string;
+  compositionShareType: string;
+  splitBps: number;
+}
+
+export type TrackNode = FreshTrackNode | CapTrackNode | DealTrackNode;
+
+const isFresh = (t: TrackNode): t is FreshTrackNode => "recordingIndex" in t;
+const isDealBacked = (t: TrackNode): t is DealTrackNode => "dealId" in t;
+
+export interface ReleaseNode {
+  title: string;
+  /** u256 nonce as a decimal string (deterministic release id). */
+  nonce: string;
+  adminAddress: string;
+  releaseRegistryId: string;
+  /** The ordered tracklist. Display grouping (discs/sides) is extension data. */
+  tracks: TrackNode[];
+}
+
+export interface PublishReleaseGraphParams {
+  compositions: CompositionNode[];
+  recordings: RecordingNode[];
+  release?: ReleaseNode;
+  misoPackageId: string;
+  minatoPackageId: string;
+}
+
+interface Parts {
+  work: TransactionObjectArgument;
+  adminCap: TransactionObjectArgument;
+  balance: TransactionObjectArgument;
+}
+
+/** Builds the entire graph in a single transaction (see file header for ordering). */
+export function publishReleaseGraph(params: PublishReleaseGraphParams): (tx: Transaction) => void {
+  const { misoPackageId: pkg, minatoPackageId } = params;
+  return (tx) => {
+    // ── 1) Create every composition, then every recording (borrow-before-share) ──
+    const comps: Parts[] = params.compositions.map((c) => {
+      const r = tx.add(
+        composition._new({
+          package: pkg,
+          typeArguments: [c.shareType],
+          arguments: [tx.pure.string(c.title), tx.pure.u16(c.royaltyRateBps), tx.object(c.shareCurrencyId), tx.object(c.shareTreasuryCapId)],
+        }),
+      );
+      const parts: Parts = { work: r[0]!, adminCap: r[1]!, balance: r[2]! };
+      if (c.royaltyPool) {
+        attachCompositionRoyaltyPool(tx, {
+          composition: parts.work,
+          adminCap: parts.adminCap,
+          compositionShareType: c.shareType,
+          currency: c.royaltyPool.currency,
+          compositionRoyaltyPoolPackageId: c.royaltyPool.extensionPackageId,
+          royaltyPoolPackageId: c.royaltyPool.royaltyPoolPackageId,
+        });
+      }
+      return parts;
+    });
+
+    const recTypeArgs = (i: number): [string, string] => {
+      const n = params.recordings[i]!;
+      return [n.shareType, n.compositionShareType];
+    };
+
+    const recs: Parts[] = params.recordings.map((rec, i) => {
+      const parent = rec.parentCompositionIndex !== undefined ? comps[rec.parentCompositionIndex]!.work : tx.object(rec.parentCompositionId!);
+      // Slippage guard: a parent created in this PTB has a known rate — pin it
+      // exactly. An existing parent uses the caller's observed rate (or accepts
+      // up to the protocol max).
+      const maxRoyaltyRateBps =
+        rec.parentCompositionIndex !== undefined
+          ? params.compositions[rec.parentCompositionIndex]!.royaltyRateBps
+          : (rec.maxRoyaltyRateBps ?? PROTOCOL_MAX_ROYALTY_RATE_BPS);
+      const typeArgs = recTypeArgs(i);
+      const r = tx.add(
+        recording._new({ package: pkg, typeArguments: typeArgs, arguments: [parent, tx.object(rec.shareCurrencyId), tx.object(rec.shareTreasuryCapId), tx.pure.u16(maxRoyaltyRateBps)] }),
+      );
+      const parts: Parts = { work: r[0]!, adminCap: r[1]!, balance: r[2]! };
+      if (rec.royaltyPool) {
+        attachRecordingRoyaltyPool(tx, {
+          recording: parts.work,
+          adminCap: parts.adminCap,
+          recordingShareType: rec.shareType,
+          compositionShareType: rec.compositionShareType,
+          currency: rec.royaltyPool.currency,
+          recordingRoyaltyPoolPackageId: rec.royaltyPool.extensionPackageId,
+          royaltyPoolPackageId: rec.royaltyPool.royaltyPoolPackageId,
+        });
+      }
+      return parts;
+    });
+
+    // ── 2) Release: derive the id on-chain, then deals → tracks → release ──
+    if (params.release) {
+      const rel = params.release;
+      const ordered = rel.tracks;
+      if (ordered.some(isDealBacked) && ordered.some(isFresh)) {
+        throw new Error(
+          "A release cannot mix pre-made deals with recordings created in this transaction: " +
+            "a deal pins the exact release id, whose digest includes every track's recording id, " +
+            "and a fresh recording's id is unknowable when the deal was created. " +
+            "Authorize the existing recordings with their admin caps instead.",
+        );
+      }
+
+      // The derived id feeds the deals created inline (fresh/cap-backed tracks).
+      // Pre-made deals already store it, so an all-deal release skips the derive.
+      let releaseId: TransactionObjectArgument | undefined;
+      if (!ordered.every(isDealBacked)) {
+        const idVec = tx.makeMoveVec({
+          type: "0x2::object::ID",
+          elements: ordered.map((t) =>
+            isFresh(t)
+              ? tx.add(recording.id({ package: pkg, typeArguments: recTypeArgs(t.recordingIndex), arguments: [recs[t.recordingIndex]!.work] }))
+              : tx.pure.id(t.recordingId),
+          ),
+        });
+        const splitVec = tx.makeMoveVec({ type: "u64", elements: ordered.map((t) => tx.pure.u64(t.splitBps)) });
+        releaseId = tx.add(
+          release.deriveReleaseId({ package: pkg, arguments: [idVec, splitVec, tx.pure.u256(BigInt(rel.nonce)), tx.object(rel.releaseRegistryId)] }),
+        );
+      }
+
+      const trackArgs = ordered.map((t) => {
+        if (isDealBacked(t)) {
+          const typeArgs: [string, string] = [t.recordingShareType, t.compositionShareType];
+          return tx.add(track._new({ package: pkg, typeArguments: typeArgs, arguments: [tx.object(t.dealId), tx.object(t.recordingId)] }));
+        }
+        if (isFresh(t)) {
+          const typeArgs = recTypeArgs(t.recordingIndex);
+          const parts = recs[t.recordingIndex]!;
+          const dealArg = tx.add(deal._new({ package: pkg, typeArguments: typeArgs, arguments: [parts.adminCap, parts.work, releaseId!, tx.pure.u16(t.splitBps)] }));
+          return tx.add(track._new({ package: pkg, typeArguments: typeArgs, arguments: [dealArg, parts.work] }));
+        }
+        const typeArgs: [string, string] = [t.recordingShareType, t.compositionShareType];
+        const rec = tx.object(t.recordingId);
+        const dealArg = tx.add(
+          deal._new({ package: pkg, typeArguments: typeArgs, arguments: [tx.object(t.recordingAdminCapId), rec, releaseId!, tx.pure.u16(t.splitBps)] }),
+        );
+        return tx.add(track._new({ package: pkg, typeArguments: typeArgs, arguments: [dealArg, rec] }));
+      });
+      const trackVec = tx.makeMoveVec({ type: `${pkg}::track::Track`, elements: trackArgs });
+      const releaseParts = createRelease(
+        tx,
+        { title: rel.title, nonce: rel.nonce, releaseRegistryId: rel.releaseRegistryId, misoPackageId: pkg },
+        trackVec,
+      );
+      finalizeRelease(tx, { ...releaseParts, adminAddress: rel.adminAddress, misoPackageId: pkg });
+    }
+
+    // ── 3) Share every work, disperse its supply, transfer admin caps ──
+    params.compositions.forEach((c, i) => {
+      const parts = comps[i]!;
+      disperseShares(tx, minatoPackageId, c.shareType, parts.balance, c.shareRecipients);
+      tx.add(composition.publish({ package: pkg, typeArguments: [c.shareType], arguments: [parts.work, parts.adminCap] }));
+      tx.transferObjects([parts.adminCap], c.adminAddress);
+    });
+    params.recordings.forEach((rec, i) => {
+      const parts = recs[i]!;
+      tx.add(recording.publish({ package: pkg, typeArguments: recTypeArgs(i), arguments: [parts.work, parts.adminCap] }));
+      disperseShares(tx, minatoPackageId, rec.shareType, parts.balance, rec.shareRecipients);
+      tx.transferObjects([parts.adminCap], rec.adminAddress);
+    });
+  };
+}

package/src/share-template.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Embedded share-currency bytecode template: the compiled `share` Move package
+// (deps 0x1/0x2, network-agnostic). `patchInitializer` stamps the INITIALIZER
+// address into a fresh copy before publish. Kept as a typed const rather than a
+// JSON asset so the SDK is self-contained — no file read, no path resolution, and
+// it bundles cleanly. Regenerate from the compiled package if the share module
+// changes.
+
+import type { PackageBytecode } from "./transactions.ts";
+
+export const SHARE_TEMPLATE: PackageBytecode = {
+  "modules": [
+    "oRzrCwYAAAAKAQAOAg4gAy4gBE4EBVJHB5kB1QEI7gJgBs4DNwqFBAYMiwQ4ABEBEgIHAggCCQIPAhMAAggAAQMHAAMEDAEAAQQACAAEAQABAAEFBgQABgUCAAANAAEAARQFBgACCwUEAAQKCgIBAAQOCAkBCAYQAwQABAcDBwUIAQgBCAEHCAMHCAYBCwIBCAAAAQYIBgEFAQoCAQgBAQgABwcIAwIIAQgBCAEIAQcIBgILBAEJAAsCAQkAAgsEAQkABwgGDENvaW5SZWdpc3RyeRNDdXJyZW5jeUluaXRpYWxpemVyBVNoYXJlBlN0cmluZwtUcmVhc3VyeUNhcAlUeENvbnRleHQDVUlEB2FkZHJlc3MEY29pbg1jb2luX3JlZ2lzdHJ5IGZpbmFsaXplX2FuZF9kZWxldGVfbWV0YWRhdGFfY2FwCmZyb21fYnl0ZXMCaWQKaW5pdGlhbGl6ZQxuZXdfY3VycmVuY3kGb2JqZWN0BnNlbmRlcgVzaGFyZQZzdHJpbmcKdHhfY29udGV4dAR1dGY4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACCgIhIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwgAAAAAAAAAAAoCBgVTSEFSRQACAQwIBQABAAABHAoELhEFBwARAiEECAUOCwQBCwMBBwEnCwMxBgcCEQELAAsBCwIKBDgADAULBDgBCwUCAA=="
+  ],
+  "dependencies": [
+    "0x0000000000000000000000000000000000000000000000000000000000000001",
+    "0x0000000000000000000000000000000000000000000000000000000000000002"
+  ],
+  "digest": [
+    191,
+    44,
+    36,
+    112,
+    72,
+    10,
+    163,
+    173,
+    88,
+    79,
+    123,
+    99,
+    33,
+    92,
+    255,
+    215,
+    122,
+    199,
+    22,
+    101,
+    247,
+    141,
+    222,
+    237,
+    187,
+    42,
+    28,
+    13,
+    201,
+    193,
+    173,
+    204
+  ]
+};

package/src/share.ts

@@ -0,0 +1,258 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Share-currency provisioning.
+//
+// Every composition and every recording is backed by its own fixed-supply
+// (10M @ 6dp) share currency — an independently published `share` package whose
+// `INITIALIZER` constant is patched to an authorized address before publish.
+// Creating one is two transactions that CANNOT share a PTB: a `moveCall` target
+// must name a concrete package id, but a package published in the same PTB has no
+// id until it executes, so `${pkg}::share::initialize` must run in a later tx.
+//
+// The bytecode is identical for every currency (only the baked-in INITIALIZER
+// matters, and it is the same signer for all), so publishes are fungible: a whole
+// batch can be published — up to 5 `tx.publish` per PTB (the protocol's
+// `max_publish_or_upgrade_per_ptb` cap) — and run concurrently through a
+// `ParallelTransactionExecutor`. Initialization is likewise batched. The caller
+// assigns packages to work slots and supplies per-package metadata, so each
+// currency still gets a descriptive, work-specific name.
+
+import type { ParallelTransactionExecutor } from "@mysten/sui/transactions";
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import type { Signer } from "@mysten/sui/cryptography";
+import { fromBase64, fromHex, toBase64 } from "@mysten/sui/utils";
+import { update_constants } from "@mysten/move-bytecode-template";
+import {
+  execThunks,
+  publishedPackageId,
+  allPublishedPackageIds,
+  createdByType,
+  allCreatedByType,
+  type ExecResult,
+} from "@misonetwork/sdk";
+
+import { publishShareCurrency, initializeShareCurrency, type PackageBytecode } from "./transactions.ts";
+import { SHARE_TEMPLATE } from "./share-template.ts";
+import { executeViaExecutor } from "./execute.ts";
+
+/** The protocol cap on Publish/Upgrade commands per programmable transaction. */
+const PUBLISHES_PER_PTB = 5;
+/** Initializes batched per PTB (each is one moveCall + transfer; all share the 0xc registry). */
+const INITS_PER_PTB = 10;
+
+// Address-free type markers: gRPC object types carry fully-normalized addresses
+// (e.g. 0x0000…0002::coin::TreasuryCap), so we match on module::type rather than a
+// short "0x2" prefix that would never match.
+const CURRENCY_TYPE = "::coin_registry::Currency<";
+const TREASURY_CAP_TYPE = "::coin::TreasuryCap<";
+
+export interface ShareCurrency {
+  /** The published share package id. */
+  packageId: string;
+  /** The `Currency<Share>` object id. */
+  currencyId: string;
+  /** The fully-qualified share type, `${packageId}::share::Share`. */
+  shareType: string;
+  /** The `TreasuryCap<Share>` object id (held by the treasury-cap recipient). */
+  treasuryCapId: string;
+  /** Net gas (MIST) attributed to this currency, if tracked per-item (else 0). */
+  gasUsed: number;
+}
+
+export interface ShareCurrencyMeta {
+  name: string;
+  description: string;
+  iconUrl?: string;
+}
+
+// ── Bytecode patching ────────────────────────────────────────────────────────
+
+/**
+ * Patches the `INITIALIZER` constant in the share module bytecode, replacing the
+ * 32-byte zero-address placeholder with `initializerAddress`. The template is left
+ * untouched; a fresh patched copy is returned. `share::initialize` asserts the
+ * sender equals this address, so it must be the signer that will initialize.
+ */
+export function patchInitializer(template: PackageBytecode, initializerAddress: string): PackageBytecode {
+  const moduleBytes = fromBase64(template.modules[0]!);
+
+  // BCS-encoded vector<u8> of 32 zero bytes: [length=32, 0×32].
+  const oldValue = new Uint8Array(33);
+  oldValue[0] = 32;
+
+  // BCS-encoded vector<u8> of the initializer's 32 address bytes.
+  const newValue = new Uint8Array(33);
+  newValue[0] = 32;
+  newValue.set(fromHex(initializerAddress), 1);
+
+  const patched = update_constants(moduleBytes, newValue, oldValue, "Vector(U8)");
+  return { ...template, modules: [toBase64(patched)] };
+}
+
+// ── Single (sequential) ──────────────────────────────────────────────────────
+
+export interface CreateShareCurrencyParams {
+  /** The share bytecode template. Defaults to the embedded {@link SHARE_TEMPLATE}. */
+  template?: PackageBytecode;
+  name: string;
+  description: string;
+  iconUrl?: string;
+  /** Address baked in as INITIALIZER; must be the signer. Defaults to the signer. */
+  initializerAddress?: string;
+  /** Recipient of the minted `TreasuryCap`. Defaults to the signer. */
+  treasuryCapRecipient?: string;
+}
+
+/** Publishes + initializes a fresh share currency in two sequential txs. */
+export async function createShareCurrency(
+  client: ClientWithCoreApi,
+  signer: Signer,
+  params: CreateShareCurrencyParams,
+): Promise<ShareCurrency> {
+  const signerAddress = signer.toSuiAddress();
+  const initializer = params.initializerAddress ?? signerAddress;
+  const recipient = params.treasuryCapRecipient ?? signerAddress;
+
+  // Tx 1: publish the share package with the initializer baked in.
+  const patched = patchInitializer(params.template ?? SHARE_TEMPLATE, initializer);
+  const publishRes = await execThunks(client, signer, publishShareCurrency(patched));
+  const packageId = publishedPackageId(publishRes);
+
+  // Tx 2: initialize → creates the Currency object + transfers the TreasuryCap.
+  const initRes = await execThunks(
+    client,
+    signer,
+    initializeShareCurrency({
+      shareCurrencyPackageId: packageId,
+      name: params.name,
+      description: params.description,
+      iconUrl: params.iconUrl ?? "",
+      treasuryCapRecipient: recipient,
+    }),
+  );
+
+  return {
+    packageId,
+    currencyId: createdByType(initRes, CURRENCY_TYPE),
+    shareType: `${packageId}::share::Share`,
+    treasuryCapId: createdByType(initRes, TREASURY_CAP_TYPE),
+    gasUsed: publishRes.gasUsed + initRes.gasUsed,
+  };
+}
+
+// ── Batched (parallel) ─────────────────────────────────────────────────────
+
+/** Splits an array into fixed-size chunks. */
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+/**
+ * Publishes `count` fresh share-currency packages, batched at ≤5 publishes per PTB
+ * and run concurrently through the executor. Returns the published package ids
+ * (fungible — order is not meaningful; the caller assigns them to work slots).
+ */
+export async function publishShareCurrencies(
+  executor: ParallelTransactionExecutor,
+  initializerAddress: string,
+  count: number,
+  template: PackageBytecode = SHARE_TEMPLATE,
+): Promise<{ packageIds: string[]; gasUsed: number }> {
+  if (count <= 0) return { packageIds: [], gasUsed: 0 };
+
+  // One patched template, reused for every publish (identical bytecode → distinct packages).
+  const patched = patchInitializer(template, initializerAddress);
+
+  const batchSizes: number[] = [];
+  for (let remaining = count; remaining > 0; remaining -= PUBLISHES_PER_PTB) {
+    batchSizes.push(Math.min(PUBLISHES_PER_PTB, remaining));
+  }
+
+  const results = await Promise.all(
+    batchSizes.map((n) => executeViaExecutor(executor, ...Array.from({ length: n }, () => publishShareCurrency(patched)))),
+  );
+
+  const packageIds = results.flatMap(allPublishedPackageIds);
+  const gasUsed = results.reduce((sum, r) => sum + r.gasUsed, 0);
+  if (packageIds.length !== count) {
+    throw new Error(`Expected ${count} published share packages, got ${packageIds.length}.`);
+  }
+  return { packageIds, gasUsed };
+}
+
+/** Re-associates one init PTB's created objects back to their packages by share type. */
+function currenciesFromResult(res: ExecResult, batchPkgs: string[]): ShareCurrency[] {
+  const currencies = allCreatedByType(res, CURRENCY_TYPE);
+  const treasuries = allCreatedByType(res, TREASURY_CAP_TYPE);
+  return batchPkgs.map((pkg) => {
+    const shareType = `${pkg}::share::Share`;
+    const currency = currencies.find((o) => o.objectType.includes(shareType));
+    const treasury = treasuries.find((o) => o.objectType.includes(shareType));
+    if (!currency) throw new Error(`No Currency<${shareType}> created during initialize.`);
+    if (!treasury) throw new Error(`No TreasuryCap<${shareType}> created during initialize.`);
+    return { packageId: pkg, currencyId: currency.objectId, shareType, treasuryCapId: treasury.objectId, gasUsed: 0 };
+  });
+}
+
+/**
+ * Initializes each published package into a `Currency<Share>` + `TreasuryCap`,
+ * batched and run concurrently. `metaOf` supplies each package's display metadata,
+ * so a currency destined for a specific work is named for it.
+ *
+ * `share::initialize` is NON-idempotent (`coin_registry` registers one `Currency`
+ * per type), so a batch must never be re-run. Batches run under `Promise.allSettled`
+ * and `onBatch` fires for each SUCCEEDED batch as it lands — letting the caller
+ * persist that batch immediately. If any batch fails, the succeeded ones are already
+ * reported and this throws, so a resume re-initializes only the still-missing packages.
+ */
+export async function initializeShareCurrencies(
+  executor: ParallelTransactionExecutor,
+  signerAddress: string,
+  packageIds: string[],
+  metaOf: (packageId: string) => ShareCurrencyMeta,
+  onBatch?: (currencies: ShareCurrency[], gasUsed: number) => void | Promise<void>,
+): Promise<{ currencies: ShareCurrency[]; gasUsed: number }> {
+  if (packageIds.length === 0) return { currencies: [], gasUsed: 0 };
+
+  const batches = chunk(packageIds, INITS_PER_PTB);
+  const settled = await Promise.allSettled(
+    batches.map(async (batchPkgs) => {
+      const res = await executeViaExecutor(
+        executor,
+        ...batchPkgs.map((pkg) => {
+          const meta = metaOf(pkg);
+          return initializeShareCurrency({
+            shareCurrencyPackageId: pkg,
+            name: meta.name,
+            description: meta.description,
+            iconUrl: meta.iconUrl ?? "",
+            treasuryCapRecipient: signerAddress,
+          });
+        }),
+      );
+      const batchCurrencies = currenciesFromResult(res, batchPkgs);
+      if (onBatch) await onBatch(batchCurrencies, res.gasUsed);
+      return { batchCurrencies, gasUsed: res.gasUsed };
+    }),
+  );
+
+  const currencies: ShareCurrency[] = [];
+  const errors: unknown[] = [];
+  let gasUsed = 0;
+  for (const s of settled) {
+    if (s.status === "fulfilled") {
+      currencies.push(...s.value.batchCurrencies);
+      gasUsed += s.value.gasUsed;
+    } else {
+      errors.push(s.reason);
+    }
+  }
+  if (errors.length > 0) {
+    const msg = errors.map((e) => (e instanceof Error ? e.message : String(e))).join("; ");
+    throw new Error(`${errors.length}/${batches.length} initialize batch(es) failed: ${msg}`);
+  }
+  return { currencies, gasUsed };
+}