@unlink-xyz/core 0.1.0

package/dist/key-derivation/bech32.js

@@ -0,0 +1,86 @@
+import { bech32m } from "@scure/base";
+import { ByteLength, ByteUtils } from "./bytes.js";
+export const ADDRESS_VERSION = 1;
+export const ADDRESS_LENGTH_LIMIT = 127;
+export const ALL_CHAINS_NETWORK_ID = "ffffffffffffffff";
+const PREFIX = "0zk";
+const XOR_SALT = new TextEncoder().encode("unlink");
+/**
+ * XOR the network identifier with a static salt to keep addresses compact and avoid
+ * exposing raw chain IDs directly (mirrors the reference implementation).
+ */
+const xorNetworkID = (networkID) => {
+    const bytes = ByteUtils.hexStringToBytes(networkID);
+    const result = new Uint8Array(bytes.length);
+    const saltLength = XOR_SALT.length;
+    for (let i = 0; i < bytes.length; i += 1) {
+        const byte = bytes[i] ?? 0;
+        let saltByte = 0;
+        if (saltLength > 0) {
+            const saltIndex = i % saltLength;
+            saltByte = XOR_SALT[saltIndex] ?? 0;
+        }
+        result[i] = byte ^ saltByte;
+    }
+    return ByteUtils.bytesToHex(result);
+};
+const chainToNetworkID = (chain) => {
+    if (!chain)
+        return ALL_CHAINS_NETWORK_ID;
+    const { type, id } = chain;
+    const typeHex = (type & 0xff).toString(16).padStart(2, "0");
+    const idHex = BigInt(id).toString(16).padStart(14, "0");
+    return `${typeHex}${idHex}`;
+};
+const networkIDToChain = (networkID) => {
+    if (networkID === ALL_CHAINS_NETWORK_ID) {
+        return undefined;
+    }
+    const type = parseInt(networkID.slice(0, 2), 16);
+    const id = parseInt(networkID.slice(2), 16);
+    return { type, id };
+};
+/**
+ * Encode address metadata into a Bech32m string with the 0zk prefix.
+ */
+export const encodeAddress = (addressData) => {
+    const versionHex = (addressData.version ?? ADDRESS_VERSION)
+        .toString(16)
+        .padStart(2, "0");
+    const masterPublicKey = ByteUtils.nToHex(addressData.masterPublicKey, ByteLength.UINT_256, false);
+    const viewingPublicKey = ByteUtils.formatToByteLength(addressData.viewingPublicKey, ByteLength.UINT_256);
+    const networkID = xorNetworkID(chainToNetworkID(addressData.chain));
+    const payloadHex = `${versionHex}${masterPublicKey}${networkID}${viewingPublicKey}`;
+    const payload = ByteUtils.hexStringToBytes(payloadHex);
+    return bech32m.encode(PREFIX, bech32m.toWords(payload), ADDRESS_LENGTH_LIMIT);
+};
+/**
+ * Decode and validate a Bech32m address, returning the structured payload.
+ */
+export const decodeAddress = (address) => {
+    if (!address) {
+        throw new Error("No address to decode");
+    }
+    const decoded = bech32m.decode(address, ADDRESS_LENGTH_LIMIT);
+    if (decoded.prefix !== PREFIX) {
+        throw new Error("Invalid address prefix");
+    }
+    const payloadHex = ByteUtils.hexlify(bech32m.fromWords(decoded.words));
+    if (payloadHex.length !== 2 + 64 + 16 + 64) {
+        throw new Error("Incorrect address payload length");
+    }
+    const version = parseInt(payloadHex.slice(0, 2), 16);
+    if (version !== ADDRESS_VERSION) {
+        throw new Error("Incorrect address version");
+    }
+    const masterPublicKey = ByteUtils.hexToBigInt(payloadHex.slice(2, 66));
+    const networkID = xorNetworkID(payloadHex.slice(66, 82));
+    const viewingPublicKey = ByteUtils.hexStringToBytes(payloadHex.slice(82, 146));
+    const chain = networkIDToChain(networkID);
+    return {
+        version,
+        masterPublicKey,
+        viewingPublicKey,
+        chain,
+    };
+};

package/dist/key-derivation/bip32.d.ts

