@obbyx/obyte 0.0.0-stage → 0.1.0

package/src/signing/signed-message.ts

@@ -0,0 +1,147 @@
+// Ambient types for obyte.js internals; a reference (not tsconfig "include") so that
+// workspace packages compiling these sources via the @obbyx/source condition see them.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../types/obyte-internal.d.ts" />
+import obyte from 'obyte';
+import { getSignedPackageHashToSign, verify } from 'obyte/lib/internal.js';
+import { isAddress } from '../channel/definition.js';
+import type { ObyteNetwork } from '../core/networks.js';
+import { type Verdict, accept, hasOnlyKeys, isPlainObject, reject } from '../core/result.js';
+
+/**
+ * Obyte signed messages ("signed packages") as used by AA payment channels.
+ *
+ * Supported profile (same as aa-channels-lib's light verifier, plus network
+ * binding): exactly one author, an embedded `['sig', {pubkey}]` definition
+ * whose chash equals the author address, signature under path `r`, and a
+ * `version` that belongs to the expected network (testnet versions end in
+ * `t`) — so a package can never be accepted on the other network (I4).
+ *
+ * Packages are signed with obyte.js directly:
+ * `obyte.utils.signMessage(message, { privateKey, testnet })`.
+ */
+export type SigDefinition = readonly ['sig', { readonly pubkey: string }];
+
+export interface SignedPackage<M = unknown> {
+  version: string;
+  signed_message: M;
+  authors: [
+    {
+      address: string;
+      definition: SigDefinition;
+      authentifiers: { r: string };
+    },
+  ];
+}
+
+export interface VerifiedPackage<M = unknown> {
+  readonly signer: string;
+  readonly pubkey: string;
+  readonly message: M;
+}
+
+export const SIGNED_PACKAGE_VERSIONS = {
+  livenet: ['1.0', '2.0', '3.0', '4.0'],
+  testnet: ['1.0t', '2.0t', '3.0t', '4.0t'],
+} as const;
+
+const PACKAGE_KEYS = new Set([
+  'signed_message',
+  'authors',
+  'last_ball_unit',
+  'timestamp',
+  'version',
+]);
+const AUTHOR_KEYS = new Set(['address', 'definition', 'authentifiers']);
+
+export function verifySignedPackage<M = unknown>(
+  pkg: unknown,
+  options: { network: ObyteNetwork; expectedSigner?: string },
+): Verdict<VerifiedPackage<M>> {
+  if (!isPlainObject(pkg)) return reject('invalid_signed_package', 'Package must be an object');
+  if (!hasOnlyKeys(pkg, PACKAGE_KEYS)) {
+    return reject('invalid_signed_package', 'Package has unexpected fields');
+  }
+  if (!('signed_message' in pkg)) {
+    return reject('invalid_signed_package', 'Package has no signed_message');
+  }
+  const versions: readonly string[] = SIGNED_PACKAGE_VERSIONS[options.network.name];
+  if (typeof pkg['version'] !== 'string' || !versions.includes(pkg['version'])) {
+    return reject(
+      'invalid_signed_package_network',
+      `Package version is not valid for ${options.network.caip2}`,
+    );
+  }
+
+  const authors = pkg['authors'];
+  if (!Array.isArray(authors) || authors.length !== 1) {
+    return reject('invalid_signed_package', 'Package must have exactly one author');
+  }
+  const author: unknown = authors[0];
+  if (!isPlainObject(author) || !hasOnlyKeys(author, AUTHOR_KEYS)) {
+    return reject('invalid_signed_package', 'Malformed author');
+  }
+  const address = author['address'];
+  if (!isAddress(address)) return reject('invalid_signed_package', 'Invalid author address');
+  if (options.expectedSigner !== undefined && address !== options.expectedSigner) {
+    return reject('invalid_signed_package_signer', 'Package is signed by an unexpected address');
+  }
+
+  const definition = author['definition'];
+  if (!isSigDefinition(definition)) {
+    return reject(
+      'invalid_signed_package_definition',
+      "Only ['sig', {pubkey}] definitions are supported",
+    );
+  }
+  let chash: string;
+  try {
+    chash = obyte.utils.getChash160([...definition]);
+  } catch {
+    return reject('invalid_signed_package_definition', 'Definition cannot be hashed');
+  }
+  if (chash !== address) {
+    return reject('invalid_signed_package_definition', 'Definition does not match author address');
+  }
+
+  const authentifiers = author['authentifiers'];
+  if (!isPlainObject(authentifiers) || Object.keys(authentifiers).length !== 1) {
+    return reject('invalid_signed_package_signature', 'Expected a single authentifier "r"');
+  }
+  let hash: Uint8Array;
+  try {
+    hash = getSignedPackageHashToSign(pkg);
+  } catch {
+    return reject('invalid_signed_package', 'Package cannot be hashed');
+  }
+  if (!verifySignature(hash, authentifiers['r'], definition[1].pubkey)) {
+    return reject('invalid_signed_package_signature', 'Signature is invalid');
+  }
+
+  return accept({
+    signer: address,
+    pubkey: definition[1].pubkey,
+    message: pkg['signed_message'] as M,
+  });
+}
+
+export function isSigDefinition(value: unknown): value is SigDefinition {
+  if (!Array.isArray(value) || value.length !== 2 || value[0] !== 'sig') return false;
+  const params: unknown = value[1];
+  return (
+    isPlainObject(params) &&
+    Object.keys(params).length === 1 &&
+    typeof params['pubkey'] === 'string' &&
+    params['pubkey'].length === 44
+  );
+}
+
+/** secp256k1 verification that never throws on malformed input. */
+export function verifySignature(hash: Uint8Array, signature: unknown, pubkey: string): boolean {
+  if (typeof signature !== 'string') return false;
+  try {
+    return verify(hash, signature, pubkey);
+  } catch {
+    return false;
+  }
+}

