create-mn-app 0.4.0 → 0.4.1

package/package.json

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

package/templates/hello-world/README.md.template

@@ -128,6 +128,19 @@ npm run network undeployed     # or: npm run setup -- --network undeployed
 Your preview/preprod wallet seeds and deploy addresses stay in
 `.midnight-state.json`. Switch back later, and they're still there.
 
+### Wallet sync cache
+
+After each `deploy`, `cli`, or `check-balance` run, the scripts serialize the
+wallet's synced state to `.midnight-wallet-state/<network>/` (gitignored).
+The next run on the same network restores from that snapshot and only catches
+up to the latest block instead of replaying from genesis — meaningful on
+`preview` / `preprod` where a from-seed sync takes minutes.
+
+If the cache is stale or corrupt (e.g. after an SDK upgrade with an
+incompatible state format) the wallet falls back to a fresh from-seed sync
+with a one-line warning. `npm run clean` removes the cache along with other
+generated state.
+
 ## Available scripts
 
 | Script                  | Description                                                    |
@@ -138,7 +151,7 @@ Your preview/preprod wallet seeds and deploy addresses stay in
 | `npm run cli`           | Interactive CLI to call circuits on the deployed contract.     |
 | `npm run check-balance` | Print the genesis-seed wallet's NIGHT and DUST balances.       |
 | `npm run test:e2e`      | Smoke + read-back check against the deployed contract.         |
-| `npm run clean`         | Remove `contracts/managed/` and `.midnight-state.json`.        |
+| `npm run clean`         | Remove `contracts/managed/`, `.midnight-state.json`, and `.midnight-wallet-state/`. |
 | `npm run proof-server:start` / `:stop` | Compose lifecycle for just the proof-server service. |
 
 ## Project structure
@@ -151,12 +164,14 @@ Your preview/preprod wallet seeds and deploy addresses stay in
 │   └── e2e-check.ts            # smoke + read-back
 ├── src/
 │   ├── network.ts              # network selection + state file management
+│   ├── wallet.ts               # wallet construction + sync-state cache
 │   ├── setup.ts                # orchestrator for `npm run setup`
 │   ├── deploy.ts               # deploy the contract
 │   ├── cli.ts                  # interact with deployed contract
 │   └── check-balance.ts        # NIGHT / DUST balance
 ├── docker-compose.yml          # node + indexer + proof-server
 ├── .midnight-state.json        # written by deploy (gitignored)
