@forgezero/runtime 0.1.14 → 0.1.16

package/dist/finance/derive.d.ts

@@ -1,115 +0,0 @@
-/**
- * Declaring a value ForgeZero generates rather than the tenant supplying.
- *
- * A tenant that holds a signing key holds the whole risk of holding a signing
- * key: it appears in their backups, their logs, their heap dumps and their
- * environment variables. The alternative is that they never have it. They
- * declare which chain they have activated, ForgeZero derives the key from the
- * realm master seed, and the only thing that ever crosses back is an ADDRESS.
- *
- * This module is the pure half — the specification and the path arithmetic. It
- * cannot derive anything, because it has no seed and must not: this runs in a
- * browser and in a tenant's process, and neither is a place a master seed
- * belongs. The platform half does the derivation and the signing.
- *
- * ## Deterministic, so a lost row is not lost money
- *
- * The path is a function of the declared fields. Losing the database row loses
- * the metadata and not the key — re-declaring the same chain and index derives
- * the same address, and whatever was sent to it is reachable again. A random
- * key stored next to the row would make that row the only copy.
- */
-export declare class DeriveError extends Error {
-    readonly code: 'BAD_SPEC' | 'BAD_INDEX' | 'UNSUPPORTED_SCHEME';
-    constructor(code: 'BAD_SPEC' | 'BAD_INDEX' | 'UNSUPPORTED_SCHEME', message: string);
-}
-/** Curves a chain actually verifies against. */
-export declare const SCHEMES: readonly ["secp256k1", "ed25519"];
-export type Scheme = (typeof SCHEMES)[number];
-/**
- * Who generates the key, which is a real trade-off and not a default.
- *
- *   derived    ForgeZero generates it from the realm master seed, on demand,
- *              and stores NOTHING. There is no key at rest to steal, and a lost
- *              row is recoverable because the key is a function of the seed and
- *              the path. The cost: the platform can always regenerate it, so
- *              the tenant's key is only as private as the ceremony guarding the
- *              seed.
- *
- *   supplied   the tenant generates it — on their own hardware, in their own
- *              ceremony, however they like — and the vault encrypts and stores
- *              it. The platform could never have produced this key, which is
- *              exactly the point for a tenant who needs that to be true. The
- *              cost: there is now a copy at rest, and losing it loses the key,
- *              because nothing can regenerate what the platform never derived.
- *
- * Both sign the same way and neither ever returns the private half. The choice
- * is about who is CAPABLE of generating the key, not about how it is used.
- */
-export declare const CUSTODY: readonly ["derived", "supplied"];
-export type Custody = (typeof CUSTODY)[number];
-/**
- * How one platform-managed field is produced.
- *
- * Carried in the JSON Schema under `x-fz-derive`, so the schema stays the one
- * description of an entry — a separate list of "which fields are magic" is a
- * second source of truth that drifts the first time somebody edits one.
- */
-export interface DeriveSpec {
-    /** Defaults to `derived`: nothing at rest is the safer default to forget. */
-    custody?: Custody;
-    scheme: Scheme;
-    /** BIP-44 coin type. 60 is every EVM chain, 0 is Bitcoin. Derived only. */
-    coinType?: number;
-    account?: number;
-    change?: 0 | 1;
-    /** Address index. Taken from a sibling field when `indexFrom` is set. */
-    index?: number;
-    /**
-     * Read the index from another field of the same entry.
-     *
-     * Lets one schema describe a whole series — a tenant adds an entry with
-     * `index: 7` rather than authoring a seventh schema.
-     */
-    indexFrom?: string;
-    /** What comes back to the tenant. Never the private key, under any value. */
-    expose?: 'address' | 'publicKey';
-}
-export declare const custodyOf: (spec: DeriveSpec) => Custody;
-export declare function assertDeriveSpec(spec: DeriveSpec): void;
-/**
- * The BIP-44 path this spec resolves to, for one entry's data.
- *
- * `m / 44' / coin' / account' / change / index`. Purpose, coin and account are
- * hardened; change and index are not, so a watch-only public key can enumerate
- * addresses without exposing the account.
- */
-export declare function pathFor(spec: DeriveSpec, data?: Record<string, unknown>): string;
-/** The `x-fz-derive` annotation on one property, if it carries one. */
-export declare function deriveSpecOf(property: unknown): DeriveSpec | undefined;
-export interface DerivedField {
-    /** Dotted path into the entry's data. */
-    path: string;
-    spec: DeriveSpec;
-}
-/**
- * Every field of a schema that ForgeZero fills in.
- *
- * Read from the schema rather than configured alongside it, so a field cannot
- * be derived in one place and expected from the tenant in another.
- */
-export declare function derivedFields(schema: unknown, prefix?: string): DerivedField[];
-/**
- * Fields a tenant must NOT send.
- *
- * Only the DERIVED ones. Accepting a value for a derived field would let a
- * caller substitute their own key for the platform's — the entry would look
- * identical and every signature would come from a key the tenant controls.
- *
- * A `supplied` field is the opposite: the tenant is REQUIRED to send it, once,
- * and it is sealed on arrival.
- */
-export declare const derivedPaths: (schema: unknown) => readonly string[];
-/** Fields the tenant generates and the vault only seals. */
-export declare const suppliedPaths: (schema: unknown) => readonly string[];
-export declare const DERIVE_KEYWORD: "x-fz-derive";

