midnightwalletsync 0.1.0

package/.env.example

@@ -0,0 +1 @@
+wallet_id_n1=your seed here

package/README.md

@@ -0,0 +1,196 @@
+# MidNight-walletsync
+
+A lightweight Midnight wallet synchronization SDK and CLI for keeping one or more wallets synced, saving snapshots locally, and querying balances from a running synced process.
+
+This package is designed for a local workspace. It is not a public RPC replacement and it does not hold any secrets by itself; it reads seeds from your `.env` file and uses them to build and start wallet instances.
+
+## What this SDK does
+
+- Builds wallets from seed values
+- Starts and keeps wallets synced to the Midnight network
+- Stores wallet snapshots on disk
+- Exposes a tiny local HTTP server for status and balance queries
+- Supports multiple wallets at the same time using aliases like `n1`, `n2`, `n3`
+- Formats balance output in a readable way
+- Shows NIGHT and DUST with decimal formatting
+
+## Why this exists
+
+The main idea is to keep a wallet synced once, then reuse that synced wallet state for repeated balance checks and for other local tooling.
+
+That means:
+
+- you do not need to resync every time
+- another terminal can query the synced wallet
+- other local SDK code can be built on top of the same synced wallet process
+
+
+## Configuration
+
+
+### `.env`
+
+Seeds are loaded from environment variables.
+
+With the default config, the package expects:
+
+- `wallet_id_n1`
+- `wallet_id_n2`
+- `wallet_id_n3`
+
+If you change `seedBaseName`, the variable names change too.
+
+Example:
+
+- `seedBaseName = wallet_id`
+- alias = `n1`
+- expected env key = `wallet_id_n1`
+
+## Commands
+
+Commands are invoked using `npx midnightsync <command>` in your workspace.
+
+For example:
+
+```sh
+npx midnightsync sync
+npx midnightsync balance n1
+npx midnightsync status
+```
+
+Or use the npm script shortcuts:
+
+```sh
+npm run sync
+npm run balance -- n1
+npm run status
+```
+
+### `npx midnightsync init`
+
+Creates or refreshes:
+
+- `midnightwalletsync.config.json`
+- `.env.example`
+- `.env` if missing
+
+Use this first in a fresh workspace.
+
+### `npx midnightsync sync`
+
+Starts the sync runtime.
+
+What happens:
+
+1. The SDK reads config and seeds
+2. Wallets are built from the seeds
+3. Wallets are started
+4. Sync begins
+5. Snapshots are written into `.midnightwalletsync/`
+6. A local server starts on `http://127.0.0.1:8787`
+
+Stop it with Ctrl+C.
+
+### `npx midnightsync status`
+
+Prints:
+
+- config file location
+- env file location
+- wallet aliases currently configured
+
+### `npx midnightsync balance <alias>`
+
+Reads the latest saved snapshot for a wallet alias and prints balances in a human-friendly format.
+
+Default alias is `n1`.
+
+Example:
+
+```sh
+npx midnightsync balance n1
+npx midnightsync balance n2
+```
+
+## Local HTTP API
+
+When sync is running, the SDK exposes a small local server.
+
+### `GET /health`
+
+Returns whether the server is up.
+
+### `GET /wallets`
+
+Returns the configured wallet aliases.
+
+### `GET /balance/:alias`
+
+Returns the latest snapshot for a wallet alias.
+
+Examples:
+
+- `http://127.0.0.1:8787/balance/n1`
+- `http://127.0.0.1:8787/balance/n2`
+
+Important:
+
+- the balance endpoint only returns data when the wallet has fully synced
+- if the wallet is not synced yet, it returns a `503`
+- if the snapshot does not exist, it returns a `404`
+
+## Multi-wallet behavior
+
+If `walletCount` is greater than 1, the SDK starts multiple wallets in parallel.
+
+Each wallet gets an alias:
+
+- `n1`
+- `n2`
+- `n3`
+- and so on
+
+Each alias maps to a seed key in `.env`.
+
+This makes it possible to keep several wallets synced in one process.
+
+## Typical workflow
+
+1. Run `npx midnightsync init`
+2. Put real seeds into `.env`
+3. Adjust `midnightwalletsync.config.json` if needed
+4. Run `npx midnightsync sync`
+5. Open another terminal
+6. Run `npx midnightsync balance n1`
+7. Query `http://127.0.0.1:8787/balance/n1` if you want JSON output
+
+## Can other SDKs use this?
+
+Yes, conceptually this SDK can act like a local wallet service.
+
+That means another local SDK can:
+
+- wait for the wallet to sync
+- read balances and addresses
+- build higher-level logic on top of the synced wallet state
+
+## Notes
+
+- This package is currently scoped to preprod usage
+- Seeds are required for private wallet control
+- Balance queries are intentionally blocked until sync is complete
+- The local server is meant for localhost use only
+
+## Troubleshooting
+
+### `wallet is not fully synced yet`
+
+Wait for `npm run sync` to finish syncing, then query again.
+
+### `Missing seed for n1`
+
+Add the correct seed to `.env` using the expected key name.
+
+### Nothing prints in balance
+
+Check that the wallet alias exists and that the snapshot file is present in `.midnightwalletsync/`.

