@koralabs/kora-labs-common 6.8.1 → 6.9.1

package/mpt/index.d.ts

@@ -0,0 +1,29 @@
+import { Trie } from '@aiken-lang/merkle-patricia-forestry';
+import * as labelSet from './labelSet';
+import * as registryValue from './registryValue';
+export { labelSet, registryValue };
+export { Trie };
+/**
+ * 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.
+ */
+export declare const buildMintingDataTrie: (handleNames: string[]) => 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.
+ *
+ * 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>;

package/mpt/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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. Value = "" per the
+ * validator's `update_root` — see {@link computeMintingDataRoot} for the full rationale.
+ */
+const buildMintingDataTrie = async (handleNames) => {
+    const uniqueKeys = Array.from(new Set(handleNames));
+    return merkle_patricia_forestry_1.Trie.fromList(uniqueKeys.map((key) => ({ key, value: '' })));
+};
+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.
+ *
+ * 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) => {
+    var _a, _b;
+    const trie = await (0, exports.buildMintingDataTrie)(handleNames);
+    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/mpt/labelSet.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/** Does the canonical label set contain `label`? */
+export declare const contains: (set: string, label: string) => boolean;
+/** Insert `label`, keeping the set sorted ascending. Throws if already present. */
+export declare const insert: (set: string, label: string) => string;
+/** Remove `label`. Throws if absent. */
+export declare const remove: (set: string, label: string) => string;
+/** Apply a +1 (add) / -1 (remove) delta — couples the value change to the tx mint/burn. */
+export declare const apply: (set: string, label: string, amount: bigint) => string;
+/** The raw value bytes to store in the Trie (UTF-8-safe). */
+export declare const valueBuffer: (set: string) => Buffer;

package/mpt/labelSet.js

@@ -0,0 +1,70 @@
+"use strict";
+// WS1 — TypeScript port of the on-chain `label_set.ak` value encoding. The MPT value for a
+// handle key is the canonical (sorted) concatenation of fixed 4-byte CIP-67 label prefixes,
+// represented here as a lowercase hex string ("" = empty set). This MUST stay byte-identical
+// to the aiken encoding so the off-chain `old_value`/`new_value` match what the validator
+// reconstructs (`mpt.update` verifies the old bytes are in the trie).
+//
+// CANONICAL HOME: this lived (duplicated) in @koralabs/handles-decentralized-minting/store and
+// was re-derived again in api.handle.me + the minting engine. Those independent copies drifted
+// (the root went out of sync across services). It now lives ONCE here so every Node service
+// computes the registry value identically. See ./index.ts `computeMintingDataRoot`.
+//
+// Trie note: the JS Merkle-Patricia-Forestry treats string values as UTF-8, so insert the
+// value bytes via `Buffer.from(hex, "hex")` (see `valueBuffer`), not the hex string itself.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.valueBuffer = exports.apply = exports.remove = exports.insert = exports.contains = void 0;
+const LABEL_WIDTH_HEX = 8; // 4 bytes
+const chunks = (set) => {
+    const out = [];
+    for (let i = 0; i < set.length; i += LABEL_WIDTH_HEX) {
+        out.push(set.slice(i, i + LABEL_WIDTH_HEX));
+    }
+    return out;
+};
+const normalizeLabel = (label) => {
+    const l = label.toLowerCase();
+    if (l.length !== LABEL_WIDTH_HEX) {
+        throw new Error(`label must be ${LABEL_WIDTH_HEX} hex chars (4 bytes): ${label}`);
+    }
+    return l;
+};
+/** Does the canonical label set contain `label`? */
+const contains = (set, label) => chunks(set.toLowerCase()).includes(normalizeLabel(label));
+exports.contains = contains;
+/** Insert `label`, keeping the set sorted ascending. Throws if already present. */
+const insert = (set, label) => {
+    const l = normalizeLabel(label);
+    const cs = chunks(set.toLowerCase());
+    if (cs.includes(l))
+        throw new Error('LABEL_ALREADY_PRESENT');
+    cs.push(l);
+    // fixed-width hex sorts lexicographically == on-chain byte order
+    cs.sort();
+    return cs.join('');
+};
+exports.insert = insert;
+/** Remove `label`. Throws if absent. */
+const remove = (set, label) => {
+    const l = normalizeLabel(label);
+    const cs = chunks(set.toLowerCase());
+    const idx = cs.indexOf(l);
+    if (idx < 0)
+        throw new Error('LABEL_ABSENT');
+    cs.splice(idx, 1);
+    return cs.join('');
+};
+exports.remove = remove;
+/** Apply a +1 (add) / -1 (remove) delta — couples the value change to the tx mint/burn. */
+const apply = (set, label, amount) => {
+    // BigInt(1)/BigInt(-1) rather than 1n/-1n literals: klc targets es2018.
+    if (amount === BigInt(1))
+        return (0, exports.insert)(set, label);
+    if (amount === BigInt(-1))
+        return (0, exports.remove)(set, label);
+    throw new Error('INVALID_AMOUNT');
+};
+exports.apply = apply;
+/** The raw value bytes to store in the Trie (UTF-8-safe). */
+const valueBuffer = (set) => Buffer.from(set, 'hex');
+exports.valueBuffer = valueBuffer;

package/mpt/registryValue.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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

@@ -0,0 +1,78 @@
+"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;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.8.1",
+    "version": "6.9.1",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",
@@ -37,6 +37,7 @@
     "author": "",
     "license": "ISC",
     "devDependencies": {
+        "@aiken-lang/merkle-patricia-forestry": "^1.2.0",
         "@aws-sdk/client-dynamodb": "^3.549.0",
         "@aws-sdk/lib-dynamodb": "^3.549.0",
         "@types/jest": "^30.0.0",
@@ -63,5 +64,13 @@
     },
     "overrides": {
         "js-yaml": "^4.2.0"
+    },
+    "peerDependencies": {
+        "@aiken-lang/merkle-patricia-forestry": "^1.2.0"
+    },
+    "peerDependenciesMeta": {
+        "@aiken-lang/merkle-patricia-forestry": {
+            "optional": true
+        }
     }
 }