abc-blockchain 0.1.1

package/templates/hardhat-erc4337/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run ci
+
+  codeql:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+      - uses: github/codeql-action/analyze@v3

package/templates/hardhat-erc4337/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: github.repository_owner != ''
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/templates/hardhat-erc4337/.husky/pre-commit

@@ -0,0 +1 @@
+npm run format:check && npm run lint && npm test

package/templates/hardhat-erc4337/.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": false,
+  "trailingComma": "none",
+  "semi": true,
+  "plugins": ["prettier-plugin-solidity"]
+}

package/templates/hardhat-erc4337/README.md.tmpl

@@ -0,0 +1,98 @@
+# {{projectName}}
+
+ERC-4337 Hardhat development environment generated by ABC Blockchain.
+
+Creator: {{creator}}  
+Framework Signature: {{signature}}
+
+## What Is Included
+
+- Hardhat with TypeScript
+- Ethers v6
+- OpenZeppelin contracts
+- Upgrade-ready smart account template
+- Deterministic account factory
+- EntryPoint integration scaffold
+- UserOperation type support
+- Paymaster hook interface
+- Bundler RPC integration point
+- Deployment manifests
+- GitHub Actions CI and release workflow
+- ESLint, Prettier, Husky-ready scripts
+- Slither-ready configuration
+
+## Quick Start
+
+```bash
+cp .env.example .env
+npm install
+npm run ci
+npm test
+npm run deploy:local
+```
+
+## Project Structure
+
+```text
+{{projectName}}/
+├── contracts/
+│   ├── interfaces/
+│   ├── SmartAccount.sol
+│   ├── AccountFactory.sol
+│   ├── EntryPoint.sol
+│   └── Token.sol
+├── scripts/
+├── deployments/
+├── ignition/
+├── tasks/
+├── test/
+├── .github/workflows/
+├── hardhat.config.ts
+├── tsconfig.json
+├── .env.example
+├── README.md
+└── package.json
+```
+
+## Security Notes
+
+- Do not commit `.env`.
+- Use dedicated deployer keys with limited funds.
+- Run `npm audit` and Slither before production deployments.
+- Replace the included development EntryPoint with the canonical audited EntryPoint for production networks.
+- Review upgrade authorization and owner custody before deploying account implementations.
+- Validate bundler and paymaster provider trust assumptions.
+
+## Commands
+
+```bash
+npm run build
+npm test
+npm run deploy:local
+npm run deploy:sepolia
+npm run lint
+npm run format:check
+npm run audit
+```
+
+## Environment
+
+```bash
+PRIVATE_KEY=
+SEPOLIA_RPC_URL=
+MAINNET_RPC_URL=
+ETHERSCAN_API_KEY=
+REPORT_GAS=false
+BUNDLER_RPC_URL=
+PAYMASTER_RPC_URL=
+```
+
+## Production Checklist
+
+- Replace development EntryPoint with a canonical ERC-4337 EntryPoint deployment.
+- Add invariant and fuzz tests for account validation and nonce handling.
+- Run static analysis with Slither.
+- Run gas reports on all account execution paths.
+- Confirm UUPS upgrade controls with a multisig or governance process.
+- Add deployment approvals and protected environments in GitHub.
+- Pin dependency ranges before audited releases.

package/templates/hardhat-erc4337/contracts/AccountFactory.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {Create2} from "@openzeppelin/contracts/utils/Create2.sol";
+import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
+import {IEntryPoint} from "./interfaces/IEntryPoint.sol";
+import {SmartAccount} from "./SmartAccount.sol";
+
+contract AccountFactory {
+    SmartAccount public immutable accountImplementation;
+    IEntryPoint public immutable entryPoint;
+
+    event AccountCreated(address indexed account, address indexed owner, uint256 salt);
+
+    constructor(IEntryPoint factoryEntryPoint) {
+        entryPoint = factoryEntryPoint;
+        accountImplementation = new SmartAccount();
+    }
+
+    function createAccount(address owner, uint256 salt) external returns (SmartAccount account) {
+        address predicted = getAccountAddress(owner, salt);
+        if (predicted.code.length > 0) {
+            return SmartAccount(payable(predicted));
+        }
+
+        bytes memory initializer = abi.encodeCall(SmartAccount.initialize, (owner, entryPoint));
+        bytes memory bytecode = abi.encodePacked(
+            type(ERC1967Proxy).creationCode,
+            abi.encode(address(accountImplementation), initializer)
+        );
+
+        account = SmartAccount(payable(Create2.deploy(0, bytes32(salt), bytecode)));
+        emit AccountCreated(address(account), owner, salt);
+    }
+
+    function getAccountAddress(address owner, uint256 salt) public view returns (address) {
+        bytes memory initializer = abi.encodeCall(SmartAccount.initialize, (owner, entryPoint));
+        bytes memory bytecode = abi.encodePacked(
+            type(ERC1967Proxy).creationCode,
+            abi.encode(address(accountImplementation), initializer)
+        );
+
+        return Create2.computeAddress(bytes32(salt), keccak256(bytecode));
+    }
+}

