abc-blockchain 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kimberley Bezuidenhout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,89 @@
+# Publishing ABC Blockchain to npm
+
+Creator: Kimberley Bezuidenhout  
+Framework Signature: kimmicorn~glitch
+
+## Prerequisites
+
+- Node.js 20 or 22
+- npm account with publish rights for `abc-blockchain`
+- GitHub repository with Actions enabled
+- npm automation token stored as `NPM_TOKEN`
+
+## Local Release Checks
+
+Run these before publishing:
+
+```bash
+npm ci
+npm run ci
+npm pack --dry-run
+```
+
+Confirm the dry-run package includes:
+
+- `dist/`
+- `templates/`
+- `README.md`
+- `LICENSE`
+- no `.env`
+- no `node_modules`
+- no generated sample projects
+
+## First-Time npm Setup
+
+1. Create or log in to an npm account.
+2. Enable two-factor authentication on the account.
+3. Create an automation token at npm.
+4. In GitHub, open repository settings.
+5. Add `NPM_TOKEN` under `Settings > Secrets and variables > Actions`.
+6. Create an environment named `npm-production`.
+7. Add required reviewers to the `npm-production` environment.
+
+## Manual Publish from GitHub Actions
+
+1. Open `Actions`.
+2. Select `Publish to npm`.
+3. Click `Run workflow`.
+4. Enter the version, for example `0.1.1`.
+5. Keep `dry_run` enabled for the first run.
+6. Review the workflow logs and package contents.
+7. Run the workflow again with `dry_run` disabled.
+
+The workflow runs CI, updates the package version, verifies package contents, publishes with npm provenance, commits the version bump, and creates a `vX.Y.Z` git tag.
+
+## Manual Publish from Local Machine
+
+Use this only if GitHub Actions is unavailable:
+
+```bash
+npm ci
+npm run ci
+npm version 0.1.1
+npm publish --provenance --access public --tag latest
+git push origin main --follow-tags
+```
+
+## Dist Tags
+
+- `latest`: stable releases
+- `next`: release candidates
+- `beta`: beta releases
+- `alpha`: early internal validation
+
+Install examples:
+
+```bash
+npm install -g abc-blockchain@latest
+npx abc-blockchain init my-project
+```
+
+## Production Release Checklist
+
+- CI is green on `main`.
+- `npm audit --audit-level=moderate` passes for the CLI package.
+- Generated template compiles and tests with a fresh install.
+- README, SECURITY, and PUBLISHING docs match the release.
+- Package contents were reviewed through `npm pack --dry-run`.
+- GitHub environment approval is enabled for `npm-production`.
+- `NPM_TOKEN` is an npm automation token, not a personal password.

package/README.md

