create-mn-app 0.3.28 → 0.4.1

package/templates/hello-world/package.json.template

@@ -8,40 +8,42 @@
   "scripts": {
     "compile": "compact compile contracts/hello-world.compact contracts/managed/hello-world",
     "build": "npx tsc --noEmit || true",
-    "setup": "docker compose up -d && npm run compile && npm run deploy",
+    "setup": "npx tsx src/setup.ts",
     "deploy": "npx tsx src/deploy.ts",
     "cli": "npx tsx src/cli.ts",
     "check-balance": "npx tsx src/check-balance.ts",
+    "network": "npx tsx src/network.ts",
     "proof-server:start": "docker compose up -d",
     "proof-server:stop": "docker compose down",
-    "clean": "rm -rf contracts/managed deployment.json",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "clean": "rm -rf contracts/managed .midnight-state.json .midnight-wallet-state",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:e2e": "tsx scripts/e2e-check.ts"
   },
   "dependencies": {
     "@midnight-ntwrk/compact-js": "2.5.0",
-    "rxjs": "^7.8.1",
-    "@midnight-ntwrk/compact-runtime": "0.15.0",
+    "rxjs": "^7.8.2",
+    "@midnight-ntwrk/compact-runtime": "0.16.0",
     "@midnight-ntwrk/ledger-v8": "8.0.3",
-    "@midnight-ntwrk/midnight-js-contracts": "4.0.2",
-    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "4.0.2",
-    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.0.2",
-    "@midnight-ntwrk/midnight-js-level-private-state-provider": "4.0.2",
-    "@midnight-ntwrk/midnight-js-network-id": "4.0.2",
-    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "4.0.2",
-    "@midnight-ntwrk/midnight-js-types": "4.0.2",
-    "@midnight-ntwrk/midnight-js-utils": "4.0.2",
+    "@midnight-ntwrk/midnight-js-contracts": "4.0.4",
+    "@midnight-ntwrk/midnight-js-http-client-proof-provider": "4.0.4",
+    "@midnight-ntwrk/midnight-js-indexer-public-data-provider": "4.0.4",
+    "@midnight-ntwrk/midnight-js-level-private-state-provider": "4.0.4",
+    "@midnight-ntwrk/midnight-js-network-id": "4.0.4",
+    "@midnight-ntwrk/midnight-js-node-zk-config-provider": "4.0.4",
+    "@midnight-ntwrk/midnight-js-types": "4.0.4",
+    "@midnight-ntwrk/midnight-js-utils": "4.0.4",
     "@midnight-ntwrk/wallet-sdk-dust-wallet": "3.0.0",
     "@midnight-ntwrk/wallet-sdk-facade": "3.0.0",
     "@midnight-ntwrk/wallet-sdk-hd": "3.0.1",
     "@midnight-ntwrk/wallet-sdk-shielded": "2.1.0",
     "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "2.1.0",
-    "ws": "^8.19.0"
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.18.1",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=22.0.0"

package/templates/hello-world/scripts/e2e-check.ts.template

@@ -0,0 +1,124 @@
+/**
+ * End-to-end smoke check for {{projectName}}.
+ *
+ * Reconnects to the deployed contract, reads its ledger state, and exits 0
+ * on success. Used by `npm run test:e2e` and by the project's CI workflows.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { WebSocket } from 'ws';
+
+import { findDeployedContract } from '@midnight-ntwrk/midnight-js-contracts';
+import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client-proof-provider';
+import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
+import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
+import { NodeZkConfigProvider } from '@midnight-ntwrk/midnight-js-node-zk-config-provider';
+import { resolveNetwork, getOrCreateSeed, getDeployment } from '../src/network';
+import { createWallet, persistWalletState } from '../src/wallet';
+import { CompiledContract } from '@midnight-ntwrk/compact-js';
+
+// @ts-expect-error wallet sync requires WebSocket
+globalThis.WebSocket = WebSocket;
+
+// ─── Network configuration ─────────────────────────────────────────────────────
+
+const { network, config: networkConfig } = resolveNetwork();
+const SEED = getOrCreateSeed(network);
+
+function fail(msg: string): never {
+  console.error(`❌ e2e-check failed: ${msg}`);
+  process.exit(1);
+}
+
+function isHexAddress(s: unknown): s is string {
+  return typeof s === 'string' && /^[0-9a-fA-F]+$/.test(s) && s.length >= 32;
+}
+
+async function main() {
+  // 1. Deployment sanity
+  const deployment = getDeployment(network);
+  if (!deployment) {
+    console.error(`No deploy on file for network ${network}.`);
+    process.exit(1);
+  }
+  if (!isHexAddress(deployment.address)) {
+    fail(`Deployment address missing or invalid: ${JSON.stringify(deployment, null, 2)}`);
+  }
+
+  // 2. Build wallet and providers
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const zkConfigPath = path.resolve(__dirname, '..', 'contracts', 'managed', 'hello-world');
+  const contractPath = path.join(zkConfigPath, 'contract', 'index.js');
+  if (!fs.existsSync(contractPath)) fail('Compiled contract missing — run `npm run compile`.');
+  const HelloWorld = await import(pathToFileURL(contractPath).href);
+  const compiledContract = CompiledContract.make('hello-world', HelloWorld.Contract).pipe(
+    CompiledContract.withVacantWitnesses,
+    CompiledContract.withCompiledFileAssets(zkConfigPath),
+  );
+
+  const walletCtx = await createWallet({ network, networkConfig, seed: SEED });
+  const state = await walletCtx.wallet.waitForSyncedState();
+  // Persist the sync state — saves time on the next e2e-check invocation in CI
+  // when run against the same persistent wallet directory.
+  await persistWalletState(network, walletCtx);
+
+  const zkConfigProvider = new NodeZkConfigProvider(zkConfigPath);
+  const walletProvider = {
+    getCoinPublicKey: () => state.shielded.coinPublicKey.toHexString(),
+    getEncryptionPublicKey: () => state.shielded.encryptionPublicKey.toHexString(),
+    async balanceTx() {
+      throw new Error('e2e-check is read-only and should not balance transactions');
+    },
+    submitTx() {
+      throw new Error('e2e-check is read-only and should not submit transactions');
+    },
+  } as any;
+
+  const providers = {
+    privateStateProvider: levelPrivateStateProvider({
+      privateStateStoreName: 'hello-world-state',
+      accountId: walletCtx.unshieldedKeystore.getBech32Address().toString(),
+      // SDK requires ≥16 chars. e2e-check is read-only so we don't expose
+      // the env-var override here — match the deploy script's local-devnet default.
+      privateStoragePasswordProvider: () => 'Local-Devnet-Development-Placeholder-1',
+    }),
+    publicDataProvider: indexerPublicDataProvider(networkConfig.indexer, networkConfig.indexerWS),
+    zkConfigProvider,
+    proofProvider: httpClientProofProvider(networkConfig.proofServer, zkConfigProvider),
+    walletProvider,
+    midnightProvider: walletProvider,
+  };
+
+  // 3. Reconnect to the deployed contract — proves callTx interface is wired
+  try {
+    await findDeployedContract(providers, {
+      contractAddress: deployment.address,
+      compiledContract: compiledContract as any,
+    });
+  } catch (err: any) {
+    await walletCtx.wallet.stop();
+    fail(`findDeployedContract threw: ${err?.message ?? err}`);
+  }
+
+  // 4. Read the on-chain contract state via the public data provider — proves
+  // the contract is indexed and queryable on the chain itself, not just that
+  // we know how to construct the local handle.
+  const onChainState = await providers.publicDataProvider.queryContractState(deployment.address);
+  if (!onChainState) {
+    await walletCtx.wallet.stop();
+    fail(`queryContractState returned null for ${deployment.address}`);
+  }
+
+  console.log(`✅ e2e-check passed`);
+  console.log(`   contractAddress: ${deployment.address}`);
+  console.log(`   network:         ${network}`);
+
+  await walletCtx.wallet.stop();
+  process.exit(0);
+}
+
+main().catch(async (err) => {
+  console.error(err);
+  process.exit(1);
+});

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

@@ -1,75 +1,21 @@
 /**
- * Check wallet balance on Midnight Preprod network
+ * Check wallet balance on the local Midnight devnet
  */
-import * as fs from 'node:fs';
 import { WebSocket } from 'ws';
-import * as Rx from 'rxjs';
-import { Buffer } from 'buffer';
 
 // Midnight SDK imports
-import { setNetworkId, getNetworkId } from '@midnight-ntwrk/midnight-js-network-id';
-import * as ledger from '@midnight-ntwrk/ledger-v8';
 import { unshieldedToken } from '@midnight-ntwrk/ledger-v8';
-import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
-import { DustWallet } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
-import { HDWallet, Roles } from '@midnight-ntwrk/wallet-sdk-hd';
-import { ShieldedWallet } from '@midnight-ntwrk/wallet-sdk-shielded';
-import { createKeystore, InMemoryTransactionHistoryStorage, PublicKey, UnshieldedWallet } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { resolveNetwork, getOrCreateSeed } from './network';
+import { createWallet, persistWalletState } from './wallet';
 
 // Enable WebSocket for GraphQL subscriptions
 // @ts-expect-error Required for wallet sync
 globalThis.WebSocket = WebSocket;
 
-// Set network to preprod
-setNetworkId('preprod');
+// ─── Network configuration ─────────────────────────────────────────────────────
 
-// Preprod network configuration
-const CONFIG = {
-  indexer: 'https://indexer.preprod.midnight.network/api/v3/graphql',
-  indexerWS: 'wss://indexer.preprod.midnight.network/api/v3/graphql/ws',
-  node: 'https://rpc.preprod.midnight.network',
-  proofServer: 'http://127.0.0.1:6300',
-  faucetUrl: 'https://faucet.preprod.midnight.network/',
-};
-
-// ─── Wallet Functions ──────────────────────────────────────────────────────────
-
-function deriveKeys(seed: string) {
-  const hdWallet = HDWallet.fromSeed(Buffer.from(seed, 'hex'));
-  if (hdWallet.type !== 'seedOk') throw new Error('Invalid seed');
-  const result = hdWallet.hdWallet.selectAccount(0).selectRoles([Roles.Zswap, Roles.NightExternal, Roles.Dust]).deriveKeysAt(0);
-  if (result.type !== 'keysDerived') throw new Error('Key derivation failed');
-  hdWallet.hdWallet.clear();
-  return result.keys;
-}
-
-async function createWallet(seed: string) {
-  const keys = deriveKeys(seed);
-  const networkId = getNetworkId();
-  const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(keys[Roles.Zswap]);
-  const dustSecretKey = ledger.DustSecretKey.fromSeed(keys[Roles.Dust]);
-  const unshieldedKeystore = createKeystore(keys[Roles.NightExternal], networkId);
-
-  const walletConfig = {
-    networkId,
-    indexerClientConnection: { indexerHttpUrl: CONFIG.indexer, indexerWsUrl: CONFIG.indexerWS },
-    provingServerUrl: new URL(CONFIG.proofServer),
-    relayURL: new URL(CONFIG.node.replace(/^http/, 'ws')),
-    txHistoryStorage: new InMemoryTransactionHistoryStorage(),
-    costParameters: { additionalFeeOverhead: 300_000_000_000_000n, feeBlocksMargin: 5 },
-  };
-
-  const wallet = await WalletFacade.init({
-    configuration: walletConfig,
-    shielded: async (config) => ShieldedWallet(config).startWithSecretKeys(shieldedSecretKeys),
-    unshielded: async (config) => UnshieldedWallet(config).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
-    dust: async (config) => DustWallet(config).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
-  });
-
-  await wallet.start(shieldedSecretKeys, dustSecretKey);
-
-  return { wallet, unshieldedKeystore };
-}
+const { network, config: networkConfig } = resolveNetwork();
+const SEED = getOrCreateSeed(network);
 
 // ─── Main ──────────────────────────────────────────────────────────────────────
 
@@ -78,23 +24,13 @@ async function main() {
   console.log('║                   Wallet Balance Checker                      ║');
   console.log('╚══════════════════════════════════════════════════════════════╝\n');
 
-  // Check for deployment.json to get seed
-  if (!fs.existsSync('deployment.json')) {
-    console.error('❌ No deployment.json found! Run: npm run deploy\n');
-    process.exit(1);
-  }
-
-  const deployment = JSON.parse(fs.readFileSync('deployment.json', 'utf-8'));
-
-  if (!fs.existsSync('.midnight-seed')) {
-    console.error('❌ No .midnight-seed file found! Run: npm run deploy\n');
-    process.exit(1);
-  }
-  const seed = fs.readFileSync('.midnight-seed', 'utf-8').trim();
-
   try {
     console.log('  Building wallet...');
-    const { wallet, unshieldedKeystore } = await createWallet(seed);
+    const walletCtx = await createWallet({ network, networkConfig, seed: SEED });
+    const restoredCount = Object.values(walletCtx.restored).filter(Boolean).length;
+    if (restoredCount > 0) {
+      console.log(`  Restored ${restoredCount}/3 child wallets from .midnight-wallet-state — sync will resume from saved point.`);
+    }
 
     console.log('  Syncing with network...');
     console.log('  ℹ  This may take several minutes depending on network size.');
@@ -104,33 +40,39 @@ async function main() {
       const elapsed = Math.round((Date.now() - syncStart) / 1000);
       process.stdout.write(`\r  ⏳ Still syncing... (${elapsed}s elapsed)   `);
     }, 5000);
-    const state = await wallet.waitForSyncedState();
+    const state = await walletCtx.wallet.waitForSyncedState();
     clearInterval(syncInterval);
     process.stdout.write('\r  ✓ Synced with network.                                      \n');
 
-    const address = unshieldedKeystore.getBech32Address();
+    const address = walletCtx.unshieldedKeystore.getBech32Address();
     const tNightBalance = state.unshielded.balances[unshieldedToken().raw] ?? 0n;
     const dustBalance = state.dust.balance(new Date());
 
     console.log('\n─── Wallet Details ─────────────────────────────────────────────\n');
     console.log(`  Address: ${address}`);
-    console.log(`  Network: preprod\n`);
+    console.log(`  Network: ${networkConfig.networkId}\n`);
 
     console.log('─── Balances ───────────────────────────────────────────────────\n');
     console.log(`  tNight: ${tNightBalance.toLocaleString()}`);
     console.log(`  DUST:   ${dustBalance.toLocaleString()}\n`);
 
     if (tNightBalance === 0n) {
-      console.log('─── Need Funds? ────────────────────────────────────────────────\n');
-      console.log(`  1. Visit: ${CONFIG.faucetUrl}`);
-      console.log(`  2. Paste your address: ${address}`);
-      console.log(`  3. Request tokens and wait ~2-5 minutes`);
-      console.log(`  4. Run this command again to check balance\n`);
+      if (network === 'undeployed') {
+        console.log('  ⚠ Wallet has no tNight. Make sure the local devnet is running');
+        console.log('     (npm run setup) — the genesis seed is pre-funded by the dev preset.\n');
+      } else if (networkConfig.faucet) {
+        console.log(`  ⚠ Wallet has no tNight. Fund it from the faucet:`);
+        console.log(`     ${networkConfig.faucet}`);
+        console.log(`     Wallet address: ${address}\n`);
+      } else {
+        console.log('  ⚠ Wallet has no tNight.\n');
+      }
     } else {
       console.log('  ✅ Wallet is funded and ready!\n');
     }
 
-    await wallet.stop();
+    await persistWalletState(network, walletCtx);
+    await walletCtx.wallet.stop();
   } catch (error) {
     console.error('\n❌ Error:', error instanceof Error ? error.message : error);
     process.exit(1);

package/templates/hello-world/src/cli.ts.template

@@ -7,7 +7,6 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { WebSocket } from 'ws';
-import * as Rx from 'rxjs';
 import { Buffer } from 'buffer';
 
 // Midnight SDK imports
@@ -16,30 +15,16 @@ import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client
 import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
 import { levelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
 import { NodeZkConfigProvider } from '@midnight-ntwrk/midnight-js-node-zk-config-provider';
-import { setNetworkId, getNetworkId } from '@midnight-ntwrk/midnight-js-network-id';
-import * as ledger from '@midnight-ntwrk/ledger-v8';
-import { unshieldedToken } from '@midnight-ntwrk/ledger-v8';
-import { WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
-import { DustWallet } from '@midnight-ntwrk/wallet-sdk-dust-wallet';
-import { HDWallet, Roles } from '@midnight-ntwrk/wallet-sdk-hd';
-import { ShieldedWallet } from '@midnight-ntwrk/wallet-sdk-shielded';
-import { createKeystore, InMemoryTransactionHistoryStorage, PublicKey, UnshieldedWallet } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { resolveNetwork, getOrCreateSeed, getDeployment } from './network';
+import { createWallet, persistWalletState, unshieldedToken, type WalletContext } from './wallet';
 import { CompiledContract } from '@midnight-ntwrk/compact-js';
 
 // Enable WebSocket for GraphQL subscriptions
 // @ts-expect-error Required for wallet sync
 globalThis.WebSocket = WebSocket;
 
-// Set network to preprod
-setNetworkId('preprod');
-
-// Preprod network configuration
-const CONFIG = {
-  indexer: 'https://indexer.preprod.midnight.network/api/v3/graphql',
-  indexerWS: 'wss://indexer.preprod.midnight.network/api/v3/graphql/ws',
-  node: 'https://rpc.preprod.midnight.network',
-  proofServer: 'http://127.0.0.1:6300',
-};
+const { network, config: networkConfig } = resolveNetwork();
+const SEED = getOrCreateSeed(network);
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const zkConfigPath = path.resolve(__dirname, '..', 'contracts', 'managed', 'hello-world');
@@ -60,47 +45,13 @@ const compiledContract = CompiledContract.make('hello-world', HelloWorld.Contrac
   CompiledContract.withCompiledFileAssets(zkConfigPath),
 );
 
-// ─── Wallet Functions ──────────────────────────────────────────────────────────
-
-function deriveKeys(seed: string) {
-  const hdWallet = HDWallet.fromSeed(Buffer.from(seed, 'hex'));
-  if (hdWallet.type !== 'seedOk') throw new Error('Invalid seed');
-  const result = hdWallet.hdWallet.selectAccount(0).selectRoles([Roles.Zswap, Roles.NightExternal, Roles.Dust]).deriveKeysAt(0);
-  if (result.type !== 'keysDerived') throw new Error('Key derivation failed');
-  hdWallet.hdWallet.clear();
-  return result.keys;
-}
-
-async function createWallet(seed: string) {
-  const keys = deriveKeys(seed);
-  const networkId = getNetworkId();
-  const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(keys[Roles.Zswap]);
-  const dustSecretKey = ledger.DustSecretKey.fromSeed(keys[Roles.Dust]);
-  const unshieldedKeystore = createKeystore(keys[Roles.NightExternal], networkId);
-
-  const walletConfig = {
-    networkId,
-    indexerClientConnection: { indexerHttpUrl: CONFIG.indexer, indexerWsUrl: CONFIG.indexerWS },
-    provingServerUrl: new URL(CONFIG.proofServer),
-    relayURL: new URL(CONFIG.node.replace(/^http/, 'ws')),
-    txHistoryStorage: new InMemoryTransactionHistoryStorage(),
-    costParameters: { additionalFeeOverhead: 300_000_000_000_000n, feeBlocksMargin: 5 },
-  };
-
-  const wallet = await WalletFacade.init({
-    configuration: walletConfig,
-    shielded: async (config) => ShieldedWallet(config).startWithSecretKeys(shieldedSecretKeys),
-    unshielded: async (config) => UnshieldedWallet(config).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
-    dust: async (config) => DustWallet(config).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
-  });
+// ─── Providers ─────────────────────────────────────────────────────────────────
 
-  await wallet.start(shieldedSecretKeys, dustSecretKey);
-
-  return { wallet, shieldedSecretKeys, dustSecretKey, unshieldedKeystore };
-}
-
-async function createProviders(walletCtx: ReturnType<typeof createWallet> extends Promise<infer T> ? T : never) {
-  const privateStatePassword = process.env.PRIVATE_STATE_PASSWORD?.trim() || 'development';
+async function createProviders(walletCtx: WalletContext) {
+  // The SDK requires the private-state password to be at least 16 characters.
+  // The default below is a placeholder for local devnet only — set a strong
+  // password via PRIVATE_STATE_PASSWORD when you move to a non-local target.
+  const privateStatePassword = process.env.PRIVATE_STATE_PASSWORD?.trim() || 'Local-Devnet-Development-Placeholder-1';
 
   const state = await walletCtx.wallet.waitForSyncedState();
 
@@ -130,9 +81,9 @@ async function createProviders(walletCtx: ReturnType<typeof createWallet> extend
       accountId,
       privateStoragePasswordProvider: () => privateStatePassword,
     }),
-    publicDataProvider: indexerPublicDataProvider(CONFIG.indexer, CONFIG.indexerWS),
+    publicDataProvider: indexerPublicDataProvider(networkConfig.indexer, networkConfig.indexerWS),
     zkConfigProvider,
-    proofProvider: httpClientProofProvider(CONFIG.proofServer, zkConfigProvider),
+    proofProvider: httpClientProofProvider(networkConfig.proofServer, zkConfigProvider),
     walletProvider,
     midnightProvider: walletProvider,
   };
@@ -148,25 +99,23 @@ async function main() {
   const rl = createInterface({ input: stdin, output: stdout });
 
   // Check for deployment
-  if (!fs.existsSync('deployment.json')) {
-    console.error('❌ No deployment.json found! Run: npm run deploy\n');
+  const deployment = getDeployment(network);
+  if (!deployment) {
+    console.error(`No deploy on file for network ${network}. Run \`npm run setup -- --network ${network}\` first.`);
     process.exit(1);
   }
-
-  const deployment = JSON.parse(fs.readFileSync('deployment.json', 'utf-8'));
-  console.log(`  Contract: ${deployment.contractAddress}`);
-  console.log(`  Network: ${deployment.network || 'preprod'}\n`);
+  console.log(`  Contract: ${deployment.address}`);
+  console.log(`  Network: ${network}\n`);
 
   try {
-    // Create wallet from saved seed
-    if (!fs.existsSync('.midnight-seed')) {
-      console.error('❌ No .midnight-seed file found! Run: npm run deploy\n');
-      process.exit(1);
-    }
-    const seed = fs.readFileSync('.midnight-seed', 'utf-8').trim();
+    const seed = SEED;
 
     console.log('  Connecting to wallet...');
-    const walletCtx = await createWallet(seed);
+    const walletCtx = await createWallet({ network, networkConfig, seed });
+    const restoredCount = Object.values(walletCtx.restored).filter(Boolean).length;
+    if (restoredCount > 0) {
+      console.log(`  Restored ${restoredCount}/3 child wallets from .midnight-wallet-state — sync will resume from saved point.`);
+    }
 
     console.log('  Syncing with network...');
     console.log('  ℹ  This may take several minutes depending on network size.');
@@ -179,16 +128,30 @@ async function main() {
     const state = await walletCtx.wallet.waitForSyncedState();
     clearInterval(syncInterval);
     process.stdout.write('\r  ✓ Synced with network.                                      \n');
+
+    // Persist sync state so the next run doesn't have to redo this work.
+    await persistWalletState(network, walletCtx);
     const balance = state.unshielded.balances[unshieldedToken().raw] ?? 0n;
     console.log(`  Balance: ${balance.toLocaleString()} tNight\n`);
 
+    // Surface a faucet hint when a public-network wallet has 0 tNIGHT.
+    // Reads (option 2) work without funds, but writes (option 1) need DUST
+    // generated from registered NIGHT — without this hint the next failure
+    // mode is a confusing "Insufficient Funds" deep inside the tx builder.
+    if (balance === 0n && network !== 'undeployed' && networkConfig.faucet) {
+      const address = walletCtx.unshieldedKeystore.getBech32Address();
+      console.log('  ⚠ Wallet has no tNight. Fund it from the faucet to send transactions:');
+      console.log(`     ${networkConfig.faucet}`);
+      console.log(`     Wallet address: ${address}\n`);
+    }
+
     // Setup providers and connect to contract
     console.log('  Connecting to contract...');
     const providers = await createProviders(walletCtx);
 
     const deployed: any = await findDeployedContract(providers, {
       compiledContract: compiledContract as any,
-      contractAddress: deployment.contractAddress,
+      contractAddress: deployment.address,
     });
 
     console.log('  ✅ Connected!\n');
@@ -222,7 +185,7 @@ async function main() {
         case '2': {
           console.log('\n  Reading message from blockchain...');
           try {
-            const contractState = await providers.publicDataProvider.queryContractState(deployment.contractAddress);
+            const contractState = await providers.publicDataProvider.queryContractState(deployment.address);
             if (contractState) {
               const ledgerState = HelloWorld.ledger(contractState.data);
               const message = Buffer.from(ledgerState.message).toString();
@@ -256,6 +219,7 @@ async function main() {
       }
     }
 
+    await persistWalletState(network, walletCtx);
     await walletCtx.wallet.stop();
   } catch (error) {
     console.error('\n❌ Error:', error instanceof Error ? error.message : error);