package/templates/hardhat-erc4337/contracts/EntryPoint.sol

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {IEntryPoint} from "./interfaces/IEntryPoint.sol";
+
+contract EntryPoint is IEntryPoint {
+    mapping(address => uint256) private deposits;
+
+    event UserOperationHandled(address indexed sender, bytes32 indexed userOpHash, bool success);
+    event Deposited(address indexed account, uint256 amount);
+    event Withdrawn(address indexed account, address indexed withdrawAddress, uint256 amount);
+
+    receive() external payable {
+        depositTo(msg.sender);
+    }
+
+    function handleOps(
+        UserOperation[] calldata ops,
+        address payable beneficiary
+    ) external override {
+        uint256 collected;
+        for (uint256 i = 0; i < ops.length; i++) {
+            bytes32 opHash = getUserOpHash(ops[i]);
+            (bool success, ) = ops[i].sender.call(ops[i].callData);
+            emit UserOperationHandled(ops[i].sender, opHash, success);
+            collected += ops[i].preVerificationGas;
+        }
+
+        if (collected > 0 && address(this).balance >= collected) {
+            beneficiary.transfer(collected);
+        }
+    }
+
+    function getUserOpHash(UserOperation calldata userOp) public view override returns (bytes32) {
+        return
+            keccak256(
+                abi.encode(
+                    userOp.sender,
+                    userOp.nonce,
+                    keccak256(userOp.initCode),
+                    keccak256(userOp.callData),
+                    userOp.callGasLimit,
+                    userOp.verificationGasLimit,
+                    userOp.preVerificationGas,
+                    userOp.maxFeePerGas,
+                    userOp.maxPriorityFeePerGas,
+                    keccak256(userOp.paymasterAndData),
+                    block.chainid,
+                    address(this)
+                )
+            );
+    }
+
+    function depositTo(address account) public payable override {
+        deposits[account] += msg.value;
+        emit Deposited(account, msg.value);
+    }
+
+    function balanceOf(address account) external view override returns (uint256) {
+        return deposits[account];
+    }
+
+    function withdrawTo(address payable withdrawAddress, uint256 amount) external override {
+        require(deposits[msg.sender] >= amount, "Insufficient deposit");
+        deposits[msg.sender] -= amount;
+        withdrawAddress.transfer(amount);
+        emit Withdrawn(msg.sender, withdrawAddress, amount);
+    }
+}