package/src/types/obyte-internal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Types for obyte.js internals used directly (ADR-0006). obyte.js publishes
+ * types only for its public API; these helpers live in `lib/internal.js`.
+ * The obyte.js version is pinned exactly; conformance tests against testnet
+ * ledger data catch behavioural drift on upgrade.
+ */
+declare module 'obyte/lib/internal.js' {
+  export function getUnitHash(unit: object): string;
+  export function getUnitHashToSign(unit: object): Uint8Array;
+  export function getSignedPackageHashToSign(pkg: object): Uint8Array;
+  export function getBase64Hash(obj: unknown, jsonBased: boolean): string;
+  export function getHeadersSize(unit: object, withKeys: boolean): number;
+  export function getTotalPayloadSize(unit: object, withKeys: boolean): number;
+  export function sign(hash: Uint8Array, privateKey: Uint8Array): string;
+  export function verify(hash: Uint8Array, signature: string, pubkey: string): boolean;
+  export function toPublicKey(privateKey: Uint8Array): string;
+  export function getSourceString(obj: unknown): string;
+  export function chashGetChash160(sourceString: string): string;
+}

package/src/unit/exact-unit.ts

@@ -0,0 +1,388 @@
+// Ambient types for obyte.js internals; a reference (not tsconfig "include") so that
+// workspace packages compiling these sources via the @obbyx/source condition see them.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../types/obyte-internal.d.ts" />
+import obyte from 'obyte';
+import {
+  getBase64Hash,
+  getHeadersSize,
+  getTotalPayloadSize,
+  getUnitHash,
+  getUnitHashToSign,
+} from 'obyte/lib/internal.js';
+import { isAddress, isAssetId } from '../channel/definition.js';
+import type { ObyteNetwork } from '../core/networks.js';
+import { type Verdict, accept, hasOnlyKeys, isPlainObject, reject } from '../core/result.js';
+import { type SigDefinition, isSigDefinition, verifySignature } from '../signing/signed-message.js';
+
+/**
+ * Local (ledger-independent) validation of a client-signed unit for the x402
+ * `exact` scheme — the supported profile of ADR-0002.
+ *
+ * Checks done here need no hub: structure, network, unit hash, payload hashes,
+ * author definition and signature, commissions, message set, outputs and the
+ * signed binding. Ledger checks (inputs unspent, last ball recency, author
+ * definition when not embedded) are performed by the facilitator with a
+ * LedgerPort using {@link ExactUnitFacts}.
+ *
+ * Anything outside the profile is rejected; the profile is deliberately narrow.
+ */
+
+export const EXACT_REASONS = {
+  unsupported: 'invalid_exact_obyte_unsupported_unit',
+  tooLarge: 'invalid_exact_obyte_unit_too_large',
+  network: 'invalid_exact_obyte_network',
+  unitHash: 'invalid_exact_obyte_unit_hash',
+  payloadHash: 'invalid_exact_obyte_payload_hash',
+  definition: 'invalid_exact_obyte_definition',
+  definitionRequired: 'invalid_exact_obyte_definition_required',
+  signature: 'invalid_exact_obyte_signature',
+  commissions: 'invalid_exact_obyte_commissions',
+  recipient: 'invalid_exact_obyte_recipient_mismatch',
+  amount: 'invalid_exact_obyte_amount_mismatch',
+  asset: 'invalid_exact_obyte_asset_mismatch',
+  binding: 'invalid_exact_obyte_binding_mismatch',
+  payer: 'invalid_exact_obyte_payer',
+} as const;
+
+/** Only current unit versions are accepted. */
+export const EXACT_UNIT_VERSIONS = { livenet: '4.0', testnet: '4.0t' } as const;
+const ALT = { livenet: '1', testnet: '2' } as const;
+
+export const DEFAULT_MAX_UNIT_BYTES = 16 * 1024;
+
+export interface ExactExpectation {
+  readonly network: ObyteNetwork;
+  readonly payTo: string;
+  /** `'base'` or asset id; must be allowlisted by the caller beforehand. */
+  readonly asset: string;
+  readonly amount: bigint;
+  readonly binding: string;
+  readonly quoteId: string;
+  /** Facilitator's own addresses: they must never be the payer. */
+  readonly facilitatorAddresses?: readonly string[];
+  readonly maxUnitBytes?: number;
+}
+
+export interface InputRef {
+  readonly asset: string;
+  readonly unit: string;
+  readonly messageIndex: number;
+  readonly outputIndex: number;
+}
+
+export interface ExactUnitFacts {
+  readonly unitHash: string;
+  readonly payer: string;
+  readonly inputs: readonly InputRef[];
+  readonly lastBallUnit: string;
+  readonly parentUnits: readonly string[];
+  readonly timestamp: number;
+  /** Sum of outputs per asset ('base' for bytes), used to check inputs balance. */
+  readonly outputTotals: Readonly<Record<string, bigint>>;
+  readonly commissions: { readonly headers: number; readonly payload: number };
+  /** True when the author definition was not embedded and came from the caller. */
+  readonly definitionFromLedger: boolean;
+}
+
+const UNIT_KEYS = new Set([
+  'version',
+  'alt',
+  'messages',
+  'authors',
+  'parent_units',
+  'last_ball',
+  'last_ball_unit',
+  'timestamp',
+  'headers_commission',
+  'payload_commission',
+  'tps_fee',
+  'burn_fee',
+  'max_aa_responses',
+  'unit',
+]);
+const AUTHOR_KEYS = new Set(['address', 'authentifiers', 'definition']);
+const MESSAGE_KEYS = new Set(['app', 'payload_location', 'payload_hash', 'payload']);
+const PAYMENT_KEYS = new Set(['asset', 'inputs', 'outputs']);
+const INPUT_KEYS = new Set(['unit', 'message_index', 'output_index']);
+const OUTPUT_KEYS = new Set(['address', 'amount']);
+const HASH_RE = /^[A-Za-z0-9+/]{43}=$/;
+
+const isHash = (v: unknown): v is string => typeof v === 'string' && HASH_RE.test(v);
+const isIndex = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0;
+const isPositiveAmount = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) > 0;
+
+export function validateExactUnit(
+  unit: unknown,
+  expect: ExactExpectation,
+  options: { authorDefinition?: SigDefinition } = {},
+): Verdict<ExactUnitFacts> {
+  const R = EXACT_REASONS;
+  const unsupported = (why: string) => reject<ExactUnitFacts>(R.unsupported, why);
+
+  // --- structure & size ---------------------------------------------------
+  if (!isPlainObject(unit)) return unsupported('Unit must be an object');
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(unit);
+  } catch {
+    return unsupported('Unit is not serializable');
+  }
+  if (serialized.length > (expect.maxUnitBytes ?? DEFAULT_MAX_UNIT_BYTES)) {
+    return reject(R.tooLarge, 'Unit exceeds the size limit');
+  }
+  if (!hasOnlyKeys(unit, UNIT_KEYS)) return unsupported('Unit has fields outside the profile');
+
+  // --- network --------------------------------------------------------------
+  const net = expect.network.name;
+  if (unit['version'] !== EXACT_UNIT_VERSIONS[net] || unit['alt'] !== ALT[net]) {
+    return reject(R.network, `Unit version/alt do not match ${expect.network.caip2}`);
+  }
+
+  // --- headers --------------------------------------------------------------
+  const parents = unit['parent_units'];
+  if (!Array.isArray(parents) || parents.length === 0 || !parents.every(isHash)) {
+    return unsupported('Invalid parent_units');
+  }
+  if (!isHash(unit['last_ball']) || !isHash(unit['last_ball_unit'])) {
+    return unsupported('Invalid last ball');
+  }
+  if (!Number.isSafeInteger(unit['timestamp'])) return unsupported('Invalid timestamp');
+  for (const fee of ['headers_commission', 'payload_commission'] as const) {
+    if (!Number.isSafeInteger(unit[fee]) || (unit[fee] as number) <= 0) {
+      return unsupported(`Invalid ${fee}`);
+    }
+  }
+  for (const fee of ['tps_fee', 'burn_fee', 'max_aa_responses'] as const) {
+    if (fee in unit && !isIndex(unit[fee])) return unsupported(`Invalid ${fee}`);
+  }
+
+  // --- unit hash --------------------------------------------------------------
+  if (!isHash(unit['unit'])) return reject(R.unitHash, 'Missing unit hash');
+  const messages = unit['messages'];
+  const authors = unit['authors'];
+  if (!Array.isArray(messages) || !Array.isArray(authors)) return unsupported('Malformed unit');
+  let unitHash: string;
+  try {
+    unitHash = getUnitHash(unit);
+  } catch {
+    return reject(R.unitHash, 'Unit cannot be hashed');
+  }
+  if (unitHash !== unit['unit']) return reject(R.unitHash, 'Unit hash does not match content');
+
+  // --- author, definition, signature -----------------------------------------
+  if (authors.length !== 1) return unsupported('Exactly one author is supported');
+  const author: unknown = authors[0];
+  if (!isPlainObject(author) || !hasOnlyKeys(author, AUTHOR_KEYS))
+    return unsupported('Malformed author');
+  const payer = author['address'];
+  if (!isAddress(payer)) return unsupported('Invalid author address');
+
+  let definition: SigDefinition;
+  let definitionFromLedger = false;
+  if ('definition' in author) {
+    if (!isSigDefinition(author['definition'])) {
+      return reject(R.definition, "Only ['sig', {pubkey}] author definitions are supported");
+    }
+    definition = author['definition'];
+  } else if (options.authorDefinition !== undefined) {
+    if (!isSigDefinition(options.authorDefinition)) {
+      return reject(R.definition, "Only ['sig', {pubkey}] author definitions are supported");
+    }
+    definition = options.authorDefinition;
+    definitionFromLedger = true;
+  } else {
+    return reject(
+      R.definitionRequired,
+      'Author definition is not embedded; fetch it from the ledger',
+    );
+  }
+  if (obyte.utils.getChash160([...definition]) !== payer) {
+    return reject(R.definition, 'Definition does not match the author address');
+  }
+  const authentifiers = author['authentifiers'];
+  if (!isPlainObject(authentifiers) || !hasOnlyKeys(authentifiers, new Set(['r']))) {
+    return reject(R.signature, 'Expected a single authentifier "r"');
+  }
+  if (!verifySignature(getUnitHashToSign(unit), authentifiers['r'], definition[1].pubkey)) {
+    return reject(R.signature, 'Signature is invalid');
+  }
+
+  // --- payer / recipient sanity -------------------------------------------------
+  if (payer === expect.payTo) return reject(R.payer, 'Payer and payTo must differ');
+  if (expect.facilitatorAddresses?.includes(payer)) {
+    return reject(R.payer, 'A facilitator address must never be the payer');
+  }
+
+  // --- messages -----------------------------------------------------------------
+  let dataCount = 0;
+  const payments = new Map<string, Record<string, unknown>>();
+  for (const message of messages) {
+    if (!isPlainObject(message) || !hasOnlyKeys(message, MESSAGE_KEYS)) {
+      return unsupported('Malformed message');
+    }
+    if (message['payload_location'] !== 'inline' || !('payload' in message)) {
+      return unsupported('Only inline payloads are supported');
+    }
+    if (getBase64Hash(message['payload'], true) !== message['payload_hash']) {
+      return reject(R.payloadHash, 'payload_hash does not match payload');
+    }
+    const payload = message['payload'];
+    if (message['app'] === 'data') {
+      dataCount += 1;
+      const binding = checkBinding(payload, expect);
+      if (binding !== undefined) return binding;
+    } else if (message['app'] === 'payment') {
+      if (!isPlainObject(payload) || !hasOnlyKeys(payload, PAYMENT_KEYS)) {
+        return unsupported('Malformed payment');
+      }
+      const asset = 'asset' in payload ? payload['asset'] : 'base';
+      if (asset === 'base' && 'asset' in payload)
+        return unsupported('Bytes payment must omit asset');
+      if (!isAssetId(asset)) return unsupported('Invalid payment asset');
+      if (payments.has(asset)) return unsupported('One payment message per asset');
+      payments.set(asset, payload);
+    } else {
+      return unsupported('Only payment and data messages are supported');
+    }
+  }
+  if (dataCount !== 1)
+    return reject(R.binding, 'Exactly one data message with the binding is required');
+  if (!payments.has('base')) return unsupported('A bytes payment message is required');
+  const allowedAssets = new Set(['base', expect.asset]);
+  for (const asset of payments.keys()) {
+    if (!allowedAssets.has(asset)) return reject(R.asset, 'Payment in an unexpected asset');
+  }
+  if (!payments.has(expect.asset)) return reject(R.asset, 'No payment in the required asset');
+
+  // --- inputs & outputs -----------------------------------------------------------
+  const inputs: InputRef[] = [];
+  const seenInputs = new Set<string>();
+  const outputTotals: Record<string, bigint> = {};
+  let paidToPayTo = 0n;
+  let outputsToPayTo = 0;
+  for (const [asset, payment] of payments) {
+    const ins = payment['inputs'];
+    const outs = payment['outputs'];
+    if (!Array.isArray(ins) || ins.length === 0 || !Array.isArray(outs) || outs.length === 0) {
+      return unsupported('Payment needs inputs and outputs');
+    }
+    for (const input of ins) {
+      if (
+        !isPlainObject(input) ||
+        !hasOnlyKeys(input, INPUT_KEYS) ||
+        !isHash(input['unit']) ||
+        !isIndex(input['message_index']) ||
+        !isIndex(input['output_index'])
+      ) {
+        return unsupported('Only transfer inputs are supported');
+      }
+      const key = `${input['unit']}:${input['message_index']}:${input['output_index']}`;
+      if (seenInputs.has(key)) return unsupported('Duplicate input');
+      seenInputs.add(key);
+      inputs.push({
+        asset,
+        unit: input['unit'],
+        messageIndex: input['message_index'],
+        outputIndex: input['output_index'],
+      });
+    }
+    let total = 0n;
+    let previous: { address: string; amount: number } | undefined;
+    for (const output of outs) {
+      if (
+        !isPlainObject(output) ||
+        !hasOnlyKeys(output, OUTPUT_KEYS) ||
+        !isAddress(output['address']) ||
+        !isPositiveAmount(output['amount'])
+      ) {
+        return unsupported('Malformed output');
+      }
+      // ocore requires outputs sorted by address, then amount; duplicates are
+      // outside our profile.
+      const current = { address: output['address'], amount: output['amount'] };
+      if (previous !== undefined && compareOutputs(previous, current) >= 0) {
+        return unsupported('Outputs must be sorted by address and amount without duplicates');
+      }
+      previous = current;
+      const amount = BigInt(output['amount']);
+      total += amount;
+      if (output['address'] === expect.payTo) {
+        if (asset !== expect.asset)
+          return reject(R.recipient, 'payTo receives an unexpected asset');
+        outputsToPayTo += 1;
+        paidToPayTo += amount;
+      } else if (output['address'] !== payer) {
+        return reject(R.recipient, 'Outputs may only go to payTo or back to the payer');
+      }
+    }
+    outputTotals[asset] = total;
+  }
+  if (outputsToPayTo !== 1) return reject(R.recipient, 'Exactly one output to payTo is required');
+  if (paidToPayTo !== expect.amount) return reject(R.amount, 'Amount paid to payTo does not match');
+
+  // --- commissions ------------------------------------------------------------------
+  const commissions = expectedCommissions(unit);
+  if (
+    commissions.headers !== unit['headers_commission'] ||
+    commissions.payload !== unit['payload_commission']
+  ) {
+    return reject(R.commissions, 'Commissions do not match the unit size');
+  }
+
+  return accept({
+    unitHash,
+    payer,
+    inputs,
+    lastBallUnit: unit['last_ball_unit'],
+    parentUnits: parents,
+    timestamp: unit['timestamp'] as number,
+    outputTotals,
+    commissions,
+    definitionFromLedger,
+  });
+}
+
+/** Length of one base64 secp256k1 signature, as counted by obyte.js. */
+const SIGNATURE_SIZE = 88;
+
+/**
+ * Commissions ocore expects for an already SIGNED single-author unit (v4,
+ * sizes counted with keys). obyte.js `getHeadersSize` is meant for the
+ * unsigned unit during compose (authentifiers hold a path placeholder) and
+ * adds SIGNATURE_SIZE itself; on a signed unit the real signature is already
+ * counted, so it is subtracted. Verified against testnet unit DxPSVW8p…
+ * (headers 452, payload 432).
+ */
+export function expectedCommissions(unit: object): { headers: number; payload: number } {
+  return {
+    headers: getHeadersSize(unit, true) - SIGNATURE_SIZE,
+    payload: getTotalPayloadSize(unit, true),
+  };
+}
+
+export function compareOutputs(
+  a: { address: string; amount: number },
+  b: { address: string; amount: number },
+): number {
+  if (a.address !== b.address) return a.address < b.address ? -1 : 1;
+  return a.amount - b.amount;
+}
+
+function checkBinding(
+  payload: unknown,
+  expect: ExactExpectation,
+): Verdict<ExactUnitFacts> | undefined {
+  const R = EXACT_REASONS;
+  if (!isPlainObject(payload) || !hasOnlyKeys(payload, new Set(['x402']))) {
+    return reject(R.binding, 'Data message must be exactly {x402: {binding, quoteId}}');
+  }
+  const x402 = payload['x402'];
+  if (!isPlainObject(x402) || !hasOnlyKeys(x402, new Set(['binding', 'quoteId']))) {
+    return reject(R.binding, 'Data message must be exactly {x402: {binding, quoteId}}');
+  }
+  if (x402['binding'] !== expect.binding || x402['quoteId'] !== expect.quoteId) {
+    return reject(R.binding, 'Signed binding does not match this operation');
+  }
+  return undefined;
+}