+├── .midnight-wallet-state/     # serialized sync state per network (gitignored)
 ├── package.json
 └── tsconfig.json
 ```

package/templates/hello-world/_gitignore

@@ -55,3 +55,6 @@ temp/
 
 # Midnight network state (per-network seeds, deploy addresses)
 .midnight-state.json
+
+# Midnight wallet sync state (per-network serialized wallet state cache)
+.midnight-wallet-state/

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

@@ -15,7 +15,7 @@
     "network": "npx tsx src/network.ts",
     "proof-server:start": "docker compose up -d",
     "proof-server:stop": "docker compose down",
-    "clean": "rm -rf contracts/managed .midnight-state.json",
+    "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"
   },

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/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 });
+}

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

@@ -0,0 +1,189 @@
+// Wallet construction + sync-state restore.
+//
+// Mirrors network.ts in structure. The on-disk format and pure I/O live in
+// wallet-state.ts (unit-tested from the scaffolder workspace, no SDK deps);
+// this file is the glue between that format and the wallet SDK.
+
+import { Buffer } from 'buffer';
+
+import * as ledger from '@midnight-ntwrk/ledger-v8';
+import { unshieldedToken } from '@midnight-ntwrk/ledger-v8';
+import { setNetworkId, getNetworkId } from '@midnight-ntwrk/midnight-js-network-id';
+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 type { NetworkConfig, NetworkId } from './network';
+import {
+  CHILD_KINDS,
+  loadWalletState,
+  saveWalletState,
+  type ChildKind,
+  type PersistedWalletState,
+} from './wallet-state';
+
+export { unshieldedToken };
+export type { PersistedWalletState };
+export {
+  loadWalletState,
+  saveWalletState,
+  clearWalletState,
+  WALLET_STATE_DIR,
+  WALLET_STATE_VERSION,
+} from './wallet-state';
+
+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;
+}
+
+export interface WalletContext {
+  wallet: Awaited<ReturnType<typeof WalletFacade.init>>;
+  shieldedSecretKeys: ReturnType<typeof ledger.ZswapSecretKeys.fromSeed>;
+  dustSecretKey: ReturnType<typeof ledger.DustSecretKey.fromSeed>;
+  unshieldedKeystore: ReturnType<typeof createKeystore>;
+  restored: { shielded: boolean; unshielded: boolean; dust: boolean };
+}
+
+export interface CreateWalletOptions {
+  network: NetworkId;
+  networkConfig: NetworkConfig;
+  seed: string;
+  /**
+   * Whether to attempt to restore each child wallet from saved state.
+   * Defaults to true. Pass false to force a from-seed sync (used by tests).
+   */
+  restore?: boolean;
+  cwd?: string;
+}
+
+function warnRestoreFailure(kind: ChildKind, err: unknown): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`  ⚠ Could not restore ${kind} wallet state (${msg}); falling back to fresh sync.\n`);
+}
+
+/**
+ * Build the wallet facade, restoring each child from saved state when
+ * available and falling back to a from-seed start when not (or when restore
+ * throws, e.g. after an SDK upgrade with an incompatible state format).
+ *
+ * Caller is responsible for `await wallet.waitForSyncedState()` afterwards.
+ */
+export async function createWallet(opts: CreateWalletOptions): Promise<WalletContext> {
+  setNetworkId(opts.networkConfig.networkId);
+
+  const keys = deriveKeys(opts.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 saved: PersistedWalletState = opts.restore === false
+    ? {}
+    : loadWalletState(opts.network, { cwd: opts.cwd });
+
+  const restored = { shielded: false, unshielded: false, dust: false };
+
+  const walletConfig = {
+    networkId,
+    indexerClientConnection: {
+      indexerHttpUrl: opts.networkConfig.indexer,
+      indexerWsUrl: opts.networkConfig.indexerWS,
+    },
+    provingServerUrl: new URL(opts.networkConfig.proofServer),
+    relayURL: new URL(opts.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) => {
+      const cls = ShieldedWallet(config);
+      if (saved.shielded !== undefined) {
+        try {
+          const restoredWallet = await (cls as any).restore(saved.shielded);
+          restored.shielded = true;
+          return restoredWallet;
+        } catch (err) {
+          warnRestoreFailure('shielded', err);
+        }
+      }
+      return cls.startWithSecretKeys(shieldedSecretKeys);
+    },
+    unshielded: async (config) => {
+      const cls = UnshieldedWallet(config);
+      if (saved.unshielded !== undefined) {
+        try {
+          const restoredWallet = await (cls as any).restore(saved.unshielded);
+          restored.unshielded = true;
+          return restoredWallet;
+        } catch (err) {
+          warnRestoreFailure('unshielded', err);
+        }
+      }
+      return cls.startWithPublicKey(PublicKey.fromKeyStore(unshieldedKeystore));
+    },
+    dust: async (config) => {
+      const cls = DustWallet(config);
+      if (saved.dust !== undefined) {
+        try {
+          const restoredWallet = await (cls as any).restore(saved.dust);
+          restored.dust = true;
+          return restoredWallet;
+        } catch (err) {
+          warnRestoreFailure('dust', err);
+        }
+      }
+      return cls.startWithSecretKey(dustSecretKey, ledger.LedgerParameters.initialParameters().dust);
+    },
+  });
+
+  await wallet.start(shieldedSecretKeys, dustSecretKey);
+
+  return { wallet, shieldedSecretKeys, dustSecretKey, unshieldedKeystore, restored };
+}
+
+/**
+ * Serialize each child wallet's current state and persist it for the next run.
+ * Safe to call multiple times. Logs but does not throw on individual failures —
+ * losing one child's state means the next run re-syncs that child only.
+ */
+export async function persistWalletState(
+  network: NetworkId,
+  ctx: WalletContext,
+  cwd?: string,
+): Promise<void> {
+  const next: PersistedWalletState = {};
+
+  for (const kind of CHILD_KINDS) {
+    try {
+      const child = (ctx.wallet as unknown as Record<ChildKind, { serializeState: () => Promise<unknown> }>)[kind];
+      const serialized = await child.serializeState();
+      if (kind === 'dust') {
+        next.dust = serialized as string;
+      } else {
+        next[kind] = serialized;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`  ⚠ Could not serialize ${kind} wallet state (${msg}); next run will re-sync.\n`);
+    }
+  }
+
+  saveWalletState(network, next, { cwd });
+}