@unlink-xyz/core 0.1.0 → 0.1.2

package/.eslintrc.json

@@ -0,0 +1,4 @@
+{
+  "root": true,
+  "extends": ["../../.eslintrc.base.json"]
+}

package/account/zkAccount.test.ts

@@ -0,0 +1,316 @@
+import { describe, expect, it } from "vitest";
+
+import { Mnemonic } from "../key-derivation/bip39.js";
+import { ByteUtils } from "../key-derivation/bytes.js";
+import {
+  deriveNodesFromSeed,
+  WalletNode,
+} from "../key-derivation/wallet-node.js";
+import { createMemoryStorage } from "../storage/memory.js";
+import {
+  deriveZkAccount,
+  deriveZkAccountFromMnemonic,
+  generateMasterSeed,
+  importMasterMnemonic,
+  loadMasterMnemonic,
+  loadMasterSeed,
+  MASTER_MNEMONIC_KEY,
+  MASTER_SEED_KEY,
+  MASTER_SEED_LENGTH,
+  storeMasterMnemonic,
+  type MasterSeedCrypto,
+} from "./zkAccount.js";
+
+describe("deriveZkAccount", () => {
+  const seed = Uint8Array.from(
+    { length: MASTER_SEED_LENGTH },
+    (_, i) => i & 0xff,
+  );
+
+  it("derives wallet key material", async () => {
+    const account = await deriveZkAccount(seed, 0);
+
+    expect(account.spendingKeyPair.privateKey).toHaveLength(32);
+    expect(typeof account.spendingKeyPair.pubkey[0]).toBe("bigint");
+    expect(typeof account.spendingKeyPair.pubkey[1]).toBe("bigint");
+
+    expect(account.viewingKeyPair.privateKey).toHaveLength(32);
+    expect(account.viewingKeyPair.pubkey).toHaveLength(32);
+
+    expect(account.nullifyingKey).toBeTypeOf("bigint");
+
+    const expectedNullifyingKey = await deriveNodesFromSeed(
+      seed,
+      0,
+    ).viewing.getNullifyingKey();
+    expect(account.nullifyingKey).toBe(expectedNullifyingKey);
+
+    const expectedMPK = WalletNode.getMasterPublicKey(
+      account.spendingKeyPair.pubkey,
+      account.nullifyingKey,
+    );
+    expect(account.masterPublicKey).toBe(expectedMPK);
+  });
+
+  it("derives distinct accounts per index", async () => {
+    const first = await deriveZkAccount(seed, 0);
+    const second = await deriveZkAccount(seed, 1);
+
+    expect(first.spendingKeyPair.privateKey).not.toEqual(
+      second.spendingKeyPair.privateKey,
+    );
+    expect(first.viewingKeyPair.privateKey).not.toEqual(
+      second.viewingKeyPair.privateKey,
+    );
+    expect(first.nullifyingKey).not.toEqual(second.nullifyingKey);
+    expect(first.masterPublicKey).not.toEqual(second.masterPublicKey);
+  });
+
+  it("rejects negative indices", async () => {
+    await expect(deriveZkAccount(seed, -1)).rejects.toThrow(
+      "accountIndex must be a non-negative integer",
+    );
+  });
+
+  it("rejects non-integer indices", async () => {
+    await expect(deriveZkAccount(seed, Number.NaN)).rejects.toThrow(
+      "accountIndex must be a non-negative integer",
+    );
+    await expect(deriveZkAccount(seed, 0.25)).rejects.toThrow(
+      "accountIndex must be a non-negative integer",
+    );
+  });
+
+  it("rejects seeds that are not 64 bytes", async () => {
+    const shortSeed = Uint8Array.from({ length: 32 }, () => 1);
+    await expect(deriveZkAccount(shortSeed, 0)).rejects.toThrow(
+      "master seed must be 64 bytes",
+    );
+  });
+
+  it("derives the same keys when using mnemonic helper", async () => {
+    const entropy = Uint8Array.from({ length: 32 }, (_, i) => (i * 19) & 0xff);
+    const mnemonic = Mnemonic.fromEntropy(ByteUtils.bytesToHex(entropy));
+    const seedFromMnemonic = ByteUtils.hexStringToBytes(
+      Mnemonic.toSeed(mnemonic),
+    );
+
+    const fromSeed = await deriveZkAccount(seedFromMnemonic, 2);
+    const fromMnemonic = await deriveZkAccountFromMnemonic(mnemonic, 2);
+
+    expect(fromMnemonic).toEqual(fromSeed);
+  });
+});
+
+describe("generateMasterSeed", () => {
+  const fixtureEntropy = Uint8Array.from(
+    { length: 32 },
+    (_, i) => (i * 13) & 0xff,
+  );
+  const fixtureMnemonic = Mnemonic.fromEntropy(
+    ByteUtils.bytesToHex(fixtureEntropy),
+  );
+  const fixtureSeed = ByteUtils.hexStringToBytes(
+    Mnemonic.toSeed(fixtureMnemonic),
+  );
+
+  function rngFixture(): (n: number) => Uint8Array {
+    return (n) => {
+      expect(n).toBe(32);
+      return new Uint8Array(fixtureEntropy);
+    };
+  }
+
+  it("creates and persists a new seed when none exists", async () => {
+    const storage = createMemoryStorage();
+
+    const seed = await generateMasterSeed({
+      storage,
+      rng: rngFixture(),
+      mnemonicPassphrase: "",
+    });
+
+    expect(seed).toEqual(fixtureSeed);
+    const stored = await storage.get(MASTER_SEED_KEY);
+    expect(stored).not.toBeNull();
+    expect(stored).toEqual(fixtureSeed);
+
+    const mnemonic = await loadMasterMnemonic(storage);
+    expect(mnemonic).toEqual(fixtureMnemonic);
+  });
+
+  it("returns existing seed without invoking rng", async () => {
+    const storage = createMemoryStorage();
+    await storage.put(MASTER_SEED_KEY, fixtureSeed);
+
+    const seed = await generateMasterSeed({
+      storage,
+      rng: () => {
+        throw new Error("rng should not be called when seed exists");
+      },
+    });
+
+    expect(seed).toEqual(fixtureSeed);
+  });
+
+  it("overwrites when requested", async () => {
+    const storage = createMemoryStorage();
+    const existing = Uint8Array.from(
+      { length: MASTER_SEED_LENGTH },
+      (_, i) => (i * 3) & 0xff,
+    );
+    await storage.put(MASTER_SEED_KEY, existing);
+    const replacementEntropy = Uint8Array.from(
+      { length: 32 },
+      (_, i) => (i * 7) & 0xff,
+    );
+    const replacementMnemonic = Mnemonic.fromEntropy(
+      ByteUtils.bytesToHex(replacementEntropy),
+    );
+    const replacementSeed = ByteUtils.hexStringToBytes(
+      Mnemonic.toSeed(replacementMnemonic),
+    );
+
+    const seed = await generateMasterSeed({
+      storage,
+      rng: (n) => {
+        expect(n).toBe(32);
+        return new Uint8Array(replacementEntropy);
+      },
+      overwrite: true,
+      mnemonicPassphrase: "",
+    });
+
+    expect(seed).toEqual(replacementSeed);
+    const stored = await storage.get(MASTER_SEED_KEY);
+    expect(stored).toEqual(replacementSeed);
+    const mnemonic = await loadMasterMnemonic(storage);
+    expect(mnemonic).toEqual(replacementMnemonic);
+  });
+
+  it("applies custom crypto hooks", async () => {
+    const storage = createMemoryStorage();
+
+    const crypto: MasterSeedCrypto = {
+      encrypt(seed) {
+        return seed.map((byte) => byte ^ 0xff);
+      },
+      decrypt(payload) {
+        return payload.map((byte) => byte ^ 0xff);
+      },
+    };
+
+    const seed = await generateMasterSeed({
+      storage,
+      rng: rngFixture(),
+      crypto,
+      mnemonicPassphrase: "",
+    });
+
+    expect(seed).toEqual(fixtureSeed);
+    const roundTrip = await loadMasterSeed(storage, crypto);
+    expect(roundTrip).toEqual(fixtureSeed);
+
+    const storedMnemonic = await storage.get(MASTER_MNEMONIC_KEY);
+    expect(storedMnemonic).toEqual(
+      textEncode(fixtureMnemonic).map((byte) => byte ^ 0xff),
+    );
+
+    const mnemonicRoundTrip = await loadMasterMnemonic(storage, crypto);
+    expect(mnemonicRoundTrip).toEqual(fixtureMnemonic);
+  });
+
+  it("returns null when no seed is stored", async () => {
+    const storage = createMemoryStorage();
+
+    const result = await loadMasterSeed(storage);
+
+    expect(result).toBeNull();
+  });
+
+  it("throws if rng returns incorrect length", async () => {
+    const storage = createMemoryStorage();
+
+    await expect(
+      generateMasterSeed({
+        storage,
+        rng: () => new Uint8Array(16),
+        mnemonicPassphrase: "",
+      }),
+    ).rejects.toThrow(/mnemonic entropy must be 32 bytes/);
+  });
+
+  it("reconstitutes seed from stored mnemonic when seed missing", async () => {
+    const storage = createMemoryStorage();
+    await storeMnemonicFixture(storage, fixtureMnemonic);
+
+    const seed = await generateMasterSeed({
+      storage,
+      rng: rngFixture(),
+      mnemonicPassphrase: "",
+    });
+
+    expect(seed).toEqual(fixtureSeed);
+    const stored = await storage.get(MASTER_SEED_KEY);
+    expect(stored).toEqual(fixtureSeed);
+  });
+});
+
+describe("importMasterMnemonic", () => {
+  const mnemonic =
+    "legal winner thank year wave sausage worth useful legal winner thank yellow";
+  const seed = ByteUtils.hexStringToBytes(Mnemonic.toSeed(mnemonic));
+
+  it("imports mnemonic and stores derived seed", async () => {
+    const storage = createMemoryStorage();
+
+    const derived = await importMasterMnemonic({ storage, mnemonic });
+
+    expect(derived).toEqual(seed);
+    const storedSeed = await loadMasterSeed(storage);
+    expect(storedSeed).toEqual(seed);
+    const storedMnemonic = await loadMasterMnemonic(storage);
+    expect(storedMnemonic).toEqual(mnemonic);
+  });
+
+  it("refuses to overwrite without flag", async () => {
+    const storage = createMemoryStorage();
+    await importMasterMnemonic({ storage, mnemonic });
+
+    await expect(importMasterMnemonic({ storage, mnemonic })).rejects.toThrow(
+      /already exists/,
+    );
+  });
+
+  it("overwrites when requested", async () => {
+    const storage = createMemoryStorage();
+    await importMasterMnemonic({ storage, mnemonic });
+
+    const alternate =
+      "letter advice cage absurd amount doctor acoustic avoid letter advice cage above";
+    const alternateSeed = ByteUtils.hexStringToBytes(
+      Mnemonic.toSeed(alternate),
+    );
+
+    const derived = await importMasterMnemonic({
+      storage,
+      mnemonic: alternate,
+      overwrite: true,
+    });
+
+    expect(derived).toEqual(alternateSeed);
+    const storedMnemonic = await loadMasterMnemonic(storage);
+    expect(storedMnemonic).toEqual(alternate);
+  });
+});
+
+function textEncode(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}
+
+async function storeMnemonicFixture(
+  storage: ReturnType<typeof createMemoryStorage>,
+  mnemonic: string,
+) {
+  await storeMasterMnemonic(storage, mnemonic);
+}