package/src/wallet/index.ts

@@ -0,0 +1,130 @@
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import obyte from 'obyte';
+import { z } from 'zod';
+import { isAddress } from '../channel/definition.js';
+import { ObbyxError } from '../core/errors.js';
+import type { ObyteNetwork } from '../core/networks.js';
+
+/**
+ * Local single-address wallet shared by the CLI, the seller watcher and the
+ * demo playground: one private key per network in
+ * `$OBBYX_HOME/wallet-<network>.json` (default ~/.obbyx), file mode 0600.
+ * Loading verifies the file (schema), its permissions, its network and that
+ * the key derives the stored address. The key never leaves this machine.
+ */
+export const walletFileSchema = z
+  .object({
+    version: z.literal(1),
+    network: z.string(),
+    address: z.string().refine(isAddress, 'invalid Obyte address'),
+    wif: z.string().min(1),
+    createdAt: z.string(),
+  })
+  .strict();
+
+export type WalletFile = z.infer<typeof walletFileSchema>;
+
+export function obbyxHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env['OBBYX_HOME'] ?? join(homedir(), '.obbyx');
+}
+
+export function walletPath(network: ObyteNetwork, env: NodeJS.ProcessEnv = process.env): string {
+  return join(obbyxHome(env), `wallet-${network.name}.json`);
+}
+
+export function createWallet(
+  network: ObyteNetwork,
+  opts: { force?: boolean; env?: NodeJS.ProcessEnv } = {},
+): WalletFile {
+  const path = walletPath(network, opts.env);
+  if (existsSync(path) && opts.force !== true) {
+    throw new ObbyxError(
+      'wallet_exists',
+      `A wallet already exists at ${path} (use --force to replace it)`,
+    );
+  }
+  let privateKey: Uint8Array;
+  let address: string;
+  for (;;) {
+    privateKey = randomBytes(32);
+    try {
+      address = addressOfKey(privateKey, network); // rejects the (astronomically unlikely) invalid scalar
+      break;
+    } catch {
+      continue;
+    }
+  }
+  const wallet: WalletFile = {
+    version: 1,
+    network: network.caip2,
+    address,
+    wif: obyte.utils.toWif(privateKey, network.testnet),
+    createdAt: new Date().toISOString(),
+  };
+  mkdirSync(obbyxHome(opts.env), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(wallet, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return wallet;
+}
+
+export function loadWallet(
+  network: ObyteNetwork,
+  env: NodeJS.ProcessEnv = process.env,
+): WalletFile & { privateKey: Uint8Array } {
+  const path = walletPath(network, env);
+  if (!existsSync(path)) {
+    throw new ObbyxError(
+      'no_wallet',
+      `No wallet for ${network.caip2}. Run: obbyx init --network ${network.name}`,
+    );
+  }
+  if ((statSync(path).mode & 0o077) !== 0) {
+    throw new ObbyxError(
+      'wallet_permissions',
+      `${path} is readable by others; run: chmod 600 ${path}`,
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new ObbyxError('wallet_corrupt', `${path} is not valid JSON`);
+  }
+  const parsed = walletFileSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ObbyxError(
+      'wallet_corrupt',
+      `${path}: ${parsed.error.issues[0]?.message ?? 'invalid wallet file'}`,
+    );
+  }
+  const wallet = parsed.data;
+  if (wallet.network !== network.caip2) {
+    throw new ObbyxError('wallet_network', `${path} belongs to ${wallet.network}`);
+  }
+  let privateKey: Uint8Array;
+  try {
+    privateKey = obyte.utils.fromWif(wallet.wif, network.testnet).privateKey as Uint8Array;
+  } catch {
+    throw new ObbyxError('wallet_corrupt', `${path}: invalid key for ${network.caip2}`);
+  }
+  const address = addressOfKey(privateKey, network);
+  if (address !== wallet.address)
+    throw new ObbyxError('wallet_corrupt', `${path}: key does not match address`);
+  return { ...wallet, privateKey };
+}
+
+/** Address of a single-sig key, via obyte.js public API (signMessage reports its author). */
+export function addressOfKey(privateKey: Uint8Array, network: ObyteNetwork): string {
+  const signed = obyte.utils.signMessage('obbyx', {
+    privateKey,
+    testnet: network.testnet,
+  }) as unknown as {
+    authors: { address: string }[];
+  };
+  const address = signed.authors[0]?.address;
+  if (address === undefined) throw new ObbyxError('wallet_corrupt', 'Cannot derive address');
+  return address;
+}