@invisi-labs/sdk 1.1.3 → 1.1.4

package/dist/{chunk-FSQYZO66.js → chunk-BE52B32Z.js}

@@ -2,6 +2,53 @@ import {
   EthersChainReader
 } from "./chunk-4HMM7ZKY.js";
 
+// src/errors.ts
+import { MissingCapabilityError } from "@invisi-labs/core";
+var InvisiError = class extends Error {
+  code;
+  operation;
+  address;
+  outputIndex;
+  field;
+  capability;
+  constructor(code, message, details = {}) {
+    super(message, { cause: details.cause });
+    this.name = "InvisiError";
+    this.code = code;
+    this.operation = details.operation;
+    this.address = details.address;
+    this.outputIndex = details.outputIndex;
+    this.field = details.field;
+    this.capability = details.capability;
+  }
+};
+async function prepareWithErrors(operation, prepare) {
+  try {
+    return await prepare();
+  } catch (cause) {
+    if (cause instanceof InvisiError) {
+      if (cause.operation) throw cause;
+      throw new InvisiError(cause.code, cause.message, {
+        operation,
+        ...cause.address === void 0 ? {} : { address: cause.address },
+        ...cause.outputIndex === void 0 ? {} : { outputIndex: cause.outputIndex },
+        ...cause.field === void 0 ? {} : { field: cause.field },
+        ...cause.capability === void 0 ? {} : { capability: cause.capability },
+        cause: cause.cause
+      });
+    }
+    throw new InvisiError(
+      cause instanceof MissingCapabilityError ? "MISSING_CAPABILITY" : "PREPARATION_FAILED",
+      cause instanceof Error ? cause.message : "Transaction preparation failed",
+      {
+        operation,
+        cause,
+        ...cause instanceof MissingCapabilityError ? { capability: cause.capability } : {}
+      }
+    );
+  }
+}
+
 // src/session/state.ts
 function creditReservationKey(commitment) {
   return "credit:" + commitment;
@@ -78,11 +125,8 @@ import {
   transactUserPublicInputs
 } from "@invisi-labs/protocol";
 function requiresAuthorization(plan) {
-  if (plan.kind === "sweep") {
-    if (plan.credit || !plan.inputs.length || plan.outputs.length || !plan.params || plan.params.outputCommitments.length || (plan.funding.amount ?? 0n) !== 0n || BigInt(plan.params.withdrawalAddress) !== BigInt(plan.scope.walletIdentity) || plan.params.withdrawalAmount !== plan.inputs.reduce((sum, input) => sum + input.note.amount, 0n) || plan.inputs.some((input) => input.note.walletIdentity !== plan.scope.walletIdentity))
-      throw new Error("invalid owner-only sweep plan");
-    return false;
-  }
+  const ownerOnlyFullWithdrawal = !plan.credit && plan.inputs.length > 0 && plan.outputs.length === 0 && plan.params !== void 0 && plan.params.outputCommitments.length === 0 && (plan.funding.amount ?? 0n) === 0n && plan.fundingMode === "none" && BigInt(plan.params.withdrawalAddress) === BigInt(plan.scope.walletIdentity) && plan.params.withdrawalAmount === plan.inputs.reduce((sum, input) => sum + input.note.amount, 0n) && plan.inputs.every((input) => input.note.walletIdentity === plan.scope.walletIdentity);
+  if (ownerOnlyFullWithdrawal) return false;
   return !!plan.credit || plan.inputs.length > 0;
 }
 function inputFacts(plan) {
@@ -1909,12 +1953,13 @@ function readProtocolLogs(receipt, protocolAddress) {
 }
 
 // src/session/discovery.ts
+import { MAX_CIPHERTEXT_BYTES } from "@invisi-labs/core";
 import { isAddress } from "ethers";
 import {
   decodeAddress,
   ReceivingAddress
 } from "@invisi-labs/core";
-import { normalizeDelivery } from "@invisi-labs/protocol";
+import { normalizeOpaqueDelivery } from "@invisi-labs/protocol";
 var EVENTS = /* @__PURE__ */ new Set([
   "CommitmentsInserted",
   "BatchOutputs",
@@ -2007,7 +2052,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
     check(inserted, "delivery has no matching canonical insertion");
     if (commitment !== void 0)
       check(hash(commitment) === inserted, "delivery commitment conflicts with insertion");
-    const delivery = normalizeDelivery(wire, { credit: role !== "funds" });
+    const delivery = normalizeOpaqueDelivery(wire);
     check(
       typeof token === "string" && isAddress(token) && BigInt(token) !== 0n,
       "invalid event token"
@@ -2038,7 +2083,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
     add(log, tree, index(leaves[0]), fields.creditCommitment, "owner", ds[0]);
     add(log, tree, index(leaves[0]), fields.creditCommitment, "spender", ds[1]);
     if (hasChange) add(log, tree, index(leaves[1]), change, "funds", ds[2]);
-    else normalizeDelivery(ds[2], { empty: true });
+    else normalizeOpaqueDelivery(ds[2], { empty: true });
   };
   for (const log of relevant) {
     const a = object(log.args);
@@ -2068,7 +2113,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
         const length = Number.parseInt(packed.slice(offset, offset + 4), 16);
         offset += 4;
         check(
-          length >= 160 && length <= 416 && offset + length * 2 + 136 <= packed.length,
+          length >= 1 && length <= MAX_CIPHERTEXT_BYTES && offset + length * 2 + 136 <= packed.length,
           "invalid packed delivery length"
         );
         const ciphertext = `0x${packed.slice(offset, offset + length * 2)}`;
@@ -2090,8 +2135,8 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
       cs.forEach((c, i) => {
         if (BigInt(hash(c)) === 0n) {
           check(integer(leaves[i]) === 0n, "absent remainder has nonzero position");
-          normalizeDelivery(ds[2 * i], { empty: true });
-          normalizeDelivery(ds[2 * i + 1], { empty: true });
+          normalizeOpaqueDelivery(ds[2 * i], { empty: true });
+          normalizeOpaqueDelivery(ds[2 * i + 1], { empty: true });
         } else {
           add(log, tree, index(leaves[i]), c, "owner", ds[2 * i]);
           add(log, tree, index(leaves[i]), c, "spender", ds[2 * i + 1]);
@@ -2285,7 +2330,7 @@ function scopeKey(scope) {
   return bytesToHex(
     sha256(
       utf8ToBytes(
-        "Invisi.WalletScope.v2:" + JSON.stringify([
+        "Invisi.WalletScope.v1:" + JSON.stringify([
           scope.namespace,
           scope.chainId.toString(),
           scope.protocolAddress.toLowerCase(),
@@ -2400,10 +2445,15 @@ var MemoryAtomicRecords = class {
 };
 
 // src/session/operation-execution.ts
-import { verifyTypedData } from "ethers";
+import { Signature, SigningKey, getBytes as getBytes2, concat, verifyTypedData } from "ethers";
 import {
-  computeWalletAuthorizationDigest
+  computeWalletAuthorizationDigest,
+  AuthorizedStatement,
+  computeWalletIdentity,
+  createSigningRequest,
+  walletAuthorizationTypedData
 } from "@invisi-labs/core";
+import { WitnessBuilder as WitnessBuilder2 } from "@invisi-labs/protocol";
 
 // src/session/proof-integrity.ts
 import { getBytes } from "ethers";
@@ -2439,16 +2489,34 @@ async function authorizeOperation(plan, provider) {
   return signed;
 }
 async function proveOperation(protocol, plan, authorization, prover, options) {
+  if (Object.hasOwn(options, "target")) {
+    throw new Error("prove accepts execution, not a backend target");
+  }
+  const { execution = "single", ...proverOptions } = options;
+  if (execution !== "single" && execution !== "aggregate") {
+    throw new Error("execution must be single or aggregate");
+  }
+  const frozen = statement(plan);
+  if (execution === "aggregate" && (plan.kind !== "transfer" || plan.capacity !== 14)) {
+    throw new Error("aggregate execution requires a 14-slot transfer");
+  }
+  if (plan.kind === "transfer") {
+    plan.statement = WitnessBuilder2.statement(
+      frozen.circuitName,
+      frozen.expectedPublicInputs,
+      execution === "aggregate" ? "noir-recursive" : "evm"
+    );
+  }
   const request = await witnessFor(protocol, plan, authorization);
   if (JSON.stringify({ ...request, witness: void 0 }) !== JSON.stringify(plan.statement))
     throw new Error("prepared proof statement changed");
   try {
-    const proof = publicProof(await prover.prove(request, options));
+    const proof = publicProof(await prover.prove(request, proverOptions));
     sameStatement(proof, plan.statement);
     if (await prover.verify(
       structuredClone(proof),
       structuredClone(plan.statement),
-      options
+      proverOptions
     ) !== true)
       throw new Error("proof verification failed");
     return proof;
@@ -2463,19 +2531,88 @@ async function signOperationFunding(saved, signer, verifier) {
     throw new Error("funding signer is not the payer");
   const typed = await fundingTypedData(saved);
   const signature = await signer.signTypedData(structuredClone(typed));
+  return verifyFundingSignature(typed, payer, signature, verifier);
+}
+function walletSigningRequest(plan) {
+  return createSigningRequest(walletAuthorizationTypedData(authorizationRequest(plan)));
+}
+async function acceptWalletSignature(plan, signature) {
+  const request = authorizationRequest(plan);
+  const digest = computeWalletAuthorizationDigest(request);
+  try {
+    const signed = Signature.from(signature);
+    const publicKey = getBytes2(SigningKey.recoverPublicKey(digest, signed));
+    const owner = await computeWalletIdentity(publicKey);
+    if (owner.toLowerCase() !== plan.scope.walletIdentity.toLowerCase()) {
+      throw new Error("wallet signature identity mismatch");
+    }
+    return new AuthorizedStatement(plan.scope.walletIdentity, digest, {
+      public_key_x: Array.from(publicKey.slice(1, 33)),
+      public_key_y: Array.from(publicKey.slice(33)),
+      signature: Array.from(getBytes2(concat([signed.r, signed.s])))
+    });
+  } catch {
+    throw new Error("invalid wallet authorization signature");
+  }
+}
+async function fundingSigningRequest(saved, runtime) {
+  const plan = saved.plan;
+  if (plan.fundingMode !== "signature") {
+    throw new Error("operation does not require a funding signature");
+  }
+  if (plan.kind !== "shield" && !saved.proof) {
+    throw new Error("proof must precede funding authorization");
+  }
+  await runtime.options.protocol.validateDeployment(runtime.reader);
+  const block = await runtime.reader.getBlock(await runtime.reader.getLatestBlockNumber());
+  if (block.timestamp > plan.deadline || block.timestamp > (plan.funding.deadline ?? 0n)) {
+    throw new Error("funding authorization expired");
+  }
+  if (await runtime.reader.getFundingNonce(plan.context, plan.funding.payer, block) !== plan.funding.sigNonce) {
+    throw new Error("funding nonce changed; prepare again");
+  }
+  const request = createSigningRequest(await fundingTypedData(saved));
+  if ((await runtime.reader.getBlock(block.number)).hash !== block.hash) {
+    throw new Error("canonical funding block changed");
+  }
+  return request;
+}
+async function acceptFundingSignature(saved, signature, runtime) {
+  if (!/^0x(?:[a-fA-F0-9]{2})+$/.test(signature)) {
+    throw new Error("invalid EVM funding signature");
+  }
+  const request = await fundingSigningRequest(saved, runtime);
+  return verifyFundingSignature(
+    request,
+    saved.plan.funding.payer,
+    signature,
+    runtime.options.fundingVerifier
+  );
+}
+async function verifyFundingSignature(request, payer, signature, verifier) {
+  if (!/^0x(?:[a-fA-F0-9]{2})+$/.test(signature)) {
+    throw new Error("invalid EVM funding signature");
+  }
+  const types = Object.fromEntries(
+    Object.entries(request.types).map(([name, fields]) => [name, [...fields]])
+  );
+  let validEOA = false;
+  try {
+    validEOA = verifyTypedData(request.domain, types, request.message, signature).toLowerCase() === payer.toLowerCase();
+    if (validEOA) {
+      signature = Signature.from(signature).serialized;
+    }
+  } catch {
+    validEOA = false;
+  }
   const valid = verifier ? await verifier.verifyTypedData({
-    ...structuredClone(typed),
+    ...structuredClone(request),
     address: payer,
     signature
-  }) : verifyTypedData(
-    typed.domain,
-    Object.fromEntries(
-      Object.entries(typed.types).map(([name, fields]) => [name, [...fields]])
-    ),
-    typed.message,
-    signature
-  ).toLowerCase() === payer.toLowerCase();
-  if (valid !== true) throw new Error("invalid EVM funding signature");
+  }) : validEOA;
+  if (valid !== true) {
+    throw new Error("invalid EVM funding signature");
+  }
   return signature;
 }
 
@@ -2516,7 +2653,7 @@ function operationPreview(plan, status) {
 }
 
 // src/session/Operation.ts
-import { MissingCapabilityError } from "@invisi-labs/core";
+import { MissingCapabilityError as MissingCapabilityError2 } from "@invisi-labs/core";
 import { normalizeFunding } from "@invisi-labs/protocol";
 
 // src/session/operation-confirmation.ts
@@ -3203,6 +3340,81 @@ var Operation = class _Operation {
       throw error;
     }
   }
+  async signingCurrent() {
+    await this.#runtime.store.transaction(this.#runtime.scope, (state) => {
+      check5(!state.invalidated, "wallet state requires canonical resync");
+      this.current(state.operations[this.id]);
+    });
+  }
+  /** Public EIP-712 request; signing transport and key custody belong to the caller. */
+  async exportWalletAuthorization(options = {}) {
+    options.signal?.throwIfAborted();
+    await this.signingCurrent();
+    check5(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check5(
+      ["prepared", "authorized"].includes(this.status),
+      "operation is not awaiting wallet authorization"
+    );
+    return walletSigningRequest(this.#saved.plan);
+  }
+  /** Attach an external EOA signature, retaining its witness only at the private proving boundary. */
+  async withWalletSignature(signature, options = {}) {
+    options.signal?.throwIfAborted();
+    await this.signingCurrent();
+    check5(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check5(
+      ["prepared", "authorized"].includes(this.status),
+      "operation is not awaiting wallet authorization"
+    );
+    const authorization = await acceptWalletSignature(this.#saved.plan, signature);
+    return this.stage(
+      "wallet authorization",
+      ["prepared", "authorized"],
+      async () => ({ status: "authorized", authorization }),
+      options.signal
+    );
+  }
+  /** Export only after proving when the funding authorization binds an actual proof hash. */
+  async exportFundingAuthorization(options = {}) {
+    options.signal?.throwIfAborted();
+    await this.signingCurrent();
+    check5(
+      this.status === (this.kind === "shield" ? "prepared" : "proved"),
+      "operation is not awaiting funding authorization or proof"
+    );
+    const request = await fundingSigningRequest(this.#saved, this.#runtime);
+    options.signal?.throwIfAborted();
+    await this.signingCurrent();
+    return request;
+  }
+  /** Verify an external signature against this handle's own frozen operation. */
+  async withFundingSignature(signature, options = {}) {
+    options.signal?.throwIfAborted();
+    await this.signingCurrent();
+    check5(
+      this.status === (this.kind === "shield" ? "prepared" : "proved"),
+      "operation is not awaiting funding authorization or proof"
+    );
+    const verified = await acceptFundingSignature(this.#saved, signature, this.#runtime);
+    return this.stage(
+      "funding authorization",
+      this.kind === "shield" ? ["prepared"] : ["proved"],
+      async (saved) => {
+        saved.plan.funding.signature = verified;
+        if (saved.plan.statement?.target !== "noir-recursive") {
+          saved.call = await this.encode(saved);
+        }
+        return { status: "ready" };
+      },
+      options.signal
+    );
+  }
   async authorize(options = {}) {
     check5(
       requiresAuthorization(this.#saved.plan),
@@ -3223,7 +3435,8 @@ var Operation = class _Operation {
       options.signal
     );
   }
-  async prove(options = {}) {
+  async prove(suppliedOptions = {}) {
+    const options = { ...suppliedOptions };
     const plan = this.#saved.plan;
     check5(plan.kind !== "shield", "shield requires no proof");
     if (requiresAuthorization(plan)) {
@@ -3234,7 +3447,7 @@ var Operation = class _Operation {
     }
     const prover = this.#runtime.options.prover;
     if (!prover) {
-      throw new MissingCapabilityError("prover");
+      throw new MissingCapabilityError2("prover");
     }
     return this.stage(
       "proof",
@@ -3268,7 +3481,7 @@ var Operation = class _Operation {
     check5(p.kind === "shield" || this.#saved.proof, "proof must precede funding authorization");
     const signer = this.#runtime.options.fundingSigner;
     if (!signer) {
-      throw new MissingCapabilityError("EVM funding signer");
+      throw new MissingCapabilityError2("EVM funding signer");
     }
     check5(
       signer.address.toLowerCase() === p.funding.payer.toLowerCase(),
@@ -3457,25 +3670,142 @@ var Operation = class _Operation {
   }
 };
 
+// src/session/WalletSession.ts
+import { Wallet } from "@invisi-labs/core";
+
+// src/session/history.ts
+function walletHistory(state, options = {}) {
+  const token = options.tokenAddress?.toLowerCase();
+  const outgoing = [];
+  for (const record of Object.values(state.operations)) {
+    const saved = record.payload;
+    if (!saved?.plan || token && saved.plan.context.tokenAddress.toLowerCase() !== token) {
+      continue;
+    }
+    const plan = saved.plan;
+    outgoing.push({
+      ...operationPreview(plan, record.status),
+      preparedAt: { ...plan.preparedAt },
+      ...record.transactionHash ? { transactionHash: record.transactionHash } : {},
+      outputs: plan.outputs.map((output) => ({
+        to: output.address,
+        amount: output.note.amount,
+        change: output.change,
+        commitment: output.commitment,
+        payload: Uint8Array.from(output.note.payload ?? [])
+      }))
+    });
+  }
+  outgoing.sort(
+    (a, b) => a.preparedAt.number === b.preparedAt.number ? a.id.localeCompare(b.id) : a.preparedAt.number > b.preparedAt.number ? -1 : 1
+  );
+  const incoming = [];
+  for (const record of Object.values(state.notes)) {
+    const tokenAddress = `0x${record.note.tokenAddress.toString(16).padStart(40, "0")}`;
+    if (token && tokenAddress !== token) continue;
+    incoming.push({
+      commitment: record.commitment,
+      treeId: record.treeId,
+      leafIndex: record.leafIndex,
+      blockNumber: record.blockNumber,
+      blockHash: record.blockHash,
+      ...record.transactionHash ? { transactionHash: record.transactionHash } : {},
+      tokenAddress,
+      amount: record.note.amount,
+      payload: Uint8Array.from(record.note.payload ?? []),
+      spent: record.spent
+    });
+  }
+  incoming.sort(
+    (a, b) => a.blockNumber === b.blockNumber ? a.commitment.localeCompare(b.commitment) : a.blockNumber > b.blockNumber ? -1 : 1
+  );
+  return structuredClone({
+    revision: state.revision,
+    checkedThrough: state.discoveryThrough ?? null,
+    invalidated: !!state.invalidated,
+    outgoing,
+    incoming
+  });
+}
+
 // src/session/WalletSession.ts
 import { getAddress as getAddress4 } from "ethers";
-import { MissingCapabilityError as MissingCapabilityError3 } from "@invisi-labs/core";
+import { MissingCapabilityError as MissingCapabilityError5 } from "@invisi-labs/core";
 
 // src/session/transaction-preparation.ts
 import { getAddress as getAddress3 } from "ethers";
 import {
   normalizeTransactRequest,
   transactUserPublicInputs as transactUserPublicInputs2,
-  WitnessBuilder as WitnessBuilder3,
+  WitnessBuilder as WitnessBuilder4,
   ZERO_ADDRESS
 } from "@invisi-labs/protocol";
 
+// src/resolve-recipient.ts
+import {
+  MissingCapabilityError as MissingCapabilityError3,
+  ReceivingAddress as ReceivingAddress2
+} from "@invisi-labs/core";
+async function resolveRecipient(address2, lookup, details = {}) {
+  const context = { ...details, address: address2 };
+  let recipient;
+  try {
+    recipient = ReceivingAddress2.parse(address2);
+  } catch (cause) {
+    throw new InvisiError("INVALID_RECIPIENT", "Invalid recipient address", {
+      ...context,
+      cause
+    });
+  }
+  if (recipient.kind === "long") return recipient;
+  if (!lookup) {
+    throw new InvisiError("MISSING_CAPABILITY", "Missing registry lookup capability", {
+      ...context,
+      capability: "registry lookup"
+    });
+  }
+  let keys;
+  try {
+    keys = await lookup(recipient.walletIdentity);
+  } catch (cause) {
+    if (cause instanceof MissingCapabilityError3) {
+      throw new InvisiError("MISSING_CAPABILITY", cause.message, {
+        ...context,
+        cause,
+        capability: cause.capability
+      });
+    }
+    throw new InvisiError("RECIPIENT_LOOKUP_FAILED", "Recipient registry lookup failed", {
+      ...context,
+      cause
+    });
+  }
+  if (keys == null) {
+    throw new InvisiError(
+      "EVM_ADDRESS_NOT_REGISTERED",
+      "EVM address has no registered receiving keys",
+      context
+    );
+  }
+  try {
+    return ReceivingAddress2.from({
+      walletIdentity: recipient.walletIdentity,
+      viewingPublicKey: keys.viewingPublicKey,
+      clueKey: keys.clueKey
+    });
+  } catch (cause) {
+    throw new InvisiError(
+      "RECIPIENT_LOOKUP_FAILED",
+      "Registry returned invalid receiving keys",
+      { ...context, cause }
+    );
+  }
+}
+
 // src/session/prepare-common.ts
 import { getAddress, hexlify } from "ethers";
 import {
-  encodeMemo,
-  MissingCapabilityError as MissingCapabilityError2,
-  ReceivingAddress as ReceivingAddress2,
+  MissingCapabilityError as MissingCapabilityError4,
   computeNoteCommitment,
   computeNoteIdentity,
   createClue,
@@ -3517,6 +3847,27 @@ function positiveAmount(value, bits = 128) {
   }
   return value;
 }
+function copyApplicationPayload(value) {
+  if (value === void 0) return new Uint8Array();
+  if (!(value instanceof Uint8Array)) throw new TypeError("payload must be Uint8Array");
+  return Uint8Array.from(value);
+}
+function positiveOutputAmount(payment, outputIndex) {
+  try {
+    return positiveAmount(payment.amount);
+  } catch (cause) {
+    throw new InvisiError(
+      "PREPARATION_FAILED",
+      cause instanceof Error ? cause.message : "Invalid output amount",
+      {
+        address: payment.to,
+        field: "amount",
+        ...outputIndex === void 0 ? {} : { outputIndex },
+        cause
+      }
+    );
+  }
+}
 var Preparation = class {
   constructor(runtime) {
     this.runtime = runtime;
@@ -3586,52 +3937,70 @@ var Preparation = class {
     }
     return { funding, fundingMode: mode };
   }
-  async output(payment, context, change = false) {
-    positiveAmount(payment.amount);
-    const recipient = await ReceivingAddress2.parse(payment.to).resolve(
-      this.runtime.options.addressResolver
-    );
-    const memo = encodeMemo(payment.memo);
-    const nonce = generateNonce();
-    const identity = await computeNoteIdentity(BigInt(recipient.walletIdentity), nonce);
-    const keys = recipient.getReceivingKeys();
-    const note = {
-      chainId: context.chainId,
-      protocolAddress: BigInt(context.protocolAddress),
-      tokenAddress: BigInt(context.tokenAddress),
-      walletIdentity: recipient.walletIdentity,
-      amount: payment.amount,
-      ...memo.length === 0 ? {} : { memo },
-      nonce
-    };
-    const commitment = await computeNoteCommitment(
-      context.chainId,
-      identity,
-      note.tokenAddress,
-      note.amount
-    );
-    return {
-      note,
-      commitment,
-      identity,
-      address: payment.to,
-      change,
-      delivery: {
-        ciphertext: hexlify(
-          await encryptPrivateTransferNote(keys.viewingPublicKey, note, {
-            chainId: context.chainId,
-            protocolAddress: note.protocolAddress,
-            outputCommitment: commitment
-          })
-        ),
-        clue: hexlify(createClue(keys.clueKey))
-      }
-    };
+  async output(payment, context, change = false, outputIndex) {
+    try {
+      positiveOutputAmount(payment, outputIndex);
+      const recipient = await resolveRecipient(
+        payment.to,
+        this.runtime.options.addressResolver,
+        {
+          field: change ? "changeAddress" : "to",
+          ...outputIndex === void 0 ? {} : { outputIndex }
+        }
+      );
+      const nonce = generateNonce();
+      const identity = await computeNoteIdentity(BigInt(recipient.walletIdentity), nonce);
+      const keys = recipient.getReceivingKeys();
+      const note = {
+        chainId: context.chainId,
+        protocolAddress: BigInt(context.protocolAddress),
+        tokenAddress: BigInt(context.tokenAddress),
+        walletIdentity: recipient.walletIdentity,
+        amount: payment.amount,
+        payload: copyApplicationPayload(payment.payload),
+        nonce
+      };
+      const commitment = await computeNoteCommitment(
+        context.chainId,
+        identity,
+        note.tokenAddress,
+        note.amount
+      );
+      return {
+        note,
+        commitment,
+        identity,
+        address: payment.to,
+        change,
+        delivery: {
+          ciphertext: hexlify(
+            await encryptPrivateTransferNote(keys.viewingPublicKey, note, {
+              chainId: context.chainId,
+              protocolAddress: note.protocolAddress,
+              outputCommitment: commitment
+            })
+          ),
+          clue: hexlify(createClue(keys.clueKey))
+        }
+      };
+    } catch (cause) {
+      if (cause instanceof InvisiError) throw cause;
+      throw new InvisiError(
+        "PREPARATION_FAILED",
+        cause instanceof Error ? cause.message : "Output preparation failed",
+        {
+          address: payment.to,
+          field: change ? "changeAddress" : "to",
+          ...outputIndex === void 0 ? {} : { outputIndex },
+          cause
+        }
+      );
+    }
   }
   async membership(input, frame) {
     const { options, reader } = this.runtime;
     if (!options.protocolRpc)
-      throw new MissingCapabilityError2("Protocol RPC membership provider");
+      throw new MissingCapabilityError4("Protocol RPC membership provider");
     const root = this.#roots.get(input.treeId);
     const proof = await options.protocolRpc.getMembership(
       frame.context,
@@ -3736,7 +4105,6 @@ import {
   FIELD_MODULUS as FIELD_MODULUS3,
   normalizeCreditPolicy,
   applyCreditDrawUsage,
-  ReceivingAddress as ReceivingAddress3,
   computeCreditNullifier as computeCreditNullifier2,
   computeCreditRecoveryPad,
   createClue as createClue2,
@@ -3747,7 +4115,7 @@ import {
   normalizeCreditDeliveryState as normalizeCreditDeliveryState2
 } from "@invisi-labs/core";
 import {
-  WitnessBuilder as WitnessBuilder2,
+  WitnessBuilder as WitnessBuilder3,
   cancelCreditPublicInputs as cancelCreditPublicInputs2,
   createCreditPublicInputs as createCreditPublicInputs2,
   creditDrawPublicInputs as creditDrawPublicInputs2,
@@ -3838,10 +4206,16 @@ var CreditPreparation = class {
     positiveAmount(options.amount, 126);
     const frame = await this.#prepare.frame(options.deadline);
     const expiry = this.expiry(options.expiry, frame);
-    const spender = await ReceivingAddress3.parse(options.spender).resolve(
-      this.runtime.options.addressResolver
+    const spender = await resolveRecipient(
+      options.spender,
+      this.runtime.options.addressResolver,
+      { field: "spender" }
+    );
+    const owner = await resolveRecipient(
+      this.runtime.options.wallet.getReceivingAddress().toString(),
+      this.runtime.options.addressResolver,
+      { field: "wallet" }
     );
-    const owner = await this.runtime.options.wallet.getReceivingAddress().resolve(this.runtime.options.addressResolver);
     const ownerPayout = getAddress2(owner.walletIdentity);
     const spenderPayout = getAddress2(spender.walletIdentity);
     if (BigInt(ownerPayout) === 0n || BigInt(spenderPayout) === 0n) {
@@ -3863,7 +4237,7 @@ var CreditPreparation = class {
             monthlyLimit: options.monthlyLimit ?? 0n
           }),
           amount: options.amount,
-          ...options.memo === void 0 ? {} : { memo: options.memo },
+          payload: copyApplicationPayload(options.payload),
           expiry,
           nonce: generateNonce2(),
           creditSharedKey: generateCreditSharedKey()
@@ -3928,12 +4302,12 @@ var CreditPreparation = class {
         creditNullifier: previous.nullifier,
         previousExpiry: previous.input.state.note.expiry
       };
-      plan.statement = WitnessBuilder2.statement(
+      plan.statement = WitnessBuilder3.statement(
         "credit_top_up",
         topUpCreditPublicInputs2(frame.context, plan.credit.topUp, deliveries, plan.funding)
       );
     } else {
-      plan.statement = WitnessBuilder2.statement(
+      plan.statement = WitnessBuilder3.statement(
         "create_credit",
         createCreditPublicInputs2(frame.context, creation, deliveries, plan.funding)
       );
@@ -3965,7 +4339,9 @@ var CreditPreparation = class {
           amount,
           expiry,
           nonce: generateNonce2(),
-          ...options.memo === void 0 ? {} : { memo: options.memo }
+          payload: copyApplicationPayload(
+            options.payload === void 0 ? old.note.payload : options.payload
+          )
         }
       },
       frame
@@ -4035,7 +4411,9 @@ var CreditPreparation = class {
             ...n,
             ...usage,
             amount: remaining,
-            ...options.credits[i].memo === void 0 ? {} : { memo: options.credits[i].memo },
+            payload: copyApplicationPayload(
+              options.credits[i].payload === void 0 ? n.payload : options.credits[i].payload
+            ),
             nonce: await deriveRemainderNonce(...args)
           }
         },
@@ -4068,7 +4446,7 @@ var CreditPreparation = class {
       draw: params,
       amounts
     };
-    plan.statement = WitnessBuilder2.statement(
+    plan.statement = WitnessBuilder3.statement(
       profile.name,
       creditDrawPublicInputs2(frame.context, params, deliveries)
     );
@@ -4090,7 +4468,7 @@ var CreditPreparation = class {
     };
     plan.capacity = 1;
     plan.credit = { inputs: [previous.input], outputs: [], deliveries: [], cancel: params };
-    plan.statement = WitnessBuilder2.statement(
+    plan.statement = WitnessBuilder3.statement(
       "credit_cancel",
       cancelCreditPublicInputs2(frame.context, params)
     );
@@ -4113,87 +4491,48 @@ var TransactionPreparation = class {
     return this.context.scope;
   }
   async prepareTransfer(options) {
+    if (Object.hasOwn(options, "target") || Object.hasOwn(options, "execution")) {
+      throw new Error(
+        "prepareTransfer accepts no target or execution; choose execution in prove()"
+      );
+    }
     const copied = structuredClone(options);
-    const preparation = new Preparation(this.runtime(copied.tokenAddress));
+    const runtime = this.runtime(copied.tokenAddress);
+    if (copied.commitments !== void 0 && copied.commitments.length === 0)
+      throw new Error("empty explicit input selection");
+    const preparation = new Preparation({
+      ...runtime,
+      ...copied.commitments !== void 0 ? { inputSelection: copied.commitments } : {}
+    });
     const frame = await preparation.frame(copied.deadline);
-    if (copied.outputs.length < 1 || copied.outputs.length > 168) {
-      throw new Error("transfer requires 1..168 outputs");
+    if (copied.outputs.length > 168) throw new Error("transfer supports at most 168 outputs");
+    let withdrawalAddress = ZERO_ADDRESS;
+    let withdrawalAmount = 0n;
+    if (copied.withdrawal !== void 0) {
+      withdrawalAddress = getAddress3(copied.withdrawal.to);
+      positiveAmount(copied.withdrawal.amount);
+      if (BigInt(withdrawalAddress) === 0n)
+        throw new Error("withdrawal destination must be nonzero");
+      withdrawalAmount = copied.withdrawal.amount;
     }
+    if (copied.outputs.length === 0 && withdrawalAmount === 0n)
+      throw new Error("transfer requires a private output or public withdrawal");
     const total = copied.outputs.reduce(
-      (sum, output) => sum + positiveAmount(output.amount),
-      0n
+      (sum, output, index2) => sum + positiveOutputAmount(output, index2),
+      withdrawalAmount
     );
     const funding = await preparation.funding(copied.funding, frame);
     return this.funds(
-      "transfer",
       copied.outputs,
       total,
-      ZERO_ADDRESS,
-      0n,
+      withdrawalAddress,
+      withdrawalAmount,
       frame,
       funding,
-      copied.target,
-      preparation
-    );
-  }
-  async prepareWithdraw(options) {
-    const copied = structuredClone(options);
-    const preparation = new Preparation(this.runtime(copied.tokenAddress));
-    const frame = await preparation.frame(copied.deadline);
-    const to = getAddress3(copied.to);
-    positiveAmount(copied.amount);
-    if (BigInt(to) === 0n) {
-      throw new Error("withdrawal destination must be nonzero");
-    }
-    return this.funds(
-      "withdraw",
-      [],
-      copied.amount,
-      to,
-      copied.amount,
-      frame,
-      { funding: {}, fundingMode: "none" },
-      copied.target,
       preparation
     );
   }
-  /** Full payout to the note owner; no arbitrary destination, change or spending signature. */
-  async prepareSweep(options) {
-    const copied = structuredClone(options);
-    const runtime = this.runtime(copied.tokenAddress);
-    const state = await runtime.readInventory();
-    const available = Object.values(state.notes).filter(
-      (record) => record.note.tokenAddress === BigInt(copied.tokenAddress) && record.spent === "unspent" && !state.reservations[record.commitment]
-    );
-    const selected = copied.commitments ?? available.map((record) => record.commitment);
-    if (selected.length === 0) throw new Error("empty sweep input selection");
-    if (new Set(selected).size !== selected.length) throw new Error("duplicate sweep inputs");
-    const byId = new Map(available.map((record) => [record.commitment, record]));
-    let amount = 0n;
-    for (const id of selected) {
-      const record = byId.get(id);
-      if (!record) throw new Error("sweep input unavailable");
-      amount += record.note.amount;
-    }
-    positiveAmount(amount);
-    const preparation = new Preparation({
-      ...runtime,
-      inputSelection: selected
-    });
-    const frame = await preparation.frame(copied.deadline);
-    return this.funds(
-      "sweep",
-      [],
-      amount,
-      this.scope.walletIdentity,
-      amount,
-      frame,
-      { funding: {}, fundingMode: "none" },
-      copied.target,
-      preparation
-    );
-  }
-  async funds(kind, payments, total, withdrawalAddress, withdrawalAmount, frame, funding, target, preparation) {
+  async funds(payments, total, withdrawalAddress, withdrawalAmount, frame, funding, preparation) {
     if (total >= 1n << 135n) {
       throw new Error("transaction sum exceeds uint135");
     }
@@ -4203,7 +4542,7 @@ var TransactionPreparation = class {
       frame
     );
     const outputs = await Promise.all(
-      payments.map((payment) => preparation.output(payment, context))
+      payments.map((payment, index2) => preparation.output(payment, context, false, index2))
     );
     const change = selection.amount + (funding.funding.amount ?? 0n) - total;
     if (change > 0n) {
@@ -4229,16 +4568,16 @@ var TransactionPreparation = class {
     };
     const deliveries = outputs.map((output) => output.delivery);
     const normalized = normalizeTransactRequest(context, params, deliveries, funding.funding);
-    const statement2 = WitnessBuilder3.statement(
+    const statement2 = WitnessBuilder4.statement(
       `transact_user_slots${normalized.capacity}`,
       transactUserPublicInputs2(context, params, deliveries, funding.funding),
-      target ?? "evm"
+      "evm"
     );
     await preparation.assertBlock(frame);
     return preparation.runtime.complete({
       version: 1,
       id: crypto.randomUUID(),
-      kind,
+      kind: "transfer",
       context,
       scope: this.scope,
       preparedAt: block,
@@ -4260,7 +4599,9 @@ var TransactionPreparation = class {
       throw new Error("shield requires 1..10 outputs");
     }
     const outputs = await Promise.all(
-      copied.outputs.map((output) => preparation.output(output, frame.context))
+      copied.outputs.map(
+        (output, index2) => preparation.output(output, frame.context, false, index2)
+      )
     );
     if (outputs.reduce((sum, output) => sum + output.note.amount, 0n) !== (funding.funding.amount ?? 0n)) {
       throw new Error("shield funding must equal output total");
@@ -4369,7 +4710,6 @@ import { NullifierCapability } from "@invisi-labs/core";
 
 // src/session/inventory.ts
 import {
-  encodeMemo as encodeMemo2,
   computeCreditCommitment as computeCreditCommitment2,
   computeCreditNullifier as computeCreditNullifier3,
   computeCreditSharedKeyHash as computeCreditSharedKeyHash2,
@@ -4519,7 +4859,7 @@ var InventoryProcessor = class {
             const child = foundByKey.get(
               params.remainderCommitments[index2] + ":" + previous.role
             );
-            const memo = child?.state.note.memo;
+            const payload = child?.state.note.payload;
             const record = {
               commitment: params.remainderCommitments[index2],
               treeId: BigInt(args.outputTreeId),
@@ -4532,7 +4872,7 @@ var InventoryProcessor = class {
                 ...clone(previous.state),
                 note: {
                   ...remainder,
-                  ...memo === void 0 ? {} : { memo: encodeMemo2(memo) }
+                  ...payload === void 0 ? {} : { payload: clone(payload) }
                 }
               },
               receivingKeySource: { kind: "draw", commitment: previous.commitment },
@@ -4780,6 +5120,7 @@ var WalletUpdater = class extends InventoryProcessor {
           draft.notes = {};
           draft.credits = {};
           delete draft.observedThrough;
+          delete draft.discoveryThrough;
           delete draft.invalidated;
         }
         mergeReceiptRecords(draft, { notes, credits, checkpoint: block });
@@ -4811,13 +5152,38 @@ var WalletUpdater = class extends InventoryProcessor {
 var WalletSession = class {
   #options;
   #updater;
+  #listeners = /* @__PURE__ */ new Set();
   #sending = /* @__PURE__ */ new Set();
   #refreshQueue = Promise.resolve();
   scope;
   protocol;
   constructor(options) {
+    if ("ciphertextCodecs" in options || "envelopeVersion" in options) {
+      throw new Error(
+        "SDK envelope versions are fixed; encode application payload bytes externally"
+      );
+    }
+    const store = options.store;
     this.#options = {
       ...options,
+      ...store ? {
+        store: {
+          persistent: store.persistent,
+          readSnapshot: (scope) => store.readSnapshot(scope),
+          transaction: async (scope, action) => {
+            const result = await store.transaction(scope, action);
+            if (scopeKey(scope) === scopeKey(this.scope)) {
+              for (const listener of [...this.#listeners]) {
+                try {
+                  listener();
+                } catch {
+                }
+              }
+            }
+            return result;
+          }
+        }
+      } : {},
       ...options.gasBenchmarks ? { gasBenchmarks: copyGasBenchmarks(options.gasBenchmarks) } : {}
     };
     this.protocol = options.protocol;
@@ -4832,7 +5198,7 @@ var WalletSession = class {
   /** Delegate sending to ethers; managed operations additionally retain the resulting hash. */
   async sendTransaction(input, options = {}) {
     const signer = this.#options.signer;
-    if (!signer) throw new MissingCapabilityError3("ethers signer");
+    if (!signer) throw new MissingCapabilityError5("ethers signer");
     const operation = input instanceof Operation ? input : void 0;
     if (operation && this.#sending.has(operation.id))
       throw new Error("operation is already being sent by this session");
@@ -4840,12 +5206,12 @@ var WalletSession = class {
     const overrides = { ...options };
     const plain = operation ? void 0 : { ...input };
     try {
-      if (!signer.provider) throw new MissingCapabilityError3("connected ethers signer");
+      if (!signer.provider) throw new MissingCapabilityError5("connected ethers signer");
       if ((await signer.provider.getNetwork()).chainId !== this.protocol.context.chainId) {
         throw new Error("signer-provider session chain mismatch");
       }
       if (operation) {
-        if (!this.#options.store) throw new MissingCapabilityError3("wallet store");
+        if (!this.#options.store) throw new MissingCapabilityError5("wallet store");
         const state = await this.#options.store.readSnapshot(this.scope);
         if (!state.operations[operation.id])
           throw new Error("operation does not belong to this wallet session");
@@ -4876,25 +5242,30 @@ var WalletSession = class {
   runtime(tokenAddress) {
     const options = this.#options;
     if (!options.store) {
-      throw new MissingCapabilityError3("wallet store");
+      throw new MissingCapabilityError5("wallet store");
     }
     if (!options.chainReader) {
-      throw new MissingCapabilityError3("chain reader");
+      throw new MissingCapabilityError5("chain reader");
     }
     return {
       options: { ...options, protocol: options.protocol.forToken(tokenAddress) },
       scope: this.scope,
       store: options.store,
       reader: options.chainReader,
-      authorization: () => options.authorization ?? options.wallet.exportAuthorization()
+      authorization: () => {
+        if (options.authorization) return options.authorization;
+        if (options.wallet instanceof Wallet) return options.wallet.exportAuthorization();
+        throw new MissingCapabilityError5("wallet authorization");
+      }
     };
   }
   updater() {
     if (this.#updater) return this.#updater;
     const options = this.#options;
     if (!options.store || !options.chainReader || !options.protocolRpc)
-      throw new MissingCapabilityError3("wallet store, chain reader and Protocol RPC");
-    const viewing = options.viewing ?? options.wallet.getViewer();
+      throw new MissingCapabilityError5("wallet store, chain reader and Protocol RPC");
+    const viewing = options.viewing ?? (options.wallet instanceof Wallet ? options.wallet.getViewer() : void 0);
+    if (!viewing) throw new MissingCapabilityError5("viewing");
     const receivingAddress = options.wallet.getReceivingAddress();
     const receivingKeys = receivingAddress.kind === "long" ? receivingAddress.getReceivingKeys() : void 0;
     this.#updater = new WalletUpdater({
@@ -4908,10 +5279,27 @@ var WalletSession = class {
     });
     return this.#updater;
   }
+  /** Local session commits only. Host applications own cross-tab/store subscriptions. */
+  subscribe(listener) {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+  /** Detached history for wallet UI; construction records do not imply chain success. */
+  async getHistory(options = {}) {
+    const tokenAddress = options.tokenAddress ? getAddress4(options.tokenAddress) : void 0;
+    const store = this.#options.store;
+    if (!store) throw new MissingCapabilityError5("wallet store");
+    return walletHistory(
+      await store.readSnapshot(this.scope),
+      tokenAddress ? { tokenAddress } : {}
+    );
+  }
   async balance(tokenAddress) {
     const store = this.#options.store;
     if (!store) {
-      throw new MissingCapabilityError3("wallet store");
+      throw new MissingCapabilityError5("wallet store");
     }
     return walletBalance(await store.readSnapshot(this.scope), getAddress4(tokenAddress));
   }
@@ -4919,15 +5307,15 @@ var WalletSession = class {
   async refresh(options) {
     const provider = this.#options.protocolRpc;
     const reader = this.#options.chainReader;
-    if (!reader) throw new MissingCapabilityError3("chain reader");
-    if (!provider) throw new MissingCapabilityError3("Protocol RPC");
+    if (!reader) throw new MissingCapabilityError5("chain reader");
+    if (!provider) throw new MissingCapabilityError5("Protocol RPC");
     const updater = this.updater();
     const request = {
       ...options,
       ...options.detectionKey ? { detectionKey: options.detectionKey.slice() } : {}
     };
-    const task = this.#refreshQueue.then(
-      () => refreshWallet(
+    const task = this.#refreshQueue.then(async () => {
+      const result = await refreshWallet(
         {
           provider,
           reader,
@@ -4936,8 +5324,21 @@ var WalletSession = class {
           apply: (batch, settings) => updater.applyUpdates(batch, settings)
         },
         request
-      )
-    );
+      );
+      await this.#options.store.transaction(this.scope, (state) => {
+        request.signal?.throwIfAborted();
+        if (state.invalidated) throw new Error("wallet requires canonical resync");
+        const previous = state.discoveryThrough;
+        const start = previous ? previous.number + 1n : this.protocol.deployment.protocol.fromBlock;
+        if (request.fromBlock <= start && (!previous || result.block.number >= previous.number)) {
+          state.discoveryThrough = {
+            number: result.block.number,
+            hash: result.block.hash
+          };
+        }
+      });
+      return result;
+    });
     this.#refreshQueue = task.catch(() => {
     });
     return task;
@@ -4948,38 +5349,43 @@ var WalletSession = class {
       options: runtime.options,
       scope: runtime.scope,
       reader: runtime.reader,
-      authorization: runtime.authorization,
       readInventory: () => runtime.store.readSnapshot(runtime.scope),
       complete: (plan) => Operation.prepare(runtime, plan)
     });
   }
   async prepareTransfer(options) {
-    return this.preparation(options.tokenAddress).prepareTransfer(options);
-  }
-  async prepareWithdraw(options) {
-    return this.preparation(options.tokenAddress).prepareWithdraw(options);
-  }
-  async prepareSweep(options) {
-    return this.preparation(options.tokenAddress).prepareSweep(options);
+    return prepareWithErrors("prepareTransfer", async () => {
+      return this.preparation(options.tokenAddress).prepareTransfer(options);
+    });
   }
   async prepareShield(options) {
-    return this.preparation(options.tokenAddress).prepareShield(options);
+    return prepareWithErrors("prepareShield", async () => {
+      return this.preparation(options.tokenAddress).prepareShield(options);
+    });
   }
   async prepareCreateCredit(options) {
-    return this.preparation(options.tokenAddress).prepareCreateCredit(options);
+    return prepareWithErrors("prepareCreateCredit", async () => {
+      return this.preparation(options.tokenAddress).prepareCreateCredit(options);
+    });
   }
   async prepareDrawCredit(options) {
-    return this.preparation(options.tokenAddress).prepareDrawCredit(options);
+    return prepareWithErrors("prepareDrawCredit", async () => {
+      return this.preparation(options.tokenAddress).prepareDrawCredit(options);
+    });
   }
   async prepareTopUpCredit(options) {
-    return this.preparation(options.tokenAddress).prepareTopUpCredit(options);
+    return prepareWithErrors("prepareTopUpCredit", async () => {
+      return this.preparation(options.tokenAddress).prepareTopUpCredit(options);
+    });
   }
   async prepareCancelCredit(options) {
-    return this.preparation(options.tokenAddress).prepareCancelCredit(options);
+    return prepareWithErrors("prepareCancelCredit", async () => {
+      return this.preparation(options.tokenAddress).prepareCancelCredit(options);
+    });
   }
   async resume(operationId) {
     const store = this.#options.store;
-    if (!store) throw new MissingCapabilityError3("wallet store");
+    if (!store) throw new MissingCapabilityError5("wallet store");
     const state = await store.readSnapshot(this.scope);
     const saved = state.operations[operationId]?.payload;
     if (!saved?.plan) throw new Error("operation not found");
@@ -5051,6 +5457,8 @@ var MemoryWalletStore = class extends TransactionalWalletStore {
 };
 
 export {
+  InvisiError,
+  prepareWithErrors,
   walletBalance,
   requiresAuthorization,
   statement,
@@ -5060,14 +5468,18 @@ export {
   defineGasBenchmarks,
   estimateGasReference,
   sameStatement,
-  authorizeOperation,
   proveOperation,
-  signOperationFunding,
+  walletSigningRequest,
+  acceptWalletSignature,
+  fundingSigningRequest,
+  acceptFundingSignature,
   operationPreview,
   positiveAmount,
   TransactionPreparation,
   serializeState,
   deserializeState,
+  readProtocolLogs,
+  decryptCandidates,
   DisclosureVerifier,
   TransactionalWalletStore,
   MemoryAtomicRecords,
@@ -5075,4 +5487,4 @@ export {
   WalletSession,
   MemoryWalletStore
 };
-//# sourceMappingURL=chunk-FSQYZO66.js.map
+//# sourceMappingURL=chunk-BE52B32Z.js.map