@@ -0,0 +1,144 @@
+# ABC Blockchain
+
+Enterprise-grade npm bootstrap framework for ERC-4337 Hardhat development environments.
+
+Creator: Kimberley Bezuidenhout  
+Framework Signature: kimmicorn~glitch
+
+## Usage
+
+```bash
+npx abc-blockchain init my-project
+cd my-project
+npm test
+```
+
+The generated project includes Solidity contracts, Hardhat, TypeScript, Ethers v6, OpenZeppelin, dotenv validation, CI, release workflow, linting, formatting, security scanning hooks, deployment scripts, tests, and ERC-4337 integration points.
+
+## CLI
+
+```bash
+abc-blockchain init <project-name> [--no-install] [--package-manager npm|pnpm|yarn]
+```
+
+## Generated File Tree
+
+```text
+my-project/
+├── contracts/
+│   ├── interfaces/
+│   │   ├── IEntryPoint.sol
+│   │   └── IPaymasterHook.sol
+│   ├── SmartAccount.sol
+│   ├── AccountFactory.sol
+│   ├── EntryPoint.sol
+│   └── Token.sol
+├── scripts/
+│   ├── lib/
+│   │   ├── bundler.ts
+│   │   ├── env.ts
+│   │   └── logger.ts
+│   ├── createAccount.ts
+│   └── deploy.ts
+├── deployments/
+├── ignition/
+│   └── modules/
+│       └── AccountAbstraction.ts
+├── tasks/
+│   └── accounts.ts
+├── test/
+│   └── SmartAccount.ts
+├── .github/workflows/
+│   ├── ci.yml
+│   └── release.yml
+├── hardhat.config.ts
+├── tsconfig.json
+├── .env.example
+├── README.md
+└── package.json
+```
+
+## Architecture
+
+- CLI package copies a versioned Hardhat template and renders project metadata.
+- Generated projects keep contracts, scripts, tasks, tests, deployments, and CI concerns separated.
+- Environment variables are parsed through Zod so missing or malformed configuration fails early.
+- Deployment scripts emit structured JSON logs and deployment manifests.
+- No telemetry, hidden network calls, covert tracking, or obfuscated code is included.
+
+## Implementation Roadmap
+
+1. Stabilize v0.1 template with EntryPoint integration, smart account factory, deterministic deployments, and tests.
+2. Add selectable templates for minimal, audited, upgradeable, and paymaster-enabled project profiles.
+3. Add real bundler and paymaster provider adapters for common ERC-4337 infrastructure vendors.
+4. Add Foundry optional profile, Slither CI container job, and contract size reporting.
+5. Add template snapshot tests and generated-project compile tests in CI.
+6. Publish v1.0 after external security review and compatibility checks across Node LTS versions.
+
+## Release Plan
+
+- Use semantic versioning.
+- `0.x`: rapid template iteration, breaking changes allowed with changelog entries.
+- `1.0`: stable CLI flags, stable generated folder contracts, documented migration guide.
+- Patch releases: bug fixes, dependency security bumps, documentation corrections.
+- Minor releases: new template options, new provider adapters, additional CI integrations.
+- Major releases: Hardhat or ERC-4337 interface upgrades that require user migration.
+
+## NPM Publishing Workflow
+
+This repository ships a production-oriented manual publish workflow at `.github/workflows/publish-npm.yml`.
+
+Local checks:
+
+```bash
+npm ci
+npm run ci
+npm pack --dry-run
+```
+
+GitHub setup:
+
+1. Create an npm automation token.
+2. Store it in GitHub Actions secrets as `NPM_TOKEN`.
+3. Create a GitHub environment named `npm-production`.
+4. Add required reviewers to the environment.
+5. Run the `Publish to npm` workflow with `dry_run` enabled first.
+6. Re-run the workflow with `dry_run` disabled when the package contents are correct.
+
+Manual fallback:
+
+```bash
+npm ci
+npm run ci
+npm version 0.1.1
+npm publish --provenance --access public
+git push origin main --follow-tags
+```
+
+See `PUBLISHING.md` for the full release checklist.
+
+## Repository Structure
+
+```text
+abc-blockchain/
+├── src/
+│   ├── branding.ts
+│   ├── cli.ts
+│   ├── config.ts
+│   ├── create-project.ts
+│   ├── logger.ts
+│   ├── package-manager.ts
+│   └── template.ts
+├── templates/
+│   └── hardhat-erc4337/
+├── .github/workflows/
+├── PUBLISHING.md
+├── SECURITY.md
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Security Position
+
+ABC Blockchain intentionally avoids hardcoded secrets, hidden backdoors, malicious telemetry, covert tracking, and opaque logic. Generated projects include environment validation, dependency audit scripts, CodeQL scanning, Slither-ready configuration, and audit-friendly folder boundaries.

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Supported Versions
+
+ABC Blockchain is pre-1.0. Security fixes are released on the latest minor line.
+
+## Reporting a Vulnerability
+
+Report vulnerabilities privately to the repository maintainer. Do not open public issues for suspected exploitable behavior.
+
+Include:
+
+- Affected version
+- Reproduction steps
+- Impact assessment
+- Suggested fix, if known
+
+## Security Guarantees
+
+ABC Blockchain does not include hidden telemetry, covert tracking, backdoors, or obfuscated logic.
+
+Generated projects are designed to avoid hardcoded secrets and include:
+
+- `.env.example` with no real credentials
+- Zod environment validation
+- GitHub Actions CI
+- npm audit gate
+- CodeQL analysis
+- Slither-ready Solidity layout
+- Explicit creator attribution
+
+## Required Production Review
+
+Before deploying generated contracts to production:
+
+- Replace the development `EntryPoint.sol` with the canonical audited ERC-4337 EntryPoint for the target network.
+- Run Slither and review all findings.
+- Run gas reports for account validation and execution paths.
+- Review UUPS upgrade ownership and transfer it to a multisig or governance process.
+- Audit paymaster and bundler trust assumptions.
+- Pin dependency versions for audited releases.

package/dist/branding.d.ts

@@ -0,0 +1,7 @@
+export declare const BRAND: {
+    readonly packageName: "abc-blockchain";
+    readonly frameworkName: "ABC Blockchain";
+    readonly creator: "Kimberley Bezuidenhout";
+    readonly signature: "kimmicorn~glitch";
+};
+export declare function banner(): string;

package/dist/branding.js

@@ -0,0 +1,14 @@
+export const BRAND = {
+    packageName: "abc-blockchain",
+    frameworkName: "ABC Blockchain",
+    creator: "Kimberley Bezuidenhout",
+    signature: "kimmicorn~glitch"
+};
+export function banner() {
+    return [
+        "ABC Blockchain",
+        `Creator: ${BRAND.creator}`,
+        `Framework Signature: ${BRAND.signature}`,
+        "Enterprise ERC-4337 Hardhat bootstrap"
+    ].join("\n");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { banner, BRAND } from "./branding.js";
+import { createProject } from "./create-project.js";
+import { logger } from "./logger.js";
+const program = new Command();
+program
+    .name(BRAND.packageName)
+    .description("Generate enterprise-grade ERC-4337 Hardhat development environments.")
+    .version("0.1.0");
+program
+    .command("init")
+    .argument("<project-name>", "Project directory and npm package name")
+    .option("--no-install", "Skip dependency installation")
+    .option("--package-manager <manager>", "npm, pnpm, or yarn", "npm")
+    .action(async (projectName, options) => {
+    console.log(banner());
+    try {
+        await createProject({
+            projectName,
+            cwd: process.cwd(),
+            install: options.install,
+            packageManager: options.packageManager
+        }, logger);
+    }
+    catch (error) {
+        logger.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});
+await program.parseAsync(process.argv);

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const InitOptionsSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    cwd: z.ZodString;
+    install: z.ZodDefault<z.ZodBoolean>;
+    packageManager: z.ZodDefault<z.ZodEnum<["npm", "pnpm", "yarn"]>>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    cwd: string;
+    install: boolean;
+    packageManager: "npm" | "pnpm" | "yarn";
+}, {
+    projectName: string;
+    cwd: string;
+    install?: boolean | undefined;
+    packageManager?: "npm" | "pnpm" | "yarn" | undefined;
+}>;
+export type InitOptions = z.infer<typeof InitOptionsSchema>;
+export type ResolvedInitConfig = InitOptions & {
+    targetDirectory: string;
+};
+export declare function resolveInitConfig(input: InitOptions): ResolvedInitConfig;

package/dist/config.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { z } from "zod";
+export const InitOptionsSchema = z.object({
+    projectName: z.string().min(1),
+    cwd: z.string().min(1),
+    install: z.boolean().default(true),
+    packageManager: z.enum(["npm", "pnpm", "yarn"]).default("npm")
+});
+export function resolveInitConfig(input) {
+    const options = InitOptionsSchema.parse(input);
+    return {
+        ...options,
+        targetDirectory: path.resolve(options.cwd, options.projectName)
+    };
+}

package/dist/create-project.d.ts

@@ -0,0 +1,3 @@
+import { type InitOptions } from "./config.js";
+import type { Logger } from "./logger.js";
+export declare function createProject(input: InitOptions, log: Logger): Promise<void>;

package/dist/create-project.js

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import fs from "fs-extra";
+import validatePackageName from "validate-npm-package-name";
+import { BRAND } from "./branding.js";
+import { resolveInitConfig } from "./config.js";
+import { displayRunCommand, installCommand } from "./package-manager.js";
+import { copyTemplate } from "./template.js";
+export async function createProject(input, log) {
+    const config = resolveInitConfig(input);
+    const validation = validatePackageName(config.projectName);
+    if (!validation.validForNewPackages) {
+        throw new Error([...(validation.errors ?? []), ...(validation.warnings ?? [])].join("\n") ||
+            "Project name is not a valid npm package name.");
+    }
+    if (await fs.pathExists(config.targetDirectory)) {
+        const existing = await fs.readdir(config.targetDirectory);
+        if (existing.length > 0) {
+            throw new Error(`Target directory is not empty: ${config.targetDirectory}`);
+        }
+    }
+    await fs.ensureDir(config.targetDirectory);
+    await copyTemplate(config.targetDirectory, {
+        projectName: config.projectName,
+        creator: BRAND.creator,
+        signature: BRAND.signature
+    });
+    log.success(`Generated ${config.projectName} at ${config.targetDirectory}`);
+    if (config.install) {
+        const [command, ...args] = installCommand(config.packageManager);
+        log.info(`Installing dependencies with ${config.packageManager}...`);
+        await run(command, args, config.targetDirectory);
+    }
+    else {
+        log.warn("Skipped dependency installation.");
+    }
+    log.success("ABC Blockchain project ready.");
+    log.info(`Next: cd ${config.projectName}`);
+    log.info(`Test: ${displayRunCommand(config.packageManager, "test")}`);
+}
+function run(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            stdio: "inherit",
+            shell: process.platform === "win32"
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${command} ${args.join(" ")} exited with code ${code}`));
+        });
+    });
+}

