@koralabs/kora-labs-common 6.9.0 → 6.9.2

package/mpt/index.d.ts

@@ -1,20 +1,43 @@
+import { Trie } from '@aiken-lang/merkle-patricia-forestry';
 import * as labelSet from './labelSet';
 import * as registryValue from './registryValue';
 export { labelSet, registryValue };
+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 registry value the on-chain validator stores at the
+ * key: `registryValue.encode(freeNames, labels)`.
+ *   - `freeNames`: a ROOT's currently-claimed FREE private-virtual sub names (the free-virtual
+ *     allowance). The DeMi free-virtual mint/burn path writes this into the root key's value, so it
+ *     MUST be supplied or the off-chain root drifts from chain on every root holding a free virtual.
+ *   - `labels`: the sorted CIP-67 label set (001-004). The in-band `MintLabelAssets` path is NOT
+ *     yet deployed on-chain, so callers pass "" today; flip to the real label set when it ships.
+ */
+export interface MintingDataEntry {
+    name: string;
+    freeNames?: string[];
+    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.
+ *
+ * The value at each key is `registryValue.encode(freeNames, labels)` — byte-identical to what the
+ * on-chain `demimntmpt` validator stores (`mpt.update` verifies the old bytes). A handle with no
+ * free names and no labels encodes to "" (the legacy `update_root` `mpt.insert(root, name, #"")`
+ * case), so passing bare strings reproduces the empty-valued root exactly.
+ */
+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,37 +23,60 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeMintingDataRoot = exports.registryValue = exports.labelSet = void 0;
+exports.computeMintingDataRoot = exports.buildMintingDataTrie = exports.Trie = exports.registryValue = 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';
 // Mirrors the './aws' server-only convention; keeps the package root isomorphic/browser-safe.
 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.
+ *
+ * The value at each key is `registryValue.encode(freeNames, labels)` — byte-identical to what the
+ * on-chain `demimntmpt` validator stores (`mpt.update` verifies the old bytes). A handle with no
+ * free names and no labels encodes to "" (the legacy `update_root` `mpt.insert(root, name, #"")`
+ * case), so passing bare strings reproduces the empty-valued root exactly.
+ */
+const buildMintingDataTrie = async (handles) => {
+    var _a, _b;
+    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 freeNames = typeof handle === 'string' ? [] : (_a = handle.freeNames) !== null && _a !== void 0 ? _a : [];
+        const labels = typeof handle === 'string' ? '' : (_b = handle.labels) !== null && _b !== void 0 ? _b : '';
+        const encoded = registryValue.encode(freeNames, labels);
+        // MPF treats string values as UTF-8; supply the decoded bytes for a non-empty registry
+        // value, and "" (an empty value) for the common no-registry case.
+        entries.push({ key: name, value: encoded ? Buffer.from(encoded, '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 uniqueKeys = Array.from(new Set(handleNames));
-    const trie = await merkle_patricia_forestry_1.Trie.fromList(uniqueKeys.map((key) => ({ key, value: '' })));
+    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.0",
+    "version": "6.9.2",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",