package/account/zkAccount.ts

@@ -0,0 +1,222 @@
+import { Mnemonic } from "../key-derivation/bip39.js";
+import { ByteUtils } from "../key-derivation/bytes.js";
+import {
+  deriveNodesFromSeed,
+  WalletNode,
+  type SpendingKeyPair,
+  type ViewingKeyPair,
+} from "../key-derivation/wallet-node.js";
+import type { Storage } from "../types.js";
+
+export type MasterSeedCrypto = {
+  encrypt(seed: Uint8Array): Promise<Uint8Array> | Uint8Array;
+  decrypt(payload: Uint8Array): Promise<Uint8Array> | Uint8Array;
+};
+
+export type GenerateMasterSeedOptions = {
+  storage: Storage;
+  rng: (n: number) => Uint8Array;
+  crypto?: MasterSeedCrypto;
+  overwrite?: boolean;
+  mnemonicPassphrase: string;
+};
+
+export const MASTER_SEED_LENGTH = 64;
+export const MASTER_SEED_KEY = "cfg:wallet:master_seed/v1";
+export const MASTER_MNEMONIC_KEY = "cfg:wallet:master_mnemonic/v1";
+
+const MNEMONIC_ENTROPY_BYTES = 32;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export type ZkAccount = {
+  spendingKeyPair: SpendingKeyPair;
+  viewingKeyPair: ViewingKeyPair;
+  nullifyingKey: bigint;
+  masterPublicKey: bigint;
+};
+
+export async function deriveZkAccount(
+  masterSeed: Uint8Array,
+  accountIndex: number = 0,
+): Promise<ZkAccount> {
+  const seed = normalizeMasterSeed(masterSeed);
+  if (!Number.isInteger(accountIndex) || accountIndex < 0) {
+    throw new Error("accountIndex must be a non-negative integer");
+  }
+
+  const { spending, viewing } = deriveNodesFromSeed(seed, accountIndex);
+  const spendingKeyPair = spending.getSpendingKeyPair();
+  const viewingKeyPair = await viewing.getViewingKeyPair();
+  const nullifyingKey = WalletNode.getNullifyingKey(viewingKeyPair.privateKey);
+  const masterPublicKey = WalletNode.getMasterPublicKey(
+    spendingKeyPair.pubkey,
+    nullifyingKey,
+  );
+
+  return {
+    spendingKeyPair,
+    viewingKeyPair,
+    nullifyingKey,
+    masterPublicKey,
+  };
+}
+
+export async function deriveZkAccountFromMnemonic(
+  mnemonic: string,
+  accountIndex: number = 0,
+  password: string = "",
+): Promise<ZkAccount> {
+  const normalized = normalizeMnemonic(mnemonic);
+  const seed = mnemonicToSeed(normalized, password);
+  return deriveZkAccount(seed, accountIndex);
+}
+
+const identityMasterSeedCrypto: MasterSeedCrypto = {
+  encrypt(seed) {
+    return clone(seed);
+  },
+  decrypt(payload) {
+    return clone(payload);
+  },
+};
+
+export async function generateMasterSeed({
+  storage,
+  rng,
+  crypto = identityMasterSeedCrypto,
+  overwrite = false,
+  mnemonicPassphrase,
+}: GenerateMasterSeedOptions): Promise<Uint8Array> {
+  if (!overwrite) {
+    const existingSeed = await loadMasterSeed(storage, crypto);
+    if (existingSeed) return existingSeed;
+
+    const existingMnemonic = await loadMasterMnemonic(storage, crypto);
+    if (existingMnemonic) {
+      const seedFromMnemonic = mnemonicToSeed(
+        existingMnemonic,
+        mnemonicPassphrase,
+      );
+      await storeMasterSeed(storage, seedFromMnemonic, crypto);
+      return seedFromMnemonic;
+    }
+  }
+
+  const entropy = rng(MNEMONIC_ENTROPY_BYTES);
+  if (entropy.length !== MNEMONIC_ENTROPY_BYTES) {
+    throw new Error(`mnemonic entropy must be ${MNEMONIC_ENTROPY_BYTES} bytes`);
+  }
+
+  const mnemonic = Mnemonic.fromEntropy(ByteUtils.bytesToHex(entropy));
+  await storeMasterMnemonic(storage, mnemonic, crypto);
+  const seed = mnemonicToSeed(mnemonic, mnemonicPassphrase);
+  await storeMasterSeed(storage, seed, crypto);
+  return seed;
+}
+
+export async function loadMasterSeed(
+  storage: Storage,
+  crypto: MasterSeedCrypto = identityMasterSeedCrypto,
+): Promise<Uint8Array | null> {
+  const stored = await storage.get(MASTER_SEED_KEY);
+  if (!stored) return null;
+  const plaintext = await crypto.decrypt(stored);
+  return normalizeMasterSeed(plaintext);
+}
+
+export async function storeMasterSeed(
+  storage: Storage,
+  seed: Uint8Array,
+  crypto: MasterSeedCrypto = identityMasterSeedCrypto,
+): Promise<void> {
+  const normalized = normalizeMasterSeed(seed);
+  const encrypted = await crypto.encrypt(normalized);
+  if (!(encrypted instanceof Uint8Array)) {
+    throw new Error("master seed encryptor must return Uint8Array");
+  }
+  await storage.put(MASTER_SEED_KEY, clone(encrypted));
+}
+
+export async function loadMasterMnemonic(
+  storage: Storage,
+  crypto: MasterSeedCrypto = identityMasterSeedCrypto,
+): Promise<string | null> {
+  const stored = await storage.get(MASTER_MNEMONIC_KEY);
+  if (!stored) return null;
+  const plaintext = await crypto.decrypt(stored);
+  const mnemonic = textDecoder.decode(plaintext);
+  return normalizeMnemonic(mnemonic);
+}
+
+export type ImportMasterMnemonicOptions = {
+  storage: Storage;
+  mnemonic: string;
+  crypto?: MasterSeedCrypto;
+  overwrite?: boolean;
+  password?: string;
+};
+
+export async function importMasterMnemonic({
+  storage,
+  mnemonic,
+  crypto = identityMasterSeedCrypto,
+  overwrite = false,
+  password = "",
+}: ImportMasterMnemonicOptions): Promise<Uint8Array> {
+  if (!overwrite) {
+    const existing = await loadMasterMnemonic(storage, crypto);
+    if (existing) {
+      throw new Error(
+        "master mnemonic already exists; set overwrite to true to replace it",
+      );
+    }
+  }
+
+  const normalized = normalizeMnemonic(mnemonic);
+  const seed = mnemonicToSeed(normalized, password);
+  await storeMasterMnemonic(storage, normalized, crypto);
+  await storeMasterSeed(storage, seed, crypto);
+  return seed;
+}
+
+export async function storeMasterMnemonic(
+  storage: Storage,
+  mnemonic: string,
+  crypto: MasterSeedCrypto = identityMasterSeedCrypto,
+): Promise<void> {
+  const normalized = normalizeMnemonic(mnemonic);
+  const encrypted = await crypto.encrypt(textEncoder.encode(normalized));
+  if (!(encrypted instanceof Uint8Array)) {
+    throw new Error("master mnemonic encryptor must return Uint8Array");
+  }
+  await storage.put(MASTER_MNEMONIC_KEY, clone(encrypted));
+}
+
+function clone(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes);
+}
+
+function normalizeMasterSeed(seed: Uint8Array): Uint8Array {
+  if (!(seed instanceof Uint8Array)) {
+    throw new Error("master seed must be a Uint8Array");
+  }
+  if (seed.length !== MASTER_SEED_LENGTH) {
+    throw new Error(`master seed must be ${MASTER_SEED_LENGTH} bytes`);
+  }
+  return clone(seed);
+}
+
+function normalizeMnemonic(mnemonic: string): string {
+  const formatted = mnemonic.trim().replace(/\s+/g, " ");
+  if (!Mnemonic.validate(formatted)) {
+    throw new Error("invalid BIP-39 mnemonic phrase");
+  }
+  return formatted;
+}
+
+function mnemonicToSeed(mnemonic: string, password: string = ""): Uint8Array {
+  const seedHex = Mnemonic.toSeed(mnemonic, password);
+  return ByteUtils.hexStringToBytes(seedHex);
+}