@@ -0,0 +1,17 @@
+export type KeyNode = {
+    chainKey: string;
+    chainCode: string;
+};
+/**
+ * Parse a derivation path into hardened segment indexes.
+ */
+export declare const getPathSegments: (path: string) => number[];
+/**
+ * Perform hardened child derivation using the BabyJubJub curve seed.
+ */
+export declare const childKeyDerivationHardened: (node: KeyNode, index: number, offset?: number) => KeyNode;
+/**
+ * Create the root BIP-32 node from a BIP-39 seed.
+ */
+export declare const getMasterKeyFromSeed: (seed: string) => KeyNode;
+//# sourceMappingURL=bip32.d.ts.map

package/dist/key-derivation/bip32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip32.d.ts","sourceRoot":"","sources":["../../key-derivation/bip32.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AASF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MAAM,EASpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,MAAM,OAAO,EACb,OAAO,MAAM,EACb,SAAQ,MAAmB,KAC1B,OAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,OAKnD,CAAC"}

package/dist/key-derivation/bip32.js

@@ -0,0 +1,41 @@
+import { ByteUtils, fromUTF8String } from "./bytes.js";
+import { sha512HMAC } from "./hash.js";
+const CURVE_SEED = fromUTF8String("babyjubjub seed");
+// Validates derivation paths of the form m/... with hardened segments.
+const PATH_REGEX = /^m(\/[0-9]+')+$/;
+const isValidPath = (path) => {
+    return PATH_REGEX.test(path);
+};
+/**
+ * Parse a derivation path into hardened segment indexes.
+ */
+export const getPathSegments = (path) => {
+    if (!isValidPath(path)) {
+        throw new Error("Invalid derivation path");
+    }
+    return path
+        .split("/")
+        .slice(1)
+        .map((segment) => segment.replace("'", ""))
+        .map((segment) => parseInt(segment, 10));
+};
+/**
+ * Perform hardened child derivation using the BabyJubJub curve seed.
+ */
+export const childKeyDerivationHardened = (node, index, offset = 0x80000000) => {
+    const indexFormatted = ByteUtils.padToLength(index + offset, 4);
+    const preImage = `00${node.chainKey}${indexFormatted}`;
+    const I = sha512HMAC(node.chainCode, preImage);
+    const chainKey = I.slice(0, 64);
+    const chainCode = I.slice(64);
+    return { chainKey, chainCode };
+};
+/**
+ * Create the root BIP-32 node from a BIP-39 seed.
+ */
+export const getMasterKeyFromSeed = (seed) => {
+    const I = sha512HMAC(CURVE_SEED, seed);
+    const chainKey = I.slice(0, 64);
+    const chainCode = I.slice(64);
+    return { chainKey, chainCode };
+};

package/dist/key-derivation/bip39.d.ts

@@ -0,0 +1,22 @@
+export declare class Mnemonic {
+    /**
+     * Generate a BIP-39 mnemonic using the English wordlist.
+     */
+    static generate(strength?: 128 | 192 | 256): string;
+    /**
+     * Validate a mnemonic against the English wordlist checksum.
+     */
+    static validate(mnemonic: string): boolean;
+    /**
+     * Convert a mnemonic to a hex-encoded BIP-39 seed. Optional password supported.
+     */
+    static toSeed(mnemonic: string, password?: string): string;
+    static toEntropy(mnemonic: string): string;
+    static fromEntropy(entropyHex: string): string;
+    /**
+     * Convenience helper: derive a 0x private key for non-0zk flows.
+     */
+    static to0xPrivateKey(mnemonic: string, derivationIndex?: number): string;
+    static to0xAddress(mnemonic: string, derivationIndex?: number): string;
+}
+//# sourceMappingURL=bip39.d.ts.map

package/dist/key-derivation/bip39.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bip39.d.ts","sourceRoot":"","sources":["../../key-derivation/bip39.ts"],"names":[],"mappings":"AAqBA,qBAAa,QAAQ;IACnB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,GAAE,GAAG,GAAG,GAAG,GAAG,GAAS,GAAG,MAAM;IAIxD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI1C;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM;IAK9D,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAK1C,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAK9C;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM;IAWzE,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM;CAOvE"}

package/dist/key-derivation/bip39.js

@@ -0,0 +1,56 @@
+import { entropyToMnemonic, generateMnemonic, mnemonicToEntropy, mnemonicToSeedSync, validateMnemonic, } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { HDKey } from "ethereum-cryptography/hdkey";
+import { Mnemonic as EthersMnemonic, HDNodeWallet } from "ethers";
+import { ByteUtils } from "./bytes.js";
+/**
+ * Standard ETH derivation path helper for convenience utilities below.
+ * Not used for 0zk accounts but kept for backwards compatibility.
+ */
+const derivationPath = (index = 0) => {
+    return `m/44'/60'/0'/0/${index}`;
+};
+export class Mnemonic {
+    /**
+     * Generate a BIP-39 mnemonic using the English wordlist.
+     */
+    static generate(strength = 128) {
+        return generateMnemonic(wordlist, strength);
+    }
+    /**
+     * Validate a mnemonic against the English wordlist checksum.
+     */
+    static validate(mnemonic) {
+        return validateMnemonic(mnemonic, wordlist);
+    }
+    /**
+     * Convert a mnemonic to a hex-encoded BIP-39 seed. Optional password supported.
+     */
+    static toSeed(mnemonic, password = "") {
+        const seed = mnemonicToSeedSync(mnemonic, password);
+        return ByteUtils.bytesToHex(seed);
+    }
+    static toEntropy(mnemonic) {
+        const entropy = mnemonicToEntropy(mnemonic, wordlist);
+        return ByteUtils.bytesToHex(entropy);
+    }
+    static fromEntropy(entropyHex) {
+        const entropy = ByteUtils.hexStringToBytes(entropyHex);
+        return entropyToMnemonic(entropy, wordlist);
+    }
+    /**
+     * Convenience helper: derive a 0x private key for non-0zk flows.
+     */
+    static to0xPrivateKey(mnemonic, derivationIndex) {
+        const seed = mnemonicToSeedSync(mnemonic);
+        const node = HDKey.fromMasterSeed(Buffer.from(seed)).derive(derivationPath(derivationIndex));
+        if (!node.privateKey) {
+            throw new Error("Failed to derive private key");
+        }
+        return ByteUtils.bytesToHex(node.privateKey);
+    }
+    static to0xAddress(mnemonic, derivationIndex) {
+        const wallet = HDNodeWallet.fromMnemonic(EthersMnemonic.fromPhrase(mnemonic), derivationPath(derivationIndex));
+        return wallet.address;
+    }
+}

package/dist/key-derivation/bytes.d.ts

@@ -0,0 +1,19 @@
+export declare enum ByteLength {
+    UINT_256 = 32,
+    UINT_512 = 64
+}
+export type BytesData = string | number | bigint | Uint8Array | ArrayLike<number>;
+export declare class ByteUtils {
+    static prefix0x(value: string): string;
+    static strip0x(value: string): string;
+    static hexlify(data: BytesData): string;
+    static bytesToHex(bytes: Uint8Array): string;
+    static hexStringToBytes(hex: string): Uint8Array;
+    static arrayify(data: BytesData): Uint8Array;
+    static hexToBigInt(hex: string): bigint;
+    static padToLength(data: BytesData, length: number, side?: "left" | "right"): string;
+    static formatToByteLength(data: BytesData, length: ByteLength): string;
+    static nToHex(value: bigint, length: ByteLength, prefix?: boolean): string;
+}
+export declare function fromUTF8String(value: string): string;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/key-derivation/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../key-derivation/bytes.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,QAAQ,KAAK;IACb,QAAQ,KAAK;CACd;AAED,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,MAAM,GACN,UAAU,GACV,SAAS,CAAC,MAAM,CAAC,CAAC;AAkBtB,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAItC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIrC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM;IAavC,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM;IAQ5C,MAAM,CAAC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAUhD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU;IAa5C,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIvC,MAAM,CAAC,WAAW,CAChB,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAM,GAAG,OAAgB,GAC9B,MAAM;IAWT,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM;IAQtE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,UAAQ,GAAG,MAAM;CAIzE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/key-derivation/bytes.js

@@ -0,0 +1,92 @@
+export var ByteLength;
+(function (ByteLength) {
+    ByteLength[ByteLength["UINT_256"] = 32] = "UINT_256";
+    ByteLength[ByteLength["UINT_512"] = 64] = "UINT_512";
+})(ByteLength || (ByteLength = {}));
+const HEX_REGEX = /^[0-9a-f]*$/i;
+const isPrefixed = (value) => value.startsWith("0x");
+const assertEvenLength = (hex) => {
+    if (hex.length % 2 !== 0) {
+        throw new Error("Hex string must have an even length");
+    }
+};
+const assertHex = (hex) => {
+    if (!HEX_REGEX.test(hex)) {
+        throw new Error("Invalid hex string");
+    }
+};
+export class ByteUtils {
+    static prefix0x(value) {
+        return isPrefixed(value) ? value : `0x${value}`;
+    }
+    static strip0x(value) {
+        return isPrefixed(value) ? value.slice(2) : value;
+    }
+    static hexlify(data) {
+        if (typeof data === "string") {
+            return ByteUtils.strip0x(data).toLowerCase();
+        }
+        if (typeof data === "number" || typeof data === "bigint") {
+            if (data < 0)
+                throw new Error("Cannot hexlify negative values");
+            const hex = data.toString(16);
+            return hex.length % 2 === 0 ? hex : `0${hex}`;
+        }
+        const view = data instanceof Uint8Array ? data : Uint8Array.from(data);
+        return ByteUtils.bytesToHex(view);
+    }
+    static bytesToHex(bytes) {
+        let hex = "";
+        for (const byte of bytes) {
+            hex += byte.toString(16).padStart(2, "0");
+        }
+        return hex;
+    }
+    static hexStringToBytes(hex) {
+        const normalized = ByteUtils.strip0x(hex).toLowerCase();
+        assertEvenLength(normalized);
+        assertHex(normalized);
+        const byteLength = normalized.length / 2;
+        return Uint8Array.from({ length: byteLength }, (_, index) => parseInt(normalized.slice(index * 2, index * 2 + 2), 16));
+    }
+    static arrayify(data) {
+        if (data instanceof Uint8Array) {
+            return new Uint8Array(data);
+        }
+        if (typeof data === "string") {
+            return ByteUtils.hexStringToBytes(data);
+        }
+        if (typeof data === "number" || typeof data === "bigint") {
+            return ByteUtils.hexStringToBytes(ByteUtils.hexlify(data));
+        }
+        return Uint8Array.from(data);
+    }
+    static hexToBigInt(hex) {
+        return BigInt(`0x${ByteUtils.strip0x(hex)}`);
+    }
+    static padToLength(data, length, side = "left") {
+        const hex = ByteUtils.hexlify(data);
+        const targetLength = length * 2;
+        if (hex.length > targetLength) {
+            throw new Error("Cannot pad data that exceeds target length");
+        }
+        return side === "left"
+            ? hex.padStart(targetLength, "0")
+            : hex.padEnd(targetLength, "0");
+    }
+    static formatToByteLength(data, length) {
+        const hex = ByteUtils.hexlify(data);
+        if (hex.length > length * 2) {
+            return hex.slice(0, length * 2);
+        }
+        return hex.padStart(length * 2, "0");
+    }
+    static nToHex(value, length, prefix = false) {
+        const hex = value.toString(16).padStart(length * 2, "0");
+        return prefix ? `0x${hex}` : hex;
+    }
+}
+export function fromUTF8String(value) {
+    const encoder = new TextEncoder();
+    return ByteUtils.hexlify(encoder.encode(value));
+}

package/dist/key-derivation/hash.d.ts

@@ -0,0 +1,3 @@
+import { BytesData } from "./bytes.js";
+export declare function sha512HMAC(key: BytesData, data: BytesData): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/key-derivation/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../key-derivation/hash.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAMlD,wBAAgB,UAAU,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAGlE"}

package/dist/key-derivation/hash.js

@@ -0,0 +1,10 @@
+import { hmac } from "@noble/hashes/hmac";
+import { sha512 } from "@noble/hashes/sha2";
+import { ByteUtils } from "./bytes.js";
+const toBytes = (data) => {
+    return ByteUtils.arrayify(data);
+};
+export function sha512HMAC(key, data) {
+    const mac = hmac(sha512, toBytes(key), toBytes(data));
+    return ByteUtils.bytesToHex(mac);
+}

package/dist/key-derivation/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./babyjubjub.js";
+export * from "./bip32.js";
+export * from "./bip39.js";
+export * from "./bech32.js";
+export * from "./bytes.js";
+export * from "./hash.js";
+export * from "./wallet-node.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/key-derivation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../key-derivation/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC"}

