@unlink-xyz/core 0.1.0 → 0.1.2

package/errors.ts

@@ -0,0 +1,20 @@
+export class CoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CoreError";
+  }
+}
+
+export class KeyValidationError extends CoreError {
+  constructor(message: string) {
+    super(message);
+    this.name = "KeyValidationError";
+  }
+}
+
+export class SchemaMismatchError extends CoreError {
+  constructor(current: number, expected: number) {
+    super(`schema mismatch (current ${current}, expected ${expected})`);
+    this.name = "SchemaMismatchError";
+  }
+}

package/index.ts

@@ -0,0 +1,17 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./keys.js";
+export * from "./storage/index.js";
+export * from "./schema.js";
+export * from "./core.js";
+export * from "./state/index.js";
+export * from "./utils/validators.js";
+export * from "./utils/bigint.js";
+export * from "./account/zkAccount.js";
+export * from "./key-derivation/index.js";
+export * from "./transactions/index.js";
+export { createJobReconciler } from "./transactions/reconcile.js";
+export { serviceConfig } from "./config.js";
+export type { ServiceConfig } from "./config.js";
+export * from "./clients/broadcaster.js";
+export * from "./clients/indexer.js";

package/key-derivation/babyjubjub.ts

@@ -0,0 +1,11 @@
+import { babyjub } from "@railgun-community/circomlibjs";
+
+/**
+ * Lightweight wrapper exposing the BabyJubJub point packing helpers we rely on for
+ * derivation and address encoding. Re-exported for consumers that need raw curve ops.
+ */
+export class Babyjubjub {
+  static packPoint = babyjub.packPoint;
+
+  static unpackPoint = babyjub.unpackPoint;
+}

package/key-derivation/bech32.test.ts

@@ -0,0 +1,90 @@
+import { bech32m } from "@scure/base";
+import { describe, expect, it } from "vitest";
+
+import {
+  ADDRESS_LENGTH_LIMIT,
+  ADDRESS_VERSION,
+  decodeAddress,
+  encodeAddress,
+  type Chain,
+} from "./bech32.js";
+
+describe("bech32 address encoding", () => {
+  const masterPublicKey = 1234567890123456789012345678901234567890n;
+  const viewingPublicKey = Uint8Array.from(
+    { length: 32 },
+    (_, i) => (i * 3) & 0xff,
+  );
+
+  it("encodes and decodes addresses without chain metadata", () => {
+    const address = encodeAddress({
+      masterPublicKey,
+      viewingPublicKey,
+    });
+
+    const decoded = decodeAddress(address);
+
+    expect(decoded.masterPublicKey).toEqual(masterPublicKey);
+    expect(decoded.viewingPublicKey).toEqual(viewingPublicKey);
+    expect(decoded.chain).toBeUndefined();
+    expect(decoded.version).toBe(ADDRESS_VERSION);
+  });
+
+  it("preserves chain metadata when provided", () => {
+    const chain: Chain = { type: 1, id: 42161 };
+    const address = encodeAddress({
+      masterPublicKey,
+      viewingPublicKey,
+      chain,
+    });
+
+    const decoded = decodeAddress(address);
+
+    expect(decoded.chain).toEqual(chain);
+  });
+
+  it("rejects malformed payloads", () => {
+    const address = encodeAddress({
+      masterPublicKey,
+      viewingPublicKey,
+    });
+
+    expect(() => decodeAddress("")).toThrow("No address to decode");
+
+    const decoded = bech32m.decode(address, ADDRESS_LENGTH_LIMIT);
+    const reencoded = bech32m.encode(
+      "abc",
+      decoded.words,
+      ADDRESS_LENGTH_LIMIT,
+    );
+
+    expect(() => decodeAddress(reencoded)).toThrow("Invalid address prefix");
+  });
+
+  it("throws on incorrect version", () => {
+    const address = encodeAddress({
+      masterPublicKey,
+      viewingPublicKey,
+    });
+
+    const mutated = mutatePayload(address, (payload) => {
+      payload[0] ^= 0xff;
+    });
+
+    expect(() => decodeAddress(mutated)).toThrow("Incorrect address version");
+  });
+});
+
+function mutatePayload(
+  address: string,
+  mutator: (payload: Uint8Array) => void,
+): string {
+  const decoded = bech32m.decode(address, ADDRESS_LENGTH_LIMIT);
+  const payload = Uint8Array.from(bech32m.fromWords(decoded.words));
+  mutator(payload);
+  return bech32m.encode(
+    decoded.prefix,
+    bech32m.toWords(payload),
+    ADDRESS_LENGTH_LIMIT,
+  );
+}

