create-stylus 1.1.0

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

@@ -0,0 +1,263 @@
+![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/jest.config.js

@@ -0,0 +1,15 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/scripts'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    'scripts/**/*.ts',
+    '!scripts/**/*.d.ts',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+}; 

package/templates/base/packages/stylus/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ss/stylus",
+  "version": "1.0.0",
+  "description": "TypeScript project for Stylus dApp",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "deploy": "ts-node scripts/deploy_wrapper.ts",
+    "test:networks": "ts-node scripts/test_network.ts",
+    "export-abi": "ts-node scripts/export_abi.ts",
+    "clean": "rm -rf dist",
+    "test": "cargo test",
+    "lint": "eslint scripts --ext .ts",
+    "lint:fix": "eslint scripts --ext .ts --fix",
+    "new-module": "bash scripts/new_module.sh"
+  },
+  "keywords": [
+    "stylus",
+    "typescript",
+    "arbitrum",
+    "blockchain"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/yargs": "^17.0.32",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.3.0",
+    "yargs": "^17.7.2"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.81.5",
+    "abitype": "^1.0.8",
+    "dotenv": "^16.0.0",
+    "ethers": "^6.15.0",
+    "prettier": "^3.6.2",
+    "toml": "^3.0.0",
+    "ts-node": "^10.9.2",
+    "viem": "^1.19.9"
+  }
+}

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

@@ -0,0 +1,29 @@
+import deployStylusContract from "./deploy_contract";
+import {
+  getDeploymentConfig,
+  printDeployedAddresses,
+} from "./utils/";
+import { DeployOptions } from "./utils/type";
+
+/**
+ * Define your deployment logic here
+ */
+export default async function deployScript(deployOptions: DeployOptions) {
+  // Deploy a single contract
+  await deployStylusContract({
+    contract: "your-contract",
+    ...deployOptions,
+  });
+
+  // deploy your contract with a custom name
+  await deployStylusContract({
+    contract: "your-contract",
+    name: "my-contract",
+    ...deployOptions,
+  });
+
+  // Print the deployed addresses
+  const config = getDeploymentConfig(deployOptions);
+  console.log("\n\n");
+  printDeployedAddresses(config.deploymentDir);
+}

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

@@ -0,0 +1,59 @@
+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);
+}

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

