@lionden/network 0.1.0

package/dist/connection.js

@@ -0,0 +1,1064 @@
+/**
+ * AleoConnection — concrete implementation of NetworkConnection.
+ *
+ * Delegates to the Provable SDK's AleoNetworkClient for queries and
+ * transaction broadcasting, and to ProgramManager for transaction building.
+ */
+import * as fs from "node:fs";
+import { normalizeRuntimeImportRef } from "@lionden/config";
+import { buildRuntimeKeyIdentity, findCachedExecutionKeys, resolveProgramExecutionArtifacts, } from "./execution-key-cache.js";
+import { captureSdkCall } from "./sdk-diagnostics.js";
+import { selectMatchingTransition } from "./transition-selector.js";
+import { LocalExecutionWasmTrapError, LocalVmExecutionError, NetworkConfirmationTimeoutError, TransitionRejectedError, } from "./types.js";
+/**
+ * Thrown when a 2xx response body fails to match the expected confirmed-tx
+ * shape (missing required fields, wrong types). Distinct from transient
+ * network errors — the polling loop must NOT retry on this class.
+ */
+export class TransactionShapeParseError extends Error {
+    kind = "TransactionShapeParseError";
+    txId;
+    field;
+    constructor(message, txId, field, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "TransactionShapeParseError";
+        this.txId = txId;
+        this.field = field;
+    }
+}
+const DEFAULT_CONFIRMATION_TIMEOUT_MS = 60_000;
+const CONFIRMATION_POLL_INTERVAL_MS = 1_000;
+const U32_MAX = 0xffffffff;
+function formatStorageVectorIndex(index) {
+    if (!Number.isSafeInteger(index) || index < 0 || index > U32_MAX) {
+        throw new Error(`Storage vector index must be a non-negative safe integer in range 0..${U32_MAX}.`);
+    }
+    return `${index}u32`;
+}
+function parseStorageVectorLength(value) {
+    const stripped = value.replace(/u32(?:\.(?:public|private))?$/i, "");
+    const length = Number(stripped);
+    if (!Number.isSafeInteger(length) || length < 0 || length > U32_MAX) {
+        throw new Error(`Invalid storage vector length: ${value}`);
+    }
+    return length;
+}
+/**
+ * Process-wide serialization for local-WASM trap capture.
+ *
+ * runWithLocalWasmTrapCapture installs process-global uncaughtException /
+ * unhandledRejection handlers. Those handler windows cannot safely overlap,
+ * even when the SDK operations use different connections or diagnostics sinks.
+ */
+let localWasmTrapCaptureLock = Promise.resolve();
+export class AleoConnection {
+    type;
+    name;
+    endpoint;
+    networkId;
+    privateKey;
+    apiKey;
+    egressPolicy;
+    artifactsDir;
+    keyCache;
+    logLevel;
+    projectRoot;
+    executionImports;
+    sdkObjects;
+    sdkObjectsPromise;
+    _closed = false;
+    /** Whether this connection has been permanently closed. */
+    get closed() {
+        return this._closed;
+    }
+    /** Throws if this connection has been closed. */
+    assertOpen() {
+        if (this._closed) {
+            throw new Error("Connection is closed.");
+        }
+    }
+    // Per-signer SDK object cache — isolated PM + RecordProvider + Account per key
+    signerSdkResolved = new Map();
+    signerSdkInflight = new Map();
+    constructor(options) {
+        this.type = options.type;
+        this.name = options.name;
+        this.endpoint = options.endpoint;
+        this.networkId = options.networkId;
+        this.privateKey = options.privateKey;
+        this.apiKey = options.apiKey;
+        this.egressPolicy = options.egressPolicy;
+        this.artifactsDir = options.artifactsDir;
+        this.keyCache = options.keyCache;
+        this.logLevel = options.logLevel;
+        this.projectRoot = options.projectRoot;
+        this.executionImports = options.executionImports ?? {};
+        // Devnode connections support block advancement
+        if (this.type === "devnode") {
+            this.advanceBlocks = async (count) => {
+                this.assertOpen();
+                for (let i = 0; i < count; i++) {
+                    const url = `${this.endpoint}/${this.networkId}/block/create`;
+                    const response = await fetch(url, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify({ num_blocks: 1 }),
+                    });
+                    if (!response.ok) {
+                        throw new Error(`Failed to advance block: ${response.status} ${response.statusText}`);
+                    }
+                }
+            };
+        }
+    }
+    /** Lazy-init and cache SDK objects for this connection. */
+    async getSdkObjects() {
+        this.assertOpen();
+        if (this.sdkObjects)
+            return this.sdkObjects;
+        if (!this.sdkObjectsPromise) {
+            this.sdkObjectsPromise = (async () => {
+                const { createSdkObjects } = await import("./sdk-adapter.js");
+                const objects = await createSdkObjects({
+                    network: this.networkId,
+                    endpoint: this.endpoint,
+                    privateKey: this.privateKey,
+                    apiKey: this.apiKey,
+                    keyCache: this.keyCache,
+                    logLevel: this.logLevel,
+                    egressPolicy: this.egressPolicy,
+                });
+                // Guard: if close() was called while we were initializing,
+                // destroy the account and bail out.
+                if (this._closed) {
+                    tryDestroyAccount(objects.account);
+                    throw new Error("Connection closed during SDK initialization.");
+                }
+                this.sdkObjects = objects;
+                return objects;
+            })();
+        }
+        return this.sdkObjectsPromise;
+    }
+    /**
+     * Get the effective ProgramManager for an execution.
+     * Returns the default PM when no signer override is given,
+     * or a per-signer isolated PM otherwise.
+     */
+    async getEffectivePm(signerPrivateKey) {
+        const defaultSdk = await this.getSdkObjects();
+        if (!signerPrivateKey || signerPrivateKey === this.privateKey) {
+            return {
+                pm: defaultSdk.programManager,
+                nc: defaultSdk.networkClient,
+                diagnostics: defaultSdk.diagnostics,
+            };
+        }
+        // Check resolved cache. State queries during a signer execution go through
+        // the signer PM's own transport, so attribute failures to the signer sink.
+        const resolved = this.signerSdkResolved.get(signerPrivateKey);
+        if (resolved) {
+            return {
+                pm: resolved.programManager,
+                nc: defaultSdk.networkClient,
+                diagnostics: resolved.diagnostics,
+            };
+        }
+        // Check inflight cache
+        let inflight = this.signerSdkInflight.get(signerPrivateKey);
+        if (!inflight) {
+            inflight = (async () => {
+                const { createSignerSdkObjects } = await import("./sdk-adapter.js");
+                const signerSdk = await createSignerSdkObjects({
+                    privateKey: signerPrivateKey,
+                    endpoint: this.endpoint,
+                    network: this.networkId,
+                    keyProvider: defaultSdk.keyProvider,
+                    apiKey: this.apiKey,
+                    logLevel: this.logLevel,
+                    egressPolicy: this.egressPolicy,
+                });
+                // If close() was called while creating, destroy and bail
+                if (this._closed) {
+                    tryDestroyAccount(signerSdk.account);
+                    throw new Error("Connection closed during signer SDK initialization.");
+                }
+                this.signerSdkResolved.set(signerPrivateKey, signerSdk);
+                this.signerSdkInflight.delete(signerPrivateKey);
+                return signerSdk;
+            })();
+            this.signerSdkInflight.set(signerPrivateKey, inflight);
+            // Evict from inflight on rejection so retries work
+            inflight.catch(() => {
+                this.signerSdkInflight.delete(signerPrivateKey);
+            });
+        }
+        const signerSdk = await inflight;
+        return {
+            pm: signerSdk.programManager,
+            nc: defaultSdk.networkClient,
+            diagnostics: signerSdk.diagnostics,
+        };
+    }
+    async getBalance(address) {
+        this.assertOpen();
+        const addr = address ?? (await this.getDefaultAddress());
+        const value = await this.getMappingValue("credits.aleo", "account", addr);
+        if (value === null)
+            return 0n;
+        // Value looks like "123456u64" — strip the suffix
+        return BigInt(value.replace(/u\d+$/i, ""));
+    }
+    /**
+     * Shared query body for mapping/storage reads. Resolves the SDK network
+     * client, calls `getProgramMappingValue`, coerces undefined/null to `null`,
+     * treats 404/"not found" as `null`, and otherwise rethrows wrapped in a
+     * `Failed to query ${failureLabel}` error. Callers supply the flavored
+     * `failureLabel` ("mapping …" vs "storage …") so error strings stay distinct.
+     */
+    async queryProgramMappingRaw(programId, mappingName, key, failureLabel) {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        try {
+            const value = await nc.getProgramMappingValue(programId, mappingName, key);
+            if (value === undefined || value === null)
+                return null;
+            return typeof value === "string" ? value : String(value);
+        }
+        catch (err) {
+            // SDK throws on 404 / missing key — treat as null
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes("404") ||
+                message.includes("not found") ||
+                message.includes("Not Found")) {
+                return null;
+            }
+            throw new Error(`Failed to query ${failureLabel}: ${message}`);
+        }
+    }
+    async getMappingValue(programId, mappingName, key) {
+        return this.queryProgramMappingRaw(programId, mappingName, key, `mapping ${programId}/${mappingName}`);
+    }
+    async getStorageValue(programId, variableName) {
+        return this.queryProgramMappingRaw(programId, `${variableName}__`, "false", `storage ${programId}/${variableName}`);
+    }
+    async getStorageVectorLength(programId, variableName) {
+        const value = await this.getMappingValue(programId, `${variableName}__len__`, "false");
+        return value === null ? 0 : parseStorageVectorLength(value);
+    }
+    async getStorageVectorValue(programId, variableName, index) {
+        return this.getMappingValue(programId, `${variableName}__`, formatStorageVectorIndex(index));
+    }
+    async execute(programId, transitionName, args, options) {
+        this.assertOpen();
+        if (this.type === "devnode") {
+            const { checkDevnodeSdkSupport, initConsensusHeights } = await import("./sdk-adapter.js");
+            // Enforce the SDK baseline for devnode operations.
+            await checkDevnodeSdkSupport();
+            await initConsensusHeights();
+        }
+        // Resolve the effective ProgramManager — uses a per-signer isolated PM
+        // when options.signer is provided, otherwise the connection's default.
+        // `diagnostics` is the transport-failure sink for whichever PM was chosen.
+        const { pm: effectivePm, nc: effectiveNc, diagnostics, } = await this.getEffectivePm(options?.signer?.privateKey);
+        const pm = effectivePm;
+        const nc = effectiveNc;
+        const mode = options?.mode ?? "onchain";
+        // Resolve runtime imports (config layer + per-call layer) once.
+        // Path refs are absolutized via @lionden/config helpers; missing files
+        // fail-fast here with a clear error before we touch the SDK.
+        const runtimeImports = this.collectRuntimeImports(programId, options?.imports);
+        // Resolve program source + transitive imports once for every mode.
+        // includeSidecar=true is safe everywhere; it's a cheap fs read and only
+        // consulted when the filesystem keycache path is exercised below.
+        const artifacts = await resolveProgramExecutionArtifacts({
+            artifactsDir: this.artifactsDir,
+            programId,
+            networkClient: nc,
+            includeSidecar: true,
+            runtimeImports,
+        });
+        if (mode === "local") {
+            // Local execution — run without generating proofs. captureSdkCall covers
+            // local *rejections* and opaque-shape classification; the sink is normally
+            // empty for local. runWithLocalWasmTrapCapture is nested INSIDE (closest
+            // to pm.run) so a Leo body panic that escapes the pm.run promise as a
+            // process-global `RuntimeError: unreachable` trap becomes a rejection
+            // rather than hanging forever. Order matters: captureSdkCall must stay the
+            // outer wrapper so its runExclusive mutex is released when the trap rejects
+            // — see sdk-diagnostics.ts for the matching LocalExecutionWasmTrapError
+            // pass-through that keeps the trap from being re-wrapped.
+            const result = await captureSdkCall(diagnostics, { operation: "local", programId, transitionName }, () => runWithLocalWasmTrapCapture(() => pm.run(artifacts.source, transitionName, args, false, // proveExecution = false
+            artifacts.imports)));
+            const outputs = extractLocalExecutionOutputs(result);
+            return {
+                outputs,
+            };
+        }
+        // On-chain execution
+        let txId;
+        const useDevnodeFastPath = this.type === "devnode" &&
+            !options?.prove &&
+            typeof pm.buildDevnodeExecutionTransaction === "function";
+        const importsSlice = artifacts.imports === undefined ? {} : { imports: artifacts.imports };
+        if (useDevnodeFastPath) {
+            // Devnode fast-path — skips proof generation. Only the build is wrapped;
+            // broadcast already surfaces a usable HTTP error on its own. The build runs
+            // the transition body locally to authorize the tx, so an arithmetic body
+            // panic traps the same way local pm.run does — runWithLocalWasmTrapCapture
+            // nested INSIDE captureSdkCall converts that trap into a rejection instead
+            // of a hang/crash (tmp/bug-hunts/onchain-trap probe).
+            const tx = await captureSdkCall(diagnostics, { operation: "execute", programId, transitionName }, () => runWithLocalWasmTrapCapture(() => pm.buildDevnodeExecutionTransaction({
+                programName: programId,
+                functionName: transitionName,
+                inputs: args,
+                priorityFee: options?.fee ?? 0,
+                privateFee: options?.privateFee ?? false,
+                program: artifacts.source,
+                ...importsSlice,
+            })));
+            txId = await this.broadcastTransaction(tx);
+        }
+        else {
+            const persistentExtras = await this.getPersistentExecutionOptions(nc, programId, transitionName, artifacts);
+            // Standard execution via ProgramManager. This is the prove path whose
+            // WASM state-query callbacks surface as opaque "JS callback Promise
+            // rejected:" errors — captureSdkCall enriches them from the sink. The
+            // local authorize phase runs the transition body before proof generation,
+            // so an arithmetic body panic traps before any state query —
+            // runWithLocalWasmTrapCapture (nested INSIDE captureSdkCall) converts that
+            // trap into a rejection instead of a hang/crash. A normal opaque rejection
+            // still passes through to captureSdkCall's enrichment unchanged.
+            txId = await captureSdkCall(diagnostics, { operation: "execute", programId, transitionName }, () => runWithLocalWasmTrapCapture(() => pm.execute({
+                programName: programId,
+                functionName: transitionName,
+                inputs: args,
+                priorityFee: options?.fee ?? 0,
+                privateFee: options?.privateFee ?? false,
+                program: artifacts.source,
+                ...importsSlice,
+                ...(persistentExtras ?? {}),
+            })));
+        }
+        if (options?.awaitConfirmation !== true) {
+            return { outputs: [], txId };
+        }
+        return this.getTransitionOutputs(txId, programId, transitionName);
+    }
+    async checkLocalExecution(programId, transitionName, args, options) {
+        this.assertOpen();
+        if (this.type === "devnode") {
+            const { checkDevnodeSdkSupport, initConsensusHeights } = await import("./sdk-adapter.js");
+            await checkDevnodeSdkSupport();
+            await initConsensusHeights();
+        }
+        const { pm: effectivePm, nc: effectiveNc } = await this.getEffectivePm(options?.signer?.privateKey);
+        const pm = effectivePm;
+        const nc = effectiveNc;
+        if (typeof pm.buildAuthorizationUnchecked !== "function") {
+            throw new Error("Local failure checks require SDK ProgramManager.buildAuthorizationUnchecked().");
+        }
+        const runtimeImports = this.collectRuntimeImports(programId, options?.imports);
+        const artifacts = await resolveProgramExecutionArtifacts({
+            artifactsDir: this.artifactsDir,
+            programId,
+            networkClient: nc,
+            includeSidecar: true,
+            runtimeImports,
+        });
+        try {
+            await runWithLocalWasmTrapCapture(() => pm.buildAuthorizationUnchecked({
+                programName: programId,
+                functionName: transitionName,
+                inputs: args,
+                programSource: artifacts.source,
+                ...(artifacts.imports === undefined ? {} : { programImports: artifacts.imports }),
+            }));
+        }
+        catch (error) {
+            if (error instanceof LocalExecutionWasmTrapError || isCatchableLocalVmError(error)) {
+                throw new LocalVmExecutionError(`Local VM execution failed for ${programId}/${transitionName}: ${errorMessage(error)}`, {
+                    programId,
+                    transitionName,
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Await confirmation of `txId` and return the parsed outputs for the
+     * matching `(programId, transitionName)` transition. Used internally by
+     * `execute()` when `awaitConfirmation: true`, and exposed as a public
+     * follow-up for callers that opted into fire-and-forget broadcast.
+     */
+    async getTransitionOutputs(txId, programId, transitionName, timeout) {
+        const confirmed = await this.waitForConfirmation(txId, timeout);
+        if (confirmed.status === "rejected") {
+            throw new TransitionRejectedError(`Transition ${programId}/${transitionName} was rejected on inclusion (txId ${txId}); rejected execute transactions are converted to fee-only and carry no transition outputs.`, {
+                txId: confirmed.txId,
+                programId,
+                transitionName,
+                blockHeight: confirmed.blockHeight,
+            });
+        }
+        const transition = selectMatchingTransition(programId, transitionName, confirmed.transitions, confirmed.txId);
+        const outputs = transition.rawOutputs.map(toOutputString);
+        return {
+            outputs,
+            rawOutputs: transition.rawOutputs,
+            txId: confirmed.txId,
+        };
+    }
+    /**
+     * Merge config-level and per-call runtime-import refs. Per-call entries
+     * are normalized against `this.projectRoot`; path refs that don't exist
+     * fail-fast here with a config-style error. Output is sorted and deduped
+     * by `(kind, value)` for cache identity stability.
+     */
+    collectRuntimeImports(programId, callRefs) {
+        const fromConfig = this.executionImports[programId] ?? [];
+        const fromCall = [];
+        for (const raw of callRefs ?? []) {
+            const ref = normalizeRuntimeImportRef(raw, this.projectRoot);
+            if (ref.kind === "path") {
+                if (!fs.existsSync(ref.absolutePath)) {
+                    throw new Error(`Runtime import path not found: ${ref.absolutePath} (from per-call options.imports ${JSON.stringify(raw)})`);
+                }
+            }
+            fromCall.push(ref);
+        }
+        return dedupAndSortRuntimeImports([...fromConfig, ...fromCall]);
+    }
+    async getPersistentExecutionOptions(nc, programId, transitionName, artifacts) {
+        if (this.keyCache?.storage !== "filesystem" || !this.keyCache.path) {
+            return undefined;
+        }
+        const edition = await getLatestProgramEditionIfAvailable(nc, programId);
+        const runtime = await import("./sdk-adapter.js");
+        const sdkMetadata = runtime.getSdkRuntimeMetadata(this.networkId);
+        const identity = buildRuntimeKeyIdentity({
+            network: this.networkId,
+            programId,
+            transition: transitionName,
+            edition,
+            sourceHash: artifacts.sourceHash,
+            importsHash: artifacts.importsHash,
+            wasmHash: sdkMetadata.wasmHash,
+        });
+        const cached = findCachedExecutionKeys({
+            cachePath: this.keyCache.path,
+            identity,
+            artifacts,
+        });
+        const keyBytes = cached;
+        if (!keyBytes) {
+            // Cache miss. Do not call the query-less WASM `synthesizeKeyPair` path:
+            // direct PROBE-2 evidence showed `pm.execute` lazy synthesis stays on the
+            // guarded CallbackQuery path, while eager synthesis cannot be transport
+            // guarded. Cache hits above still inject keys.
+            return edition === undefined ? undefined : { edition };
+        }
+        const keys = await runtime.createExecutionKeysFromBytes(this.networkId, {
+            provingKey: keyBytes.provingKeyBytes,
+            verifyingKey: keyBytes.verifyingKeyBytes,
+        });
+        return {
+            ...(edition === undefined ? {} : { edition }),
+            provingKey: keys.provingKey,
+            verifyingKey: keys.verifyingKey,
+        };
+    }
+    async waitForConfirmation(txId, timeout) {
+        this.assertOpen();
+        const effectiveTimeout = timeout ?? DEFAULT_CONFIRMATION_TIMEOUT_MS;
+        const deadline = Date.now() + effectiveTimeout;
+        const headers = {};
+        if (this.apiKey) {
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        }
+        const base = `${this.endpoint}/${this.networkId}`;
+        // Phase 1: poll /transaction/confirmed/<txId> until the tx is in a block.
+        // This response no longer carries block_height; the height is resolved in
+        // phases 2–3 via the two-step find/blockHash + block/<hash> lookup. Each
+        // phase delegates its per-poll verdict to a named classifier so the error
+        // policy is uniform and separately testable (see classify* below).
+        const confirmedBody = await pollPhase(`${base}/transaction/confirmed/${txId}`, headers, deadline, (response) => classifyConfirmedBody(response, txId), () => {
+            throw new NetworkConfirmationTimeoutError(`Transaction ${txId} not confirmed within ${effectiveTimeout}ms`, { txId, timeout: effectiveTimeout, stage: "confirmed" });
+        });
+        // In Aleo, rejected transactions are confirmed as fee-only.
+        // Accepted: transaction.type is "execute" or "deploy". Rejected: "fee".
+        const txData = confirmedBody["transaction"];
+        const txType = txData?.["type"] ?? confirmedBody["type"];
+        const status = txType === "fee" ? "rejected" : "accepted";
+        // Parse execute transitions. For fee-only rejected txs, the original
+        // execute transitions are not carried by the chain, so transitions: [].
+        // For accepted execute txs, missing/malformed transition data fails
+        // fast (TransactionShapeParseError) rather than silently returning [].
+        const transitions = parseConfirmedTransitions(txData, txId);
+        // Phase 2: resolve the containing block's hash.
+        //   GET /<network>/find/blockHash/<txId>  -> JSON-encoded block-hash string
+        const blockHash = await pollPhase(`${base}/find/blockHash/${txId}`, headers, deadline, (response) => classifyBlockHash(response), () => {
+            throw new NetworkConfirmationTimeoutError(`Transaction ${txId} confirmed but block-hash lookup did not resolve within ${effectiveTimeout}ms`, { txId, timeout: effectiveTimeout, stage: "blockHash" });
+        });
+        // Phase 3: resolve the block's height.
+        //   GET /<network>/block/<blockHash>  -> header.metadata.height (number)
+        const blockHeight = await pollPhase(`${base}/block/${blockHash}`, headers, deadline, (response) => classifyBlockHeight(response, txId, blockHash), () => {
+            throw new NetworkConfirmationTimeoutError(`Transaction ${txId} confirmed but block height could not be resolved within ${effectiveTimeout}ms`, { txId, timeout: effectiveTimeout, stage: "blockHeight" });
+        });
+        return { txId, blockHeight, status, transitions };
+    }
+    // Assigned dynamically for devnode connections only
+    advanceBlocks;
+    async getBlockHeight() {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        const height = await nc.getLatestHeight();
+        return height;
+    }
+    async getProgramSource(programId) {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        try {
+            const source = await nc.getProgram(programId);
+            if (source === undefined || source === null)
+                return null;
+            return typeof source === "string" ? source : String(source);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes("404") ||
+                message.includes("not found") ||
+                message.includes("Not Found") ||
+                message.includes("500") // devnode returns 500 for non-existent programs
+            ) {
+                return null;
+            }
+            throw new Error(`Failed to fetch program source for "${programId}": ${message}`);
+        }
+    }
+    async getProgramEdition(programId) {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        return (await getLatestProgramEditionIfAvailable(nc, programId)) ?? null;
+    }
+    async getProgramChecksum(programId) {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        if (typeof nc.getProgram !== "function")
+            return null;
+        try {
+            const source = await nc.getProgram(programId);
+            if (source === undefined || source === null)
+                return null;
+            const program = typeof source === "string" ? source : String(source);
+            const { computeProgramChecksum } = await import("./sdk-adapter.js");
+            return await computeProgramChecksum(this.networkId, program);
+        }
+        catch {
+            return null;
+        }
+    }
+    async close() {
+        this._closed = true;
+        // Destroy cached signer accounts
+        for (const signerSdk of this.signerSdkResolved.values()) {
+            tryDestroyAccount(signerSdk.account);
+        }
+        this.signerSdkResolved.clear();
+        this.signerSdkInflight.clear();
+        // Destroy default account if resolved
+        if (this.sdkObjects) {
+            tryDestroyAccount(this.sdkObjects.account);
+        }
+        else if (this.sdkObjectsPromise !== undefined) {
+            // Pending — await and destroy
+            try {
+                const sdk = await this.sdkObjectsPromise;
+                tryDestroyAccount(sdk.account);
+            }
+            catch {
+                // Init failed — nothing to destroy
+            }
+        }
+        this.sdkObjects = undefined;
+        this.sdkObjectsPromise = undefined;
+    }
+    /** Broadcast a serialized transaction via the SDK network client. */
+    async broadcastTransaction(transaction) {
+        this.assertOpen();
+        const sdk = await this.getSdkObjects();
+        const nc = sdk.networkClient;
+        const txId = await nc.submitTransaction(transaction);
+        return typeof txId === "string" ? txId.replace(/"/g, "") : String(txId);
+    }
+    async getDefaultAddress() {
+        if (this.privateKey) {
+            const sdk = await this.getSdkObjects();
+            const account = sdk.account;
+            return typeof account.address === "function"
+                ? account.address().to_string()
+                : String(account.address ?? account);
+        }
+        throw new Error("No address specified and no private key configured. " +
+            "Pass an address or configure a private key in network config.");
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// The Provable WASM runtime can report Leo runtime panics (integer
+// under/overflow, division by zero) as process-level `RuntimeError: unreachable`
+// traps while leaving the SDK promise pending. Wrap this around any local-WASM
+// SDK operation to convert that specific trap into the rejection callers expect:
+//   - local `pm.run` (mode:"local"),
+//   - local failure checks via `buildAuthorizationUnchecked`, and
+//   - the local authorize/build phase of on-chain execute
+//     (`buildDevnodeExecutionTransaction` fast-path and `pm.execute` prove path),
+//     where a transition-body arithmetic panic traps the same way before any
+//     broadcast — confirmed by the tmp/bug-hunts/onchain-trap probe.
+// (An explicit `assert` failure is a *catchable* `Stack …` rejection, not a
+// trap, so it settles the promise normally and never reaches this handler.)
+//
+// When LionDen owns the capture point it rethrows unrelated uncaught exceptions;
+// when another capture callback is already installed, it observes traps through
+// `uncaughtExceptionMonitor` because Node suppresses the `uncaughtException`
+// event. The capture point and rejection listener are process-global, so every
+// trap-captured SDK operation is intentionally serialized by the module-level
+// mutex above. An unrelated `RuntimeError: unreachable` during the same window
+// would still be attributed to this run, so keep each wrap scoped to a single
+// in-flight call.
+//
+// The trap only carries the generic `unreachable` message; the descriptive
+// snarkVM panic text (e.g. "Integer subtraction failed on: ...") is written to
+// stderr by the panic hook and is not available here, so the resulting
+// `LocalExecutionWasmTrapError` cannot surface the underlying failure reason.
+async function runWithLocalWasmTrapCapture(operation) {
+    if (typeof process === "undefined")
+        return operation();
+    const previous = localWasmTrapCaptureLock;
+    let release;
+    localWasmTrapCaptureLock = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await raceLocalOperationWithTrap(operation, (rejectTrap) => {
+            // The trap escapes the SDK promise through one of two process-global
+            // channels, depending on the call site (observed via the onchain-trap probe):
+            //   - `uncaughtException`  — local `pm.run` and the prove-path `pm.execute`
+            //     throw the trap out of band.
+            //   - `unhandledRejection` — the devnode fast-path
+            //     `buildDevnodeExecutionTransaction` rejects an internal promise that is
+            //     never awaited.
+            // Watch both so every confirmed site is covered; the first to fire wins
+            // (the trap promise's reject is idempotent).
+            const cleanups = [
+                installUncaughtExceptionTrapHandler(rejectTrap),
+                installUnhandledRejectionTrapHandler(rejectTrap),
+            ];
+            return () => {
+                for (const cleanup of cleanups)
+                    cleanup();
+            };
+        });
+    }
+    finally {
+        release();
+    }
+}
+// Convert the `RuntimeError: unreachable` trap that escapes as an
+// uncaughtException (local `pm.run`, prove-path `pm.execute`) into a rejection.
+// Uses the capture-callback API when available — and `uncaughtExceptionMonitor`
+// when another callback already owns the slot, since Node suppresses the
+// `uncaughtException` event once a capture callback is installed. Unrelated
+// exceptions are re-raised so Node's default crash behavior is preserved.
+function installUncaughtExceptionTrapHandler(rejectTrap) {
+    const hasCaptureCallbackSupport = typeof process.setUncaughtExceptionCaptureCallback === "function" &&
+        typeof process.hasUncaughtExceptionCaptureCallback === "function";
+    if (hasCaptureCallbackSupport) {
+        if (process.hasUncaughtExceptionCaptureCallback()) {
+            const handler = (error) => {
+                if (isLocalExecutionWasmTrap(error)) {
+                    rejectTrap(error);
+                }
+            };
+            process.on("uncaughtExceptionMonitor", handler);
+            return () => {
+                process.removeListener("uncaughtExceptionMonitor", handler);
+            };
+        }
+        process.setUncaughtExceptionCaptureCallback((error) => {
+            if (isLocalExecutionWasmTrap(error)) {
+                rejectTrap(error);
+                return;
+            }
+            process.setUncaughtExceptionCaptureCallback(null);
+            setImmediate(() => {
+                throw error;
+            });
+        });
+        return () => {
+            if (process.hasUncaughtExceptionCaptureCallback()) {
+                process.setUncaughtExceptionCaptureCallback(null);
+            }
+        };
+    }
+    const handler = (error) => {
+        if (isLocalExecutionWasmTrap(error)) {
+            rejectTrap(error);
+            return;
+        }
+        // Unrelated exception: detach before re-raising. A listener-based handler
+        // suppresses Node's default crash, so rethrowing while still attached would
+        // loop straight back into this handler. Detaching first lets the rethrow
+        // reach Node's default (crash) behavior.
+        process.removeListener("uncaughtException", handler);
+        setImmediate(() => {
+            throw error;
+        });
+    };
+    process.on("uncaughtException", handler);
+    return () => {
+        process.removeListener("uncaughtException", handler);
+    };
+}
+// Convert the same trap when it escapes as an unhandledRejection — the devnode
+// `buildDevnodeExecutionTransaction` fast-path rejects an internal promise that
+// LionDen never awaits, so the trap surfaces here rather than as an
+// uncaughtException (confirmed by the onchain-trap probe: trapVia=unhandledRejection).
+//
+// Only the specific trap is intercepted; unrelated rejections are left for other
+// listeners and Node's default. Merely having a listener suppresses Node's
+// built-in default for the brief, serial capture window, but every other
+// `unhandledRejection` listener still fires (EventEmitter semantics), so this is
+// only observable if LionDen is the sole listener — an accepted process-global
+// caveat that mirrors the uncaughtException path.
+function installUnhandledRejectionTrapHandler(rejectTrap) {
+    const handler = (reason) => {
+        if (isLocalExecutionWasmTrap(reason)) {
+            rejectTrap(reason);
+        }
+    };
+    process.on("unhandledRejection", handler);
+    return () => {
+        process.removeListener("unhandledRejection", handler);
+    };
+}
+function raceLocalOperationWithTrap(operation, installTrapHandler) {
+    let cleanupTrapHandler = () => { };
+    const trap = new Promise((_, reject) => {
+        cleanupTrapHandler = installTrapHandler((error) => {
+            reject(new LocalExecutionWasmTrapError(error));
+        });
+    });
+    let operationPromise;
+    try {
+        operationPromise = operation();
+    }
+    catch (error) {
+        cleanupTrapHandler();
+        return Promise.reject(error);
+    }
+    return Promise.race([operationPromise, trap]).finally(cleanupTrapHandler);
+}
+function isLocalExecutionWasmTrap(error) {
+    if (error instanceof WebAssembly.RuntimeError && error.message === "unreachable") {
+        return true;
+    }
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return candidate.name === "RuntimeError" && candidate.message === "unreachable";
+}
+function dedupAndSortRuntimeImports(refs) {
+    const seen = new Set();
+    const out = [];
+    for (const ref of refs) {
+        const key = ref.kind === "programId" ? `id:${ref.programId}` : `path:${ref.absolutePath}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(ref);
+    }
+    out.sort((a, b) => {
+        const aKey = a.kind === "programId" ? a.programId : a.absolutePath;
+        const bKey = b.kind === "programId" ? b.programId : b.absolutePath;
+        if (aKey === bKey)
+            return 0;
+        return aKey < bKey ? -1 : 1;
+    });
+    return out;
+}
+async function getLatestProgramEditionIfAvailable(nc, programId) {
+    if (typeof nc.getLatestProgramEdition !== "function")
+        return undefined;
+    try {
+        const edition = await nc.getLatestProgramEdition(programId);
+        return Number.isInteger(edition) && edition >= 0 ? edition : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Flatten a `RawTransitionOutput` to a string for the `outputs: string[]`
+ * field of `TransitionCallResult`. Plain string entries pass through;
+ * id-only dynamic-record outputs surface their `id`. The faithful shape is
+ * preserved separately in `TransitionCallResult.rawOutputs`.
+ */
+function toOutputString(output) {
+    return typeof output === "string" ? output : output.id;
+}
+/** Best-effort destroy of an SDK Account to release WASM private-key state. */
+function tryDestroyAccount(account) {
+    if (account && typeof account.destroy === "function") {
+        try {
+            account.destroy();
+        }
+        catch {
+            // Non-fatal — some SDK versions may not support destroy
+        }
+    }
+}
+/**
+ * Run a bounded poll loop for one confirmation phase. `fetch` transport errors
+ * are surfaced to `classify` as a `null` response (which classifiers treat as
+ * `retryable`). A `fatalShape` verdict throws its error immediately; exhausting
+ * the deadline calls `onTimeout()`, which throws the staged
+ * `NetworkConfirmationTimeoutError`.
+ */
+async function pollPhase(url, headers, deadline, classify, onTimeout) {
+    while (Date.now() < deadline) {
+        let response = null;
+        try {
+            response = await fetch(url, { headers });
+        }
+        catch {
+            response = null; // transient transport error — classify as retryable
+        }
+        const outcome = await classify(response);
+        if (outcome.kind === "confirmed")
+            return outcome.value;
+        if (outcome.kind === "fatalShape")
+            throw outcome.error;
+        await sleep(CONFIRMATION_POLL_INTERVAL_MS);
+    }
+    onTimeout();
+}
+/**
+ * Phase 1 classifier — /transaction/confirmed/<txId>.
+ * non-ok → retryable; 2xx + valid JSON → confirmed; 2xx + unparseable JSON →
+ * fatalShape. A malformed JSON body after a 200 OK is a protocol-level shape
+ * mismatch, not a transient retry. (A 2xx with parseable JSON but wrong shape
+ * is caught downstream by parseConfirmedTransitions and also surfaces fast.)
+ */
+async function classifyConfirmedBody(response, txId) {
+    if (!response?.ok)
+        return { kind: "retryable" };
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        return {
+            kind: "fatalShape",
+            error: new TransactionShapeParseError(`Transaction ${txId} confirmed body is not valid JSON`, txId, "body", cause),
+        };
+    }
+    // Valid JSON that isn't an object (e.g. `null`, a number) is a deterministic
+    // 2xx shape failure — fail fast rather than confirming a value that makes the
+    // orchestrator throw a raw TypeError on property access downstream.
+    if (parsed === null || typeof parsed !== "object") {
+        return {
+            kind: "fatalShape",
+            error: new TransactionShapeParseError(`Transaction ${txId} confirmed body is not a JSON object`, txId, "body"),
+        };
+    }
+    return { kind: "confirmed", value: parsed };
+}
+/**
+ * Phase 2 classifier — /find/blockHash/<txId>.
+ * non-ok → retryable; 2xx → unquote the JSON-string body → confirmed. A
+ * read/parse failure on a 2xx body is treated as transient (retryable),
+ * preserving the prior bare-catch behavior — but now as an explicit verdict.
+ */
+async function classifyBlockHash(response) {
+    if (!response?.ok)
+        return { kind: "retryable" };
+    try {
+        const raw = (await response.text()).trim();
+        // Body is a JSON-encoded string: `"ab1...."`
+        const blockHash = raw.startsWith('"') && raw.endsWith('"') ? JSON.parse(raw) : raw;
+        return { kind: "confirmed", value: blockHash };
+    }
+    catch {
+        return { kind: "retryable" };
+    }
+}
+/**
+ * Phase 3 classifier — /block/<blockHash>.
+ * non-ok → retryable; 2xx + numeric header.metadata.height → confirmed;
+ * 2xx + unparseable JSON OR missing/non-numeric height → fatalShape. Both are
+ * hard parser disagreements that won't change on retry, so fail fast rather
+ * than burning the deadline.
+ */
+async function classifyBlockHeight(response, txId, blockHash) {
+    if (!response?.ok)
+        return { kind: "retryable" };
+    let parsed;
+    try {
+        parsed = await response.json();
+    }
+    catch (cause) {
+        return {
+            kind: "fatalShape",
+            error: new TransactionShapeParseError(`Transaction ${txId} confirmed at block ${blockHash} but the block body is not valid JSON`, txId, "body", cause),
+        };
+    }
+    // Valid JSON that isn't an object (e.g. `null`) is a deterministic shape
+    // failure — guard before indexing so it surfaces as a typed shape error
+    // rather than a raw TypeError on `block["header"]`.
+    if (parsed === null || typeof parsed !== "object") {
+        return {
+            kind: "fatalShape",
+            error: new TransactionShapeParseError(`Transaction ${txId} confirmed at block ${blockHash} but the block body is not a JSON object`, txId, "body"),
+        };
+    }
+    const block = parsed;
+    const header = block["header"];
+    const metadata = header?.["metadata"];
+    const h = metadata?.["height"];
+    if (typeof h === "number") {
+        return { kind: "confirmed", value: h };
+    }
+    return {
+        kind: "fatalShape",
+        error: new TransactionShapeParseError(`Transaction ${txId} confirmed at block ${blockHash} but header.metadata.height is missing or non-numeric`, txId, "header.metadata.height"),
+    };
+}
+/**
+ * Parse confirmed-transaction body into typed ConfirmedTransitionRecord[].
+ *
+ * Shape (accepted execute):
+ *   transaction.execution.transitions[] with each entry having:
+ *     program: "name.aleo", function: "func", outputs: [{type, id, value, ...}]
+ *
+ * Shape (rejected → fee-only / deploy):
+ *   no `execution` field. Returns [].
+ *
+ * Throws TransactionShapeParseError on:
+ *   - transaction.type === "execute" with missing/malformed execution or transitions
+ *     (would silently lose typed outputs otherwise)
+ *   - any malformed transition entry (missing program/function, non-array
+ *     outputs, output.value present but not a string)
+ */
+function parseConfirmedTransitions(txData, txId) {
+    // Strictness signal: the transaction object itself self-identifies as
+    // "execute". If there is no transaction object, stay tolerant — there's
+    // nothing to validate against.
+    if (!txData)
+        return [];
+    const isExecute = txData["type"] === "execute";
+    const execution = txData["execution"];
+    if (!execution) {
+        if (isExecute) {
+            throw new TransactionShapeParseError(`Transaction ${txId}: type is "execute" but transaction.execution is missing.`, txId, "transaction.execution");
+        }
+        return [];
+    }
+    const rawTransitions = execution["transitions"];
+    if (rawTransitions === undefined || rawTransitions === null) {
+        if (isExecute) {
+            throw new TransactionShapeParseError(`Transaction ${txId}: type is "execute" but transaction.execution.transitions is missing.`, txId, "transaction.execution.transitions");
+        }
+        return [];
+    }
+    if (!Array.isArray(rawTransitions)) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: transaction.execution.transitions is not an array (got ${typeof rawTransitions}).`, txId, "transaction.execution.transitions");
+    }
+    return rawTransitions.map((entry, index) => parseTransition(entry, txId, index));
+}
+function parseTransition(entry, txId, index) {
+    const path = `transaction.execution.transitions[${index}]`;
+    if (typeof entry !== "object" || entry === null) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: ${path} is not an object.`, txId, path);
+    }
+    const obj = entry;
+    const programId = obj["program"];
+    if (typeof programId !== "string" || programId.length === 0) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.program is missing or not a string.`, txId, `${path}.program`);
+    }
+    const transitionName = obj["function"];
+    if (typeof transitionName !== "string" || transitionName.length === 0) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.function is missing or not a string.`, txId, `${path}.function`);
+    }
+    const transitionPublicKey = obj["tpk"];
+    if (typeof transitionPublicKey !== "string" || transitionPublicKey.length === 0) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.tpk is missing or not a string. The transition public key is required to decrypt private inputs/outputs.`, txId, `${path}.tpk`);
+    }
+    const rawOutputs = obj["outputs"];
+    if (rawOutputs === undefined || rawOutputs === null) {
+        // Transition with no outputs is valid (some transitions return nothing).
+        return { programId, transitionName, rawOutputs: [], transitionPublicKey };
+    }
+    if (!Array.isArray(rawOutputs)) {
+        throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.outputs is not an array.`, txId, `${path}.outputs`);
+    }
+    const outputValues = rawOutputs.map((output, outputIndex) => {
+        if (typeof output !== "object" || output === null) {
+            throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.outputs[${outputIndex}] is not an object.`, txId, `${path}.outputs[${outputIndex}]`);
+        }
+        const outputObject = output;
+        if (!Object.hasOwn(outputObject, "value")) {
+            const id = outputObject["id"];
+            if (typeof id !== "string" || id.length === 0) {
+                throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.outputs[${outputIndex}] has no value and no string id.`, txId, `${path}.outputs[${outputIndex}].id`);
+            }
+            const type = outputObject["type"];
+            return {
+                kind: "idOnly",
+                id,
+                type: typeof type === "string" && type.length > 0 ? type : "unknown",
+            };
+        }
+        const value = outputObject["value"];
+        if (typeof value !== "string") {
+            throw new TransactionShapeParseError(`Transaction ${txId}: ${path}.outputs[${outputIndex}].value is not a string.`, txId, `${path}.outputs[${outputIndex}].value`);
+        }
+        return value;
+    });
+    return { programId, transitionName, rawOutputs: outputValues, transitionPublicKey };
+}
+function extractLocalExecutionOutputs(result) {
+    if (Array.isArray(result)) {
+        return result.map(String);
+    }
+    if (result && typeof result === "object") {
+        const executionResponse = result;
+        if (typeof executionResponse.getOutputs === "function") {
+            const outputs = executionResponse.getOutputs();
+            return Array.isArray(outputs) ? outputs.map(String) : [];
+        }
+        if (Array.isArray(executionResponse.outputs)) {
+            return executionResponse.outputs.map(String);
+        }
+    }
+    return [];
+}
+function isCatchableLocalVmError(error) {
+    const message = errorMessage(error);
+    return (message.startsWith("Stack authorization failed:") ||
+        message.startsWith("Stack evaluation failed:"));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=connection.js.map