@worldcoin/minikit-js 1.11.0 → 2.0.0-dev.1

package/README.md

@@ -10,6 +10,113 @@ or use the CDN:
 
 For comprehensive setup instructions and usage examples, visit our [developer documentation](https://docs.world.org/mini-apps).
 
+## Scope
+
+`@worldcoin/minikit-js` is the mini-app command SDK:
+
+- `MiniKit.walletAuth()`
+- `MiniKit.sendTransaction()`
+- `MiniKit.pay()`
+- `MiniKit.shareContacts()`
+- `MiniKit.signMessage()`
+- `MiniKit.signTypedData()`
+- and related mini-app commands
+
+World ID verification belongs to IDKit:
+
+- Use `@worldcoin/idkit` for verification requests and widget UI
+- Use `@worldcoin/idkit-core` for backend signing helpers such as `signRequest`
+
+## v2 -> v3 Migration Highlights
+
+- `MiniKit.commands.*` / `MiniKit.commandsAsync.*` are removed. Use `await MiniKit.<command>(...)`.
+- Command responses now use `{ executedWith, data }`.
+- Verify flows moved to IDKit (`@worldcoin/idkit`), not MiniKit.
+- `walletAuth` nonce validation is stricter (alphanumeric SIWE nonce).
+- Tree-shakeable subpath exports are available for commands and helpers.
+
+### `sendTransaction` uses one flexible transaction type
+
+When `transaction[i].data` is provided, MiniKit prioritizes raw calldata over
+`abi` / `functionName` / `args`.
+
+Example:
+
+```ts
+await MiniKit.sendTransaction({
+  transaction: [
+    {
+      address: tokenAddress,
+      data: '0xa9059cbb...', // takes priority when present
+      abi: erc20Abi,
+      functionName: 'transfer',
+      args: [to, amount],
+    },
+  ],
+});
+```
+
+Type shape:
+
+```ts
+type Transaction = {
+  address: string;
+  value?: string;
+  data?: string;
+  abi?: Abi | readonly unknown[];
+  functionName?: ContractFunctionName<...>;
+  args?: ContractFunctionArgs<...>;
+};
+
+interface MiniKitSendTransactionOptions<TCustomFallback = SendTransactionResult> {
+  transaction: Transaction[];
+  chainId?: number; // defaults to 480 on World App
+  permit2?: Permit2[];
+  formatPayload?: boolean;
+}
+```
+
+### Tree-shakeable subpath exports
+
+Use subpaths to import only what you need:
+
+```ts
+import {
+  MiniKitSendTransactionOptions,
+  SendTransactionErrorCodes,
+} from '@worldcoin/minikit-js/commands';
+import { getIsUserVerified } from '@worldcoin/minikit-js/address-book';
+import {
+  parseSiweMessage,
+  verifySiweMessage,
+} from '@worldcoin/minikit-js/siwe';
+```
+
+You can still import `MiniKit` itself from the package root:
+
+```ts
+import { MiniKit } from '@worldcoin/minikit-js';
+```
+
+### Commands now support custom fallbacks
+
+Use `fallback` to run equivalent logic outside World App:
+
+```ts
+const result = await MiniKit.sendHapticFeedback({
+  hapticsType: 'impact',
+  style: 'light',
+  fallback: () => {
+    navigator.vibrate?.(20);
+    return {
+      status: 'success',
+      version: 1,
+      timestamp: new Date().toISOString(),
+    };
+  },
+});
+```
+
 ## 🛠 ️Developing Locally
 
 To run the example mini app locally:

package/build/address-book.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/address-book.ts
+var address_book_exports = {};
+__export(address_book_exports, {
+  getIsUserVerified: () => getIsUserVerified
+});
+module.exports = __toCommonJS(address_book_exports);
+
+// src/helpers/address-book.ts
+var import_viem = require("viem");
+var import_chains = require("viem/chains");
+var worldIdAddressBookContractAddress = "0x57b930D551e677CC36e2fA036Ae2fe8FdaE0330D";
+var addressVerifiedUntilAbi = [
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    name: "addressVerifiedUntil",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  }
+];
+var getIsUserVerified = async (walletAddress, rpcUrl) => {
+  const publicClient = (0, import_viem.createPublicClient)({
+    chain: import_chains.worldchain,
+    transport: (0, import_viem.http)(
+      rpcUrl || "https://worldchain-mainnet.g.alchemy.com/public"
+    )
+  });
+  try {
+    const verifiedUntilResponse = await publicClient.readContract({
+      address: worldIdAddressBookContractAddress,
+      abi: addressVerifiedUntilAbi,
+      functionName: "addressVerifiedUntil",
+      args: [walletAddress]
+    });
+    const verifiedUntil = Number(verifiedUntilResponse.toString());
+    if (!Number.isFinite(verifiedUntil)) {
+      console.warn("Invalid verifiedUntil value:", verifiedUntil);
+      return false;
+    }
+    const currentTime = Math.floor(Date.now() / 1e3);
+    return verifiedUntil > currentTime;
+  } catch (error) {
+    console.error("Error verifying user:", error);
+    return false;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getIsUserVerified
+});

