@unlink-xyz/core 0.1.3 → 0.1.4

package/transactions/types.ts

@@ -1,141 +0,0 @@
-import { IMTMerkleProof } from "@zk-kit/imt";
-
-import type { ZkAccount } from "../account/zkAccount.js";
-import type { CommitmentRecord } from "../clients/indexer.js";
-import type {
-  JobStatus,
-  LeafRecord,
-  NoteRecord,
-  NullifierRecord,
-  PendingJobKind,
-  PendingJobRecord,
-  RootRecord,
-} from "../state/index.js";
-
-/**
- * Base state store interface with common methods shared across services.
- */
-export type BaseStateStore = {
-  putLeaf(record: LeafRecord): Promise<void>;
-  getLeaf(chainId: number, index: number): Promise<LeafRecord | null>;
-  clearLeaves(chainId: number): Promise<void>;
-  putRoot(record: RootRecord): Promise<void>;
-  putPendingJob(job: PendingJobRecord): Promise<void>;
-  getPendingJob(relayId: string): Promise<PendingJobRecord | null>;
-  listPendingJobs(filter?: {
-    kind?: PendingJobKind;
-    statuses?: JobStatus[];
-  }): Promise<PendingJobRecord[]>;
-  deletePendingJob(relayId: string): Promise<void>;
-};
-
-export type DepositStateStore = BaseStateStore;
-
-export type TransactStateStore = BaseStateStore & {
-  getNote(chainId: number, index: number): Promise<NoteRecord | null>;
-  markNoteSpent(
-    chainId: number,
-    index: number,
-    spentAt?: number,
-  ): Promise<NoteRecord>;
-  putNullifier(record: NullifierRecord): Promise<void>;
-};
-
-export type DepositNoteInput = {
-  mpk: bigint;
-  random: bigint;
-  token: string;
-  amount: bigint;
-};
-
-export type DepositRequest = {
-  zkAccount: ZkAccount;
-  chainId: number;
-  poolAddress: string;
-  depositor: string;
-  note: DepositNoteInput;
-};
-
-export type DepositRelayResult = {
-  relayId: string;
-  calldata: string;
-  commitment: string;
-};
-
-export type DepositSyncResult = {
-  chainId: number;
-  index: number;
-  commitment: string;
-  root: string;
-};
-
-/**
- * Minimal reference to an input note; index resolves the canonical note state.
- */
-export type SpendNoteReference = {
-  index: number;
-};
-
-export type WithdrawalNoteInput = {
-  npk: bigint;
-  amount: bigint;
-  token: string;
-};
-
-/**
- * Private output note to append back into the pool after spending.
- */
-export type OutputNoteInput = {
-  mpk: bigint;
-  random: bigint;
-  token: string;
-  amount: bigint;
-};
-
-/**
- * Placeholder proof structure matching the pool interface; pubSignals remain meaningful.
- */
-export type Proof = {
-  pA: [bigint, bigint];
-  pB: [[bigint, bigint], [bigint, bigint]];
-  pC: [bigint, bigint];
-  pubSignals: bigint[];
-};
-
-/**
- * Parameters required to a mock transact call against the local state.
- */
-export type TransactRequest = {
-  zkAccount: ZkAccount; // TODO: put zkAccount in parent?
-  chainId: number;
-  poolAddress: string;
-  token: string;
-  inputs: SpendNoteReference[];
-  withdrawal: WithdrawalNoteInput;
-  outputs: OutputNoteInput[];
-};
-
-/**
- * Result of the mock transact flow, including calldata and state deltas.
- */
-export type TransactRelayResult = {
-  relayId: string;
-  calldata: string;
-  proof: Proof;
-  witnesses: IMTMerkleProof[];
-  nullifiers: string[];
-  predictedCommitments: string[];
-};
-
-export type TransactSyncResult = {
-  chainId: number;
-  root: string;
-  nullifiers: string[];
-  newCommitments: string[];
-  txHash?: string;
-  indexedCommitments?: CommitmentRecord[];
-};
-
-export type Ciphertext = {
-  data: [bigint, bigint, bigint];
-};

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./",
-    "composite": true,
-    "declaration": true,
-    "declarationMap": true,
-    "noEmit": false,
-    "resolveJsonModule": true,
-    "typeRoots": ["./types", "../../node_modules/@types"]
-  },
-  "include": ["./**/*.ts", "./circuits.json"],
-  "exclude": ["./dist/**/*", "./node_modules/**/*", "**/*.test.ts"]
-}

