@unlink-xyz/core 0.1.0 → 0.1.2

package/clients/indexer.ts

@@ -0,0 +1,150 @@
+import type { FetchLike } from "./http.js";
+import { createJsonHttpClient } from "./http.js";
+import { isNotFoundError } from "../utils/async.js";
+
+// The HTTP API returns snake_case fields; the `Raw` helpers mirror that
+// payload exactly so we can normalize everything to camelCase in one place.
+type CommitmentRecordRaw = {
+  leaf_index: number;
+  commitment: string;
+  ciphertext: [string, string, string];
+  root: string;
+  tx_hash: string;
+  inserted_at: number;
+};
+
+export type CommitmentRecord = {
+  index: number;
+  commitment: string;
+  ciphertext: [string, string, string];
+  root: string;
+  txHash: string;
+  insertedAt: number;
+};
+
+type NullifierRecordRaw = {
+  nullifier: string;
+  tx_hash: string;
+  spent_at: number;
+  chain_id: number;
+};
+
+export type IndexerNullifierRecord = {
+  nullifier: string;
+  txHash: string;
+  spentAt: number;
+  chainId: number;
+};
+
+type CommitmentBatchResponseRaw = {
+  chain_id: number;
+  commitments: CommitmentRecordRaw[];
+  latest_root: string | null;
+};
+
+export type CommitmentBatchResponse = {
+  chainId: number;
+  commitments: CommitmentRecord[];
+  latestRoot: string | null;
+};
+
+export type FetchCommitmentsParams = {
+  chainId: number;
+  start?: number;
+  limit?: number;
+};
+
+export type GetCommitmentParams = {
+  chainId: number;
+  commitment: string;
+};
+
+export type GetNullifierParams = {
+  chainId: number;
+  nullifier: string;
+};
+
+type NullifierCountResponseRaw = {
+  chain_id: number;
+  count: number;
+};
+
+type IndexerClientDeps = {
+  fetch: FetchLike;
+};
+
+export function createIndexerClient(baseUrl: string, deps: IndexerClientDeps) {
+  const http = createJsonHttpClient(baseUrl, deps);
+
+  // Converts the snake_case record from the REST API into the camelCase shape
+  // the rest of the SDK consumes.
+  const normalizeRecord = (record: CommitmentRecordRaw): CommitmentRecord => ({
+    index: record.leaf_index,
+    commitment: record.commitment,
+    ciphertext: [...record.ciphertext] as [string, string, string],
+    root: record.root,
+    txHash: record.tx_hash,
+    insertedAt: record.inserted_at,
+  });
+
+  const normalizeNullifierRecord = (
+    record: NullifierRecordRaw,
+  ): IndexerNullifierRecord => ({
+    nullifier: record.nullifier,
+    txHash: record.tx_hash,
+    spentAt: record.spent_at,
+    chainId: record.chain_id,
+  });
+
+  return {
+    async fetchCommitmentBatch(
+      params: FetchCommitmentsParams,
+    ): Promise<CommitmentBatchResponse> {
+      const raw = await http.request<CommitmentBatchResponseRaw>({
+        method: "GET",
+        path: `/chains/${params.chainId}/commitments`,
+        query: {
+          start: params.start,
+          limit: params.limit,
+        },
+      });
+      return {
+        chainId: raw.chain_id,
+        commitments: raw.commitments.map(normalizeRecord),
+        latestRoot: raw.latest_root,
+      };
+    },
+    async getCommitment(
+      params: GetCommitmentParams,
+    ): Promise<CommitmentRecord> {
+      const raw = await http.request<CommitmentRecordRaw>({
+        method: "GET",
+        path: `/chains/${params.chainId}/commitments/${params.commitment}`,
+      });
+      return normalizeRecord(raw);
+    },
+    async getNullifier(
+      params: GetNullifierParams,
+    ): Promise<IndexerNullifierRecord | null> {
+      try {
+        const raw = await http.request<NullifierRecordRaw>({
+          method: "GET",
+          path: `/chains/${params.chainId}/nullifiers/${params.nullifier}`,
+        });
+        return normalizeNullifierRecord(raw);
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return null; // Nullifier not spent on-chain
+        }
+        throw err;
+      }
+    },
+    async getNullifierCount(chainId: number): Promise<number> {
+      const raw = await http.request<NullifierCountResponseRaw>({
+        method: "GET",
+        path: `/chains/${chainId}/nullifiers/count`,
+      });
+      return raw.count;
+    },
+  };
+}