package/dist/key-derivation/index.js

@@ -0,0 +1,7 @@
+export * from "./babyjubjub.js";
+export * from "./bip32.js";
+export * from "./bip39.js";
+export * from "./bech32.js";
+export * from "./bytes.js";
+export * from "./hash.js";
+export * from "./wallet-node.js";

package/dist/key-derivation/wallet-node.d.ts

@@ -0,0 +1,45 @@
+import { KeyNode } from "./bip32.js";
+export type SpendingPublicKey = [bigint, bigint];
+export type SpendingKeyPair = {
+    privateKey: Uint8Array;
+    pubkey: SpendingPublicKey;
+};
+export type ViewingKeyPair = {
+    privateKey: Uint8Array;
+    pubkey: Uint8Array;
+};
+export type WalletNodes = {
+    spending: WalletNode;
+    viewing: WalletNode;
+};
+export declare const deriveNodes: (mnemonic: string, index?: number) => WalletNodes;
+export declare const deriveNodesFromSeed: (seed: Uint8Array, index?: number) => WalletNodes;
+export declare class WalletNode {
+    private readonly chainKey;
+    private readonly chainCode;
+    constructor(node: KeyNode);
+    static fromMnemonic(mnemonic: string): WalletNode;
+    /**
+     * Convenience constructor for callers that already hold a seed or mnemonic-derived hex.
+     */
+    static fromSeed(seed: Uint8Array | string): WalletNode;
+    /**
+     * Traverse a derivation path, returning the resulting hardened node.
+     */
+    derive(path: string): WalletNode;
+    /**
+     * Derive the BabyJubJub spending key pair (private scalar + affine point).
+     */
+    getSpendingKeyPair(): SpendingKeyPair;
+    static getMasterPublicKey(spendingPublicKey: SpendingPublicKey, nullifyingKey: bigint): bigint;
+    static getNullifyingKey(viewingPrivateKey: Uint8Array): bigint;
+    /**
+     * Derive the Ed25519 viewing key pair for encrypted note retrieval.
+     */
+    getViewingKeyPair(): Promise<ViewingKeyPair>;
+    /**
+     * Compute the Poseidon-based nullifying key used in note nullifier generation.
+     */
+    getNullifyingKey(): Promise<bigint>;
+}
+//# sourceMappingURL=wallet-node.d.ts.map

