opacity-issuer-core 0.2.2 → 0.3.0

package/dist/index.cjs

@@ -524,12 +524,12 @@ function createPurchasesNamespace(options = {}) {
           "Payment token returned false from approve."
         );
       const wallet = await walletFor(params);
-      const hash = await wallet.writeContract({
+      const hash2 = await wallet.writeContract({
         ...step.request,
         account: wallet.account ?? params.buyer,
         chain: sendChain(wallet, params.deployment.chainId)
       });
-      return { ...params, kind: "approval", step: step.kind, approvedAmount: step.amount, hash };
+      return { ...params, kind: "approval", step: step.kind, approvedAmount: step.amount, hash: hash2 };
     });
   }
   async function sendPurchase(input) {
@@ -538,17 +538,17 @@ function createPurchasesNamespace(options = {}) {
       await walletFor(params);
       const prepared = await simulatePurchase(params);
       const wallet = await walletFor(params);
-      const hash = await wallet.writeContract({
+      const hash2 = await wallet.writeContract({
         ...prepared.request,
         account: wallet.account ?? params.buyer,
         chain: sendChain(wallet, params.deployment.chainId)
       });
-      return { ...params, kind: "purchase", hash };
+      return { ...params, kind: "purchase", hash: hash2 };
     });
   }
   async function receiptFor(submitted, options2) {
     const params = purchaseParams(submitted);
-    const hash = bytes32(submitted.hash, "hash", true);
+    const hash2 = bytes32(submitted.hash, "hash", true);
     for (const [name, value] of Object.entries(options2)) {
       if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
         throw new OpacityPurchaseError("invalid-input", `${name} must be a positive safe integer.`);
@@ -557,7 +557,7 @@ function createPurchasesNamespace(options = {}) {
     const client = await clientFor(params.deployment);
     let replacementReason;
     const receipt = await client.waitForTransactionReceipt({
-      hash,
+      hash: hash2,
       ...options2.confirmations === void 0 ? {} : { confirmations: options2.confirmations },
       ...options2.timeout === void 0 ? {} : { timeout: options2.timeout },
       ...options2.pollingInterval === void 0 ? {} : { pollingInterval: options2.pollingInterval },
@@ -565,10 +565,10 @@ function createPurchasesNamespace(options = {}) {
         replacementReason = replacement.reason;
       }
     });
-    const replaced = receipt.transactionHash.toLowerCase() !== hash.toLowerCase();
+    const replaced = receipt.transactionHash.toLowerCase() !== hash2.toLowerCase();
     return {
       status: replaced || replacementReason !== void 0 ? "replaced" : receipt.status === "reverted" ? "reverted" : "unverified",
-      submittedHash: hash,
+      submittedHash: hash2,
       hash: receipt.transactionHash,
       receipt,
       ...replacementReason === void 0 ? {} : { replacementReason }
@@ -6246,14 +6246,14 @@ function createTransfersNamespace(options = {}) {
         rpcUrls: { default: { http: [] } }
       });
       const { gas, gasPrice, maxFeePerGas, maxPriorityFeePerGas } = prepared.gas;
-      const hash = await wallet.writeContract({
+      const hash2 = await wallet.writeContract({
         ...prepared.request,
         account: wallet.account ?? params.sender,
         chain: chain2,
         gas,
         ...gasPrice === void 0 ? { maxFeePerGas, maxPriorityFeePerGas } : { gasPrice }
       });
-      return Object.freeze({ ...params, kind: "transfer", hash });
+      return Object.freeze({ ...params, kind: "transfer", hash: hash2 });
     } finally {
       sendsInProgress.delete(key);
     }
@@ -6262,8 +6262,8 @@ function createTransfersNamespace(options = {}) {
     if (submitted?.kind !== "transfer")
       throw new OpacityTransferError("invalid-input", "Expected a submitted transfer record.");
     const params = transferParams(submitted);
-    const hash = submitted.hash;
-    if (typeof hash !== "string" || !/^0x[\da-fA-F]{64}$/.test(hash) || /^0x0+$/.test(hash)) {
+    const hash2 = submitted.hash;
+    if (typeof hash2 !== "string" || !/^0x[\da-fA-F]{64}$/.test(hash2) || /^0x0+$/.test(hash2)) {
       throw new OpacityTransferError("invalid-input", "hash must be nonzero bytes32.");
     }
     const waitOptions3 = {
@@ -6282,7 +6282,7 @@ function createTransfersNamespace(options = {}) {
     const client = await clientFor(params.deployment);
     let replacementReason;
     const received = await client.waitForTransactionReceipt({
-      hash,
+      hash: hash2,
       ...waitOptions3,
       onReplaced: (replacement) => {
         replacementReason = replacement.reason;
@@ -6294,8 +6294,8 @@ function createTransfersNamespace(options = {}) {
     };
     await clientFor(params.deployment);
     const result = {
-      status: receipt.transactionHash.toLowerCase() !== hash.toLowerCase() || replacementReason !== void 0 ? "replaced" : receipt.status === "reverted" ? "reverted" : "unverified",
-      submittedHash: hash,
+      status: receipt.transactionHash.toLowerCase() !== hash2.toLowerCase() || replacementReason !== void 0 ? "replaced" : receipt.status === "reverted" ? "reverted" : "unverified",
+      submittedHash: hash2,
       hash: receipt.transactionHash,
       receipt,
       ...replacementReason === void 0 ? {} : { replacementReason }
@@ -6305,15 +6305,15 @@ function createTransfersNamespace(options = {}) {
       return result;
     let transaction;
     try {
-      transaction = { ...await client.getTransaction({ hash }) };
+      transaction = { ...await client.getTransaction({ hash: hash2 }) };
     } catch {
       return result;
     }
     await clientFor(params.deployment);
-    if (transaction.chainId !== params.deployment.chainId || typeof transaction.hash !== "string" || transaction.hash.toLowerCase() !== hash.toLowerCase() || !sameAddress2(transaction.from, params.sender) || !sameAddress2(transaction.to, params.deployment.token) || transaction.value !== 0n || typeof transaction.input !== "string" || transaction.input.toLowerCase() !== buildTransferTransaction(params).data.toLowerCase())
+    if (transaction.chainId !== params.deployment.chainId || typeof transaction.hash !== "string" || transaction.hash.toLowerCase() !== hash2.toLowerCase() || !sameAddress2(transaction.from, params.sender) || !sameAddress2(transaction.to, params.deployment.token) || transaction.value !== 0n || typeof transaction.input !== "string" || transaction.input.toLowerCase() !== buildTransferTransaction(params).data.toLowerCase())
       return result;
     for (const log of receipt.logs) {
-      if (!sameAddress2(log.address, params.deployment.token) || log.removed || log.transactionHash?.toLowerCase() !== hash.toLowerCase())
+      if (!sameAddress2(log.address, params.deployment.token) || log.removed || log.transactionHash?.toLowerCase() !== hash2.toLowerCase())
         continue;
       try {
         const event = viem.decodeEventLog({
@@ -7199,6 +7199,357 @@ function createPolicyReplacementBatch(currentCount, policies) {
   return createPolicyBatch(changes);
 }
 
+// src/issuers/discovery.ts
+var discoveryAbi = viem.parseAbi([
+  "function allowlistRegistry() view returns (address)",
+  "function beaconRegistry() view returns (address)",
+  "function platformOperator() view returns (address)",
+  "function policyEngine() view returns (address)",
+  "function policyRegistry() view returns (address)",
+  "function getDefaultVariant() view returns (bytes32)",
+  "function getBeacon(bytes32) view returns (address)",
+  "function isVariantActive(bytes32) view returns (bool)",
+  "function isAuthorizedFactory(address) view returns (bool)",
+  "function getIssuerTokens(address) view returns (address[])",
+  "function implementationsOf(bytes32) view returns (address[])",
+  "function isApproved(address) view returns (bool)",
+  "function policyTypeOf(address) view returns (bytes32)",
+  "function policyType() view returns (bytes32)"
+]);
+var policyKinds = Object.keys(issuerPolicyTypes);
+function fail(message) {
+  throw new OpacityIssuerOperationError("deployment-mismatch", message);
+}
+function address4(value, optional = false) {
+  if (optional && value === null) return viem.zeroAddress;
+  if (typeof value !== "string" || !viem.isAddress(value, { strict: false }) || !optional && value.toLowerCase() === viem.zeroAddress)
+    fail("Issuer discovery returned an invalid contract address.");
+  return value.toLowerCase();
+}
+function hash(value) {
+  if (typeof value !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(value))
+    fail("Issuer discovery requires valid block and transaction hashes.");
+  return value.toLowerCase();
+}
+function positiveBigint(value) {
+  return typeof value === "bigint" && value > 0n;
+}
+function validateHead(meta) {
+  if (!meta || meta.hasIndexingErrors !== false || typeof meta.deployment !== "string" || !meta.deployment || !positiveBigint(meta.block?.number) || !positiveBigint(meta.block.timestamp))
+    fail("Issuer discovery requires a healthy subgraph with complete block evidence.");
+  const age = BigInt(Math.floor(Date.now() / 1e3)) - meta.block.timestamp;
+  if (age > 600n || age < -60n)
+    fail("Issuer discovery requires a subgraph block from the last 10 minutes.");
+  return {
+    deployment: meta.deployment,
+    number: meta.block.number,
+    hash: hash(meta.block.hash),
+    timestamp: meta.block.timestamp
+  };
+}
+async function resolveIssuerDeployment(input, options) {
+  if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["chainId", "token", "maxTokens"].includes(key)) || !options || typeof options !== "object" || Array.isArray(options))
+    throw new OpacityIssuerOperationError("invalid-input", "Invalid issuer discovery arguments.");
+  const chainId4 = issuerChainId(input.chainId);
+  const selectedToken = input.token === void 0 ? void 0 : issuerAddress(input.token, "token").toLowerCase();
+  const maxTokens = input.maxTokens === void 0 ? 100 : input.maxTokens;
+  if (!Number.isSafeInteger(maxTokens) || maxTokens < 1 || maxTokens > 1e3)
+    throw new OpacityIssuerOperationError(
+      "invalid-input",
+      "maxTokens must be an integer between 1 and 1000."
+    );
+  const { indexer, publicClient: client } = options;
+  if (!client || !indexer || ["getMetadata", "getRegistry", "listTokens", "getToken"].some(
+    (method) => typeof indexer[method] !== "function"
+  ) || typeof client.getChainId !== "function")
+    throw new OpacityIssuerOperationError(
+      "missing-client",
+      "Issuer discovery requires publicClient and a configured indexer."
+    );
+  if (client.chain && client.chain.id !== chainId4 || await client.getChainId() !== chainId4)
+    throw new OpacityIssuerOperationError(
+      "chain-mismatch",
+      "RPC and requested issuer discovery chains must agree."
+    );
+  const snapshot2 = validateHead(await indexer.getMetadata());
+  function validateSnapshot(meta) {
+    if (!meta || meta.hasIndexingErrors !== false || meta.deployment !== snapshot2.deployment || meta.block?.number !== snapshot2.number || meta.block.hash !== null && hash(meta.block.hash) !== snapshot2.hash || meta.block.timestamp !== null && meta.block.timestamp !== snapshot2.timestamp)
+      fail("The subgraph snapshot changed during issuer discovery. Retry discovery.");
+  }
+  const atSnapshot = { blockHash: snapshot2.hash };
+  const registryResult = await indexer.getRegistry(atSnapshot);
+  validateSnapshot(registryResult.meta);
+  if (!registryResult.item) fail("The configured subgraph has no indexed protocol registry.");
+  const registry = address4(registryResult.item.contractAddress);
+  const tokens = [];
+  if (selectedToken !== void 0) {
+    const result = await indexer.getToken(selectedToken, atSnapshot);
+    validateSnapshot(result.meta);
+    if (!result.item || address4(result.item.id) !== selectedToken)
+      fail("The selected source token is not indexed in this environment.");
+    tokens.push(result.item);
+  } else {
+    let cursor = null;
+    const seenCursors = /* @__PURE__ */ new Set();
+    do {
+      const page = await indexer.listTokens({
+        registry,
+        ...atSnapshot,
+        pageSize: Math.min(100, maxTokens - tokens.length),
+        ...cursor ? { cursor } : {}
+      });
+      validateSnapshot(page.meta);
+      if (!Array.isArray(page.items) || page.items.length > maxTokens - tokens.length)
+        fail("Issuer discovery returned an invalid token page.");
+      tokens.push(...page.items);
+      cursor = page.nextCursor;
+      if (cursor) {
+        if (tokens.length >= maxTokens)
+          fail("Issuer discovery exceeded maxTokens. Select a source token or raise maxTokens.");
+        if (!page.items.length || seenCursors.has(cursor.after))
+          fail("Issuer discovery pagination did not advance.");
+        seenCursors.add(cursor.after);
+      }
+    } while (cursor);
+  }
+  if (!tokens.length)
+    fail(
+      "The configured subgraph has no indexed token deployments. Index the protocol deployment before discovering its factory; a new issuer does not need an existing token of their own."
+    );
+  const tokenAddresses = tokens.map((token) => address4(token.id));
+  if (new Set(tokenAddresses).size !== tokens.length)
+    fail("Issuer discovery returned duplicate source tokens.");
+  const [indexedBlock, latest] = await Promise.all([
+    client.getBlock({ blockNumber: snapshot2.number }),
+    client.getBlock({ blockTag: "latest" })
+  ]);
+  if (indexedBlock.number !== snapshot2.number || hash(indexedBlock.hash) !== snapshot2.hash || indexedBlock.timestamp !== snapshot2.timestamp || !positiveBigint(latest.number) || latest.number < snapshot2.number || !positiveBigint(latest.timestamp) || latest.timestamp < snapshot2.timestamp)
+    fail("Subgraph block evidence does not match the requested RPC chain.");
+  const latestHash = hash(latest.hash);
+  validateHead({
+    deployment: snapshot2.deployment,
+    hasIndexingErrors: false,
+    block: { number: latest.number, hash: latestHash, timestamp: latest.timestamp }
+  });
+  const blocks = [.../* @__PURE__ */ new Set([snapshot2.number, latest.number])];
+  const readCache = /* @__PURE__ */ new Map();
+  function read(contract, functionName, args, blockNumber) {
+    const key = `${contract}:${functionName}:${args.join(",")}:${blockNumber}`;
+    let result = readCache.get(key);
+    if (!result) {
+      result = client.readContract({
+        address: contract,
+        abi: discoveryAbi,
+        functionName,
+        args,
+        blockNumber
+      });
+      readCache.set(key, result);
+    }
+    return result;
+  }
+  const codeCache = /* @__PURE__ */ new Set();
+  async function requireCode(contract, blockNumber) {
+    const key = `${contract}:${blockNumber}`;
+    if (codeCache.has(key)) return;
+    const code = await client.getBytecode({ address: contract, blockNumber });
+    if (!code || code === "0x") fail(`No contract code at discovered address ${contract}.`);
+    codeCache.add(key);
+  }
+  async function sameAddressAtBoth(contract, functionName, expected, optional = false) {
+    for (const block of blocks) {
+      if (address4(await read(contract, functionName, [], block), optional) !== expected)
+        fail(`Discovered ${functionName} differs from the indexed or current chain state.`);
+    }
+  }
+  const factories = /* @__PURE__ */ new Set();
+  const receiptCache = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    const tokenAddress = address4(token.id);
+    const tokenIssuer = address4(token.issuer?.id);
+    if (address4(token.allowlistRegistry) !== registry)
+      fail("An indexed source token belongs to a different registry.");
+    if (!positiveBigint(token.deployedAtBlock) || token.deployedAtBlock > snapshot2.number)
+      fail("The indexed token deployment block is invalid.");
+    for (const block of blocks) await requireCode(tokenAddress, block);
+    await sameAddressAtBoth(tokenAddress, "allowlistRegistry", registry);
+    const engine = address4(token.policyEngine, true);
+    await sameAddressAtBoth(tokenAddress, "policyEngine", engine, true);
+    const txHash = hash(token.deployTxHash);
+    let receipt = receiptCache.get(txHash);
+    if (!receipt) {
+      receipt = await client.getTransactionReceipt({ hash: txHash });
+      receiptCache.set(txHash, receipt);
+    }
+    if (receipt.status !== "success" || hash(receipt.transactionHash) !== txHash || receipt.blockNumber !== token.deployedAtBlock)
+      fail("The indexed token deployment receipt does not match the chain.");
+    const deployedBlock = await client.getBlock({ blockNumber: receipt.blockNumber });
+    if (deployedBlock.number !== token.deployedAtBlock || hash(deployedBlock.hash) !== hash(receipt.blockHash) || deployedBlock.timestamp !== token.deployedAtTimestamp)
+      fail("The indexed token deployment receipt is not on the canonical chain.");
+    const emitters = [];
+    for (const log of receipt.logs) {
+      if (log.removed) continue;
+      try {
+        const event = viem.decodeEventLog({
+          abi: issuerFactoryAbi,
+          eventName: "TokenDeployed",
+          topics: log.topics,
+          data: log.data,
+          strict: true
+        });
+        if (address4(event.args.token) === tokenAddress && address4(event.args.issuer) === tokenIssuer && address4(event.args.allowlistRegistry) === registry)
+          emitters.push(address4(log.address));
+      } catch {
+      }
+    }
+    if (emitters.length !== 1)
+      fail("Expected exactly one matching TokenDeployed event in the indexed receipt.");
+    const emitter = emitters[0];
+    for (const block of blocks) {
+      const issued = await read(emitter, "getIssuerTokens", [tokenIssuer], block);
+      if (!Array.isArray(issued) || !issued.some((item) => address4(item) === tokenAddress))
+        fail("The indexed token is not recorded by its deployment factory for that issuer.");
+    }
+    factories.add(emitter);
+  }
+  if (factories.size !== 1)
+    fail(
+      "Multiple protocol deployments are indexed. Select a source token explicitly; discovery never guesses a factory."
+    );
+  const factory = [...factories][0];
+  for (const block of blocks) {
+    await requireCode(factory, block);
+    await requireCode(registry, block);
+  }
+  await sameAddressAtBoth(factory, "allowlistRegistry", registry);
+  const beaconRegistry = address4(await read(factory, "beaconRegistry", [], snapshot2.number));
+  await sameAddressAtBoth(factory, "beaconRegistry", beaconRegistry);
+  const defaultBeaconVariant = hash(
+    await read(beaconRegistry, "getDefaultVariant", [], snapshot2.number)
+  );
+  const beacon = address4(
+    await read(beaconRegistry, "getBeacon", [defaultBeaconVariant], snapshot2.number)
+  );
+  for (const block of blocks) {
+    await requireCode(beaconRegistry, block);
+    await requireCode(beacon, block);
+    const [variant, actualBeacon, active3, authorized] = await Promise.all([
+      read(beaconRegistry, "getDefaultVariant", [], block),
+      read(beaconRegistry, "getBeacon", [defaultBeaconVariant], block),
+      read(beaconRegistry, "isVariantActive", [defaultBeaconVariant], block),
+      read(beaconRegistry, "isAuthorizedFactory", [factory], block)
+    ]);
+    if (hash(variant) !== defaultBeaconVariant || address4(actualBeacon) !== beacon || active3 !== true || authorized !== true)
+      fail("Discovered factory or default beacon is inactive, unauthorized, or changed.");
+  }
+  const deployment2 = {
+    chainId: chainId4,
+    factory,
+    allowlistRegistry: registry,
+    beaconRegistry
+  };
+  const policies = Object.fromEntries(policyKinds.map((kind) => [kind, []]));
+  const policyEngine = await (async () => {
+    try {
+      const operator = address4(await read(registry, "platformOperator", [], snapshot2.number));
+      await sameAddressAtBoth(registry, "platformOperator", operator);
+      for (const block of blocks) await requireCode(operator, block);
+      const governedEngine = address4(await read(operator, "policyEngine", [], snapshot2.number));
+      await sameAddressAtBoth(operator, "policyEngine", governedEngine);
+      return governedEngine;
+    } catch (cause) {
+      const unsupported = cause instanceof viem.BaseError ? cause.walk(
+        (error) => error instanceof viem.ContractFunctionZeroDataError || error instanceof viem.ContractFunctionRevertedError
+      ) : void 0;
+      if (!(cause instanceof OpacityIssuerOperationError && cause.code === "deployment-mismatch") && !(unsupported instanceof viem.ContractFunctionZeroDataError) && !(unsupported instanceof viem.ContractFunctionRevertedError))
+        throw cause;
+      throw new OpacityIssuerOperationError(
+        "deployment-mismatch",
+        "Cannot verify registry-governed policy infrastructure. Automatic discovery requires a contract platformOperator exposing policyEngine at the indexed and current blocks; an EOA operator or incompatible deployment must be configured by protocol governance before discovery can proceed.",
+        { cause }
+      );
+    }
+  })();
+  if (policyEngine) {
+    const policyRegistry = address4(await read(policyEngine, "policyRegistry", [], snapshot2.number));
+    for (const block of blocks) {
+      await requireCode(policyEngine, block);
+      await requireCode(policyRegistry, block);
+    }
+    await sameAddressAtBoth(policyEngine, "policyRegistry", policyRegistry);
+    await sameAddressAtBoth(policyRegistry, "allowlistRegistry", registry);
+    deployment2.policyEngine = policyEngine;
+    deployment2.policyRegistry = policyRegistry;
+    await Promise.all(
+      policyKinds.map(async (kind) => {
+        const policyType = issuerPolicyTypes[kind];
+        const raw = await read(policyRegistry, "implementationsOf", [policyType], snapshot2.number);
+        if (!Array.isArray(raw) || raw.length > 1e3)
+          fail("The policy registry returned an invalid or excessive implementation catalog.");
+        const implementations = raw.map((item) => address4(item));
+        if (new Set(implementations).size !== implementations.length)
+          fail("The policy registry returned duplicate implementations.");
+        const current = await read(
+          policyRegistry,
+          "implementationsOf",
+          [policyType],
+          latest.number
+        );
+        if (!Array.isArray(current) || current.length !== implementations.length || current.some((item, i) => address4(item) !== implementations[i]))
+          fail("The policy catalog changed since the indexed block. Wait for indexing and retry.");
+        for (const implementation of implementations) {
+          const approved = await read(
+            policyRegistry,
+            "isApproved",
+            [implementation],
+            snapshot2.number
+          );
+          if (typeof approved !== "boolean") fail("The policy registry returned invalid approval.");
+          if (await read(policyRegistry, "isApproved", [implementation], latest.number) !== approved)
+            fail("Policy approval changed since the indexed block. Wait for indexing and retry.");
+          if (!approved) continue;
+          for (const block of blocks) {
+            await requireCode(implementation, block);
+            const [registeredType, actualType] = await Promise.all([
+              read(policyRegistry, "policyTypeOf", [implementation], block),
+              read(implementation, "policyType", [], block)
+            ]);
+            if (hash(registeredType) !== policyType || hash(actualType) !== policyType)
+              fail("An approved policy implementation does not match its registered policy type.");
+          }
+          policies[kind].push(implementation);
+        }
+      })
+    );
+  }
+  const [finalIndexed, finalLatest] = await Promise.all([
+    client.getBlock({ blockNumber: snapshot2.number }),
+    client.getBlock({ blockNumber: latest.number })
+  ]);
+  if (hash(finalIndexed.hash) !== snapshot2.hash || hash(finalLatest.hash) !== latestHash)
+    fail("The chain reorganized during issuer discovery. Retry discovery.");
+  validateHead({
+    deployment: snapshot2.deployment,
+    hasIndexingErrors: false,
+    block: { number: snapshot2.number, hash: snapshot2.hash, timestamp: snapshot2.timestamp }
+  });
+  return {
+    deployment: deployment2,
+    policies,
+    defaultBeaconVariant,
+    beacon,
+    evidence: {
+      subgraphDeployment: snapshot2.deployment,
+      blockNumber: snapshot2.number,
+      blockHash: snapshot2.hash,
+      timestamp: snapshot2.timestamp,
+      verifiedAtBlock: latest.number,
+      verifiedAtBlockHash: latestHash,
+      sourceTokens: tokenAddresses
+    }
+  };
+}
+
 // src/issuers/sandbox-deployment.ts
 var { chainId: chainId3, addresses } = chunkGMPQFX25_cjs.SEPOLIA_SANDBOX_MANIFEST;
 var SANDBOX_ISSUER_DEPLOYMENT = Object.freeze({
@@ -7217,6 +7568,37 @@ var SANDBOX_ISSUER_DEPLOYMENT = Object.freeze({
 function createIssuersNamespace(options = {}) {
   const configuredChain = options.chainId === void 0 ? void 0 : issuerChainId(options.chainId);
   const busy = /* @__PURE__ */ new Set();
+  async function discoverDeployment(params = {}) {
+    if (!params || typeof params !== "object" || Array.isArray(params) || ![Object.prototype, null].includes(Object.getPrototypeOf(params)))
+      throw new OpacityIssuerOperationError(
+        "invalid-input",
+        "Discovery parameters must be a plain object."
+      );
+    const chainId4 = params.chainId === void 0 ? configuredChain : params.chainId;
+    if (chainId4 === void 0)
+      throw new OpacityIssuerOperationError(
+        "invalid-input",
+        "Configure chainId before discovering an issuer deployment."
+      );
+    issuerChainId(chainId4);
+    if (configuredChain !== void 0 && chainId4 !== configuredChain)
+      throw new OpacityIssuerOperationError(
+        "chain-mismatch",
+        "Discovery chain must match the configured issuer chain."
+      );
+    if (!options.indexer || !options.publicClient)
+      throw new OpacityIssuerOperationError(
+        "missing-client",
+        "Deployment discovery requires an indexer and publicClient."
+      );
+    return resolveIssuerDeployment(
+      { ...params, chainId: chainId4 },
+      {
+        indexer: options.indexer,
+        publicClient: options.publicClient
+      }
+    );
+  }
   async function clientFor(chainId4) {
     issuerChainId(chainId4);
     const client = options.publicClient;
@@ -7246,15 +7628,15 @@ function createIssuersNamespace(options = {}) {
       );
     return wallet;
   }
-  async function requireCode(client, address4, blockNumber) {
+  async function requireCode(client, address5, blockNumber) {
     const code = await client.getBytecode({
-      address: address4,
+      address: address5,
       ...blockNumber === void 0 ? {} : { blockNumber }
     });
     if (!code || code === "0x")
       throw new OpacityIssuerOperationError(
         "deployment-mismatch",
-        `No contract code at ${address4}.`
+        `No contract code at ${address5}.`
       );
   }
   async function sandboxVersionAt(client, registry, blockNumber) {
@@ -7545,10 +7927,10 @@ function createIssuersNamespace(options = {}) {
           "deployment-blocked",
           `Issuer deployment blocked: ${prepared.blockers.join(", ")}.`
         );
-      const hash = await write(prepared.transaction);
+      const hash2 = await write(prepared.transaction);
       return {
         kind: "deployment",
-        hash,
+        hash: hash2,
         transaction: prepared.transaction,
         params,
         predictedToken: prepared.predictedToken,
@@ -7721,28 +8103,28 @@ function createIssuersNamespace(options = {}) {
   }
   async function waitForTransaction(record2, wait = {}) {
     const tx = issuerTransaction(record2.transaction);
-    const hash = issuerBytes(record2.hash, "hash", 32);
+    const hash2 = issuerBytes(record2.hash, "hash", 32);
     const client = await clientFor(tx.chainId);
     let replacementReason;
     const receipt = await client.waitForTransactionReceipt({
-      hash,
+      hash: hash2,
       ...wait,
       onReplaced: ({ reason }) => {
         replacementReason = reason;
       }
     });
-    const base = { submittedHash: hash, hash: receipt.transactionHash, receipt };
-    if (replacementReason || receipt.transactionHash.toLowerCase() !== hash.toLowerCase())
+    const base = { submittedHash: hash2, hash: receipt.transactionHash, receipt };
+    if (replacementReason || receipt.transactionHash.toLowerCase() !== hash2.toLowerCase())
       return {
         ...base,
         status: "replaced",
         ...replacementReason === void 0 ? {} : { replacementReason }
       };
     if (receipt.status === "reverted") return { ...base, status: "reverted" };
-    const actual = await client.getTransaction({ hash });
+    const actual = await client.getTransaction({ hash: hash2 });
     const actualTo = actual.to ?? void 0;
     const sameTarget = tx.to === void 0 ? actualTo === void 0 : actualTo !== void 0 && sameIssuerAddress(tx.to, actualTo);
-    const verified = actual.hash.toLowerCase() === hash.toLowerCase() && sameIssuerAddress(actual.from, tx.from) && sameTarget && actual.input.toLowerCase() === tx.data.toLowerCase() && actual.value === tx.value && (actual.chainId === void 0 || actual.chainId === tx.chainId) && (tx.to !== void 0 || !!receipt.contractAddress);
+    const verified = actual.hash.toLowerCase() === hash2.toLowerCase() && sameIssuerAddress(actual.from, tx.from) && sameTarget && actual.input.toLowerCase() === tx.data.toLowerCase() && actual.value === tx.value && (actual.chainId === void 0 || actual.chainId === tx.chainId) && (tx.to !== void 0 || !!receipt.contractAddress);
     return { ...base, status: verified ? "confirmed" : "unverified" };
   }
   async function waitForDeployment(record2, wait) {
@@ -7887,10 +8269,10 @@ function createIssuersNamespace(options = {}) {
   }
   async function getApprovedPolicies(input) {
     const client = await clientFor(input.chainId);
-    const address4 = issuerAddress(input.policyRegistry, "policyRegistry");
+    const address5 = issuerAddress(input.policyRegistry, "policyRegistry");
     const policyType = issuerBytes(input.policyType, "policyType", 32);
     const { number: blockNumber } = await client.getBlock({ blockTag: "latest" });
-    const req = { address: address4, abi: issuerPolicyRegistryAbi, blockNumber };
+    const req = { address: address5, abi: issuerPolicyRegistryAbi, blockNumber };
     const implementations = await client.readContract({
       ...req,
       functionName: "implementationsOf",
@@ -7990,6 +8372,7 @@ function createIssuersNamespace(options = {}) {
     };
   }
   return {
+    discoverDeployment,
     prepareDeployment,
     simulateDeployment,
     sendDeployment,
@@ -8182,21 +8565,21 @@ async function waitForSandboxUserFunding(publicClient, submission, wait) {
   };
   if (tx.value === 0n || tx.data !== "0x")
     invalid("Funding must be a positive native transfer with empty data.");
-  const hash = issuerBytes(submission.hash, "hash", 32);
+  const hash2 = issuerBytes(submission.hash, "hash", 32);
   const options = waitOptions(wait);
   await checkChain(publicClient, tx.chainId);
   let replacementReason;
   const receipt = structuredClone(
     await publicClient.waitForTransactionReceipt({
-      hash,
+      hash: hash2,
       ...options,
       onReplaced: ({ reason }) => {
         replacementReason = reason;
       }
     })
   );
-  const base = { submittedHash: hash, hash: receipt.transactionHash, receipt };
-  if (replacementReason || receipt.transactionHash.toLowerCase() !== hash.toLowerCase())
+  const base = { submittedHash: hash2, hash: receipt.transactionHash, receipt };
+  if (replacementReason || receipt.transactionHash.toLowerCase() !== hash2.toLowerCase())
     return {
       ...base,
       status: "replaced",
@@ -8205,11 +8588,11 @@ async function waitForSandboxUserFunding(publicClient, submission, wait) {
   if (receipt.status === "reverted") return { ...base, status: "reverted" };
   let actual;
   try {
-    actual = await publicClient.getTransaction({ hash });
+    actual = await publicClient.getTransaction({ hash: hash2 });
   } catch {
     return { ...base, status: "unverified" };
   }
-  const verified = actual.hash.toLowerCase() === hash.toLowerCase() && sameIssuerAddress(actual.from, tx.from) && actual.to !== null && sameIssuerAddress(actual.to, tx.to) && actual.input === "0x" && actual.value === tx.value && (actual.chainId === void 0 || actual.chainId === tx.chainId);
+  const verified = actual.hash.toLowerCase() === hash2.toLowerCase() && sameIssuerAddress(actual.from, tx.from) && actual.to !== null && sameIssuerAddress(actual.to, tx.to) && actual.input === "0x" && actual.value === tx.value && (actual.chainId === void 0 || actual.chainId === tx.chainId);
   return { ...base, status: verified ? "confirmed" : "unverified" };
 }
 function sameTransaction(a, b) {
@@ -8327,15 +8710,15 @@ async function createSandboxUser(publicClient, params) {
       await checkChain(publicClient, chainId4);
       if (!sameIssuerAddress(await walletAddress(sponsor, chainId4), from))
         invalid("Selected funding account changed before sending.");
-      const hash = await sponsor.sendTransaction({
+      const hash2 = await sponsor.sendTransaction({
         account: sponsor.account ?? from,
         chain: sponsor.chain ?? chain2,
         to: account.address,
         value: transaction.value,
         data: "0x"
       });
-      state.funding = { kind: "funding", hash, transaction };
-      state.pending.hash = hash;
+      state.funding = { kind: "funding", hash: hash2, transaction };
+      state.pending.hash = hash2;
       state.stage = "waiting-funding";
       await save();
       const result = await waitForSandboxUserFunding(publicClient, state.funding, wait);
@@ -8590,15 +8973,15 @@ async function transferSandboxUser(publicClient, params) {
       await checkChain2(publicClient, chainId4);
       if (!sameIssuerAddress(await fundingAccount(sponsor, chainId4), from))
         invalid("Selected funding account changed before sending.");
-      const hash = await sponsor.sendTransaction({
+      const hash2 = await sponsor.sendTransaction({
         account: sendAccount,
         chain: chain2,
         to: wallet,
         value: transaction.value,
         data: "0x"
       });
-      state.funding = { kind: "funding", hash, transaction: structuredClone(transaction) };
-      state.pending.hash = hash;
+      state.funding = { kind: "funding", hash: hash2, transaction: structuredClone(transaction) };
+      state.pending.hash = hash2;
       state.stage = "waiting-funding";
       await save();
       const result2 = structuredClone(
@@ -9065,7 +9448,7 @@ function createSandboxWalletLinksNamespace(options) {
         );
       const tx = buildSandboxWalletLinkTransaction(intent, signature);
       attempted = true;
-      const hash = await wallet.sendTransaction({
+      const hash2 = await wallet.sendTransaction({
         account: wallet.account ?? intent.existingWallet,
         chain: wallet.chain ?? viem.defineChain({
           id: intent.chainId,
@@ -9078,7 +9461,7 @@ function createSandboxWalletLinksNamespace(options) {
         value: 0n,
         nonce: progress.senderNonce
       });
-      progress.hash = issuerBytes(hash, "transaction hash", 32);
+      progress.hash = issuerBytes(hash2, "transaction hash", 32);
       progress.stage = "submitted";
       await save();
       return structuredClone(progress);
@@ -9118,7 +9501,7 @@ function createSandboxWalletLinksNamespace(options) {
     if (input.kind !== "wallet-link" || !["submitted", "complete"].includes(input.stage))
       invalid("Expected a submitted wallet link.");
     const intent = validateSandboxWalletLinkIntent(input.intent);
-    const hash = issuerBytes(input.hash, "hash", 32);
+    const hash2 = issuerBytes(input.hash, "hash", 32);
     const senderNonce = input.senderNonce;
     if (!Number.isSafeInteger(senderNonce) || senderNonce < 0)
       invalid("senderNonce must be a nonnegative safe integer.");
@@ -9127,7 +9510,7 @@ function createSandboxWalletLinksNamespace(options) {
     let replacementReason;
     const receipt = structuredClone(
       await client.waitForTransactionReceipt({
-        hash,
+        hash: hash2,
         ...waitOptions3,
         onReplaced: ({ reason }) => {
           replacementReason = reason;
@@ -9135,22 +9518,22 @@ function createSandboxWalletLinksNamespace(options) {
       })
     );
     await clientFor(intent.chainId);
-    const base = { submittedHash: hash, hash: receipt.transactionHash, receipt };
+    const base = { submittedHash: hash2, hash: receipt.transactionHash, receipt };
     let exactTransaction = false;
     let result = { ...base, status: "unverified" };
-    if (replacementReason || receipt.transactionHash.toLowerCase() !== hash.toLowerCase())
+    if (replacementReason || receipt.transactionHash.toLowerCase() !== hash2.toLowerCase())
       result = { ...base, status: "replaced", ...replacementReason ? { replacementReason } : {} };
     else if (receipt.status === "reverted") result = { ...base, status: "reverted" };
     else if (receipt.status === "success") {
       try {
-        const tx = await client.getTransaction({ hash });
+        const tx = await client.getTransaction({ hash: hash2 });
         await clientFor(intent.chainId);
         const decoded = viem.decodeFunctionData({ abi: sandboxWalletLinkAbi, data: tx.input });
-        const matches = sameIssuerAddress(receipt.from, intent.existingWallet) && receipt.to !== null && sameIssuerAddress(receipt.to, intent.registryAddress) && tx.blockHash === receipt.blockHash && tx.blockNumber === receipt.blockNumber && tx.hash.toLowerCase() === hash.toLowerCase() && tx.chainId === intent.chainId && sameIssuerAddress(tx.from, intent.existingWallet) && tx.to !== null && sameIssuerAddress(tx.to, intent.registryAddress) && tx.value === 0n && (senderNonce === void 0 || tx.nonce === senderNonce) && decoded.functionName === "sandboxLinkWallet" && sameIssuerAddress(decoded.args[0], intent.newWallet) && decoded.args[1].toLowerCase() === intent.nonce.toLowerCase() && decoded.args[2] === intent.deadline;
+        const matches = sameIssuerAddress(receipt.from, intent.existingWallet) && receipt.to !== null && sameIssuerAddress(receipt.to, intent.registryAddress) && tx.blockHash === receipt.blockHash && tx.blockNumber === receipt.blockNumber && tx.hash.toLowerCase() === hash2.toLowerCase() && tx.chainId === intent.chainId && sameIssuerAddress(tx.from, intent.existingWallet) && tx.to !== null && sameIssuerAddress(tx.to, intent.registryAddress) && tx.value === 0n && (senderNonce === void 0 || tx.nonce === senderNonce) && decoded.functionName === "sandboxLinkWallet" && sameIssuerAddress(decoded.args[0], intent.newWallet) && decoded.args[1].toLowerCase() === intent.nonce.toLowerCase() && decoded.args[2] === intent.deadline;
         exactTransaction = matches;
         if (matches)
           for (const log of receipt.logs) {
-            if (!sameIssuerAddress(log.address, intent.registryAddress) || log.removed || log.blockHash !== receipt.blockHash || log.blockNumber !== receipt.blockNumber || log.transactionHash?.toLowerCase() !== hash.toLowerCase())
+            if (!sameIssuerAddress(log.address, intent.registryAddress) || log.removed || log.blockHash !== receipt.blockHash || log.blockNumber !== receipt.blockNumber || log.transactionHash?.toLowerCase() !== hash2.toLowerCase())
               continue;
             try {
               const { args } = viem.decodeEventLog({
@@ -9171,14 +9554,14 @@ function createSandboxWalletLinksNamespace(options) {
     const current = pending.get(keyFor(intent));
     if (current?.hash === void 0 && current?.stage === "sending" && result.status === "reverted") {
       try {
-        const tx = await client.getTransaction({ hash });
+        const tx = await client.getTransaction({ hash: hash2 });
         await clientFor(intent.chainId);
         const decoded = viem.decodeFunctionData({ abi: sandboxWalletLinkAbi, data: tx.input });
-        exactTransaction = tx.hash.toLowerCase() === hash.toLowerCase() && tx.chainId === intent.chainId && sameIssuerAddress(tx.from, intent.existingWallet) && tx.to !== null && sameIssuerAddress(tx.to, intent.registryAddress) && tx.value === 0n && tx.nonce === senderNonce && tx.blockHash === receipt.blockHash && tx.blockNumber === receipt.blockNumber && decoded.functionName === "sandboxLinkWallet" && sameIssuerAddress(decoded.args[0], intent.newWallet) && decoded.args[1].toLowerCase() === intent.nonce.toLowerCase() && decoded.args[2] === intent.deadline;
+        exactTransaction = tx.hash.toLowerCase() === hash2.toLowerCase() && tx.chainId === intent.chainId && sameIssuerAddress(tx.from, intent.existingWallet) && tx.to !== null && sameIssuerAddress(tx.to, intent.registryAddress) && tx.value === 0n && tx.nonce === senderNonce && tx.blockHash === receipt.blockHash && tx.blockNumber === receipt.blockNumber && decoded.functionName === "sandboxLinkWallet" && sameIssuerAddress(decoded.args[0], intent.newWallet) && decoded.args[1].toLowerCase() === intent.nonce.toLowerCase() && decoded.args[2] === intent.deadline;
       } catch {
       }
     }
-    if (current && pending.get(keyFor(intent)) === current && sameIntent(current.intent, intent) && (current.hash?.toLowerCase() === hash.toLowerCase() || current.hash === void 0 && current.stage === "sending" && current.senderNonce === senderNonce && exactTransaction) && (result.status === "confirmed" || result.status === "reverted" || result.status === "replaced"))
+    if (current && pending.get(keyFor(intent)) === current && sameIntent(current.intent, intent) && (current.hash?.toLowerCase() === hash2.toLowerCase() || current.hash === void 0 && current.stage === "sending" && current.senderNonce === senderNonce && exactTransaction) && (result.status === "confirmed" || result.status === "reverted" || result.status === "replaced"))
       pending.delete(keyFor(intent));
     return result;
   }
@@ -9683,6 +10066,7 @@ exports.prepareSandboxUser = prepareSandboxUser;
 exports.purchasePaymentTokenAbi = purchasePaymentTokenAbi;
 exports.purchaseRegistryAbi = purchaseRegistryAbi;
 exports.purchaseSecurityTokenAbi = purchaseSecurityTokenAbi;
+exports.resolveIssuerDeployment = resolveIssuerDeployment;
 exports.resolveSandboxUserTraits = resolveSandboxUserTraits;
 exports.restoreSandboxLinkedWallet = restoreSandboxLinkedWallet;
 exports.restoreSandboxUserWallet = restoreSandboxUserWallet;