package/bin/midnightsync.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'child_process';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+
+// Try to find tsx from package node_modules
+const tsxPath = join(rootDir, 'node_modules', '.bin', 'tsx');
+
+const result = spawnSync(tsxPath, [join(rootDir, 'src', 'cli.ts'), ...process.argv.slice(2)], {
+  cwd: rootDir,
+  env: {
+    ...process.env,
+    NODE_OPTIONS: '--no-deprecation',
+  },
+  stdio: 'inherit',
+});
+
+process.exit(result.status ?? 0);

package/midnightwalletsync.config.json

@@ -0,0 +1,14 @@
+{
+  "network": "preprod",
+  "seedBaseName": "wallet_id",
+  "walletCount": 1,
+  "stateDir": ".midnightwalletsync",
+  "port": 8787,
+  "nightDecimals": 6,
+  "dustDecimals": 15,
+  "indexer": "https://indexer.preprod.midnight.network/api/v4/graphql",
+  "indexerWS": "wss://indexer.preprod.midnight.network/api/v4/graphql/ws",
+  "node": "https://rpc.preprod.midnight.network",
+  "nodeWS": "wss://rpc.preprod.midnight.network",
+  "proofServer": "https://proof.preprod.midnight.network"
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "midnightwalletsync",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "midnightwalletsync.config.json",
+    ".env.example",
+    "tsconfig.json"
+  ],
+  "bin": {
+    "midnightsync": "bin/midnightsync.js"
+  },
+  "scripts": {
+    "init": "NODE_OPTIONS=--no-deprecation tsx src/cli.ts init",
+    "sync": "NODE_OPTIONS=--no-deprecation tsx src/cli.ts sync",
+    "balance": "NODE_OPTIONS=--no-deprecation tsx src/cli.ts balance",
+    "status": "NODE_OPTIONS=--no-deprecation tsx src/cli.ts status",
+    "build": "npm run typecheck",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@midnight-ntwrk/ledger-v8": "latest",
+    "@midnight-ntwrk/testkit-js": "latest",
+    "@midnight-ntwrk/wallet-sdk-address-format": "latest",
+    "@midnight-ntwrk/wallet-sdk-facade": "latest",
+    "tsx": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "latest"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,147 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureWorkspaceFiles, envExamplePath, envPath, seedKey, walletAliases } from './config.js';
+import { WalletSyncRuntime } from './runtime.js';
+import type { WalletAlias } from './types.js';
+
+const NIGHT_TOKEN_TYPE = '0000000000000000000000000000000000000000000000000000000000000000';
+
+function formatUnits(raw: bigint, decimals: number): string {
+  if (decimals <= 0) {
+    return raw.toString();
+  }
+  const base = 10n ** BigInt(decimals);
+  const whole = raw / base;
+  const fraction = raw % base;
+  if (fraction === 0n) {
+    return whole.toString();
+  }
+  const fractionText = fraction.toString().padStart(decimals, '0').replace(/0+$/, '');
+  return `${whole.toString()}.${fractionText}`;
+}
+
+function labelToken(token: string): string {
+  return token === NIGHT_TOKEN_TYPE ? 'NIGHT' : token;
+}
+
+function usage(): void {
+  console.log([
+    'MidNight-walletsync commands:',
+    '  init',
+    '  sync',
+    '  status',
+    '  balance <n1|n2|...>',
+  ].join('\n'));
+}
+
+function printSnapshot(snapshot: any, nightDecimals: number, dustDecimals: number): void {
+  const unshieldedBalances = snapshot.unshieldedBalances ?? {};
+  const shieldedBalances = snapshot.shieldedBalances ?? {};
+  const nightRaw = BigInt(unshieldedBalances[NIGHT_TOKEN_TYPE] ?? '0') + BigInt(shieldedBalances[NIGHT_TOKEN_TYPE] ?? '0');
+  const dustRaw = BigInt(snapshot.dustBalanceRaw ?? '0');
+
+  const labeledUnshielded = Object.fromEntries(
+    Object.entries(unshieldedBalances).map(([token, amount]) => [labelToken(token), amount]),
+  );
+  const labeledShielded = Object.fromEntries(
+    Object.entries(shieldedBalances).map(([token, amount]) => [labelToken(token), amount]),
+  );
+
+  const otherUnshielded = Object.fromEntries(
+    Object.entries(unshieldedBalances).filter(([token]) => token !== NIGHT_TOKEN_TYPE),
+  );
+  const otherShielded = Object.fromEntries(
+    Object.entries(shieldedBalances).filter(([token]) => token !== NIGHT_TOKEN_TYPE),
+  );
+
+  console.log('=== WALLET BALANCE ===');
+  console.log(`alias: ${snapshot.alias}`);
+  console.log(`updatedAt: ${snapshot.updatedAt}`);
+  console.log(`synced: ${snapshot.isSynced}`);
+  console.log(`unshielded address: ${snapshot.unshieldedAddress}`);
+  console.log(`shielded address: ${snapshot.shieldedAddress}`);
+  console.log(`dust address: ${snapshot.dustAddress}`);
+  console.log('');
+  console.log('unshielded balances:');
+  console.log(JSON.stringify(labeledUnshielded, null, 2));
+  console.log(`NIGHT: ${formatUnits(nightRaw, nightDecimals)}`);
+  console.log(`DUST: ${formatUnits(dustRaw, dustDecimals)}`);
+  console.log('');
+  console.log('other unshielded tokens (raw):');
+  console.log(JSON.stringify(otherUnshielded, null, 2));
+  console.log('other shielded tokens (raw):');
+  console.log(JSON.stringify(otherShielded, null, 2));
+  console.log('');
+  console.log('shielded balances:');
+  console.log(JSON.stringify(labeledShielded, null, 2));
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  const cwd = process.cwd();
+
+  if (!command) {
+    usage();
+    return;
+  }
+
+  if (command === 'init') {
+    const config = ensureWorkspaceFiles(cwd);
+    const example = walletAliases(config.walletCount)
+      .map((alias) => `${seedKey(config.seedBaseName, alias)}=replace_me`)
+      .join('\n');
+    writeFileSync(envExamplePath(cwd), `${example}\n`, 'utf8');
+    console.log(`Created ${join(cwd, 'midnightwalletsync.config.json')}`);
+    console.log(`Created ${envExamplePath(cwd)}`);
+    return;
+  }
+
+  const config = ensureWorkspaceFiles(cwd);
+  const runtime = WalletSyncRuntime.fromWorkspace(cwd, config);
+
+  if (command === 'sync') {
+    const server = runtime.createServer();
+    const shutdown = async () => {
+      server.close();
+      await runtime.stopAll();
+      process.exit(0);
+    };
+    const keepAlive = new Promise<void>((resolve) => {
+      process.once('SIGINT', () => { void shutdown().finally(resolve); });
+      process.once('SIGTERM', () => { void shutdown().finally(resolve); });
+    });
+    server.listen(config.port, '127.0.0.1', () => {
+      console.log(`[info] server listening on http://127.0.0.1:${config.port}`);
+    });
+    await runtime.startAll();
+    console.log('[info] all wallets synced');
+    await keepAlive;
+    return;
+  }
+
+  if (command === 'status') {
+    console.log(`Config file: ${join(cwd, 'midnightwalletsync.config.json')}`);
+    console.log(`Env file: ${envPath(cwd)}`);
+    console.log(`Wallets: ${runtime.listAliases().join(', ')}`);
+    return;
+  }
+
+  if (command === 'balance') {
+    const alias = (args[0] ?? 'n1') as WalletAlias;
+    const snapshotPath = join(cwd, config.stateDir, `${alias}.json`);
+    const snapshot = JSON.parse(readFileSync(snapshotPath, 'utf8'));
+    if (!snapshot.isSynced) {
+      console.log('[info] wallet is not fully synced yet');
+      return;
+    }
+    printSnapshot(snapshot, config.nightDecimals, config.dustDecimals);
+    return;
+  }
+
+  usage();
+}
+
+main().catch((error) => {
+  console.error('[error]', error);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,139 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { MidnightWalletSyncConfig, WalletAlias } from './types.js';
+
+export const CONFIG_FILE_NAME = 'midnightwalletsync.config.json';
+export const ENV_FILE_NAME = '.env';
+export const ENV_EXAMPLE_FILE_NAME = '.env.example';
+
+export function defaultConfig(): MidnightWalletSyncConfig {
+  return {
+    network: 'preprod',
+    seedBaseName: 'wallet_id',
+    walletCount: 3,
+    stateDir: '.midnightwalletsync',
+    port: 8787,
+    nightDecimals: 6,
+    dustDecimals: 15,
+    indexer: 'https://indexer.preprod.midnight.network/api/v4/graphql',
+    indexerWS: 'wss://indexer.preprod.midnight.network/api/v4/graphql/ws',
+    node: 'https://rpc.preprod.midnight.network',
+    nodeWS: 'wss://rpc.preprod.midnight.network',
+    proofServer: 'https://proof.preprod.midnight.network',
+  };
+}
+
+export function configPath(cwd = process.cwd()): string {
+  return join(cwd, CONFIG_FILE_NAME);
+}
+
+export function envPath(cwd = process.cwd()): string {
+  return join(cwd, ENV_FILE_NAME);
+}
+
+export function envExamplePath(cwd = process.cwd()): string {
+  return join(cwd, ENV_EXAMPLE_FILE_NAME);
+}
+
+export function normalizeConfig(config: Partial<MidnightWalletSyncConfig>): MidnightWalletSyncConfig {
+  const base = defaultConfig();
+  const walletCount = Number(config.walletCount ?? base.walletCount);
+  return {
+    network: String(config.network ?? base.network),
+    seedBaseName: String(config.seedBaseName ?? base.seedBaseName),
+    walletCount: Number.isFinite(walletCount) && walletCount > 0 ? Math.floor(walletCount) : base.walletCount,
+    stateDir: String(config.stateDir ?? base.stateDir),
+    port: Number(config.port ?? base.port),
+    nightDecimals: Number(config.nightDecimals ?? base.nightDecimals),
+    dustDecimals: Number(config.dustDecimals ?? base.dustDecimals),
+    indexer: String(config.indexer ?? base.indexer),
+    indexerWS: String(config.indexerWS ?? base.indexerWS),
+    node: String(config.node ?? base.node),
+    nodeWS: String(config.nodeWS ?? base.nodeWS),
+    proofServer: String(config.proofServer ?? base.proofServer),
+  };
+}
+
+export function writeDefaultConfig(cwd = process.cwd()): MidnightWalletSyncConfig {
+  const config = defaultConfig();
+  writeFileSync(configPath(cwd), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return config;
+}
+
+export function ensureConfig(cwd = process.cwd()): MidnightWalletSyncConfig {
+  const path = configPath(cwd);
+  if (!existsSync(path)) {
+    return writeDefaultConfig(cwd);
+  }
+  const raw = readFileSync(path, 'utf8');
+  return normalizeConfig(JSON.parse(raw) as Partial<MidnightWalletSyncConfig>);
+}
+
+function parseEnvFile(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function loadEnvMap(cwd = process.cwd()): Record<string, string> {
+  const fromProcess = Object.fromEntries(
+    Object.entries(process.env).flatMap(([key, value]) => (value === undefined ? [] : [[key, value]])),
+  );
+  const file = envPath(cwd);
+  if (!existsSync(file)) {
+    return fromProcess;
+  }
+  const fileEnv = parseEnvFile(readFileSync(file, 'utf8'));
+  return {
+    ...fromProcess,
+    ...fileEnv,
+  };
+}
+
+export function seedKey(baseName: string, alias: WalletAlias): string {
+  return `${baseName}_${alias}`;
+}
+
+export function resolveSeed(envMap: Record<string, string>, baseName: string, alias: WalletAlias): string {
+  const key = seedKey(baseName, alias);
+  const direct = envMap[key] ?? envMap[baseName];
+  if (!direct) {
+    throw new Error(`Missing seed for ${alias}. Expected ${key} in .env`);
+  }
+  return direct;
+}
+
+export function walletAliases(walletCount: number): WalletAlias[] {
+  return Array.from({ length: walletCount }, (_, index) => `n${index + 1}` as WalletAlias);
+}
+
+export function ensureWorkspaceFiles(cwd = process.cwd()): MidnightWalletSyncConfig {
+  const config = ensureConfig(cwd);
+  if (!existsSync(envExamplePath(cwd))) {
+    const lines = walletAliases(config.walletCount).map((alias) => `${seedKey(config.seedBaseName, alias)}=replace_me`);
+    writeFileSync(envExamplePath(cwd), `${lines.join('\n')}\n`, 'utf8');
+  }
+  if (!existsSync(envPath(cwd))) {
+    writeFileSync(envPath(cwd), `# Copy values from .env.example into this file\n`, 'utf8');
+  }
+  mkdirSync(join(cwd, config.stateDir), { recursive: true });
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './config.js';
+export * from './snapshot.js';
+export * from './runtime.js';

package/src/runtime.ts

@@ -0,0 +1,217 @@
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { DustSecretKey, LedgerParameters, ZswapSecretKeys } from '@midnight-ntwrk/ledger-v8';
+import { type FacadeState, type WalletFacade } from '@midnight-ntwrk/wallet-sdk-facade';
+import { MidnightBech32m, ShieldedAddress, UnshieldedAddress } from '@midnight-ntwrk/wallet-sdk-address-format';
+import { type DustWalletOptions, FluentWalletBuilder } from '@midnight-ntwrk/testkit-js';
+import type { MidnightWalletSyncConfig, WalletAlias, WalletSnapshot } from './types.js';
+import { loadEnvMap, resolveSeed, walletAliases } from './config.js';
+import { saveSnapshot, snapshotPath } from './snapshot.js';
+
+function formatBalances(balances: Record<string, bigint>): Record<string, string> {
+  return Object.fromEntries(Object.entries(balances).map(([token, amount]) => [token, amount.toString()]));
+}
+
+function formatAddress(networkId: string, address: unknown): string {
+  try {
+    if (address && typeof address === 'object') {
+      return MidnightBech32m.encode(networkId, address as never).asString();
+    }
+  } catch {
+    // fall through
+  }
+  return String(address);
+}
+
+function snapshotFromState(alias: WalletAlias, networkId: string, state: any): WalletSnapshot {
+  return {
+    alias,
+    updatedAt: new Date().toISOString(),
+    isSynced: Boolean(state.isSynced),
+    shieldedBalances: formatBalances(state.shielded.balances),
+    unshieldedBalances: formatBalances(state.unshielded.balances),
+    dustBalanceRaw: state.dust.balance(new Date()).toString(),
+    shieldedAddress: formatAddress(networkId, state.shielded.address),
+    unshieldedAddress: formatAddress(networkId, state.unshielded.address),
+    dustAddress: formatAddress(networkId, state.dust.address),
+  };
+}
+
+function createLogger() {
+  return {
+    info: (...args: unknown[]) => console.log('[info]', ...args),
+    debug: (...args: unknown[]) => console.debug('[debug]', ...args),
+    error: (...args: unknown[]) => console.error('[error]', ...args),
+  } as const;
+}
+
+class WalletService {
+  readonly wallet: WalletFacade;
+
+  private constructor(
+    private readonly logger: ReturnType<typeof createLogger>,
+    private readonly cwd: string,
+    private readonly networkId: string,
+    wallet: WalletFacade,
+    private readonly shieldedSecretKeys: ZswapSecretKeys,
+    private readonly dustSecretKey: DustSecretKey,
+  ) {
+    this.wallet = wallet;
+  }
+
+  static async build(logger: ReturnType<typeof createLogger>, config: MidnightWalletSyncConfig, seed: string) {
+    const environment = {
+      walletNetworkId: config.network,
+      networkId: config.network,
+      indexer: config.indexer,
+      indexerWS: config.indexerWS,
+      node: config.node,
+      nodeWS: config.nodeWS,
+      proofServer: config.proofServer,
+    };
+    const dustOptions: DustWalletOptions = {
+      ledgerParams: LedgerParameters.initialParameters(),
+      additionalFeeOverhead: 1_000n,
+      feeBlocksMargin: 5,
+    };
+    const walletFacadeBuilder = FluentWalletBuilder.forEnvironment(environment).withDustOptions(dustOptions);
+    const buildResult = await walletFacadeBuilder.withSeed(seed).buildWithoutStarting();
+    const { wallet, seeds } = buildResult as {
+      wallet: WalletFacade;
+      seeds: { masterSeed: string; shielded: Uint8Array; dust: Uint8Array };
+    };
+    logger.info(`Wallet built from seed: ${seeds.masterSeed.slice(0, 8)}...`);
+    return new WalletService(
+      logger,
+      process.cwd(),
+      environment.networkId,
+      wallet,
+      ZswapSecretKeys.fromSeed(seeds.shielded),
+      DustSecretKey.fromSeed(seeds.dust),
+    );
+  }
+
+  async start(): Promise<void> {
+    this.logger.info('Starting wallet...');
+    await this.wallet.start(this.shieldedSecretKeys, this.dustSecretKey);
+  }
+
+  async stop(): Promise<void> {
+    await this.wallet.stop();
+  }
+
+  async waitSynced(): Promise<FacadeState> {
+    return this.wallet.waitForSyncedState();
+  }
+
+  subscribeSnapshots(
+    alias: WalletAlias,
+    stateDir: string,
+    onSnapshot?: (snapshot: WalletSnapshot) => void,
+  ): void {
+    this.wallet.state().subscribe((state: any) => {
+      const snapshot = snapshotFromState(alias, this.networkId, state);
+      saveSnapshot(this.cwd, stateDir, snapshot);
+      onSnapshot?.(snapshot);
+    });
+  }
+}
+
+export class WalletSyncRuntime {
+  private readonly logger = createLogger();
+  private readonly envMap: Record<string, string>;
+  private readonly aliases: WalletAlias[];
+  private readonly services = new Map<WalletAlias, WalletService>();
+
+  constructor(
+    private readonly cwd: string,
+    readonly config: MidnightWalletSyncConfig,
+  ) {
+    this.envMap = loadEnvMap(cwd);
+    this.aliases = walletAliases(config.walletCount);
+  }
+
+  static fromWorkspace(cwd: string, config: MidnightWalletSyncConfig) {
+    return new WalletSyncRuntime(cwd, config);
+  }
+
+  private seedFor(alias: WalletAlias): string {
+    return resolveSeed(this.envMap, this.config.seedBaseName, alias);
+  }
+
+  async startAll(onSnapshot?: (alias: WalletAlias, snapshot: WalletSnapshot) => void): Promise<void> {
+    for (const alias of this.aliases) {
+      const service = await WalletService.build(this.logger, this.config, this.seedFor(alias));
+      this.services.set(alias, service);
+      service.subscribeSnapshots(alias, this.config.stateDir, (snapshot) => onSnapshot?.(alias, snapshot));
+    }
+    await Promise.all(
+      Array.from(this.services.entries()).map(async ([alias, service]) => {
+        await service.start();
+        await service.waitSynced();
+        this.logger.info(`Wallet ${alias} synced`);
+      }),
+    );
+  }
+
+  async stopAll(): Promise<void> {
+    await Promise.all(Array.from(this.services.values()).map((service) => service.stop()));
+  }
+
+  readSnapshot(alias: WalletAlias): WalletSnapshot | null {
+    const path = snapshotPath(this.cwd, this.config.stateDir, alias);
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as WalletSnapshot;
+    } catch {
+      return null;
+    }
+  }
+
+  listAliases(): WalletAlias[] {
+    return [...this.aliases];
+  }
+
+  get port(): number {
+    return this.config.port;
+  }
+
+  createServer() {
+    return createServer(async (req, res) => {
+      const requestUrl = new URL(req.url ?? '/', `http://127.0.0.1:${this.port}`);
+      const pathParts = requestUrl.pathname.split('/').filter(Boolean);
+
+      if (requestUrl.pathname === '/health') {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+
+      if (requestUrl.pathname === '/wallets') {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, wallets: this.listAliases() }, null, 2));
+        return;
+      }
+
+      if (pathParts[0] === 'balance' && pathParts.length === 2) {
+        const alias = pathParts[1] as WalletAlias;
+        const snapshot = this.readSnapshot(alias);
+        if (!snapshot) {
+          res.writeHead(404, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, message: `No snapshot for ${alias}` }));
+          return;
+        }
+        if (!snapshot.isSynced) {
+          res.writeHead(503, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, message: 'Wallet not fully synced yet.' }));
+          return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, ...snapshot }, null, 2));
+        return;
+      }
+
+      res.writeHead(404, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, message: 'Use /health, /wallets, or /balance/:alias' }));
+    });
+  }
+}

