opacity-issuer-core 0.2.1 → 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(
@@ -8641,6 +9024,777 @@ async function transferSandboxUser(publicClient, params) {
     active2.delete(key);
   }
 }
+var sandboxWalletLinkAbi = [
+  {
+    type: "function",
+    name: "sandboxWalletLinkingVersion",
+    stateMutability: "pure",
+    inputs: [],
+    outputs: [{ type: "uint256" }]
+  },
+  {
+    type: "function",
+    name: "sandboxWalletLinkUsed",
+    stateMutability: "view",
+    inputs: [{ name: "digest", type: "bytes32" }],
+    outputs: [{ type: "bool" }]
+  },
+  {
+    type: "function",
+    name: "sandboxLinkWallet",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "newWallet", type: "address" },
+      { name: "nonce", type: "bytes32" },
+      { name: "deadline", type: "uint64" },
+      { name: "newWalletSignature", type: "bytes" }
+    ],
+    outputs: []
+  },
+  {
+    type: "event",
+    name: "SandboxWalletLinked",
+    anonymous: false,
+    inputs: [
+      { name: "existingWallet", type: "address", indexed: true },
+      { name: "newWallet", type: "address", indexed: true },
+      { name: "userId", type: "bytes32", indexed: true },
+      { name: "nonce", type: "bytes32", indexed: false },
+      { name: "deadline", type: "uint64", indexed: false }
+    ]
+  }
+];
+var sandboxWalletLinkTypes = {
+  SandboxWalletLink: [
+    { name: "existingWallet", type: "address" },
+    { name: "newWallet", type: "address" },
+    { name: "userId", type: "bytes32" },
+    { name: "nonce", type: "bytes32" },
+    { name: "deadline", type: "uint64" }
+  ]
+};
+var SandboxWalletLinkError = class extends Error {
+  constructor(code, message, progress) {
+    super(message);
+    this.code = code;
+    this.progress = progress;
+    this.name = "SandboxWalletLinkError";
+  }
+  code;
+  progress;
+};
+function walletLinkData(value, label, keys) {
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    invalid(`${label} must be a plain object.`);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !keys.includes(key) || !descriptor.enumerable || !Object.hasOwn(descriptor, "value"))
+      invalid(`${label} must contain only recognized enumerable data fields.`);
+  }
+}
+var fields = [
+  "chainId",
+  "registryAddress",
+  "existingWallet",
+  "newWallet",
+  "nonce",
+  "deadline",
+  "checkedAssets"
+];
+function validateSandboxWalletLinkParams(input) {
+  walletLinkData(input, "Wallet link", fields);
+  if (!Array.isArray(input.checkedAssets) || input.checkedAssets.length === 0)
+    invalid("checkedAssets must include every relevant fund token.");
+  for (const key of Reflect.ownKeys(input.checkedAssets)) {
+    if (key === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(input.checkedAssets, key);
+    if (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= input.checkedAssets.length || !descriptor.enumerable || !Object.hasOwn(descriptor, "value"))
+      invalid("checkedAssets must contain data entries only.");
+  }
+  if (Object.keys(input.checkedAssets).length !== input.checkedAssets.length)
+    invalid("checkedAssets must not contain missing entries.");
+  const seen = /* @__PURE__ */ new Set();
+  const checkedAssets = input.checkedAssets.map((asset) => {
+    walletLinkData(asset, "Checked asset", ["token", "tokenId"]);
+    const token = issuerAddress(asset.token, "token");
+    const tokenId = issuerUint(asset.tokenId, "tokenId");
+    const key = `${token.toLowerCase()}:${tokenId}`;
+    if (seen.has(key)) invalid("checkedAssets must not contain duplicates.");
+    seen.add(key);
+    return Object.freeze({ token, tokenId });
+  });
+  const result = {
+    checkedAssets: Object.freeze(checkedAssets),
+    chainId: issuerChainId(input.chainId),
+    registryAddress: issuerAddress(input.registryAddress, "registryAddress"),
+    existingWallet: issuerAddress(input.existingWallet, "existingWallet"),
+    newWallet: issuerAddress(input.newWallet, "newWallet"),
+    nonce: issuerBytes(input.nonce, "nonce", 32),
+    deadline: issuerUint(input.deadline, "deadline")
+  };
+  if (result.deadline === 0n || result.deadline >= 1n << 64n)
+    invalid("deadline must be a positive uint64 timestamp.");
+  if (sameIssuerAddress(result.existingWallet, result.newWallet))
+    invalid("Choose a different wallet to link.");
+  return Object.freeze(result);
+}
+function validateSandboxWalletLinkIntent(input) {
+  walletLinkData(input, "Wallet link intent", [...fields, "userId"]);
+  const { userId, ...params } = input;
+  const id = issuerBytes(userId, "userId", 32);
+  if (id.toLowerCase() === viem.zeroHash) invalid("The existing wallet must have a user identity.");
+  return Object.freeze({ ...validateSandboxWalletLinkParams(params), userId: id });
+}
+function buildSandboxWalletLinkTypedData(input) {
+  const { chainId: chainId4, registryAddress, existingWallet, newWallet, userId, nonce, deadline } = validateSandboxWalletLinkIntent(input);
+  const message = { existingWallet, newWallet, userId, nonce, deadline };
+  return {
+    domain: {
+      name: "AllowlistRegistry",
+      version: "1",
+      chainId: chainId4,
+      verifyingContract: registryAddress
+    },
+    types: sandboxWalletLinkTypes,
+    primaryType: "SandboxWalletLink",
+    message
+  };
+}
+function buildSandboxWalletLinkTransaction(input, signature) {
+  const intent = validateSandboxWalletLinkIntent(input);
+  return {
+    from: intent.existingWallet,
+    to: intent.registryAddress,
+    chainId: intent.chainId,
+    value: 0n,
+    data: viem.encodeFunctionData({
+      abi: sandboxWalletLinkAbi,
+      functionName: "sandboxLinkWallet",
+      args: [intent.newWallet, intent.nonce, intent.deadline, issuerBytes(signature, "signature")]
+    })
+  };
+}
+function walletLinkWaitOptions(value = {}) {
+  walletLinkData(value, "wait", ["confirmations", "timeout", "pollingInterval"]);
+  for (const n of Object.values(value))
+    if (n !== void 0 && (!Number.isSafeInteger(n) || n <= 0))
+      invalid("Wait options must be positive safe integers.");
+  return { ...value };
+}
+async function checkChain3(client, chainId4) {
+  if (client.chain && client.chain.id !== chainId4 || await client.getChainId() !== chainId4)
+    invalid("The wallet, RPC and requested chains must match.");
+}
+async function checkWallet(wallet, chainId4, expected) {
+  if (!wallet) invalid("Wallet linking requires a wallet client.");
+  await checkChain3(wallet, chainId4);
+  const selected = wallet.account?.type === "local" ? wallet.account.address : (await wallet.getAddresses())[0];
+  if (!selected || !sameIssuerAddress(selected, expected) || wallet.account && !sameIssuerAddress(wallet.account.address, selected))
+    invalid("The selected wallet changed. Review the link with the expected wallet.");
+  return wallet;
+}
+function absentCapability(error) {
+  if (!(error instanceof viem.BaseError)) return false;
+  return !!error.walk(
+    (cause) => cause instanceof viem.ContractFunctionRevertedError || cause instanceof viem.ContractFunctionZeroDataError
+  );
+}
+function rejected(error) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let e = error; e && typeof e === "object" && !seen.has(e); e = e.cause) {
+    seen.add(e);
+    if (e.code === 4001) return true;
+  }
+  return false;
+}
+var pending = /* @__PURE__ */ new Map();
+var keyFor = (i) => `${i.chainId}:${i.existingWallet.toLowerCase()}`;
+var sameIntent = (a, b) => viem.hashTypedData(buildSandboxWalletLinkTypedData(a)) === viem.hashTypedData(buildSandboxWalletLinkTypedData(b));
+function createSandboxWalletLinksNamespace(options) {
+  async function clientFor(chainId4) {
+    if (options.chainId !== void 0 && options.chainId !== chainId4)
+      invalid("Configured and requested wallet linking chains must match.");
+    await checkChain3(options.publicClient, chainId4);
+    return options.publicClient;
+  }
+  async function prepareWalletLink(input) {
+    const params = validateSandboxWalletLinkParams(input);
+    const client = await clientFor(params.chainId);
+    const block = await client.getBlock();
+    const blockNumber = block.number;
+    const context = { address: params.registryAddress, blockNumber };
+    let supported = false;
+    try {
+      supported = await client.readContract({
+        ...context,
+        abi: sandboxWalletLinkAbi,
+        functionName: "sandboxWalletLinkingVersion"
+      }) === 1n;
+    } catch (error) {
+      if (!absentCapability(error)) throw error;
+    }
+    const [paused, allowed, userId, targetUserId, targetStatus, targetIssuer, sourceExpiry] = await Promise.all([
+      client.readContract({ ...context, abi: issuerRegistryAbi, functionName: "paused" }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "isAllowed",
+        args: [params.existingWallet]
+      }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "getUserId",
+        args: [params.existingWallet]
+      }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "getUserId",
+        args: [params.newWallet]
+      }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "getEntryStatus",
+        args: [params.newWallet]
+      }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "isAuthorizedIssuer",
+        args: [params.newWallet]
+      }),
+      client.readContract({
+        ...context,
+        abi: issuerRegistryAbi,
+        functionName: "getEntryExpiry",
+        args: [params.existingWallet]
+      })
+    ]);
+    const intent = { ...params, userId };
+    const blockers = [];
+    if (!supported) blockers.push("unsupported-wallet-linking");
+    if (paused) blockers.push("registry-paused");
+    if (!allowed) blockers.push("source-not-approved");
+    if (userId === viem.zeroHash) blockers.push("source-identity-missing");
+    if (targetUserId !== viem.zeroHash) blockers.push("target-already-linked");
+    if (targetStatus !== 0) blockers.push("target-not-fresh");
+    if (targetIssuer) blockers.push("target-is-issuer");
+    for (const asset of params.checkedAssets) {
+      const registry = await client.readContract({
+        address: asset.token,
+        blockNumber,
+        abi: issuerTokenAbi,
+        functionName: "allowlistRegistry"
+      });
+      if (!sameIssuerAddress(registry, params.registryAddress))
+        invalid("A checked fund token uses a different registry.");
+      const balance = await client.readContract({
+        address: asset.token,
+        blockNumber,
+        abi: issuerTokenAbi,
+        functionName: "balanceOf",
+        args: [params.newWallet, asset.tokenId]
+      });
+      if (balance !== 0n && !blockers.includes("target-holds-assets"))
+        blockers.push("target-holds-assets");
+    }
+    if (params.deadline < block.timestamp) blockers.push("consent-expired");
+    if (supported && userId !== viem.zeroHash && await client.readContract({
+      ...context,
+      abi: sandboxWalletLinkAbi,
+      functionName: "sandboxWalletLinkUsed",
+      args: [viem.hashTypedData(buildSandboxWalletLinkTypedData(intent))]
+    }))
+      blockers.push("consent-used");
+    await clientFor(params.chainId);
+    return {
+      intent: Object.freeze(intent),
+      blockNumber,
+      sourceExpiry,
+      blockers,
+      ready: blockers.length === 0
+    };
+  }
+  async function fresh(input) {
+    const intent = validateSandboxWalletLinkIntent(input);
+    const { userId: _id, ...params } = intent;
+    const prepared = await prepareWalletLink(params);
+    if (prepared.blockers.length)
+      throw new SandboxWalletLinkError(
+        "blocked",
+        `Wallet linking is blocked: ${prepared.blockers.join(", ")}.`
+      );
+    if (!sameIntent(intent, prepared.intent))
+      throw new SandboxWalletLinkError(
+        "stale-intent",
+        "The existing wallet identity changed. Prepare and review a new link."
+      );
+    return prepared;
+  }
+  async function signWalletLink(input, newWalletClient) {
+    const intent = validateSandboxWalletLinkIntent(input);
+    await fresh(intent);
+    const wallet = await checkWallet(newWalletClient, intent.chainId, intent.newWallet);
+    let signature;
+    try {
+      signature = await wallet.signTypedData({
+        ...buildSandboxWalletLinkTypedData(intent),
+        account: wallet.account ?? intent.newWallet
+      });
+    } catch (error) {
+      throw new SandboxWalletLinkError(
+        rejected(error) ? "rejected" : "blocked",
+        "Wallet consent was not signed. No transaction was sent."
+      );
+    }
+    await checkWallet(wallet, intent.chainId, intent.newWallet);
+    return issuerBytes(signature, "signature");
+  }
+  async function preflightWalletLink(input, signature) {
+    const intent = validateSandboxWalletLinkIntent(input);
+    const transaction = buildSandboxWalletLinkTransaction(intent, signature);
+    const prepared = await fresh(intent);
+    const client = await clientFor(intent.chainId);
+    try {
+      await client.call({
+        account: transaction.from,
+        to: transaction.to,
+        data: transaction.data,
+        value: 0n
+      });
+    } catch (error) {
+      const reverted = error instanceof viem.BaseError && !!error.walk(
+        (cause) => cause instanceof viem.ContractFunctionRevertedError || cause instanceof viem.ExecutionRevertedError
+      );
+      throw new SandboxWalletLinkError(
+        reverted ? "blocked" : "check-unavailable",
+        reverted ? "This wallet link was rejected. Check the consent and current wallet eligibility." : "The connection could not check this wallet link. Try the check again before sending."
+      );
+    }
+    let gas;
+    try {
+      const [estimatedGas, gasPrice, nativeBalance] = await Promise.all([
+        client.estimateGas({
+          account: transaction.from,
+          to: transaction.to,
+          data: transaction.data,
+          value: 0n
+        }),
+        client.getGasPrice(),
+        client.getBalance({ address: intent.existingWallet })
+      ]);
+      const estimatedCost = estimatedGas * gasPrice;
+      gas = { estimatedGas, gasPrice, estimatedCost, nativeBalance };
+      if (nativeBalance < estimatedCost || nativeBalance === 0n)
+        throw new SandboxWalletLinkError(
+          "insufficient-gas",
+          "The existing wallet needs more test ETH to link this wallet."
+        );
+    } catch (error) {
+      if (error instanceof SandboxWalletLinkError) throw error;
+      throw new SandboxWalletLinkError(
+        "check-unavailable",
+        "The connection could not estimate the network fee. Check again before sending."
+      );
+    }
+    await clientFor(intent.chainId);
+    return { ...prepared, gas };
+  }
+  async function sendWalletLink(input) {
+    walletLinkData(input, "Send wallet link", ["intent", "signature", "persist"]);
+    const intent = validateSandboxWalletLinkIntent(input.intent);
+    const signature = issuerBytes(input.signature, "signature");
+    const persist = input.persist;
+    if (typeof persist !== "function")
+      invalid("persist must save wallet linking progress before sending.");
+    const key = keyFor(intent);
+    if (pending.has(key))
+      throw new SandboxWalletLinkError(
+        "send-in-progress",
+        "Check the existing wallet link before starting another.",
+        structuredClone(pending.get(key))
+      );
+    const progress = { kind: "wallet-link", intent, stage: "prepared" };
+    pending.set(key, structuredClone(progress));
+    let attempted = false;
+    let persistence = false;
+    const save = async () => {
+      pending.set(key, structuredClone(progress));
+      persistence = true;
+      await persist(structuredClone(progress));
+      persistence = false;
+    };
+    try {
+      await save();
+      await preflightWalletLink(intent, signature);
+      await checkWallet(options.walletClient, intent.chainId, intent.existingWallet);
+      progress.senderNonce = await (await clientFor(intent.chainId)).getTransactionCount({ address: intent.existingWallet, blockTag: "pending" });
+      if (!Number.isSafeInteger(progress.senderNonce) || progress.senderNonce < 0)
+        invalid("The RPC returned an invalid transaction nonce.");
+      progress.stage = "sending";
+      await save();
+      await preflightWalletLink(intent, signature);
+      const wallet = await checkWallet(options.walletClient, intent.chainId, intent.existingWallet);
+      const client = await clientFor(intent.chainId);
+      if (await client.getTransactionCount({
+        address: intent.existingWallet,
+        blockTag: "pending"
+      }) !== progress.senderNonce)
+        throw new SandboxWalletLinkError(
+          "stale-intent",
+          "The existing wallet has another pending transaction. Check it before reviewing a new link."
+        );
+      const tx = buildSandboxWalletLinkTransaction(intent, signature);
+      attempted = true;
+      const hash2 = await wallet.sendTransaction({
+        account: wallet.account ?? intent.existingWallet,
+        chain: wallet.chain ?? viem.defineChain({
+          id: intent.chainId,
+          name: `Sandbox ${intent.chainId}`,
+          nativeCurrency: { name: "Native", symbol: "NATIVE", decimals: 18 },
+          rpcUrls: { default: { http: [] } }
+        }),
+        to: tx.to,
+        data: tx.data,
+        value: 0n,
+        nonce: progress.senderNonce
+      });
+      progress.hash = issuerBytes(hash2, "transaction hash", 32);
+      progress.stage = "submitted";
+      await save();
+      return structuredClone(progress);
+    } catch (error) {
+      if (!attempted || !progress.hash && !persistence && rejected(error)) {
+        pending.delete(key);
+        progress.stage = "rejected";
+        try {
+          await persist(structuredClone(progress));
+        } catch {
+        }
+        if (error instanceof SandboxWalletLinkError)
+          throw new SandboxWalletLinkError(error.code, error.message, structuredClone(progress));
+        throw new SandboxWalletLinkError(
+          persistence ? "persistence-failed" : "rejected",
+          persistence ? "Wallet link progress could not be saved. No transaction was sent." : "Wallet linking stopped before a transaction was submitted.",
+          structuredClone(progress)
+        );
+      }
+      pending.set(key, structuredClone(progress));
+      throw new SandboxWalletLinkError(
+        "uncertain",
+        "Check the existing transaction before trying another wallet link.",
+        structuredClone(progress)
+      );
+    }
+  }
+  async function waitForWalletLink(input, wait = {}) {
+    walletLinkData(input, "Wallet link submission", [
+      "kind",
+      "intent",
+      "stage",
+      "hash",
+      "senderNonce",
+      "result"
+    ]);
+    if (input.kind !== "wallet-link" || !["submitted", "complete"].includes(input.stage))
+      invalid("Expected a submitted wallet link.");
+    const intent = validateSandboxWalletLinkIntent(input.intent);
+    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.");
+    const client = await clientFor(intent.chainId);
+    const waitOptions3 = walletLinkWaitOptions(wait);
+    let replacementReason;
+    const receipt = structuredClone(
+      await client.waitForTransactionReceipt({
+        hash: hash2,
+        ...waitOptions3,
+        onReplaced: ({ reason }) => {
+          replacementReason = reason;
+        }
+      })
+    );
+    await clientFor(intent.chainId);
+    const base = { submittedHash: hash2, hash: receipt.transactionHash, receipt };
+    let exactTransaction = false;
+    let result = { ...base, status: "unverified" };
+    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: 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() === 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() !== hash2.toLowerCase())
+              continue;
+            try {
+              const { args } = viem.decodeEventLog({
+                abi: sandboxWalletLinkAbi,
+                eventName: "SandboxWalletLinked",
+                data: log.data,
+                topics: log.topics,
+                strict: true
+              });
+              if (sameIssuerAddress(args.existingWallet, intent.existingWallet) && sameIssuerAddress(args.newWallet, intent.newWallet) && args.userId.toLowerCase() === intent.userId.toLowerCase() && args.nonce.toLowerCase() === intent.nonce.toLowerCase() && args.deadline === intent.deadline)
+                result = { ...base, status: "confirmed" };
+            } catch {
+            }
+          }
+      } catch {
+      }
+    }
+    const current = pending.get(keyFor(intent));
+    if (current?.hash === void 0 && current?.stage === "sending" && result.status === "reverted") {
+      try {
+        const tx = await client.getTransaction({ hash: hash2 });
+        await clientFor(intent.chainId);
+        const decoded = viem.decodeFunctionData({ abi: sandboxWalletLinkAbi, data: tx.input });
+        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() === 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;
+  }
+  return {
+    prepareWalletLink,
+    signWalletLink,
+    preflightWalletLink,
+    sendWalletLink,
+    waitForWalletLink
+  };
+}
+var SandboxLinkedWalletCreationError = class extends Error {
+  constructor(progress) {
+    super(
+      "Wallet creation stopped. Recover the saved wallet and check its pending link before another attempt."
+    );
+    this.progress = progress;
+    this.name = "SandboxLinkedWalletCreationError";
+    Object.defineProperty(this, "progress", { enumerable: false });
+  }
+  progress;
+};
+async function createSandboxLinkedWallet(publicClient, input) {
+  walletLinkData(input, "Create linked wallet", [
+    "chainId",
+    "registryAddress",
+    "existingWallet",
+    "checkedAssets",
+    "sourceWalletClient",
+    "persist",
+    "privateKey",
+    "nonce",
+    "deadline",
+    "wait"
+  ]);
+  const chainId4 = issuerChainId(input.chainId);
+  const registryAddress = issuerAddress(input.registryAddress, "registryAddress");
+  const existingWallet = issuerAddress(input.existingWallet, "existingWallet");
+  const persist = input.persist;
+  if (typeof persist !== "function") invalid("persist must save the new wallet before sending.");
+  if (!input.sourceWalletClient || typeof input.sourceWalletClient.sendTransaction !== "function")
+    invalid("sourceWalletClient is required.");
+  const sourceWalletClient = input.sourceWalletClient;
+  const privateKey = input.privateKey === void 0 ? accounts.generatePrivateKey() : issuerBytes(input.privateKey, "privateKey", 32);
+  let account;
+  try {
+    account = accounts.privateKeyToAccount(privateKey);
+  } catch {
+    invalid("privateKey must be a valid test-wallet private key.");
+  }
+  const nonce = input.nonce === void 0 ? accounts.generatePrivateKey() : issuerBytes(input.nonce, "nonce", 32);
+  const wait = walletLinkWaitOptions(input.wait);
+  const provisional = validateSandboxWalletLinkParams({
+    chainId: chainId4,
+    registryAddress,
+    existingWallet,
+    newWallet: account.address,
+    checkedAssets: input.checkedAssets,
+    nonce,
+    deadline: input.deadline ?? 1n
+  });
+  const explicitDeadline = input.deadline;
+  const links = createSandboxWalletLinksNamespace({
+    publicClient,
+    walletClient: sourceWalletClient,
+    chainId: chainId4
+  });
+  const deadline = explicitDeadline ?? (await publicClient.getBlock()).timestamp + 900n;
+  const prepared = await links.prepareWalletLink({ ...provisional, deadline });
+  if (!prepared.ready)
+    throw new SandboxWalletLinkError(
+      "blocked",
+      `Wallet linking is blocked: ${prepared.blockers.join(", ")}.`
+    );
+  const state = {
+    kind: "linked-wallet",
+    wallet: account.address,
+    existingWallet,
+    privateKey,
+    chainId: chainId4,
+    registryAddress,
+    userId: prepared.intent.userId,
+    stage: "created",
+    link: { kind: "wallet-link", intent: prepared.intent, stage: "prepared" }
+  };
+  const targetWallet = viem.createWalletClient({
+    account,
+    transport: viem.custom({
+      request: async ({ method }) => {
+        if (method === "eth_chainId") return `0x${chainId4.toString(16)}`;
+        throw new Error("Generated wallet transport supports only local signing.");
+      }
+    })
+  });
+  const save = () => persist(structuredClone(state));
+  try {
+    await save();
+    const signature = await links.signWalletLink(prepared.intent, targetWallet);
+    state.stage = "linking";
+    const submission = await links.sendWalletLink({
+      intent: prepared.intent,
+      signature,
+      persist: async (link) => {
+        state.link = structuredClone(link);
+        await save();
+      }
+    });
+    const result = await links.waitForWalletLink(submission, wait);
+    state.link = {
+      ...submission,
+      result,
+      ...result.status === "confirmed" ? { stage: "complete" } : {}
+    };
+    if (result.status !== "confirmed") {
+      await save();
+      throw new Error("Link is not confirmed.");
+    }
+    state.stage = "complete";
+    await save();
+    return structuredClone(state);
+  } catch (error) {
+    if (error instanceof SandboxWalletLinkError && error.progress)
+      state.link = structuredClone(error.progress);
+    throw new SandboxLinkedWalletCreationError(structuredClone(state));
+  }
+}
+function savedData(value, ancestors = /* @__PURE__ */ new Set()) {
+  if (value === null || value === void 0 || ["string", "boolean", "bigint"].includes(typeof value))
+    return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object" || value === null || ancestors.has(value))
+    invalid("Saved wallet must contain acyclic data.");
+  if (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    invalid("Saved wallet must contain plain data.");
+  ancestors.add(value);
+  for (const key of Reflect.ownKeys(value)) {
+    if (Array.isArray(value) && key === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !descriptor.enumerable || !Object.hasOwn(descriptor, "value"))
+      invalid("Saved wallet must contain enumerable data fields.");
+    savedData(descriptor.value, ancestors);
+  }
+  ancestors.delete(value);
+}
+function validateSandboxLinkedWalletProgress(input) {
+  savedData(input);
+  walletLinkData(input, "Saved linked wallet", [
+    "kind",
+    "wallet",
+    "existingWallet",
+    "privateKey",
+    "chainId",
+    "registryAddress",
+    "userId",
+    "stage",
+    "link"
+  ]);
+  if (input.kind !== "linked-wallet" || !["created", "linking", "complete"].includes(input.stage))
+    invalid("Invalid saved linked-wallet state.");
+  walletLinkData(input.link, "Saved wallet link", [
+    "kind",
+    "intent",
+    "stage",
+    "hash",
+    "senderNonce",
+    "result"
+  ]);
+  const intent = validateSandboxWalletLinkIntent(input.link.intent);
+  if (input.link.kind !== "wallet-link" || !["prepared", "sending", "submitted", "rejected", "complete"].includes(input.link.stage))
+    invalid("Invalid saved link journal.");
+  if (input.link.hash !== void 0) issuerBytes(input.link.hash, "hash", 32);
+  if (["submitted", "complete"].includes(input.link.stage) && input.link.hash === void 0)
+    invalid("A submitted link requires its transaction hash.");
+  if (input.link.senderNonce !== void 0 && (!Number.isSafeInteger(input.link.senderNonce) || input.link.senderNonce < 0))
+    invalid("Invalid saved sender nonce.");
+  if (["sending", "submitted", "complete"].includes(input.link.stage) && input.link.senderNonce === void 0)
+    invalid("A pending link requires its sender nonce.");
+  if (input.link.result !== void 0) {
+    const result = input.link.result;
+    walletLinkData(result, "Saved link result", [
+      "status",
+      "submittedHash",
+      "hash",
+      "receipt",
+      "replacementReason"
+    ]);
+    if (!["confirmed", "reverted", "unverified", "replaced"].includes(result.status) || result.submittedHash.toLowerCase() !== input.link.hash?.toLowerCase() || result.receipt.transactionHash.toLowerCase() !== result.hash.toLowerCase())
+      invalid("Saved link result does not match its submission.");
+    issuerBytes(result.hash, "result hash", 32);
+    if (result.status === "confirmed" && (result.hash.toLowerCase() !== result.submittedHash.toLowerCase() || result.receipt.status !== "success"))
+      invalid("Saved confirmed result is inconsistent.");
+  }
+  if (input.stage === "complete" && (input.link.stage !== "complete" || input.link.result?.status !== "confirmed"))
+    invalid("Saved wallet completion requires a confirmed link.");
+  if (input.link.stage === "complete" && input.link.result?.status !== "confirmed")
+    invalid("Saved link completion requires confirmation.");
+  if (issuerChainId(input.chainId) !== intent.chainId || !sameIssuerAddress(
+    issuerAddress(input.registryAddress, "registryAddress"),
+    intent.registryAddress
+  ) || !sameIssuerAddress(issuerAddress(input.wallet, "wallet"), intent.newWallet) || !sameIssuerAddress(
+    issuerAddress(input.existingWallet, "existingWallet"),
+    intent.existingWallet
+  ) || issuerBytes(input.userId, "userId", 32).toLowerCase() !== intent.userId.toLowerCase())
+    invalid("Saved wallet and link identities do not match.");
+  try {
+    if (!sameIssuerAddress(
+      accounts.privateKeyToAccount(issuerBytes(input.privateKey, "privateKey", 32)).address,
+      intent.newWallet
+    ))
+      invalid("Saved key and wallet do not match.");
+  } catch {
+    invalid("Saved key and wallet do not match.");
+  }
+  return structuredClone(input);
+}
+function restoreSandboxLinkedWallet(input, options) {
+  const progress = validateSandboxLinkedWalletProgress(input);
+  if (progress.stage !== "complete")
+    invalid("Check the pending link before restoring this wallet for transactions.");
+  return restoreSandboxUserWallet(
+    {
+      wallet: progress.wallet,
+      privateKey: progress.privateKey,
+      userId: progress.userId,
+      chainId: progress.chainId,
+      registryAddress: progress.registryAddress,
+      stage: "complete",
+      traits: [],
+      submissions: []
+    },
+    options
+  );
+}
 
 Object.defineProperty(exports, "SANDBOX_CHAIN_ID", {
   enumerable: true,
@@ -8830,8 +9984,10 @@ exports.OpacityPurchaseError = OpacityPurchaseError;
 exports.OpacityTransferError = OpacityTransferError;
 exports.SANDBOX_ISSUER_DEPLOYMENT = SANDBOX_ISSUER_DEPLOYMENT;
 exports.SANDBOX_PURCHASE_DEPLOYMENT = SANDBOX_PURCHASE_DEPLOYMENT;
+exports.SandboxLinkedWalletCreationError = SandboxLinkedWalletCreationError;
 exports.SandboxTransferError = SandboxTransferError;
 exports.SandboxUserCreationError = SandboxUserCreationError;
+exports.SandboxWalletLinkError = SandboxWalletLinkError;
 exports.buildAdapterOperation = buildAdapterOperation;
 exports.buildConfigureVaultTransaction = buildConfigureVaultTransaction;
 exports.buildForcedTransferTransaction = buildForcedTransferTransaction;
@@ -8856,6 +10012,8 @@ exports.buildPurchaseWriteRequest = buildPurchaseWriteRequest;
 exports.buildRuleSetOperation = buildRuleSetOperation;
 exports.buildSandboxRegistryOperation = buildSandboxRegistryOperation;
 exports.buildSandboxVaultOperation = buildSandboxVaultOperation;
+exports.buildSandboxWalletLinkTransaction = buildSandboxWalletLinkTransaction;
+exports.buildSandboxWalletLinkTypedData = buildSandboxWalletLinkTypedData;
 exports.buildSetIssuerAdminTransaction = buildSetIssuerAdminTransaction;
 exports.buildSetUserTraitsTransactions = buildSetUserTraitsTransactions;
 exports.buildSetWalletsTransaction = buildSetWalletsTransaction;
@@ -8869,7 +10027,9 @@ exports.createPolicyAttachment = createPolicyAttachment;
 exports.createPolicyBatch = createPolicyBatch;
 exports.createPolicyReplacementBatch = createPolicyReplacementBatch;
 exports.createPurchasesNamespace = createPurchasesNamespace;
+exports.createSandboxLinkedWallet = createSandboxLinkedWallet;
 exports.createSandboxUser = createSandboxUser;
+exports.createSandboxWalletLinksNamespace = createSandboxWalletLinksNamespace;
 exports.createTransfersNamespace = createTransfersNamespace;
 exports.encodeAllowedTransfereeConfig = encodeAllowedTransfereeConfig;
 exports.encodeCeilingBalanceConfig = encodeCeilingBalanceConfig;
@@ -8906,12 +10066,21 @@ exports.prepareSandboxUser = prepareSandboxUser;
 exports.purchasePaymentTokenAbi = purchasePaymentTokenAbi;
 exports.purchaseRegistryAbi = purchaseRegistryAbi;
 exports.purchaseSecurityTokenAbi = purchaseSecurityTokenAbi;
+exports.resolveIssuerDeployment = resolveIssuerDeployment;
 exports.resolveSandboxUserTraits = resolveSandboxUserTraits;
+exports.restoreSandboxLinkedWallet = restoreSandboxLinkedWallet;
 exports.restoreSandboxUserWallet = restoreSandboxUserWallet;
 exports.sandboxJurisdictionTraitId = sandboxJurisdictionTraitId;
 exports.sandboxTraitId = sandboxTraitId;
+exports.sandboxWalletLinkAbi = sandboxWalletLinkAbi;
+exports.sandboxWalletLinkTypes = sandboxWalletLinkTypes;
 exports.securityTokenVaultAbi = securityTokenVaultAbi;
 exports.transferSandboxUser = transferSandboxUser;
+exports.validateSandboxLinkedWalletProgress = validateSandboxLinkedWalletProgress;
+exports.validateSandboxWalletLinkIntent = validateSandboxWalletLinkIntent;
+exports.validateSandboxWalletLinkParams = validateSandboxWalletLinkParams;
 exports.waitForSandboxUserFunding = waitForSandboxUserFunding;
+exports.walletLinkData = walletLinkData;
+exports.walletLinkWaitOptions = walletLinkWaitOptions;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map