@1sat/cli 0.0.1

package/src/commands/tx.ts

@@ -0,0 +1,65 @@
+/**
+ * Transaction utility commands - decode.
+ */
+
+import { Transaction } from '@bsv/sdk'
+import type { GlobalFlags } from '../args'
+import { printCommandHelp } from '../help'
+import { fatal, output } from '../output'
+
+export async function handleTxCommand(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const [subcommand, ...rest] = args
+
+	switch (subcommand) {
+		case 'decode':
+			return txDecode(rest, opts)
+		default:
+			printCommandHelp('tx', {
+				decode: 'Decode a raw transaction hex',
+			})
+			if (subcommand && subcommand !== 'help') {
+				process.exit(1)
+			}
+	}
+}
+
+async function txDecode(args: string[], opts: GlobalFlags): Promise<void> {
+	const hex = args[0]
+
+	if (!hex) fatal('Missing transaction hex. Usage: 1sat tx decode <hex>')
+
+	let tx: Transaction
+	try {
+		tx = Transaction.fromHex(hex)
+	} catch (e) {
+		fatal(
+			`Failed to decode transaction: ${e instanceof Error ? e.message : String(e)}`,
+		)
+	}
+
+	const decoded = {
+		txid: tx.id('hex'),
+		version: tx.version,
+		lockTime: tx.lockTime,
+		inputs: tx.inputs.map((input, i) => ({
+			index: i,
+			sourceTXID: input.sourceTXID,
+			sourceOutputIndex: input.sourceOutputIndex,
+			sequence: input.sequence,
+			scriptLength: input.unlockingScript?.toBinary().length ?? 0,
+		})),
+		outputs: tx.outputs.map((out, i) => ({
+			index: i,
+			satoshis: out.satoshis,
+			scriptLength: out.lockingScript.toBinary().length,
+			scriptHex:
+				out.lockingScript.toHex().slice(0, 80) +
+				(out.lockingScript.toHex().length > 80 ? '...' : ''),
+		})),
+	}
+
+	output(decoded, opts)
+}

package/src/commands/wallet.ts