package/templates/hardhat-erc4337/contracts/SmartAccount.sol

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {MessageHashUtils} from "@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol";
+import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import {IEntryPoint} from "./interfaces/IEntryPoint.sol";
+
+contract SmartAccount is Initializable, OwnableUpgradeable, UUPSUpgradeable {
+    using ECDSA for bytes32;
+
+    error NotEntryPoint();
+    error ExecutionFailed(bytes result);
+    error InvalidSignature();
+
+    IEntryPoint public entryPoint;
+    uint256 public nonce;
+
+    event EntryPointUpdated(address indexed entryPoint);
+    event AccountExecuted(address indexed target, uint256 value, bytes data);
+
+    modifier onlyEntryPoint() {
+        if (msg.sender != address(entryPoint)) revert NotEntryPoint();
+        _;
+    }
+
+    constructor() {
+        _disableInitializers();
+    }
+
+    function initialize(address initialOwner, IEntryPoint accountEntryPoint) external initializer {
+        __Ownable_init(initialOwner);
+        entryPoint = accountEntryPoint;
+        emit EntryPointUpdated(address(accountEntryPoint));
+    }
+
+    receive() external payable {}
+
+    function execute(address target, uint256 value, bytes calldata data) external onlyEntryPoint {
+        _call(target, value, data);
+    }
+
+    function executeBatch(
+        address[] calldata targets,
+        uint256[] calldata values,
+        bytes[] calldata payloads
+    ) external onlyEntryPoint {
+        require(
+            targets.length == values.length && targets.length == payloads.length,
+            "Length mismatch"
+        );
+        for (uint256 i = 0; i < targets.length; i++) {
+            _call(targets[i], values[i], payloads[i]);
+        }
+    }
+
+    function validateUserOp(
+        IEntryPoint.UserOperation calldata userOp,
+        bytes32 userOpHash,
+        uint256 missingAccountFunds
+    ) external onlyEntryPoint returns (uint256 validationData) {
+        bytes32 digest = MessageHashUtils.toEthSignedMessageHash(userOpHash);
+        address recovered = ECDSA.recover(digest, userOp.signature);
+        if (recovered != owner()) revert InvalidSignature();
+
+        require(userOp.nonce == nonce, "Invalid nonce");
+        unchecked {
+            nonce++;
+        }
+
+        if (missingAccountFunds > 0) {
+            (bool sent, ) = payable(msg.sender).call{value: missingAccountFunds}("");
+            require(sent, "Prefund failed");
+        }
+
+        return 0;
+    }
+
+    function updateEntryPoint(IEntryPoint newEntryPoint) external onlyOwner {
+        entryPoint = newEntryPoint;
+        emit EntryPointUpdated(address(newEntryPoint));
+    }
+
+    function _call(address target, uint256 value, bytes calldata data) internal {
+        (bool success, bytes memory result) = target.call{value: value}(data);
+        if (!success) revert ExecutionFailed(result);
+        emit AccountExecuted(target, value, data);
+    }
+
+    function _authorizeUpgrade(address) internal override onlyOwner {}
+}

package/templates/hardhat-erc4337/contracts/Token.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+contract Token is ERC20, Ownable {
+    constructor(address initialOwner) ERC20("ABC Demo Token", "ABC") Ownable(initialOwner) {
+        _mint(initialOwner, 1_000_000 ether);
+    }
+
+    function mint(address to, uint256 amount) external onlyOwner {
+        _mint(to, amount);
+    }
+}

package/templates/hardhat-erc4337/contracts/interfaces/IEntryPoint.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+interface IEntryPoint {
+    struct UserOperation {
+        address sender;
+        uint256 nonce;
+        bytes initCode;
+        bytes callData;
+        uint256 callGasLimit;
+        uint256 verificationGasLimit;
+        uint256 preVerificationGas;
+        uint256 maxFeePerGas;
+        uint256 maxPriorityFeePerGas;
+        bytes paymasterAndData;
+        bytes signature;
+    }
+
+    function handleOps(UserOperation[] calldata ops, address payable beneficiary) external;
+    function getUserOpHash(UserOperation calldata userOp) external view returns (bytes32);
+    function depositTo(address account) external payable;
+    function balanceOf(address account) external view returns (uint256);
+    function withdrawTo(address payable withdrawAddress, uint256 amount) external;
+}

package/templates/hardhat-erc4337/contracts/interfaces/IPaymasterHook.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {IEntryPoint} from "./IEntryPoint.sol";
+
+interface IPaymasterHook {
+    function validatePaymasterUserOp(
+        IEntryPoint.UserOperation calldata userOp,
+        bytes32 userOpHash,
+        uint256 maxCost
+    ) external returns (bytes memory context, uint256 validationData);
+}

package/templates/hardhat-erc4337/deployments/.gitkeep

@@ -0,0 +1 @@
+

package/templates/hardhat-erc4337/hardhat.config.ts

