@stellaris-lab/por-sdk 0.1.0

package/dist/domain.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Domain model for the Stellaris proof-of-reserves SDK.
+ *
+ * This file intentionally has no Stellar SDK or snarkjs imports. Mature SDKs keep
+ * domain primitives independent from transport/proving so they can be reused by
+ * CLIs, backend services, browser apps, tests, and indexers.
+ */
+export type DecimalString = string;
+export type PublicKey = string;
+export type ContractId = string;
+export type UnixTimestamp = bigint;
+export type PeriodId = bigint;
+export type FieldElement = DecimalString;
+export interface ReserveAccount {
+    readonly label: string;
+    readonly balance: bigint;
+    readonly asset?: string;
+    readonly sourceRef?: string;
+}
+export interface LiabilityStatement {
+    readonly total: bigint;
+    readonly asset?: string;
+    readonly sourceRef?: string;
+}
+export interface ReserveSnapshot {
+    readonly periodId: PeriodId;
+    readonly accounts: readonly ReserveAccount[];
+    readonly liabilities: LiabilityStatement;
+    readonly salt: bigint;
+    readonly metadata?: SnapshotMetadata;
+}
+export interface SnapshotMetadata {
+    readonly issuerName?: string;
+    readonly ledger?: bigint;
+    readonly generatedAt?: UnixTimestamp;
+    readonly externalReportUri?: string;
+    readonly notes?: readonly string[];
+}
+export interface NormalizedReserveSnapshot {
+    readonly periodId: PeriodId;
+    readonly balances: readonly bigint[];
+    readonly liabilities: bigint;
+    readonly salt: bigint;
+    readonly accounts: readonly ReserveAccount[];
+    readonly metadata?: SnapshotMetadata;
+}
+export interface PublicSignals {
+    readonly solvent: boolean;
+    readonly commitment: FieldElement;
+    readonly liabilities: bigint;
+    readonly periodId: PeriodId;
+}
+export interface ProofBundle {
+    readonly proof: SnarkJsGroth16Proof;
+    readonly publicSignals: readonly FieldElement[];
+    readonly parsed: PublicSignals;
+}
+/** v2 public signals: [solvent, reserveCommitment, liabRoot, liabTotal, period]. */
+export interface PublicSignalsV2 {
+    readonly solvent: boolean;
+    readonly reserveCommitment: FieldElement;
+    readonly liabRoot: FieldElement;
+    readonly liabTotal: bigint;
+    readonly periodId: PeriodId;
+}
+export interface ProofBundleV2 {
+    readonly proof: SnarkJsGroth16Proof;
+    readonly publicSignals: readonly FieldElement[];
+    readonly parsed: PublicSignalsV2;
+}
+/**
+ * v3 public signals (multi-asset): [aggregateSolvent, reserveCommitment,
+ * priceCommitment, assetSolvent[0..n-1], period]. `assetSolvent` is the
+ * per-asset flag vector; `aggregateSolvent` is the oracle-priced aggregate.
+ */
+export interface PublicSignalsV3 {
+    readonly aggregateSolvent: boolean;
+    readonly reserveCommitment: FieldElement;
+    readonly priceCommitment: FieldElement;
+    readonly assetSolvent: readonly boolean[];
+    readonly periodId: PeriodId;
+}
+export interface ProofBundleV3 {
+    readonly proof: SnarkJsGroth16Proof;
+    readonly publicSignals: readonly FieldElement[];
+    readonly parsed: PublicSignalsV3;
+}
+/** A G2 point pair as emitted by snarkjs (two field-element coordinates). */
+export type Groth16G2Pair = readonly [FieldElement, FieldElement];
+export interface SnarkJsGroth16Proof {
+    readonly pi_a: readonly [FieldElement, FieldElement, FieldElement?];
+    readonly pi_b: readonly [Groth16G2Pair, Groth16G2Pair, Groth16G2Pair?];
+    readonly pi_c: readonly [FieldElement, FieldElement, FieldElement?];
+    readonly protocol?: string;
+    readonly curve?: string;
+}
+export interface Attestation {
+    readonly commitment: FieldElement;
+    readonly liabilities: bigint;
+    readonly solvent: boolean;
+    readonly ledgerTs: UnixTimestamp;
+    readonly periodId: PeriodId;
+    readonly issuer: PublicKey;
+}
+export interface AttestationReceipt {
+    readonly attestation: Attestation;
+    readonly transactionHash?: string;
+    readonly ledger?: bigint;
+    readonly networkPassphrase: string;
+    readonly contractId: ContractId;
+}
+/**
+ * v2 attestation: solvency with a SNARK-proven liability total. Unlike v1, the
+ * liability figure (`liabTotal`) is not a trusted scalar — it is the constrained
+ * total of a Merkle-sum liability tree, committed to by `liabRoot`.
+ */
+export interface AttestationV2 {
+    readonly reserveCommitment: FieldElement;
+    readonly liabRoot: FieldElement;
+    readonly liabTotal: bigint;
+    readonly solvent: boolean;
+    readonly ledgerTs: UnixTimestamp;
+    readonly periodId: PeriodId;
+    readonly issuer: PublicKey;
+}
+export interface AttestationReceiptV2 {
+    readonly attestation: AttestationV2;
+    readonly transactionHash?: string;
+    readonly ledger?: bigint;
+    readonly networkPassphrase: string;
+    readonly contractId: ContractId;
+}
+/**
+ * v3 multi-asset attestation: oracle-priced aggregate solvency plus per-asset
+ * flags. `aggregateSolvent` is the priced cross-asset solvency; `assetSolvent`
+ * is the per-asset breakdown (an asset may be underwater while the aggregate is
+ * solvent). `priceCommitment` binds the price vector used (trust boundary: the
+ * prices' authenticity is a C3 signed-feed concern).
+ */
+export interface AttestationV3 {
+    readonly aggregateSolvent: boolean;
+    readonly reserveCommitment: FieldElement;
+    readonly priceCommitment: FieldElement;
+    readonly assetSolvent: readonly boolean[];
+    /**
+     * C3 provenance: true iff a designated-oracle price commitment was published
+     * for this period AND the attested priceCommitment matched it. When false the
+     * prices are issuer-chosen; a consumer requiring oracle-bound pricing MUST
+     * check this flag.
+     */
+    readonly oracleBound: boolean;
+    /**
+     * C2 provenance: true iff a designated custodian's BLS12-381 signature over the
+     * reserveCommitment was presented and verified on-chain (via `attestV3Signed`).
+     * When false the reserves are not custodian-attested; a consumer requiring a
+     * named-custodian signature MUST check this flag.
+     */
+    readonly custodianBound: boolean;
+    readonly ledgerTs: UnixTimestamp;
+    readonly periodId: PeriodId;
+    readonly issuer: PublicKey;
+}
+export interface AttestationReceiptV3 {
+    readonly attestation: AttestationV3;
+    readonly transactionHash?: string;
+    readonly ledger?: bigint;
+    readonly networkPassphrase: string;
+    readonly contractId: ContractId;
+}
+export interface VerificationKeyDocument {
+    readonly protocol?: string;
+    readonly curve?: string;
+    readonly nPublic?: number;
+    readonly vk_alpha_1?: unknown;
+    readonly vk_beta_2?: unknown;
+    readonly vk_gamma_2?: unknown;
+    readonly vk_delta_2?: unknown;
+    readonly IC?: unknown[];
+    readonly [key: string]: unknown;
+}
+export interface ProvingArtifacts {
+    readonly wasmUrl: string;
+    readonly zkeyUrl: string;
+    readonly verificationKey?: VerificationKeyDocument;
+}
+export interface ContractDeployment {
+    readonly contractId: ContractId;
+    readonly networkPassphrase: string;
+    readonly rpcUrl: string;
+}
+export declare function normalizeSnapshot(snapshot: ReserveSnapshot): NormalizedReserveSnapshot;
+export declare function totalReserves(snapshot: Pick<NormalizedReserveSnapshot, "balances">): bigint;
+export declare function isSolvent(snapshot: Pick<NormalizedReserveSnapshot, "balances" | "liabilities">): boolean;
+export declare function toReserveInput(snapshot: NormalizedReserveSnapshot): {
+    balances: bigint[];
+    salt: bigint;
+    liabilities: bigint;
+    periodId: bigint;
+};