package/build/address-book.d.cts

@@ -0,0 +1,3 @@
+declare const getIsUserVerified: (walletAddress: string, rpcUrl?: string) => Promise<boolean>;
+
+export { getIsUserVerified };

package/build/address-book.d.ts

@@ -0,0 +1,3 @@
+declare const getIsUserVerified: (walletAddress: string, rpcUrl?: string) => Promise<boolean>;
+
+export { getIsUserVerified };

package/build/address-book.js

@@ -0,0 +1,54 @@
+// src/helpers/address-book.ts
+import { createPublicClient, http } from "viem";
+import { worldchain } from "viem/chains";
+var worldIdAddressBookContractAddress = "0x57b930D551e677CC36e2fA036Ae2fe8FdaE0330D";
+var addressVerifiedUntilAbi = [
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    name: "addressVerifiedUntil",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  }
+];
+var getIsUserVerified = async (walletAddress, rpcUrl) => {
+  const publicClient = createPublicClient({
+    chain: worldchain,
+    transport: http(
+      rpcUrl || "https://worldchain-mainnet.g.alchemy.com/public"
+    )
+  });
+  try {
+    const verifiedUntilResponse = await publicClient.readContract({
+      address: worldIdAddressBookContractAddress,
+      abi: addressVerifiedUntilAbi,
+      functionName: "addressVerifiedUntil",
+      args: [walletAddress]
+    });
+    const verifiedUntil = Number(verifiedUntilResponse.toString());
+    if (!Number.isFinite(verifiedUntil)) {
+      console.warn("Invalid verifiedUntil value:", verifiedUntil);
+      return false;
+    }
+    const currentTime = Math.floor(Date.now() / 1e3);
+    return verifiedUntil > currentTime;
+  } catch (error) {
+    console.error("Error verifying user:", error);
+    return false;
+  }
+};
+export {
+  getIsUserVerified
+};

package/build/chunk-2UPJKPQ6.js