@@ -0,0 +1,41 @@
+import hardhatEthers from "@nomicfoundation/hardhat-ethers";
+import hardhatMocha from "@nomicfoundation/hardhat-mocha";
+import accountsTask from "./tasks/accounts.js";
+import { defineConfig } from "hardhat/config";
+import { env } from "./scripts/lib/env.js";
+
+const accounts = env.PRIVATE_KEY ? [env.PRIVATE_KEY] : [];
+
+export default defineConfig({
+  plugins: [hardhatEthers, hardhatMocha],
+  tasks: [accountsTask],
+  solidity: {
+    version: "0.8.24",
+    settings: {
+      optimizer: {
+        enabled: true,
+        runs: 200
+      },
+      viaIR: true
+    }
+  },
+  networks: {
+    localhost: {
+      type: "http",
+      url: "http://127.0.0.1:8545",
+      chainId: 31337
+    },
+    sepolia: {
+      type: "http",
+      url: env.SEPOLIA_RPC_URL,
+      chainId: 11155111,
+      accounts
+    },
+    mainnet: {
+      type: "http",
+      url: env.MAINNET_RPC_URL,
+      chainId: 1,
+      accounts
+    }
+  }
+});

package/templates/hardhat-erc4337/ignition/modules/AccountAbstraction.ts

@@ -0,0 +1,14 @@
+// Install @nomicfoundation/hardhat-ignition when enabling Ignition deployments.
+// The module shape is kept here so deployment ownership stays explicit.
+import { buildModule } from "hardhat/ignition";
+
+const AccountAbstractionModule = buildModule("AccountAbstractionModule", (m) => {
+  const deployer = m.getAccount(0);
+  const entryPoint = m.contract("EntryPoint");
+  const factory = m.contract("AccountFactory", [entryPoint]);
+  const token = m.contract("Token", [deployer]);
+
+  return { entryPoint, factory, token };
+});
+
+export default AccountAbstractionModule;

package/templates/hardhat-erc4337/package.json.tmpl