package/dist/domain.js

@@ -0,0 +1,57 @@
+/**
+ * Domain model for the Stellaris proof-of-reserves SDK.
+ *
+ * This file intentionally has no Stellar SDK or snarkjs imports. Mature SDKs keep
+ * domain primitives independent from transport/proving so they can be reused by
+ * CLIs, backend services, browser apps, tests, and indexers.
+ */
+import { MAX_RESERVE, N_RESERVES } from "./constants.js";
+import { StellarisError } from "./errors.js";
+export function normalizeSnapshot(snapshot) {
+    if (snapshot.accounts.length === 0) {
+        throw StellarisError.validation("reserve snapshot must include at least one account");
+    }
+    if (snapshot.accounts.length > N_RESERVES) {
+        throw StellarisError.validation(`reserve snapshot has ${snapshot.accounts.length} accounts; max is ${N_RESERVES}`);
+    }
+    if (snapshot.periodId < 0n) {
+        throw StellarisError.validation("periodId must be non-negative");
+    }
+    if (snapshot.salt < 0n) {
+        throw StellarisError.validation("salt must be non-negative");
+    }
+    if (snapshot.liabilities.total < 0n) {
+        throw StellarisError.validation("liabilities must be non-negative");
+    }
+    const balances = snapshot.accounts.map((account, index) => {
+        if (!account.label || account.label.trim().length === 0) {
+            throw StellarisError.validation(`reserve account ${index} is missing a label`);
+        }
+        if (account.balance < 0n || account.balance > MAX_RESERVE) {
+            throw StellarisError.validation(`reserve account ${account.label} balance is outside uint64 range`);
+        }
+        return account.balance;
+    });
+    return {
+        periodId: snapshot.periodId,
+        balances,
+        liabilities: snapshot.liabilities.total,
+        salt: snapshot.salt,
+        accounts: snapshot.accounts,
+        ...(snapshot.metadata === undefined ? {} : { metadata: snapshot.metadata }),
+    };
+}
+export function totalReserves(snapshot) {
+    return snapshot.balances.reduce((sum, balance) => sum + balance, 0n);
+}
+export function isSolvent(snapshot) {
+    return totalReserves(snapshot) >= snapshot.liabilities;
+}
+export function toReserveInput(snapshot) {
+    return {
+        balances: [...snapshot.balances],
+        salt: snapshot.salt,
+        liabilities: snapshot.liabilities,
+        periodId: snapshot.periodId,
+    };
+}

