@invisi-labs/sdk 1.1.3 → 1.1.4

package/dist/index.cjs

@@ -21,33 +21,89 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AddressRegistry: () => AddressRegistry,
-  Detector: () => import_core16.Detector,
-  Disclosure: () => import_core16.Disclosure,
+  Detector: () => import_core20.Detector,
+  Disclosure: () => import_core20.Disclosure,
   DisclosureVerifier: () => DisclosureVerifier,
   EncryptedWalletCodec: () => EncryptedWalletCodec,
   Invisi: () => Invisi,
-  MAX_MEMO_BYTES: () => import_core16.MAX_MEMO_BYTES,
-  MissingCapabilityError: () => import_core16.MissingCapabilityError,
-  NullifierCapability: () => import_core16.NullifierCapability,
+  InvisiError: () => InvisiError,
+  MAX_MEMO_BYTES: () => import_core20.MAX_MEMO_BYTES,
+  MissingCapabilityError: () => import_core20.MissingCapabilityError,
+  NullifierCapability: () => import_core20.NullifierCapability,
   Operation: () => Operation,
   PreparedTransaction: () => PreparedTransaction,
-  Protocol: () => import_protocol10.Protocol,
+  Protocol: () => import_protocol11.Protocol,
   ProtocolRpcClient: () => ProtocolRpcClient2,
   ProtocolRpcError: () => import_rpc3.ProtocolRpcError,
-  RegistrationOperation: () => import_protocol10.RegistrationOperation,
-  ViewingCapability: () => import_core16.ViewingCapability,
-  Wallet: () => import_core16.Wallet,
-  WalletAuthorization: () => import_core16.WalletAuthorization,
+  PublicWallet: () => import_core20.PublicWallet,
+  RegistrationOperation: () => import_protocol11.RegistrationOperation,
+  ViewingCapability: () => import_core20.ViewingCapability,
+  Wallet: () => import_core20.Wallet,
+  WalletAuthorization: () => import_core20.WalletAuthorization,
   WalletSession: () => WalletSession,
-  decodeMemoText: () => import_core16.decodeMemoText,
+  computeCreditNullifier: () => import_core20.computeCreditNullifier,
+  creditPeriods: () => import_core20.creditPeriods,
+  creditV1: () => import_core20.creditV1,
+  decodeDeliveryHeader: () => import_core20.decodeDeliveryHeader,
+  decodeMemoText: () => import_core20.decodeMemoText,
+  decryptCandidates: () => decryptCandidates,
   defineGasBenchmarks: () => defineGasBenchmarks,
-  encodeMemo: () => import_core16.encodeMemo,
+  encodeMemo: () => import_core20.encodeMemo,
+  fundsV1: () => import_core20.fundsV1,
+  readProtocolLogs: () => readProtocolLogs,
   walletBalance: () => walletBalance
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/session/operation-protocol.ts
+// src/errors.ts
 var import_core = 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_core.MissingCapabilityError ? "MISSING_CAPABILITY" : "PREPARATION_FAILED",
+      cause instanceof Error ? cause.message : "Transaction preparation failed",
+      {
+        operation,
+        cause,
+        ...cause instanceof import_core.MissingCapabilityError ? { capability: cause.capability } : {}
+      }
+    );
+  }
+}
+
+// src/session/operation-protocol.ts
+var import_core2 = require("@invisi-labs/core");
 var import_protocol = require("@invisi-labs/protocol");
 
 // src/session/state.ts
@@ -106,11 +162,8 @@ function walletBalances(state) {
 
 // src/session/operation-protocol.ts
 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) {
@@ -374,7 +427,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_core.creditPeriods)(plan.preparedAt.timestamp), current2 = (0, import_core.creditPeriods)(now);
+    const prepared = (0, import_core2.creditPeriods)(plan.preparedAt.timestamp), current2 = (0, import_core2.creditPeriods)(now);
     if (prepared.currentDay !== current2.currentDay || prepared.currentMonth !== current2.currentMonth)
       return true;
   }
@@ -1876,7 +1929,8 @@ var import_ethers6 = require("ethers");
 
 // src/session/operation-execution.ts
 var import_ethers2 = require("ethers");
-var import_core2 = require("@invisi-labs/core");
+var import_core3 = require("@invisi-labs/core");
+var import_protocol2 = require("@invisi-labs/protocol");
 
 // src/session/proof-integrity.ts
 var import_ethers = require("ethers");