package/dist/finance/derive.js

@@ -1,116 +0,0 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
-// src/finance/derive.ts
-class DeriveError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "DeriveError";
-  }
-}
-var SCHEMES = ["secp256k1", "ed25519"];
-var CUSTODY = ["derived", "supplied"];
-var HARDENED = 2147483648;
-var assertIndex = (value, what) => {
-  if (!Number.isInteger(value) || value < 0 || value >= HARDENED) {
-    throw new DeriveError("BAD_INDEX", `${what} must be an integer in 0..${HARDENED - 1}.`);
-  }
-  return value;
-};
-var custodyOf = (spec) => spec.custody ?? "derived";
-function assertDeriveSpec(spec) {
-  if (!SCHEMES.includes(spec.scheme)) {
-    throw new DeriveError("UNSUPPORTED_SCHEME", `${spec.scheme} is not a supported curve.`);
-  }
-  if (custodyOf(spec) === "supplied") {
-    if (spec.coinType !== undefined || spec.index !== undefined || spec.indexFrom) {
-      throw new DeriveError("BAD_SPEC", "A supplied key has no derivation path; drop coinType, index and indexFrom.");
-    }
-    return;
-  }
-  if (spec.coinType === undefined) {
-    throw new DeriveError("BAD_SPEC", "A derived key needs a coinType.");
-  }
-  assertIndex(spec.coinType, "coinType");
-  if (spec.account !== undefined)
-    assertIndex(spec.account, "account");
-  if (spec.index !== undefined)
-    assertIndex(spec.index, "index");
-  if (spec.change !== undefined && spec.change !== 0 && spec.change !== 1) {
-    throw new DeriveError("BAD_SPEC", "change is 0 (external) or 1 (internal).");
-  }
-  if (spec.index === undefined && !spec.indexFrom) {
-    throw new DeriveError("BAD_SPEC", "A spec needs an index, or a field to read one from.");
-  }
-  if (spec.index !== undefined && spec.indexFrom) {
-    throw new DeriveError("BAD_SPEC", "Give an index or an indexFrom, never both.");
-  }
-}
-function pathFor(spec, data = {}) {
-  assertDeriveSpec(spec);
-  if (custodyOf(spec) === "supplied") {
-    throw new DeriveError("BAD_SPEC", "A supplied key has no derivation path.");
-  }
-  let index = spec.index;
-  if (spec.indexFrom) {
-    const raw = data[spec.indexFrom];
-    const value = typeof raw === "string" ? Number(raw) : raw;
-    if (typeof value !== "number") {
-      throw new DeriveError("BAD_INDEX", `${spec.indexFrom} is not a number on this entry.`);
-    }
-    index = assertIndex(value, spec.indexFrom);
-  }
-  const account = spec.account ?? 0;
-  const change = spec.change ?? 0;
-  return `m/44'/${spec.coinType}'/${account}'/${change}/${index}`;
-}
-function deriveSpecOf(property) {
-  if (typeof property !== "object" || property === null)
-    return;
-  const spec = property["x-fz-derive"];
-  if (typeof spec !== "object" || spec === null)
-    return;
-  const parsed = spec;
-  assertDeriveSpec(parsed);
-  return parsed;
-}
-function derivedFields(schema, prefix = "") {
-  if (typeof schema !== "object" || schema === null)
-    return [];
-  const properties = schema.properties;
-  if (!properties)
-    return [];
-  const out = [];
-  for (const [name, property] of Object.entries(properties)) {
-    const path = prefix ? `${prefix}.${name}` : name;
-    const spec = deriveSpecOf(property);
-    if (spec)
-      out.push({ path, spec });
-    else
-      out.push(...derivedFields(property, path));
-  }
-  return out;
-}
-var derivedPaths = (schema) => derivedFields(schema).filter((field) => custodyOf(field.spec) === "derived").map((field) => field.path);
-var suppliedPaths = (schema) => derivedFields(schema).filter((field) => custodyOf(field.spec) === "supplied").map((field) => field.path);
-var DERIVE_KEYWORD = "x-fz-derive";
-export {
-  suppliedPaths,
-  pathFor,
-  derivedPaths,
-  derivedFields,
-  deriveSpecOf,
-  custodyOf,
-  assertDeriveSpec,
-  SCHEMES,
-  DeriveError,
-  DERIVE_KEYWORD,
-  CUSTODY
-};