package/types/global.d.ts

@@ -1,15 +0,0 @@
-declare module "@railgun-community/circomlibjs" {
-  export const babyjub: {
-    Base8: [bigint, bigint];
-    packPoint: (point: [bigint, bigint]) => Uint8Array;
-    unpackPoint: (bytes: Uint8Array) => [bigint, bigint];
-  };
-  export const poseidon: (inputs: (bigint | number)[]) => bigint;
-  export const eddsa: {
-    prv2pub: (privKey: Uint8Array) => [bigint, bigint];
-    signPoseidon: (
-      privKey: Uint8Array,
-      message: bigint,
-    ) => { R8: [bigint, bigint]; S: bigint };
-  };
-}

package/types.ts

@@ -1,24 +0,0 @@
-export type Bytes = Uint8Array;
-
-export type IterOptions = {
-  prefix?: string;
-  start?: string; // inclusive
-  end?: string; // inclusive
-  limit?: number;
-  reverse?: boolean;
-};
-
-export type KvPair = { key: string; value: Bytes };
-
-export type BatchOp = { put?: [string, Bytes]; del?: string };
-
-export type Storage = {
-  open(): Promise<void>;
-  get(key: string): Promise<Bytes | null>;
-  delete(key: string): Promise<void>;
-  put(key: string, value: Bytes): Promise<void>;
-  batch(ops: BatchOp[]): Promise<void>;
-  iter(opts: IterOptions): Promise<KvPair[]>;
-  getSchemaVersion(): Promise<number>;
-  setSchemaVersion(v: number): Promise<void>;
-};

package/utils/async.ts

@@ -1,15 +0,0 @@
-import { HttpError } from "../clients/http.js";
-
-/**
- * Promise-based delay utility.
- */
-export function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Type guard for HTTP 404 errors.
- */
-export function isNotFoundError(err: unknown): err is HttpError {
-  return err instanceof HttpError && err.status === 404;
-}

package/utils/bigint.ts

@@ -1,34 +0,0 @@
-import { CoreError } from "../errors.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-
-/**
- * BigInt helpers shared across transaction builders to keep formatting consistent.
- */
-export function formatUint256(value: bigint): string {
-  assertNonNegative("uint256", value);
-  return ByteUtils.nToHex(value, ByteLength.UINT_256, true);
-}
-
-export function parseHexToBigInt(value: string): bigint {
-  return ByteUtils.hexToBigInt(value);
-}
-
-export function parseNumToBigInt(value: string | undefined): bigint {
-  if (value === undefined) {
-    throw new CoreError("Value is undefined");
-  }
-  return BigInt(value);
-}
-
-export function assertNonNegative(label: string, value: bigint): void {
-  if (value < 0n) {
-    throw new CoreError(`${label} must be non-negative`);
-  }
-}
-
-export function ensureBigint(label: string, value: unknown): bigint {
-  if (typeof value !== "bigint") {
-    throw new CoreError(`${label} must be provided as a bigint`);
-  }
-  return value;
-}

