create-qorechain-dapp 0.3.0

package/templates/evm-solidity/contracts/Counter.sol

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.24;
+
+/// @title Counter
+/// @notice A minimal storage contract: a single number you can read, set, and
+///         increment. Used as the smallest useful example of deploying and
+///         interacting with a contract on the QoreChain EVM Engine.
+contract Counter {
+    /// @notice The current count.
+    uint256 public count;
+
+    /// @notice Emitted whenever the count changes.
+    event CountChanged(uint256 newCount);
+
+    /// @param initial The starting value for the counter.
+    constructor(uint256 initial) {
+        count = initial;
+        emit CountChanged(initial);
+    }
+
+    /// @notice Increase the count by one.
+    function increment() external {
+        count += 1;
+        emit CountChanged(count);
+    }
+
+    /// @notice Set the count to an explicit value.
+    /// @param value The new count.
+    function set(uint256 value) external {
+        count = value;
+        emit CountChanged(value);
+    }
+}

package/templates/evm-solidity/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "qorechain-evm-solidity-dapp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A QoreChain EVM dApp: a Solidity Counter contract deployed and exercised with viem via @qorechain/evm.",
+  "scripts": {
+    "deploy": "tsx scripts/deploy.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@qorechain/evm": "^0.3.0",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.3"
+  }
+}

package/templates/evm-solidity/scripts/deploy.ts

