@koralabs/kora-labs-common 6.9.1 → 6.9.3

package/mpt/index.d.ts

@@ -1,29 +1,39 @@
 import { Trie } from '@aiken-lang/merkle-patricia-forestry';
 import * as labelSet from './labelSet';
-import * as registryValue from './registryValue';
-export { labelSet, registryValue };
+export { labelSet };
 export { Trie };
+/**
+ * A minting-data MPT entry. A bare string is shorthand for a handle with no registry value
+ * (value = ""). The object form carries the key's on-chain value — the sorted CIP-67 label set
+ * (001-004) bytes. (The 3-free-virtual feature was removed, so keys no longer carry a free-name
+ * value; the only non-empty value is the label set, once the in-band MintLabelAssets path ships.)
+ */
+export interface MintingDataEntry {
+    name: string;
+    /** Sorted CIP-67 label set (001-004) hex. Empty/absent => value "". The in-band MintLabelAssets
+     * path is not on-chain yet, so callers pass "" today; flip to the real set when it ships. */
+    labels?: string;
+}
+type MintingDataInput = ReadonlyArray<string | MintingDataEntry>;
 /**
  * THE canonical minting-data MPT (a real {@link Trie}, for proof generation during mint/burn).
  * Consumers that only need the root hash should use {@link computeMintingDataRoot}; consumers that
- * generate proofs (the minting engine's verifyRootHash) keep the returned Trie. Value = "" per the
- * validator's `update_root` — see {@link computeMintingDataRoot} for the full rationale.
+ * generate proofs (the minting engine's verifyRootHash) keep the returned Trie.
+ *
+ * The value at each key is the sorted label-set bytes (CIP-67 001-004), byte-identical to what the
+ * on-chain `demimntmpt` validator stores (`mpt.update` verifies the old bytes). A handle with no
+ * labels => value "" (the `update_root` `mpt.insert(root, name, #"")` case), so passing bare strings
+ * reproduces the empty-valued root exactly — which is every key today (labels not yet on-chain).
  */
-export declare const buildMintingDataTrie: (handleNames: string[]) => Promise<Trie>;
+export declare const buildMintingDataTrie: (handles: MintingDataInput) => Promise<Trie>;
 /**
  * THE canonical minting-data MPT root. Every Node service (api.handle.me, the minting engine,
  * handle.me/bff) and the on-chain mirror (@koralabs/handles-decentralized-minting) MUST compute
  * the root through this one function, so the off-chain root can never drift from what the
- * validator maintains. (It drifted before because api + engine each re-derived it independently.)
- *
- * Value = "" (empty) per the legacy/DeMi mint validator's `update_root`:
- *   `mpt.insert(root, handle_name, #"", proof)`
- * Labels (001/002…) are NOT in the root until the in-band `MintLabelAssets` path is deployed;
- * until then the off-chain root MUST use empty values or it diverges from chain on every labeled
- * handle. When labels go in-band, change ONLY this function (accept a registry arg, set
- * value = registryValue.encode(freeNames, labels)) and every consumer moves in lockstep.
+ * validator maintains. (It drifted before because api + engine each re-derived it independently —
+ * and again when this function ignored the free-virtual registry value the contract writes.)
  *
  * Order-independent (MPT root is determined by the key/value set), so callers need not sort;
  * duplicate keys are de-duped to avoid a Trie insert throw.
  */
-export declare const computeMintingDataRoot: (handleNames: string[]) => Promise<string>;
+export declare const computeMintingDataRoot: (handles: MintingDataInput) => Promise<string>;

package/mpt/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeMintingDataRoot = exports.buildMintingDataTrie = exports.Trie = exports.registryValue = exports.labelSet = void 0;
+exports.computeMintingDataRoot = exports.buildMintingDataTrie = exports.Trie = exports.labelSet = void 0;
 // Server-only (Node) MPT module. Pulls @aiken-lang/merkle-patricia-forestry (native `level`/`blake2b`)
 // so it is NOT re-exported from the package root — import it from the subpath:
 //   import { computeMintingDataRoot } from '@koralabs/kora-labs-common/mpt';