package/src/snapshot.ts

@@ -0,0 +1,37 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { WalletAlias, WalletSnapshot } from './types.js';
+
+export function snapshotDirPath(cwd: string, stateDir: string): string {
+  return join(cwd, stateDir);
+}
+
+export function snapshotPath(cwd: string, stateDir: string, alias: WalletAlias): string {
+  return join(snapshotDirPath(cwd, stateDir), `${alias}.json`);
+}
+
+export function saveSnapshot(cwd: string, stateDir: string, snapshot: WalletSnapshot): void {
+  const dir = snapshotDirPath(cwd, stateDir);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(snapshotPath(cwd, stateDir, snapshot.alias), `${JSON.stringify(snapshot, null, 2)}\n`, 'utf8');
+}
+
+export function loadSnapshot(
+  cwd: string,
+  stateDir: string,
+  alias: WalletAlias,
+): WalletSnapshot | null {
+  const path = snapshotPath(cwd, stateDir, alias);
+  if (!existsSync(path)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(path, 'utf8')) as WalletSnapshot;
+}
+
+export function listSavedSnapshots(cwd: string, stateDir: string): WalletSnapshot[] {
+  const dir = snapshotDirPath(cwd, stateDir);
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return [];
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export type MidnightWalletSyncConfig = {
+  network: string;
+  seedBaseName: string;
+  walletCount: number;
+  stateDir: string;
+  port: number;
+  nightDecimals: number;
+  dustDecimals: number;
+  indexer: string;
+  indexerWS: string;
+  node: string;
+  nodeWS: string;
+  proofServer: string;
+};
+
+export type WalletAlias = `n${number}`;
+
+export type WalletSnapshot = {
+  alias: WalletAlias;
+  updatedAt: string;
+  isSynced: boolean;
+  shieldedBalances: Record<string, string>;
+  unshieldedBalances: Record<string, string>;
+  dustBalanceRaw: string;
+  shieldedAddress: string;
+  unshieldedAddress: string;
+  dustAddress: string;
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}