package/dist/finance/ledger.d.ts

@@ -1,227 +0,0 @@
-import { type Money } from './money';
-/**
- * Balances, as postings.
- *
- * **This module contains no concurrency control, and that is the design.**
- *
- * `@forgezero/runtime/queue` already claims a KEY rather than a message and
- * carries a `dedupeKey`, which gives the two properties people build a ledger
- * lock to get: two writes to one account run one after the other because they
- * share a key, and a retried operation is recognised rather than repeated. A
- * second mechanism next to that is not extra safety — it is a second thing to
- * get right, and it is the one that ends up subtly wrong.
- *
- * So every write here is expected to be inside `drainKey(accountOwner)`, and
- * this module is a data model: entries that sum to zero, balances derived from
- * them.
- *
- * ## A hold is a posting, not a lock
- *
- * "Available" versus "total" is the reason ledgers grow locking code. Here an
- * owner has sub-accounts — `available` and `held` — and placing a hold is a
- * posting between them. `availableOf()` is then an ordinary balance query, and
- * `requireBalance` in `@forgezero/access/conditions` (which already checks
- * available rather than total) is the guard with no new code at all.
- *
- * ## Why double entry rather than a balance column
- *
- * A single column loses the ability to answer *why*. Every movement here has a
- * counterparty and every transaction sums to zero, so a discrepancy names the
- * posting that caused it instead of appearing as a number nobody can
- * reconstruct. It is also what makes a commission split provable: platform
- * revenue, referrer share and user debit are three legs of one transaction that
- * must balance, so a split that loses a unit cannot be committed at all.
- */
-export declare class LedgerError extends Error {
-    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
-    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
-}
-/**
- * The sub-accounts every owner has.
- *
- *   available  spendable now
- *   held       committed to something open — an order, a pending withdrawal
- *
- * Splitting them is what removes the need for a lock: the question "is there
- * enough?" becomes a balance read on one sub-account rather than a balance read
- * plus a reservation somewhere else.
- */
-export declare const BUCKETS: readonly ["available", "held"];
-export type Bucket = (typeof BUCKETS)[number];
-/**
- * Where money can sit.
- *
- * `external` is the counterparty for anything crossing the system boundary — a
- * chain deposit, a card payment. Without it a deposit has one leg and cannot
- * balance, which is how single-column ledgers start.
- */
-export declare const ACCOUNT_KINDS: readonly ["user", "platform", "external"];
-export type AccountKind = (typeof ACCOUNT_KINDS)[number];
-export interface AccountRef {
-    kind: AccountKind;
-    /** User key, or a platform account name like `revenue` or `promotions`. */
-    owner: string;
-    bucket?: Bucket;
-}
-/** Canonical string form, so an account is comparable and indexable. */
-export declare const accountId: (account: AccountRef) => string;
-export declare function parseAccount(id: string): AccountRef;
-/**
- * The queue key for any write touching this account.
- *
- * The OWNER, not the sub-account: moving between an owner's available and held
- * buckets must serialise against every other write for that owner, or a hold
- * and a withdrawal can interleave and both see the same available balance.
- *
- * Exported so callers cannot invent their own convention — two call sites
- * disagreeing about the key is the same as having no key.
- */
-export declare const queueKeyFor: (account: AccountRef) => string;
-export interface Entry {
-    account: AccountRef;
-    /** Positive credits the account, negative debits it. */
-    amount: Money;
-}
-export interface Transaction {
-    /**
-     * The idempotency key, and the queue's `dedupeKey`.
-     *
-     * A retry carrying the same reference is the same transaction. This is the
-     * field that makes a redelivered deposit a no-op rather than a double credit.
-     */
-    reference: string;
-    /** `deposit`, `order.fill`, `commission`, `bonus` — read during an incident. */
-    kind: string;
-    entries: readonly Entry[];
-    atMs: number;
-    memo?: string;
-}
-/**
- * A ledger transaction is one atomic business movement, not a batch transport.
- * Keeping the posting set small bounds both the durable document and the
- * multikey `accountIds[*]` index entry fan-out derived from it by the API.
- */
-export declare const MAX_LEDGER_ENTRIES = 64;
-/**
- * Every transaction sums to zero, per asset.
- *
- * Per asset, not overall: a transaction moving BTC and USDT in one breath would
- * otherwise "balance" by cancelling unrelated currencies against each other,
- * which is not balance, it is an accident that adds to zero.
- */
-export declare function assertBalanced(transaction: Pick<Transaction, 'entries'>): void;
-/** Two legs: one account credited, another debited, same asset. */
-export declare function transfer(args: {
-    reference: string;
-    kind: string;
-    from: AccountRef;
-    to: AccountRef;
-    amount: Money;
-    atMs: number;
-    memo?: string;
-}): Transaction;
-/**
- * Place a hold: available → held, same owner.
- *
- * Not a lock. After this posting `availableOf()` returns less, so the next
- * balance check sees the reduced figure with no reservation table, no expiry
- * sweeper and no way for a crashed process to strand funds behind a lease.
- */
-export declare const placeHold: (args: {
-    reference: string;
-    owner: string;
-    kind?: AccountKind;
-    amount: Money;
-    atMs: number;
-    memo?: string;
-}) => Transaction;
-/** Release a hold: held → available. The order was cancelled, nothing moved. */
-export declare const releaseHold: (args: {
-    reference: string;
-    owner: string;
-    kind?: AccountKind;
-    amount: Money;
-    atMs: number;
-}) => Transaction;
-/**
- * Capture a hold: held → somewhere else. The thing it was held for happened.
- *
- * Deliberately separate from `releaseHold`. Collapsing them into one "resolve"
- * with a flag is how a cancellation ends up paying somebody: the two have
- * opposite effects and should not share a code path.
- */
-export declare const captureHold: (args: {
-    reference: string;
-    owner: string;
-    kind?: AccountKind;
-    to: AccountRef;
-    amount: Money;
-    atMs: number;
-    memo?: string;
-}) => Transaction;
-/**
- * Sum entries into a balance per account and asset.
- *
- * Derived rather than stored, because a stored balance and its postings can
- * disagree — and when they do, nobody can say which is right. Production reads
- * a cached figure the store maintains; this is what proves the cache correct.
- */
-export declare function balancesFrom(transactions: readonly Transaction[]): Map<string, Map<string, Money>>;
-export declare function balanceOf(balances: Map<string, Map<string, Money>>, account: AccountRef, asset: string): Money;
-/** Spendable now. What `requireBalance` should be given as `available`. */
-export declare const availableOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
-export declare const heldOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
-/** Available plus held. What the owner has, not what they can spend. */
-export declare const totalOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
-export interface TrialBalance {
-    ok: boolean;
-    perAsset: {
-        asset: string;
-        total: bigint;
-        accounts: number;
-    }[];
-    /** Assets that do not sum to zero, with the discrepancy. */
-    discrepancies: {
-        asset: string;
-        off: bigint;
-    }[];
-}
-/**
- * Does the whole book balance?
- *
- * The check that finds a bug rather than preventing one. Every transaction is
- * validated on the way in, so a non-zero total here means something wrote
- * around this module or a row was edited — which is exactly the class of
- * problem that is invisible until a customer notices.
- *
- * Run it on a schedule. A book that balanced yesterday and does not today has a
- * bounded set of transactions to inspect; one nobody checks has a year of them.
- */
-export declare function trialBalance(transactions: readonly Transaction[]): TrialBalance;
-/**
- * A human-readable statement for one account.
- *
- * Ordered by time with a running balance, because the question during a dispute
- * is never "what is the balance" — it is "when did it become that".
- */
-export declare function statement(transactions: readonly Transaction[], account: AccountRef, asset: string): {
-    atMs: number;
-    reference: string;
-    kind: string;
-    amount: string;
-    balance: string;
-}[];
-/**
- * Would this leave the account short?
- *
- * A convenience for a caller that already holds the balances. The real guard is
- * `requireBalance` at the route, which returns the right status and the right
- * body; this exists so a job — which has no request to refuse — can make the
- * same check without inventing a second answer.
- */
-export declare function assertAvailable(balances: Map<string, Map<string, Money>>, args: {
-    owner: string;
-    amount: Money;
-    kind?: AccountKind;
-}): void;
-export declare const VERSION = "0.1.0";