package/clients/broadcaster.ts

@@ -0,0 +1,67 @@
+import type { FetchLike } from "./http.js";
+import { createJsonHttpClient } from "./http.js";
+
+export type BroadcasterRelayPayload = {
+  kind: "call_data";
+  to: string;
+  data: string;
+};
+
+export type SubmitRelayParams = {
+  clientTxId: string;
+  chainId: number;
+  payload: BroadcasterRelayPayload;
+};
+
+export type SubmitRelayResponse = {
+  id: string;
+  accepted: boolean;
+  message?: string | null;
+};
+
+export type RelayState =
+  | "pending"
+  | "broadcasting"
+  | "succeeded"
+  | "failed"
+  | "dead";
+
+export type RelayStatusResponse = {
+  id: string;
+  state: RelayState;
+  txHash?: string | null;
+  receipt?: unknown;
+  error?: string | null;
+};
+
+type BroadcasterClientDeps = {
+  fetch: FetchLike;
+};
+
+export function createBroadcasterClient(
+  baseUrl: string,
+  deps: BroadcasterClientDeps,
+) {
+  const http = createJsonHttpClient(baseUrl, deps);
+
+  return {
+    async submitRelay(params: SubmitRelayParams) {
+      return http.request<SubmitRelayResponse>({
+        method: "POST",
+        path: "/relays",
+        json: {
+          client_tx_id: params.clientTxId,
+          chain_id: params.chainId,
+          ...params.payload,
+        },
+      });
+    },
+
+    async getRelayStatus(relayId: string) {
+      return http.request<RelayStatusResponse>({
+        method: "GET",
+        path: `/relays/${relayId}`,
+      });
+    },
+  };
+}