@@ -0,0 +1,93 @@
+import {
+  getDeploymentConfig,
+  ensureDeploymentDirectory,
+  executeCommand,
+  generateContractAddress,
+  extractDeployedAddress,
+  saveDeployedAddress,
+  clearDeploymentDir,
+  // estimateGasPrice,
+} from "./utils/";
+import { exportStylusAbi } from "./export_abi";
+import {
+  DeployOptions,
+  AdditionalOptions,
+} from "./utils/type";
+import { buildDeployCommand } from "./utils/command";
+
+/**
+ * Deploy a single contract using cargo stylus
+ * @param deployOptions - The deploy options
+ * @param additionalOptions - The additional options
+ * @returns void
+ */
+export default async function deployStylusContract(
+  deployOptions: DeployOptions,
+  additionalOptions: AdditionalOptions = {
+    isSingleCommand: true,
+    shouldClearDeploymentDir: false,
+  },
+) {
+  console.log(`\n🚀 Deploying contract in: ${deployOptions.contract}`);
+
+  const config = getDeploymentConfig(deployOptions);
+  if (additionalOptions.shouldClearDeploymentDir) {
+    clearDeploymentDir();
+    ensureDeploymentDirectory(config.deploymentDir);
+  }
+
+  console.log(`📄 Contract name: ${config.contractName}`);
+
+  config.contractAddress = generateContractAddress();
+
+  if (additionalOptions.isSingleCommand) {
+    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}`);
+  }
+
+  try {
+    // Step 1: Deploy the contract using cargo stylus with contract address
+    // --contract-address='${config.contractAddress}' deactivated for now as it's not working. Issue https://github.com/OffchainLabs/cargo-stylus/issues/171
+    const deployCommand = await buildDeployCommand(config, deployOptions);
+    const deployOutput = await executeCommand(
+      deployCommand,
+      deployOptions.contract!,
+      "Deploying contract with cargo stylus",
+    );
+
+    if (deployOptions.estimateGas) {
+      console.log(deployOutput);
+      process.exit(0);
+    }
+
+    // Extract the actual deployed address from the output
+    const deployedAddress = extractDeployedAddress(deployOutput);
+    if (deployedAddress) {
+      config.contractAddress = deployedAddress;
+      console.log(`📋 Contract deployed at address: ${config.contractAddress}`);
+    } else {
+      console.log(`📋 Using fallback address: ${config.contractAddress}`);
+    }
+
+    // Save the deployed address to addresses.json
+    saveDeployedAddress(config);
+
+    // Step 2: Export ABI using the shared function
+    await exportStylusAbi(config.contractFolder, config.contractName, false);
+
+    console.log(`✅ Successfully deployed contract in: ${deployOptions.contract}`);
+    if (additionalOptions.isSingleCommand) {
+      console.log(`📋 Contract deployed at address: ${config.contractAddress}`);
+      console.log(`📋 Chain ID: ${config.chain?.id}`);
+    }
+  } catch (error) {
+    console.error(`❌ Deployment failed in: ${deployOptions.contract}`, error);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,79 @@
+import * as fs from "fs";
+import deployStylusContract from "./deploy_contract";
+import { hideBin } from "yargs/helpers";
+import yargs from "yargs";
+import { DeployCommandOptions, DeployOptions } from "./utils/type";
+import deployAllStylusContracts from "./deploy_all_contracts";
+import deployScript from "./deploy";
+
+/**
+ * Entry point for the deploy script
+ * This script is used to deploy a single contract or all contracts in the stylus folder
+ */
+if (require.main === module) {
+  // Use yargs for argument parsing
+  const argv = yargs(hideBin(process.argv))
+    .usage("Usage: yarn deploy --name <contractName> --network <network>")
+    .option("all", {
+      alias: "a",
+      describe: "Deploy all contracts in the stylus folder",
+      type: "boolean",
+      demandOption: false,
+    })
+    .option("contract", {
+      alias: "c",
+      describe: "Name of the contract folder",
+      type: "string",
+      demandOption: false,
+    })
+    .option("name", {
+      alias: "n",
+      describe: "Name of the contract",
+      type: "string",
+      demandOption: false,
+    })
+    .option("network", {
+      alias: "net",
+      describe: "Network to deploy to",
+      type: "string",
+      demandOption: false,
+    })
+    .option("estimate-gas", {
+      alias: "eg",
+      describe: "Estimate gas for the deployment",
+      type: "boolean",
+      demandOption: false,
+    })
+    .option("max-fee", {
+      alias: "mf",
+      describe: "Max fee per gas gwei",
+      type: "string",
+      demandOption: false,
+    })
+    .help()
+    .parseSync() as DeployCommandOptions;
+
+  if (argv.all) {
+    deployAllStylusContracts(argv as DeployOptions).catch((error) => {
+      console.error("Fatal error:", error);
+      process.exit(1);
+    });
+  } else if (argv.contract) {
+    if (!fs.existsSync(argv.contract)) {
+      console.error(`❌ Contract folder does not exist: ${argv.contract}`);
+      process.exit(1);
+    }
+
+    deployStylusContract(argv as DeployOptions, {
+      shouldClearDeploymentDir: true,
+    }).catch((error) => {
+      console.error("Fatal error:", error);
+      process.exit(1);
+    });
+  } else {
+    deployScript(argv as DeployOptions).catch((error) => {
+      console.error("Fatal error:", error);
+      process.exit(1);
+    });
+  }
+}

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

@@ -0,0 +1,87 @@
+import * as path from "path";
+import * as fs from "fs";
+import {
+  getExportConfig,
+  ensureDeploymentDirectory,
+  executeCommand,
+  generateTsAbi,
+  handleSolcError,
+} from "./utils/";
+
+export async function exportStylusAbi(
+  contractFolder: string,
+  contractName: string,
+  isSingleCommand: boolean = true,
+) {
+  console.log("📄 Starting Stylus ABI export...");
+
+  const config = getExportConfig(contractFolder, contractName);
+
+  // If contractAddress is not set, error and exit
+  if (!config.contractAddress) {
+    console.error(
+      `❌ Contract address not found. Please deploy the contract first or ensure it is saved in ${path.resolve(config.deploymentDir, "addresses.json")}`,
+    );
+    process.exit(1);
+  }
+
+  if (isSingleCommand) {
+    console.log(`📄 Contract name: ${config.contractName}`);
+    console.log(`📁 Deployment directory: ${config.deploymentDir}`);
+    console.log(`📍 Contract address: ${config.contractAddress}`);
+    console.log(`🔗 Chain ID: ${config.chainId}`);
+  }
+
+  try {
+    // Ensure deployment directory exists
+    ensureDeploymentDirectory(config.deploymentDir);
+
+    // Export ABI
+    const exportCommand = `cargo stylus export-abi --output='../${config.deploymentDir}/${config.contractFolder}' --json`;
+    await executeCommand(exportCommand, contractFolder, "Exporting ABI");
+
+    console.log(
+      `📄 ABI file location: ${config.deploymentDir}/${config.contractFolder}`,
+    );
+
+    // Verify the ABI file was created
+    const abiFilePath = path.resolve(
+      config.deploymentDir,
+      `${config.contractFolder}`,
+    );
+    if (fs.existsSync(abiFilePath)) {
+      console.log(`✅ ABI file verified at: ${abiFilePath}`);
+    } else {
+      console.warn(
+        `⚠️  ABI file not found at expected location: ${abiFilePath}`,
+      );
+    }
+
+    // do not Generate TypeScript ABI when called from yarn script
+    if (!isSingleCommand) {
+      await generateTsAbi(
+        abiFilePath,
+        config.contractName,
+        config.contractAddress,
+        config.chainId,
+      );
+    }
+  } catch (error) {
+    handleSolcError(error as Error);
+    process.exit(1);
+  }
+}
+
+// Allow running this file directly
+if (require.main === module) {
+  // Get contract folder from command line args, default to 'your-contract'
+  const contractFolder = process.argv[2] || "your-contract";
+  if (!fs.existsSync(contractFolder)) {
+    console.error(`❌ Contract folder does not exist: ${contractFolder}`);
+    process.exit(1);
+  }
+  exportStylusAbi(contractFolder, contractFolder).catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+  });
+}