package/dist/key-derivation/wallet-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-node.d.ts","sourceRoot":"","sources":["../../key-derivation/wallet-node.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,OAAO,EACR,MAAM,YAAY,CAAC;AASpB,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACjD,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IAAE,UAAU,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAgB5E,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAExE,eAAO,MAAM,WAAW,GACtB,UAAU,MAAM,EAChB,QAAO,MAAU,KAChB,WAOF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,MAAM,UAAU,EAChB,QAAO,MAAU,KAChB,WAOF,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,OAAO;IAKzB,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAKjD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,UAAU;IAQtD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU;IAUhC;;OAEG;IACH,kBAAkB,IAAI,eAAe;IASrC,MAAM,CAAC,kBAAkB,CACvB,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,MAAM,GACpB,MAAM;IAIT,MAAM,CAAC,gBAAgB,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM;IAW9D;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IASlD;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;CAI1C"}

package/dist/key-derivation/wallet-node.js

@@ -0,0 +1,109 @@
+import { Buffer } from "buffer";
+import { getPublicKey, hashes } from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2";
+import { eddsa, poseidon } from "@railgun-community/circomlibjs";
+import { childKeyDerivationHardened, getMasterKeyFromSeed, getPathSegments, } from "./bip32.js";
+import { Mnemonic } from "./bip39.js";
+import { ByteUtils } from "./bytes.js";
+hashes.sha512 = sha512;
+hashes.sha512Async = async (message) => sha512(message);
+const HARDENED_OFFSET = 0x80000000;
+/**
+ * Hardened base paths for spending/viewing keys. The final path becomes
+ * m/.../{index}' for each account slot.
+ */
+const DERIVATION_PATH_PREFIXES = {
+    SPENDING: "m/44'/1984'/0'/0'/",
+    VIEWING: "m/420'/1984'/0'/0'/",
+};
+const derivePathsForIndex = (index = 0) => ({
+    spending: `${DERIVATION_PATH_PREFIXES.SPENDING}${index}'`,
+    viewing: `${DERIVATION_PATH_PREFIXES.VIEWING}${index}'`,
+});
+export const deriveNodes = (mnemonic, index = 0) => {
+    const paths = derivePathsForIndex(index);
+    const root = WalletNode.fromMnemonic(mnemonic);
+    return {
+        spending: root.derive(paths.spending),
+        viewing: root.derive(paths.viewing),
+    };
+};
+export const deriveNodesFromSeed = (seed, index = 0) => {
+    const paths = derivePathsForIndex(index);
+    const root = WalletNode.fromSeed(seed);
+    return {
+        spending: root.derive(paths.spending),
+        viewing: root.derive(paths.viewing),
+    };
+};
+export class WalletNode {
+    chainKey;
+    chainCode;
+    constructor(node) {
+        this.chainKey = node.chainKey;
+        this.chainCode = node.chainCode;
+    }
+    static fromMnemonic(mnemonic) {
+        const seedHex = Mnemonic.toSeed(mnemonic);
+        return new WalletNode(getMasterKeyFromSeed(seedHex));
+    }
+    /**
+     * Convenience constructor for callers that already hold a seed or mnemonic-derived hex.
+     */
+    static fromSeed(seed) {
+        const seedHex = typeof seed === "string"
+            ? ByteUtils.hexlify(seed)
+            : ByteUtils.bytesToHex(seed);
+        return new WalletNode(getMasterKeyFromSeed(seedHex));
+    }
+    /**
+     * Traverse a derivation path, returning the resulting hardened node.
+     */
+    derive(path) {
+        const segments = getPathSegments(path);
+        const derived = segments.reduce((parent, segment) => childKeyDerivationHardened(parent, segment, HARDENED_OFFSET), { chainKey: this.chainKey, chainCode: this.chainCode });
+        return new WalletNode(derived);
+    }
+    /**
+     * Derive the BabyJubJub spending key pair (private scalar + affine point).
+     */
+    getSpendingKeyPair() {
+        const privateKey = ByteUtils.hexStringToBytes(this.chainKey);
+        if (privateKey.length !== 32) {
+            throw new Error("Spending private key must be 32 bytes");
+        }
+        const pubkey = eddsa.prv2pub(Buffer.from(privateKey));
+        return { privateKey, pubkey };
+    }
+    static getMasterPublicKey(spendingPublicKey, nullifyingKey) {
+        return poseidon([...spendingPublicKey, nullifyingKey]);
+    }
+    static getNullifyingKey(viewingPrivateKey) {
+        if (!(viewingPrivateKey instanceof Uint8Array)) {
+            throw new Error("Viewing private key must be a Uint8Array");
+        }
+        if (viewingPrivateKey.length !== 32) {
+            throw new Error("Viewing private key must be 32 bytes");
+        }
+        const privateKeyHex = ByteUtils.bytesToHex(viewingPrivateKey);
+        return poseidon([ByteUtils.hexToBigInt(privateKeyHex)]);
+    }
+    /**
+     * Derive the Ed25519 viewing key pair for encrypted note retrieval.
+     */
+    async getViewingKeyPair() {
+        const privateKey = ByteUtils.hexStringToBytes(this.chainKey);
+        if (privateKey.length !== 32) {
+            throw new Error("Viewing private key must be 32 bytes");
+        }
+        const pubkey = await getPublicKey(privateKey);
+        return { privateKey, pubkey };
+    }
+    /**
+     * Compute the Poseidon-based nullifying key used in note nullifier generation.
+     */
+    async getNullifyingKey() {
+        const { privateKey } = await this.getViewingKeyPair();
+        return WalletNode.getNullifyingKey(privateKey);
+    }
+}

