@misofm/sdk 0.15.10 → 0.16.0

package/src/read/wallet.ts

@@ -22,6 +22,9 @@ import {
 import type { MisoClient } from "./client.ts";
 import { int, u64 } from "./internal/scalars.ts";
 import * as vaultContract from "../contracts/vault/vault.ts";
+import * as recordContract from "../contracts/miso_record/record.ts";
+import { deriveRecordId } from "../pressing.ts";
+import { requireRecordSalesDeployment } from "../deployments.ts";
 import type {
   Balance,
   OwnedParty,
@@ -125,29 +128,14 @@ export function classifyVaultedWorkAdminCapType(
 
 // ── Records ──────────────────────────────────────────────────────────────────
 
-function coerceNumber(v: unknown): number | null {
-  if (typeof v === "number" && Number.isFinite(v)) return v;
-  if (typeof v === "bigint") return Number(v);
-  if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) return Number(v);
-  return null;
-}
-
-function record(value: unknown): Record<string, unknown> | null {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
 /**
- * A wallet record is trusted only when both halves of its concrete type are the
- * currently configured protocol packages. Checking the parsed tag (rather than
- * a prefix/suffix) rejects retired namespaces, extra type parameters, and an
- * arbitrary certificate that anyone can use with `record::new`.
+ * A wallet record is trusted only when it is the exact, non-generic Record type
+ * from the configured package. Checking the parsed tag (rather than a prefix or
+ * suffix) rejects retired namespaces and legacy/arbitrary generic wrappers.
  */
 function isCanonicalRecordType(
   type: string,
   recordPackageId: string,
-  pressingPackageId: string,
 ): boolean {
   let tag: ReturnType<typeof parseStructTag>;
   try {
@@ -160,34 +148,11 @@ function isCanonicalRecordType(
     tag.address !== normalizeSuiAddress(recordPackageId) ||
     tag.module !== "record" ||
     tag.name !== "Record" ||
-    tag.typeParams.length !== 1
+    tag.typeParams.length !== 0
   ) {
     return false;
   }
-
-  const certificate = tag.typeParams[0];
-  return (
-    certificate !== undefined &&
-    typeof certificate !== "string" &&
-    certificate.address === normalizeSuiAddress(pressingPackageId) &&
-    certificate.module === "certificate" &&
-    certificate.name === "Certificate" &&
-    certificate.typeParams.length === 0
-  );
-}
-
-/**
- * This copy's number in its pressing run. The current Record keeps issuance
- * details inside its embedded Certificate, so the canonical JSON shape is
- * `{ release_id, certificate: { number } }`.
- */
-function readRecordNumber(json: Record<string, unknown>): number | null {
-  return coerceNumber(record(json.certificate)?.number);
-}
-
-function readReleaseId(json: Record<string, unknown>): string | null {
-  const r = json.release_id;
-  return typeof r === "string" && r ? r : null;
+  return true;
 }
 
 /**
@@ -199,8 +164,8 @@ function readReleaseId(json: Record<string, unknown>): string | null {
 export async function getOwnedRecords(client: MisoClient, owner: string): Promise<OwnedRecord[]> {
   const out: OwnedRecord[] = [];
   let cursor: string | null = null;
-  const recordType = `${client.config.protocol.record}::record::Record`;
-  const pressingPackageId = client.config.protocol.pressing;
+  const sales = requireRecordSalesDeployment(client.config.recordSales);
+  const recordType = `${sales.recordPackageId}::record::Record`;
 
   for (let page = 0; page < MAX_PAGES; page++) {
     // Annotated: `cursor` is both an input and assigned from the result, which
@@ -211,18 +176,32 @@ export async function getOwnedRecords(client: MisoClient, owner: string): Promis
         type: recordType,
         cursor,
         limit: 50,
-        include: { json: true },
+        include: { content: true },
       });
     for (const obj of res.objects) {
-      if (!isCanonicalRecordType(obj.type, client.config.protocol.record, pressingPackageId)) {
+      if (!isCanonicalRecordType(obj.type, sales.recordPackageId)) {
         continue;
       }
-      const json = (obj.json ?? {}) as Record<string, unknown>;
+      if (!obj.content) throw new Error(`Record ${obj.objectId} has no BCS content`);
+      const record = recordContract.Record.parse(obj.content);
+      if (normalizeSuiAddress(record.id) !== normalizeSuiAddress(obj.objectId)) {
+        throw new Error(`Record ${obj.objectId} has mismatched embedded UID ${record.id}`);
+      }
+      const derived = deriveRecordId(record.pressing_id, record.number, sales.recordPackageId);
+      if (normalizeSuiAddress(derived) !== normalizeSuiAddress(obj.objectId)) {
+        throw new Error(`Record ${obj.objectId} is not derived from its Pressing and number`);
+      }
       out.push({
         id: obj.objectId,
         type: obj.type,
-        releaseId: readReleaseId(json),
-        number: readRecordNumber(json),
+        releaseId: record.release_id,
+        pressingId: record.pressing_id,
+        edition: record.edition,
+        number: record.number,
+        purchaseCurrency: normalizeStructTag(record.purchase_currency.name),
+        purchasePrice: record.purchase_price,
+        purchasedBy: record.purchased_by,
+        purchasedTimestampMs: record.purchased_timestamp_ms,
       });
     }
     if (!res.hasNextPage) break;
@@ -406,7 +385,7 @@ async function resolveVaultedReleaseCaps(
       const vault = vaultContract.Vault(networkContracts.release.ReleaseAdminCap).parse(
         object.content,
       );
-      const releaseId = vault.cap.value?.release_id;
+      const releaseId = vault.cap?.value?.release_id;
       if (releaseId) releasesByVault.set(object.objectId, releaseId);
     } catch {
       // Batch catalog discovery is best-effort per authority, matching the
@@ -615,20 +594,54 @@ export async function getWorkByCap(client: MisoClient, capId: string): Promise<W
 
 // ── Balance ──────────────────────────────────────────────────────────────────
 
+const decimalsByClient = new WeakMap<MisoClient, Map<string, Promise<number>>>();
+
+/** Resolve once per client/type. Failed lookups are evicted so a transient
+ * fullnode error cannot poison a long-lived API worker. */
+async function coinDecimals(client: MisoClient, coinType: string): Promise<number> {
+  let cache = decimalsByClient.get(client);
+  if (!cache) {
+    cache = new Map();
+    decimalsByClient.set(client, cache);
+  }
+  const key = normalizeStructTag(coinType);
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  const pending = client.protocol.core.getCoinMetadata({ coinType: key }).then(({ coinMetadata }) => {
+    const decimals = coinMetadata?.decimals;
+    if (!Number.isSafeInteger(decimals) || decimals! < 0 || decimals! > 18) {
+      throw new Error(`Coin metadata for ${key} has no supported decimal precision`);
+    }
+    return decimals!;
+  });
+  cache.set(key, pending);
+  try {
+    return await pending;
+  } catch (error) {
+    if (cache.get(key) === pending) cache.delete(key);
+    throw error;
+  }
+}
+
 /**
- * A wallet's spendable balance in one currency. `core.getBalance` totals coin
- * OBJECTS and the address balance, so funds that arrived either way are counted —
- * which matters because `balance::send_funds` (how the app transfers dollars)
- * credits the address balance, not a coin.
+ * A wallet's balance in one currency. Keep the aggregate and both Sui storage
+ * classes: callers using a `FundsWithdrawal` must never mistake coin-object
+ * value for immediately withdrawable address balance.
  */
 export async function getBalance(client: MisoClient, address: string, coinType?: string): Promise<Balance> {
   const type = coinType ?? client.config.money.usdCoinType;
-  const res = await client.protocol.core.getBalance({ owner: address, coinType: type });
+  const [res, decimals] = await Promise.all([
+    client.protocol.core.getBalance({ owner: address, coinType: type }),
+    coinDecimals(client, type),
+  ]);
   return {
     address: normalizeSuiAddress(address),
     coinType: type,
     balance: u64(res.balance.balance),
-    decimals: type === client.config.money.usdCoinType ? client.config.money.usdDecimals : 9,
+    coinBalance: u64(res.balance.coinBalance),
+    addressBalance: u64(res.balance.addressBalance),
+    decimals,
   };
 }
 

package/src/vault.ts

@@ -17,7 +17,7 @@ import type {
   TransactionArgument,
   TransactionObjectArgument,
 } from "@mysten/sui/transactions";
-import { normalizeStructTag } from "@mysten/sui/utils";
+import { deriveObjectID, normalizeStructTag } from "@mysten/sui/utils";
 import * as vault from "./contracts/vault/vault.ts";
 import * as compositionRoyaltyPool from "./contracts/composition_royalty_pool/composition_royalty_pool.ts";
 import * as recordingRoyaltyPool from "./contracts/recording_royalty_pool/recording_royalty_pool.ts";
@@ -30,6 +30,9 @@ import * as routedStake from "./contracts/routed_stake/routed_stake.ts";
 /** An object id resolved lazily when a transaction thunk is applied. */
 export type ObjectInput = string | TransactionObjectArgument;
 
+/** The framework singleton read by `balance::settled_funds_value`. */
+export const SUI_ACCUMULATOR_ROOT_OBJECT_ID = "0xacc";
+
 function object(tx: Transaction, value: ObjectInput): TransactionObjectArgument {
   return typeof value === "string" ? tx.object(value) : value;
 }
@@ -145,6 +148,8 @@ export function invokeWithAdminCap(
 export interface CustodyNewAdminCapParams {
   /** The freshly-created raw protocol cap, consumed into the Vault. */
   readonly adminCap: TransactionObjectArgument;
+  /** Shared singleton from which canonical Vault IDs are derived. */
+  readonly vaultRegistry: ObjectInput;
   readonly capType: string;
   readonly vaultPackageId: string;
   /** Recipient of the only owner-held authority: VaultAdminCap. */
@@ -162,6 +167,7 @@ export type AdminCapCustody =
   | {
       readonly kind: "vault";
       readonly owner: string | TransactionArgument;
+      readonly vaultRegistry: ObjectInput;
       readonly capType: string;
       readonly vaultPackageId: string;
       readonly configure?: CustodyNewAdminCapParams["configure"];
@@ -179,6 +185,7 @@ export function disposeNewAdminCap(
   }
   custodyNewAdminCap(tx, {
     adminCap,
+    vaultRegistry: custody.vaultRegistry,
     capType: custody.capType,
     vaultPackageId: custody.vaultPackageId,
     owner: custody.owner,
@@ -186,23 +193,60 @@ export function disposeNewAdminCap(
   });
 }
 
-/** Destroy a vault only while deliberately disposing of its returned raw cap. */
-export function destroyVault(
+/** Withdraw the raw capability while leaving its canonical Vault shell intact. */
+export function withdrawVaultCapability(
   tx: Transaction,
   params: {
     readonly vault: ObjectInput;
     readonly vaultAdminCap: ObjectInput;
     readonly capType: string;
     readonly vaultPackageId: string;
-    readonly disposition: AdminCapCustody;
   },
-): void {
-  const cap = tx.add(vault.destroy({
+): TransactionObjectArgument {
+  return tx.add(vault.withdrawCap({
     package: params.vaultPackageId,
     typeArguments: [params.capType],
     arguments: [object(tx, params.vault), object(tx, params.vaultAdminCap)],
   }));
-  disposeNewAdminCap(tx, cap, params.disposition);
+}
+
+/** Restore the one exact capability permanently assigned to a Vault. */
+export function restoreVaultCapability(
+  tx: Transaction,
+  params: {
+    readonly vault: ObjectInput;
+    readonly vaultAdminCap: ObjectInput;
+    readonly adminCap: ObjectInput;
+    readonly capType: string;
+    readonly vaultPackageId: string;
+  },
+): void {
+  tx.add(vault.restoreCap({
+    package: params.vaultPackageId,
+    typeArguments: [params.capType],
+    arguments: [
+      object(tx, params.vault),
+      object(tx, params.vaultAdminCap),
+      object(tx, params.adminCap),
+    ],
+  }));
+}
+
+/** Transfer the key-only VaultAdminCap through the Vault module. */
+export function transferVaultAdminCap(
+  tx: Transaction,
+  params: {
+    readonly vaultAdminCap: ObjectInput;
+    readonly owner: string | TransactionArgument;
+    readonly capType: string;
+    readonly vaultPackageId: string;
+  },
+): void {
+  tx.add(vault.transferAdminCap({
+    package: params.vaultPackageId,
+    typeArguments: [params.capType],
+    arguments: [object(tx, params.vaultAdminCap), params.owner],
+  }));
 }
 
 /**
@@ -217,7 +261,7 @@ export function custodyNewAdminCap(
     vault._new({
       package: params.vaultPackageId,
       typeArguments: [params.capType],
-      arguments: [params.adminCap],
+      arguments: [object(tx, params.vaultRegistry), params.adminCap],
     }),
   );
   const vaultObject = requiredVaultResult(created, 0, "vault::_new");
@@ -230,7 +274,43 @@ export function custodyNewAdminCap(
       arguments: [vaultObject],
     }),
   );
-  tx.transferObjects([vaultAdminCap], params.owner);
+  transferVaultAdminCap(tx, {
+    vaultAdminCap,
+    owner: params.owner,
+    capType: params.capType,
+    vaultPackageId: params.vaultPackageId,
+  });
+}
+
+export interface VaultIdParams {
+  readonly vaultRegistryId: string;
+  readonly capId: string;
+  readonly capType: string;
+  readonly vaultPackageId: string;
+}
+
+/** Derive the canonical Vault ID without an RPC lookup. */
+export function deriveVaultId(params: VaultIdParams): string {
+  const keyType = normalizeStructTag(
+    `${params.vaultPackageId}::vault::VaultKey<${params.capType}>`,
+  );
+  return deriveObjectID(
+    params.vaultRegistryId,
+    keyType,
+    vault.VaultKey.serialize([params.capId]).toBytes(),
+  );
+}
+
+/** Derive the canonical VaultAdminCap ID from its Vault ID. */
+export function deriveVaultAdminCapId(
+  vaultId: string,
+  vaultPackageId: string,
+): string {
+  return deriveObjectID(
+    vaultId,
+    `${vaultPackageId}::vault::VaultAdminCapKey`,
+    vault.VaultAdminCapKey.serialize([false]).toBytes(),
+  );
 }
 
 export interface CompositionRoyaltyPoolPluginParams {
@@ -299,7 +379,6 @@ export interface CompositionRoyaltyPoolCrankParams {
   readonly vault: TransactionObjectArgument;
   readonly composition: TransactionObjectArgument;
   readonly pool: TransactionObjectArgument;
-  readonly accumulatorRoot: TransactionObjectArgument;
   readonly compositionShareType: string;
   readonly currencyType: string;
   readonly pluginPackageId: string;
@@ -308,6 +387,9 @@ export interface CompositionRoyaltyPoolCrankParams {
 /** JSON-safe input for an on-chain u64. Numbers are rejected to prevent rounding. */
 export type U64Input = bigint | string | number;
 
+/** An exact scalar or the result of an earlier PTB command returning `u64`. */
+export type U64Argument = U64Input | TransactionArgument;
+
 /** Validate an SDK scalar before serializing it as a Move u64. */
 export function asU64(name: string, value: U64Input): bigint {
   if (typeof value === "number" && (!Number.isSafeInteger(value) || value < 0)) {
@@ -323,20 +405,79 @@ export function asU64(name: string, value: U64Input): bigint {
   return parsed;
 }
 
-/** Permissionless crank: sweep settled address funds into the canonical pool. */
-export function sweepCompositionRoyaltyPool(
+function asU64Argument(name: string, value: U64Argument): bigint | TransactionArgument {
+  if (
+    typeof value === "bigint" ||
+    typeof value === "string" ||
+    typeof value === "number"
+  ) {
+    return asU64(name, value);
+  }
+  return value;
+}
+
+/** Read the commit-settled accumulator balance for an address inside this PTB. */
+export function settledFundsValue(
+  tx: Transaction,
+  params: {
+    readonly address: string | TransactionArgument;
+    readonly currencyType: string;
+    readonly accumulatorRoot?: ObjectInput;
+  },
+): TransactionArgument {
+  return tx.moveCall({
+    target: "0x2::balance::settled_funds_value",
+    typeArguments: [params.currencyType],
+    arguments: [
+      object(tx, params.accumulatorRoot ?? SUI_ACCUMULATOR_ROOT_OBJECT_ID),
+      typeof params.address === "string"
+        ? tx.pure.address(params.address)
+        : params.address,
+    ],
+  });
+}
+
+/** Permissionless crank: redeem an exact Composition amount into its pool. */
+export function redeemAndDepositCompositionRoyaltyPool(
   tx: Transaction,
-  params: CompositionRoyaltyPoolCrankParams,
+  params: CompositionRoyaltyPoolCrankParams & {
+    readonly value: U64Argument;
+  },
 ): void {
   tx.add(
-    compositionRoyaltyPool.sweepAndDeposit({
+    compositionRoyaltyPool.redeemAndDeposit({
       package: params.pluginPackageId,
       typeArguments: [params.compositionShareType, params.currencyType],
-      arguments: [params.vault, params.composition, params.pool, params.accumulatorRoot],
+      arguments: [
+        params.vault,
+        params.composition,
+        params.pool,
+        asU64Argument("value", params.value),
+      ],
     }),
   );
 }
 
+/** Redeem exactly the framework-reported settled Composition funds. */
+export function settleCompositionRoyaltyPool(
+  tx: Transaction,
+  params: Omit<CompositionRoyaltyPoolCrankParams, "composition"> & {
+    readonly compositionId: string;
+    readonly accumulatorRoot?: ObjectInput;
+  },
+): void {
+  const value = settledFundsValue(tx, {
+    address: params.compositionId,
+    currencyType: params.currencyType,
+    accumulatorRoot: params.accumulatorRoot,
+  });
+  redeemAndDepositCompositionRoyaltyPool(tx, {
+    ...params,
+    composition: tx.object(params.compositionId),
+    value,
+  });
+}
+
 /** Permissionless crank: receive selected Composition-owned coins into the pool. */
 export function receiveCompositionRoyaltyPool(
   tx: Transaction,
@@ -435,7 +576,7 @@ export function receivePartyWalletBalance(
 /** Redeem an exact Party accumulator amount and return its Balance. */
 export function redeemPartyWalletBalance(
   tx: Transaction,
-  params: PartyWalletFundsParams & { readonly value: U64Input },
+  params: PartyWalletFundsParams & { readonly value: U64Argument },
 ): TransactionArgument {
   return tx.add(
     partyWallet.redeemBalance({
@@ -445,31 +586,30 @@ export function redeemPartyWalletBalance(
         params.vault,
         params.party,
         params.vaultAdminCap,
-        asU64("value", params.value),
+        asU64Argument("value", params.value),
       ],
     }),
   );
 }
 
-/** Sweep the Party's currently settled accumulator funds and return its Balance. */
-export function sweepPartyWalletBalance(
+/** Redeem exactly the framework-reported settled Party funds. */
+export function settlePartyWalletBalance(
   tx: Transaction,
-  params: PartyWalletFundsParams & {
-    readonly accumulatorRoot: TransactionObjectArgument;
+  params: Omit<PartyWalletFundsParams, "party"> & {
+    readonly partyId: string;
+    readonly accumulatorRoot?: ObjectInput;
   },
 ): TransactionArgument {
-  return tx.add(
-    partyWallet.sweepBalance({
-      package: params.pluginPackageId,
-      typeArguments: [params.currencyType],
-      arguments: [
-        params.vault,
-        params.party,
-        params.accumulatorRoot,
-        params.vaultAdminCap,
-      ],
-    }),
-  );
+  const value = settledFundsValue(tx, {
+    address: params.partyId,
+    currencyType: params.currencyType,
+    accumulatorRoot: params.accumulatorRoot,
+  });
+  return redeemPartyWalletBalance(tx, {
+    ...params,
+    party: tx.object(params.partyId),
+    value,
+  });
 }
 
 export function uninstallRecordingRoyaltyPoolPlugin(
@@ -525,31 +665,57 @@ export interface RecordingRoyaltyPoolCrankParams {
   readonly vault: TransactionObjectArgument;
   readonly recording: TransactionObjectArgument;
   readonly pool: TransactionObjectArgument;
-  readonly accumulatorRoot: TransactionObjectArgument;
   readonly recordingShareType: string;
   readonly compositionShareType: string;
   readonly currencyType: string;
   readonly pluginPackageId: string;
 }
 
-/** Permissionless crank: sweep settled address funds into the canonical pool. */
-export function sweepRecordingRoyaltyPool(
+/** Permissionless crank: redeem an exact Recording amount into its pool. */
+export function redeemAndDepositRecordingRoyaltyPool(
   tx: Transaction,
-  params: RecordingRoyaltyPoolCrankParams,
+  params: RecordingRoyaltyPoolCrankParams & {
+    readonly value: U64Argument;
+  },
 ): void {
   tx.add(
-    recordingRoyaltyPool.sweepAndDeposit({
+    recordingRoyaltyPool.redeemAndDeposit({
       package: params.pluginPackageId,
       typeArguments: [
         params.recordingShareType,
         params.compositionShareType,
         params.currencyType,
       ],
-      arguments: [params.vault, params.recording, params.pool, params.accumulatorRoot],
+      arguments: [
+        params.vault,
+        params.recording,
+        params.pool,
+        asU64Argument("value", params.value),
+      ],
     }),
   );
 }
 
+/** Redeem exactly the framework-reported settled Recording funds. */
+export function settleRecordingRoyaltyPool(
+  tx: Transaction,
+  params: Omit<RecordingRoyaltyPoolCrankParams, "recording"> & {
+    readonly recordingId: string;
+    readonly accumulatorRoot?: ObjectInput;
+  },
+): void {
+  const value = settledFundsValue(tx, {
+    address: params.recordingId,
+    currencyType: params.currencyType,
+    accumulatorRoot: params.accumulatorRoot,
+  });
+  redeemAndDepositRecordingRoyaltyPool(tx, {
+    ...params,
+    recording: tx.object(params.recordingId),
+    value,
+  });
+}
+
 /** Permissionless crank: receive selected Recording-owned coins into the pool. */
 export function receiveRecordingRoyaltyPool(
   tx: Transaction,
@@ -604,18 +770,39 @@ export function redeemAndDistributeReleaseRevenue(
   params: Omit<ReleaseRevenueDistributorPluginParams, "vaultAdminCap"> & {
     readonly release: TransactionObjectArgument;
     readonly currencyType: string;
-    readonly value: U64Input;
+    readonly value: U64Argument;
   },
 ): void {
   tx.add(
     releaseRevenueDistributor.redeemAndDistribute({
       package: params.pluginPackageId,
       typeArguments: [params.currencyType],
-      arguments: [params.vault, params.release, asU64("value", params.value)],
+      arguments: [params.vault, params.release, asU64Argument("value", params.value)],
     }),
   );
 }
 
+/** Redeem exactly the framework-reported settled Release funds and route them. */
+export function settleAndDistributeReleaseRevenue(
+  tx: Transaction,
+  params: Omit<ReleaseRevenueDistributorPluginParams, "vaultAdminCap"> & {
+    readonly releaseId: string;
+    readonly currencyType: string;
+    readonly accumulatorRoot?: ObjectInput;
+  },
+): void {
+  const value = settledFundsValue(tx, {
+    address: params.releaseId,
+    currencyType: params.currencyType,
+    accumulatorRoot: params.accumulatorRoot,
+  });
+  redeemAndDistributeReleaseRevenue(tx, {
+    ...params,
+    release: tx.object(params.releaseId),
+    value,
+  });
+}
+
 /** Permissionless crank: receive release-owned coins and route them by track BPS. */
 export function receiveAndDistributeReleaseRevenue(
   tx: Transaction,