@@ -0,0 +1,98 @@
+/**
+ * deploy.ts — deploy the Counter contract to the QoreChain EVM Engine and
+ * exercise it: read the initial count, increment it, and read it back.
+ *
+ * Uses @qorechain/evm:
+ *   - createEvmClient({ endpoints })  → a viem-backed client (chain id auto-detected)
+ *   - deployContract(walletClient, …) → deploy and get the tx hash
+ *   - readContract / writeContract    → typed reads and writes
+ *
+ * Requirements (see README):
+ *   - QORE_EVM_RPC_URL pointing at a reachable QoreChain EVM JSON-RPC endpoint.
+ *   - QORE_EVM_PRIVATE_KEY for a funded EVM account (0x-prefixed, 32 bytes).
+ */
+import {
+  createEvmClient,
+  deployContract,
+  evmAccountFromPrivateKey,
+  readContract,
+  writeContract,
+} from "@qorechain/evm";
+import type { Address, Hex } from "viem";
+
+import { counterAbi, counterBytecode } from "../contracts/Counter.artifact.js";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+async function main(): Promise<void> {
+  const evmRpc = process.env.QORE_EVM_RPC_URL ?? "http://localhost:8545";
+  const privateKey = requireEnv("QORE_EVM_PRIVATE_KEY") as Hex;
+  const initialCount = BigInt(process.env.QORE_COUNTER_INITIAL ?? "0");
+
+  const client = await createEvmClient({ endpoints: { evmRpc } });
+  const account = evmAccountFromPrivateKey(privateKey);
+  const wallet = client.getWalletClient(account);
+
+  console.log(`network:  QoreChain EVM (chain id ${await client.getChainId()})`);
+  console.log(`deployer: ${account.address}`);
+
+  // Deploy.
+  console.log(`\nDeploying Counter(initial=${initialCount})…`);
+  const deployHash = await deployContract(wallet, {
+    abi: counterAbi,
+    bytecode: counterBytecode,
+    args: [initialCount],
+  });
+  const receipt = await client.publicClient.waitForTransactionReceipt({
+    hash: deployHash,
+  });
+  const contract = receipt.contractAddress;
+  if (!contract) {
+    throw new Error("Deployment receipt did not include a contract address.");
+  }
+  console.log(`deployed: ${contract}`);
+
+  // Read.
+  const before = await readContract(client.publicClient, {
+    address: contract as Address,
+    abi: counterAbi,
+    functionName: "count",
+  });
+  console.log(`count (before): ${before}`);
+
+  // Write: increment. `account` and `chain` come from the wallet client; we pass
+  // them explicitly so the call type-checks against viem's strict signature.
+  console.log("\nCalling increment()…");
+  const incHash = await writeContract(wallet, {
+    address: contract as Address,
+    abi: counterAbi,
+    functionName: "increment",
+    account: wallet.account ?? null,
+    chain: wallet.chain,
+  });
+  await client.publicClient.waitForTransactionReceipt({ hash: incHash });
+
+  // Read again.
+  const after = await readContract(client.publicClient, {
+    address: contract as Address,
+    abi: counterAbi,
+    functionName: "count",
+  });
+  console.log(`count (after):  ${after}`);
+  console.log("\nDone.");
+}
+
+main().catch((err: unknown) => {
+  console.error("\nDeploy failed.");
+  console.error(
+    "Check QORE_EVM_RPC_URL is reachable and QORE_EVM_PRIVATE_KEY funds an account.",
+  );
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/templates/evm-solidity/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "lib": ["ES2022"],
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["scripts", "contracts"]
+}

package/templates/fullstack-web/.env.example

@@ -0,0 +1,5 @@
+# QoreChain endpoints for the web app (Vite exposes only VITE_-prefixed vars).
+# Defaults target localhost so the app runs out of the box against a local node.
+# Point these at a testnet (qorechain-diana) or mainnet (qorechain-vladi) node.
+VITE_QORE_REST_URL=http://localhost:1317
+VITE_QORE_EVM_RPC_URL=http://localhost:8545

package/templates/fullstack-web/README.md

@@ -0,0 +1,53 @@
+# QoreChain full-stack web starter
+
+A minimal [Vite](https://vitejs.dev) + React + TypeScript dApp that uses
+[`@qorechain/sdk`](https://github.com/qorechain/qorechain-sdk) to:
+
+- connect to QoreChain testnet (`createClient`),
+- read a native balance for an address you enter, and
+- read the tokenomics overview (`qor_getTokenomicsOverview`).
+
+## Prerequisites
+
+- **Node.js >= 20**.
+- A reachable QoreChain **REST** endpoint (`VITE_QORE_REST_URL`) for balances and
+  an **EVM JSON-RPC** endpoint (`VITE_QORE_EVM_RPC_URL`) for the `qor_*`
+  namespace. Both default to localhost. Point them at a testnet
+  (`qorechain-diana`) or mainnet (`qorechain-vladi`) node, or a local node.
+
+## Setup & run
+
+```sh
+pnpm install
+cp .env.example .env   # the scaffolder already does this for you
+pnpm dev               # http://localhost:5173
+```
+
+Configure endpoints in `.env` (only `VITE_`-prefixed vars are exposed to the
+browser):
+
+| Variable               | Purpose                | Default                 |
+| ---------------------- | ---------------------- | ----------------------- |
+| `VITE_QORE_REST_URL`     | Cosmos REST (balances) | `http://localhost:1317` |
+| `VITE_QORE_EVM_RPC_URL`  | EVM JSON-RPC (`qor_*`) | `http://localhost:8545` |
+
+## Build / type-check
+
+```sh
+pnpm typecheck   # tsc --noEmit
+pnpm build       # type-check + vite build
+```
+
+## Using `@qorechain/sdk` before it is published
+
+`@qorechain/sdk` is published to npm — once published, `pnpm install` just
+works. Until then, scaffold with the CLI's `--local` flag to rewrite the
+dependency to a `file:` link into the SDK monorepo, after building the workspace
+packages:
+
+```sh
+# at the qorechain-sdk monorepo root
+pnpm -r build
+# then scaffold with --local
+npx create-qorechain-dapp my-dapp --template fullstack-web --local
+```

package/templates/fullstack-web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>QoreChain dApp</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/fullstack-web/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "qorechain-fullstack-web-dapp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A minimal Vite + React + TypeScript QoreChain dApp using @qorechain/sdk to read balances and tokenomics.",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@qorechain/sdk": "^0.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.0"
+  }
+}

package/templates/fullstack-web/src/App.tsx

@@ -0,0 +1,134 @@
+import { useMemo, useState } from "react";
+
+import { createClient, type QoreChainClient } from "@qorechain/sdk";
+
+// Endpoints come from Vite env vars (VITE_-prefixed), with localhost defaults so
+// the app runs out of the box against a local node. Override in `.env`.
+const REST_URL = import.meta.env.VITE_QORE_REST_URL ?? "http://localhost:1317";
+const EVM_RPC_URL =
+  import.meta.env.VITE_QORE_EVM_RPC_URL ?? "http://localhost:8545";
+
+interface Balance {
+  denom: string;
+  amount: string;
+}
+
+export function App(): JSX.Element {
+  // One client for the app's lifetime.
+  const client: QoreChainClient = useMemo(
+    () =>
+      createClient({
+        network: "testnet",
+        endpoints: { rest: REST_URL, evmRpc: EVM_RPC_URL },
+      }),
+    [],
+  );
+
+  const [address, setAddress] = useState("");
+  const [balances, setBalances] = useState<Balance[] | null>(null);
+  const [tokenomics, setTokenomics] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function loadBalance(): Promise<void> {
+    setError(null);
+    setBalances(null);
+    if (!address.trim()) {
+      setError("Enter an address first.");
+      return;
+    }
+    setLoading(true);
+    try {
+      const res = await client.rest.getAllBalances(address.trim());
+      setBalances(res.balances as Balance[]);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function loadTokenomics(): Promise<void> {
+    setError(null);
+    setTokenomics(null);
+    setLoading(true);
+    try {
+      const overview = await client.qor.getTokenomicsOverview();
+      setTokenomics(JSON.stringify(overview, null, 2));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <main
+      style={{
+        fontFamily: "system-ui, sans-serif",
+        maxWidth: 720,
+        margin: "2rem auto",
+        padding: "0 1rem",
+        lineHeight: 1.5,
+      }}
+    >
+      <h1>QoreChain dApp</h1>
+      <p style={{ color: "#555" }}>
+        Network: <code>{client.network.name}</code> (
+        <code>{client.network.chainId ?? "n/a"}</code>) &middot; REST:{" "}
+        <code>{REST_URL}</code>
+      </p>
+
+      <section style={{ marginTop: "1.5rem" }}>
+        <h2>Native balance</h2>
+        <div style={{ display: "flex", gap: "0.5rem" }}>
+          <input
+            value={address}
+            onChange={(e) => setAddress(e.target.value)}
+            placeholder="qor1…"
+            style={{ flex: 1, padding: "0.5rem" }}
+            aria-label="QoreChain address"
+          />
+          <button onClick={loadBalance} disabled={loading}>
+            Get balance
+          </button>
+        </div>
+        {balances && (
+          <ul>
+            {balances.length === 0 && <li>(no balances)</li>}
+            {balances.map((b) => (
+              <li key={b.denom}>
+                {b.amount} {b.denom}
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+
+      <section style={{ marginTop: "1.5rem" }}>
+        <h2>Tokenomics overview</h2>
+        <button onClick={loadTokenomics} disabled={loading}>
+          Read qor_getTokenomicsOverview
+        </button>
+        {tokenomics && (
+          <pre
+            style={{
+              background: "#f5f5f5",
+              padding: "1rem",
+              overflowX: "auto",
+              borderRadius: 6,
+            }}
+          >
+            {tokenomics}
+          </pre>
+        )}
+      </section>
+
+      {error && (
+        <p style={{ color: "#b00020", marginTop: "1rem" }} role="alert">
+          {error}
+        </p>
+      )}
+    </main>
+  );
+}

package/templates/fullstack-web/src/main.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App.js";
+
+const container = document.getElementById("root");
+if (!container) {
+  throw new Error("Root element #root not found");
+}
+
+createRoot(container).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/templates/fullstack-web/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_QORE_REST_URL?: string;
+  readonly VITE_QORE_EVM_RPC_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/templates/fullstack-web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "noEmit": true,
+    "useDefineForClassFields": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/fullstack-web/vite.config.ts

@@ -0,0 +1,10 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// Minimal Vite config for the QoreChain full-stack web starter.
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+  },
+});