@@ -0,0 +1,62 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "ERC-4337 development environment generated by ABC Blockchain.",
+  "author": "{{creator}}",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "hardhat compile",
+    "clean": "hardhat clean",
+    "test": "hardhat test",
+    "ci": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run audit",
+    "deploy:local": "hardhat run scripts/deploy.ts --network localhost",
+    "deploy:sepolia": "hardhat run scripts/deploy.ts --network sepolia",
+    "lint": "eslint \"{scripts,tasks,test,ignition}/**/*.ts\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "audit": "npm audit --audit-level=moderate",
+    "slither": "slither . --config-file slither.config.json"
+  },
+  "abcBlockchain": {
+    "creator": "{{creator}}",
+    "signature": "{{signature}}",
+    "generatedBy": "abc-blockchain",
+    "telemetry": false
+  },
+  "dependencies": {
+    "@openzeppelin/contracts": "5.0.2",
+    "@openzeppelin/contracts-upgradeable": "5.0.2",
+    "dotenv": "16.4.5",
+    "ethers": "6.13.1",
+    "zod": "3.23.8"
+  },
+  "devDependencies": {
+    "@nomicfoundation/hardhat-ethers": "4.0.12",
+    "@nomicfoundation/hardhat-mocha": "3.0.20",
+    "@types/chai": "4.3.16",
+    "@types/mocha": "10.0.7",
+    "@types/node": "22.10.2",
+    "@typescript-eslint/eslint-plugin": "7.16.0",
+    "@typescript-eslint/parser": "7.16.0",
+    "chai": "4.4.1",
+    "eslint": "8.57.0",
+    "eslint-config-prettier": "9.1.0",
+    "hardhat": "3.7.0",
+    "husky": "9.1.1",
+    "prettier": "3.3.3",
+    "prettier-plugin-solidity": "1.3.1",
+    "ts-node": "10.9.2",
+    "typescript": "5.5.3"
+  },
+  "overrides": {
+    "diff": "8.0.3",
+    "serialize-javascript": "7.0.5",
+    "ws": "8.20.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/templates/hardhat-erc4337/scripts/createAccount.ts

@@ -0,0 +1,33 @@
+import { network } from "hardhat";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { log } from "./lib/logger.js";
+
+async function main() {
+  const connection = await network.create();
+  const { ethers } = connection;
+  const [owner] = await ethers.getSigners();
+  const chainId = Number((await ethers.provider.getNetwork()).chainId);
+  const deployment = JSON.parse(
+    await fs.readFile(path.join("deployments", `${chainId}.json`), "utf8")
+  ) as { contracts: { AccountFactory: string } };
+
+  const factory = await ethers.getContractAt("AccountFactory", deployment.contracts.AccountFactory);
+  const salt = 0n;
+  const predicted = await factory.getAccountAddress(owner.address, salt);
+  const tx = await factory.createAccount(owner.address, salt);
+  await tx.wait();
+
+  log.info("account:created", {
+    owner: owner.address,
+    smartAccount: predicted
+  });
+  await connection.close();
+}
+
+main().catch((error) => {
+  log.error("account:create:failed", {
+    error: error instanceof Error ? error.message : String(error)
+  });
+  process.exitCode = 1;
+});

package/templates/hardhat-erc4337/scripts/deploy.ts

@@ -0,0 +1,50 @@
+import { network } from "hardhat";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { log } from "./lib/logger.js";
+
+async function main() {
+  const connection = await network.create();
+  const { ethers } = connection;
+  const [deployer] = await ethers.getSigners();
+  log.info("deploy:start", { deployer: deployer.address });
+
+  const EntryPoint = await ethers.getContractFactory("EntryPoint");
+  const entryPoint = await EntryPoint.deploy();
+  await entryPoint.waitForDeployment();
+
+  const AccountFactory = await ethers.getContractFactory("AccountFactory");
+  const accountFactory = await AccountFactory.deploy(await entryPoint.getAddress());
+  await accountFactory.waitForDeployment();
+
+  const Token = await ethers.getContractFactory("Token");
+  const token = await Token.deploy(deployer.address);
+  await token.waitForDeployment();
+
+  const deployment = {
+    network: (await ethers.provider.getNetwork()).name,
+    chainId: Number((await ethers.provider.getNetwork()).chainId),
+    deployer: deployer.address,
+    contracts: {
+      EntryPoint: await entryPoint.getAddress(),
+      AccountFactory: await accountFactory.getAddress(),
+      Token: await token.getAddress()
+    },
+    creator: "{{creator}}",
+    signature: "{{signature}}"
+  };
+
+  await fs.mkdir("deployments", { recursive: true });
+  await fs.writeFile(
+    path.join("deployments", `${deployment.chainId}.json`),
+    JSON.stringify(deployment, null, 2)
+  );
+
+  log.info("deploy:complete", deployment);
+  await connection.close();
+}
+
+main().catch((error) => {
+  log.error("deploy:failed", { error: error instanceof Error ? error.message : String(error) });
+  process.exitCode = 1;
+});

package/templates/hardhat-erc4337/scripts/lib/bundler.ts

@@ -0,0 +1,17 @@
+import { JsonRpcProvider } from "ethers";
+import { env } from "./env.js";
+
+export type BundlerClient = {
+  sendUserOperation(userOperation: unknown, entryPoint: string): Promise<string>;
+};
+
+export function createBundlerClient(): BundlerClient | undefined {
+  if (!env.BUNDLER_RPC_URL) return undefined;
+  const provider = new JsonRpcProvider(env.BUNDLER_RPC_URL);
+
+  return {
+    async sendUserOperation(userOperation, entryPoint) {
+      return provider.send("eth_sendUserOperation", [userOperation, entryPoint]) as Promise<string>;
+    }
+  };
+}

package/templates/hardhat-erc4337/scripts/lib/env.ts

@@ -0,0 +1,18 @@
+import "dotenv/config";
+import { z } from "zod";
+
+const EnvSchema = z.object({
+  PRIVATE_KEY: z.string().optional(),
+  SEPOLIA_RPC_URL: z.string().url().optional().default("http://127.0.0.1:8545"),
+  MAINNET_RPC_URL: z.string().url().optional().default("http://127.0.0.1:8545"),
+  ETHERSCAN_API_KEY: z.string().optional().default(""),
+  REPORT_GAS: z
+    .string()
+    .optional()
+    .default("false")
+    .transform((value) => value === "true"),
+  BUNDLER_RPC_URL: z.string().url().optional(),
+  PAYMASTER_RPC_URL: z.string().url().optional()
+});
+
+export const env = EnvSchema.parse(process.env);