package/dist/keys.d.ts

@@ -0,0 +1,22 @@
+export declare const RESERVED_PREFIXES: readonly ["meta:", "notes:", "leaves:", "roots:", "nullifiers:", "ciphertexts:", "jobs:", "proof_cache:", "cfg:", "idx:", "locks:"];
+/** Canonical builders for storage key namespaces used across core */
+export declare const keys: {
+    note: (c: number, i: number) => string;
+    leaf: (c: number, i: number) => string;
+    ciphertext: (c: number, i: number) => string;
+    /** Track note indices that remain unspent for a given master public key (mpk acts as the account identifier). */
+    unspent: (c: number, mpk: string, i: number) => string;
+    unspentPrefix: (c: number, mpk: string) => string;
+    nullifierObs: (c: number, n: string) => string;
+    nullToIndex: (c: number, n: string) => string;
+    nullifier: (c: number, n: string) => string;
+    root: (c: number, value: string) => string;
+    latestRoot: (c: number) => string;
+    rootCursor: (c: number) => string;
+    cursor: (c: number) => string;
+    aggregate: (c: number, a: string) => string;
+    job: (relayId: string) => string;
+};
+export declare const MAX_KEY_LEN = 512;
+export declare function validateKey(key: string): void;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../keys.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,qIAYpB,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,IAAI;cACL,MAAM,KAAK,MAAM;cACjB,MAAM,KAAK,MAAM;oBACX,MAAM,KAAK,MAAM;IACjC,iHAAiH;iBACpG,MAAM,OAAO,MAAM,KAAK,MAAM;uBAExB,MAAM,OAAO,MAAM;sBACpB,MAAM,KAAK,MAAM;qBAClB,MAAM,KAAK,MAAM;mBACnB,MAAM,KAAK,MAAM;cACtB,MAAM,SAAS,MAAM;oBACf,MAAM;oBACN,MAAM;gBACV,MAAM;mBACH,MAAM,KAAK,MAAM;mBACjB,MAAM;CACtB,CAAC;AAEF,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,QAQtC"}