package/utils/crypto.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { CoreError } from "../errors.js";
-import { Ciphertext, OutputNoteInput } from "../transactions/types.js";
-import { decryptNote, encryptNote } from "./crypto.js";
-
-describe("crypto", () => {
-  describe("decryptNote", () => {
-    it("successfully decrypts with correct key", () => {
-      // Create a valid note
-      const originalNote: OutputNoteInput = {
-        mpk: 12345n,
-        random: 67890n,
-        token: "0x1111111111111111111111111111111111111111",
-        amount: 1000n,
-      };
-
-      const ciphertext = encryptNote(originalNote);
-
-      // Decrypt with the correct key (mpk)
-      const decryptedNote = decryptNote(ciphertext, originalNote.mpk);
-
-      // Verify decrypted data matches original
-      expect(decryptedNote.mpk).toBe(originalNote.mpk);
-      expect(decryptedNote.random).toBe(originalNote.random);
-      expect(decryptedNote.token).toBe(originalNote.token);
-      expect(decryptedNote.amount).toBe(originalNote.amount);
-    });
-
-    it("throws CoreError when decrypting with wrong key", () => {
-      const originalNote: OutputNoteInput = {
-        mpk: 12345n,
-        random: 67890n,
-        token: "0x1111111111111111111111111111111111111111",
-        amount: 1000n,
-      };
-
-      // Encrypt the note with the correct key
-      const ciphertext = encryptNote(originalNote);
-
-      // Try to decrypt with a DIFFERENT key
-      const wrongKey = 99999n;
-
-      // Should throw CoreError with "Invalid Decrypt" message
-      expect(() => decryptNote(ciphertext, wrongKey)).toThrow(CoreError);
-      expect(() => decryptNote(ciphertext, wrongKey)).toThrow(
-        "Invalid Decrypt",
-      );
-    });
-
-    it("throws CoreError when decrypted token exceeds valid Ethereum address range", () => {
-      const invalidCiphertext: Ciphertext = {
-        data: [
-          123n,
-          // This large value will decrypt to something > 160 bits
-          0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn,
-          456n,
-        ],
-      };
-
-      const someKey = 12345n;
-
-      expect(() => decryptNote(invalidCiphertext, someKey)).toThrow(CoreError);
-      expect(() => decryptNote(invalidCiphertext, someKey)).toThrow(
-        "Invalid Decrypt",
-      );
-    });
-  });
-});

package/utils/crypto.ts

@@ -1,58 +0,0 @@
-import { poseidon } from "@railgun-community/circomlibjs";
-
-import { CoreError } from "../errors.js";
-import {
-  Ciphertext,
-  DepositNoteInput,
-  DepositRequest,
-  OutputNoteInput,
-} from "../transactions/types.js";
-import { parseHexToBigInt } from "./bigint.js";
-
-export function encryptNote(
-  note: OutputNoteInput | DepositNoteInput,
-): Ciphertext {
-  return {
-    data: [
-      encrypt(note.random, note.mpk),
-      encrypt(parseHexToBigInt(note.token), note.mpk),
-      encrypt(note.amount, note.mpk),
-    ],
-  };
-}
-
-export function encrypt(data: bigint, key: bigint): bigint {
-  return poseidon([0x556e6c696e6b, key]) ^ data;
-}
-
-export function decryptNote(c: Ciphertext, key: bigint): OutputNoteInput {
-  const token_bigint = encrypt(c.data[1], key);
-  if (token_bigint > 0xffffffffffffffffffffffffffffffffffffffffn) {
-    throw new CoreError("Invalid Decrypt");
-  }
-  const result = {
-    mpk: key,
-    random: encrypt(c.data[0], key),
-    token: "0x" + token_bigint.toString(16).padStart(40, "0"),
-    amount: encrypt(c.data[2], key),
-  };
-  return result;
-}
-
-export function deriveCommitment(note: {
-  npk: bigint;
-  amount: bigint;
-  token: string;
-}) {
-  const tokenScalar = BigInt(note.token);
-  return poseidon([note.npk, tokenScalar, note.amount]);
-}
-
-export function deriveNpk(request: DepositRequest) {
-  return poseidon([request.note.mpk, request.note.random]);
-}
-
-export function computeCommitment(request: DepositRequest, npk: bigint) {
-  const tokenScalar = BigInt(request.note.token);
-  return poseidon([npk, tokenScalar, request.note.amount]);
-}