package/key-derivation/bech32.ts

@@ -0,0 +1,124 @@
+import { bech32m } from "@scure/base";
+
+import { ByteLength, ByteUtils } from "./bytes.js";
+
+export type Chain = {
+  type: number;
+  id: number;
+};
+
+export type AddressData = {
+  masterPublicKey: bigint;
+  viewingPublicKey: Uint8Array;
+  chain?: Chain;
+  version?: number;
+};
+
+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: string): string => {
+  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?: Chain): string => {
+  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: string): Chain | undefined => {
+  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: AddressData): string => {
+  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: string): AddressData => {
+  if (!address) {
+    throw new Error("No address to decode");
+  }
+
+  const decoded = bech32m.decode(
+    address as `${string}1${string}`,
+    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/key-derivation/bip32.ts

@@ -0,0 +1,56 @@
+import { ByteUtils, fromUTF8String } from "./bytes.js";
+import { sha512HMAC } from "./hash.js";
+
+const CURVE_SEED = fromUTF8String("babyjubjub seed");
+
+export type KeyNode = {
+  chainKey: string;
+  chainCode: string;
+};
+
+// Validates derivation paths of the form m/... with hardened segments.
+const PATH_REGEX = /^m(\/[0-9]+')+$/;
+
+const isValidPath = (path: string): boolean => {
+  return PATH_REGEX.test(path);
+};
+
+/**
+ * Parse a derivation path into hardened segment indexes.
+ */
+export const getPathSegments = (path: string): number[] => {
+  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: KeyNode,
+  index: number,
+  offset: number = 0x80000000,
+): KeyNode => {
+  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: string): KeyNode => {
+  const I = sha512HMAC(CURVE_SEED, seed);
+  const chainKey = I.slice(0, 64);
+  const chainCode = I.slice(64);
+  return { chainKey, chainCode };
+};

package/key-derivation/bip39.ts

@@ -0,0 +1,76 @@
+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): string => {
+  return `m/44'/60'/0'/0/${index}`;
+};
+
+export class Mnemonic {
+  /**
+   * Generate a BIP-39 mnemonic using the English wordlist.
+   */
+  static generate(strength: 128 | 192 | 256 = 128): string {
+    return generateMnemonic(wordlist, strength);
+  }
+
+  /**
+   * Validate a mnemonic against the English wordlist checksum.
+   */
+  static validate(mnemonic: string): boolean {
+    return validateMnemonic(mnemonic, wordlist);
+  }
+
+  /**
+   * Convert a mnemonic to a hex-encoded BIP-39 seed. Optional password supported.
+   */
+  static toSeed(mnemonic: string, password: string = ""): string {
+    const seed = mnemonicToSeedSync(mnemonic, password);
+    return ByteUtils.bytesToHex(seed);
+  }
+
+  static toEntropy(mnemonic: string): string {
+    const entropy = mnemonicToEntropy(mnemonic, wordlist);
+    return ByteUtils.bytesToHex(entropy);
+  }
+
+  static fromEntropy(entropyHex: string): string {
+    const entropy = ByteUtils.hexStringToBytes(entropyHex);
+    return entropyToMnemonic(entropy, wordlist);
+  }
+
+  /**
+   * Convenience helper: derive a 0x private key for non-0zk flows.
+   */
+  static to0xPrivateKey(mnemonic: string, derivationIndex?: number): string {
+    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: string, derivationIndex?: number): string {
+    const wallet = HDNodeWallet.fromMnemonic(
+      EthersMnemonic.fromPhrase(mnemonic),
+      derivationPath(derivationIndex),
+    );
+    return wallet.address;
+  }
+}

package/key-derivation/bytes.ts

@@ -0,0 +1,118 @@
+export enum ByteLength {
+  UINT_256 = 32,
+  UINT_512 = 64,
+}
+
+export type BytesData =
+  | string
+  | number
+  | bigint
+  | Uint8Array
+  | ArrayLike<number>;
+
+const HEX_REGEX = /^[0-9a-f]*$/i;
+
+const isPrefixed = (value: string): boolean => value.startsWith("0x");
+
+const assertEvenLength = (hex: string): void => {
+  if (hex.length % 2 !== 0) {
+    throw new Error("Hex string must have an even length");
+  }
+};
+
+const assertHex = (hex: string): void => {
+  if (!HEX_REGEX.test(hex)) {
+    throw new Error("Invalid hex string");
+  }
+};
+
+export class ByteUtils {
+  static prefix0x(value: string): string {
+    return isPrefixed(value) ? value : `0x${value}`;
+  }
+
+  static strip0x(value: string): string {
+    return isPrefixed(value) ? value.slice(2) : value;
+  }
+
+  static hexlify(data: BytesData): string {
+    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: Uint8Array): string {
+    let hex = "";
+    for (const byte of bytes) {
+      hex += byte.toString(16).padStart(2, "0");
+    }
+    return hex;
+  }
+
+  static hexStringToBytes(hex: string): Uint8Array {
+    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: BytesData): Uint8Array {
+    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: string): bigint {
+    return BigInt(`0x${ByteUtils.strip0x(hex)}`);
+  }
+
+  static padToLength(
+    data: BytesData,
+    length: number,
+    side: "left" | "right" = "left",
+  ): string {
+    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: BytesData, length: ByteLength): string {
+    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: bigint, length: ByteLength, prefix = false): string {
+    const hex = value.toString(16).padStart(length * 2, "0");
+    return prefix ? `0x${hex}` : hex;
+  }
+}
+
+export function fromUTF8String(value: string): string {
+  const encoder = new TextEncoder();
+  return ByteUtils.hexlify(encoder.encode(value));
+}

package/key-derivation/hash.ts

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

package/key-derivation/index.ts

@@ -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/key-derivation/wallet-node.ts

@@ -0,0 +1,155 @@
+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,
+  KeyNode,
+} from "./bip32.js";
+import { Mnemonic } from "./bip39.js";
+import { ByteUtils } from "./bytes.js";
+
+hashes.sha512 = sha512;
+hashes.sha512Async = async (message: Uint8Array) => sha512(message);
+
+const HARDENED_OFFSET = 0x80000000;
+
+export type SpendingPublicKey = [bigint, bigint];
+export type SpendingKeyPair = {
+  privateKey: Uint8Array;
+  pubkey: SpendingPublicKey;
+};
+export type ViewingKeyPair = { privateKey: Uint8Array; pubkey: Uint8Array };
+
+/**
+ * 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: number = 0) => ({
+  spending: `${DERIVATION_PATH_PREFIXES.SPENDING}${index}'`,
+  viewing: `${DERIVATION_PATH_PREFIXES.VIEWING}${index}'`,
+});
+
+export type WalletNodes = { spending: WalletNode; viewing: WalletNode };
+
+export const deriveNodes = (
+  mnemonic: string,
+  index: number = 0,
+): WalletNodes => {
+  const paths = derivePathsForIndex(index);
+  const root = WalletNode.fromMnemonic(mnemonic);
+  return {
+    spending: root.derive(paths.spending),
+    viewing: root.derive(paths.viewing),
+  };
+};
+
+export const deriveNodesFromSeed = (
+  seed: Uint8Array,
+  index: number = 0,
+): WalletNodes => {
+  const paths = derivePathsForIndex(index);
+  const root = WalletNode.fromSeed(seed);
+  return {
+    spending: root.derive(paths.spending),
+    viewing: root.derive(paths.viewing),
+  };
+};
+
+export class WalletNode {
+  private readonly chainKey: string;
+
+  private readonly chainCode: string;
+
+  constructor(node: KeyNode) {
+    this.chainKey = node.chainKey;
+    this.chainCode = node.chainCode;
+  }
+
+  static fromMnemonic(mnemonic: string): WalletNode {
+    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: Uint8Array | string): WalletNode {
+    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: string): WalletNode {
+    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(): SpendingKeyPair {
+    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)) as SpendingPublicKey;
+    return { privateKey, pubkey };
+  }
+
+  static getMasterPublicKey(
+    spendingPublicKey: SpendingPublicKey,
+    nullifyingKey: bigint,
+  ): bigint {
+    return poseidon([...spendingPublicKey, nullifyingKey]);
+  }
+
+  static getNullifyingKey(viewingPrivateKey: Uint8Array): bigint {
+    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(): Promise<ViewingKeyPair> {
+    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(): Promise<bigint> {
+    const { privateKey } = await this.getViewingKeyPair();
+    return WalletNode.getNullifyingKey(privateKey);
+  }
+}