package/config.ts

@@ -0,0 +1,39 @@
+const DEFAULT_RPC_URL = "http://localhost:3000";
+
+function readEnv(key: string): string | undefined {
+  if (typeof process !== "undefined" && process?.env) {
+    return process.env[key];
+  }
+  // Support environments where process isn't defined but a shim sets globalThis.process
+  const globalProcess = (
+    globalThis as typeof globalThis & {
+      process?: { env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return globalProcess?.env?.[key];
+}
+
+function readServiceUrl(envKey: string, fallback: string): string {
+  const raw = readEnv(envKey);
+  if (!raw) return fallback;
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error(`${envKey} must not be empty when set`);
+  }
+  return trimmed.replace(/\/+$/, "");
+}
+
+export const serviceConfig = {
+  /**
+   * Base URL for the Broadcaster HTTP API (default: http://localhost:8081).
+   */
+  broadcasterBaseUrl:
+    readServiceUrl("UNLINK_RPC_URL", DEFAULT_RPC_URL) + "/broadcaster",
+  /**
+   * Base URL for the Indexer HTTP API (default: http://localhost:8082).
+   */
+  indexerBaseUrl:
+    readServiceUrl("UNLINK_RPC_URL", DEFAULT_RPC_URL) + "/indexer",
+};
+
+export type ServiceConfig = typeof serviceConfig;

package/core.ts

@@ -0,0 +1,17 @@
+import { migrate } from "./schema.js";
+import type { Storage } from "./types.js";
+
+export type CoreDeps = {
+  storage: Storage;
+  rng: (n: number) => Uint8Array;
+};
+
+export async function initCore(deps: CoreDeps) {
+  if (!deps?.storage) throw new Error("storage dep required");
+  if (!deps?.rng) throw new Error("rng dep required");
+  await migrate(deps.storage);
+  return {
+    storage: deps.storage,
+    rng: deps.rng,
+  };
+}

package/dist/account/railgun-imports-prototype.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Quick smoke-test to guarantee the new dependency surface compiles and behaves as expected.
+ * This is a temporary helper that will be removed once zkAccount is migrated.
+ */
+export declare const railgunDependencySmokeTest: () => Promise<{
+    mnemonicRoundTrip: string;
+    packedPoint: Uint8Array<ArrayBufferLike>;
+    viewingKey: Uint8Array<ArrayBufferLike>;
+    address: `0zk1${string}`;
+    poseidonHash: bigint;
+}>;
+//# sourceMappingURL=railgun-imports-prototype.d.ts.map

package/dist/account/railgun-imports-prototype.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"railgun-imports-prototype.d.ts","sourceRoot":"","sources":["../../account/railgun-imports-prototype.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;EAwBtC,CAAC"}

package/dist/account/railgun-imports-prototype.js

@@ -0,0 +1,30 @@
+import { babyjub, poseidon } from '@railgun-community/circomlibjs';
+import { getPublicKey } from '@noble/ed25519';
+import { sha512 } from '@noble/hashes/sha512';
+import { bech32m } from '@scure/base';
+import { entropyToMnemonic, generateMnemonic, mnemonicToEntropy, mnemonicToSeedSync, validateMnemonic, } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+/**
+ * Quick smoke-test to guarantee the new dependency surface compiles and behaves as expected.
+ * This is a temporary helper that will be removed once zkAccount is migrated.
+ */
+export const railgunDependencySmokeTest = async () => {
+    const mnemonic = generateMnemonic(wordlist);
+    validateMnemonic(mnemonic, wordlist);
+    const seed = mnemonicToSeedSync(mnemonic);
+    const entropy = mnemonicToEntropy(mnemonic, wordlist);
+    const mnemonicRoundTrip = entropyToMnemonic(entropy, wordlist);
+    const babyjubPoint = babyjub.Base8;
+    const packedPoint = babyjub.packPoint(babyjubPoint);
+    const viewingKey = await getPublicKey(seed.slice(0, 32));
+    const digest = sha512(seed);
+    const address = bech32m.encode('0zk', bech32m.toWords(digest.subarray(0, 32)), 127);
+    const poseidonHash = poseidon([BigInt(1), BigInt(2), BigInt(3)]);
+    return {
+        mnemonicRoundTrip,
+        packedPoint,
+        viewingKey,
+        address,
+        poseidonHash,
+    };
+};

package/dist/clients/indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../clients/indexer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAc3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AASF,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAQF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,KAAK,iBAAiB,GAAG;IACvB,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;iCAyB9D,sBAAsB,GAC7B,OAAO,CAAC,uBAAuB,CAAC;0BAgBzB,mBAAmB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;yBAQlB,kBAAkB,GACzB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;+BAcR,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;EAQ5D"}
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../clients/indexer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAe3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AASF,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAQF,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAOF,KAAK,iBAAiB,GAAG;IACvB,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB;iCAyB9D,sBAAsB,GAC7B,OAAO,CAAC,uBAAuB,CAAC;0BAgBzB,mBAAmB,GAC1B,OAAO,CAAC,gBAAgB,CAAC;yBAQlB,kBAAkB,GACzB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;+BAcR,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;EAQ5D"}

package/dist/clients/indexer.js

@@ -1,5 +1,5 @@
-import { isNotFoundError } from "../utils/async.js";
 import { createJsonHttpClient } from "./http.js";
+import { isNotFoundError } from "../utils/async.js";
 export function createIndexerClient(baseUrl, deps) {
     const http = createJsonHttpClient(baseUrl, deps);
     // Converts the snake_case record from the REST API into the camelCase shape

package/dist/state/hydrator.d.ts

@@ -0,0 +1,16 @@
+export type LeafLoader = (chainId: number, index: number) => Promise<{
+    commitment: string;
+} | null>;
+export type HydrateChainParams = {
+    chainId: number;
+    trees: {
+        reset(chainId: number): void;
+        addLeaf(chainId: number, value: bigint): {
+            index: number;
+        };
+    };
+    loadLeaf: LeafLoader;
+    hydrated: Set<number>;
+};
+export declare function hydrateChain({ chainId, trees, loadLeaf, hydrated, }: HydrateChainParams): Promise<void>;
+//# sourceMappingURL=hydrator.d.ts.map

package/dist/state/hydrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrator.d.ts","sourceRoot":"","sources":["../../state/hydrator.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5D,CAAC;IACF,QAAQ,EAAE,UAAU,CAAC;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,wBAAsB,YAAY,CAAC,EACjC,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,EAAE,kBAAkB,iBAcpB"}

package/dist/state/hydrator.js

@@ -0,0 +1,18 @@
+import { parseHexToBigInt } from "../utils/bigint.js";
+export async function hydrateChain({ chainId, trees, loadLeaf, hydrated, }) {
+    if (hydrated.has(chainId))
+        return;
+    trees.reset(chainId);
+    let idx = 0;
+    for (;;) {
+        const leaf = await loadLeaf(chainId, idx);
+        if (!leaf)
+            break;
+        const { index } = trees.addLeaf(chainId, parseHexToBigInt(leaf.commitment));
+        if (index !== idx) {
+            throw new Error("stored leaves are inconsistent with local tree");
+        }
+        idx += 1;
+    }
+    hydrated.add(chainId);
+}

package/dist/state/job-store.d.ts

@@ -0,0 +1,12 @@
+import type { Storage } from "../types.js";
+import type { JobStatus, PendingJobKind, PendingJobRecord } from "./jobs.js";
+export declare function createJobStore(storage: Storage): {
+    putPendingJob(job: PendingJobRecord): Promise<void>;
+    getPendingJob(relayId: string): Promise<PendingJobRecord | null>;
+    listPendingJobs(filter?: {
+        kind?: PendingJobKind;
+        statuses?: JobStatus[];
+    }): Promise<PendingJobRecord[]>;
+    deletePendingJob(relayId: string): Promise<void>;
+};
+//# sourceMappingURL=job-store.d.ts.map

package/dist/state/job-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-store.d.ts","sourceRoot":"","sources":["../../state/job-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EACd,gBAAgB,EAGjB,MAAM,WAAW,CAAC;AA4GnB,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO;uBAElB,gBAAgB;2BASZ,MAAM;6BAKzB;QACN,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;8BAe6B,MAAM;EAIzC"}

package/dist/state/job-store.js

@@ -0,0 +1,118 @@
+import { keys } from "../keys.js";
+import { decodeJson, encodeJson, getJson } from "../utils/json-codec.js";
+import { ensureAddress, ensureChainId, ensurePositiveInt, } from "../utils/validators.js";
+import { DEFAULT_JOB_TIMEOUT_MS } from "./jobs.js";
+const VALID_STATUSES = [
+    "pending",
+    "submitted",
+    "broadcasting",
+    "succeeded",
+    "failed",
+    "dead",
+];
+function assertStatus(status) {
+    if (!VALID_STATUSES.includes(status)) {
+        throw new Error(`invalid job status: ${status}`);
+    }
+}
+function assertKind(kind) {
+    if (kind !== "deposit" && kind !== "transact") {
+        throw new Error(`invalid job kind: ${kind}`);
+    }
+}
+function normalizeTimestamps(job) {
+    const createdAt = typeof job.createdAt === "number" && Number.isFinite(job.createdAt)
+        ? job.createdAt
+        : Date.now();
+    const timeoutMs = typeof job.timeoutMs === "number" && job.timeoutMs > 0
+        ? job.timeoutMs
+        : DEFAULT_JOB_TIMEOUT_MS;
+    return {
+        ...job,
+        createdAt,
+        timeoutMs,
+    };
+}
+function validateTransactContext(context) {
+    ensurePositiveInt("context index", context.index);
+    if (!context.nullifier) {
+        throw new Error("context nullifier is required");
+    }
+    const { witness } = context;
+    if (!witness) {
+        throw new Error("context witness is required");
+    }
+    ensurePositiveInt("witness leafIndex", witness.leafIndex);
+    if (!Array.isArray(witness.pathElements) ||
+        !Array.isArray(witness.pathIndices)) {
+        throw new Error("witness pathElements and pathIndices are required");
+    }
+}
+function validateTransactJob(job) {
+    ensureAddress("pool address", job.poolAddress);
+    if (!job.calldata) {
+        throw new Error("calldata is required for transact job");
+    }
+    job.contexts.forEach(validateTransactContext);
+    job.predictedOutputs.forEach((output) => {
+        if (!output.hex) {
+            throw new Error("predicted output hex is required");
+        }
+        ensurePositiveInt("predicted output index", output.index);
+    });
+}
+function validateDepositJob(job) {
+    if (!job.predictedCommitment?.hex) {
+        throw new Error("predicted commitment hex is required");
+    }
+    if (job.predictedCommitment.index !== undefined) {
+        ensurePositiveInt("predicted commitment index", job.predictedCommitment.index);
+    }
+}
+function validateJob(job) {
+    if (!job.relayId) {
+        throw new Error("relayId is required");
+    }
+    ensureChainId(job.chainId);
+    assertStatus(job.status);
+    assertKind(job.kind);
+    ensurePositiveInt("job createdAt", job.createdAt);
+    ensurePositiveInt("job timeoutMs", job.timeoutMs);
+    if (job.lastCheckedAt !== undefined) {
+        ensurePositiveInt("job lastCheckedAt", job.lastCheckedAt);
+    }
+    if (job.kind === "deposit") {
+        validateDepositJob(job);
+    }
+    else {
+        validateTransactJob(job);
+    }
+}
+function buildJobKey(relayId) {
+    return keys.job(relayId);
+}
+export function createJobStore(storage) {
+    return {
+        async putPendingJob(job) {
+            const normalized = normalizeTimestamps(job);
+            validateJob(normalized);
+            await storage.put(buildJobKey(normalized.relayId), encodeJson(normalized));
+        },
+        async getPendingJob(relayId) {
+            return getJson(storage, buildJobKey(relayId));
+        },
+        async listPendingJobs(filter = {}) {
+            const entries = await storage.iter({ prefix: "jobs:" });
+            const statuses = filter.statuses ?? VALID_STATUSES;
+            const filtered = entries
+                .map(({ value }) => decodeJson(value))
+                .filter((job) => (filter.kind === undefined || job.kind === filter.kind) &&
+                statuses.includes(job.status));
+            filtered.sort((a, b) => a.createdAt - b.createdAt);
+            return filtered;
+        },
+        async deletePendingJob(relayId) {
+            await storage.delete(buildJobKey(relayId));
+        },
+    };
+}

package/dist/state/jobs.d.ts

@@ -0,0 +1,50 @@
+export type JobStatus = "pending" | "submitted" | "broadcasting" | "succeeded" | "failed" | "dead";
+export type PendingJobKind = "deposit" | "transact";
+export type PendingJobBase = {
+    relayId: string;
+    kind: PendingJobKind;
+    chainId: number;
+    status: JobStatus;
+    broadcasterRelayId?: string | null;
+    txHash?: string | null;
+    createdAt: number;
+    lastCheckedAt?: number;
+    timeoutMs: number;
+    error?: string | null;
+};
+export type PendingDepositJob = PendingJobBase & {
+    kind: "deposit";
+    predictedCommitment: {
+        hex: string;
+        index?: number;
+        root?: string;
+    };
+};
+export type PendingTransactContext = {
+    index: number;
+    nullifier: string;
+    witness: {
+        root: string;
+        leaf: string;
+        pathElements: string[][];
+        pathIndices: number[];
+        leafIndex: number;
+    };
+    root: string;
+};
+export type PendingTransactOutput = {
+    hex: string;
+    index: number;
+    root?: string;
+};
+export type PendingTransactJob = PendingJobBase & {
+    kind: "transact";
+    poolAddress: string;
+    calldata: string;
+    contexts: PendingTransactContext[];
+    predictedOutputs: PendingTransactOutput[];
+    expectedRoot?: string;
+};
+export type PendingJobRecord = PendingDepositJob | PendingTransactJob;
+export declare const DEFAULT_JOB_TIMEOUT_MS: number;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/state/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../state/jobs.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,WAAW,GACX,cAAc,GACd,WAAW,GACX,QAAQ,GACR,MAAM,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,IAAI,EAAE,SAAS,CAAC;IAChB,mBAAmB,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;QACzB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG;IAChD,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,gBAAgB,EAAE,qBAAqB,EAAE,CAAC;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEtE,eAAO,MAAM,sBAAsB,QAAgB,CAAC"}

package/dist/state/jobs.js

@@ -0,0 +1 @@
+export const DEFAULT_JOB_TIMEOUT_MS = 5 * 60 * 1000;

package/dist/state.d.ts

@@ -0,0 +1,83 @@
+import type { Storage } from './types.js';
+export declare function ensurePositiveInt(label: string, value: number): void;
+export declare function ensureChainId(chainId: number): void;
+/**
+ * Locally cached metadata for a shielded note we consider owned.
+ */
+export type NoteRecord = {
+    chainId: number;
+    /** Leaf index within the on-chain tree (zero-based, monotonic). */
+    index: number;
+    /** Canonical asset identifier, typically the ERC-20 address lowercased. */
+    token: string;
+    /** Amount expressed as an unsigned BigInt serialized to a base-10 string. */
+    value: string;
+    /** Commitment stored on-chain (Poseidon(note)). */
+    commitment: string;
+    /** Nullifier public key derived from the account's master keys. */
+    npk: string;
+    /**
+     * Master public key for the account (Poseidon(spendingPk.public, nullifyingKey)).
+     * Acts as the stable account identifier when grouping notes locally.
+     */
+    mpk: string;
+    /** Randomizer used when committing the note. */
+    random: string;
+    /** Nullifier that will be revealed when the note is spent. */
+    nullifier: string;
+    /** Optional timestamp when the note was marked as spent. */
+    spentAt?: number;
+};
+/**
+ * Details about a nullifier observed on-chain, whether or not we own the note.
+ */
+export type NullifierRecord = {
+    chainId: number;
+    /** Nullifier value (expected to match NoteRecord.nullifier). */
+    nullifier: string;
+    /** Leaf index of the corresponding note when known. */
+    noteIndex?: number;
+};
+/**
+ * Public information about a leaf commitment inserted into the pool's tree.
+ */
+export type LeafRecord = {
+    chainId: number;
+    /** Leaf index inside the tree (zero-based). */
+    index: number;
+    /** Commitment value stored in the tree. */
+    commitment: string;
+};
+/**
+ * Historical merkle root snapshot used for proof construction.
+ */
+export type RootRecord = {
+    chainId: number;
+    /** Sequence number emitted by the pool contract; increments every time the root updates. */
+    sequence: number;
+    /** Merkle root value committed on-chain. */
+    root: string;
+};
+export declare function createStateStore(storage: Storage): {
+    putNote(note: NoteRecord): Promise<void>;
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    listNotes(options?: {
+        chainId?: number;
+        mpk?: string;
+        includeSpent?: boolean;
+    }): Promise<NoteRecord[]>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<NoteRecord>;
+    markNoteUnspent(chainId: number, index: number): Promise<NoteRecord>;
+    getShieldedBalance(mpk: string, options?: {
+        chainId?: number;
+    }): Promise<Record<string, bigint>>;
+    putNullifier(nullifier: NullifierRecord): Promise<void>;
+    getNullifier(chainId: number, value: string): Promise<NullifierRecord | null>;
+    putLeaf(leaf: LeafRecord): Promise<void>;
+    getLeaf(chainId: number, index: number): Promise<LeafRecord | null>;
+    putRoot(root: RootRecord): Promise<void>;
+    getRoot(chainId: number, sequence: number): Promise<RootRecord | null>;
+    putCiphertext(chainId: number, index: number, payload: Uint8Array): Promise<void>;
+    getCiphertext(chainId: number, index: number): Promise<Uint8Array<ArrayBuffer> | null>;
+};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAW,OAAO,EAAE,MAAM,YAAY,CAAC;AASnD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAI7D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,QAI5C;AAkBD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CAIpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CAIpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CAGd,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO;kBAEzB,UAAU;qBAsCP,MAAM,SAAS,MAAM;wBAOjC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE;2BAuB1D,MAAM,SACR,MAAM;6BAkBgB,MAAM,SAAS,MAAM;4BAiB7C,MAAM,YACF;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;4BAgBD,eAAe;0BASjB,MAAM,SAAS,MAAM;kBAK7B,UAAU;qBAMP,MAAM,SAAS,MAAM;kBAMxB,UAAU;qBAMP,MAAM,YAAY,MAAM;2BAMlB,MAAM,SAAS,MAAM,WAAW,UAAU;2BAQ1C,MAAM,SAAS,MAAM;EASrD"}