package/dist/encoding.d.ts

@@ -0,0 +1,67 @@
+/**
+ * BLS12-381 byte encoding for the Stellaris contract ABI.
+ *
+ * This is the SINGLE shared converter required by the cross-file proof-encoding
+ * invariant: the bytes produced here MUST be identical to what the on-chain
+ * Soroban verifier (contracts/stellaris) consumes. The contract takes:
+ *
+ *   - G1 points (proof.a, proof.c, vk.alpha, vk.ic[i]) as 96-byte uncompressed
+ *     big-endian:  X(48) || Y(48)
+ *   - G2 points (proof.b, vk.beta/gamma/delta) as 192-byte uncompressed
+ *     big-endian:  X.c1(48) || X.c0(48) || Y.c1(48) || Y.c0(48)
+ *   - Public signals (U256) as 32-byte big-endian.
+ *
+ * snarkjs emits each Fp2 as [c0, c1]. The arkworks / Soroban uncompressed
+ * serialization writes the HIGH coefficient (c1) first, so the G2 encoder SWAPS
+ * within each Fp2 pair. This was confirmed byte-for-byte against the Rust
+ * on-chain pairing path (ark-bls12-381 `serialize_uncompressed` feeding the
+ * `G2Affine` the verifier accepts) and the official stellar/soroban-examples
+ * groth16_verifier. Do NOT reorder without re-running the byte-equality test.
+ *
+ * This module has ZERO crypto dependencies: it only does fixed-width big-endian
+ * serialization of already-reduced field elements. Curve membership is checked
+ * on-chain by the verifier, not here.
+ */
+import { SnarkJsGroth16Proof } from "./domain.js";
+/** Bytes per BLS12-381 base-field element (Fp), uncompressed big-endian. */
+export declare const FP_SIZE = 48;
+/** Bytes per G1 affine point: X(48) || Y(48). */
+export declare const G1_SIZE = 96;
+/** Bytes per G2 affine point: X.c1(48) || X.c0(48) || Y.c1(48) || Y.c0(48). */
+export declare const G2_SIZE = 192;
+/** Bytes per public signal (U256), big-endian. */
+export declare const U256_SIZE = 32;
+/**
+ * Serialize a non-negative decimal string into a fixed-width big-endian buffer.
+ * Throws if the value is malformed or overflows `size` bytes.
+ */
+export declare function decimalToBytes(decimal: string, size: number): Uint8Array;
+/** Serialize one Fp field element to 48 big-endian bytes. */
+export declare function fpToBytes(decimal: string): Uint8Array;
+/** Serialize a G1 affine point [x, y] to 96 uncompressed big-endian bytes: X || Y. */
+export declare function g1ToBytes(x: string, y: string): Uint8Array;
+/**
+ * Serialize a G2 affine point to 192 uncompressed big-endian bytes.
+ * Inputs are in snarkjs [c0, c1] order; output writes c1 || c0 per Fp2 (the
+ * high coefficient first), matching the on-chain layout.
+ */
+export declare function g2ToBytes(xC0: string, xC1: string, yC0: string, yC1: string): Uint8Array;
+/** Serialize a public signal (decimal U256) to 32 big-endian bytes. */
+export declare function signalToBytes(decimal: string): Uint8Array;
+/** A Groth16 proof serialized to the contract's byte layout. */
+export interface ContractProofBytes {
+    /** proof.a — G1, 96 bytes. */
+    readonly a: Uint8Array;
+    /** proof.b — G2, 192 bytes. */
+    readonly b: Uint8Array;
+    /** proof.c — G1, 96 bytes. */
+    readonly c: Uint8Array;
+}
+/**
+ * Serialize a snarkjs Groth16 proof to the contract's byte layout (G1/G2
+ * uncompressed). This is the byte-exact counterpart to `proofToContractArgs`,
+ * which keeps the decimal-string shape for inspection/logging.
+ */
+export declare function proofToBytes(proof: SnarkJsGroth16Proof): ContractProofBytes;
+/** Lowercase hex of a byte buffer (no 0x prefix) — for tests / debugging. */
+export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/encoding.js

