feat: add check-balance command and improve faucet funding instructions

- Added new 'npm run check-balance' command to verify wallet balance
- Created check-balance.ts template for standalone balance checking
- Improved deploy script messaging with clearer faucet instructions
- Added guidance for handling faucet transaction delays (2-5 minutes)
- Updated README with check-balance command and troubleshooting
- Provides users with options: wait for auto-detection or manually check

Author: Olanetsoft

README.md

@@ -87,6 +87,10 @@ Builds your TypeScript source code to JavaScript in the `dist/` directory
 
 Deploys your compiled contract to the Midnight testnet
 
+### `npm run check-balance`
+
+Checks your wallet balance. Useful for verifying if test tokens from the faucet have arrived before deploying.
+
 ## Project Structure
 
 ```
@@ -176,6 +180,24 @@ PROOF_SERVER_URL=http://localhost:6300
 
 ## Troubleshooting
 
+### Waiting for faucet funds
+
+If your deployment is waiting for funds from the testnet faucet:
+
+```bash
+# Option 1: Let the script wait (it will auto-detect funds)
+# Just leave it running after requesting from the faucet
+
+# Option 2: Stop and check manually
+# Press Ctrl+C to stop, then:
+npm run check-balance
+
+# Once funded, deploy:
+npm run deploy
+```
+
+💡 **Note**: Faucet transactions typically take 2-5 minutes to process.
+
 ### Port 6300 already in use
 
 If you see "Bind for 0.0.0.0:6300 failed: port is already allocated":

package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mn-app",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Create Midnight Network applications with zero configuration",
   "main": "dist/index.js",
   "bin": {

templates/hello-world/package.json.template

@@ -13,6 +13,7 @@
     "build": "tsc",
     "deploy": "node dist/deploy.js",
     "cli": "node dist/cli.js",
+    "check-balance": "npm run build && node dist/check-balance.js",
     "reset": "rm -rf contracts/managed deployment.json dist && npm run compile",
     "validate": "tsc --noEmit && npm run compile",
     "clean": "rm -rf dist contracts/managed deployment.json",

templates/hello-world/src/check-balance.ts.template

@@ -0,0 +1,87 @@
+import "dotenv/config";
+import { WalletBuilder } from "@midnight-ntwrk/wallet";
+import {
+  NetworkId,
+  setNetworkId,
+  getZswapNetworkId,
+  getLedgerNetworkId,
+} from "@midnight-ntwrk/midnight-js-network-id";
+import { nativeToken } from "@midnight-ntwrk/ledger";
+import { WebSocket } from "ws";
+import * as Rx from "rxjs";
+import { MidnightProviders } from "./providers/midnight-providers.js";
+import { EnvironmentManager } from "./utils/environment.js";
+
+// Fix WebSocket for Node.js environment
+// @ts-ignore
+globalThis.WebSocket = WebSocket;
+
+// Configure for Midnight Testnet
+setNetworkId(NetworkId.TestNet);
+
+async function checkBalance() {
+  try {
+    console.log("\n🌙 Checking Wallet Balance\n");
+
+    const seed = process.env.WALLET_SEED;
+    if (!seed) {
+      throw new Error("WALLET_SEED not found in .env file");
+    }
+
+    console.log("Building wallet...");
+
+    // Get network configuration
+    const networkConfig = EnvironmentManager.getNetworkConfig();
+
+    // Create providers
+    const providers = MidnightProviders.create({
+      indexerUrl: networkConfig.indexerUrl,
+      indexerWsUrl: networkConfig.indexerWsUrl,
+      prooServerUrl: networkConfig.proofServerUrl,
+      walletSeed: seed,
+      zkConfigPath: networkConfig.zkConfigPath,
+    });
+
+    // Build wallet
+    const wallet = await WalletBuilder.buildFromSeed(
+      getLedgerNetworkId(),
+      seed,
+      providers.privateStateProvider,
+      providers.zkConfigProvider,
+      providers.publicDataProvider,
+      { coinPublicKey: providers.coinPublicKey }
+    );
+
+    wallet.start();
+
+    const state = await Rx.firstValueFrom(wallet.state());
+
+    console.log(`Wallet Address: ${state.address}`);
+
+    const balance = state.balances[nativeToken()] || 0n;
+
+    if (balance === 0n) {
+      console.log(`\n💰 Balance: 0 DUST\n`);
+      console.log("❌ No funds detected.");
+      console.log("\n📝 To get funds:");
+      console.log("   1. Visit: https://midnight.network/test-faucet");
+      console.log("   2. Paste your wallet address");
+      console.log("   3. Wait a few minutes for the transaction to process");
+      console.log("   4. Run 'npm run check-balance' again to verify");
+      console.log("\n💡 Note: Faucet transactions can take 2-5 minutes to process.");
+    } else {
+      console.log(`\n💰 Balance: ${balance} DUST\n`);
+      console.log("✅ Wallet is funded!");
+      console.log("\n🚀 You can now deploy your contract:");
+      console.log("   npm run deploy");
+    }
+
+    wallet.close();
+    process.exit(0);
+  } catch (error) {
+    console.error("Error checking balance:", error);
+    process.exit(1);
+  }
+}
+
+checkBalance();

templates/hello-world/src/deploy.ts.template

@@ -84,10 +84,18 @@ async function main() {
     let balance = state.balances[nativeToken()] || 0n;
 
     if (balance === 0n) {
-      console.log(`Your wallet balance is: 0`);
-      console.log(
-        "Visit: https://midnight.network/test-faucet to get some funds."
-      );
+      console.log(`Your wallet balance is: 0 DUST`);
+      console.log("\n❌ Wallet needs funding to deploy contracts.\n");
+      console.log("📝 To get test tokens:");
+      console.log("   1. Visit: https://midnight.network/test-faucet");
+      console.log("   2. Paste your wallet address (shown above)");
+      console.log("   3. Request tokens from the faucet\n");
+      console.log("⏱️  Faucet transactions can take 2-5 minutes to process.\n");
+      console.log("💡 Options while waiting:");
+      console.log("   • Let this script wait (it will auto-detect when funds arrive)");
+      console.log("   • OR press Ctrl+C to stop, then check balance with:");
+      console.log("     npm run check-balance");
+      console.log("   • Once funded, run: npm run deploy\n");
       console.log(`Waiting to receive tokens...`);
       balance = await waitForFunds(wallet);
     }