opacity-issuer-core 0.2.1 → 0.2.2

package/dist/index.cjs

@@ -8641,6 +8641,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 hash = 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(hash, "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 hash = 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,
+        ...waitOptions3,
+        onReplaced: ({ reason }) => {
+          replacementReason = reason;
+        }
+      })
+    );
+    await clientFor(intent.chainId);
+    const base = { submittedHash: hash, hash: receipt.transactionHash, receipt };
+    let exactTransaction = false;
+    let result = { ...base, status: "unverified" };
+    if (replacementReason || receipt.transactionHash.toLowerCase() !== hash.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 });
+        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;
+        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())
+              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 });
+        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;
+      } 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"))
+      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 +9601,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 +9629,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 +9644,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;
@@ -8907,11 +9684,19 @@ exports.purchasePaymentTokenAbi = purchasePaymentTokenAbi;
 exports.purchaseRegistryAbi = purchaseRegistryAbi;
 exports.purchaseSecurityTokenAbi = purchaseSecurityTokenAbi;
 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