@@ -32,39 +32,48 @@ const merkle_patricia_forestry_1 = require("@aiken-lang/merkle-patricia-forestry
 Object.defineProperty(exports, "Trie", { enumerable: true, get: function () { return merkle_patricia_forestry_1.Trie; } });
 const labelSet = __importStar(require("./labelSet"));
 exports.labelSet = labelSet;
-const registryValue = __importStar(require("./registryValue"));
-exports.registryValue = registryValue;
 const EMPTY_ROOT_HEX = Buffer.alloc(32).toString('hex');
 /**
  * THE canonical minting-data MPT (a real {@link Trie}, for proof generation during mint/burn).
  * Consumers that only need the root hash should use {@link computeMintingDataRoot}; consumers that
- * generate proofs (the minting engine's verifyRootHash) keep the returned Trie. Value = "" per the
- * validator's `update_root` — see {@link computeMintingDataRoot} for the full rationale.
+ * generate proofs (the minting engine's verifyRootHash) keep the returned Trie.
+ *
+ * The value at each key is the sorted label-set bytes (CIP-67 001-004), byte-identical to what the
+ * on-chain `demimntmpt` validator stores (`mpt.update` verifies the old bytes). A handle with no
+ * labels => value "" (the `update_root` `mpt.insert(root, name, #"")` case), so passing bare strings
+ * reproduces the empty-valued root exactly — which is every key today (labels not yet on-chain).
  */
-const buildMintingDataTrie = async (handleNames) => {
-    const uniqueKeys = Array.from(new Set(handleNames));
-    return merkle_patricia_forestry_1.Trie.fromList(uniqueKeys.map((key) => ({ key, value: '' })));
+const buildMintingDataTrie = async (handles) => {
+    var _a;
+    const seen = new Set();
+    const entries = [];
+    for (const handle of handles) {
+        const name = typeof handle === 'string' ? handle : handle.name;
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        const labels = typeof handle === 'string' ? '' : (_a = handle.labels) !== null && _a !== void 0 ? _a : '';
+        // The key's value is the sorted label-set bytes (CIP-67 001-004), or "" when it holds none.
+        // The 3-free-virtual feature was removed, so no key carries a free-name value any more.
+        // MPF treats string values as UTF-8; supply decoded bytes for a non-empty label set.
+        entries.push({ key: name, value: labels ? Buffer.from(labels, 'hex') : '' });
+    }
+    return merkle_patricia_forestry_1.Trie.fromList(entries);
 };
 exports.buildMintingDataTrie = buildMintingDataTrie;
 /**
  * THE canonical minting-data MPT root. Every Node service (api.handle.me, the minting engine,
  * handle.me/bff) and the on-chain mirror (@koralabs/handles-decentralized-minting) MUST compute
  * the root through this one function, so the off-chain root can never drift from what the
- * validator maintains. (It drifted before because api + engine each re-derived it independently.)
- *
- * Value = "" (empty) per the legacy/DeMi mint validator's `update_root`:
- *   `mpt.insert(root, handle_name, #"", proof)`
- * Labels (001/002…) are NOT in the root until the in-band `MintLabelAssets` path is deployed;
- * until then the off-chain root MUST use empty values or it diverges from chain on every labeled
- * handle. When labels go in-band, change ONLY this function (accept a registry arg, set
- * value = registryValue.encode(freeNames, labels)) and every consumer moves in lockstep.
+ * validator maintains. (It drifted before because api + engine each re-derived it independently —
+ * and again when this function ignored the free-virtual registry value the contract writes.)
  *
  * Order-independent (MPT root is determined by the key/value set), so callers need not sort;
  * duplicate keys are de-duped to avoid a Trie insert throw.
  */
-const computeMintingDataRoot = async (handleNames) => {
+const computeMintingDataRoot = async (handles) => {
     var _a, _b;
-    const trie = await (0, exports.buildMintingDataTrie)(handleNames);
+    const trie = await (0, exports.buildMintingDataTrie)(handles);
     return (_b = (_a = trie.hash) === null || _a === void 0 ? void 0 : _a.toString('hex')) !== null && _b !== void 0 ? _b : EMPTY_ROOT_HEX;
 };
 exports.computeMintingDataRoot = computeMintingDataRoot;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.9.1",
+    "version": "6.9.3",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",

package/mpt/registryValue.d.ts

@@ -1,25 +0,0 @@
-/**
- * Byte-identical to on-chain `registry_value.encode(free_names, labels)`.
- *   free_names == []  -> labels (an empty handle stays "", any pure-label handle is WS1-identical)
- *   free_names != []  -> "ff" ++ serialise_data(free_names) ++ labels
- */
-export declare const encode: (freeNames: string[], labels: string) => string;
-/** A free slot is available iff the root holds fewer than the configured free count. */
-export declare const hasFreeSlot: (freeNames: string[], freeVirtualCount: number) => boolean;
-/** Is this sub-name one of the root's current free names? */
-export declare const hasFreeName: (freeNames: string[], name: string) => boolean;
-/**
- * Add a sub-name to the free set (a free private-virtual MINT). Prepends (mirrors aiken
- * `list.push`) and is idempotent — the prepend order is part of the encoded bytes, so it MUST
- * match the contract's `add_free_name`.
- */
-export declare const addFreeName: (freeNames: string[], name: string) => string[];
-/**
- * Remove a sub-name from the free set (a free private-virtual BURN → reopen its slot). No-op if
- * the name isn't in the set (a paid sub's burn doesn't touch the allowance). Preserves order.
- */
-export declare const removeFreeName: (freeNames: string[], name: string) => string[];
-/** Parse a stored comma-hex free-name list ("" -> []). */
-export declare const parseFreeNames: (csv: string | null | undefined) => string[];
-/** Serialize a free-name set back to comma-hex for storage. */
-export declare const serializeFreeNames: (freeNames: string[]) => string;

package/mpt/registryValue.js

@@ -1,78 +0,0 @@
-"use strict";
-// DSH-402 — TypeScript port of the on-chain `registry_value.ak`. The MPT value at a ROOT
-// handle key carries, alongside the WS1 label set, the SET OF NAMES of the root's currently-held
-// FREE private virtual subs (at most `free_virtual_count`). This MUST stay byte-identical to the
-// aiken `encode` so the off-chain `old_value`/`new_value` match what the validator reconstructs
-// (`mpt.update` verifies the old bytes are in the trie). If these diverge, every free-virtual
-// `mpt.update` fails on-chain.
-//
-// CANONICAL HOME: see ./labelSet.ts — this is the single shared definition for all Node services.
-//
-// Representation: free names and labels are lowercase hex strings; `encode` returns a hex string
-// ("" = empty value). Names are sub-handle name bytes; labels are concatenated 4-byte CIP-67
-// prefixes (each starting 0x00), so a leading 0xff marker can never collide with a label set.
-//
-// Encoding (mirrors `registry_value.ak`):
-//   - free_names == []  ->  labels                                  (backward compatible with WS1)
-//   - free_names != []  ->  0xff ++ serialise_data(free_names) ++ labels
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.serializeFreeNames = exports.parseFreeNames = exports.removeFreeName = exports.addFreeName = exports.hasFreeName = exports.hasFreeSlot = exports.encode = void 0;
-// CBOR header for a Plutus `Data` byte string (major type 2). Handle/sub names are CIP-67 asset
-// names (<= 32 bytes), so a single definite-length chunk always suffices; Plutus only chunks
-// byte strings longer than 64 bytes, which a valid handle name can never be — throw rather than
-// emit divergent bytes for an impossible input.
-const cborByteString = (hex) => {
-    const byteLen = hex.length / 2;
-    if (!Number.isInteger(byteLen)) {
-        throw new Error(`free name is not valid hex (odd length): ${hex}`);
-    }
-    if (byteLen < 24)
-        return (0x40 | byteLen).toString(16).padStart(2, '0') + hex;
-    if (byteLen <= 64)
-        return '58' + byteLen.toString(16).padStart(2, '0') + hex;
-    throw new Error(`free name exceeds 64 bytes (Plutus would chunk): ${hex}`);
-};
-// Plutus `Data` CBOR of a non-empty `List<ByteArray>` (indefinite-length array).
-const serialiseData = (freeNames) => '9f' + freeNames.map((n) => cborByteString(n.toLowerCase())).join('') + 'ff';
-/**
- * Byte-identical to on-chain `registry_value.encode(free_names, labels)`.
- *   free_names == []  -> labels (an empty handle stays "", any pure-label handle is WS1-identical)
- *   free_names != []  -> "ff" ++ serialise_data(free_names) ++ labels
- */
-const encode = (freeNames, labels) => {
-    const l = labels.toLowerCase();
-    return freeNames.length === 0 ? l : 'ff' + serialiseData(freeNames) + l;
-};
-exports.encode = encode;
-/** A free slot is available iff the root holds fewer than the configured free count. */
-const hasFreeSlot = (freeNames, freeVirtualCount) => freeNames.length < freeVirtualCount;
-exports.hasFreeSlot = hasFreeSlot;
-/** Is this sub-name one of the root's current free names? */
-const hasFreeName = (freeNames, name) => freeNames.map((n) => n.toLowerCase()).includes(name.toLowerCase());
-exports.hasFreeName = hasFreeName;
-/**
- * Add a sub-name to the free set (a free private-virtual MINT). Prepends (mirrors aiken
- * `list.push`) and is idempotent — the prepend order is part of the encoded bytes, so it MUST
- * match the contract's `add_free_name`.
- */
-const addFreeName = (freeNames, name) => {
-    const n = name.toLowerCase();
-    const lower = freeNames.map((x) => x.toLowerCase());
-    return lower.includes(n) ? lower : [n, ...lower];
-};
-exports.addFreeName = addFreeName;
-/**
- * Remove a sub-name from the free set (a free private-virtual BURN → reopen its slot). No-op if
- * the name isn't in the set (a paid sub's burn doesn't touch the allowance). Preserves order.
- */
-const removeFreeName = (freeNames, name) => {
-    const n = name.toLowerCase();
-    return freeNames.map((x) => x.toLowerCase()).filter((x) => x !== n);
-};
-exports.removeFreeName = removeFreeName;
-/** Parse a stored comma-hex free-name list ("" -> []). */
-const parseFreeNames = (csv) => (csv ? csv.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) : []);
-exports.parseFreeNames = parseFreeNames;
-/** Serialize a free-name set back to comma-hex for storage. */
-const serializeFreeNames = (freeNames) => freeNames.map((n) => n.toLowerCase()).join(',');
-exports.serializeFreeNames = serializeFreeNames;