@@ -0,0 +1,120 @@
+/**
+ * BLS12-381 byte encoding for the Stellaris contract ABI.
+ *
+ * This is the SINGLE shared converter required by the cross-file proof-encoding
+ * invariant: the bytes produced here MUST be identical to what the on-chain
+ * Soroban verifier (contracts/stellaris) consumes. The contract takes:
+ *
+ *   - G1 points (proof.a, proof.c, vk.alpha, vk.ic[i]) as 96-byte uncompressed
+ *     big-endian:  X(48) || Y(48)
+ *   - G2 points (proof.b, vk.beta/gamma/delta) as 192-byte uncompressed
+ *     big-endian:  X.c1(48) || X.c0(48) || Y.c1(48) || Y.c0(48)
+ *   - Public signals (U256) as 32-byte big-endian.
+ *
+ * snarkjs emits each Fp2 as [c0, c1]. The arkworks / Soroban uncompressed
+ * serialization writes the HIGH coefficient (c1) first, so the G2 encoder SWAPS
+ * within each Fp2 pair. This was confirmed byte-for-byte against the Rust
+ * on-chain pairing path (ark-bls12-381 `serialize_uncompressed` feeding the
+ * `G2Affine` the verifier accepts) and the official stellar/soroban-examples
+ * groth16_verifier. Do NOT reorder without re-running the byte-equality test.
+ *
+ * This module has ZERO crypto dependencies: it only does fixed-width big-endian
+ * serialization of already-reduced field elements. Curve membership is checked
+ * on-chain by the verifier, not here.
+ */
+import { StellarisError } from "./errors.js";
+/** Bytes per BLS12-381 base-field element (Fp), uncompressed big-endian. */
+export const FP_SIZE = 48;
+/** Bytes per G1 affine point: X(48) || Y(48). */
+export const G1_SIZE = 96;
+/** Bytes per G2 affine point: X.c1(48) || X.c0(48) || Y.c1(48) || Y.c0(48). */
+export const G2_SIZE = 192;
+/** Bytes per public signal (U256), big-endian. */
+export const U256_SIZE = 32;
+const DECIMAL = /^(0|[1-9][0-9]*)$/;
+/**
+ * Serialize a non-negative decimal string into a fixed-width big-endian buffer.
+ * Throws if the value is malformed or overflows `size` bytes.
+ */
+export function decimalToBytes(decimal, size) {
+    if (!DECIMAL.test(decimal)) {
+        throw StellarisError.encoding("field element must be a non-negative decimal string", {
+            value: decimal,
+        });
+    }
+    let value = BigInt(decimal);
+    const out = new Uint8Array(size);
+    for (let i = size - 1; i >= 0; i--) {
+        out[i] = Number(value & 0xffn);
+        value >>= 8n;
+    }
+    if (value !== 0n) {
+        throw StellarisError.encoding(`value exceeds ${size} bytes (serialization overflow)`, {
+            value: decimal,
+        });
+    }
+    return out;
+}
+/** Serialize one Fp field element to 48 big-endian bytes. */
+export function fpToBytes(decimal) {
+    return decimalToBytes(decimal, FP_SIZE);
+}
+/** Serialize a G1 affine point [x, y] to 96 uncompressed big-endian bytes: X || Y. */
+export function g1ToBytes(x, y) {
+    const out = new Uint8Array(G1_SIZE);
+    out.set(fpToBytes(x), 0);
+    out.set(fpToBytes(y), FP_SIZE);
+    return out;
+}
+/**
+ * Serialize a G2 affine point to 192 uncompressed big-endian bytes.
+ * Inputs are in snarkjs [c0, c1] order; output writes c1 || c0 per Fp2 (the
+ * high coefficient first), matching the on-chain layout.
+ */
+export function g2ToBytes(xC0, xC1, yC0, yC1) {
+    const out = new Uint8Array(G2_SIZE);
+    out.set(fpToBytes(xC1), 0);
+    out.set(fpToBytes(xC0), FP_SIZE);
+    out.set(fpToBytes(yC1), FP_SIZE * 2);
+    out.set(fpToBytes(yC0), FP_SIZE * 3);
+    return out;
+}
+/** Serialize a public signal (decimal U256) to 32 big-endian bytes. */
+export function signalToBytes(decimal) {
+    return decimalToBytes(decimal, U256_SIZE);
+}
+/**
+ * Serialize a snarkjs Groth16 proof to the contract's byte layout (G1/G2
+ * uncompressed). This is the byte-exact counterpart to `proofToContractArgs`,
+ * which keeps the decimal-string shape for inspection/logging.
+ */
+export function proofToBytes(proof) {
+    if (!Array.isArray(proof.pi_a) || !Array.isArray(proof.pi_b) || !Array.isArray(proof.pi_c)) {
+        throw StellarisError.encoding("invalid snarkjs proof shape");
+    }
+    const a0 = proof.pi_a[0];
+    const a1 = proof.pi_a[1];
+    const c0 = proof.pi_c[0];
+    const c1 = proof.pi_c[1];
+    const bx = proof.pi_b[0];
+    const by = proof.pi_b[1];
+    if (a0 === undefined || a1 === undefined || c0 === undefined || c1 === undefined) {
+        throw StellarisError.encoding("proof pi_a / pi_c missing coordinates");
+    }
+    if (!Array.isArray(bx) || !Array.isArray(by) || bx.length < 2 || by.length < 2) {
+        throw StellarisError.encoding("proof pi_b must be [[x.c0,x.c1],[y.c0,y.c1]]");
+    }
+    return {
+        a: g1ToBytes(a0, a1),
+        b: g2ToBytes(bx[0], bx[1], by[0], by[1]),
+        c: g1ToBytes(c0, c1),
+    };
+}
+/** Lowercase hex of a byte buffer (no 0x prefix) — for tests / debugging. */
+export function bytesToHex(bytes) {
+    let s = "";
+    for (const b of bytes) {
+        s += b.toString(16).padStart(2, "0");
+    }
+    return s;
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured SDK errors.
+ *
+ * The SDK uses stable error codes instead of ad-hoc Error messages so API
+ * consumers can branch safely, similar to mature protocol SDKs.
+ */
+export type StellarisErrorKind = "validation" | "proving" | "verification" | "encoding" | "transport" | "contract" | "configuration";
+export interface StellarisErrorDetails {
+    readonly cause?: unknown;
+    readonly context?: Record<string, unknown>;
+}
+export type StellarisErrorContext = Record<string, unknown> | StellarisErrorDetails;
+export declare class StellarisError extends Error {
+    readonly kind: StellarisErrorKind;
+    readonly context?: Record<string, unknown>;
+    constructor(kind: StellarisErrorKind, message: string, details?: StellarisErrorDetails);
+    static validation(message: string, context?: Record<string, unknown>): StellarisError;
+    static proving(message: string, details?: StellarisErrorContext): StellarisError;
+    static verification(message: string, details?: StellarisErrorContext): StellarisError;
+    static encoding(message: string, details?: StellarisErrorContext): StellarisError;
+    static transport(message: string, details?: StellarisErrorContext): StellarisError;
+    static contract(message: string, details?: StellarisErrorContext): StellarisError;
+    static configuration(message: string, details?: StellarisErrorContext): StellarisError;
+}
+export declare function wrapUnknown(kind: StellarisErrorKind, message: string, cause: unknown): StellarisError;

package/dist/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Structured SDK errors.
+ *
+ * The SDK uses stable error codes instead of ad-hoc Error messages so API
+ * consumers can branch safely, similar to mature protocol SDKs.
+ */
+export class StellarisError extends Error {
+    kind;
+    context;
+    constructor(kind, message, details) {
+        super(`[${kind}] ${message}`);
+        this.name = "StellarisError";
+        this.kind = kind;
+        if (details?.context !== undefined) {
+            this.context = details.context;
+        }
+        if (details?.cause !== undefined) {
+            this.cause = details.cause;
+        }
+    }
+    static validation(message, context) {
+        return new StellarisError("validation", message, normalizeDetails(context));
+    }
+    static proving(message, details) {
+        return new StellarisError("proving", message, normalizeDetails(details));
+    }
+    static verification(message, details) {
+        return new StellarisError("verification", message, normalizeDetails(details));
+    }
+    static encoding(message, details) {
+        return new StellarisError("encoding", message, normalizeDetails(details));
+    }
+    static transport(message, details) {
+        return new StellarisError("transport", message, normalizeDetails(details));
+    }
+    static contract(message, details) {
+        return new StellarisError("contract", message, normalizeDetails(details));
+    }
+    static configuration(message, details) {
+        return new StellarisError("configuration", message, normalizeDetails(details));
+    }
+}
+export function wrapUnknown(kind, message, cause) {
+    return new StellarisError(kind, message, { cause });
+}
+function normalizeDetails(details) {
+    if (details === undefined) {
+        return undefined;
+    }
+    if ("context" in details || "cause" in details) {
+        return details;
+    }
+    return { context: details };
+}

package/dist/events.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Typed registry/indexer events.
+ *
+ * Backend consumers should subscribe to stable events instead of reaching into
+ * reconciler internals. This mirrors mature SDK event surfaces: typed payloads,
+ * bounded replay, and composable sinks.
+ */
+import { PublicKey } from "./domain.js";
+import { RegistryDiagnostics, RegistrySnapshot } from "./registry.js";
+import { ReconciliationFailure, ReconciliationResult } from "./reconciler.js";
+export type RegistryEventKind = "reconciler.started" | "issuer.refresh.started" | "issuer.refresh.succeeded" | "issuer.refresh.failed" | "checkpoint.written" | "reconciler.completed";
+export type RegistryEvent = ReconcilerStartedEvent | IssuerRefreshStartedEvent | IssuerRefreshSucceededEvent | IssuerRefreshFailedEvent | CheckpointWrittenEvent | ReconcilerCompletedEvent;
+export interface RegistryEventBase<Kind extends RegistryEventKind> {
+    readonly kind: Kind;
+    readonly id: string;
+    readonly runId: string;
+    readonly at: string;
+}
+export interface ReconcilerStartedEvent extends RegistryEventBase<"reconciler.started"> {
+    readonly targetCount: number;
+}
+export interface IssuerRefreshStartedEvent extends RegistryEventBase<"issuer.refresh.started"> {
+    readonly issuer: PublicKey;
+    readonly attempt: number;
+}
+export interface IssuerRefreshSucceededEvent extends RegistryEventBase<"issuer.refresh.succeeded"> {
+    readonly issuer: PublicKey;
+    readonly attempt: number;
+    readonly periodCount: number;
+    readonly diagnostics: RegistryDiagnostics;
+}
+export interface IssuerRefreshFailedEvent extends RegistryEventBase<"issuer.refresh.failed"> {
+    readonly issuer: PublicKey;
+    readonly failure: ReconciliationFailure;
+}
+export interface CheckpointWrittenEvent extends RegistryEventBase<"checkpoint.written"> {
+    readonly issuerCount: number;
+    readonly recordCount: number;
+}
+export interface ReconcilerCompletedEvent extends RegistryEventBase<"reconciler.completed"> {
+    readonly status: ReconciliationResult["status"];
+    readonly attempts: number;
+    readonly snapshots: number;
+    readonly failures: number;
+}
+export interface RegistryEventSink {
+    emit(event: RegistryEvent): void | Promise<void>;
+}
+export interface RegistryEventSubscription {
+    unsubscribe(): void;
+}
+export type RegistryEventHandler = (event: RegistryEvent) => void | Promise<void>;
+/** Distributive Omit so each union member keeps its own discriminated fields. */
+type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+export declare class InMemoryRegistryEventLog implements RegistryEventSink {
+    private readonly events;
+    emit(event: RegistryEvent): void;
+    replay(handler: RegistryEventHandler, filter?: Partial<{
+        readonly kind: RegistryEventKind;
+        readonly runId: string;
+    }>): void;
+    snapshot(): readonly RegistryEvent[];
+    clear(): void;
+}
+export declare class RegistryEventBus implements RegistryEventSink {
+    private readonly handlers;
+    private readonly replayLog?;
+    constructor(input?: {
+        readonly replayLog?: InMemoryRegistryEventLog;
+    });
+    subscribe(handler: RegistryEventHandler): RegistryEventSubscription;
+    emit(event: RegistryEvent): Promise<void>;
+}
+export declare function makeRegistryEvent(input: DistributiveOmit<RegistryEvent, "id" | "at"> & {
+    readonly at?: string;
+}): RegistryEvent;
+export declare function snapshotToRefreshEvent(runId: string, snapshot: RegistrySnapshot, attempt: number): IssuerRefreshSucceededEvent;
+export {};

package/dist/events.js

@@ -0,0 +1,66 @@
+/**
+ * Typed registry/indexer events.
+ *
+ * Backend consumers should subscribe to stable events instead of reaching into
+ * reconciler internals. This mirrors mature SDK event surfaces: typed payloads,
+ * bounded replay, and composable sinks.
+ */
+export class InMemoryRegistryEventLog {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    replay(handler, filter) {
+        for (const event of this.events) {
+            if (filter?.kind !== undefined && event.kind !== filter.kind) {
+                continue;
+            }
+            if (filter?.runId !== undefined && event.runId !== filter.runId) {
+                continue;
+            }
+            void handler(event);
+        }
+    }
+    snapshot() {
+        return [...this.events];
+    }
+    clear() {
+        this.events.length = 0;
+    }
+}
+export class RegistryEventBus {
+    handlers = new Set();
+    replayLog;
+    constructor(input = {}) {
+        if (input.replayLog !== undefined) {
+            this.replayLog = input.replayLog;
+        }
+    }
+    subscribe(handler) {
+        this.handlers.add(handler);
+        return {
+            unsubscribe: () => {
+                this.handlers.delete(handler);
+            },
+        };
+    }
+    async emit(event) {
+        this.replayLog?.emit(event);
+        await Promise.all([...this.handlers].map((handler) => handler(event)));
+    }
+}
+export function makeRegistryEvent(input) {
+    const at = input.at ?? new Date().toISOString();
+    const id = `${input.runId}:${input.kind}:${at}`;
+    return { ...input, id, at };
+}
+export function snapshotToRefreshEvent(runId, snapshot, attempt) {
+    return makeRegistryEvent({
+        kind: "issuer.refresh.succeeded",
+        runId,
+        issuer: snapshot.issuer,
+        attempt,
+        periodCount: snapshot.periods.length,
+        diagnostics: snapshot.diagnostics,
+    });
+}