/**
 * @pwngh/economy-lab
 *
 * Copyright (c) Preston Neal
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE.md file in the root directory of this source tree.
 *
 * @license MIT
 */
import type { Amount } from './money.js';
import type { AccountRef } from './accounts.js';
import type { ProveReport } from './contract.js';
import type { Digest, CallOptions, Rate, Rates, Signer, Store, StoredLink } from './ports.js';
/**
 * What the thorough prover needs — a narrow pick of the Ports bag, so a host passes the whole
 * bag or hand-builds the fields. `digest` is required because the tamper check always
 * recomputes entry hashes; no path trusts a stored hash. `signer` authenticates the archival
 * boundary when one exists — proving an archived store without a signer faults rather than
 * vouching for an unverifiable boundary.
 */
export type ProvePorts = {
    store: Store;
    rates: Rates;
    digest: Digest;
    signer?: Signer;
};
/**
 * The thorough prover, reads only: it recomputes the entire hash chain to catch any altered entry,
 * unlike the lighter `economy.read.health`. An independent audit, not the enforcer — the DB enforces
 * these invariants (see db/*-schema.sql); this re-derives them from the legs to catch a bug in the
 * enforcement itself.
 *
 * @see {@link https://economy-lab-docs.pages.dev/economy/concepts/the-proof/ The proof} for how the
 *   prover re-derives every invariant.
 *
 * @example
 * const report = await proveEconomy({
 *   store: ports.store, rates: ports.rates, digest: ports.digest, signer: ports.signer,
 * });
 * if (!allInvariantsHold(report)) {
 *   throw new Error('ledger integrity check failed'); // report says which property broke
 * }
 */
export declare function proveEconomy(ports: ProvePorts, options?: CallOptions): Promise<ProveReport>;
/**
 * The two sums the backing check needs from one pass over the accounts: the credits the platform
 * owes users and the USD held in trust to back them.
 */
export type BackingTotals = {
    custodialCreditMinor: bigint;
    trustCashMinor: bigint;
};
/**
 * Folds one account's stored balance into the backing totals. The provers call this from their own
 * heads walk, which also gathers other figures; a caller that needs only the backing sums walks
 * via {@link backingTotals} instead.
 */
export declare function foldBackingAccount(totals: BackingTotals, account: AccountRef, balanceMinor: bigint): void;
/**
 * One pass over the chain heads that sums only the backing figures, reading a balance just for the
 * accounts that count. `balanceOf` is injected so a caller inside a transaction can walk the
 * store's heads while reading balances through its own unit.
 */
export declare function backingTotals(heads: AsyncIterable<readonly [AccountRef, string]>, balanceOf: (account: AccountRef) => Promise<Amount>): Promise<BackingTotals>;
/**
 * The USD that must back a given amount of credits: the amount times the par rate (the fixed
 * CREDIT-to-USD rate), rounded down via `convertFloor` so no caller can disagree with the money
 * module. The one backing conversion; both provers and the treasury sweep import it.
 */
export declare function backingRequiredMinor(custodialCreditMinor: bigint, par: Rate): bigint;
/** Returns the USD short of the requirement, clamped to zero when cash is fully held. */
export declare function backingShortfallMinor(requiredMinor: bigint, trustCashMinor: bigint): bigint;
/**
 * Rolls a {@link ProveReport} into one verdict: true only when all five flags hold — conserved,
 * backed, no overdraft, chain intact, and consistent. The one-line gate for CI and audit
 * scripts that only need pass/fail; the report itself says which property broke.
 */
export declare function allInvariantsHold(report: ProveReport): boolean;
/**
 * Locates the chain link carrying `hash`, walking every account's lineage through the public
 * read surface — a bounded forensic lookup, not an indexed query. Case-insensitive exact match;
 * the genesis prevHash never matches (it is not a posting hash). Null on a miss, or once
 * `scanMax` links (default 20 000) have been walked.
 */
export declare function findByHash(read: {
    accounts(options?: CallOptions): AsyncIterable<AccountRef>;
    lineage(account: AccountRef, options?: CallOptions): AsyncIterable<StoredLink>;
}, hash: string, options?: CallOptions & {
    scanMax?: number;
}): Promise<{
    account: AccountRef;
    link: StoredLink;
    field: 'hash' | 'prevHash';
} | null>;