zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/build/bindClient.js

@@ -0,0 +1,187 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * bindClient.ts
+ *
+ * Browser-safe client for the non-custodial device-binding flow.
+ * Mirrors `buyClient.ts` in shape: the caller drives the wallet step
+ * between `proveBind` and `confirmBind`, so the SDK stays
+ * wallet-agnostic.
+ *
+ * Binding is a root-mutating tx on the same per-app in-flight slot
+ * that buy / renew / refund use — a concurrent request
+ * against the same app returns 409 `ProveQueueBusyError`, which the
+ * caller must catch and retry (see the retry loop in
+ * examples/src/bind.ts).
+ *
+ * The signature scheme is Pallas Schnorr and is re-verified INSIDE
+ * the on-chain circuit via `Signature.verify()` — a compromised
+ * backend cannot forge a bind because it can't produce a signature
+ * that satisfies the in-circuit check.
+ */
+import { Field } from 'o1js';
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import { encodePublicKey, encodeSignature, signBinding, slotStateOf } from './ownershipSignature.js';
+function baseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+async function readJsonError(resp) {
+    try {
+        const body = await resp.json();
+        if (typeof body.error === 'string')
+            return body.error;
+    }
+    catch { /* body wasn't JSON */ }
+    return `HTTP ${resp.status}`;
+}
+// Sample a fresh replay-defense nonce. WebCrypto is required for
+// `crypto.getRandomValues` — same runtime floor as the rest of the
+// signing surface (Node ≥ 20, modern browsers).
+function freshNonce() {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('crypto.getRandomValues unavailable — bindClient requires Node ≥ 20 or a modern browser');
+    }
+    const bytes = new Uint8Array(16); // 128 bits
+    crypto.getRandomValues(bytes);
+    let n = 0n;
+    for (const b of bytes)
+        n = (n << 8n) | BigInt(b);
+    // Field(n) is safe: 128 bits << the Pallas base field size, so no
+    // modular reduction ever fires here.
+    return Field(n).toString();
+}
+// Read the target slot's current packed state and the license's expiry from
+// the keeper's license mirror. Shared with unbindClient.
+export async function fetchBindingState(opts) {
+    const fetcher = opts.fetcher ?? fetch;
+    const url = `${baseUrl(opts.keeperUrl)}/license/${encodeURIComponent(opts.zkAppAddress)}/`
+        + `${encodeURIComponent(opts.licenseHash)}?network=${encodeURIComponent(opts.network)}`;
+    const resp = await fetcher(url, { signal: opts.signal });
+    if (!resp.ok)
+        throw new Error(`License lookup failed: ${await readJsonError(resp)}`);
+    const body = await resp.json();
+    if (!body.found || !body.expirySlot)
+        throw new Error('License not found on the keeper.');
+    return {
+        slotState: slotStateOf((body.devices ?? [])[opts.slotIndex]),
+        expirySlot: body.expirySlot,
+    };
+}
+// POST /prove/bind — backend compiles + proves the bind tx.
+//
+// Retry contract:
+//   - 409 `proving queue busy` → `ProveQueueBusyError`; caller catches
+//     and retries with `retryAfterMs` cadence (see examples/src/bind.ts).
+//   - Any other non-2xx surfaces the body's `error` field verbatim.
+export async function proveBind(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const nonce = req.nonce ?? freshNonce();
+    const { slotState, expirySlot } = (req.slotState !== undefined && req.expirySlot !== undefined)
+        ? { slotState: req.slotState, expirySlot: req.expirySlot }
+        : await fetchBindingState({ ...req, fetcher });
+    const ownerPubKey = req.ownerPrivateKey.toPublicKey();
+    const ownerSig = signBinding(req.ownerPrivateKey, {
+        licenseHash: req.licenseHash,
+        deviceCommitment: req.deviceCommitment,
+        slotIndex: req.slotIndex,
+        nonce,
+        slotState,
+        expirySlot,
+        zkAppAddress: req.zkAppAddress,
+    });
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/bind`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal: req.signal,
+        body: JSON.stringify({
+            licenseHash: req.licenseHash,
+            buyerAddress: req.buyerAddress,
+            zkAppAddress: req.zkAppAddress,
+            network: req.network,
+            ownerPubKey: encodePublicKey(ownerPubKey),
+            ownerSig: encodeSignature(ownerSig),
+            deviceCommitment: req.deviceCommitment,
+            slotIndex: req.slotIndex,
+            nonce,
+        }),
+    });
+    if (!resp.ok) {
+        const parsed = await readErrorBody(resp);
+        const queueBusy = tryQueueBusyFromBody(parsed);
+        if (queueBusy)
+            throw queueBusy;
+        throw keeperError(parsed);
+    }
+    return await resp.json();
+}
+// POST /confirm/bind — pass-through no-op that clears the staged
+// intent on the backend. Call this only after the wallet has returned
+// a real txHash; a cancelled or dropped signature leaves the intent
+// to expire on its own.
+export async function confirmBind(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/bind`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        signal: req.signal,
+        body: JSON.stringify({
+            zkAppAddress: req.zkAppAddress,
+            licenseHash: req.licenseHash,
+            txHash: req.txHash,
+        }),
+    });
+    if (!resp.ok)
+        throw new Error(await readJsonError(resp));
+    return { ok: true };
+}
+// Polls GET /license/:zkAppAddress/:licenseHash until the bind has
+// landed on-chain (the target slot's commitment matches the expected
+// value) or the timeout fires. Mirrors pollRenewStatus in shape.
+export async function pollBindStatus(opts) {
+    const fetcher = opts.fetcher ?? fetch;
+    const interval = opts.intervalMs ?? 10_000;
+    const timeout = opts.timeoutMs ?? 20 * 60 * 1000;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeout;
+    const url = `${baseUrl(opts.keeperUrl)}/license/${encodeURIComponent(opts.zkAppAddress)}/${encodeURIComponent(opts.licenseHash)}?network=${opts.network}`;
+    while (true) {
+        if (opts.signal?.aborted)
+            throw new Error('pollBindStatus aborted');
+        let status = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+        try {
+            const resp = await fetcher(url, { signal: opts.signal });
+            if (resp.ok) {
+                const body = await resp.json();
+                if (body.found) {
+                    const slot = (body.devices ?? []).find(d => d.slotIndex === opts.slotIndex);
+                    const commitment = slot?.deviceCommitment ?? '0';
+                    if (commitment === opts.deviceCommitment) {
+                        status = {
+                            status: 'confirmed',
+                            slotIndex: opts.slotIndex,
+                            deviceCommitment: commitment,
+                            elapsedMs: Date.now() - startedAt,
+                        };
+                    }
+                    else {
+                        status = {
+                            status: 'pending',
+                            slotIndex: opts.slotIndex,
+                            deviceCommitment: commitment,
+                            elapsedMs: Date.now() - startedAt,
+                        };
+                    }
+                }
+            }
+        }
+        catch { /* transient network — try again on next tick */ }
+        opts.onTick?.(status);
+        if (status.status === 'confirmed')
+            return status;
+        if (Date.now() >= deadline)
+            return status;
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+//# sourceMappingURL=bindClient.js.map

package/build/bindClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindClient.js","sourceRoot":"","sources":["../src/bindClient.ts"],"names":[],"mappings":"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"}

package/build/buyClient.d.ts

@@ -1,15 +1,23 @@
+import type { PurchaseReceipt } from './receipt.js';
+import type { PrivateKey, PublicKey } from 'o1js';
 export type BuyIdentity = {
-    secretHash: string;
+    publicKey: PublicKey;
+    publicKeyBase58: string;
+    privateKey: PrivateKey;
     licenseHash: string;
 };
-export declare function deriveBuyIdentity(passphrase: string): BuyIdentity;
+export declare function deriveBuyIdentity(passphrase: string, zkAppAddress: string): Promise<BuyIdentity>;
 export type ProveBuyRequest = {
+    agentConsent?: unknown;
     keeperUrl: string;
     licenseHash: string;
     buyerAddress: string;
     zkAppAddress: string;
-    duration: 0 | 1 | 2;
+    ownerPubKey: string;
+    network: 'devnet' | 'mainnet';
+    duration: 0 | 1 | 2 | 3;
     buyerCountry: string;
+    buyerZip?: string;
     refundWaiverAccepted?: boolean;
     freezeAfterSlot?: number | null;
     fetcher?: typeof fetch;
@@ -25,6 +33,7 @@ export type ProveBuyResponse = {
     duration: number;
     durationLabel: string;
     generation: number;
+    appKey: string;
 };
 export type ConfirmBuyRequest = {
     keeperUrl: string;
@@ -35,15 +44,29 @@ export type ConfirmBuyRequest = {
     signal?: AbortSignal;
 };
 export type BuyStatus = {
-    status: 'unknown' | 'pending' | 'confirmed' | 'failed';
+    status: 'unknown' | 'pending' | 'landed' | 'timeout' | 'failed';
+    failureReason?: string;
     txHash?: string;
     landedAtBlockHeight?: number;
     landedAtSlot?: number;
     elapsedMs?: number;
 };
+/**
+ * The buyer's country guessed from their IP address (keeper `GET /geo/country`),
+ * to pre-fill the country field. Null when the keeper has no geolocation
+ * database, the address has no country, or the keeper is unreachable. The
+ * buyer's own choice is what `proveBuy` sends; the keeper separately records
+ * the country it sees as VAT evidence, and never the address.
+ */
+export declare function detectBuyerCountry(keeperUrl: string, fetcher?: typeof fetch): Promise<string | null>;
 export declare function proveBuy(req: ProveBuyRequest): Promise<ProveBuyResponse>;
+/**
+ * Returns the buyer's receipt (zklicensing/receipt) when the keeper issued
+ * one: put it in the license file as `receipt` (Vendor Terms §7.1).
+ */
 export declare function confirmBuy(req: ConfirmBuyRequest): Promise<{
     ok: true;
+    receipt?: PurchaseReceipt;
 }>;
 export type PollBuyStatusOptions = {
     keeperUrl: string;

package/build/buyClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyClient.d.ts","sourceRoot":"","sources":["../src/buyClient.ts"],"names":[],"mappings":"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"}

package/build/buyClient.js

@@ -1,31 +1,42 @@
 // Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
+// SPDX-License-Identifier: BUSL-1.1
 /**
  * buyClient.ts
  *
- * Browser-safe client for the buy flow. Exposes the three keeper roundtrips
+ * Browser-safe client for the buy flow. Exposes the three backend roundtrips
  * (derive identity → prove → confirm) as small, individually testable
  * functions plus a `pollBuyStatus` helper. Deliberately does NOT talk to a
  * wallet — the caller drives the wallet step between `proveBuy` and
  * `confirmBuy`, so the SDK stays wallet-agnostic and can be reused by CLI
  * tools, alternate UIs, and third-party integrators.
  *
- * Peer dep: o1js (for Poseidon + Encoding). Consumers of ./buy must have
- * o1js in their dependency graph.
+ * Peer dep: o1js (for Poseidon + Pallas PrivateKey/PublicKey/Signature).
+ * The ownership-signing surface (ownershipSignature.ts) uses Mina-native
+ * Schnorr so the passphrase-derived keypair also authorizes /prove/bind
+ * and /prove/unbind — verified IN-CIRCUIT there via Signature.verify(),
+ * which requires o1js. Every buy-flow consumer already ships o1js for the
+ * buy-witness path, so this is not new cost.
  */
-import { Encoding, Poseidon } from 'o1js';
 import { resolveFreezeState } from './freezeClient.js';
 import { REFUND_WINDOW_N, TOLERANCE_WINDOW_N } from './contractInterface.js';
-// Derive the two hashes the buy flow keys off. Deterministic in the
-// passphrase — same passphrase always maps to the same licenseHash on a
-// given zkApp, so a buyer's passphrase choice locks in their license
-// identity from day one. Only `licenseHash` is sent to the keeper (see
-// proveBuy); `secretHash` stays on the buyer's device and is used only by
-// the client-side LicenseOwnershipProgram challenge/response.
-export function deriveBuyIdentity(passphrase) {
-    const secretHash = Poseidon.hash(Encoding.stringToFields(passphrase));
-    const licenseHash = Poseidon.hash([secretHash]);
-    return { secretHash: secretHash.toString(), licenseHash: licenseHash.toString() };
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import { deriveOwnershipKeypair } from './ownershipSignature.js';
+import { licenseHashFromPubkey } from './ownershipLicenseHash.js';
+// Derive the ownership keypair + licenseHash the buy flow keys off.
+// Deterministic in (passphrase, zkAppAddress) — same inputs always map
+// to the same keypair (via HKDF-SHA256) and therefore the same
+// licenseHash on every device, so a buyer can re-derive their license
+// identity anywhere from the passphrase and the app address. Binding
+// the derivation to the app address means a leaked passphrase for app A
+// cannot be replayed as a valid activation for app B.
+//
+// HKDF still needs WebCrypto (Node ≥20, Chromium 137+, Safari 17+,
+// Firefox 130+); the scalar reduction and Pallas group operations are
+// pure JS through o1js. Async because subtle.deriveBits is async.
+export async function deriveBuyIdentity(passphrase, zkAppAddress) {
+    const { privateKey, publicKey, publicKeyBase58 } = await deriveOwnershipKeypair(passphrase, zkAppAddress);
+    const licenseHash = licenseHashFromPubkey(publicKey);
+    return { publicKey, publicKeyBase58, privateKey, licenseHash };
 }
 function baseUrl(url) {
     return url.replace(/\/+$/, '');
@@ -39,11 +50,11 @@ async function readJsonError(resp) {
     catch { /* body wasn't JSON */ }
     return `HTTP ${resp.status}`;
 }
-// POST /prove/buy — keeper compiles + proves the buy tx.
+// POST /prove/buy — backend compiles + proves the buy tx.
 // The buyer's wallet then signs the returned provenTxJson.
 //
 // Pre-network guards:
-//   - salesFrozen === true → refuse immediately (keeper would 423 anyway).
+//   - salesFrozen === true → refuse immediately (backend would 423 anyway).
 //   - freezeAfterSlot announced AND this buy's 14-day refund window would
 //     extend past the freeze slot AND refundWaiverAccepted !== true →
 //     refuse (buyer must explicitly accept that the scheduled hardfork
@@ -58,16 +69,36 @@ async function readJsonError(resp) {
 //     delivery) or forced by a freeze overlap.
 //   - refundWaiverAccepted !== true → POST /prove/buy (standard escrow path
 //     with a 14-day refund window).
+/**
+ * The buyer's country guessed from their IP address (keeper `GET /geo/country`),
+ * to pre-fill the country field. Null when the keeper has no geolocation
+ * database, the address has no country, or the keeper is unreachable. The
+ * buyer's own choice is what `proveBuy` sends; the keeper separately records
+ * the country it sees as VAT evidence, and never the address.
+ */
+export async function detectBuyerCountry(keeperUrl, fetcher = fetch) {
+    try {
+        const res = await fetcher(`${keeperUrl.replace(/\/$/, '')}/geo/country`, { cache: 'no-store' });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        return typeof body.country === 'string' && /^[A-Z]{2}$/.test(body.country) ? body.country : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function proveBuy(req) {
     const fetcher = req.fetcher ?? fetch;
     const freeze = await resolveFreezeState({
         keeperUrl: req.keeperUrl,
+        network: req.network,
         freezeAfterSlot: req.freezeAfterSlot,
         fetcher,
         signal: req.signal,
     });
     if (freeze.salesFrozen) {
-        throw new Error('Sales frozen — new buys refused ahead of scheduled hardfork migration');
+        throw new Error('Sales frozen — new buys refused ahead of a scheduled hardfork');
     }
     let windowOverlapsFreeze = false;
     if (freeze.freezeAfterSlot !== null) {
@@ -95,20 +126,28 @@ export async function proveBuy(req) {
             licenseHash: req.licenseHash,
             buyerAddress: req.buyerAddress,
             zkAppAddress: req.zkAppAddress,
+            ownerPubKey: req.ownerPubKey,
+            network: req.network,
             duration: req.duration,
             buyerCountry: req.buyerCountry,
+            ...(req.buyerZip ? { buyerZip: req.buyerZip } : {}),
             ...(req.refundWaiverAccepted === true ? { refundWaiverAccepted: true } : {}),
+            ...(req.refundWaiverAccepted === true && req.agentConsent ? { agentConsent: req.agentConsent } : {}),
         }),
     });
     if (!resp.ok) {
         // Distinct guidance for the no-escrow path: a 404 here means the
         // vendor's zkApp was deployed before the no-escrow method existed. Fix
-        // is a redeploy through the hardfork-migration flow (§12.13); until
+        // is a redeploy (§12.13); until
         // then the escrowless (waiver) path is unavailable on this vendor.
         if (useNoEscrow && resp.status === 404) {
-            throw new Error('Keeper does not offer /prove/buy-no-escrow — this vendor\'s zkApp does not support the escrowless (waiver) path; vendor must redeploy via the hardfork-migration flow');
+            throw new Error('Backend does not offer /prove/buy-no-escrow — this vendor\'s zkApp does not support the escrowless (waiver) path; vendor must redeploy');
         }
-        throw new Error(await readJsonError(resp));
+        const parsed = await readErrorBody(resp);
+        const queueBusy = tryQueueBusyFromBody(parsed);
+        if (queueBusy)
+            throw queueBusy;
+        throw keeperError(parsed);
     }
     return await resp.json();
 }
@@ -116,6 +155,10 @@ export async function proveBuy(req) {
 // into a persisted (pending: true) LicenseRecord. Call this only after the
 // wallet has actually returned a txHash — a cancelled or dropped signature
 // leaves the intent to expire on its own.
+/**
+ * Returns the buyer's receipt (zklicensing/receipt) when the keeper issued
+ * one: put it in the license file as `receipt` (Vendor Terms §7.1).
+ */
 export async function confirmBuy(req) {
     const fetcher = req.fetcher ?? fetch;
     const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/buy`, {
@@ -130,11 +173,14 @@ export async function confirmBuy(req) {
     });
     if (!resp.ok)
         throw new Error(await readJsonError(resp));
-    return { ok: true };
+    const body = await resp.json().catch(() => ({}));
+    return { ok: true, ...(body?.receipt ? { receipt: body.receipt } : {}) };
 }
-// Polls GET /buy/status until it returns a terminal state ('confirmed' or
-// 'failed') or the timeout fires. Terminal state is resolved via the
-// returned status; 'unknown' just means the keeper hasn't seen the tx yet.
+// Polls GET /buy/status until it returns a terminal state ('landed' — success,
+// tx included on-chain; 'failed' — included but failed on chain; or 'timeout'
+// — watch deadline passed without inclusion)
+// or the local poll timeout fires. 'unknown' just means the backend hasn't seen
+// a watch record yet (confirmBuy still landing, or retention window expired).
 export async function pollBuyStatus(opts) {
     const fetcher = opts.fetcher ?? fetch;
     const interval = opts.intervalMs ?? 3_000;
@@ -152,7 +198,7 @@ export async function pollBuyStatus(opts) {
         }
         catch { /* transient network — try again on next tick */ }
         opts.onTick?.(status);
-        if (status.status === 'confirmed' || status.status === 'failed')
+        if (status.status === 'landed' || status.status === 'timeout' || status.status === 'failed')
             return status;
         if (Date.now() >= deadline)
             return status;

package/build/buyClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyClient.js","sourceRoot":"","sources":["../src/buyClient.ts"],"names":[],"mappings":"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"}

package/build/chainHead.d.ts

@@ -0,0 +1,61 @@
+/** `state`: the account's whole app state (decimal strings). */
+export type ChainHead = {
+    root: string;
+    slot: number;
+    state: string[];
+};
+export declare function readChainHead(args: {
+    address: string;
+    network: 'devnet' | 'mainnet';
+    graphqlUrl?: string;
+    fetcher?: typeof fetch;
+}): Promise<ChainHead>;
+/** Permission names as a Mina node reports them: 'Proof', 'Signature', 'Either', 'None', 'Impossible'. */
+export type ZkappAccount = {
+    found: boolean;
+    zkappUri?: string;
+    vkHash?: string;
+    appState?: string[];
+    permissions?: {
+        editState?: string;
+        send?: string;
+        setZkappUri?: string;
+        setPermissions?: string;
+        setDelegate?: string;
+        setTiming?: string;
+        setVerificationKey?: {
+            auth?: string;
+            txnVersion?: number;
+        };
+    };
+};
+/** A Mina node that couldn't be reached or answered with an error; `status` 0 when there was no HTTP answer. */
+export declare class MinaNodeError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Reads a zkApp account (state, verification-key hash, URI, permissions)
+ * from a Mina node over GraphQL — the fields o1js's fetchAccount reads,
+ * without o1js and its global Mina instance. `found: false` when the node
+ * has no such account.
+ */
+export declare function readZkappAccount(args: {
+    address: string;
+    graphqlUrl: string;
+    fetcher?: typeof fetch;
+}): Promise<ZkappAccount>;
+/**
+ * The one GraphQL read behind readZkappAccount and readChainHead: the
+ * account and the chain's current slot (`undefined` when the node didn't
+ * report it) in one query. Throws MinaNodeError.
+ */
+export declare function readZkappHead(args: {
+    address: string;
+    graphqlUrl: string;
+    fetcher?: typeof fetch;
+}): Promise<{
+    account: ZkappAccount;
+    slot?: number;
+}>;
+//# sourceMappingURL=chainHead.d.ts.map

package/build/chainHead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainHead.d.ts","sourceRoot":"","sources":["../src/chainHead.ts"],"names":[],"mappings":"AAWA,gEAAgE;AAChE,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,GAAG,OAAO,CAAC,SAAS,CAAC,CAOrB;AAED,0GAA0G;AAC1G,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjF,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QACzC,kBAAkB,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7D,CAAC;CACH,CAAC;AAEF,gHAAgH;AAChH,qBAAa,aAAc,SAAQ,KAAK;IACT,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAxC,OAAO,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM;CACrD;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAEnI;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,YAAY,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA4C5J"}

package/build/chainHead.js

@@ -0,0 +1,88 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * chainHead.ts — reads a zkApp's first state field (its tree root) and the
+ * chain's current slot from a Mina node over GraphQL, in one query, without
+ * o1js and without touching o1js's global Mina instance.
+ */
+import { DEFAULT_MINA_GRAPHQL_URLS } from './onChainRoot.js';
+export async function readChainHead(args) {
+    const url = args.graphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[args.network];
+    const { account, slot } = await readZkappHead({ address: args.address, graphqlUrl: url, fetcher: args.fetcher });
+    const root = account.appState?.[0];
+    if (!root)
+        throw new Error(`${args.address} is not a zkApp on ${args.network}`);
+    if (slot === undefined)
+        throw new MinaNodeError(`Mina node ${url} did not report the current slot`, 0);
+    return { root, slot, state: account.appState };
+}
+/** A Mina node that couldn't be reached or answered with an error; `status` 0 when there was no HTTP answer. */
+export class MinaNodeError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Reads a zkApp account (state, verification-key hash, URI, permissions)
+ * from a Mina node over GraphQL — the fields o1js's fetchAccount reads,
+ * without o1js and its global Mina instance. `found: false` when the node
+ * has no such account.
+ */
+export async function readZkappAccount(args) {
+    return (await readZkappHead(args)).account;
+}
+/**
+ * The one GraphQL read behind readZkappAccount and readChainHead: the
+ * account and the chain's current slot (`undefined` when the node didn't
+ * report it) in one query. Throws MinaNodeError.
+ */
+export async function readZkappHead(args) {
+    const query = `query($pk: PublicKey!) {
+    account(publicKey: $pk) {
+      zkappUri
+      zkappState
+      verificationKey { hash }
+      permissions { editState send setZkappUri setPermissions setDelegate setTiming setVerificationKey { auth txnVersion } }
+    }
+    bestChain(maxLength: 1) { protocolState { consensusState { slotSinceGenesis } } }
+  }`;
+    let resp;
+    try {
+        resp = await (args.fetcher ?? fetch)(args.graphqlUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ query, variables: { pk: args.address } }),
+        });
+    }
+    catch (e) {
+        throw new MinaNodeError(`Mina node ${args.graphqlUrl}: ${e?.message ?? e}`, 0);
+    }
+    const body = await resp.json().catch(() => null);
+    if (!resp.ok || !body?.data) {
+        throw new MinaNodeError(`Mina node ${args.graphqlUrl}: ${body?.errors?.map(e => e.message).join('; ') || `HTTP ${resp.status}`}`, resp.status);
+    }
+    const rawSlot = body.data.bestChain?.[0]?.protocolState?.consensusState?.slotSinceGenesis;
+    const slot = rawSlot === undefined || rawSlot === null || !Number.isFinite(Number(rawSlot)) ? undefined : Number(rawSlot);
+    const a = body.data.account;
+    if (!a)
+        return { account: { found: false }, slot };
+    const p = a.permissions ?? {};
+    const txn = p.setVerificationKey?.txnVersion;
+    return {
+        slot,
+        account: {
+            found: true,
+            zkappUri: a.zkappUri ?? undefined,
+            vkHash: a.verificationKey?.hash != null ? String(a.verificationKey.hash) : undefined,
+            appState: Array.isArray(a.zkappState) ? a.zkappState.map(String) : undefined,
+            permissions: {
+                editState: p.editState, send: p.send, setZkappUri: p.setZkappUri, setPermissions: p.setPermissions,
+                setDelegate: p.setDelegate, setTiming: p.setTiming,
+                setVerificationKey: p.setVerificationKey ? { auth: p.setVerificationKey.auth, txnVersion: txn === undefined || txn === null ? undefined : Number(txn) } : undefined,
+            },
+        },
+    };
+}
+//# sourceMappingURL=chainHead.js.map

package/build/chainHead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainHead.js","sourceRoot":"","sources":["../src/chainHead.ts"],"names":[],"mappings":"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"}