create-stylus 0.1.11 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stylus",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "author": "Q3 Labs",
   "license": "MIT",
   "repository": {

package/templates/base/.lintstagedrc.js

@@ -1,9 +1,9 @@
 const path = require("path");
 
 const buildNextEslintCommand = (filenames) =>
-  `yarn next:lint --fix --file ${filenames
+  `yarn workspace @ss/nextjs eslint --fix ${filenames
     .map((f) => path.relative(path.join("packages", "nextjs"), f))
-    .join(" --file ")}`;
+    .join(" ")}`;
 
 const checkTypesNextCommand = () => "yarn next:check-types";
 

package/templates/base/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ss",
-  "version": "0.1.11",
+  "version": "0.1.14",
   "private": true,
   "workspaces": {
     "packages": [

package/templates/base/packages/nextjs/components/Header.tsx

@@ -105,9 +105,8 @@ export const Header = () => {
       }}
     >
       <div className="navbar-start w-auto lg:w-1/2">
-        <div className="lg:hidden dropdown" ref={burgerMenuRef}>
+        <div className={`lg:hidden dropdown ${isDrawerOpen ? "dropdown-open" : ""}`} ref={burgerMenuRef}>
           <label
-            tabIndex={0}
             className={`ml-1 btn btn-ghost ${isDrawerOpen ? "hover:bg-secondary" : "hover:bg-transparent"}`}
             onClick={() => {
               setIsDrawerOpen(prevIsOpenState => !prevIsOpenState);

package/templates/base/packages/nextjs/components/ThemeProvider.tsx

@@ -1,8 +1,7 @@
 "use client";
 
 import * as React from "react";
-import { ThemeProvider as NextThemesProvider } from "next-themes";
-import { type ThemeProviderProps } from "next-themes/dist/types";
+import { ThemeProvider as NextThemesProvider, type ThemeProviderProps } from "next-themes";
 
 export const ThemeProvider = ({ children, ...props }: ThemeProviderProps) => {
   const [mounted, setMounted] = React.useState(false);

package/templates/base/packages/nextjs/components/scaffold-eth/Input/EtherInput.tsx

@@ -66,6 +66,7 @@ export const EtherInput = ({
       return transitoryDisplayValue;
     }
     // Clear any transitory display values that might be set
+    // eslint-disable-next-line react-hooks/set-state-in-render
     setTransitoryDisplayValue(undefined);
     return newDisplayValue;
   }, [nativeCurrencyPrice, transitoryDisplayValue, displayUsdMode, value]);

package/templates/base/packages/nextjs/components/scaffold-eth/RainbowKitCustomConnectButton/AddressInfoDropdown.tsx

@@ -40,21 +40,22 @@ export const AddressInfoDropdown = ({ address, ensAvatar, displayName, onSwitchA
   const { copyToClipboard: copyAddressToClipboard, isCopiedToClipboard: isAddressCopiedToClipboard } =
     useCopyToClipboard();
   const [selectingNetwork, setSelectingNetwork] = useState(false);
-  const dropdownRef = useRef<HTMLDetailsElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
 
   const closeDropdown = () => {
     setSelectingNetwork(false);
-    dropdownRef.current?.removeAttribute("open");
+    setIsOpen(false);
   };
 
   useOutsideClick(dropdownRef, closeDropdown);
 
   return (
     <>
-      <details ref={dropdownRef} className="dropdown dropdown-end leading-3">
-        <summary
-          tabIndex={0}
+      <div ref={dropdownRef} className={`dropdown dropdown-end leading-3 ${isOpen ? "dropdown-open" : ""}`}>
+        <label
           className="dropdown-toggle gap-0 !h-auto"
+          onClick={() => setIsOpen(prev => !prev)}
           style={{
             position: "relative",
             width: "220px",
@@ -126,7 +127,7 @@ export const AddressInfoDropdown = ({ address, ensAvatar, displayName, onSwitchA
               }}
             />
           </div>
-        </summary>
+        </label>
         <ul
           tabIndex={0}
           className="dropdown-content menu z-[2] p-2 mt-4 gap-1"
@@ -229,7 +230,7 @@ export const AddressInfoDropdown = ({ address, ensAvatar, displayName, onSwitchA
             </button>
           </li>
         </ul>
-      </details>
+      </div>
     </>
   );
 };

package/templates/base/packages/nextjs/components/scaffold-eth/RainbowKitCustomConnectButton/WrongNetworkDropdown.tsx

@@ -1,13 +1,19 @@
+import { useRef, useState } from "react";
 import { NetworkOptions } from "./NetworkOptions";
 import { useDisconnect } from "wagmi";
 import { ArrowLeftEndOnRectangleIcon, ChevronDownIcon } from "@heroicons/react/24/outline";
+import { useOutsideClick } from "~~/hooks/scaffold-eth";
 
 export const WrongNetworkDropdown = () => {
   const { disconnect } = useDisconnect();
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  useOutsideClick(dropdownRef, () => setIsOpen(false));
 
   return (
-    <div className="dropdown dropdown-end mr-2">
-      <label tabIndex={0} className="btn btn-error btn-sm dropdown-toggle gap-1">
+    <div ref={dropdownRef} className={`dropdown dropdown-end mr-2 ${isOpen ? "dropdown-open" : ""}`}>
+      <label className="btn btn-error btn-sm dropdown-toggle gap-1" onClick={() => setIsOpen(prev => !prev)}>
         <span>Wrong network</span>
         <ChevronDownIcon className="h-6 w-4 ml-2 sm:ml-0" />
       </label>

package/templates/base/packages/nextjs/eslint.config.mjs

@@ -1,26 +1,21 @@
-import { FlatCompat } from "@eslint/eslintrc";
+import nextCoreWebVitals from "eslint-config-next/core-web-vitals";
+import nextTypescript from "eslint-config-next/typescript";
+import prettierConfig from "eslint-config-prettier";
 import prettierPlugin from "eslint-plugin-prettier";
 import { defineConfig } from "eslint/config";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
 
 export default defineConfig([
+  ...nextCoreWebVitals,
+  ...nextTypescript,
+  prettierConfig,
   {
     plugins: {
       prettier: prettierPlugin,
     },
-    extends: compat.extends("next/core-web-vitals", "next/typescript", "prettier"),
-
     rules: {
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/ban-ts-comment": "off",
-
+      "react-hooks/set-state-in-effect": "off",
       "prettier/prettier": [
         "warn",
         {
@@ -28,11 +23,6 @@ export default defineConfig([
         },
       ],
     },
-  },
-  {
-    files: ["next-env.d.ts"],
-    rules: {
-      "@typescript-eslint/triple-slash-reference": "off",
-    },
+    ignores: [".next", "next-env.d.ts"],
   },
 ]);

package/templates/base/packages/nextjs/hooks/scaffold-eth/useScaffoldWriteContract.ts

@@ -2,12 +2,14 @@ import { useEffect, useState } from "react";
 import { MutateOptions } from "@tanstack/react-query";
 import { Abi, ExtractAbiFunctionNames } from "abitype";
 import { Config, UseWriteContractParameters, useAccount, useConfig, useWriteContract } from "wagmi";
-import { WriteContractErrorType, WriteContractReturnType } from "wagmi/actions";
+import { estimateFeesPerGas, WriteContractErrorType, WriteContractReturnType } from "wagmi/actions";
 import { WriteContractVariables } from "wagmi/query";
 import { useSelectedNetwork } from "~~/hooks/scaffold-eth";
 import { useDeployedContractInfo, useTransactor } from "~~/hooks/scaffold-eth";
 import { notification } from "~~/utils/scaffold-eth";
 import { AllowedChainIds } from "~~/utils/scaffold-stylus";
+import scaffoldConfig from "~~/scaffold.config";
+import { wagmiConfig } from "~~/services/web3/wagmiConfig";
 import {
   ContractAbi,
   ContractName,
@@ -34,6 +36,30 @@ type ScaffoldWriteContractReturnType<TContractName extends ContractName> = Omit<
   ) => void;
 };
 
+/**
+ * Optionally bump maxFeePerGas on the write args to protect against base fee spikes.
+ * Since maxFeePerGas is a ceiling (not the actual fee), a generous multiplier is safe.
+ */
+async function applyGasFeeMultiplier(
+  args: WriteContractVariables<Abi, string, any[], Config, number>,
+  chainId: number,
+): Promise<WriteContractVariables<Abi, string, any[], Config, number>> {
+  const multiplier = scaffoldConfig.gasFeeMultiplier;
+  if (!multiplier || multiplier <= 1) return args;
+  try {
+    const fees = await estimateFeesPerGas(wagmiConfig, { chainId: chainId as any });
+    const scaledMultiplier = BigInt(Math.round(multiplier * 100));
+    return {
+      ...args,
+      maxFeePerGas: (fees.maxFeePerGas * scaledMultiplier) / 100n,
+      maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
+    } as WriteContractVariables<Abi, string, any[], Config, number>;
+  } catch (e) {
+    console.warn("⚡️ ~ useScaffoldWriteContract ~ estimateFeesPerGas failed:", e);
+    return args;
+  }
+}
+
 export function useScaffoldWriteContract<TContractName extends ContractName>(
   config: UseScaffoldWriteConfig<TContractName>,
 ): ScaffoldWriteContractReturnType<TContractName>;
@@ -110,12 +136,14 @@ export function useScaffoldWriteContract<TContractName extends ContractName>(
       setIsMining(true);
       const { blockConfirmations, onBlockConfirmation, ...mutateOptions } = options || {};
 
-      const writeContractObject = {
+      let writeContractObject = {
         abi: deployedContractData.abi as Abi,
         address: deployedContractData.address,
         ...variables,
       } as WriteContractVariables<Abi, string, any[], Config, number>;
 
+      writeContractObject = await applyGasFeeMultiplier(writeContractObject, selectedNetwork.id as AllowedChainIds);
+
       if (!finalConfig?.disableSimulate) {
         await simulateContractWriteAndNotifyError({
           wagmiConfig,
@@ -167,21 +195,24 @@ export function useScaffoldWriteContract<TContractName extends ContractName>(
       return;
     }
 
-    wagmiContractWrite.writeContract(
-      {
-        abi: deployedContractData.abi as Abi,
-        address: deployedContractData.address,
-        ...variables,
-      } as WriteContractVariables<Abi, string, any[], Config, number>,
-      options as
-        | MutateOptions<
-            WriteContractReturnType,
-            WriteContractErrorType,
-            WriteContractVariables<Abi, string, any[], Config, number>,
-            unknown
-          >
-        | undefined,
-    );
+    const writeContractObject = {
+      abi: deployedContractData.abi as Abi,
+      address: deployedContractData.address,
+      ...variables,
+    } as WriteContractVariables<Abi, string, any[], Config, number>;
+    applyGasFeeMultiplier(writeContractObject, selectedNetwork.id as AllowedChainIds).then(buffered => {
+      wagmiContractWrite.writeContract(
+        buffered,
+        options as
+          | MutateOptions<
+              WriteContractReturnType,
+              WriteContractErrorType,
+              WriteContractVariables<Abi, string, any[], Config, number>,
+              unknown
+            >
+          | undefined,
+      );
+    });
   };
 
   return {

package/templates/base/packages/nextjs/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference path="./.next/types/routes.d.ts" />
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/base/packages/nextjs/next.config.js

@@ -6,14 +6,6 @@ const nextConfig = {
   typescript: {
     ignoreBuildErrors: process.env.NEXT_PUBLIC_IGNORE_BUILD_ERROR === "true",
   },
-  eslint: {
-    ignoreDuringBuilds: process.env.NEXT_PUBLIC_IGNORE_BUILD_ERROR === "true",
-  },
-  webpack: config => {
-    config.resolve.fallback = { fs: false, net: false, tls: false };
-    config.externals.push("pino-pretty", "lokijs", "encoding");
-    return config;
-  },
 };
 
 module.exports = nextConfig;

package/templates/base/packages/nextjs/package.json

@@ -7,7 +7,7 @@
     "start": "next dev",
     "build": "next build",
     "serve": "next start",
-    "lint": "next lint",
+    "lint": "eslint .",
     "format": "prettier --write . '!(node_modules|.next|contracts)/**/*'",
     "check-types": "tsc --noEmit --incremental",
     "vercel": "vercel",
@@ -23,44 +23,43 @@
     "has-ansi": "5.0.1"
   },
   "dependencies": {
-    "@heroicons/react": "^2.1.5",
-    "@rainbow-me/rainbowkit": "2.2.8",
+    "@heroicons/react": "^2.2.0",
+    "@rainbow-me/rainbowkit": "2.2.9",
     "@tanstack/react-query": "^5.59.15",
     "@uniswap/sdk-core": "^5.8.2",
     "@uniswap/v2-sdk": "^4.6.1",
-    "blo": "^1.2.0",
-    "burner-connector": "0.0.18",
-    "daisyui": "4.5.0",
-    "kubo-rpc-client": "^5.0.2",
-    "next": "^15.2.3",
-    "next-nprogress-bar": "^2.3.13",
-    "next-themes": "^0.3.0",
-    "qrcode.react": "^4.0.1",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-hot-toast": "^2.4.0",
-    "usehooks-ts": "^3.1.0",
-    "viem": "2.34.0",
-    "wagmi": "2.16.4",
-    "zustand": "^5.0.0"
+    "blo": "^2.0.0",
+    "burner-connector": "0.0.20",
+    "daisyui": "^5.5.19",
+    "kubo-rpc-client": "^6.1.0",
+    "next": "^16.2.4",
+    "next-nprogress-bar": "^2.4.7",
+    "next-themes": "^0.4.6",
+    "qrcode.react": "^4.2.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "react-hot-toast": "^2.6.0",
+    "usehooks-ts": "^3.1.1",
+    "viem": "2.39.0",
+    "wagmi": "2.19.5",
+    "zustand": "^5.0.12"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "latest",
+    "@tailwindcss/postcss": "^4.2.4",
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
-    "@types/node": "^18.19.50",
-    "@types/react": "^19.0.7",
+    "@types/node": "^18.19.130",
+    "@types/react": "^19.2.14",
     "abitype": "1.0.6",
-    "autoprefixer": "^10.4.12",
     "bgipfs": "^0.0.12",
-    "eslint": "^9.23.0",
-    "eslint-config-next": "^15.2.3",
-    "eslint-config-prettier": "^10.1.1",
-    "eslint-plugin-prettier": "^5.2.4",
-    "postcss": "^8.4.45",
-    "prettier": "^3.5.3",
-    "tailwindcss": "^3.3.3",
+    "eslint": "^9.39.0",
+    "eslint-config-next": "^16.2.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "postcss": "^8.5.10",
+    "prettier": "^3.8.3",
+    "tailwindcss": "^4.2.4",
     "type-fest": "^4.26.1",
     "typescript": "^5.8.2",
-    "vercel": "^39.1.3"
+    "vercel": "~52.2.1"
   }
 }

package/templates/base/packages/nextjs/postcss.config.js

@@ -1,6 +1,5 @@
 module.exports = {
   plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
+    "@tailwindcss/postcss": {},
   },
 };

package/templates/base/packages/nextjs/scaffold.config.ts

@@ -11,6 +11,13 @@ export type ScaffoldConfig = {
   walletConnectProjectId: string;
   onlyLocalBurnerWallet: boolean;
   walletAutoConnect: boolean;
+  /**
+   * Multiplier applied to maxFeePerGas for contract writes.
+   * Since maxFeePerGas is a CEILING (actual fee = baseFee + priorityFee capped at this),
+   * values >1 protect against block-to-block base fee spikes without increasing real cost.
+   * Set to 1 or omit to disable.
+   */
+  gasFeeMultiplier?: number;
 };
 
 export const DEFAULT_ALCHEMY_API_KEY = "oKxs-03sij-U_N0iOlrSsZFr29-IqbuF";
@@ -51,6 +58,9 @@ const scaffoldConfig = {
    * 2. If user is not connected to any wallet:  On reload, connect to burner wallet if burnerWallet.enabled is true && burnerWallet.onlyLocal is false
    */
   walletAutoConnect: true,
+
+  // Gas fee multiplier for contract writes (ceiling, not actual cost — safe to be generous)
+  gasFeeMultiplier: 2,
 } as const satisfies ScaffoldConfig;
 
 export default scaffoldConfig;

package/templates/base/packages/nextjs/styles/globals.css

@@ -1,10 +1,134 @@
-@import "tailwindcss/base";
-@import "tailwindcss/components";
-@import "tailwindcss/utilities";
+@import "tailwindcss";
+
+@source "../app";
+@source "../components";
+@source "../utils";
+
+@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
+
+@theme {
+  --font-sans: var(--font-inter), system-ui, sans-serif;
+  --shadow-center: 0 0 12px -2px rgb(0 0 0 / 0.05);
+  --animate-pulse-fast: pulse 1s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+/* Orbitron utility — defined as a standalone @utility (not @theme) to avoid a
+   self-referential --font-orbitron, since next/font already emits that var. */
+@utility font-orbitron {
+  font-family: var(--font-orbitron), sans-serif;
+}
+
+@plugin "daisyui" {
+  themes:
+    light,
+    dark --prefersdark;
+}
+
+@plugin "daisyui/theme" {
+  name: "light";
+
+  --color-primary: #93bbfb;
+  --color-primary-content: #212638;
+  --color-secondary: #dae8ff;
+  --color-secondary-content: #212638;
+  --color-accent: #93bbfb;
+  --color-accent-content: #212638;
+  --color-neutral: #212638;
+  --color-neutral-content: #ffffff;
+  --color-base-100: #ffffff;
+  --color-base-200: #f4f8ff;
+  --color-base-300: #dae8ff;
+  --color-base-content: #212638;
+  --color-info: #93bbfb;
+  --color-success: #34eeb6;
+  --color-warning: #ffcf72;
+  --color-error: #ff8863;
+
+  /* ported from --rounded-btn: 9999rem (daisyui v4) -> v5 radius family */
+  --radius-field: 9999rem;
+  --radius-box: 1rem;
+
+  /* ported from .tooltip { --tooltip-tail: 6px } */
+  --tt-tailw: 6px;
+}
+
+@plugin "daisyui/theme" {
+  name: "dark";
+
+  --color-primary: #212638;
+  --color-primary-content: #f9fbff;
+  --color-secondary: #323f61;
+  --color-secondary-content: #f9fbff;
+  --color-accent: #4969a6;
+  --color-accent-content: #f9fbff;
+  --color-neutral: #f9fbff;
+  --color-neutral-content: #385183;
+  --color-base-100: #000000;
+  --color-base-200: #2a3655;
+  --color-base-300: #212638;
+  --color-base-content: #f9fbff;
+  --color-info: #385183;
+  --color-success: #34eeb6;
+  --color-warning: #ffcf72;
+  --color-error: #ff8863;
+
+  /* ported from --rounded-btn: 9999rem (daisyui v4) -> v5 radius family */
+  --radius-field: 9999rem;
+  --radius-box: 1rem;
+
+  /* ported from .tooltip { --tooltip-tail: 6px; --tooltip-color: oklch(var(--p)) } */
+  --tt-tailw: 6px;
+  --tt-bg: var(--color-primary);
+}
+
+/* Per-theme custom variables ported verbatim from tailwind.config.js daisyui themes.
+   Defined with explicit [data-theme] selectors (not inside the daisyui theme blocks,
+   which only accept daisyui's own tokens). */
+[data-theme="light"] {
+  --surface: rgba(0, 0, 0, 0.04);
+  --bg-border: #ffffff;
+  --round-color: #000;
+  --gradient-start: #3283eb;
+  --gradient-end: #e3066e;
+  --border-color: rgba(0, 0, 0, 0.07);
+}
+
+[data-theme="dark"] {
+  --surface: rgba(255, 255, 255, 0.04);
+  --bg-border: #000000;
+  --round-color: #e3066e;
+  --gradient-start: #3283eb;
+  --gradient-end: #e3066e;
+  --border-color: rgba(255, 255, 255, 0.2);
+}
+
+/*
+  Tailwind CSS v4 changed the default border color to `currentColor`.
+  Restore the v3 default (gray-200) so existing borders look identical.
+*/
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentColor);
+  }
+}
 
 :root,
 [data-theme] {
-  background: oklch(var(--b1));
+  background: var(--color-base-100);
+}
+
+/* ported from .link / .link:hover (defined per-theme in tailwind.config.js;
+   identical across light & dark, so defined once globally) */
+.link {
+  text-underline-offset: 2px;
+}
+
+.link:hover {
+  opacity: 80%;
 }
 
 body {

package/templates/base/packages/nextjs/tsconfig.json

@@ -9,10 +9,10 @@
     "noEmit": true,
     "esModuleInterop": true,
     "module": "esnext",
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "paths": {
       "~~/*": ["./*"]
@@ -23,6 +23,6 @@
       }
     ]
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
   "exclude": ["node_modules"]
 }

package/templates/base/packages/stylus/scripts/utils/command.ts

@@ -5,6 +5,38 @@ import {
   isContractHasConstructor,
 } from "./contract";
 import { getRpcUrlFromChain } from "./network";
+import { createPublicClient, http, formatUnits } from "viem";
+
+const DEFAULT_GAS_FEE_MULTIPLIER = 3;
+const MIN_FEE_GWEI = 0.1;
+
+function getGasFeeMultiplier(): number {
+  const envVal = process.env["DEPLOY_GAS_FEE_MULTIPLIER"];
+  if (envVal) {
+    const parsed = parseFloat(envVal);
+    if (!isNaN(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return DEFAULT_GAS_FEE_MULTIPLIER;
+}
+
+async function getBufferedMaxFeeGwei(rpcUrl: string): Promise<number> {
+  try {
+    const publicClient = createPublicClient({
+      transport: http(rpcUrl),
+    });
+    const block = await publicClient.getBlock({ blockTag: "latest" });
+    if (block.baseFeePerGas === null) {
+      return MIN_FEE_GWEI;
+    }
+    const baseFeeGwei = Number(formatUnits(block.baseFeePerGas, 9));
+    const buffered = baseFeeGwei * getGasFeeMultiplier();
+    return Math.max(buffered, MIN_FEE_GWEI);
+  } catch {
+    return MIN_FEE_GWEI;
+  }
+}
 
 export async function buildDeployCommand(
   config: DeploymentConfig,
@@ -18,6 +50,12 @@ export async function buildDeployCommand(
 
   if (deployOptions.maxFee) {
     baseCommand += ` --max-fee-per-gas-gwei=${deployOptions.maxFee}`;
+  } else {
+    // maxFeePerGas is a CEILING (actual charge = base fee), so over-provisioning is safe and free.
+    // Cargo stylus without this flag uses a tight estimate that the base fee can creep past.
+    const rpcUrl = getRpcUrlFromChain(config.chain);
+    const maxFeeGwei = await getBufferedMaxFeeGwei(rpcUrl);
+    baseCommand += ` --max-fee-per-gas-gwei=${maxFeeGwei}`;
   }
 
   if (!deployOptions.verify) {

package/templates/base/readme.md

@@ -67,12 +67,12 @@ Check the [Rust installation guide](https://www.rust-lang.org/tools/install) for
 Then install the Stylus CLI tools:
 
 ```bash
-cargo install --force cargo-stylus cargo-stylus-check
+cargo install --force --locked cargo-stylus@0.6.3
 ```
 
 **Prerequisite:**
 
-- `cargo-stylus` version `^0.6.1`
+- `cargo-stylus` version `0.6.3`
 - `rustc` version match with `packages/stylus/your-contract/rust-toolchain.toml`
 
 Set default `toolchain` match `rust-toolchain.toml` and add the `wasm32-unknown-unknown` build target to your Rust compiler: