🔄 synced file(s) with crcl-main/modularwallets-web-sdk-internal

.nvmrc

@@ -1 +1 @@
-v20.18.0
+v24.16.0

COPYRIGHT

@@ -1,12 +1,12 @@
-Copyright 2025 Circle Internet Group, Inc. All rights reserved.
+Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
 
 SPDX-License-Identifier: Apache-2.0
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
-You may obtain a copy of the License at.
+You may obtain a copy of the License at
 
-http://www.apache.org/licenses/LICENSE-2.0
+    http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,

README.md

@@ -1,6 +1,6 @@
 # w3s-web-core-sdk
 
-[![Test Coverage](https://gist.githubusercontent.com/circle-ops-repo-updater/e7bd19f4fa4b938846ab8dfd3d0fdb76/raw/badge_080600a2cd10.svg)](https://sonarqube.circle.com/component_measures?metric=coverage&view=list&id=circlefin_w3s-web-core-sdk_7e01a87f-7793-4147-b755-e0717a9ed92e)
+[![Test Coverage](https://gist.githubusercontent.com/circle-ops-repo-updater/e7bd19f4fa4b938846ab8dfd3d0fdb76/raw/badge_080600a2cd10.svg)](https://sonarqube.circle.com/component_measures?metric=coverage&view=list&id=crcl-main_w3s-web-core-sdk_7e01a87f-7793-4147-b755-e0717a9ed92e)
 
 Repository for the Circle Modular Wallet Web SDK (*aka.* BW Web SDK or Buidl Wallet Web SDK)
 

SECURITY.md

@@ -2,4 +2,7 @@
 
 ## Reporting a Vulnerability
 
-Please do not file public issues on Github for security vulnerabilities. All security vulnerabilities should be reported to Circle privately, through Circle's [Bug Bounty Program](https://hackerone.com/circle-bbp). Please read through the program policy before submitting a report.
+Please do not file public issues on GitHub for security vulnerabilities.
+All security vulnerabilities should be reported to Circle privately, through
+Circle's [Vulnerability Disclosure Program](https://hackerone.com/circle-bbp).
+Please read through the program policy before submitting a report.

examples/circle-smart-account/index.tsx

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import * as React from 'react'
 import * as ReactDOM from 'react-dom/client'
 import { polygonAmoy } from 'viem/chains'

examples/circle-smart-account/package.json

@@ -8,15 +8,15 @@
   },
   "dependencies": {
     "@circle-fin/modular-wallets-core": "workspace:*",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "viem": "^2.21.27"
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "viem": "2.23.13"
   },
   "devDependencies": {
-    "@types/react": "^18.0.27",
-    "@types/react-dom": "^18.0.10",
-    "@vitejs/plugin-react": "^4.3.2",
-    "typescript": "^5.0.3",
-    "vite": "^5.4.18"
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.3.4",
+    "typescript": "5.8.2",
+    "vite": "5.4.18"
   }
 }

examples/circle-smart-account/vite.config.ts

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 

examples/dynamic-integration/.env.example

@@ -1,3 +1,8 @@
+# Circle Modular Wallets — from https://console.circle.com/wallets/modular/configurator
+# Base Client URL only (do not include /polygonAmoy; the app appends the chain).
+# Example: https://modular-sdk.circle.com/v1/rpc/w3s/buidl
 VITE_CLIENT_KEY=
 VITE_CLIENT_URL=
+
+# Dynamic — Sandbox Environment ID from https://app.dynamic.xyz/dashboard/overview
 VITE_DYNAMIC_ENV_ID=

examples/dynamic-integration/App.tsx

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import * as React from "react"
 import * as ReactDOM from "react-dom/client"
 

examples/dynamic-integration/README.md

@@ -1,66 +1,87 @@
 # Dynamic Integration Example
 
-This example Vite application demonstrates how to integrate [Dynamic](https://www.dynamic.xyz/)'s SDK using an EOA account.
+This example Vite application demonstrates how to integrate [Dynamic](https://www.dynamic.xyz/)'s SDK with Circle Modular Wallets. A user connects an EOA through Dynamic; the app derives a Circle smart account on Polygon Amoy and can send a gas-sponsored USDC user operation.
 
-## Run the example app
+## Prerequisites
 
-Please follow the instructions to run the example app on your local machine.
+- A [Circle Modular Wallets](https://console.circle.com/wallets/modular/configurator) client configured for **Polygon Amoy**
+- A [Dynamic](https://app.dynamic.xyz/dashboard/overview) project (use the **Sandbox** environment for local development)
 
-### Environment Variables
+## Environment variables
 
-Before you start to run the app, you need to make sure that all environment variables are configured correctly.
+Copy `.env.example` to `.env` in this folder (`examples/dynamic-integration/.env`):
 
-Make a copy of `.env.example` and rename it to `.env`.
+```bash
+cp .env.example .env
+```
 
-Under `.env`, make sure the following environment variables are configured properly:
+| Variable | Description |
+| --- | --- |
+| `VITE_CLIENT_KEY` | Client Key from the Circle Developer Console |
+| `VITE_CLIENT_URL` | Base Client URL from the Circle Developer Console — **without** the chain suffix |
+| `VITE_DYNAMIC_ENV_ID` | Sandbox Environment ID from the Dynamic dashboard |
 
-- `VITE_CLIENT_KEY`: Paste your Client Key here. You can create one in [Circle Developer Console](https://console.circle.com/wallets/modular/configurator).
-- `VITE_CLIENT_URL`: Paste the Client URL here. You can copy it from [Circle Developer Console](https://console.circle.com/wallets/modular/configurator).
-- `VITE_DYNAMIC_ENV_ID`: Paste the Dynamic Environment ID here. You can copy it from [Dynamic Console](https://app.dynamic.xyz/dashboard/overview).
+> [!IMPORTANT]
+> `VITE_CLIENT_URL` must be a full `https://...` URL. The app appends `/polygonAmoy` internally. If this variable is empty, you will see `InvalidProviderError: Provider with url "/polygonAmoy" is not set or invalid`.
 
-Once you have these environment variables setup, you can now follow the steps below to run the app locally.
+Example `.env` shape (use your own credentials):
 
-### Install dependencies
+```env
+VITE_CLIENT_KEY=your-client-key
+VITE_CLIENT_URL=https://modular-sdk.circle.com/v1/rpc/w3s/buidl
+VITE_DYNAMIC_ENV_ID=your-dynamic-sandbox-environment-id
+```
 
-You first need to make sure you have followed the [README](https://github.com/circlefin/w3s-web-core-sdk/blob/master/README.md) under project root and have installed all dependencies under root folder:
+Restart `pnpm dev` after changing `.env`.
 
-```bash
-$ pnpm install
-```
+## Dynamic dashboard setup
 
-#### Important: Build the SDK
+Configure the **Sandbox** environment that matches `VITE_DYNAMIC_ENV_ID`:
 
-Since this project uses pnpm workspaces, you must build the SDK packages before running the example:
+1. **Security → Allowed CORS origins** — add `http://localhost:5173` (include the port Vite prints)
+2. **Log in** — enable at least one sign-in method (email, social, or external wallet)
+3. **Chains & Networks** — enable **EVM** and **Polygon Amoy**
+4. **Wallets** — enable **MetaMask** and/or **WalletConnect**, or enable **Embedded Wallets** with Polygon Amoy
 
-```bash
-# From the project root directory
-$ pnpm build
-```
+The app already wires up Dynamic per their React quickstart in `App.tsx` (`DynamicContextProvider`, `EthereumWalletConnectors`, `DynamicWidget`).
 
-This will generate the necessary distribution files that this example depends on.
+## Install and run
 
-Now you need to go to this example folder:
+From the repository root:
 
 ```bash
-$ cd examples/dynamic-integration
+pnpm install
+pnpm build
 ```
 
-Once you are under the example folder, install all dependencies for the app:
+Then from this folder:
 
 ```bash
-$ pnpm install
+cd examples/dynamic-integration
+pnpm dev
 ```
 
-### Run the app
+Open `http://localhost:5173/`.
 
-To run the app locally:
+## Smoke test
 
-```bash
-$ pnpm dev
-```
+1. Click the Dynamic connect button — the modal should open without CORS errors in the browser console
+2. Sign in and connect an EVM wallet
+3. Confirm an **Address:** line appears (Circle smart account derived from the Dynamic EOA)
+4. Optional: submit the USDC transfer form (requires Amoy USDC and paymaster enabled on your Circle client)
+
+## Troubleshooting
 
-Now you should be able to see your app up and running in your browser at: `http://localhost:5173/`.
+| Symptom | Likely cause |
+| --- | --- |
+| `InvalidProviderError` for `/polygonAmoy` | `VITE_CLIENT_URL` missing or `.env` not in this folder |
+| CORS errors to `app.dynamicauth.com` | Add `http://localhost:5173` to Dynamic **Allowed CORS origins** (Sandbox env) |
+| Connect button renders but modal fails | Dynamic SDK did not initialize — check CORS and `VITE_DYNAMIC_ENV_ID` |
+| `This wallet is not an Ethereum wallet` | Connected a non-EVM wallet; enable EVM connectors in Dynamic |
+| Stuck on "Loading..." after connect | `getWalletClient()` failed — ensure Polygon Amoy is enabled in Dynamic |
+| User operation fails | Circle-side issue (paymaster, funding, or Amoy USDC balance) |
 
-### Important Notes
+## Important notes
 
-**Ensure the installed SDK version is greater than or equal to `1.0.5`**
+- Ensure the installed SDK version is greater than or equal to `1.0.5`
+- `.env` lives in `examples/dynamic-integration/`, not the repository root

examples/dynamic-integration/index.tsx

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import React, { useEffect } from "react"
 import { createPublicClient, Hex, parseUnits } from "viem"
 

examples/dynamic-integration/package.json

@@ -8,17 +8,17 @@
   },
   "dependencies": {
     "@circle-fin/modular-wallets-core": "workspace:*",
-    "@dynamic-labs/ethereum": "^4.6.0",
-    "@dynamic-labs/sdk-react-core": "^4.6.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "viem": "^2.21.27"
+    "@dynamic-labs/ethereum": "4.88.6",
+    "@dynamic-labs/sdk-react-core": "4.88.6",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "viem": "2.45.3"
   },
   "devDependencies": {
-    "@types/react": "^18.0.27",
-    "@types/react-dom": "^18.0.10",
-    "@vitejs/plugin-react": "^4.3.2",
-    "typescript": "^5.0.3",
-    "vite": "^5.4.18"
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.3.4",
+    "typescript": "5.8.2",
+    "vite": "5.4.18"
   }
 }

examples/dynamic-integration/vite.config.ts

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import react from "@vitejs/plugin-react"
 import { defineConfig, loadEnv } from "vite"
 

examples/eip-1193/README.md

@@ -22,7 +22,7 @@ Once you have these environment variables setup, you can now follow the steps be
 
 ### Install dependencies
 
-You first need to make sure you have followed the [README](https://github.com/circlefin/w3s-web-core-sdk/blob/master/README.md) under project root and have installed all dependencies under root folder:
+You first need to make sure you have followed the [README](https://github.com/circlefin/modularwallets-web-sdk/blob/master/README.md) under project root and have installed all dependencies under root folder:
 
 ```bash
 $ pnpm install

examples/eip-1193/index.tsx

@@ -1,3 +1,21 @@
+/*
+ * Copyright (c) 2026, Circle Internet Group, Inc. All rights reserved.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 import * as React from "react"
 import * as ReactDOM from "react-dom/client"
 import { polygonAmoy } from "viem/chains"

examples/eip-1193/package.json

@@ -8,16 +8,16 @@
   },
   "dependencies": {
     "@circle-fin/modular-wallets-core": "workspace:*",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "viem": "^2.21.27",
-    "web3": "^4.16.0"
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "viem": "2.23.13",
+    "web3": "4.16.0"
   },
   "devDependencies": {
-    "@types/react": "^18.0.27",
-    "@types/react-dom": "^18.0.10",
-    "@vitejs/plugin-react": "^4.3.2",
-    "typescript": "^5.0.3",
-    "vite": "^5.4.18"
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.3.4",
+    "typescript": "5.8.2",
+    "vite": "5.4.18"
   }
 }