@@ -0,0 +1,218 @@
+/**
+ * Wallet commands - balance, address, send, send-all, info.
+ */
+
+import { deriveDepositAddresses, sendAllBsv, sendBsv } from '@1sat/actions'
+import { confirm, isCancel } from '@clack/prompts'
+import type { GlobalFlags } from '../args'
+import { extractFlag } from '../args'
+import { loadContext } from '../context'
+import { printCommandHelp } from '../help'
+import { loadKey, resolvePassword } from '../keys'
+import { fatal, formatValue, output, printKeyValue } from '../output'
+
+export async function handleWalletCommand(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const [subcommand, ...rest] = args
+
+	switch (subcommand) {
+		case 'balance':
+			return walletBalance(rest, opts)
+		case 'address':
+			return walletAddress(rest, opts)
+		case 'send':
+			return walletSend(rest, opts)
+		case 'send-all':
+			return walletSendAll(rest, opts)
+		case 'info':
+			return walletInfo(rest, opts)
+		default:
+			printCommandHelp('wallet', {
+				balance: 'Show wallet balance in satoshis',
+				address: 'Show deposit address',
+				send: 'Send BSV to an address (--to <addr> --sats <amount>)',
+				'send-all': 'Send all BSV to an address (--to <addr>)',
+				info: 'Show wallet info (address, balance, network)',
+			})
+			if (subcommand && subcommand !== 'help') {
+				process.exit(1)
+			}
+	}
+}
+
+async function walletBalance(
+	_args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await ctx.wallet.listOutputs({
+			basket: 'default',
+			include: 'locking scripts',
+			limit: 10000,
+		})
+
+		const totalSatoshis = result.outputs.reduce((sum, o) => sum + o.satoshis, 0)
+
+		output(
+			opts.json
+				? { satoshis: totalSatoshis, utxos: result.outputs.length }
+				: `${formatValue(totalSatoshis)} satoshis (${result.outputs.length} UTXOs)`,
+			opts,
+		)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletAddress(
+	_args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await deriveDepositAddresses.execute(ctx, {
+			prefix: '1sat',
+			count: 1,
+		})
+
+		const primary = result.derivations[0]
+		if (!primary) {
+			fatal('Failed to derive deposit address')
+		}
+
+		output(opts.json ? primary : primary.address, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletSend(args: string[], opts: GlobalFlags): Promise<void> {
+	const to = extractFlag(args, '--to')
+	const satsStr = extractFlag(args, '--sats')
+
+	if (!to) fatal('Missing --to <address>')
+	if (!satsStr) fatal('Missing --sats <amount>')
+
+	const satoshis = Number(satsStr)
+	if (!Number.isFinite(satoshis) || satoshis <= 0) {
+		fatal('--sats must be a positive number')
+	}
+
+	if (!opts.yes) {
+		const ok = await confirm({
+			message: `Send ${satoshis} satoshis to ${to}?`,
+		})
+		if (isCancel(ok) || !ok) {
+			fatal('Send cancelled.')
+		}
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await sendBsv.execute(ctx, {
+			requests: [{ address: to, satoshis }],
+		})
+
+		if (result.error) {
+			fatal(result.error)
+		}
+
+		output(opts.json ? result : { txid: result.txid }, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletSendAll(args: string[], opts: GlobalFlags): Promise<void> {
+	const to = extractFlag(args, '--to')
+
+	if (!to) fatal('Missing --to <address>')
+
+	if (!opts.yes) {
+		const ok = await confirm({
+			message: `Send ALL BSV to ${to}? This will empty your wallet.`,
+		})
+		if (isCancel(ok) || !ok) {
+			fatal('Send cancelled.')
+		}
+	}
+
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const result = await sendAllBsv.execute(ctx, { destination: to })
+
+		if (result.error) {
+			fatal(result.error)
+		}
+
+		output(opts.json ? result : { txid: result.txid }, opts)
+	} finally {
+		await destroy()
+	}
+}
+
+async function walletInfo(_args: string[], opts: GlobalFlags): Promise<void> {
+	const privateKey = await loadKey(resolvePassword())
+	const { ctx, destroy } = await loadContext(privateKey, {
+		chain: opts.chain,
+	})
+
+	try {
+		const [addressResult, balanceResult, identityResult] = await Promise.all([
+			deriveDepositAddresses.execute(ctx, { prefix: '1sat', count: 1 }),
+			ctx.wallet.listOutputs({
+				basket: 'default',
+				include: 'locking scripts',
+				limit: 10000,
+			}),
+			ctx.wallet.getPublicKey({ identityKey: true }),
+		])
+
+		const address = addressResult.derivations[0]?.address ?? 'unknown'
+		const totalSatoshis = balanceResult.outputs.reduce(
+			(sum, o) => sum + o.satoshis,
+			0,
+		)
+
+		const info = {
+			chain: opts.chain,
+			address,
+			identityKey: identityResult.publicKey,
+			balance: totalSatoshis,
+			utxos: balanceResult.outputs.length,
+		}
+
+		if (opts.json) {
+			output(info, opts)
+		} else {
+			printKeyValue({
+				Chain: info.chain,
+				Address: info.address,
+				'Identity Key': info.identityKey,
+				'Balance (sats)': info.balance,
+				UTXOs: info.utxos,
+			})
+		}
+	} finally {
+		await destroy()
+	}
+}

package/src/config.ts

@@ -0,0 +1,97 @@
+/**
+ * Config management for ~/.1sat/
+ *
+ * Handles persistent configuration on disk with secure file permissions.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const CONFIG_DIR = join(homedir(), '.1sat')
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json')
+
+export interface OneSatCliConfig {
+	/** Network: mainnet or testnet */
+	chain: 'main' | 'test'
+	/** Data directory for wallet databases */
+	dataDir: string
+	/** Remote storage URL for wallet backup */
+	remoteStorageUrl?: string
+	/** Storage identity key for wallet persistence */
+	storageIdentityKey?: string
+}
+
+const DEFAULT_CONFIG: OneSatCliConfig = {
+	chain: 'main',
+	dataDir: join(CONFIG_DIR, 'data'),
+}
+
+/**
+ * Ensure ~/.1sat/ exists with secure permissions.
+ */
+export function ensureConfigDir(): void {
+	if (!existsSync(CONFIG_DIR)) {
+		mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 })
+	}
+}
+
+/**
+ * Load config from disk. Returns defaults if file doesn't exist.
+ */
+export function loadConfig(): OneSatCliConfig {
+	if (!existsSync(CONFIG_FILE)) return { ...DEFAULT_CONFIG }
+	try {
+		const raw = readFileSync(CONFIG_FILE, 'utf8')
+		const parsed = JSON.parse(raw)
+		return { ...DEFAULT_CONFIG, ...parsed }
+	} catch {
+		return { ...DEFAULT_CONFIG }
+	}
+}
+
+/**
+ * Save config to disk with secure permissions.
+ */
+export function saveConfig(config: OneSatCliConfig): void {
+	ensureConfigDir()
+	writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {
+		mode: 0o600,
+	})
+}
+
+/**
+ * Update specific config fields, preserving the rest.
+ */
+export function updateConfig(patch: Partial<OneSatCliConfig>): OneSatCliConfig {
+	const config = loadConfig()
+	const next = { ...config, ...patch }
+	saveConfig(next)
+	return next
+}
+
+/**
+ * Get the config directory path.
+ */
+export function getConfigDir(): string {
+	return CONFIG_DIR
+}
+
+/**
+ * Get the config file path.
+ */
+export function getConfigFile(): string {
+	return CONFIG_FILE
+}
+
+/**
+ * Get the data directory, ensuring it exists.
+ */
+export function ensureDataDir(): string {
+	const config = loadConfig()
+	const dataDir = config.dataDir
+	if (!existsSync(dataDir)) {
+		mkdirSync(dataDir, { recursive: true, mode: 0o700 })
+	}
+	return dataDir
+}

package/src/context.ts

@@ -0,0 +1,63 @@
+/**
+ * OneSatContext factory for CLI commands.
+ *
+ * Creates a fully initialized wallet context with services and monitor.
+ */
+
+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'
+
+/** Extended context that includes cleanup */
+export interface CliContext {
+	ctx: OneSatContext
+	walletResult: NodeWalletResult
+	destroy: () => Promise<void>
+}
+
+/**
+ * Create a fully initialized OneSatContext for CLI use.
+ *
+ * Sets up:
+ * - Node wallet with SQLite storage
+ * - 1Sat services for API access
+ * - Monitor for transaction lifecycle
+ */
+export async function loadContext(
+	privateKey: PrivateKey,
+	opts: { chain: 'main' | 'test' },
+): Promise<CliContext> {
+	const config = loadConfig()
+	const dataDir = ensureDataDir()
+
+	const storageIdentityKey = config.storageIdentityKey ?? '1sat-cli-default'
+
+	const walletResult = await createNodeWallet({
+		privateKey,
+		chain: opts.chain,
+		storageIdentityKey,
+		storage: {
+			client: 'better-sqlite3',
+			connection: {
+				filename: `${dataDir}/wallet-${opts.chain}.db`,
+			},
+			useNullAsDefault: true,
+		},
+		remoteStorageUrl: config.remoteStorageUrl,
+	})
+
+	walletResult.monitor.startTasks()
+
+	const ctx = createContext(walletResult.wallet, {
+		services: walletResult.services,
+		chain: opts.chain,
+		dataDir,
+	})
+
+	return {
+		ctx,
+		walletResult,
+		destroy: walletResult.destroy,
+	}
+}

package/src/help.ts

@@ -0,0 +1,117 @@
+/**
+ * Help text and version display for the 1sat CLI.
+ */
+
+import { readFileSync } from 'node:fs'
+import chalk from 'chalk'
+
+export function getVersion(): string {
+	try {
+		const pkg = JSON.parse(
+			readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+		)
+		return pkg.version || 'unknown'
+	} catch {
+		return 'unknown'
+	}
+}
+
+export function printVersion(): void {
+	console.log(`1sat ${getVersion()}`)
+}
+
+export function printHelp(): void {
+	const dim = chalk.dim
+	const cyan = chalk.cyan
+	const bold = chalk.bold
+
+	console.log(`
+${bold('1sat')} - CLI for 1Sat Ordinals SDK
+
+${bold('Usage:')}
+  1sat <command> [subcommand] [options]
+
+${bold('Setup:')}
+  ${cyan('init')}                     Interactive wallet setup wizard
+  ${cyan('config')} <subcommand>      Manage configuration
+
+${bold('Wallet:')}
+  ${cyan('wallet balance')}           Show wallet balance
+  ${cyan('wallet address')}           Show deposit address
+  ${cyan('wallet send')}              Send BSV to an address
+  ${cyan('wallet send-all')}          Send all BSV to an address
+  ${cyan('wallet info')}              Show wallet info
+
+${bold('Ordinals:')}
+  ${cyan('ordinals list')}            List owned ordinals
+  ${cyan('ordinals mint')}            Mint a new ordinal inscription
+  ${cyan('ordinals transfer')}        Transfer an ordinal
+  ${cyan('ordinals sell')}            List an ordinal for sale
+  ${cyan('ordinals cancel')}          Cancel an ordinal listing
+  ${cyan('ordinals buy')}             Purchase a listed ordinal
+
+${bold('Tokens (BSV21):')}
+  ${cyan('tokens balances')}          Show token balances
+  ${cyan('tokens list')}              List owned token UTXOs
+  ${cyan('tokens send')}              Transfer tokens
+  ${cyan('tokens deploy')}            Deploy a new BSV21 token
+  ${cyan('tokens buy')}               Purchase listed tokens
+
+${bold('Locks:')}
+  ${cyan('locks info')}               Show lock information
+  ${cyan('locks lock')}               Time-lock BSV
+  ${cyan('locks unlock')}             Unlock matured BSV
+
+${bold('Identity (BAP):')}
+  ${cyan('identity create')}          Create a new BAP identity
+  ${cyan('identity info')}            Show identity information
+  ${cyan('identity sign')}            Sign a message with identity key
+  ${cyan('identity verify')}          Verify a signed message
+
+${bold('Social:')}
+  ${cyan('social post')}              Create an on-chain social post
+
+${bold('OpNS:')}
+  ${cyan('opns register')}            Register identity on OpNS name
+  ${cyan('opns deregister')}          Deregister identity from OpNS name
+  ${cyan('opns lookup')}              Look up an OpNS name
+
+${bold('Sweep:')}
+  ${cyan('sweep scan')}               Scan an address for UTXOs
+  ${cyan('sweep import')}             Import UTXOs into wallet
+
+${bold('Advanced:')}
+  ${cyan('action')} <name> [json]     Execute a registered action by name
+  ${cyan('tx decode')} <hex>          Decode a raw transaction
+
+${bold('Global Options:')}
+  ${dim('--json')}                   Output as JSON
+  ${dim('--quiet, -q')}              Suppress output
+  ${dim('--yes, -y')}                Skip confirmations
+  ${dim('--chain <main|test>')}      Network (default: main)
+  ${dim('--help, -h')}               Show help
+  ${dim('--version, -v')}            Show version
+
+${bold('Environment Variables:')}
+  ${dim('PRIVATE_KEY_WIF')}          Private key (bypasses encrypted keyfile)
+  ${dim('ONESAT_PASSWORD')}          Password for encrypted keyfile
+
+${bold('Config:')} ~/.1sat/
+`)
+}
+
+export function printCommandHelp(
+	command: string,
+	subcommands: Record<string, string>,
+): void {
+	const bold = chalk.bold
+	const cyan = chalk.cyan
+	const dim = chalk.dim
+
+	console.log(`\n${bold(`1sat ${command}`)}`)
+	console.log(`\n${bold('Subcommands:')}`)
+	for (const [sub, desc] of Object.entries(subcommands)) {
+		console.log(`  ${cyan(sub.padEnd(20))} ${dim(desc)}`)
+	}
+	console.log()
+}

package/src/keys.ts

@@ -0,0 +1,88 @@
+/**
+ * Encrypted key management for the 1sat CLI.
+ *
+ * Key resolution priority:
+ * 1. PRIVATE_KEY_WIF env var
+ * 2. ~/.1sat/keys.bep encrypted file
+ * 3. Fail with "Run 1sat init"
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PrivateKey } from '@bsv/sdk'
+import { type WifBackup, decryptBackup, encryptBackup } from 'bitcoin-backup'
+import { ensureConfigDir, getConfigDir } from './config'
+
+const KEYS_FILE = 'keys.bep'
+
+function getKeysPath(): string {
+	return join(getConfigDir(), KEYS_FILE)
+}
+
+/**
+ * Check if a key is available (env var or encrypted file).
+ */
+export function hasKey(): boolean {
+	if (process.env.PRIVATE_KEY_WIF) return true
+	return existsSync(getKeysPath())
+}
+
+/**
+ * Load the private key from env or encrypted file.
+ *
+ * @param password - Required if loading from encrypted file
+ */
+export async function loadKey(password?: string): Promise<PrivateKey> {
+	// Priority 1: Environment variable
+	const envWif = process.env.PRIVATE_KEY_WIF
+	if (envWif) {
+		return PrivateKey.fromWif(envWif)
+	}
+
+	// Priority 2: Encrypted file
+	const keysPath = getKeysPath()
+	if (!existsSync(keysPath)) {
+		throw new Error(
+			'No key found. Run "1sat init" to set up your wallet, or set PRIVATE_KEY_WIF.',
+		)
+	}
+
+	if (!password) {
+		throw new Error(
+			'Password required to decrypt key file. Pass --password or set ONESAT_PASSWORD.',
+		)
+	}
+
+	const encrypted = readFileSync(keysPath, 'utf8')
+	const backup = await decryptBackup(encrypted, password)
+	if (!('wif' in backup) || typeof backup.wif !== 'string') {
+		throw new Error('Key file does not contain a WIF key.')
+	}
+	return PrivateKey.fromWif(backup.wif)
+}
+
+/**
+ * Save a WIF-encoded private key to encrypted file.
+ */
+export async function saveKey(wif: string, password: string): Promise<void> {
+	ensureConfigDir()
+
+	// Validate the WIF before saving
+	PrivateKey.fromWif(wif)
+
+	const payload: WifBackup = {
+		wif,
+		label: '1sat-cli',
+		createdAt: new Date().toISOString(),
+	}
+	const encrypted = await encryptBackup(payload, password)
+	const keysPath = getKeysPath()
+	writeFileSync(keysPath, encrypted, { mode: 0o600 })
+}
+
+/**
+ * Resolve a password from flag or environment variable.
+ */
+export function resolvePassword(flagValue?: string): string | undefined {
+	return flagValue ?? process.env.ONESAT_PASSWORD
+}