create-mn-app 0.4.0 → 0.4.2

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

@@ -8,21 +8,14 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { WebSocket } from 'ws';
-import { Buffer } from 'buffer';
 
 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 { setNetworkId, getNetworkId } from '@midnight-ntwrk/midnight-js-network-id';
 import { resolveNetwork, getOrCreateSeed, getDeployment } from '../src/network';
-import * as ledger 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, NoOpTransactionHistoryStorage, PublicKey, UnshieldedWallet } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { createWallet, persistWalletState } from '../src/wallet';
 import { CompiledContract } from '@midnight-ntwrk/compact-js';
 
 // @ts-expect-error wallet sync requires WebSocket
@@ -31,7 +24,6 @@ globalThis.WebSocket = WebSocket;
 // ─── Network configuration ─────────────────────────────────────────────────────
 
 const { network, config: networkConfig } = resolveNetwork();
-setNetworkId(networkConfig.networkId);
 const SEED = getOrCreateSeed(network);
 
 function fail(msg: string): never {
@@ -54,7 +46,7 @@ async function main() {
     fail(`Deployment address missing or invalid: ${JSON.stringify(deployment, null, 2)}`);
   }
 
-  // 2. Build wallet (genesis seed) and providers
+  // 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');
@@ -65,37 +57,11 @@ async function main() {
     CompiledContract.withCompiledFileAssets(zkConfigPath),
   );
 
-  const hd = HDWallet.fromSeed(Buffer.from(SEED, 'hex'));
-  if (hd.type !== 'seedOk') fail('Bad seed.');
-  const derived = hd.hdWallet
-    .selectAccount(0)
-    .selectRoles([Roles.Zswap, Roles.NightExternal, Roles.Dust])
-    .deriveKeysAt(0);
-  if (derived.type !== 'keysDerived') fail('Key derivation failed.');
-  hd.hdWallet.clear();
-
-  const networkId = getNetworkId();
-  const shieldedSecretKeys = ledger.ZswapSecretKeys.fromSeed(derived.keys[Roles.Zswap]);
-  const dustSecretKey = ledger.DustSecretKey.fromSeed(derived.keys[Roles.Dust]);
-  const unshieldedKeystore = createKeystore(derived.keys[Roles.NightExternal], networkId);
-
-  const wallet = await WalletFacade.init({
-    configuration: {
-      networkId,
-      indexerClientConnection: { indexerHttpUrl: networkConfig.indexer, indexerWsUrl: networkConfig.indexerWS },
-      provingServerUrl: new URL(networkConfig.proofServer),
-      relayURL: new URL(networkConfig.node.replace(/^http/, 'ws')),
-      txHistoryStorage: new NoOpTransactionHistoryStorage(),
-      costParameters: { additionalFeeOverhead: 300_000_000_000_000n, feeBlocksMargin: 5 },
-    },
-    shielded: async (c) => ShieldedWallet(c).startWithSecretKeys(shieldedSecretKeys),
-    unshielded: async (c) =>
-      UnshieldedWallet(c).startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore)),
-    dust: async (c) =>
-      DustWallet(c).startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust),
-  });
-  await wallet.start(shieldedSecretKeys, dustSecretKey);
-  const state = await wallet.waitForSyncedState();
+  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 = {
@@ -112,7 +78,7 @@ async function main() {
   const providers = {
     privateStateProvider: levelPrivateStateProvider({
       privateStateStoreName: 'hello-world-state',
-      accountId: unshieldedKeystore.getBech32Address().toString(),
+      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',
@@ -131,7 +97,7 @@ async function main() {
       compiledContract: compiledContract as any,
     });
   } catch (err: any) {
-    await wallet.stop();
+    await walletCtx.wallet.stop();
     fail(`findDeployedContract threw: ${err?.message ?? err}`);
   }
 
@@ -140,7 +106,7 @@ async function main() {
   // we know how to construct the local handle.
   const onChainState = await providers.publicDataProvider.queryContractState(deployment.address);
   if (!onChainState) {
-    await wallet.stop();
+    await walletCtx.wallet.stop();
     fail(`queryContractState returned null for ${deployment.address}`);
   }
 
@@ -148,7 +114,7 @@ async function main() {
   console.log(`   contractAddress: ${deployment.address}`);
   console.log(`   network:         ${network}`);
 
-  await wallet.stop();
+  await walletCtx.wallet.stop();
   process.exit(0);
 }
 

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

@@ -2,19 +2,11 @@
  * Check wallet balance on the local Midnight devnet
  */
 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, NoOpTransactionHistoryStorage, 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
@@ -23,48 +15,8 @@ globalThis.WebSocket = WebSocket;
 // ─── Network configuration ─────────────────────────────────────────────────────
 
 const { network, config: networkConfig } = resolveNetwork();
-setNetworkId(networkConfig.networkId);
 const SEED = getOrCreateSeed(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: networkConfig.indexer, indexerWsUrl: networkConfig.indexerWS },
-    provingServerUrl: new URL(networkConfig.proofServer),
-    relayURL: new URL(networkConfig.node.replace(/^http/, 'ws')),
-    txHistoryStorage: new NoOpTransactionHistoryStorage(),
-    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 };
-}
-
 // ─── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -72,11 +24,13 @@ async function main() {
   console.log('║                   Wallet Balance Checker                      ║');
   console.log('╚══════════════════════════════════════════════════════════════╝\n');
 
-  const seed = SEED;
-
   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.');
@@ -86,11 +40,11 @@ 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());
 
@@ -117,7 +71,8 @@ async function main() {
       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,15 +15,8 @@ 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 { resolveNetwork, getOrCreateSeed, getDeployment } from './network';
-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, NoOpTransactionHistoryStorage, PublicKey, UnshieldedWallet } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
+import { createWallet, persistWalletState, unshieldedToken, type WalletContext } from './wallet';
 import { CompiledContract } from '@midnight-ntwrk/compact-js';
 
 // Enable WebSocket for GraphQL subscriptions
@@ -32,7 +24,6 @@ import { CompiledContract } from '@midnight-ntwrk/compact-js';
 globalThis.WebSocket = WebSocket;
 
 const { network, config: networkConfig } = resolveNetwork();
-setNetworkId(networkConfig.networkId);
 const SEED = getOrCreateSeed(network);
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -54,46 +45,9 @@ const compiledContract = CompiledContract.make('hello-world', HelloWorld.Contrac
   CompiledContract.withCompiledFileAssets(zkConfigPath),
 );
 
-// ─── Wallet Functions ──────────────────────────────────────────────────────────
+// ─── Providers ─────────────────────────────────────────────────────────────────
 
-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: networkConfig.indexer, indexerWsUrl: networkConfig.indexerWS },
-    provingServerUrl: new URL(networkConfig.proofServer),
-    relayURL: new URL(networkConfig.node.replace(/^http/, 'ws')),
-    txHistoryStorage: new NoOpTransactionHistoryStorage(),
-    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, shieldedSecretKeys, dustSecretKey, unshieldedKeystore };
-}
-
-async function createProviders(walletCtx: ReturnType<typeof createWallet> extends Promise<infer T> ? T : never) {
+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.
@@ -157,7 +111,11 @@ async function main() {
     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.');
@@ -170,6 +128,9 @@ 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`);
 
@@ -258,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);

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

@@ -7,10 +7,10 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { resolveNetwork, getOrCreateSeed, recordDeployment } from './network';
+import { createWallet, persistWalletState, unshieldedToken, type WalletContext } from './wallet';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { WebSocket } from 'ws';
 import * as Rx from 'rxjs';
-import { Buffer } from 'buffer';
 
 // Midnight SDK imports
 import { deployContract } from '@midnight-ntwrk/midnight-js-contracts';
@@ -18,14 +18,6 @@ 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, NoOpTransactionHistoryStorage, PublicKey, UnshieldedWallet } from '@midnight-ntwrk/wallet-sdk-unshielded-wallet';
 import { CompiledContract } from '@midnight-ntwrk/compact-js';
 
 // @ts-expect-error Required for wallet sync
@@ -37,7 +29,6 @@ globalThis.WebSocket = WebSocket;
 // 'undeployed' (local devnet). Switch networks with: npm run network <name>
 
 const { network, config: networkConfig } = resolveNetwork();
-setNetworkId(networkConfig.networkId);
 const SEED = getOrCreateSeed(network);
 
 // ─── Proof server readiness ────────────────────────────────────────────────────
@@ -86,51 +77,9 @@ const compiledContract = CompiledContract.make('hello-world', HelloWorld.Contrac
   CompiledContract.withCompiledFileAssets(zkConfigPath),
 );
 
-// ─── Wallet helpers ────────────────────────────────────────────────────────────
-
-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: networkConfig.indexer, indexerWsUrl: networkConfig.indexerWS },
-    provingServerUrl: new URL(networkConfig.proofServer),
-    relayURL: new URL(networkConfig.node.replace(/^http/, 'ws')),
-    txHistoryStorage: new NoOpTransactionHistoryStorage(),
-    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);
+// ─── Providers ─────────────────────────────────────────────────────────────────
 
-  return { wallet, shieldedSecretKeys, dustSecretKey, unshieldedKeystore };
-}
-
-async function createProviders(walletCtx: ReturnType<typeof createWallet> extends Promise<infer T> ? T : never) {
+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.
@@ -182,7 +131,11 @@ async function main() {
 
   console.log('─── Wallet setup ───────────────────────────────────────────────\n');
   console.log('  Creating 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.');
@@ -196,6 +149,9 @@ async function main() {
   clearInterval(syncInterval);
   process.stdout.write('\r  ✓ Synced with network.                                      \n');
 
+  // Persist sync state now so a later deploy failure doesn't waste the sync work.
+  await persistWalletState(network, walletCtx);
+
   const address = walletCtx.unshieldedKeystore.getBech32Address();
   let balance = state.unshielded.balances[unshieldedToken().raw] ?? 0n;
   console.log(`\n  Wallet Address: ${address}`);
@@ -391,6 +347,7 @@ async function main() {
   recordDeployment(network, contractAddress, address.toString());
   console.log('  Saved to .midnight-state.json\n');
 
+  await persistWalletState(network, walletCtx);
   await walletCtx.wallet.stop();
   console.log('─── Deployment complete ────────────────────────────────────────\n');
   console.log('  Next: npm run cli\n');

package/templates/hello-world/src/network.ts

@@ -53,7 +53,7 @@ export const NETWORK_CONFIGS: Record<NetworkId, NetworkConfig> = {
     indexerWS: 'wss://indexer.preview.midnight.network/api/v4/graphql/ws',
     node:      'https://rpc.preview.midnight.network',
     proofServer: 'http://127.0.0.1:6300',
-    faucet: 'https://faucet.preview.midnight.network',
+    faucet: 'https://midnight-tmnight-preview.nethermind.dev',
     composeServices: ['proof-server'],
   },
   preprod: {
@@ -62,7 +62,7 @@ export const NETWORK_CONFIGS: Record<NetworkId, NetworkConfig> = {
     indexerWS: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
     node:      'https://rpc.preprod.midnight.network',
     proofServer: 'http://127.0.0.1:6300',
-    faucet: 'https://faucet.preprod.midnight.network',
+    faucet: 'https://midnight-tmnight-preprod.nethermind.dev',
     composeServices: ['proof-server'],
   },
 };

package/templates/hello-world/src/wallet-state.ts

@@ -0,0 +1,95 @@
+// Wallet sync-state persistence.
+//
+// Mirrors network.ts: no template substitutions, all I/O via function
+// parameters, no SDK imports — keeps the module unit-testable from the
+// create-mn-app workspace (which doesn't install @midnight-ntwrk/* packages).
+//
+// Why: without persistence, every `npm run deploy` / `npm run cli` rebuilds
+// each child wallet from seed and re-syncs against the chain. On public
+// networks (preview, preprod) that's minutes per run — and painful on retries
+// after a transient failure. The SDK exposes serializeState() and restore()
+// on each child wallet class; wallet.ts is the glue that uses them, and this
+// file is the on-disk format underneath.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { NetworkId } from './network';
+
+export const WALLET_STATE_DIR = '.midnight-wallet-state';
+export const WALLET_STATE_VERSION = 1 as const;
+
+export type ChildKind = 'shielded' | 'unshielded' | 'dust';
+export const CHILD_KINDS: readonly ChildKind[] = ['shielded', 'unshielded', 'dust'] as const;
+
+export interface PersistedWalletState {
+  shielded?: unknown;
+  unshielded?: unknown;
+  dust?: string;
+}
+
+export interface FsOptions {
+  cwd?: string;
+}
+
+function networkDir(network: NetworkId, opts: FsOptions = {}): string {
+  return path.join(opts.cwd ?? process.cwd(), WALLET_STATE_DIR, network);
+}
+
+function statePath(network: NetworkId, kind: ChildKind, opts: FsOptions = {}): string {
+  return path.join(networkDir(network, opts), `${kind}.json`);
+}
+
+function atomicWrite(file: string, content: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+interface VersionedState<T> {
+  version: typeof WALLET_STATE_VERSION;
+  state: T;
+}
+
+function readVersionedState<T>(file: string): T | undefined {
+  if (!fs.existsSync(file)) return undefined;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8')) as VersionedState<T>;
+    if (!parsed || typeof parsed !== 'object' || parsed.version !== WALLET_STATE_VERSION) {
+      return undefined;
+    }
+    return parsed.state;
+  } catch {
+    // Corrupt file — caller falls back to from-seed sync; we'll overwrite on save.
+    return undefined;
+  }
+}
+
+function writeVersionedState<T>(file: string, state: T): void {
+  const payload: VersionedState<T> = { version: WALLET_STATE_VERSION, state };
+  atomicWrite(file, `${JSON.stringify(payload)}\n`);
+}
+
+export function loadWalletState(network: NetworkId, opts: FsOptions = {}): PersistedWalletState {
+  return {
+    shielded: readVersionedState(statePath(network, 'shielded', opts)),
+    unshielded: readVersionedState(statePath(network, 'unshielded', opts)),
+    dust: readVersionedState<string>(statePath(network, 'dust', opts)),
+  };
+}
+
+export function saveWalletState(
+  network: NetworkId,
+  state: PersistedWalletState,
+  opts: FsOptions = {},
+): void {
+  if (state.shielded !== undefined) writeVersionedState(statePath(network, 'shielded', opts), state.shielded);
+  if (state.unshielded !== undefined) writeVersionedState(statePath(network, 'unshielded', opts), state.unshielded);
+  if (state.dust !== undefined) writeVersionedState(statePath(network, 'dust', opts), state.dust);
+}
+
+export function clearWalletState(network: NetworkId, opts: FsOptions = {}): void {
+  const dir = networkDir(network, opts);
+  if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+}