package/dist/keys.js

@@ -0,0 +1,41 @@
+import { KeyValidationError } from "./errors.js";
+export const RESERVED_PREFIXES = [
+    "meta:",
+    "notes:",
+    "leaves:",
+    "roots:",
+    "nullifiers:",
+    "ciphertexts:",
+    "jobs:",
+    "proof_cache:",
+    "cfg:",
+    "idx:",
+    "locks:",
+];
+/** Canonical builders for storage key namespaces used across core */
+export const keys = {
+    note: (c, i) => `notes:${c}:${i}`,
+    leaf: (c, i) => `leaves:${c}:${i}`,
+    ciphertext: (c, i) => `ciphertexts:${c}:${i}`,
+    /** Track note indices that remain unspent for a given master public key (mpk acts as the account identifier). */
+    unspent: (c, mpk, i) => `idx:notes:unspent:${c}:${mpk}:${i}`,
+    unspentPrefix: (c, mpk) => `idx:notes:unspent:${c}:${mpk}:`,
+    nullifierObs: (c, n) => `nullifiers:${c}:${n}`,
+    nullToIndex: (c, n) => `idx:nullifier:${c}:${n}`,
+    nullifier: (c, n) => `nullifiers:${c}:${n}`,
+    root: (c, value) => `roots:${c}:${value}`,
+    latestRoot: (c) => `roots:latest:${c}`,
+    rootCursor: (c) => `meta:roots:cursor:${c}`,
+    cursor: (c) => `meta:sync:cursors:${c}`,
+    aggregate: (c, a) => `idx:notes:agg:${c}:${a}`,
+    job: (relayId) => `jobs:${relayId}`,
+};
+export const MAX_KEY_LEN = 512;
+export function validateKey(key) {
+    if (!key)
+        throw new KeyValidationError("key must not be empty");
+    if (key.length > MAX_KEY_LEN)
+        throw new KeyValidationError(`key exceeds ${MAX_KEY_LEN}`);
+    if (!RESERVED_PREFIXES.some((p) => key.startsWith(p)))
+        throw new KeyValidationError("key must start with a reserved namespace prefix");
+}