@invisi-labs/sdk 1.1.3 → 1.1.4

package/dist/memory.cjs

@@ -371,8 +371,9 @@ function readProtocolLogs(receipt, protocolAddress) {
 }
 
 // src/session/discovery.ts
-var import_ethers3 = require("ethers");
 var import_core = require("@invisi-labs/core");
+var import_ethers3 = require("ethers");
+var import_core2 = require("@invisi-labs/core");
 var import_protocol = require("@invisi-labs/protocol");
 var EVENTS = /* @__PURE__ */ new Set([
   "CommitmentsInserted",
@@ -466,7 +467,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
     check2(inserted, "delivery has no matching canonical insertion");
     if (commitment !== void 0)
       check2(hash(commitment) === inserted, "delivery commitment conflicts with insertion");
-    const delivery = (0, import_protocol.normalizeDelivery)(wire, { credit: role !== "funds" });
+    const delivery = (0, import_protocol.normalizeOpaqueDelivery)(wire);
     check2(
       typeof token === "string" && (0, import_ethers3.isAddress)(token) && BigInt(token) !== 0n,
       "invalid event token"
@@ -497,7 +498,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 (0, import_protocol.normalizeDelivery)(ds[2], { empty: true });
+    else (0, import_protocol.normalizeOpaqueDelivery)(ds[2], { empty: true });
   };
   for (const log of relevant) {
     const a = object(log.args);
@@ -527,7 +528,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
         const length = Number.parseInt(packed.slice(offset, offset + 4), 16);
         offset += 4;
         check2(
-          length >= 160 && length <= 416 && offset + length * 2 + 136 <= packed.length,
+          length >= 1 && length <= import_core.MAX_CIPHERTEXT_BYTES && offset + length * 2 + 136 <= packed.length,
           "invalid packed delivery length"
         );
         const ciphertext = `0x${packed.slice(offset, offset + length * 2)}`;
@@ -549,8 +550,8 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
       cs.forEach((c, i) => {
         if (BigInt(hash(c)) === 0n) {
           check2(integer(leaves[i]) === 0n, "absent remainder has nonzero position");
-          (0, import_protocol.normalizeDelivery)(ds[2 * i], { empty: true });
-          (0, import_protocol.normalizeDelivery)(ds[2 * i + 1], { empty: true });
+          (0, import_protocol.normalizeOpaqueDelivery)(ds[2 * i], { empty: true });
+          (0, import_protocol.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]);
@@ -562,7 +563,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
 }
 async function decryptCandidates(logs, options) {
   contextCheck(options.context);
-  (0, import_core.decodeAddress)(import_core.ReceivingAddress.fromIdentity(options.viewing.walletIdentity).toString());
+  (0, import_core2.decodeAddress)(import_core2.ReceivingAddress.fromIdentity(options.viewing.walletIdentity).toString());
   check2(
     !logs.some(
       (log) => log.address.toLowerCase() === options.context.protocolAddress.toLowerCase() && log.removed
@@ -904,7 +905,7 @@ function walletBalances(state) {
 }
 
 // src/session/store.ts
-var import_core2 = require("@invisi-labs/core");
+var import_core3 = require("@invisi-labs/core");
 var import_sha256 = require("@noble/hashes/sha256");
 var import_utils = require("@noble/hashes/utils");
 function scopeKey(scope) {
@@ -920,7 +921,7 @@ function scopeKey(scope) {
   return (0, import_utils.bytesToHex)(
     (0, import_sha256.sha256)(
       (0, import_utils.utf8ToBytes)(
-        "Invisi.WalletScope.v2:" + JSON.stringify([
+        "Invisi.WalletScope.v1:" + JSON.stringify([
           scope.namespace,
           scope.chainId.toString(),
           scope.protocolAddress.toLowerCase(),
@@ -957,12 +958,12 @@ function validateState(state, scope, revision) {
       throw new Error("invalid spent state");
   }
   for (const record of Object.values(state.credits)) {
-    const note = (0, import_core2.normalizeCreditDeliveryState)(record.state).note;
+    const note = (0, import_core3.normalizeCreditDeliveryState)(record.state).note;
     if (note.chainId !== scope.chainId || note.protocolAddress !== BigInt(scope.protocolAddress) || !["owner", "spender"].includes(record.role) || (record.role === "owner" ? note.ownerWalletIdentity : note.spenderWalletIdentity).toLowerCase() !== scope.walletIdentity.toLowerCase() || !["unspent", "unknown", "spent"].includes(record.spent))
       throw new Error("invalid stored Credit context or role");
   }
   for (const record of [...Object.values(state.notes), ...Object.values(state.credits)]) {
-    if (!/^0x[0-9a-fA-F]{64}$/.test(record.commitment) || BigInt(record.commitment) <= 0n || BigInt(record.commitment) >= import_core2.FIELD_MODULUS || typeof record.treeId !== "bigint" || record.treeId < 1n || record.treeId >= 1n << 64n || !Number.isInteger(record.leafIndex) || record.leafIndex < 0 || record.leafIndex >= 65536 || typeof record.blockNumber !== "bigint" || record.blockNumber < 0n || !/^0x[0-9a-fA-F]{64}$/.test(record.blockHash))
+    if (!/^0x[0-9a-fA-F]{64}$/.test(record.commitment) || BigInt(record.commitment) <= 0n || BigInt(record.commitment) >= import_core3.FIELD_MODULUS || typeof record.treeId !== "bigint" || record.treeId < 1n || record.treeId >= 1n << 64n || !Number.isInteger(record.leafIndex) || record.leafIndex < 0 || record.leafIndex >= 65536 || typeof record.blockNumber !== "bigint" || record.blockNumber < 0n || !/^0x[0-9a-fA-F]{64}$/.test(record.blockHash))
       throw new Error("invalid stored receipt position");
   }
   for (const [id, operation] of Object.entries(state.reservations))
@@ -1035,14 +1036,11 @@ var MemoryAtomicRecords = class {
 };
 
 // src/session/operation-protocol.ts
-var import_core3 = require("@invisi-labs/core");
+var import_core4 = require("@invisi-labs/core");
 var import_protocol2 = require("@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) {
@@ -1306,7 +1304,7 @@ function operationExpired(plan, now) {
   if (credit?.creation && now >= credit.creation.expiry) return true;
   if (credit?.draw) {
     if (credit.draw.expiries.some((expiry) => now >= expiry)) return true;
-    const prepared = (0, import_core3.creditPeriods)(plan.preparedAt.timestamp), current2 = (0, import_core3.creditPeriods)(now);
+    const prepared = (0, import_core4.creditPeriods)(plan.preparedAt.timestamp), current2 = (0, import_core4.creditPeriods)(now);
     if (prepared.currentDay !== current2.currentDay || prepared.currentMonth !== current2.currentMonth)
       return true;
   }
@@ -2805,7 +2803,8 @@ function estimateGasReference(plan, protocol, profiles) {
 
 // src/session/operation-execution.ts
 var import_ethers6 = require("ethers");
-var import_core4 = require("@invisi-labs/core");
+var import_core5 = require("@invisi-labs/core");
+var import_protocol3 = require("@invisi-labs/protocol");
 
 // src/session/proof-integrity.ts
 var import_ethers5 = require("ethers");
@@ -2834,23 +2833,41 @@ async function authorizeOperation(plan, provider) {
   if (provider.walletIdentity !== plan.scope.walletIdentity)
     throw new Error("wallet authorization capability mismatch");
   const request = authorizationRequest(plan);
-  const digest = (0, import_core4.computeWalletAuthorizationDigest)(request);
+  const digest = (0, import_core5.computeWalletAuthorizationDigest)(request);
   const signed = await provider.authorize(structuredClone(request));
   if (signed.walletIdentity !== plan.scope.walletIdentity || signed.digest !== digest)
     throw new Error("wallet authorization statement mismatch");
   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 = import_protocol3.WitnessBuilder.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;
@@ -2865,19 +2882,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 (0, import_core5.createSigningRequest)((0, import_core5.walletAuthorizationTypedData)(authorizationRequest(plan)));
+}
+async function acceptWalletSignature(plan, signature) {
+  const request = authorizationRequest(plan);
+  const digest = (0, import_core5.computeWalletAuthorizationDigest)(request);
+  try {
+    const signed = import_ethers6.Signature.from(signature);
+    const publicKey = (0, import_ethers6.getBytes)(import_ethers6.SigningKey.recoverPublicKey(digest, signed));
+    const owner = await (0, import_core5.computeWalletIdentity)(publicKey);
+    if (owner.toLowerCase() !== plan.scope.walletIdentity.toLowerCase()) {
+      throw new Error("wallet signature identity mismatch");
+    }
+    return new import_core5.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((0, import_ethers6.getBytes)((0, import_ethers6.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 = (0, import_core5.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 = (0, import_ethers6.verifyTypedData)(request.domain, types, request.message, signature).toLowerCase() === payer.toLowerCase();
+    if (validEOA) {
+      signature = import_ethers6.Signature.from(signature).serialized;
+    }
+  } catch {
+    validEOA = false;
+  }
   const valid = verifier ? await verifier.verifyTypedData({
-    ...structuredClone(typed),
+    ...structuredClone(request),
     address: payer,
     signature
-  }) : (0, import_ethers6.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;
 }
 
@@ -2918,16 +3004,16 @@ function operationPreview(plan, status) {
 }
 
 // src/session/Operation.ts
-var import_core8 = require("@invisi-labs/core");
-var import_protocol4 = require("@invisi-labs/protocol");
+var import_core9 = require("@invisi-labs/core");
+var import_protocol5 = require("@invisi-labs/protocol");
 
 // src/session/operation-confirmation.ts
-var import_core7 = require("@invisi-labs/core");
+var import_core8 = require("@invisi-labs/core");
 
 // src/session/aggregate-receipt.ts
 var import_ethers7 = require("ethers");
 var import_contracts3 = require("@invisi-labs/protocol/contracts");
-var import_protocol3 = require("@invisi-labs/protocol");
+var import_protocol4 = require("@invisi-labs/protocol");
 var aggregateAbi = import_contracts3.invisiProtocolAbi.filter(
   (item) => item.type === "function" && item.name === "transact" && item.inputs.length === 2 && item.inputs[1]?.type === "tuple[]"
 );
@@ -2955,7 +3041,7 @@ function matchesAggregateTransaction(saved, transaction) {
     });
     if (decoded.name !== "transact" || !Array.isArray(requests) || ![4, 8, 12].includes(requests.length))
       return false;
-    const canonical2 = (request) => (0, import_protocol3.buildTransactCalldata)({
+    const canonical2 = (request) => (0, import_protocol4.buildTransactCalldata)({
       context: { ...plan.context, tokenAddress: request.params.token },
       proof: "0x00",
       params: request.params,
@@ -2963,7 +3049,7 @@ function matchesAggregateTransaction(saved, transaction) {
       funding: request.funding,
       caller: transaction.from
     }).data.toLowerCase();
-    const expected = (0, import_protocol3.buildTransactCalldata)({
+    const expected = (0, import_protocol4.buildTransactCalldata)({
       context: plan.context,
       proof: "0x00",
       params: plan.params,
@@ -2978,10 +3064,10 @@ function matchesAggregateTransaction(saved, transaction) {
 }
 
 // src/session/credit-values.ts
-var import_core5 = require("@invisi-labs/core");
+var import_core6 = require("@invisi-labs/core");
 async function creditLeaf(state) {
   const n = state.note;
-  return (0, import_core5.computeCreditCommitment)(
+  return (0, import_core6.computeCreditCommitment)(
     n.chainId,
     n.spenderWalletIdentity,
     n.ownerWalletIdentity,
@@ -2991,23 +3077,23 @@ async function creditLeaf(state) {
     n.amount,
     n.nonce,
     n.expiry,
-    await (0, import_core5.computeCreditSharedKeyHash)(n.creditSharedKey),
+    await (0, import_core6.computeCreditSharedKeyHash)(n.creditSharedKey),
     n
   );
 }
 
 // src/session/membership.ts
-var import_core6 = require("@invisi-labs/core");
+var import_core7 = require("@invisi-labs/core");
 async function verifyMembership(reader, context, block, input, proof) {
   if (proof.block.hash !== block.hash || proof.block.number !== block.number || proof.leaf !== input.commitment || proof.treeId !== input.treeId || proof.leafIndex !== input.leafIndex || proof.path.length !== 16 || !Number.isInteger(input.leafIndex) || input.leafIndex < 0 || input.leafIndex >= 65536 || !await reader.isKnownRoot(context, input.treeId, proof.root, block))
     throw new Error("membership context/root mismatch");
   let root = BigInt(input.commitment);
   for (let i = 0; i < 16; i++) {
     const sibling = proof.path[i];
-    if (typeof sibling !== "bigint" || sibling < 0n || sibling >= import_core6.FIELD_MODULUS)
+    if (typeof sibling !== "bigint" || sibling < 0n || sibling >= import_core7.FIELD_MODULUS)
       throw new Error("noncanonical membership path");
     root = BigInt(
-      await (0, import_core6.poseidonHash)(input.leafIndex >> i & 1 ? [sibling, root] : [root, sibling])
+      await (0, import_core7.poseidonHash)(input.leafIndex >> i & 1 ? [sibling, root] : [root, sibling])
     );
   }
   if (root !== BigInt(proof.root))
@@ -3179,7 +3265,7 @@ async function confirmOperation(runtime, id, generation, hash2, signal) {
   if (credits.length) {
     const nullifiers = await Promise.all(
       credits.map(
-        async (record) => (0, import_core7.computeCreditNullifier)(
+        async (record) => (0, import_core8.computeCreditNullifier)(
           plan.context.chainId,
           record.state.note.creditSharedKey,
           await creditLeaf(record.state)
@@ -3480,6 +3566,81 @@ var Operation = class _Operation {
       throw error;
     }
   }
+  async signingCurrent() {
+    await this.#runtime.store.transaction(this.#runtime.scope, (state) => {
+      check6(!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();
+    check6(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check6(
+      ["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();
+    check6(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check6(
+      ["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();
+    check6(
+      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();
+    check6(
+      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 = {}) {
     check6(
       requiresAuthorization(this.#saved.plan),
@@ -3500,7 +3661,8 @@ var Operation = class _Operation {
       options.signal
     );
   }
-  async prove(options = {}) {
+  async prove(suppliedOptions = {}) {
+    const options = { ...suppliedOptions };
     const plan = this.#saved.plan;
     check6(plan.kind !== "shield", "shield requires no proof");
     if (requiresAuthorization(plan)) {
@@ -3511,7 +3673,7 @@ var Operation = class _Operation {
     }
     const prover = this.#runtime.options.prover;
     if (!prover) {
-      throw new import_core8.MissingCapabilityError("prover");
+      throw new import_core9.MissingCapabilityError("prover");
     }
     return this.stage(
       "proof",
@@ -3545,7 +3707,7 @@ var Operation = class _Operation {
     check6(p.kind === "shield" || this.#saved.proof, "proof must precede funding authorization");
     const signer = this.#runtime.options.fundingSigner;
     if (!signer) {
-      throw new import_core8.MissingCapabilityError("EVM funding signer");
+      throw new import_core9.MissingCapabilityError("EVM funding signer");
     }
     check6(
       signer.address.toLowerCase() === p.funding.payer.toLowerCase(),
@@ -3647,7 +3809,7 @@ var Operation = class _Operation {
         request: {
           params: structuredClone(plan.params),
           deliveries: plan.outputs.map((output) => structuredClone(output.delivery)),
-          funding: (0, import_protocol4.normalizeFunding)(plan.funding)
+          funding: (0, import_protocol5.normalizeFunding)(plan.funding)
         }
       };
     });
@@ -3734,18 +3896,181 @@ var Operation = class _Operation {
   }
 };
 
+// src/session/WalletSession.ts
+var import_core16 = require("@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/errors.ts
+var import_core10 = require("@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 import_core10.MissingCapabilityError ? "MISSING_CAPABILITY" : "PREPARATION_FAILED",
+      cause instanceof Error ? cause.message : "Transaction preparation failed",
+      {
+        operation,
+        cause,
+        ...cause instanceof import_core10.MissingCapabilityError ? { capability: cause.capability } : {}
+      }
+    );
+  }
+}
+
 // src/session/WalletSession.ts
 var import_ethers11 = require("ethers");
-var import_core13 = require("@invisi-labs/core");
+var import_core17 = require("@invisi-labs/core");
 
 // src/session/transaction-preparation.ts
 var import_ethers10 = require("ethers");
-var import_protocol7 = require("@invisi-labs/protocol");
+var import_protocol8 = require("@invisi-labs/protocol");
+
+// src/resolve-recipient.ts
+var import_core11 = require("@invisi-labs/core");
+async function resolveRecipient(address2, lookup, details = {}) {
+  const context = { ...details, address: address2 };
+  let recipient;
+  try {
+    recipient = import_core11.ReceivingAddress.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 import_core11.MissingCapabilityError) {
+      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 import_core11.ReceivingAddress.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
 var import_ethers8 = require("ethers");
-var import_core9 = require("@invisi-labs/core");
-var import_protocol5 = require("@invisi-labs/protocol");
+var import_core12 = require("@invisi-labs/core");
+var import_protocol6 = require("@invisi-labs/protocol");
 
 // src/session/selection.ts
 function selectNotes(notes, target, reserved) {
@@ -3778,6 +4103,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;
@@ -3831,7 +4177,7 @@ var Preparation = class {
     if (mode === "caller" && (source.sigNonce || source.deadline)) {
       throw new Error("caller funding uses zero nonce/deadline");
     }
-    const funding = (0, import_protocol5.normalizeFunding)({
+    const funding = (0, import_protocol6.normalizeFunding)({
       payer,
       amount: source.amount,
       sigNonce: mode === "caller" ? 0n : source.sigNonce ?? await this.runtime.reader.getFundingNonce(
@@ -3847,52 +4193,70 @@ var Preparation = class {
     }
     return { funding, fundingMode: mode };
   }
-  async output(payment, context, change = false) {
-    positiveAmount(payment.amount);
-    const recipient = await import_core9.ReceivingAddress.parse(payment.to).resolve(
-      this.runtime.options.addressResolver
-    );
-    const memo = (0, import_core9.encodeMemo)(payment.memo);
-    const nonce = (0, import_core9.generateNonce)();
-    const identity = await (0, import_core9.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 (0, import_core9.computeNoteCommitment)(
-      context.chainId,
-      identity,
-      note.tokenAddress,
-      note.amount
-    );
-    return {
-      note,
-      commitment,
-      identity,
-      address: payment.to,
-      change,
-      delivery: {
-        ciphertext: (0, import_ethers8.hexlify)(
-          await (0, import_core9.encryptPrivateTransferNote)(keys.viewingPublicKey, note, {
-            chainId: context.chainId,
-            protocolAddress: note.protocolAddress,
-            outputCommitment: commitment
-          })
-        ),
-        clue: (0, import_ethers8.hexlify)((0, import_core9.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 = (0, import_core12.generateNonce)();
+      const identity = await (0, import_core12.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 (0, import_core12.computeNoteCommitment)(
+        context.chainId,
+        identity,
+        note.tokenAddress,
+        note.amount
+      );
+      return {
+        note,
+        commitment,
+        identity,
+        address: payment.to,
+        change,
+        delivery: {
+          ciphertext: (0, import_ethers8.hexlify)(
+            await (0, import_core12.encryptPrivateTransferNote)(keys.viewingPublicKey, note, {
+              chainId: context.chainId,
+              protocolAddress: note.protocolAddress,
+              outputCommitment: commitment
+            })
+          ),
+          clue: (0, import_ethers8.hexlify)((0, import_core12.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 import_core9.MissingCapabilityError("Protocol RPC membership provider");
+      throw new import_core12.MissingCapabilityError("Protocol RPC membership provider");
     const root = this.#roots.get(input.treeId);
     const proof = await options.protocolRpc.getMembership(
       frame.context,
@@ -3939,9 +4303,9 @@ var Preparation = class {
     for (const input of selected) {
       const note = input.note;
       const c = frame.context;
-      if (note.walletIdentity !== scope.walletIdentity || note.chainId !== c.chainId || note.protocolAddress !== BigInt(c.protocolAddress) || note.tokenAddress !== BigInt(c.tokenAddress) || await (0, import_core9.computeNoteCommitment)(
+      if (note.walletIdentity !== scope.walletIdentity || note.chainId !== c.chainId || note.protocolAddress !== BigInt(c.protocolAddress) || note.tokenAddress !== BigInt(c.tokenAddress) || await (0, import_core12.computeNoteCommitment)(
         c.chainId,
-        await (0, import_core9.computeNoteIdentity)(BigInt(note.walletIdentity), note.nonce),
+        await (0, import_core12.computeNoteIdentity)(BigInt(note.walletIdentity), note.nonce),
         note.tokenAddress,
         note.amount
       ) !== input.commitment) {
@@ -3993,8 +4357,8 @@ function storedCandidates(inputs) {
 
 // src/session/prepare-credit.ts
 var import_ethers9 = require("ethers");
-var import_core10 = require("@invisi-labs/core");
-var import_protocol6 = require("@invisi-labs/protocol");
+var import_core13 = require("@invisi-labs/core");
+var import_protocol7 = require("@invisi-labs/protocol");
 var EMPTY = { ciphertext: "0x", clue: "0x" };
 var CreditPreparation = class {
   constructor(runtime) {
@@ -4009,7 +4373,7 @@ var CreditPreparation = class {
     return value;
   }
   async seal(input, frame) {
-    const state = (0, import_core10.normalizeCreditDeliveryState)(input);
+    const state = (0, import_core13.normalizeCreditDeliveryState)(input);
     const commitment = await creditLeaf(state);
     const context = {
       chainId: frame.context.chainId,
@@ -4021,9 +4385,9 @@ var CreditPreparation = class {
         const keys = role === "owner" ? state.ownerReceivingKeys : state.spenderReceivingKeys;
         return {
           ciphertext: (0, import_ethers9.hexlify)(
-            await (0, import_core10.encryptCreditNote)(keys.viewingPublicKey, state, { ...context, role })
+            await (0, import_core13.encryptCreditNote)(keys.viewingPublicKey, state, { ...context, role })
           ),
-          clue: (0, import_ethers9.hexlify)((0, import_core10.createClue)(keys.clueKey))
+          clue: (0, import_ethers9.hexlify)((0, import_core13.createClue)(keys.clueKey))
         };
       })
     );
@@ -4034,14 +4398,14 @@ var CreditPreparation = class {
     if (!stored || stored.spent !== "unspent" || stored.role !== role) {
       throw new Error(`confirmed unspent ${role} Credit is unavailable`);
     }
-    const state = (0, import_core10.normalizeCreditDeliveryState)(stored.state);
+    const state = (0, import_core13.normalizeCreditDeliveryState)(stored.state);
     const n = state.note;
     if ((role === "owner" ? n.ownerWalletIdentity : n.spenderWalletIdentity) !== this.runtime.scope.walletIdentity || n.chainId !== frame.context.chainId || n.protocolAddress !== BigInt(frame.context.protocolAddress) || n.tokenAddress !== BigInt(frame.context.tokenAddress) || await creditLeaf(state) !== commitment) {
       throw new Error("Credit role, commitment or deployment mismatch");
     }
     const proof = await this.#prepare.membership(stored, frame);
     const path = [...proof.path];
-    const nullifier = await (0, import_core10.computeCreditNullifier)(n.chainId, n.creditSharedKey, commitment);
+    const nullifier = await (0, import_core13.computeCreditNullifier)(n.chainId, n.creditSharedKey, commitment);
     await this.#prepare.assertUnspent([nullifier], frame);
     return {
       input: {
@@ -4078,10 +4442,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 import_core10.ReceivingAddress.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 = (0, import_ethers9.getAddress)(owner.walletIdentity);
     const spenderPayout = (0, import_ethers9.getAddress)(spender.walletIdentity);
     if (BigInt(ownerPayout) === 0n || BigInt(spenderPayout) === 0n) {
@@ -4097,16 +4467,16 @@ var CreditPreparation = class {
           spenderWalletIdentity: spender.walletIdentity,
           ownerPayout: BigInt(ownerPayout),
           spenderPayout: BigInt(spenderPayout),
-          ...(0, import_core10.normalizeCreditPolicy)({
+          ...(0, import_core13.normalizeCreditPolicy)({
             singleLimit: options.singleLimit ?? 0n,
             dailyLimit: options.dailyLimit ?? 0n,
             monthlyLimit: options.monthlyLimit ?? 0n
           }),
           amount: options.amount,
-          ...options.memo === void 0 ? {} : { memo: options.memo },
+          payload: copyApplicationPayload(options.payload),
           expiry,
-          nonce: (0, import_core10.generateNonce)(),
-          creditSharedKey: (0, import_core10.generateCreditSharedKey)()
+          nonce: (0, import_core13.generateNonce)(),
+          creditSharedKey: (0, import_core13.generateCreditSharedKey)()
         },
         ownerReceivingKeys: owner.getReceivingKeys(),
         spenderReceivingKeys: spender.getReceivingKeys()
@@ -4148,7 +4518,7 @@ var CreditPreparation = class {
       sources: selected.sources,
       nullifiers: selected.nullifiers,
       creditCommitment: output.commitment,
-      changeCommitment: plan.outputs[0]?.commitment ?? (0, import_protocol6.word)(0n),
+      changeCommitment: plan.outputs[0]?.commitment ?? (0, import_protocol7.word)(0n),
       owner: (0, import_ethers9.getAddress)((0, import_ethers9.toBeHex)(output.state.note.ownerPayout, 20)),
       expiry: output.state.note.expiry,
       deadline: frame.deadline
@@ -4168,14 +4538,14 @@ var CreditPreparation = class {
         creditNullifier: previous.nullifier,
         previousExpiry: previous.input.state.note.expiry
       };
-      plan.statement = import_protocol6.WitnessBuilder.statement(
+      plan.statement = import_protocol7.WitnessBuilder.statement(
         "credit_top_up",
-        (0, import_protocol6.topUpCreditPublicInputs)(frame.context, plan.credit.topUp, deliveries, plan.funding)
+        (0, import_protocol7.topUpCreditPublicInputs)(frame.context, plan.credit.topUp, deliveries, plan.funding)
       );
     } else {
-      plan.statement = import_protocol6.WitnessBuilder.statement(
+      plan.statement = import_protocol7.WitnessBuilder.statement(
         "create_credit",
-        (0, import_protocol6.createCreditPublicInputs)(frame.context, creation, deliveries, plan.funding)
+        (0, import_protocol7.createCreditPublicInputs)(frame.context, creation, deliveries, plan.funding)
       );
     }
     await this.#prepare.assertBlock(frame);
@@ -4204,8 +4574,10 @@ var CreditPreparation = class {
           monthlyLimit: options.monthlyLimit ?? old.note.monthlyLimit ?? 0n,
           amount,
           expiry,
-          nonce: (0, import_core10.generateNonce)(),
-          ...options.memo === void 0 ? {} : { memo: options.memo }
+          nonce: (0, import_core13.generateNonce)(),
+          payload: copyApplicationPayload(
+            options.payload === void 0 ? old.note.payload : options.payload
+          )
         }
       },
       frame
@@ -4221,7 +4593,7 @@ var CreditPreparation = class {
   }
   async draw(options) {
     const frame = await this.#prepare.frame(options.deadline);
-    const profile = (0, import_protocol6.selectCreditDrawCircuit)(options.credits.length);
+    const profile = (0, import_protocol7.selectCreditDrawCircuit)(options.credits.length);
     if (new Set(options.credits.map((value) => value.credit)).size !== options.credits.length) {
       throw new Error("duplicate Credit input");
     }
@@ -4253,11 +4625,11 @@ var CreditPreparation = class {
       }
       sources.set(member.source.treeId, member.source.merkleRoot);
       amounts.push(amount);
-      const usage = (0, import_core10.applyCreditDrawUsage)(n, amount, frame.block.timestamp);
+      const usage = (0, import_core13.applyCreditDrawUsage)(n, amount, frame.block.timestamp);
       const remaining = n.amount - amount;
       if (remaining === 0n) {
-        remainders.push((0, import_protocol6.word)(0n));
-        recoveryAmounts.push((0, import_protocol6.word)(0n));
+        remainders.push((0, import_protocol7.word)(0n));
+        recoveryAmounts.push((0, import_protocol7.word)(0n));
         deliveries.push({ ...EMPTY }, { ...EMPTY });
         continue;
       }
@@ -4275,8 +4647,10 @@ var CreditPreparation = class {
             ...n,
             ...usage,
             amount: remaining,
-            ...options.credits[i].memo === void 0 ? {} : { memo: options.credits[i].memo },
-            nonce: await (0, import_core10.deriveRemainderNonce)(...args)
+            payload: copyApplicationPayload(
+              options.credits[i].payload === void 0 ? n.payload : options.credits[i].payload
+            ),
+            nonce: await (0, import_core13.deriveRemainderNonce)(...args)
           }
         },
         frame
@@ -4284,7 +4658,7 @@ var CreditPreparation = class {
       outputs.push(output);
       remainders.push(output.commitment);
       recoveryAmounts.push(
-        (0, import_protocol6.word)((remaining + await (0, import_core10.computeCreditRecoveryPad)(...args)) % import_core10.FIELD_MODULUS)
+        (0, import_protocol7.word)((remaining + await (0, import_core13.computeCreditRecoveryPad)(...args)) % import_core13.FIELD_MODULUS)
       );
       deliveries.push(...output.deliveries);
     }
@@ -4308,9 +4682,9 @@ var CreditPreparation = class {
       draw: params,
       amounts
     };
-    plan.statement = import_protocol6.WitnessBuilder.statement(
+    plan.statement = import_protocol7.WitnessBuilder.statement(
       profile.name,
-      (0, import_protocol6.creditDrawPublicInputs)(frame.context, params, deliveries)
+      (0, import_protocol7.creditDrawPublicInputs)(frame.context, params, deliveries)
     );
     await this.#prepare.assertBlock(frame);
     return this.runtime.complete(plan);
@@ -4330,9 +4704,9 @@ var CreditPreparation = class {
     };
     plan.capacity = 1;
     plan.credit = { inputs: [previous.input], outputs: [], deliveries: [], cancel: params };
-    plan.statement = import_protocol6.WitnessBuilder.statement(
+    plan.statement = import_protocol7.WitnessBuilder.statement(
       "credit_cancel",
-      (0, import_protocol6.cancelCreditPublicInputs)(frame.context, params)
+      (0, import_protocol7.cancelCreditPublicInputs)(frame.context, params)
     );
     await this.#prepare.assertBlock(frame);
     return this.runtime.complete(plan);
@@ -4353,87 +4727,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 = import_protocol8.ZERO_ADDRESS;
+    let withdrawalAmount = 0n;
+    if (copied.withdrawal !== void 0) {
+      withdrawalAddress = (0, import_ethers10.getAddress)(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,
-      import_protocol7.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 = (0, import_ethers10.getAddress)(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");
     }
@@ -4443,7 +4778,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) {
@@ -4468,17 +4803,17 @@ var TransactionPreparation = class {
       deadline
     };
     const deliveries = outputs.map((output) => output.delivery);
-    const normalized = (0, import_protocol7.normalizeTransactRequest)(context, params, deliveries, funding.funding);
-    const statement2 = import_protocol7.WitnessBuilder.statement(
+    const normalized = (0, import_protocol8.normalizeTransactRequest)(context, params, deliveries, funding.funding);
+    const statement2 = import_protocol8.WitnessBuilder.statement(
       `transact_user_slots${normalized.capacity}`,
-      (0, import_protocol7.transactUserPublicInputs)(context, params, deliveries, funding.funding),
-      target ?? "evm"
+      (0, import_protocol8.transactUserPublicInputs)(context, params, deliveries, funding.funding),
+      "evm"
     );
     await preparation.assertBlock(frame);
     return preparation.runtime.complete({
       version: 1,
       id: crypto.randomUUID(),
-      kind,
+      kind: "transfer",
       context,
       scope: this.scope,
       preparedAt: block,
@@ -4500,7 +4835,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");
@@ -4605,10 +4942,10 @@ async function refreshWallet(runtime, options) {
 }
 
 // src/session/WalletUpdater.ts
-var import_core12 = require("@invisi-labs/core");
+var import_core15 = require("@invisi-labs/core");
 
 // src/session/inventory.ts
-var import_core11 = require("@invisi-labs/core");
+var import_core14 = require("@invisi-labs/core");
 var CanonicalConflict = class extends Error {
 };
 var CreditMetadataMismatch = class extends Error {
@@ -4660,10 +4997,10 @@ var InventoryProcessor = class {
   }
   async creditNullifier(state) {
     const n = state.note;
-    return (0, import_core11.computeCreditNullifier)(
+    return (0, import_core14.computeCreditNullifier)(
       n.chainId,
       n.creditSharedKey,
-      await (0, import_core11.computeCreditCommitment)(
+      await (0, import_core14.computeCreditCommitment)(
         n.chainId,
         n.spenderWalletIdentity,
         n.ownerWalletIdentity,
@@ -4673,7 +5010,7 @@ var InventoryProcessor = class {
         n.amount,
         n.nonce,
         n.expiry,
-        await (0, import_core11.computeCreditSharedKeyHash)(n.creditSharedKey),
+        await (0, import_core14.computeCreditSharedKeyHash)(n.creditSharedKey),
         n
       )
     );
@@ -4737,7 +5074,7 @@ var InventoryProcessor = class {
               previous.state.note.expiry === params.expiries[index2],
               "draw recovery expiry mismatch"
             );
-            const remainder = await (0, import_core11.recoverCreditRemainder)(
+            const remainder = await (0, import_core14.recoverCreditRemainder)(
               context,
               previous.state.note,
               {
@@ -4753,7 +5090,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),
@@ -4766,7 +5103,7 @@ var InventoryProcessor = class {
                 ...clone(previous.state),
                 note: {
                   ...remainder,
-                  ...memo === void 0 ? {} : { memo: (0, import_core11.encodeMemo)(memo) }
+                  ...payload === void 0 ? {} : { payload: clone(payload) }
                 }
               },
               receivingKeySource: { kind: "draw", commitment: previous.commitment },
@@ -4845,7 +5182,7 @@ var WalletUpdater = class extends InventoryProcessor {
   }
   async run(batch, options) {
     const { reader, protocol, scope, store, viewing } = this.#options;
-    const nullifier = import_core12.NullifierCapability.fromIdentity(scope.walletIdentity);
+    const nullifier = import_core15.NullifierCapability.fromIdentity(scope.walletIdentity);
     const { signal, reset } = options;
     signal?.throwIfAborted();
     const context = protocol.context;
@@ -5014,6 +5351,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 });
@@ -5045,13 +5383,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;
@@ -5066,7 +5429,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 import_core13.MissingCapabilityError("ethers signer");
+    if (!signer) throw new import_core17.MissingCapabilityError("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");
@@ -5074,12 +5437,12 @@ var WalletSession = class {
     const overrides = { ...options };
     const plain = operation ? void 0 : { ...input };
     try {
-      if (!signer.provider) throw new import_core13.MissingCapabilityError("connected ethers signer");
+      if (!signer.provider) throw new import_core17.MissingCapabilityError("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 import_core13.MissingCapabilityError("wallet store");
+        if (!this.#options.store) throw new import_core17.MissingCapabilityError("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");
@@ -5110,25 +5473,30 @@ var WalletSession = class {
   runtime(tokenAddress) {
     const options = this.#options;
     if (!options.store) {
-      throw new import_core13.MissingCapabilityError("wallet store");
+      throw new import_core17.MissingCapabilityError("wallet store");
     }
     if (!options.chainReader) {
-      throw new import_core13.MissingCapabilityError("chain reader");
+      throw new import_core17.MissingCapabilityError("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 import_core16.Wallet) return options.wallet.exportAuthorization();
+        throw new import_core17.MissingCapabilityError("wallet authorization");
+      }
     };
   }
   updater() {
     if (this.#updater) return this.#updater;
     const options = this.#options;
     if (!options.store || !options.chainReader || !options.protocolRpc)
-      throw new import_core13.MissingCapabilityError("wallet store, chain reader and Protocol RPC");
-    const viewing = options.viewing ?? options.wallet.getViewer();
+      throw new import_core17.MissingCapabilityError("wallet store, chain reader and Protocol RPC");
+    const viewing = options.viewing ?? (options.wallet instanceof import_core16.Wallet ? options.wallet.getViewer() : void 0);
+    if (!viewing) throw new import_core17.MissingCapabilityError("viewing");
     const receivingAddress = options.wallet.getReceivingAddress();
     const receivingKeys = receivingAddress.kind === "long" ? receivingAddress.getReceivingKeys() : void 0;
     this.#updater = new WalletUpdater({
@@ -5142,10 +5510,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 ? (0, import_ethers11.getAddress)(options.tokenAddress) : void 0;
+    const store = this.#options.store;
+    if (!store) throw new import_core17.MissingCapabilityError("wallet store");
+    return walletHistory(
+      await store.readSnapshot(this.scope),
+      tokenAddress ? { tokenAddress } : {}
+    );
+  }
   async balance(tokenAddress) {
     const store = this.#options.store;
     if (!store) {
-      throw new import_core13.MissingCapabilityError("wallet store");
+      throw new import_core17.MissingCapabilityError("wallet store");
     }
     return walletBalance(await store.readSnapshot(this.scope), (0, import_ethers11.getAddress)(tokenAddress));
   }
@@ -5153,15 +5538,15 @@ var WalletSession = class {
   async refresh(options) {
     const provider = this.#options.protocolRpc;
     const reader = this.#options.chainReader;
-    if (!reader) throw new import_core13.MissingCapabilityError("chain reader");
-    if (!provider) throw new import_core13.MissingCapabilityError("Protocol RPC");
+    if (!reader) throw new import_core17.MissingCapabilityError("chain reader");
+    if (!provider) throw new import_core17.MissingCapabilityError("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,
@@ -5170,8 +5555,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;
@@ -5182,38 +5580,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 import_core13.MissingCapabilityError("wallet store");
+    if (!store) throw new import_core17.MissingCapabilityError("wallet store");
     const state = await store.readSnapshot(this.scope);
     const saved = state.operations[operationId]?.payload;
     if (!saved?.plan) throw new Error("operation not found");