package/dist/create-project.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/create-project.test.js

@@ -0,0 +1,29 @@
+import fs from "fs-extra";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { createProject } from "./create-project.js";
+const silentLogger = {
+    info() { },
+    success() { },
+    warn() { },
+    error() { }
+};
+void describe("createProject", () => {
+    void it("generates a complete Hardhat ERC-4337 project", async () => {
+        const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "abc-blockchain-"));
+        await createProject({
+            projectName: "sample-aa",
+            cwd,
+            install: false,
+            packageManager: "npm"
+        }, silentLogger);
+        const projectRoot = path.join(cwd, "sample-aa");
+        assert.equal(await fs.pathExists(path.join(projectRoot, "contracts", "SmartAccount.sol")), true);
+        const generatedPackage = await fs.readJson(path.join(projectRoot, "package.json"));
+        assert.equal(generatedPackage.name, "sample-aa");
+        assert.equal(generatedPackage.abcBlockchain.creator, "Kimberley Bezuidenhout");
+        assert.equal(generatedPackage.abcBlockchain.signature, "kimmicorn~glitch");
+    });
+});

package/dist/logger.d.ts

@@ -0,0 +1,7 @@
+export interface Logger {
+    info(message: string): void;
+    success(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export declare const logger: Logger;

package/dist/logger.js

@@ -0,0 +1,15 @@
+import chalk from "chalk";
+export const logger = {
+    info(message) {
+        console.log(chalk.cyan("info"), message);
+    },
+    success(message) {
+        console.log(chalk.green("done"), message);
+    },
+    warn(message) {
+        console.warn(chalk.yellow("warn"), message);
+    },
+    error(message) {
+        console.error(chalk.red("error"), message);
+    }
+};

package/dist/package-manager.d.ts

@@ -0,0 +1,3 @@
+export type PackageManager = "npm" | "pnpm" | "yarn";
+export declare function installCommand(packageManager: PackageManager): string[];
+export declare function displayRunCommand(packageManager: PackageManager, script: string): string;

package/dist/package-manager.js

@@ -0,0 +1,14 @@
+export function installCommand(packageManager) {
+    if (packageManager === "yarn")
+        return ["yarn"];
+    if (packageManager === "pnpm")
+        return ["pnpm", "install"];
+    return ["npm", "install"];
+}
+export function displayRunCommand(packageManager, script) {
+    if (packageManager === "yarn")
+        return `yarn ${script}`;
+    if (packageManager === "pnpm")
+        return `pnpm ${script}`;
+    return `npm run ${script}`;
+}

package/dist/template.d.ts

@@ -0,0 +1,3 @@
+export type TemplateVariables = Record<string, string>;
+export declare function templateRoot(): string;
+export declare function copyTemplate(targetDirectory: string, variables: TemplateVariables): Promise<void>;

package/dist/template.js

@@ -0,0 +1,30 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+export function templateRoot() {
+    return path.resolve(dirname, "../templates/hardhat-erc4337");
+}
+export async function copyTemplate(targetDirectory, variables) {
+    await fs.copy(templateRoot(), targetDirectory, {
+        filter: (source) => !source.endsWith(".DS_Store")
+    });
+    await renderTemplates(targetDirectory, variables);
+}
+async function renderTemplates(directory, variables) {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+        const absolutePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            await renderTemplates(absolutePath, variables);
+            return;
+        }
+        if (!entry.name.endsWith(".tmpl"))
+            return;
+        const outputPath = absolutePath.replace(/\.tmpl$/, "");
+        const source = await fs.readFile(absolutePath, "utf8");
+        const rendered = Object.entries(variables).reduce((next, [key, value]) => next.replaceAll(`{{${key}}}`, value), source);
+        await fs.writeFile(outputPath, rendered, "utf8");
+        await fs.remove(absolutePath);
+    }));
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "abc-blockchain",
+  "version": "0.1.1",
+  "description": "Enterprise-grade ERC-4337 Hardhat bootstrap framework.",
+  "author": "Kimberley Bezuidenhout",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "abc-blockchain": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "PUBLISHING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "ci": "npm run format:check && npm run lint && npm test && npm audit --audit-level=moderate && npm run pack:check",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint \"src/**/*.ts\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "npm run build && node --test dist/create-project.test.js",
+    "pack:check": "npm pack --dry-run",
+    "prepack": "npm run build",
+    "prepare": "husky",
+    "release": "npm publish --provenance --access public"
+  },
+  "keywords": [
+    "erc-4337",
+    "hardhat",
+    "account-abstraction",
+    "ethereum",
+    "smart-contracts",
+    "bootstrap"
+  ],
+  "abcBlockchain": {
+    "creator": "Kimberley Bezuidenhout",
+    "signature": "kimmicorn~glitch",
+    "telemetry": false
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.0.1",
+    "validate-npm-package-name": "^5.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.14.10",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "@typescript-eslint/eslint-plugin": "^7.16.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "eslint": "^8.57.0",
+    "husky": "^9.1.1",
+    "prettier": "^3.3.3",
+    "prettier-plugin-solidity": "^1.3.1",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/templates/hardhat-erc4337/.env.example

@@ -0,0 +1,7 @@
+PRIVATE_KEY=
+SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY
+MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_KEY
+ETHERSCAN_API_KEY=
+REPORT_GAS=false
+BUNDLER_RPC_URL=https://bundler.example/rpc
+PAYMASTER_RPC_URL=https://paymaster.example/rpc

package/templates/hardhat-erc4337/.eslintrc.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  root: true,
+  parser: "@typescript-eslint/parser",
+  plugins: ["@typescript-eslint"],
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
+  env: {
+    node: true,
+    mocha: true,
+    es2022: true
+  },
+  rules: {
+    "@typescript-eslint/consistent-type-imports": "error"
+  }
+};