@1sat/cli 0.0.31 → 0.0.33

package/package.json

@@ -1,34 +1,45 @@
 {
-	"name": "@1sat/cli",
-	"version": "0.0.31",
-	"description": "CLI for 1Sat Ordinals SDK",
-	"type": "module",
-	"main": "./src/cli.ts",
-	"bin": {
-		"1sat": "./src/cli.ts"
-	},
-	"files": ["src"],
-	"scripts": {
-		"build": "bun build ./src/cli.ts --compile --outfile=bin/1sat --external pg --external pg-native --external pg-query-stream --external tedious --external oracledb --external mysql",
-		"dev": "bun run src/cli.ts",
-		"lint": "biome check src"
-	},
-	"keywords": ["1sat", "bsv", "ordinals", "cli"],
-	"license": "MIT",
-	"dependencies": {
-		"@1sat/actions": "0.0.99",
-		"@1sat/client": "0.0.21",
-		"@1sat/types": "0.0.17",
-		"@1sat/wallet-node": "0.0.29",
-		"@bsv/sdk": "^2.0.13",
-		"chalk": "^5.0.0",
-		"@clack/prompts": "^0.8.0",
-		"bitcoin-backup": "^0.0.11",
-		"dotenv": "^17.0.0",
-		"evlog": "^2.10.0"
-	},
-	"devDependencies": {
-		"@types/bun": "^1.3.9",
-		"typescript": "^5.9.3"
-	}
+  "name": "@1sat/cli",
+  "version": "0.0.33",
+  "description": "CLI for 1Sat Ordinals SDK",
+  "type": "module",
+  "main": "./src/cli.ts",
+  "bin": {
+    "1sat": "./src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts --compile --outfile=bin/1sat --external pg --external pg-native --external pg-query-stream --external tedious --external oracledb --external mysql",
+    "dev": "bun run src/cli.ts",
+    "lint": "biome check src"
+  },
+  "keywords": [
+    "1sat",
+    "bsv",
+    "ordinals",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@1sat/actions": "0.0.99",
+    "@1sat/client": "0.0.21",
+    "@1sat/types": "0.0.17",
+    "@1sat/wallet-node": "0.0.30",
+    "@1sat/wallet-server": "0.0.2",
+    "@bsv/sdk": "^2.0.13",
+    "@bsv/wallet-toolbox": "^2.1.21",
+    "chalk": "^5.0.0",
+    "@clack/prompts": "^0.8.0",
+    "bitcoin-backup": "^0.0.11",
+    "dotenv": "^17.0.0",
+    "evlog": "^2.10.0",
+    "knex": "^3.1.0",
+    "pg": "^8.11.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
+  }
 }

package/src/cli.ts

@@ -16,6 +16,7 @@ import { handleMcpProxyCommand } from './commands/mcp-proxy'
 import { handleOpnsCommand } from './commands/opns'
 import { handleOrdinalsCommand } from './commands/ordinals'
 import { handleRemoteCommand } from './commands/remote'
+import { handleServeCommand } from './commands/serve'
 import { handleSocialCommand } from './commands/social'
 import { handleSweepCommand } from './commands/sweep'
 import { handleTokensCommand } from './commands/tokens'