package/clients/http.ts

@@ -0,0 +1,94 @@
+import ky, { HTTPError, TimeoutError } from "ky";
+
+export type FetchLike = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type JsonHttpDeps = { fetch: FetchLike };
+
+export type JsonRequestOptions = {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  path: string;
+  query?: Record<string, string | number | boolean | undefined>;
+  json?: unknown;
+  body?: BodyInit;
+  headers?: HeadersInit;
+  signal?: AbortSignal;
+};
+
+export type JsonHttpClient = {
+  request<T>(opts: JsonRequestOptions): Promise<T>;
+};
+
+export class HttpError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(message: string, status: number, body: unknown) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+async function readErrorBodySafe(res: Response) {
+  try {
+    return await res.clone().json();
+  } catch {
+    const text = await res.text();
+    return text || null;
+  }
+}
+
+export function createJsonHttpClient(
+  baseUrl: string,
+  deps: JsonHttpDeps,
+): JsonHttpClient {
+  if (!baseUrl) throw new Error("baseUrl is required");
+  if (!deps?.fetch) throw new Error("deps.fetch is required");
+
+  // Ensure `fetch` is invoked with a global `this` to avoid "Illegal invocation"
+  // errors in some browser environments when the function is extracted. // TODO: can we fix this in another way?
+  const fetchImpl: FetchLike = (...args) => deps.fetch.apply(globalThis, args);
+
+  const api = ky.create({
+    prefixUrl: baseUrl.replace(/\/+$/, ""),
+    fetch: fetchImpl,
+  });
+
+  return {
+    async request<T>(opts: JsonRequestOptions): Promise<T> {
+      try {
+        const res = api(opts.path.replace(/^\//, ""), {
+          method: opts.method,
+          searchParams: opts.query,
+          json: opts.json,
+          body: opts.body,
+          headers: opts.headers,
+          signal: opts.signal,
+        });
+        return await res.json<T>();
+      } catch (err) {
+        if (err instanceof HTTPError) {
+          const body = await readErrorBodySafe(err.response);
+          throw new HttpError(
+            `HTTP ${err.response.status} ${err.response.statusText}`.trim(),
+            err.response.status,
+            body,
+          );
+        }
+
+        if (err instanceof TimeoutError) {
+          throw new HttpError("HTTP timeout", 408, null);
+        }
+
+        throw new HttpError(
+          err instanceof Error ? err.message : "Network error",
+          0,
+          null,
+        );
+      }
+    },
+  };
+}