package/utils/json-codec.ts

@@ -1,38 +0,0 @@
-import { CoreError } from "../errors.js";
-import { validateKey } from "../keys.js";
-import { Storage } from "../types.js";
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-
-export type JsonRecord = { [key: string]: unknown };
-
-export function encodeJson(value: JsonRecord): Uint8Array {
-  return encoder.encode(JSON.stringify(value));
-}
-
-export function decodeJson<T extends JsonRecord>(payload: Uint8Array): T {
-  try {
-    return JSON.parse(decoder.decode(payload)) as T;
-  } catch (err) {
-    throw new CoreError("failed to decode stored state payload");
-  }
-}
-
-export async function putJson(
-  storage: Storage,
-  key: string,
-  record: JsonRecord,
-) {
-  validateKey(key);
-  await storage.put(key, encodeJson(record));
-}
-
-export async function getJson<T extends JsonRecord>(
-  storage: Storage,
-  key: string,
-) {
-  const payload = await storage.get(key);
-  if (!payload) return null;
-  return decodeJson<T>(payload);
-}

package/utils/polling.ts

@@ -1,6 +0,0 @@
-/**
- * Shared polling configuration constants.
- */
-export const DEFAULT_POLL_INTERVAL_MS = 500;
-export const DEFAULT_POLL_TIMEOUT_MS = 30_000;
-export const MAX_POLL_INTERVAL_MS = 5_000;

package/utils/signature.ts

@@ -1,16 +0,0 @@
-import { Buffer } from "buffer";
-import { eddsa } from "@railgun-community/circomlibjs";
-
-/**
- * Generates an EdDSA signature over a poseidon-hashed message using the spending private key.
- * Used for transact public signal signing.
- */
-export function signTransactMessage(
-  spendingPrivateKey: Uint8Array,
-  message: bigint,
-): { R8: [bigint, bigint]; S: bigint } {
-  const key = Buffer.isBuffer(spendingPrivateKey)
-    ? spendingPrivateKey
-    : Buffer.from(spendingPrivateKey);
-  return eddsa.signPoseidon(key, message);
-}

package/utils/validators.test.ts

@@ -1,64 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  ensureFieldElement,
-  ensureNoteCommitmentInput,
-  ensureWithdrawalInput,
-} from "./validators.js";
-
-const MAX =
-  21_888_242_871_839_275_222_246_405_745_257_275_088_548_364_400_416_034_343_698_204_186_575_808_495_617n;
-
-describe("validators", () => {
-  describe("ensureWithdrawalInput", () => {
-    it("accepts valid inputs", () => {
-      const input = ensureWithdrawalInput("withdrawal", {
-        npk: 1n,
-        amount: 2n,
-        token: "0x1111111111111111111111111111111111111111",
-      });
-      expect(input.amount).toBe(2n);
-    });
-
-    it.skip("rejects zero amounts", () => {
-      // TODO: why would we want to do this?
-      expect(() =>
-        ensureWithdrawalInput("withdrawal", {
-          npk: 1n,
-          amount: 0n,
-          token: "0x1111111111111111111111111111111111111111",
-        }),
-      ).toThrow("withdrawal.amount must be greater than zero");
-    });
-
-    it("rejects values outside the field", () => {
-      expect(() =>
-        ensureWithdrawalInput("withdrawal", {
-          npk: MAX,
-          amount: 1n,
-          token: "0x1111111111111111111111111111111111111111",
-        }),
-      ).toThrow("must be less than the SNARK scalar field");
-    });
-  });
-
-  describe("ensureNoteCommitmentInput", () => {
-    it("rejects zero amounts", () => {
-      expect(() =>
-        ensureNoteCommitmentInput("note", {
-          npk: 5n,
-          amount: 0n,
-          token: "0x1111111111111111111111111111111111111111",
-        }),
-      ).toThrow("note.amount must be greater than zero");
-    });
-  });
-
-  describe("ensureFieldElement", () => {
-    it("throws for negative values", () => {
-      expect(() => ensureFieldElement("value", -1n)).toThrow(
-        "value must be a non-negative field element",
-      );
-    });
-  });
-});