@@ -98,6 +99,10 @@ async function main(): Promise<void> {
 			await handleMcpProxyCommand()
 			break
 
+		case 'serve':
+			await handleServeCommand(rest, flags)
+			break
+
 		case 'help':
 			printHelp()
 			break
@@ -111,5 +116,6 @@ async function main(): Promise<void> {
 
 main().catch((err) => {
 	console.error(formatError(`Error: ${err.message}`))
+	if (process.env.DEBUG) console.error(err.stack)
 	process.exit(1)
 })

package/src/commands/config.ts

@@ -10,11 +10,12 @@
 
 import type { GlobalFlags } from '../args'
 import {
-	type OneSatCliConfig,
 	getConfigDir,
 	getConfigFile,
 	loadConfig,
-	updateConfig,
+	parseConfigValue,
+	setConfigPath,
+	unsetConfigPath,
 } from '../config'
 import { printCommandHelp } from '../help'
 import {
@@ -23,15 +24,8 @@ import {
 	formatSuccess,
 	formatValue,
 	output,
-	printKeyValue,
 } from '../output'
 
-const SETTABLE_KEYS: Array<keyof OneSatCliConfig> = [
-	'chain',
-	'dataDir',
-	'storageIdentityKey',
-]
-
 export async function handleConfigCommand(
 	args: string[],
 	opts: GlobalFlags,
@@ -69,11 +63,7 @@ function configShow(opts: GlobalFlags): void {
 	}
 
 	console.log()
-	printKeyValue({
-		chain: config.chain,
-		dataDir: config.dataDir,
-		storageIdentityKey: config.storageIdentityKey ?? '(not set)',
-	})
+	printNested(config, '')
 	console.log()
 	console.log(
 		`  ${formatLabel('config file:')}  ${formatValue(getConfigFile())}`,
@@ -81,48 +71,83 @@ function configShow(opts: GlobalFlags): void {
 	console.log()
 }
 
-function configSet(args: string[], opts: GlobalFlags): void {
-	const [key, value] = args
-
-	if (!key || !value) {
-		fatal(
-			`Usage: 1sat config set <key> <value>\n\nSettable keys: ${SETTABLE_KEYS.join(', ')}`,
+function printNested(value: unknown, prefix: string): void {
+	if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+		console.log(
+			`  ${formatLabel(`${prefix || '(value)'}:`)}  ${formatValue(String(value))}`,
 		)
+		return
 	}
-
-	if (!SETTABLE_KEYS.includes(key as keyof OneSatCliConfig)) {
-		fatal(
-			`Unknown config key: ${key}\n\nSettable keys: ${SETTABLE_KEYS.join(', ')}`,
-		)
+	const obj = value as Record<string, unknown>
+	for (const [k, v] of Object.entries(obj)) {
+		const path = prefix ? `${prefix}.${k}` : k
+		if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+			printNested(v, path)
+		} else {
+			const display = Array.isArray(v)
+				? JSON.stringify(v)
+				: String(v ?? '(not set)')
+			console.log(`  ${formatLabel(`${path}:`)}  ${formatValue(display)}`)
+		}
 	}
+}
+
+function configSet(args: string[], opts: GlobalFlags): void {
+	const [key, ...valueArgs] = args
+	const value = valueArgs.join(' ')
 
-	// Validate specific keys
-	if (key === 'chain' && value !== 'main' && value !== 'test') {
-		fatal("chain must be 'main' or 'test'")
+	if (!key || valueArgs.length === 0) {
+		fatal('Usage: 1sat config set <dotted.path> <value>')
 	}
 
-	const updated = updateConfig({ [key]: value })
-	output(opts.json ? updated : formatSuccess(`Set ${key} = ${value}`), opts)
+	const parsed = parseConfigValue(value)
+	validateKnownPath(key, parsed)
+
+	setConfigPath(key, parsed)
+	output(
+		opts.json ? { [key]: parsed } : formatSuccess(`Set ${key} = ${value}`),
+		opts,
+	)
 }
 
 function configUnset(args: string[], opts: GlobalFlags): void {
 	const [key] = args
 
 	if (!key) {
-		fatal(
-			`Usage: 1sat config unset <key>\n\nKeys that can be unset: ${SETTABLE_KEYS.join(', ')}`,
-		)
+		fatal('Usage: 1sat config unset <dotted.path>')
 	}
 
-	if (!SETTABLE_KEYS.includes(key as keyof OneSatCliConfig)) {
-		fatal(
-			`Unknown config key: ${key}\n\nKeys that can be unset: ${SETTABLE_KEYS.join(', ')}`,
-		)
-	}
+	unsetConfigPath(key)
+	output(opts.json ? { [key]: undefined } : formatSuccess(`Unset ${key}`), opts)
+}
 
-	// For other keys, use undefined
-	const updated = updateConfig({ [key]: undefined })
-	output(opts.json ? updated : formatSuccess(`Unset ${key}`), opts)
+/**
+ * Enforce the few semantic constraints we care about. Unknown paths are
+ * allowed — callers that read them can validate at consumption time.
+ */
+function validateKnownPath(key: string, value: unknown): void {
+	switch (key) {
+		case 'chain':
+			if (value !== 'main' && value !== 'test') {
+				fatal("chain must be 'main' or 'test'")
+			}
+			break
+		case 'server.storage.provider':
+			if (value !== 'bun-sqlite' && value !== 'knex-pg') {
+				fatal("server.storage.provider must be 'bun-sqlite' | 'knex-pg'")
+			}
+			break
+		case 'server.port':
+			if (typeof value !== 'number' || value <= 0 || !Number.isInteger(value)) {
+				fatal('server.port must be a positive integer')
+			}
+			break
+		case 'server.accounts.enabled':
+			if (typeof value !== 'boolean') {
+				fatal('server.accounts.enabled must be true or false')
+			}
+			break
+	}
 }
 
 function configPath(opts: GlobalFlags): void {

package/src/commands/remote.ts

@@ -8,6 +8,8 @@
  *   set-active - Switch active storage to a remote or back to local
  */
 
+import { StorageClient } from '@1sat/wallet-node'
+import { WalletServerClient, topUpStorage } from '@1sat/wallet-server'
 import { confirm, isCancel, text } from '@clack/prompts'
 import type { GlobalFlags } from '../args'
 import { loadConfig, saveConfig } from '../config'
@@ -31,6 +33,10 @@ export async function handleRemoteCommand(
 			return remoteDelete(rest, opts)
 		case 'set-active':
 			return remoteSetActive(rest, opts)
+		case 'status':
+			return remoteStatus(rest, opts)
+		case 'topup':
+			return remoteTopup(rest, opts)
 		default:
 			printCommandHelp('remote', {
 				add: 'Add a remote storage as backup (1sat remote add <url>)',
@@ -39,6 +45,10 @@ export async function handleRemoteCommand(
 					'Remove a remote from the backup list (1sat remote delete <url>)',
 				'set-active':
 					'Switch active storage (1sat remote set-active <url | local>)',
+				status:
+					'Fetch GET /account/status from a remote (1sat remote status [url])',
+				topup:
+					'Buy capacity on a remote (1sat remote topup [url] [--units N])',
 			})
 			if (subcommand && subcommand !== 'help') {
 				process.exit(1)
@@ -85,11 +95,7 @@ async function remoteAdd(args: string[], opts: GlobalFlags): Promise<void> {
 	const config = loadConfig()
 
 	try {
-		// For backup-only, we use StorageClient via wallet-node
-		// biome-ignore lint/suspicious/noExplicitAny: StorageClient constructor not typed in wallet-toolbox
-		const { StorageClient } = await import('@1sat/wallet-node')
-		const wallet = walletResult.wallet as any
-		const client = new (StorageClient as any)(wallet, url)
+		const client = new StorageClient(walletResult.wallet, url)
 		await walletResult.storage.addWalletStorageProvider(client)
 
 		// When adding a backup, the remote may report itself as "active" which
@@ -128,7 +134,7 @@ async function remoteAdd(args: string[], opts: GlobalFlags): Promise<void> {
 
 async function remoteList(_args: string[], opts: GlobalFlags): Promise<void> {
 	const privateKey = await loadKey(resolvePassword())
-	const { walletResult, destroy } = await loadContext(privateKey, {
+	const { destroy } = await loadContext(privateKey, {
 		chain: opts.chain,
 	})
 
@@ -321,6 +327,152 @@ async function remoteSetActive(
 	}
 }
 
+// ============================================================================
+// remote status
+// ============================================================================
+
+async function remoteStatus(args: string[], opts: GlobalFlags): Promise<void> {
+	const config = loadConfig()
+	const url = args[0] ?? config.activeRemote ?? config.backups?.[0]
+	if (!url) {
+		fatal(
+			'No remote URL supplied. Pass one as an argument or configure activeRemote/backups first.',
+		)
+	}
+	try {
+		new URL(url)
+	} catch {
+		fatal(`Invalid URL: ${url}`)
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { walletResult, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const client = new WalletServerClient(url, walletResult.wallet)
+		const status = await client.accountStatus()
+
+		if (opts.json) {
+			output(status, opts)
+			return
+		}
+
+		console.log()
+		console.log(`  ${bold('Remote:')} ${url}`)
+		console.log(`  ${bold('Identity:')} ${status.identityKey}`)
+		console.log(
+			`  ${bold('Accounts:')} ${status.accountsEnabled ? 'on' : 'off'}`,
+		)
+		if (status.currentBlock != null) {
+			console.log(`  ${bold('Chain tip:')} block ${status.currentBlock}`)
+		}
+		if (status.usedBytes != null) {
+			console.log(`  ${bold('Used:')} ${formatBytes(status.usedBytes)}`)
+		}
+		if (status.accountsEnabled) {
+			console.log(`  ${bold('Baseline:')} ${formatBytes(status.baselineBytes)}`)
+			console.log(`  ${bold('Paid:')} ${formatBytes(status.paidBytes)}`)
+			console.log(`  ${bold('Capacity:')} ${formatBytes(status.capacityBytes)}`)
+			if (status.deficitBytes > 0) {
+				console.log(
+					`  ${bold('Deficit:')} ${formatBytes(status.deficitBytes)} (next write will trigger 402)`,
+				)
+			}
+			if (status.paidThroughBlock != null) {
+				const remaining = status.paidThroughBlock - status.currentBlock
+				console.log(
+					`  ${bold('Paid through:')} block ${status.paidThroughBlock} (${remaining} blocks left)`,
+				)
+			}
+			console.log(
+				`  ${bold('Pricing:')} ${status.pricing.satsPerUnit} sats per ${formatBytes(status.pricing.purchaseUnitBytes)} over ${status.pricing.durationBlocks} blocks`,
+			)
+		}
+		console.log()
+	} finally {
+		await destroy()
+	}
+}
+
+// ============================================================================
+// remote topup
+// ============================================================================
+
+async function remoteTopup(args: string[], opts: GlobalFlags): Promise<void> {
+	let url: string | undefined
+	let units: number | undefined
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]
+		if (arg === '--units') {
+			const val = args[++i]
+			const parsed = Number(val)
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				fatal(`--units requires a positive integer, got "${val}"`)
+			}
+			units = parsed
+		} else if (!url) {
+			url = arg
+		}
+	}
+
+	const config = loadConfig()
+	url = url ?? config.activeRemote ?? config.backups?.[0]
+	if (!url) {
+		fatal(
+			'No remote URL supplied. Pass one as an argument or configure activeRemote/backups first.',
+		)
+	}
+	try {
+		new URL(url)
+	} catch {
+		fatal(`Invalid URL: ${url}`)
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { walletResult, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await topUpStorage(walletResult.wallet, url, { units })
+
+		if (opts.json) {
+			output(result, opts)
+			return
+		}
+
+		console.log()
+		console.log(`  ${bold('Remote:')} ${url}`)
+		console.log(`  ${bold('Units bought:')} ${result.unitsBought}`)
+		console.log(`  ${bold('Sats paid:')} ${result.satsPaid}`)
+		console.log(`  ${bold('Payment txid:')} ${result.txid}`)
+		if (result.status.accountsEnabled) {
+			console.log()
+			console.log(
+				`  ${bold('New capacity:')} ${formatBytes(result.status.capacityBytes)} (${formatBytes(result.status.usedBytes)} used, ${formatBytes(result.status.deficitBytes)} deficit)`,
+			)
+			if (result.status.paidThroughBlock != null) {
+				const remaining = result.status.paidThroughBlock - result.status.currentBlock
+				console.log(
+					`  ${bold('Paid through:')} block ${result.status.paidThroughBlock} (${remaining} blocks left)`,
+				)
+			}
+		}
+		console.log()
+	} finally {
+		await destroy()
+	}
+}
+
+function formatBytes(n: number): string {
+	if (n < 1024) return `${n} B`
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+	if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`
+	return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`
+}
+
 // ============================================================================
 // Helpers
 // ============================================================================

package/src/commands/serve.ts

@@ -0,0 +1,315 @@
+/**
+ * `1sat serve` command — launch wallet server and/or monitor.
+ *
+ *   1sat serve             Wallet server + monitor daemon
+ *   1sat serve wallet      Wallet server only
+ *   1sat serve monitor     Monitor daemon only
+ *
+ * The server wraps the same wallet instance the CLI uses. Storage, active
+ * remote, and backups all come from `~/.1sat/cli/config.json` via the same
+ * `createNodeWallet` factory `1sat wallet` commands use.
+ *
+ * Server-only settings live under `server.*` in the config:
+ *   1sat config set server.port 8100
+ *   1sat config set server.host 0.0.0.0
+ *   1sat config set server.accounts.enabled true
+ */
+
+import { join } from 'node:path'
+import {
+	type NodeWalletResult,
+	type NodeWalletStorageConfig,
+	createNodeWallet,
+} from '@1sat/wallet-node'
+import { createWalletServer } from '@1sat/wallet-server'
+import type { PrivateKey } from '@bsv/sdk'
+import type { GlobalFlags } from '../args'
+import {
+	type ServerAccountsConfig,
+	type ServerStorageConfig,
+	loadConfig,
+} from '../config'
+import { ensureDataDir } from '../config'
+import { printCommandHelp } from '../help'
+import { loadKey, resolvePassword } from '../keys'
+import { clearMonitorPid, writeMonitorPid } from '../monitor-lock'
+import { fatal } from '../output'
+
+const DEFAULT_HOST = '127.0.0.1'
+const DEFAULT_PORT = 8100
+const DEFAULT_ONESAT_URL = 'https://api.1sat.app/1sat'
+const DEFAULT_BASELINE_BYTES = 1024 * 1024 * 1024 // 1 GB
+const DEFAULT_PURCHASE_UNIT_BYTES = 1_073_741_824 // 1 GB chunks for production
+const DEFAULT_SATS_PER_UNIT = 1_000_000
+const DEFAULT_DURATION_BLOCKS = 4383
+const DEFAULT_STORAGE_IDENTITY_KEY = '1sat-cli-default'
+
+type ServeMode = 'all' | 'wallet' | 'monitor'
+
+interface ResolvedServe {
+	chain: 'main' | 'test'
+	host: string
+	port: number
+	onesatURL: string
+	storage: ServerStorageConfig
+	dataDir: string
+	sqliteFilename: string
+	storageIdentityKey: string
+	activeRemote?: string
+	backups?: string[]
+	accounts: ResolvedAccounts
+	privateKey: PrivateKey
+}
+
+interface ResolvedAccounts {
+	enabled: boolean
+	baselineBytes: number
+	purchaseUnitBytes: number
+	satsPerUnit: number
+	durationBlocks: number
+	freeIdentityKeys: string[]
+}
+
+export async function handleServeCommand(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const [subcommand] = args
+	const mode = resolveMode(subcommand)
+
+	if (mode === null) {
+		printCommandHelp('serve', {
+			'(no subcommand)': 'Wallet server plus monitor daemon',
+			wallet: 'Wallet server only',
+			monitor: 'Monitor daemon only',
+		})
+		if (subcommand && subcommand !== 'help') process.exit(1)
+		return
+	}
+
+	const resolved = await resolveServe(opts)
+	const handles: Stoppable[] = []
+
+	try {
+		handles.push(await runWithStorage(resolved, mode))
+		await waitForShutdown()
+	} finally {
+		for (const h of handles.reverse()) {
+			try {
+				await h.stop()
+			} catch (err) {
+				console.error(`Error during shutdown: ${(err as Error).message}`)
+			}
+		}
+	}
+}
+
+function resolveMode(subcommand: string | undefined): ServeMode | null {
+	if (!subcommand) return 'all'
+	switch (subcommand) {
+		case 'wallet':
+		case 'monitor':
+			return subcommand
+		default:
+			return null
+	}
+}
+
+/**
+ * Load the CLI config, apply serve defaults, and resolve the server identity
+ * key via the existing keyring mechanism.
+ */
+async function resolveServe(opts: GlobalFlags): Promise<ResolvedServe> {
+	const config = loadConfig()
+	const server = config.server ?? {}
+
+	const storage: ServerStorageConfig = server.storage ?? {
+		provider: 'bun-sqlite',
+	}
+	if (storage.provider === 'knex-pg' && !storage.dbUrl) {
+		fatal(
+			'server.storage.provider is knex-pg but server.storage.dbUrl is not set. ' +
+				'Set it with: 1sat config set server.storage.dbUrl postgres://…',
+		)
+	}
+
+	const dataDir = ensureDataDir()
+	const chain = opts.chain ?? config.chain ?? 'main'
+
+	let privateKey: PrivateKey
+	try {
+		privateKey = await loadKey(resolvePassword())
+	} catch (err) {
+		fatal((err as Error).message)
+	}
+
+	return {
+		chain,
+		host: server.host ?? DEFAULT_HOST,
+		port: server.port ?? DEFAULT_PORT,
+		onesatURL: DEFAULT_ONESAT_URL,
+		storage,
+		dataDir,
+		sqliteFilename: deriveSqliteFilename(dataDir, chain),
+		storageIdentityKey:
+			config.storageIdentityKey ?? DEFAULT_STORAGE_IDENTITY_KEY,
+		activeRemote: config.activeRemote,
+		backups: config.backups,
+		accounts: resolveAccounts(server.accounts),
+		privateKey,
+	}
+}
+
+function deriveSqliteFilename(dataDir: string, chain: string): string {
+	return join(dataDir, `wallet-${chain}.db`)
+}
+
+function resolveWalletStorageConfig(
+	resolved: ResolvedServe,
+): NodeWalletStorageConfig {
+	const storage = resolved.storage
+	if (storage.provider === 'bun-sqlite') {
+		return { provider: 'bun-sqlite', filename: resolved.sqliteFilename }
+	}
+	if (storage.provider === 'knex-pg') {
+		return { provider: 'knex-pg', dbUrl: storage.dbUrl }
+	}
+	fatal(
+		`server.storage.provider '${storage.provider}' is not supported. Use 'bun-sqlite' or 'knex-pg'.`,
+	)
+}
+
+function resolveAccounts(accounts?: ServerAccountsConfig): ResolvedAccounts {
+	return {
+		enabled: accounts?.enabled ?? false,
+		baselineBytes: accounts?.baselineBytes ?? DEFAULT_BASELINE_BYTES,
+		purchaseUnitBytes:
+			accounts?.purchaseUnitBytes ?? DEFAULT_PURCHASE_UNIT_BYTES,
+		satsPerUnit: accounts?.satsPerUnit ?? DEFAULT_SATS_PER_UNIT,
+		durationBlocks: accounts?.durationBlocks ?? DEFAULT_DURATION_BLOCKS,
+		freeIdentityKeys: accounts?.freeIdentityKeys ?? [],
+	}
+}
+
+interface Stoppable {
+	stop(): Promise<void>
+}
+
+/**
+ * Construct the wallet via the same `createNodeWallet` factory the CLI
+ * uses, with storage provider (bun-sqlite / knex-pg) chosen from config.
+ * Server + monitor operate on that single wallet instance, so
+ * `activeRemote`, `backups`, and `storageIdentityKey` behave identically
+ * to `1sat wallet <command>`.
+ */
+async function runWithStorage(
+	resolved: ResolvedServe,
+	mode: ServeMode,
+): Promise<Stoppable> {
+	const storage = resolveWalletStorageConfig(resolved)
+	const walletResult = await createNodeWallet({
+		privateKey: resolved.privateKey,
+		chain: resolved.chain,
+		storageIdentityKey: resolved.storageIdentityKey,
+		storage,
+		activeRemote: resolved.activeRemote,
+		backups: resolved.backups,
+		// Server owns the monitor loop; suppress the factory's initial
+		// runOnce so CLI invocations in the same data dir don't race with it.
+		skipInitialMonitor: mode !== 'wallet',
+	})
+
+	const accounts =
+		mode === 'monitor'
+			? undefined
+			: await buildAccountsForServer(resolved, walletResult)
+
+	const serverHandle =
+		mode === 'monitor'
+			? undefined
+			: await startWalletServer(resolved, walletResult, accounts)
+
+	if (mode !== 'wallet') {
+		// startTasks loops until stopTasks flips its flag. Fire without
+		// awaiting so the caller can install shutdown handlers and write
+		// the monitor pid file.
+		walletResult.monitor.startTasks().catch((err: unknown) => {
+			console.error('[monitor] task loop exited:', err)
+		})
+		writeMonitorPid(resolved.dataDir)
+		console.log('[monitor] started')
+	}
+
+	return {
+		async stop() {
+			if (mode !== 'wallet') {
+				walletResult.monitor.stopTasks()
+				clearMonitorPid(resolved.dataDir)
+			}
+			if (serverHandle) await serverHandle.stop()
+			// Accounts shares the wallet's connection — walletResult.destroy
+			// below closes it. No separate teardown needed.
+			await walletResult.destroy()
+		},
+	}
+}
+
+async function startWalletServer(
+	resolved: ResolvedServe,
+	walletResult: NodeWalletResult,
+	accounts: AccountsRuntime | undefined,
+): Promise<{ stop(): Promise<void> }> {
+	const handle = createWalletServer({
+		wallet: walletResult.wallet,
+		storage: walletResult.getActiveStorage(),
+		serverIdentityKey: walletResult.wallet.identityKey,
+		listen: { port: resolved.port, host: resolved.host },
+		publicPath: '/',
+		internalPath: null,
+		accounts: accounts?.walletServerAccounts,
+	})
+	const port = await handle.start()
+	const accountsNote = resolved.accounts.enabled ? ' (accounts: on)' : ''
+	console.log(`[wallet] listening on ${resolved.host}:${port}${accountsNote}`)
+	return { stop: () => handle.stop() }
+}
+
+interface AccountsRuntime {
+	walletServerAccounts: NonNullable<
+		Parameters<typeof createWalletServer>[0]['accounts']
+	>
+}
+
+async function buildAccountsForServer(
+	resolved: ResolvedServe,
+	walletResult: NodeWalletResult,
+): Promise<AccountsRuntime | undefined> {
+	// When the wallet is remote-primary the server is fronting someone else's
+	// storage; accounts semantics don't apply.
+	if (resolved.activeRemote) return undefined
+
+	return {
+		walletServerAccounts: {
+			config: {
+				enabled: resolved.accounts.enabled,
+				baselineBytes: resolved.accounts.baselineBytes,
+				purchaseUnitBytes: resolved.accounts.purchaseUnitBytes,
+				satsPerUnit: resolved.accounts.satsPerUnit,
+				durationBlocks: resolved.accounts.durationBlocks,
+				freeIdentityKeys: resolved.accounts.freeIdentityKeys,
+			},
+			currentBlock: () => walletResult.services.chaintracks.currentHeight(),
+		},
+	}
+}
+
+function waitForShutdown(): Promise<void> {
+	return new Promise((resolve) => {
+		const handler = (sig: string) => {
+			console.log(`Received ${sig}, shutting down...`)
+			resolve()
+		}
+		process.once('SIGINT', () => handler('SIGINT'))
+		process.once('SIGTERM', () => handler('SIGTERM'))
+	})
+}

package/src/config.ts

@@ -11,6 +11,46 @@ import { join } from 'node:path'
 const CONFIG_DIR = join(homedir(), '.1sat', 'cli')
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json')
 
+export interface ServerStorageBunSqliteConfig {
+	provider: 'bun-sqlite'
+}
+
+export interface ServerStorageKnexPgConfig {
+	provider: 'knex-pg'
+	/** Postgres connection URL (required for knex-pg). */
+	dbUrl: string
+}
+
+export type ServerStorageConfig =
+	| ServerStorageBunSqliteConfig
+	| ServerStorageKnexPgConfig
+
+export interface ServerAccountsConfig {
+	/** Master toggle. Defaults to false when omitted. */
+	enabled?: boolean
+	/** Free baseline per identity key, in bytes. */
+	baselineBytes?: number
+	/** Purchase chunk size in bytes. Deficits round up to whole chunks. Defaults to 1 GB. */
+	purchaseUnitBytes?: number
+	/** Sats charged per purchase unit. */
+	satsPerUnit?: number
+	/** Block window a payment remains valid for. */
+	durationBlocks?: number
+	/** Identity keys that bypass metering (server's own key is auto-added). */
+	freeIdentityKeys?: string[]
+}
+
+export interface ServerConfig {
+	/** Hostname to bind. Defaults to `127.0.0.1`. */
+	host?: string
+	/** Port to bind. Defaults to `8100`. */
+	port?: number
+	/** Storage backend. Defaults to `{ provider: 'bun-sqlite' }`. */
+	storage?: ServerStorageConfig
+	/** Optional account/metering layer (opt-in per-deployment). */
+	accounts?: ServerAccountsConfig
+}
+
 export interface OneSatCliConfig {
 	/** Network: mainnet or testnet */
 	chain: 'main' | 'test'
@@ -22,6 +62,8 @@ export interface OneSatCliConfig {
 	backups?: string[]
 	/** Storage identity key for wallet persistence */
 	storageIdentityKey?: string
+	/** Settings read by `1sat serve` subcommands. Absent for client-only installs. */
+	server?: ServerConfig
 }
 
 const DEFAULT_CONFIG: OneSatCliConfig = {
@@ -72,6 +114,66 @@ export function updateConfig(patch: Partial<OneSatCliConfig>): OneSatCliConfig {
 	return next
 }
 
+/**
+ * Set a value at a dotted path inside the config, creating intermediate
+ * objects as needed. `value` is stored as-is; callers are responsible for
+ * type coercion (typically via `parseConfigValue`).
+ */
+export function setConfigPath(path: string, value: unknown): OneSatCliConfig {
+	if (!path) throw new Error('setConfigPath requires a non-empty path')
+	const config = loadConfig() as Record<string, unknown>
+	const segments = path.split('.')
+	let cursor: Record<string, unknown> = config
+	for (let i = 0; i < segments.length - 1; i++) {
+		const key = segments[i]
+		const existing = cursor[key]
+		if (
+			existing == null ||
+			typeof existing !== 'object' ||
+			Array.isArray(existing)
+		) {
+			cursor[key] = {}
+		}
+		cursor = cursor[key] as Record<string, unknown>
+	}
+	cursor[segments[segments.length - 1]] = value
+	saveConfig(config as OneSatCliConfig)
+	return config as OneSatCliConfig
+}
+
+/**
+ * Remove a value at a dotted path. Leaves empty parent objects in place to
+ * keep the file shape explicit.
+ */
+export function unsetConfigPath(path: string): OneSatCliConfig {
+	if (!path) throw new Error('unsetConfigPath requires a non-empty path')
+	const config = loadConfig() as Record<string, unknown>
+	const segments = path.split('.')
+	let cursor: Record<string, unknown> | undefined = config
+	for (let i = 0; i < segments.length - 1; i++) {
+		const next = cursor?.[segments[i]]
+		if (next == null || typeof next !== 'object')
+			return config as OneSatCliConfig
+		cursor = next as Record<string, unknown>
+	}
+	if (cursor) delete cursor[segments[segments.length - 1]]
+	saveConfig(config as OneSatCliConfig)
+	return config as OneSatCliConfig
+}
+
+/**
+ * Parse a raw CLI argument into a typed JSON value. Tries `JSON.parse`
+ * first so numbers, booleans, objects and arrays round-trip naturally;
+ * falls back to the raw string for bare words that aren't valid JSON.
+ */
+export function parseConfigValue(raw: string): unknown {
+	try {
+		return JSON.parse(raw)
+	} catch {
+		return raw
+	}
+}
+
 /**
  * Get the config directory path.
  */

package/src/context.ts

@@ -8,6 +8,7 @@ import { type OneSatContext, createContext } from '@1sat/actions'
 import { type NodeWalletResult, createNodeWallet } from '@1sat/wallet-node'
 import type { PrivateKey } from '@bsv/sdk'
 import { ensureDataDir, loadConfig } from './config'
+import { readLiveMonitorPid } from './monitor-lock'
 
 /** Extended context that includes cleanup */
 export interface CliContext {
@@ -36,13 +37,19 @@ export async function loadContext(
 
 	const storageIdentityKey = config.storageIdentityKey ?? '1sat-cli-default'
 
+	const skipInitialMonitor = readLiveMonitorPid(dataDir) !== undefined
+
 	const walletResult = await createNodeWallet({
 		privateKey,
 		chain: opts.chain,
 		storageIdentityKey,
-		filename: `${dataDir}/wallet-${opts.chain}.db`,
+		storage: {
+			provider: 'bun-sqlite',
+			filename: `${dataDir}/wallet-${opts.chain}.db`,
+		},
 		activeRemote: config.activeRemote,
 		backups: config.backups,
+		skipInitialMonitor,
 	})
 
 	const ctx = createContext(walletResult.wallet, {

package/src/monitor-lock.ts

@@ -0,0 +1,50 @@
+/**
+ * PID lock file coordinating a single monitor owner across CLI invocations
+ * and a long-running `1sat serve` process.
+ *
+ * - `1sat serve` (modes that run the monitor) writes the pid on startup and
+ *   removes it on clean shutdown.
+ * - CLI invocations read the file and, if the pid is alive, skip firing
+ *   their own `monitor.runOnce()` to avoid duplicate work against the same
+ *   SQLite file.
+ */
+
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const MONITOR_PID_FILENAME = 'monitor.pid'
+
+export function monitorPidPath(dataDir: string): string {
+	return join(dataDir, MONITOR_PID_FILENAME)
+}
+
+export function writeMonitorPid(
+	dataDir: string,
+	pid: number = process.pid,
+): void {
+	writeFileSync(monitorPidPath(dataDir), `${pid}\n`, 'utf8')
+}
+
+export function clearMonitorPid(dataDir: string): void {
+	try {
+		unlinkSync(monitorPidPath(dataDir))
+	} catch {}
+}
+
+/** Returns the pid of a live monitor owner, or undefined if none. */
+export function readLiveMonitorPid(dataDir: string): number | undefined {
+	let raw: string
+	try {
+		raw = readFileSync(monitorPidPath(dataDir), 'utf8')
+	} catch {
+		return undefined
+	}
+	const pid = Number.parseInt(raw.trim(), 10)
+	if (!Number.isInteger(pid) || pid <= 0) return undefined
+	try {
+		process.kill(pid, 0)
+		return pid
+	} catch {
+		return undefined
+	}
+}