@@ -0,0 +1,272 @@
+import {
+  setFallbackAdapter
+} from "./chunk-Z2UGRZJ2.js";
+
+// src/commands/wagmi-fallback.ts
+var SIWE_NONCE_REGEX = /^[a-zA-Z0-9]{8,}$/;
+var WAGMI_KEY = "__minikit_wagmi_config__";
+function setWagmiConfig(config) {
+  globalThis[WAGMI_KEY] = config;
+  registerWagmiFallbacks();
+}
+function getWagmiConfig() {
+  return globalThis[WAGMI_KEY];
+}
+function hasWagmiConfig() {
+  return globalThis[WAGMI_KEY] !== void 0;
+}
+function registerWagmiFallbacks() {
+  setFallbackAdapter({
+    walletAuth: wagmiWalletAuth,
+    signMessage: wagmiSignMessage,
+    signTypedData: wagmiSignTypedData,
+    sendTransaction: wagmiSendTransaction
+  });
+}
+async function loadWagmiActions() {
+  console.log("[MiniKit WagmiFallback] loadWagmiActions:start", {
+    hasWindow: typeof window !== "undefined",
+    hasWagmiConfig: hasWagmiConfig()
+  });
+  try {
+    const actions = await import(
+      /* webpackIgnore: true */
+      "wagmi/actions"
+    );
+    console.log("[MiniKit WagmiFallback] loadWagmiActions:success");
+    return actions;
+  } catch (error) {
+    console.log("[MiniKit WagmiFallback] loadWagmiActions:error", {
+      message: error instanceof Error ? error.message : String(error)
+    });
+    const wrappedError = new Error(
+      'Wagmi fallback requires the "wagmi" package. Install wagmi or provide a custom fallback.'
+    );
+    wrappedError.cause = error;
+    throw wrappedError;
+  }
+}
+async function loadSiwe() {
+  try {
+    return await import(
+      /* webpackIgnore: true */
+      "siwe"
+    );
+  } catch (error) {
+    const wrappedError = new Error(
+      'Wagmi walletAuth fallback requires the "siwe" package. Install siwe or provide a custom fallback.'
+    );
+    wrappedError.cause = error;
+    throw wrappedError;
+  }
+}
+async function checksumAddress(addr) {
+  try {
+    const { getAddress } = await import(
+      /* webpackIgnore: true */
+      "viem"
+    );
+    return getAddress(addr);
+  } catch {
+    return addr;
+  }
+}
+async function ensureConnected(config) {
+  const { connect, getConnections } = await loadWagmiActions();
+  const isWorldApp = typeof window !== "undefined" && Boolean(window.WorldApp);
+  const existingConnection = getConnections(config).find(
+    (connection) => connection.accounts && connection.accounts.length > 0 && (isWorldApp || connection.connector?.id !== "worldApp")
+  );
+  if (existingConnection && existingConnection.accounts) {
+    return checksumAddress(existingConnection.accounts[0]);
+  }
+  const connectors = config.connectors;
+  if (!connectors || connectors.length === 0) {
+    throw new Error("No Wagmi connectors configured");
+  }
+  const candidateConnectors = isWorldApp ? connectors : connectors.filter(
+    (connector) => connector.id !== "worldApp"
+  );
+  if (!isWorldApp && candidateConnectors.length === 0) {
+    throw new Error(
+      "No web Wagmi connectors configured. Add a web connector (e.g. injected or walletConnect) after worldApp()."
+    );
+  }
+  const selectedConnector = candidateConnectors[0];
+  try {
+    const result = await connect(config, { connector: selectedConnector });
+    if (result.accounts.length > 0) {
+      const account = result.accounts[0];
+      const address = typeof account === "string" ? account : account.address;
+      if (address) {
+        return checksumAddress(address);
+      }
+    }
+  } catch (error) {
+    const connectorId = selectedConnector.id ?? "unknown";
+    const wrappedError = new Error(
+      `Failed to connect with connector "${connectorId}". Reorder connectors to change the default connector.`
+    );
+    wrappedError.cause = error;
+    throw wrappedError;
+  }
+  throw new Error("Failed to connect wallet");
+}
+async function wagmiWalletAuth(params) {
+  console.log("[MiniKit WagmiFallback] walletAuth:start", {
+    hasWagmiConfig: hasWagmiConfig(),
+    nonceLength: params.nonce?.length ?? 0
+  });
+  const config = getWagmiConfig();
+  if (!config) {
+    console.log("[MiniKit WagmiFallback] walletAuth:error:no-config");
+    throw new Error(
+      "Wagmi config not available. Pass wagmiConfig to MiniKitProvider."
+    );
+  }
+  const { signMessage } = await loadWagmiActions();
+  const { SiweMessage } = await loadSiwe();
+  const address = await ensureConnected(config);
+  if (!SIWE_NONCE_REGEX.test(params.nonce)) {
+    throw new Error(
+      "Invalid nonce: must be alphanumeric and at least 8 characters (EIP-4361)"
+    );
+  }
+  const siweMessage = new SiweMessage({
+    domain: typeof window !== "undefined" ? window.location.host : "localhost",
+    address,
+    statement: params.statement,
+    uri: typeof window !== "undefined" ? window.location.origin : "http://localhost",
+    version: "1",
+    chainId: 480,
+    // World Chain
+    nonce: params.nonce,
+    expirationTime: params.expirationTime?.toISOString()
+  });
+  const message = siweMessage.prepareMessage();
+  const signature = await signMessage(config, { message });
+  return {
+    address,
+    message,
+    signature
+  };
+}
+async function wagmiSignMessage(params) {
+  console.log("[MiniKit WagmiFallback] signMessage:start", {
+    hasWagmiConfig: hasWagmiConfig()
+  });
+  const config = getWagmiConfig();
+  if (!config) {
+    console.log("[MiniKit WagmiFallback] signMessage:error:no-config");
+    throw new Error(
+      "Wagmi config not available. Pass wagmiConfig to MiniKitProvider."
+    );
+  }
+  const { signMessage } = await loadWagmiActions();
+  const address = await ensureConnected(config);
+  const signature = await signMessage(config, {
+    account: address,
+    message: params.message
+  });
+  return {
+    status: "success",
+    version: 1,
+    signature,
+    address
+  };
+}
+async function wagmiSignTypedData(params) {
+  console.log("[MiniKit WagmiFallback] signTypedData:start", {
+    hasWagmiConfig: hasWagmiConfig(),
+    hasChainId: params.chainId !== void 0
+  });
+  const config = getWagmiConfig();
+  if (!config) {
+    console.log("[MiniKit WagmiFallback] signTypedData:error:no-config");
+    throw new Error(
+      "Wagmi config not available. Pass wagmiConfig to MiniKitProvider."
+    );
+  }
+  const { getChainId, signTypedData, switchChain } = await loadWagmiActions();
+  const address = await ensureConnected(config);
+  if (params.chainId !== void 0) {
+    const currentChainId = await getChainId(config);
+    if (currentChainId !== params.chainId) {
+      await switchChain(config, { chainId: params.chainId });
+    }
+  }
+  const signature = await signTypedData(config, {
+    account: address,
+    types: params.types,
+    primaryType: params.primaryType,
+    domain: params.domain,
+    message: params.message
+  });
+  return {
+    status: "success",
+    version: 1,
+    signature,
+    address
+  };
+}
+function isChainMismatchError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("does not match the target chain");
+}
+async function wagmiSendTransaction(params) {
+  console.log("[MiniKit WagmiFallback] sendTransaction:start", {
+    hasWagmiConfig: hasWagmiConfig(),
+    chainId: params.chainId,
+    hasData: Boolean(params.transaction.data)
+  });
+  const config = getWagmiConfig();
+  if (!config) {
+    console.log("[MiniKit WagmiFallback] sendTransaction:error:no-config");
+    throw new Error(
+      "Wagmi config not available. Pass wagmiConfig to MiniKitProvider."
+    );
+  }
+  const { getChainId, getWalletClient, sendTransaction, switchChain } = await loadWagmiActions();
+  await ensureConnected(config);
+  const targetChainId = params.chainId ?? config.chains?.[0]?.id;
+  const ensureTargetChain = async () => {
+    if (targetChainId === void 0) return;
+    const currentChainId = await getChainId(config);
+    if (currentChainId !== targetChainId) {
+      await switchChain(config, { chainId: targetChainId });
+    }
+    const walletClient = await getWalletClient(config);
+    const providerChainId = walletClient ? await walletClient.getChainId() : await getChainId(config);
+    if (providerChainId !== targetChainId) {
+      throw new Error(
+        `Wallet network mismatch: expected chain ${targetChainId}, got ${providerChainId}. Please switch networks in your wallet and retry.`
+      );
+    }
+  };
+  await ensureTargetChain();
+  let transactionHash;
+  try {
+    transactionHash = await sendTransaction(config, {
+      chainId: targetChainId,
+      to: params.transaction.address,
+      data: params.transaction.data,
+      value: params.transaction.value ? BigInt(params.transaction.value) : void 0
+    });
+  } catch (error) {
+    if (targetChainId === void 0 || !isChainMismatchError(error)) {
+      throw error;
+    }
+    await ensureTargetChain();
+    transactionHash = await sendTransaction(config, {
+      chainId: targetChainId,
+      to: params.transaction.address,
+      data: params.transaction.data,
+      value: params.transaction.value ? BigInt(params.transaction.value) : void 0
+    });
+  }
+  return { transactionHash };
+}
+
+export {
+  setWagmiConfig
+};