package/utils/validators.ts

@@ -1,86 +0,0 @@
-import { CoreError } from "../errors.js";
-import { assertNonNegative } from "./bigint.js";
-
-export const SNARK_SCALAR_FIELD =
-  21_888_242_871_839_275_222_246_405_745_257_275_088_548_364_400_416_034_343_698_204_186_575_808_495_617n;
-
-export function ensurePositiveInt(label: string, value: number) {
-  if (!Number.isInteger(value) || value < 0) {
-    throw new CoreError(`${label} must be a non-negative integer`);
-  }
-}
-
-export function ensureChainId(chainId: number) {
-  if (!Number.isInteger(chainId) || chainId <= 0) {
-    throw new CoreError("chainId must be a positive integer");
-  }
-}
-
-/** Guards master public key strings against empty values. */
-export function ensureMpk(mpk: string) {
-  if (typeof mpk !== "string" || mpk.length === 0) {
-    throw new CoreError("note mpk must be a non-empty string");
-  }
-}
-
-export function ensureBigIntString(label: string, value: string) {
-  let parsed: bigint;
-  try {
-    parsed = BigInt(value);
-  } catch {
-    throw new CoreError(`${label} must be a base-10 bigint string`);
-  }
-  if (parsed < 0n) {
-    throw new CoreError(`${label} must be non-negative`);
-  }
-}
-
-const ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
-
-export function ensureAddress(label: string, value: string) {
-  if (typeof value !== "string" || !ADDRESS_REGEX.test(value)) {
-    throw new CoreError(`${label} must be a 0x-prefixed hex address`);
-  }
-}
-
-/** Confirms the bigint resides in the SNARK scalar field range. */
-export function ensureFieldElement(label: string, value: bigint) {
-  if (value < 0n) {
-    throw new CoreError(`${label} must be a non-negative field element`);
-  }
-  if (value >= SNARK_SCALAR_FIELD) {
-    throw new CoreError(`${label} must be less than the SNARK scalar field`);
-  }
-}
-
-/** Validates withdrawal note public data before encoding calldata. */
-export function ensureWithdrawalInput(
-  label: string,
-  withdrawal: { npk: bigint; amount: bigint; token: string },
-) {
-  assertNonNegative(`${label}.npk`, withdrawal.npk);
-  ensureFieldElement(`${label}.npk`, withdrawal.npk);
-  assertNonNegative(`${label}.amount`, withdrawal.amount);
-  // if (withdrawal.amount === 0n) {
-  //   throw new CoreError(`${label}.amount must be greater than zero`);
-  // }
-  ensureFieldElement(`${label}.amount`, withdrawal.amount);
-  ensureAddress(`${label}.token`, withdrawal.token);
-  return withdrawal;
-}
-
-/** Validates note parameters before producing a Poseidon commitment. */
-export function ensureNoteCommitmentInput(
-  label: string,
-  note: { npk: bigint; amount: bigint; token: string },
-) {
-  assertNonNegative(`${label}.npk`, note.npk);
-  ensureFieldElement(`${label}.npk`, note.npk);
-  assertNonNegative(`${label}.amount`, note.amount);
-  if (note.amount === 0n) {
-    throw new CoreError(`${label}.amount must be greater than zero`);
-  }
-  ensureFieldElement(`${label}.amount`, note.amount);
-  ensureAddress(`${label}.token`, note.token);
-  return note;
-}