create-stylus 1.1.0 → 1.1.1

package/templates/base/readme.md

@@ -1,4 +1,4 @@
-# 🏗 scaffold-stylus
+# 🏗 scaffold-stylus 
 
 <h4 align="center">
   <a href="https://arb-stylus.github.io/scaffold-stylus-docs/">Documentation</a> |
@@ -10,8 +10,8 @@
 ⚙️ Built using Rust, NextJS, RainbowKit, Stylus, Wagmi, Viem, and TypeScript.
 
 - ✅ **Contract Hot Reload**: Your frontend auto-adapts to your smart contract as you edit it.
-- 🪝 **[Custom hooks]()**: Collection of React hooks wrapped around [wagmi](https://wagmi.sh/) to simplify interactions with smart contracts with TypeScript autocompletion.
-- 🧱 [**Components**](): Collection of common web3 components to quickly build your frontend.
+- 🪝 **[Custom hooks](https://arb-stylus.github.io/scaffold-stylus-docs/components)**: Collection of React hooks wrapped around [wagmi](https://wagmi.sh/) to simplify interactions with smart contracts with TypeScript autocompletion.
+- 🧱 [**Components**](https://arb-stylus.github.io/scaffold-stylus-docs/hooks): Collection of common web3 components to quickly build your frontend.
 - 🔥 **Burner Wallet & Local Faucet**: Quickly test your application with a burner wallet and local faucet.
 - 🔐 **Integration with Wallet Providers**: Connect to different wallet providers and interact with the Arbitrum network.
 
@@ -30,13 +30,11 @@ Before you begin, you need to install the following tools:
 
 ## Quickstart
 
-[Video Demo](https://app.screencastify.com/watch/9GYnnO0Fqq9QOjYRjQg0)
-
 To get started with Scaffold-Stylus, follow the steps below:
 
-1. Clone this repo & install dependencies
+### 1. Clone this repo & install dependencies
 
-```
+```bash
 git clone https://github.com/Arb-Stylus/scaffold-stylus.git
 cd scaffold-stylus
 yarn install
@@ -44,34 +42,72 @@ yarn install
 git submodule update --init --recursive
 ```
 
-2. Run a local network in the first terminal:
+### 2. Install Stylus tools
 
+Install [Rust](https://www.rust-lang.org/tools/install), and then install the Stylus CLI tool with Cargo:
+
+```bash
+cargo install --force cargo-stylus cargo-stylus-check
 ```
+
+**Prerequisite:**
+
+- `cargo-stylus` version `^0.6.1`
+- `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:
+
+```bash
+rustup default 1.87
+rustup target add wasm32-unknown-unknown --toolchain 1.87
+```
+
+You should now have it available as a Cargo subcommand:
+
+```bash
+cargo stylus --help
+```
+
+### 3. Run a local network
+
+In your first terminal:
+
+```bash
 yarn chain
 ```
 
 This command starts a local Stylus-compatible network using the Nitro dev node script (`./nitro-devnode/run-dev-node.sh`). The network runs on your local machine and can be used for testing and development. You can customize the Nitro dev node configuration in the `nitro-devnode` submodule.
 
-3. On a second terminal, deploy the test contract:
+### 4. Deploy the test contract
 
-```
+In your second terminal:
+
+```bash
 yarn deploy
 ```
 
-This command deploys a test smart contract to the local network. The contract is located in `packages/stylus/your-contract/src` and can be modified to suit your needs. The `yarn deploy` command uses the deploy script located in `packages/stylus/scripts` to deploy the contract to the network. You can also customize the deploy script.
+This command deploys a test smart contract to the local network. The contract is located in `packages/stylus/your-contract/src` and can be modified to suit your needs. The `yarn deploy` command uses the deploy script located in `packages/stylus/scripts` to deploy the contract to the network. You can also customize the deploy script .
 
-4. On a third terminal, start your NextJS app:
+### 5. Start your NextJS app
 
-```
+In your third terminal:
+
+```bash
 yarn start
 ```
 
-Visit your app at: `http://localhost:3000`. You can interact with your smart contract using the `Debug Contracts` page. You can tweak the app config in `packages/nextjs/scaffold.config.ts`.
+Visit your app at: `http://localhost:3000`. You can interact with your smart contract using the **Debug Contracts** page, which provides a user-friendly interface for testing your contract's functions and viewing its state.
+
+### 6. Test your smart contract
 
-Run smart contract tests with `yarn stylus:test`
+```bash
+yarn stylus:test
+```
+
+## Development Workflow
 
 - Edit your smart contract `lib.rs` in `packages/stylus/your-contract/src`
-- Edit your frontend in `packages/nextjs/pages`
+- Edit your frontend in `packages/nextjs/app`
 - Edit your deployment scripts in `packages/stylus/scripts`
 
 ## Create Your Own Contract
@@ -82,7 +118,7 @@ Scaffold-Stylus enables you to create and deploy multiple contracts within a sin
 
 Use the following command to create a new contract and customize it as needed:
 
-```
+```bash
 yarn new-module <contract-name>
 ```
 
@@ -90,39 +126,18 @@ The generated contract will be located in `packages/stylus/<contract-name>`.
 
 ### Step 2: Deploy Your Contract
 
-Deploy your contract using one of the following methods:
-
-#### Method A: Deploy with Script (Recommended)
-
-```
-yarn deploy
+```bash
+yarn deploy [...options]
 ```
 
 This command runs the `deploy.ts` script located in `packages/stylus/scripts`. You can customize this script with your deployment logic.
 
-#### Method B: Deploy Single Contract Directly
-
-If you prefer not to write a deployment script, you can deploy a single contract directly:
-
-```
-yarn deploy --contract <contractFolder> [...options]
-```
-
 **Available Options:**
 
-- `--name <contractName>`: Deploy your contract with a custom name (default is the contract folder name)
 - `--network <network>`: Specify which network to deploy to
 - `--estimate-gas`: Only perform gas estimation without deploying
 - `--max-fee=<maxFee>`: Set maximum fee per gas in gwei
 
-#### Method C: Deploy All Contracts
-
-Deploy all contracts in your project with a single command:
-
-```
-yarn deploy --all [...options]
-```
-
 **Note:** Deployment information is automatically saved in `packages/stylus/deployments` by default.
 
 ## Deploying to Other Networks
@@ -139,6 +154,8 @@ To deploy your contracts to other networks (other than the default local Nitro d
    RPC_URL_SEPOLIA=https://your-network-rpc-url
    ```
 
+   **Note:** If RPC URL is not provided, system will use default public RPC URL from that network
+
 2. **Set the Private Key**
 
    For real deployments, you must provide your own wallet's private key. Set the `PRIVATE_KEY_<network>` environment variable:
@@ -149,7 +166,15 @@ To deploy your contracts to other networks (other than the default local Nitro d
 
    **Security Note:** A development key is used by default when running the Nitro dev node locally, but for external deployments, you must provide your own private key.
 
-3. **Update Frontend Configuration**
+3. **Set the Account Address**
+
+   Set the `ACCOUNT_ADDRESS_<network>`
+
+   ```env
+   ACCOUNT_ADDRESS_SEPOLIA=your_account_address_here
+   ```
+
+4. **Update Frontend Configuration**
 
    Open `packages/nextjs/scaffold.config.ts` and update the `targetNetworks` array to include your target chain. This ensures your frontend connects to the correct network and generates the proper ABI in `deployedContracts.ts`:
 
@@ -159,21 +184,161 @@ To deploy your contracts to other networks (other than the default local Nitro d
    targetNetworks: [chains.arbitrumSepolia],
    ```
 
+### Available Networks
+
+This template supports Arbitrum networks only. You can test which networks are available and their RPC URLs:
+
+```bash
+yarn test:networks
+```
+
+This will show you all supported networks and their corresponding RPC endpoints.
+
 ### Deploy to Other Network
 
 Once configured, deploy to your target network:
 
-```
+```bash
 yarn deploy --network <network>
 ```
 
 **Important Security Notes:**
 
 - The values in `.env.example` provide a template for required environment variables
-
 - **Always keep your private key secure and never commit it to version control**
 - Consider using environment variable management tools for production deployments
 
+## Verify your contract
+
+#### Prerequisites
+
+Your contract must meet Arbiscan's verification requirements:
+
+- No external libraries
+- No constructor arguments
+- No custom optimization settings
+- No specific compiler version requirements
+
+### Local Verification
+
+Make sure your constructor does not contain any args
+
+```rs
+pub fn constructor(&mut self)
+```
+
+The scaffold includes built-in local verification to ensure your Stylus contract deployments are reproducible. To enable verification during deployment, set `verify: true` in your deployment script:
+
+```ts
+await deployStylusContract({
+  contract: "your-contract",
+  verify: true,
+  ...deployOptions,
+});
+```
+
+This runs `cargo stylus verify` locally after deployment, which:
+
+- Verifies that the deployed bytecode matches your source code
+- Ensures reproducibility across different environments
+- Validates the deployment transaction
+
+### Arbiscan Verification
+
+For public verification on Arbiscan, follow these steps:
+
+#### Steps
+
+1. **Create a dedicated repository** containing only your contract source code
+2. **Navigate to Arbiscan**:
+   - Go to [Arbiscan Verify Contract](https://arbiscan.io/verifyContract)
+   - Enter your deployed contract address
+3. **Follow the verification process**:
+   - Select "Solidity (Standard-Json-Input)" as the compiler type
+   - Enter your contract source code (github link)
+   - Provide any constructor arguments if applicable
+   - Submit for verification
+
+Check official document for detail instructions: https://docs.arbitrum.io/stylus/how-tos/verifying-contracts-arbiscan
+
+> **Note**: Arbiscan verification for Stylus contracts is still evolving. If you encounter issues, consider using the local verification method or check Arbiscan's latest documentation for Stylus-specific instructions.
+
+### 🛠️ Troubleshooting Common Issues
+
+#### 1. `stylus` Not Recognized
+
+If you encounter an error stating that `stylus` is not recognized as an external or internal command, run the following command in your terminal:
+
+```bash
+sudo apt-get update && sudo apt-get install -y pkg-config libssl-dev
+```
+
+After that, check if `stylus` is installed by running:
+
+```bash
+cargo stylus --version
+```
+
+If the version is displayed, `stylus` has been successfully installed and the path is correctly set.
+
+#### 2. ABI Not Generated
+
+If you face issues with the ABI not being generated, you can try one of the following solutions:
+
+- **Restart Docker Node**: Pause and restart the Docker node and the local setup of the project. You can do this by deleting all ongoing running containers and then restarting the local terminal using:
+  ```bash
+  yarn run dev
+  ```
+- **Modify the Script**: In the `run-dev-node.sh` script, replace the line:
+
+  ```bash
+  cargo stylus export-abi
+  ```
+
+  with:
+
+  ```bash
+  cargo run --manifest-path=Cargo.toml --features export-abi
+  ```
+
+- **Access Denied Issue**: If you encounter an access denied permission error during ABI generation, run the following command and then execute the script again:
+  ```bash
+  sudo chown -R $USER:$USER target
+  ```
+
+#### 3. 🚨 Fixing Line Endings and Running Shell Scripts in WSL
+
+> ⚠️ This guide provides step-by-step instructions to resolve the Command not found error caused by CRLF line endings in shell scripts when running in a WSL environment.
+
+Shell scripts created in Windows often have `CRLF` line endings, which cause issues in Unix-like environments such as WSL. To fix this:
+
+**Using `dos2unix`:**
+
+1. Install `dos2unix` (if not already installed):
+
+   ```bash
+   sudo apt install dos2unix
+   ```
+
+2. Convert the script's line endings:
+
+   ```bash
+   dos2unix run-dev-node.sh
+   ```
+
+3. Make the Script Executable:
+
+   ```bash
+   chmod +x run-dev-node.sh
+   ```
+
+4. Run the Script in WSL:
+   ```bash
+   bash run-dev-node.sh
+   ```
+
+---
+
 ## Documentation
 
 Visit our [docs](https://arb-stylus.github.io/scaffold-stylus-docs/) to learn how to start building with Scaffold-Stylus.

package/templates/base/yarn.lock

@@ -4633,7 +4633,6 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "@ss/stylus@workspace:packages/stylus"
   dependencies:
-    "@tanstack/react-query": ^5.81.5
     "@types/node": ^20.0.0
     "@types/yargs": ^17.0.32
     "@typescript-eslint/eslint-plugin": ^6.0.0
@@ -4844,7 +4843,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tanstack/react-query@npm:^5.59.15, @tanstack/react-query@npm:^5.81.5":
+"@tanstack/react-query@npm:^5.59.15":
   version: 5.83.0
   resolution: "@tanstack/react-query@npm:5.83.0"
   dependencies:

package/templates/base/packages/stylus/README.md

@@ -1,263 +0,0 @@
-![Image](./header.png)
-
-# Stylus Hello World
-
-Project starter template for writing Arbitrum Stylus programs in Rust using the [stylus-sdk](https://github.com/OffchainLabs/stylus-sdk-rs). It includes a Rust implementation of a basic counter Ethereum smart contract:
-
-```js
-// SPDX-License-Identifier: UNLICENSED
-pragma solidity ^0.8.13;
-
-contract Counter {
-    uint256 public number;
-
-    function setNumber(uint256 newNumber) public {
-        number = newNumber;
-    }
-
-    function increment() public {
-        number++;
-    }
-}
-```
-
-To set up more minimal example that still uses the Stylus SDK, use `cargo stylus new --minimal <YOUR_PROJECT_NAME>` under [OffchainLabs/cargo-stylus](https://github.com/OffchainLabs/cargo-stylus).
-
-## Quick Start
-
-Install [Rust](https://www.rust-lang.org/tools/install), and then install the Stylus CLI tool with Cargo
-
-```bash
-cargo install --force cargo-stylus cargo-stylus-check
-```
-
-Add the `wasm32-unknown-unknown` build target to your Rust compiler:
-
-```
-rustup target add wasm32-unknown-unknown
-```
-
-You should now have it available as a Cargo subcommand:
-
-```bash
-cargo stylus --help
-```
-
-Then, clone the template:
-
-```
-git clone https://github.com/OffchainLabs/stylus-hello-world && cd stylus-hello-world
-```
-
-### Testnet Information
-
-All testnet information, including faucets and RPC endpoints can be found [here](https://docs.arbitrum.io/stylus/reference/testnet-information).
-
-### ABI Export
-
-You can export the Solidity ABI for your program by using the `cargo stylus` tool as follows:
-
-```bash
-cargo stylus export-abi
-```
-
-which outputs:
-
-```js
-/**
- * This file was automatically generated by Stylus and represents a Rust program.
- * For more information, please see [The Stylus SDK](https://github.com/OffchainLabs/stylus-sdk-rs).
- */
-
-// SPDX-License-Identifier: MIT-OR-APACHE-2.0
-pragma solidity ^0.8.23;
-
-interface ICounter {
-    function number() external view returns (uint256);
-
-    function setNumber(uint256 new_number) external;
-
-    function mulNumber(uint256 new_number) external;
-
-    function addNumber(uint256 new_number) external;
-
-    function increment() external;
-}
-```
-
-Exporting ABIs uses a feature that is enabled by default in your Cargo.toml:
-
-```toml
-[features]
-export-abi = ["stylus-sdk/export-abi"]
-```
-
-## Deploying
-
-You can use the `cargo stylus` command to also deploy your program to the Stylus testnet. We can use the tool to first check
-our program compiles to valid WASM for Stylus and will succeed a deployment onchain without transacting. By default, this will use the Stylus testnet public RPC endpoint. See here for [Stylus testnet information](https://docs.arbitrum.io/stylus/reference/testnet-information)
-
-```bash
-cargo stylus check
-```
-
-If successful, you should see:
-
-```bash
-Finished release [optimized] target(s) in 1.88s
-Reading WASM file at stylus-hello-world/target/wasm32-unknown-unknown/release/stylus-hello-world.wasm
-Compressed WASM size: 8.9 KB
-Program succeeded Stylus onchain activation checks with Stylus version: 1
-```
-
-Next, we can estimate the gas costs to deploy and activate our program before we send our transaction. Check out the [cargo-stylus](https://github.com/OffchainLabs/cargo-stylus) README to see the different wallet options for this step:
-
-```bash
-cargo stylus deploy \
-  --private-key-path=<PRIVKEY_FILE_PATH> \
-  --estimate-gas
-```
-
-You will then see the estimated gas cost for deploying before transacting:
-
-```bash
-Deploying program to address e43a32b54e48c7ec0d3d9ed2d628783c23d65020
-Estimated gas for deployment: 1874876
-```
-
-The above only estimates gas for the deployment tx by default. To estimate gas for activation, first deploy your program using `--mode=deploy-only`, and then run `cargo stylus deploy` with the `--estimate-gas` flag, `--mode=activate-only`, and specify `--activate-program-address`.
-
-Here's how to deploy:
-
-```bash
-cargo stylus deploy \
-  --private-key-path=<PRIVKEY_FILE_PATH>
-```
-
-The CLI will send 2 transactions to deploy and activate your program onchain.
-
-```bash
-Compressed WASM size: 8.9 KB
-Deploying program to address 0x457b1ba688e9854bdbed2f473f7510c476a3da09
-Estimated gas: 1973450
-Submitting tx...
-Confirmed tx 0x42db…7311, gas used 1973450
-Activating program at address 0x457b1ba688e9854bdbed2f473f7510c476a3da09
-Estimated gas: 14044638
-Submitting tx...
-Confirmed tx 0x0bdb…3307, gas used 14044638
-```
-
-Once both steps are successful, you can interact with your program as you would with any Ethereum smart contract.
-
-## Network Configuration
-
-This template includes enhanced deployment scripts that support automatic RPC URL resolution from viem's chain definitions. You can now specify a network name instead of manually providing RPC URLs.
-
-### Using Network Names
-
-Instead of setting `RPC_URL` in your environment, you can use the `NETWORK` environment variable:
-
-```bash
-# Deploy to Arbitrum One (mainnet)
-NETWORK=arbitrum yarn deploy
-NETWORK=mainnet yarn deploy  # alias for arbitrum
-
-# Deploy to Arbitrum Sepolia testnet
-NETWORK=arbitrumSepolia yarn deploy
-NETWORK=testnet yarn deploy  # alias for arbitrumSepolia
-```
-
-### Available Networks
-
-This template supports Arbitrum networks only. You can test which networks are available and their RPC URLs:
-
-```bash
-yarn test:networks
-```
-
-This will show you all supported networks and their corresponding RPC endpoints.
-
-### Fallback Behavior
-
-If a network name is not supported (only `arbitrum`, `arbitrumSepolia`, `mainnet`, and `testnet` are supported), the system will:
-
-1. Show a warning message indicating the network isn't supported
-2. Fall back to the `RPC_URL` environment variable (or default to `http://localhost:8547`)
-3. Continue with deployment using the fallback endpoint
-
-### Environment Variables
-
-You can still use the traditional approach with `RPC_URL`:
-
-```bash
-RPC_URL=https://your-custom-rpc.com yarn deploy
-```
-
-Or combine both (network takes precedence):
-
-```bash
-NETWORK=mainnet RPC_URL=https://fallback-rpc.com yarn deploy
-```
-
-## Calling Your Program
-
-This template includes an example of how to call and transact with your program in Rust using [ethers-rs](https://github.com/gakonst/ethers-rs) under the `examples/counter.rs`. However, your programs are also Ethereum ABI equivalent if using the Stylus SDK. **They can be called and transacted with using any other Ethereum tooling.**
-
-By using the program address from your deployment step above, and your wallet, you can attempt to call the counter program and increase its value in storage:
-
-```rs
-abigen!(
-    Counter,
-    r#"[
-        function number() external view returns (uint256)
-        function setNumber(uint256 number) external
-        function increment() external
-    ]"#
-);
-let counter = Counter::new(address, client);
-let num = counter.number().call().await;
-println!("Counter number value = {:?}", num);
-
-let _ = counter.increment().send().await?.await?;
-println!("Successfully incremented counter via a tx");
-
-let num = counter.number().call().await;
-println!("New counter number value = {:?}", num);
-```
-
-Before running, set the following env vars or place them in a `.env` file (see: [.env.example](./.env.example)) in this project:
-
-```
-RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
-STYLUS_CONTRACT_ADDRESS=<the onchain address of your deployed program>
-PRIV_KEY_PATH=<the file path for your priv key to transact with>
-```
-
-Next, run:
-
-```
-cargo run --example counter --target=<YOUR_ARCHITECTURE>
-```
-
-Where you can find `YOUR_ARCHITECTURE` by running `rustc -vV | grep host`. For M1 Apple computers, for example, this is `aarch64-apple-darwin` and for most Linux x86 it is `x86_64-unknown-linux-gnu`
-
-## Build Options
-
-By default, the cargo stylus tool will build your project for WASM using sensible optimizations, but you can control how this gets compiled by seeing the full README for [cargo stylus](https://github.com/OffchainLabs/cargo-stylus). If you wish to optimize the size of your compiled WASM, see the different options available [here](https://github.com/OffchainLabs/cargo-stylus/blob/main/OPTIMIZING_BINARIES.md).
-
-## Peeking Under the Hood
-
-The [stylus-sdk](https://github.com/OffchainLabs/stylus-sdk-rs) contains many features for writing Stylus programs in Rust. It also provides helpful macros to make the experience for Solidity developers easier. These macros expand your code into pure Rust code that can then be compiled to WASM. If you want to see what the `stylus-hello-world` boilerplate expands into, you can use `cargo expand` to see the pure Rust code that will be deployed onchain.
-
-First, run `cargo install cargo-expand` if you don't have the subcommand already, then:
-
-```
-cargo expand --all-features --release --target=<YOUR_ARCHITECTURE>
-```
-
-Where you can find `YOUR_ARCHITECTURE` by running `rustc -vV | grep host`. For M1 Apple computers, for example, this is `aarch64-apple-darwin`.
-
-## License
-
-This project is fully open source, including an Apache-2.0 or MIT license at your choosing under your own copyright.

package/templates/base/packages/stylus/scripts/deploy_all_contracts.ts

@@ -1,59 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import deployStylusContract from "./deploy_contract";
-import {
-  clearDeploymentDir,
-  ensureDeploymentDirectory,
-  getDeploymentConfig,
-  isContractFolder,
-  printDeployedAddresses,
-} from "./utils/";
-import { DeployOptions } from "./utils/type";
-
-/**
- * Deploy all contracts in the stylus folder
- * @param deployOptions - The deploy options
- * @returns void
- */
-export default async function deployAllStylusContracts(
-  deployOptions: DeployOptions,
-) {
-  const contractsRoot = ".";
-  const entries = fs.readdirSync(contractsRoot, { withFileTypes: true });
-
-  const config = getDeploymentConfig(deployOptions);
-  clearDeploymentDir();
-  ensureDeploymentDirectory(config.deploymentDir);
-
-  console.log(`📄 Deploying all contracts`);
-  console.log(`📡 Using endpoint: ${config.chain?.rpcUrl}`);
-  if (config.chain) {
-    console.log(`🌐 Network specified: ${config.chain?.name}`);
-  }
-  console.log(`🔑 Using private key: ${config.privateKey.substring(0, 10)}...`);
-  console.log(`📁 Deployment directory: ${config.deploymentDir}`);
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const contractFolder = path.join(contractsRoot, entry.name);
-    if (isContractFolder(contractFolder)) {
-      try {
-        await deployStylusContract(
-          {
-            contract: entry.name,
-            ...deployOptions,
-          },
-          {
-            isSingleCommand: false,
-          },
-        );
-      } catch (e) {
-        console.error(`❌ Failed to deploy contract in: ${contractFolder}`);
-        console.error(e);
-      }
-    }
-  }
-
-  console.log("\n\n");
-  printDeployedAddresses(config.deploymentDir);
-}