@@ -1905,23 +1959,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_core2.computeWalletAuthorizationDigest)(request);
+  const digest = (0, import_core3.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_protocol2.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;
@@ -1936,25 +2008,94 @@ 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_core3.createSigningRequest)((0, import_core3.walletAuthorizationTypedData)(authorizationRequest(plan)));
+}
+async function acceptWalletSignature(plan, signature) {
+  const request = authorizationRequest(plan);
+  const digest = (0, import_core3.computeWalletAuthorizationDigest)(request);
+  try {
+    const signed = import_ethers2.Signature.from(signature);
+    const publicKey = (0, import_ethers2.getBytes)(import_ethers2.SigningKey.recoverPublicKey(digest, signed));
+    const owner = await (0, import_core3.computeWalletIdentity)(publicKey);
+    if (owner.toLowerCase() !== plan.scope.walletIdentity.toLowerCase()) {
+      throw new Error("wallet signature identity mismatch");
+    }
+    return new import_core3.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_ethers2.getBytes)((0, import_ethers2.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_core3.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_ethers2.verifyTypedData)(request.domain, types, request.message, signature).toLowerCase() === payer.toLowerCase();
+    if (validEOA) {
+      signature = import_ethers2.Signature.from(signature).serialized;
+    }
+  } catch {
+    validEOA = false;
+  }
   const valid = verifier ? await verifier.verifyTypedData({
-    ...structuredClone(typed),
+    ...structuredClone(request),
     address: payer,
     signature
-  }) : (0, import_ethers2.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;
 }
 
 // src/PreparedTransaction.ts
-var import_core3 = require("@invisi-labs/core");
-var import_protocol2 = require("@invisi-labs/protocol");
+var import_core4 = require("@invisi-labs/core");
+var import_protocol3 = require("@invisi-labs/protocol");
 
 // src/session/operation-preview.ts
 function operationPreview(plan, status) {
@@ -2062,30 +2203,77 @@ var PreparedTransaction = class _PreparedTransaction {
       this.#lifecycle.busy = false;
     }
   }
-  async authorize(providerOrOptions = {}, suppliedOptions = {}) {
-    const options = "authorize" in providerOrOptions ? suppliedOptions : providerOrOptions;
-    const provider = "authorize" in providerOrOptions ? providerOrOptions : this.#runtime.authorization();
+  /** Public EIP-712 request; signing transport and key custody belong to the caller. */
+  async exportWalletAuthorization(options = {}) {
+    options.signal?.throwIfAborted();
+    this.current();
     check2(
       requiresAuthorization(this.#saved.plan),
       "operation does not require wallet authorization"
     );
-    const selectedProvider = provider;
     check2(
-      provider.walletIdentity === this.#runtime.scope.walletIdentity,
-      "wallet authorization capability mismatch"
+      ["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();
+    this.current();
+    check2(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check2(
+      ["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();
+    this.current();
+    check2(
+      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();
+    this.current();
+    return request;
+  }
+  /** Verify an external signature against this handle's own frozen operation. */
+  async withFundingSignature(signature, options = {}) {
+    options.signal?.throwIfAborted();
+    this.current();
+    check2(
+      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) => {
-        const authorization = await authorizeOperation(saved.plan, selectedProvider);
-        return { status: "authorized", authorization };
+        saved.plan.funding.signature = verified;
+        if (saved.plan.statement?.target !== "noir-recursive") {
+          saved.call = await this.encode(saved);
+        }
+        return { status: "ready" };
       },
       options.signal
     );
   }
   async prove(backendOrOptions = {}, suppliedOptions = {}) {
-    const options = "prove" in backendOrOptions ? suppliedOptions : backendOrOptions;
+    const options = { ..."prove" in backendOrOptions ? suppliedOptions : backendOrOptions };
     const plan = this.#saved.plan;
     check2(plan.kind !== "shield", "shield requires no proof");
     if (requiresAuthorization(plan)) {
@@ -2096,7 +2284,7 @@ var PreparedTransaction = class _PreparedTransaction {
     }
     const prover = "prove" in backendOrOptions ? backendOrOptions : this.#runtime.options.prover;
     if (!prover) {
-      throw new import_core3.MissingCapabilityError("prover");
+      throw new import_core4.MissingCapabilityError("prover");
     }
     return this.stage(
       "proof",
@@ -2124,37 +2312,6 @@ var PreparedTransaction = class _PreparedTransaction {
   encode(saved) {
     return encodeOperation(saved);
   }
-  async authorizeFunding(signerOrOptions = {}, suppliedOptions = {}) {
-    const options = "signTypedData" in signerOrOptions ? suppliedOptions : signerOrOptions;
-    const suppliedSigner = "signTypedData" in signerOrOptions ? signerOrOptions : void 0;
-    const p = this.#saved.plan;
-    check2(p.fundingMode === "signature", "operation does not require a funding signature");
-    check2(p.kind === "shield" || this.#saved.proof, "proof must precede funding authorization");
-    const signer = suppliedSigner ?? this.#runtime.options.fundingSigner;
-    if (!signer) {
-      throw new import_core3.MissingCapabilityError("EVM funding signer");
-    }
-    check2(
-      signer.address.toLowerCase() === p.funding.payer.toLowerCase(),
-      "funding signer is not the payer"
-    );
-    return this.stage(
-      "funding authorization",
-      p.kind === "shield" ? ["prepared"] : ["proved"],
-      async (saved) => {
-        saved.plan.funding.signature = await signOperationFunding(
-          saved,
-          signer,
-          this.#runtime.options.fundingVerifier
-        );
-        if (saved.plan.statement?.target !== "noir-recursive") {
-          saved.call = await this.encode(saved);
-        }
-        return { status: "ready" };
-      },
-      options.signal
-    );
-  }
   /** Shield caller funding needs no wallet signing or proof; this step only encodes its frozen request. */
   async ready() {
     check2(
@@ -2199,7 +2356,7 @@ var PreparedTransaction = class _PreparedTransaction {
       request: {
         params: structuredClone(plan.params),
         deliveries: plan.outputs.map((output) => structuredClone(output.delivery)),
-        funding: (0, import_protocol2.normalizeFunding)(plan.funding)
+        funding: (0, import_protocol3.normalizeFunding)(plan.funding)
       }
     };
   }
@@ -2211,23 +2368,81 @@ var PreparedTransaction = class _PreparedTransaction {
   }
 };
 
+// src/resolve-recipient.ts
+var import_core5 = require("@invisi-labs/core");
+async function resolveRecipient(address2, lookup, details = {}) {
+  const context = { ...details, address: address2 };
+  let recipient;
+  try {
+    recipient = import_core5.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_core5.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_core5.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_ethers3 = require("ethers");
-var import_core5 = require("@invisi-labs/core");
-var import_protocol3 = require("@invisi-labs/protocol");
+var import_core7 = require("@invisi-labs/core");
+var import_protocol4 = require("@invisi-labs/protocol");
 
 // src/session/membership.ts
-var import_core4 = require("@invisi-labs/core");
+var import_core6 = 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_core4.FIELD_MODULUS)
+    if (typeof sibling !== "bigint" || sibling < 0n || sibling >= import_core6.FIELD_MODULUS)
       throw new Error("noncanonical membership path");
     root = BigInt(
-      await (0, import_core4.poseidonHash)(input.leafIndex >> i & 1 ? [sibling, root] : [root, sibling])
+      await (0, import_core6.poseidonHash)(input.leafIndex >> i & 1 ? [sibling, root] : [root, sibling])
     );
   }
   if (root !== BigInt(proof.root))
@@ -2265,6 +2480,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;
@@ -2318,7 +2554,7 @@ var Preparation = class {
     if (mode === "caller" && (source.sigNonce || source.deadline)) {
       throw new Error("caller funding uses zero nonce/deadline");
     }
-    const funding = (0, import_protocol3.normalizeFunding)({
+    const funding = (0, import_protocol4.normalizeFunding)({
       payer,
       amount: source.amount,
       sigNonce: mode === "caller" ? 0n : source.sigNonce ?? await this.runtime.reader.getFundingNonce(
@@ -2334,52 +2570,70 @@ var Preparation = class {
     }
     return { funding, fundingMode: mode };
   }
-  async output(payment, context, change = false) {
-    positiveAmount(payment.amount);
-    const recipient = await import_core5.ReceivingAddress.parse(payment.to).resolve(
-      this.runtime.options.addressResolver
-    );
-    const memo = (0, import_core5.encodeMemo)(payment.memo);
-    const nonce = (0, import_core5.generateNonce)();
-    const identity = await (0, import_core5.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_core5.computeNoteCommitment)(
-      context.chainId,
-      identity,
-      note.tokenAddress,
-      note.amount
-    );
-    return {
-      note,
-      commitment,
-      identity,
-      address: payment.to,
-      change,
-      delivery: {
-        ciphertext: (0, import_ethers3.hexlify)(
-          await (0, import_core5.encryptPrivateTransferNote)(keys.viewingPublicKey, note, {
-            chainId: context.chainId,
-            protocolAddress: note.protocolAddress,
-            outputCommitment: commitment
-          })
-        ),
-        clue: (0, import_ethers3.hexlify)((0, import_core5.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_core7.generateNonce)();
+      const identity = await (0, import_core7.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_core7.computeNoteCommitment)(
+        context.chainId,
+        identity,
+        note.tokenAddress,
+        note.amount
+      );
+      return {
+        note,
+        commitment,
+        identity,
+        address: payment.to,
+        change,
+        delivery: {
+          ciphertext: (0, import_ethers3.hexlify)(
+            await (0, import_core7.encryptPrivateTransferNote)(keys.viewingPublicKey, note, {
+              chainId: context.chainId,
+              protocolAddress: note.protocolAddress,
+              outputCommitment: commitment
+            })
+          ),
+          clue: (0, import_ethers3.hexlify)((0, import_core7.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_core5.MissingCapabilityError("Protocol RPC membership provider");
+      throw new import_core7.MissingCapabilityError("Protocol RPC membership provider");
     const root = this.#roots.get(input.treeId);
     const proof = await options.protocolRpc.getMembership(
       frame.context,
@@ -2426,9 +2680,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_core5.computeNoteCommitment)(
+      if (note.walletIdentity !== scope.walletIdentity || note.chainId !== c.chainId || note.protocolAddress !== BigInt(c.protocolAddress) || note.tokenAddress !== BigInt(c.tokenAddress) || await (0, import_core7.computeNoteCommitment)(
         c.chainId,
-        await (0, import_core5.computeNoteIdentity)(BigInt(note.walletIdentity), note.nonce),
+        await (0, import_core7.computeNoteIdentity)(BigInt(note.walletIdentity), note.nonce),
         note.tokenAddress,
         note.amount
       ) !== input.commitment) {
@@ -2480,18 +2734,18 @@ function storedCandidates(inputs) {
 
 // src/session/transaction-preparation.ts
 var import_ethers5 = require("ethers");
-var import_protocol5 = require("@invisi-labs/protocol");
+var import_protocol6 = require("@invisi-labs/protocol");
 
 // src/session/prepare-credit.ts
 var import_ethers4 = require("ethers");
-var import_core7 = 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/credit-values.ts
-var import_core6 = require("@invisi-labs/core");
+var import_core8 = require("@invisi-labs/core");
 async function creditLeaf(state) {
   const n = state.note;
-  return (0, import_core6.computeCreditCommitment)(
+  return (0, import_core8.computeCreditCommitment)(
     n.chainId,
     n.spenderWalletIdentity,
     n.ownerWalletIdentity,
@@ -2501,7 +2755,7 @@ async function creditLeaf(state) {
     n.amount,
     n.nonce,
     n.expiry,
-    await (0, import_core6.computeCreditSharedKeyHash)(n.creditSharedKey),
+    await (0, import_core8.computeCreditSharedKeyHash)(n.creditSharedKey),
     n
   );
 }
@@ -2521,7 +2775,7 @@ var CreditPreparation = class {
     return value;
   }
   async seal(input, frame) {
-    const state = (0, import_core7.normalizeCreditDeliveryState)(input);
+    const state = (0, import_core9.normalizeCreditDeliveryState)(input);
     const commitment = await creditLeaf(state);
     const context = {
       chainId: frame.context.chainId,
@@ -2533,9 +2787,9 @@ var CreditPreparation = class {
         const keys = role === "owner" ? state.ownerReceivingKeys : state.spenderReceivingKeys;
         return {
           ciphertext: (0, import_ethers4.hexlify)(
-            await (0, import_core7.encryptCreditNote)(keys.viewingPublicKey, state, { ...context, role })
+            await (0, import_core9.encryptCreditNote)(keys.viewingPublicKey, state, { ...context, role })
           ),
-          clue: (0, import_ethers4.hexlify)((0, import_core7.createClue)(keys.clueKey))
+          clue: (0, import_ethers4.hexlify)((0, import_core9.createClue)(keys.clueKey))
         };
       })
     );
@@ -2546,14 +2800,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_core7.normalizeCreditDeliveryState)(stored.state);
+    const state = (0, import_core9.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_core7.computeCreditNullifier)(n.chainId, n.creditSharedKey, commitment);
+    const nullifier = await (0, import_core9.computeCreditNullifier)(n.chainId, n.creditSharedKey, commitment);
     await this.#prepare.assertUnspent([nullifier], frame);
     return {
       input: {
@@ -2590,10 +2844,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_core7.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_ethers4.getAddress)(owner.walletIdentity);
     const spenderPayout = (0, import_ethers4.getAddress)(spender.walletIdentity);
     if (BigInt(ownerPayout) === 0n || BigInt(spenderPayout) === 0n) {
@@ -2609,16 +2869,16 @@ var CreditPreparation = class {
           spenderWalletIdentity: spender.walletIdentity,
           ownerPayout: BigInt(ownerPayout),
           spenderPayout: BigInt(spenderPayout),
-          ...(0, import_core7.normalizeCreditPolicy)({
+          ...(0, import_core9.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_core7.generateNonce)(),
-          creditSharedKey: (0, import_core7.generateCreditSharedKey)()
+          nonce: (0, import_core9.generateNonce)(),
+          creditSharedKey: (0, import_core9.generateCreditSharedKey)()
         },
         ownerReceivingKeys: owner.getReceivingKeys(),
         spenderReceivingKeys: spender.getReceivingKeys()
@@ -2660,7 +2920,7 @@ var CreditPreparation = class {
       sources: selected.sources,
       nullifiers: selected.nullifiers,
       creditCommitment: output.commitment,
-      changeCommitment: plan.outputs[0]?.commitment ?? (0, import_protocol4.word)(0n),
+      changeCommitment: plan.outputs[0]?.commitment ?? (0, import_protocol5.word)(0n),
       owner: (0, import_ethers4.getAddress)((0, import_ethers4.toBeHex)(output.state.note.ownerPayout, 20)),
       expiry: output.state.note.expiry,
       deadline: frame.deadline
@@ -2680,14 +2940,14 @@ var CreditPreparation = class {
         creditNullifier: previous.nullifier,
         previousExpiry: previous.input.state.note.expiry
       };
-      plan.statement = import_protocol4.WitnessBuilder.statement(
+      plan.statement = import_protocol5.WitnessBuilder.statement(
         "credit_top_up",
-        (0, import_protocol4.topUpCreditPublicInputs)(frame.context, plan.credit.topUp, deliveries, plan.funding)
+        (0, import_protocol5.topUpCreditPublicInputs)(frame.context, plan.credit.topUp, deliveries, plan.funding)
       );
     } else {
-      plan.statement = import_protocol4.WitnessBuilder.statement(
+      plan.statement = import_protocol5.WitnessBuilder.statement(
         "create_credit",
-        (0, import_protocol4.createCreditPublicInputs)(frame.context, creation, deliveries, plan.funding)
+        (0, import_protocol5.createCreditPublicInputs)(frame.context, creation, deliveries, plan.funding)
       );
     }
     await this.#prepare.assertBlock(frame);
@@ -2716,8 +2976,10 @@ var CreditPreparation = class {
           monthlyLimit: options.monthlyLimit ?? old.note.monthlyLimit ?? 0n,
           amount,
           expiry,
-          nonce: (0, import_core7.generateNonce)(),
-          ...options.memo === void 0 ? {} : { memo: options.memo }
+          nonce: (0, import_core9.generateNonce)(),
+          payload: copyApplicationPayload(
+            options.payload === void 0 ? old.note.payload : options.payload
+          )
         }
       },
       frame
@@ -2733,7 +2995,7 @@ var CreditPreparation = class {
   }
   async draw(options) {
     const frame = await this.#prepare.frame(options.deadline);
-    const profile = (0, import_protocol4.selectCreditDrawCircuit)(options.credits.length);
+    const profile = (0, import_protocol5.selectCreditDrawCircuit)(options.credits.length);
     if (new Set(options.credits.map((value) => value.credit)).size !== options.credits.length) {
       throw new Error("duplicate Credit input");
     }
@@ -2765,11 +3027,11 @@ var CreditPreparation = class {
       }
       sources.set(member.source.treeId, member.source.merkleRoot);
       amounts.push(amount);
-      const usage = (0, import_core7.applyCreditDrawUsage)(n, amount, frame.block.timestamp);
+      const usage = (0, import_core9.applyCreditDrawUsage)(n, amount, frame.block.timestamp);
       const remaining = n.amount - amount;
       if (remaining === 0n) {
-        remainders.push((0, import_protocol4.word)(0n));
-        recoveryAmounts.push((0, import_protocol4.word)(0n));
+        remainders.push((0, import_protocol5.word)(0n));
+        recoveryAmounts.push((0, import_protocol5.word)(0n));
         deliveries.push({ ...EMPTY }, { ...EMPTY });
         continue;
       }
@@ -2787,8 +3049,10 @@ var CreditPreparation = class {
             ...n,
             ...usage,
             amount: remaining,
-            ...options.credits[i].memo === void 0 ? {} : { memo: options.credits[i].memo },
-            nonce: await (0, import_core7.deriveRemainderNonce)(...args)
+            payload: copyApplicationPayload(
+              options.credits[i].payload === void 0 ? n.payload : options.credits[i].payload
+            ),
+            nonce: await (0, import_core9.deriveRemainderNonce)(...args)
           }
         },
         frame
@@ -2796,7 +3060,7 @@ var CreditPreparation = class {
       outputs.push(output);
       remainders.push(output.commitment);
       recoveryAmounts.push(
-        (0, import_protocol4.word)((remaining + await (0, import_core7.computeCreditRecoveryPad)(...args)) % import_core7.FIELD_MODULUS)
+        (0, import_protocol5.word)((remaining + await (0, import_core9.computeCreditRecoveryPad)(...args)) % import_core9.FIELD_MODULUS)
       );
       deliveries.push(...output.deliveries);
     }
@@ -2820,9 +3084,9 @@ var CreditPreparation = class {
       draw: params,
       amounts
     };
-    plan.statement = import_protocol4.WitnessBuilder.statement(
+    plan.statement = import_protocol5.WitnessBuilder.statement(
       profile.name,
-      (0, import_protocol4.creditDrawPublicInputs)(frame.context, params, deliveries)
+      (0, import_protocol5.creditDrawPublicInputs)(frame.context, params, deliveries)
     );
     await this.#prepare.assertBlock(frame);
     return this.runtime.complete(plan);
@@ -2842,9 +3106,9 @@ var CreditPreparation = class {
     };
     plan.capacity = 1;
     plan.credit = { inputs: [previous.input], outputs: [], deliveries: [], cancel: params };
-    plan.statement = import_protocol4.WitnessBuilder.statement(
+    plan.statement = import_protocol5.WitnessBuilder.statement(
       "credit_cancel",
-      (0, import_protocol4.cancelCreditPublicInputs)(frame.context, params)
+      (0, import_protocol5.cancelCreditPublicInputs)(frame.context, params)
     );
     await this.#prepare.assertBlock(frame);
     return this.runtime.complete(plan);
@@ -2865,87 +3129,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_protocol6.ZERO_ADDRESS;
+    let withdrawalAmount = 0n;
+    if (copied.withdrawal !== void 0) {
+      withdrawalAddress = (0, import_ethers5.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_protocol5.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_ethers5.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");
     }
@@ -2955,7 +3180,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) {
@@ -2980,17 +3205,17 @@ var TransactionPreparation = class {
       deadline
     };
     const deliveries = outputs.map((output) => output.delivery);
-    const normalized = (0, import_protocol5.normalizeTransactRequest)(context, params, deliveries, funding.funding);
-    const statement2 = import_protocol5.WitnessBuilder.statement(
+    const normalized = (0, import_protocol6.normalizeTransactRequest)(context, params, deliveries, funding.funding);
+    const statement2 = import_protocol6.WitnessBuilder.statement(
       `transact_user_slots${normalized.capacity}`,
-      (0, import_protocol5.transactUserPublicInputs)(context, params, deliveries, funding.funding),
-      target ?? "evm"
+      (0, import_protocol6.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,
@@ -3012,7 +3237,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");
@@ -3094,14 +3321,21 @@ function explicitPreparation(options, data, tokenAddress) {
     namespace: "explicit",
     walletIdentity: options.wallet.walletIdentity
   };
-  const { store: _store, coinSelector: _selector, ...capabilities } = options;
+  const {
+    store: _store,
+    coinSelector: _selector,
+    authorization: _authorization,
+    viewing: _viewing,
+    signer: _signer,
+    fundingSigner: _fundingSigner,
+    ...capabilities
+  } = options;
   if (inputs.some((input) => input.note.tokenAddress !== BigInt((0, import_ethers6.getAddress)(tokenAddress))))
     throw new Error("explicit note token mismatch");
   const runtime = {
     options: { ...capabilities, protocol: options.protocol.forToken(tokenAddress) },
     reader: options.chainReader,
-    scope,
-    authorization: () => options.authorization ?? options.wallet.exportAuthorization()
+    scope
   };
   return new TransactionPreparation({
     ...runtime,
@@ -3399,34 +3633,6 @@ var EthersAddressResolver = class {
     }).getReceivingKeys();
   };
 };
-var EthersFundingSigner = class _EthersFundingSigner {
-  constructor(signer, chainId, address2) {
-    this.signer = signer;
-    this.chainId = chainId;
-    this.address = getAddress5(address2);
-  }
-  address;
-  static async create(signer, chainId) {
-    return new _EthersFundingSigner(signer, chainId, getAddress5(await signer.getAddress()));
-  }
-  async signTypedData(data) {
-    const copied = structuredClone(data);
-    check3(
-      BigInt(copied.domain.chainId) === this.chainId,
-      "funding typed-data chain mismatch"
-    );
-    check3(
-      getAddress5(await this.signer.getAddress()) === this.address,
-      "funding signer address mismatch"
-    );
-    if (this.signer.provider) await chain(this.signer.provider, this.chainId);
-    return await this.signer.signTypedData(
-      copied.domain,
-      fundingTypes(copied),
-      copied.message
-    );
-  }
-};
 var EthersFundingVerifier = class {
   constructor(client, chainId) {
     this.client = client;
@@ -3469,7 +3675,24 @@ var EthersFundingVerifier = class {
 };
 
 // src/Invisi.ts
-var import_core15 = require("@invisi-labs/core");
+var import_core19 = require("@invisi-labs/core");
+
+// src/AddressRegistry.ts
+var import_protocol7 = require("@invisi-labs/protocol");
+var AddressRegistry = class extends import_protocol7.AddressRegistry {
+  prepareRegistration(options) {
+    return prepareWithErrors("prepareRegistration", async () => {
+      if ("provider" in options) {
+        const { provider, ...preparation } = options;
+        return super.prepareRegistration({
+          ...preparation,
+          reader: new EthersChainReader(provider)
+        });
+      }
+      return super.prepareRegistration(options);
+    });
+  }
+};
 
 // src/session/codec.ts
 function encode(value) {
@@ -3515,8 +3738,8 @@ function deserializeState(data) {
 
 // src/session/protocol-events.ts
 var import_contracts2 = require("@invisi-labs/protocol/contracts");
-var import_ethers8 = require("ethers");
-var protocolInterface = new import_ethers8.Interface(import_contracts2.invisiProtocolAbi);
+var import_ethers9 = require("ethers");
+var protocolInterface = new import_ethers9.Interface(import_contracts2.invisiProtocolAbi);
 function decodeProtocolEvent(log) {
   const decoded = protocolInterface.parseLog(log);
   if (!decoded) throw new Error("Unknown protocol receipt event");
@@ -3579,9 +3802,10 @@ function readProtocolLogs(receipt, protocolAddress) {
 }
 
 // src/session/discovery.ts
-var import_ethers9 = require("ethers");
-var import_core8 = require("@invisi-labs/core");
-var import_protocol6 = require("@invisi-labs/protocol");
+var import_core10 = require("@invisi-labs/core");
+var import_ethers10 = require("ethers");
+var import_core11 = require("@invisi-labs/core");
+var import_protocol8 = require("@invisi-labs/protocol");
 var EVENTS = /* @__PURE__ */ new Set([
   "CommitmentsInserted",
   "BatchOutputs",
@@ -3629,7 +3853,7 @@ function hash(value) {
 function contextCheck(context) {
   check4(context.chainId >= 0n && context.chainId < 1n << 64n, "invalid discovery chain");
   check4(
-    (0, import_ethers9.isAddress)(context.protocolAddress) && BigInt(context.protocolAddress) !== 0n,
+    (0, import_ethers10.isAddress)(context.protocolAddress) && BigInt(context.protocolAddress) !== 0n,
     "invalid discovery instance/token"
   );
 }
@@ -3674,9 +3898,9 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
     check4(inserted, "delivery has no matching canonical insertion");
     if (commitment !== void 0)
       check4(hash(commitment) === inserted, "delivery commitment conflicts with insertion");
-    const delivery = (0, import_protocol6.normalizeDelivery)(wire, { credit: role !== "funds" });
+    const delivery = (0, import_protocol8.normalizeOpaqueDelivery)(wire);
     check4(
-      typeof token === "string" && (0, import_ethers9.isAddress)(token) && BigInt(token) !== 0n,
+      typeof token === "string" && (0, import_ethers10.isAddress)(token) && BigInt(token) !== 0n,
       "invalid event token"
     );
     const value = {
@@ -3705,7 +3929,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_protocol6.normalizeDelivery)(ds[2], { empty: true });
+    else (0, import_protocol8.normalizeOpaqueDelivery)(ds[2], { empty: true });
   };
   for (const log of relevant) {
     const a = object(log.args);
@@ -3735,7 +3959,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
         const length = Number.parseInt(packed.slice(offset, offset + 4), 16);
         offset += 4;
         check4(
-          length >= 160 && length <= 416 && offset + length * 2 + 136 <= packed.length,
+          length >= 1 && length <= import_core10.MAX_CIPHERTEXT_BYTES && offset + length * 2 + 136 <= packed.length,
           "invalid packed delivery length"
         );
         const ciphertext = `0x${packed.slice(offset, offset + length * 2)}`;
@@ -3757,8 +3981,8 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
       cs.forEach((c, i) => {
         if (BigInt(hash(c)) === 0n) {
           check4(integer(leaves[i]) === 0n, "absent remainder has nonzero position");
-          (0, import_protocol6.normalizeDelivery)(ds[2 * i], { empty: true });
-          (0, import_protocol6.normalizeDelivery)(ds[2 * i + 1], { empty: true });
+          (0, import_protocol8.normalizeOpaqueDelivery)(ds[2 * i], { empty: true });
+          (0, import_protocol8.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]);
@@ -3770,7 +3994,7 @@ function extractDeliveryCandidates(logs, context, confirmedThrough) {
 }
 async function decryptCandidates(logs, options) {
   contextCheck(options.context);
-  (0, import_core8.decodeAddress)(import_core8.ReceivingAddress.fromIdentity(options.viewing.walletIdentity).toString());
+  (0, import_core11.decodeAddress)(import_core11.ReceivingAddress.fromIdentity(options.viewing.walletIdentity).toString());
   check4(
     !logs.some(
       (log) => log.address.toLowerCase() === options.context.protocolAddress.toLowerCase() && log.removed
@@ -4058,7 +4282,7 @@ function mergeReceiptRecords(state, batch) {
 }
 
 // src/session/store.ts
-var import_core9 = require("@invisi-labs/core");
+var import_core12 = require("@invisi-labs/core");
 var import_sha2562 = require("@noble/hashes/sha256");
 var import_utils2 = require("@noble/hashes/utils");
 function scopeKey(scope) {
@@ -4074,7 +4298,7 @@ function scopeKey(scope) {
   return (0, import_utils2.bytesToHex)(
     (0, import_sha2562.sha256)(
       (0, import_utils2.utf8ToBytes)(
-        "Invisi.WalletScope.v2:" + JSON.stringify([
+        "Invisi.WalletScope.v1:" + JSON.stringify([
           scope.namespace,
           scope.chainId.toString(),
           scope.protocolAddress.toLowerCase(),
@@ -4111,12 +4335,12 @@ function validateState(state, scope, revision) {
       throw new Error("invalid spent state");
   }
   for (const record of Object.values(state.credits)) {
-    const note = (0, import_core9.normalizeCreditDeliveryState)(record.state).note;
+    const note = (0, import_core12.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_core9.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_core12.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))
@@ -4177,16 +4401,16 @@ var TransactionalWalletStore = class {
 };
 
 // src/session/Operation.ts
-var import_core11 = require("@invisi-labs/core");
-var import_protocol8 = require("@invisi-labs/protocol");
+var import_core14 = require("@invisi-labs/core");
+var import_protocol10 = require("@invisi-labs/protocol");
 
 // src/session/operation-confirmation.ts
-var import_core10 = require("@invisi-labs/core");
+var import_core13 = require("@invisi-labs/core");
 
 // src/session/aggregate-receipt.ts
-var import_ethers11 = require("ethers");
+var import_ethers12 = require("ethers");
 var import_contracts3 = require("@invisi-labs/protocol/contracts");
-var import_protocol7 = require("@invisi-labs/protocol");
+var import_protocol9 = 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[]"
 );
@@ -4195,7 +4419,7 @@ function matchesAggregateTransaction(saved, transaction) {
   if (plan.statement?.target !== "noir-recursive" || !plan.params || !saved.externalized || transaction.to.toLowerCase() !== plan.context.protocolAddress.toLowerCase() || transaction.value !== 0n)
     return false;
   try {
-    const decoded = new import_ethers11.Interface(aggregateAbi).parseTransaction({ data: transaction.data }), requests = decoded.args[1].map((request) => {
+    const decoded = new import_ethers12.Interface(aggregateAbi).parseTransaction({ data: transaction.data }), requests = decoded.args[1].map((request) => {
       const member = request.toObject(true);
       member.params.sources = request.params.sources.map(
         (source) => source.toObject(true)
@@ -4214,7 +4438,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_protocol7.buildTransactCalldata)({
+    const canonical2 = (request) => (0, import_protocol9.buildTransactCalldata)({
       context: { ...plan.context, tokenAddress: request.params.token },
       proof: "0x00",
       params: request.params,
@@ -4222,7 +4446,7 @@ function matchesAggregateTransaction(saved, transaction) {
       funding: request.funding,
       caller: transaction.from
     }).data.toLowerCase();
-    const expected = (0, import_protocol7.buildTransactCalldata)({
+    const expected = (0, import_protocol9.buildTransactCalldata)({
       context: plan.context,
       proof: "0x00",
       params: plan.params,
@@ -4401,7 +4625,7 @@ async function confirmOperation(runtime, id, generation, hash2, signal) {
   if (credits.length) {
     const nullifiers = await Promise.all(
       credits.map(
-        async (record) => (0, import_core10.computeCreditNullifier)(
+        async (record) => (0, import_core13.computeCreditNullifier)(
           plan.context.chainId,
           record.state.note.creditSharedKey,
           await creditLeaf(record.state)
@@ -4702,6 +4926,81 @@ var Operation = class _Operation {
       throw error;
     }
   }
+  async signingCurrent() {
+    await this.#runtime.store.transaction(this.#runtime.scope, (state) => {
+      check7(!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();
+    check7(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check7(
+      ["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();
+    check7(
+      requiresAuthorization(this.#saved.plan),
+      "operation does not require wallet authorization"
+    );
+    check7(
+      ["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();
+    check7(
+      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();
+    check7(
+      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 = {}) {
     check7(
       requiresAuthorization(this.#saved.plan),
@@ -4722,7 +5021,8 @@ var Operation = class _Operation {
       options.signal
     );
   }
-  async prove(options = {}) {
+  async prove(suppliedOptions = {}) {
+    const options = { ...suppliedOptions };
     const plan = this.#saved.plan;
     check7(plan.kind !== "shield", "shield requires no proof");
     if (requiresAuthorization(plan)) {
@@ -4733,7 +5033,7 @@ var Operation = class _Operation {
     }
     const prover = this.#runtime.options.prover;
     if (!prover) {
-      throw new import_core11.MissingCapabilityError("prover");
+      throw new import_core14.MissingCapabilityError("prover");
     }
     return this.stage(
       "proof",
@@ -4767,7 +5067,7 @@ var Operation = class _Operation {
     check7(p.kind === "shield" || this.#saved.proof, "proof must precede funding authorization");
     const signer = this.#runtime.options.fundingSigner;
     if (!signer) {
-      throw new import_core11.MissingCapabilityError("EVM funding signer");
+      throw new import_core14.MissingCapabilityError("EVM funding signer");
     }
     check7(
       signer.address.toLowerCase() === p.funding.payer.toLowerCase(),
@@ -4869,7 +5169,7 @@ var Operation = class _Operation {
         request: {
           params: structuredClone(plan.params),
           deliveries: plan.outputs.map((output) => structuredClone(output.delivery)),
-          funding: (0, import_protocol8.normalizeFunding)(plan.funding)
+          funding: (0, import_protocol10.normalizeFunding)(plan.funding)
         }
       };
     });
@@ -4957,8 +5257,66 @@ var Operation = class _Operation {
 };
 
 // src/session/WalletSession.ts
-var import_ethers12 = require("ethers");
-var import_core14 = require("@invisi-labs/core");
+var import_core17 = 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/session/WalletSession.ts
+var import_ethers13 = require("ethers");
+var import_core18 = require("@invisi-labs/core");
 
 // src/session/refresh.ts
 async function refreshWallet(runtime, options) {
@@ -5015,10 +5373,10 @@ async function refreshWallet(runtime, options) {
 }
 
 // src/session/WalletUpdater.ts
-var import_core13 = require("@invisi-labs/core");
+var import_core16 = require("@invisi-labs/core");
 
 // src/session/inventory.ts
-var import_core12 = require("@invisi-labs/core");
+var import_core15 = require("@invisi-labs/core");
 var CanonicalConflict = class extends Error {
 };
 var CreditMetadataMismatch = class extends Error {
@@ -5070,10 +5428,10 @@ var InventoryProcessor = class {
   }
   async creditNullifier(state) {
     const n = state.note;
-    return (0, import_core12.computeCreditNullifier)(
+    return (0, import_core15.computeCreditNullifier)(
       n.chainId,
       n.creditSharedKey,
-      await (0, import_core12.computeCreditCommitment)(
+      await (0, import_core15.computeCreditCommitment)(
         n.chainId,
         n.spenderWalletIdentity,
         n.ownerWalletIdentity,
@@ -5083,7 +5441,7 @@ var InventoryProcessor = class {
         n.amount,
         n.nonce,
         n.expiry,
-        await (0, import_core12.computeCreditSharedKeyHash)(n.creditSharedKey),
+        await (0, import_core15.computeCreditSharedKeyHash)(n.creditSharedKey),
         n
       )
     );
@@ -5147,7 +5505,7 @@ var InventoryProcessor = class {
               previous.state.note.expiry === params.expiries[index2],
               "draw recovery expiry mismatch"
             );
-            const remainder = await (0, import_core12.recoverCreditRemainder)(
+            const remainder = await (0, import_core15.recoverCreditRemainder)(
               context,
               previous.state.note,
               {
@@ -5163,7 +5521,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),
@@ -5176,7 +5534,7 @@ var InventoryProcessor = class {
                 ...clone(previous.state),
                 note: {
                   ...remainder,
-                  ...memo === void 0 ? {} : { memo: (0, import_core12.encodeMemo)(memo) }
+                  ...payload === void 0 ? {} : { payload: clone(payload) }
                 }
               },
               receivingKeySource: { kind: "draw", commitment: previous.commitment },
@@ -5255,7 +5613,7 @@ var WalletUpdater = class extends InventoryProcessor {
   }
   async run(batch, options) {
     const { reader, protocol, scope, store, viewing } = this.#options;
-    const nullifier = import_core13.NullifierCapability.fromIdentity(scope.walletIdentity);
+    const nullifier = import_core16.NullifierCapability.fromIdentity(scope.walletIdentity);
     const { signal, reset } = options;
     signal?.throwIfAborted();
     const context = protocol.context;
@@ -5424,6 +5782,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 });
@@ -5455,13 +5814,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;
@@ -5476,7 +5860,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_core14.MissingCapabilityError("ethers signer");
+    if (!signer) throw new import_core18.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");
@@ -5484,12 +5868,12 @@ var WalletSession = class {
     const overrides = { ...options };
     const plain = operation ? void 0 : { ...input };
     try {
-      if (!signer.provider) throw new import_core14.MissingCapabilityError("connected ethers signer");
+      if (!signer.provider) throw new import_core18.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_core14.MissingCapabilityError("wallet store");
+        if (!this.#options.store) throw new import_core18.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");
@@ -5520,25 +5904,30 @@ var WalletSession = class {
   runtime(tokenAddress) {
     const options = this.#options;
     if (!options.store) {
-      throw new import_core14.MissingCapabilityError("wallet store");
+      throw new import_core18.MissingCapabilityError("wallet store");
     }
     if (!options.chainReader) {
-      throw new import_core14.MissingCapabilityError("chain reader");
+      throw new import_core18.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_core17.Wallet) return options.wallet.exportAuthorization();
+        throw new import_core18.MissingCapabilityError("wallet authorization");
+      }
     };
   }
   updater() {
     if (this.#updater) return this.#updater;
     const options = this.#options;
     if (!options.store || !options.chainReader || !options.protocolRpc)
-      throw new import_core14.MissingCapabilityError("wallet store, chain reader and Protocol RPC");
-    const viewing = options.viewing ?? options.wallet.getViewer();
+      throw new import_core18.MissingCapabilityError("wallet store, chain reader and Protocol RPC");
+    const viewing = options.viewing ?? (options.wallet instanceof import_core17.Wallet ? options.wallet.getViewer() : void 0);
+    if (!viewing) throw new import_core18.MissingCapabilityError("viewing");
     const receivingAddress = options.wallet.getReceivingAddress();
     const receivingKeys = receivingAddress.kind === "long" ? receivingAddress.getReceivingKeys() : void 0;
     this.#updater = new WalletUpdater({
@@ -5552,26 +5941,43 @@ 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_ethers13.getAddress)(options.tokenAddress) : void 0;
+    const store = this.#options.store;
+    if (!store) throw new import_core18.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_core14.MissingCapabilityError("wallet store");
+      throw new import_core18.MissingCapabilityError("wallet store");
     }
-    return walletBalance(await store.readSnapshot(this.scope), (0, import_ethers12.getAddress)(tokenAddress));
+    return walletBalance(await store.readSnapshot(this.scope), (0, import_ethers13.getAddress)(tokenAddress));
   }
   /** Pull explicitly selected indexed pages; no chain scanning or public tree reconstruction. */
   async refresh(options) {
     const provider = this.#options.protocolRpc;
     const reader = this.#options.chainReader;
-    if (!reader) throw new import_core14.MissingCapabilityError("chain reader");
-    if (!provider) throw new import_core14.MissingCapabilityError("Protocol RPC");
+    if (!reader) throw new import_core18.MissingCapabilityError("chain reader");
+    if (!provider) throw new import_core18.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,
@@ -5580,8 +5986,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;
@@ -5592,38 +6011,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_core14.MissingCapabilityError("wallet store");
+    if (!store) throw new import_core18.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");
@@ -5641,6 +6065,16 @@ var WalletSession = class {
 var Invisi = class {
   #options;
   constructor(options = {}) {
+    if ("ciphertextCodecs" in options || "envelopeVersion" in options) {
+      throw new Error(
+        "SDK envelope versions are fixed; encode application payload bytes externally"
+      );
+    }
+    if ("signer" in options || "fundingSigner" in options) {
+      throw new Error(
+        "Invisi does not accept signer defaults; export a signing request and attach the external signature"
+      );
+    }
     this.#options = {
       ...options,
       ...options.gasBenchmarks ? { gasBenchmarks: copyGasBenchmarks(options.gasBenchmarks) } : {}
@@ -5651,7 +6085,15 @@ var Invisi = class {
     return new WalletSession(await this.resolve(options));
   }
   async resolve(options) {
-    const allowed = ["wallet", "protocol", "namespace", "viewing", "authorization"];
+    const allowed = [
+      "wallet",
+      "protocol",
+      "namespace",
+      "viewing",
+      "authorization",
+      "signer",
+      "fundingSigner"
+    ];
     for (const key of Object.keys(options)) {
       if (!allowed.includes(key))
         throw new Error(
@@ -5660,97 +6102,150 @@ var Invisi = class {
     }
     const selected = { ...options };
     const combined = { ...this.#options, ...selected };
-    const { provider, signer, ...runtime } = combined;
+    const { provider, addressLookup = "protocol-rpc", ...runtime } = combined;
+    if (addressLookup !== void 0 && addressLookup !== "chain" && addressLookup !== "protocol-rpc") {
+      throw new Error("Invalid recipient address lookup source");
+    }
     const reader = combined.chainReader ?? (provider ? new EthersChainReader(provider) : void 0);
-    if (!reader) throw new import_core15.MissingCapabilityError("chain reader");
+    if (!reader) throw new import_core19.MissingCapabilityError("chain reader");
     if (provider && (await provider.getNetwork()).chainId !== selected.protocol.context.chainId)
       throw new Error("provider deployment chain mismatch");
     await selected.protocol.validateDeployment(reader);
     if (runtime.protocolRpc instanceof import_rpc.ProtocolRpcClient) {
       runtime.protocolRpc = runtime.protocolRpc.withReader(reader);
     }
-    if (signer) {
-      if (!provider) throw new import_core15.MissingCapabilityError("provider for signer");
-      if (!signer.provider) throw new Error("signer must be connected to a provider");
-      if ((await signer.provider.getNetwork()).chainId !== selected.protocol.context.chainId)
-        throw new Error("signer-provider deployment chain mismatch");
-    }
     const registry = selected.protocol.deployment.registry;
-    const fundingSigner = combined.fundingSigner ?? (signer ? await EthersFundingSigner.create(signer, selected.protocol.context.chainId) : void 0);
     const fundingVerifier = combined.fundingVerifier ?? (provider ? new EthersFundingVerifier(provider, selected.protocol.context.chainId) : void 0);
-    const addressResolver = combined.addressResolver ?? (provider && registry ? new EthersAddressResolver(
-      provider,
-      {
-        chainId: selected.protocol.context.chainId,
-        registryAddress: registry.address
-      },
-      registry.runtimeCodeHash
-    ).lookup : void 0);
+    let addressResolver = combined.addressResolver;
+    if (!addressResolver && registry) {
+      if (addressLookup === "protocol-rpc") {
+        const rpc = runtime.protocolRpc;
+        addressResolver = async (identity) => {
+          if (!(rpc instanceof import_rpc.ProtocolRpcClient)) {
+            throw new import_core19.MissingCapabilityError("Protocol RPC recipient discovery");
+          }
+          const discovered = await rpc.getDeployment(selected.protocol.context.chainId);
+          const expected = selected.protocol.deployment;
+          if (discovered.protocol.address !== expected.protocol.address || discovered.protocol.runtimeCodeHash !== expected.protocol.runtimeCodeHash || discovered.protocol.fromBlock !== expected.protocol.fromBlock || discovered.registry?.address !== registry.address || discovered.registry.runtimeCodeHash !== registry.runtimeCodeHash || discovered.registry.fromBlock !== registry.fromBlock)
+            throw new Error("Recipient registry deployment pins mismatch");
+          const registration = await rpc.getReceivingAddress(identity);
+          return registration ? import_core19.ReceivingAddress.parse(registration.receivingAddress).getReceivingKeys() : null;
+        };
+      } else if (provider) {
+        addressResolver = new EthersAddressResolver(
+          provider,
+          {
+            chainId: selected.protocol.context.chainId,
+            registryAddress: registry.address
+          },
+          registry.runtimeCodeHash
+        ).lookup;
+      }
+    }
     return {
       ...runtime,
       chainReader: reader,
-      ...signer ? { signer } : {},
-      ...fundingSigner ? { fundingSigner } : {},
       ...fundingVerifier ? { fundingVerifier } : {},
       ...addressResolver ? { addressResolver } : {},
       protocol: selected.protocol
     };
   }
+  /** Discover the selected chain's registry and prepare an independent signing request. */
+  async prepareRegistration(options) {
+    return prepareWithErrors("prepareRegistration", async () => {
+      for (const key of Object.keys(options)) {
+        if (!["wallet", "update", "deadline"].includes(key)) {
+          throw new Error(`Unknown registration option: ${key}`);
+        }
+      }
+      this.assertPublicIdentity(options);
+      const selected = { ...options };
+      const { provider, protocolRpc } = this.#options;
+      if (!provider) throw new import_core19.MissingCapabilityError("ethers provider");
+      if (!(protocolRpc instanceof import_rpc.ProtocolRpcClient)) {
+        throw new import_core19.MissingCapabilityError("Protocol RPC deployment discovery");
+      }
+      const chainId = (await provider.getNetwork()).chainId;
+      const deployment = await protocolRpc.getDeployment(chainId);
+      if (!deployment.registry) {
+        throw new import_core19.MissingCapabilityError("receiving-key registry deployment");
+      }
+      const registry = new AddressRegistry(
+        { chainId, registryAddress: deployment.registry.address },
+        { expectedRuntimeCodeHash: deployment.registry.runtimeCodeHash }
+      );
+      return registry.prepareRegistration({ ...selected, provider });
+    });
+  }
+  assertPublicIdentity(options) {
+    const { wallet } = options;
+    if (!(wallet instanceof import_core19.PublicWallet) || ["getViewer", "getDetector", "exportAuthorization"].some((key) => key in wallet)) {
+      throw new Error(
+        "Independent preparation requires a PublicWallet without private capabilities"
+      );
+    }
+    for (const key of ["authorization", "signer", "fundingSigner", "viewing"]) {
+      if (key in options)
+        throw new Error(`Independent preparation does not accept capability: ${key}`);
+    }
+  }
+  resolveExplicit(options) {
+    this.assertPublicIdentity(options);
+    return this.resolve({ wallet: options.wallet, protocol: options.protocol });
+  }
   async prepareTransfer(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareTransfer(request);
-  }
-  async prepareWithdraw(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareWithdraw(request);
-  }
-  async prepareSweep(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareSweep(request);
+    return prepareWithErrors("prepareTransfer", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, request, request.tokenAddress);
+      return preparation.prepareTransfer(request);
+    });
   }
   async prepareShield(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, {}, request.tokenAddress);
-    return preparation.prepareShield(request);
+    return prepareWithErrors("prepareShield", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, {}, request.tokenAddress);
+      return preparation.prepareShield(request);
+    });
   }
   async prepareCreateCredit(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareCreateCredit(request);
+    return prepareWithErrors("prepareCreateCredit", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, request, request.tokenAddress);
+      return preparation.prepareCreateCredit(request);
+    });
   }
   async prepareDrawCredit(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareDrawCredit(request);
+    return prepareWithErrors("prepareDrawCredit", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, request, request.tokenAddress);
+      return preparation.prepareDrawCredit(request);
+    });
   }
   async prepareTopUpCredit(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareTopUpCredit(request);
+    return prepareWithErrors("prepareTopUpCredit", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, request, request.tokenAddress);
+      return preparation.prepareTopUpCredit(request);
+    });
   }
   async prepareCancelCredit(options) {
-    const { wallet, protocol, ...input } = options;
-    const request = structuredClone(input);
-    const runtime = await this.resolve({ wallet, protocol });
-    const preparation = explicitPreparation(runtime, request, request.tokenAddress);
-    return preparation.prepareCancelCredit(request);
+    return prepareWithErrors("prepareCancelCredit", async () => {
+      const { wallet, protocol, ...input } = options;
+      const request = structuredClone(input);
+      const runtime = await this.resolveExplicit(options);
+      const preparation = explicitPreparation(runtime, request, request.tokenAddress);
+      return preparation.prepareCancelCredit(request);
+    });
   }
   toJSON() {
     return { invisi: true };
@@ -5761,8 +6256,8 @@ var Invisi = class {
 };
 
 // src/index.ts
-var import_core16 = require("@invisi-labs/core");
-var import_protocol10 = require("@invisi-labs/protocol");
+var import_core20 = require("@invisi-labs/core");
+var import_protocol11 = require("@invisi-labs/protocol");
 var import_rpc3 = require("@invisi-labs/rpc");
 
 // src/ProtocolRpcClient.ts
@@ -5773,21 +6268,6 @@ var ProtocolRpcClient2 = class extends import_rpc2.ProtocolRpcClient {
   }
 };
 
-// src/AddressRegistry.ts
-var import_protocol9 = require("@invisi-labs/protocol");
-var AddressRegistry = class extends import_protocol9.AddressRegistry {
-  prepareRegistration(options) {
-    if ("provider" in options) {
-      const { provider, ...preparation } = options;
-      return super.prepareRegistration({
-        ...preparation,
-        reader: new EthersChainReader(provider)
-      });
-    }
-    return super.prepareRegistration(options);
-  }
-};
-
 // src/integrations/encrypted-codec.ts
 var EncryptedWalletCodec = class _EncryptedWalletCodec {
   #key;
@@ -5879,6 +6359,7 @@ var EncryptedWalletCodec = class _EncryptedWalletCodec {
   DisclosureVerifier,
   EncryptedWalletCodec,
   Invisi,
+  InvisiError,
   MAX_MEMO_BYTES,
   MissingCapabilityError,
   NullifierCapability,
@@ -5887,14 +6368,22 @@ var EncryptedWalletCodec = class _EncryptedWalletCodec {
   Protocol,
   ProtocolRpcClient,
   ProtocolRpcError,
+  PublicWallet,
   RegistrationOperation,
   ViewingCapability,
   Wallet,
   WalletAuthorization,
   WalletSession,
+  computeCreditNullifier,
+  creditPeriods,
+  creditV1,
+  decodeDeliveryHeader,
   decodeMemoText,
+  decryptCandidates,
   defineGasBenchmarks,
   encodeMemo,
+  fundsV1,
+  readProtocolLogs,
   walletBalance
 });
 //# sourceMappingURL=index.cjs.map