@stellaris-lab/por-sdk 0.1.0

package/dist/pipeline.js

@@ -0,0 +1,95 @@
+/**
+ * End-to-end attestation pipeline.
+ *
+ * This is the orchestration layer an exchange/backend service would use: it
+ * normalizes a snapshot, evaluates issuer policy, generates a local proof,
+ * optionally verifies it locally, and submits the attestation on-chain.
+ */
+import { InMemoryAuditSink, makeAuditLog, makeAuditStep, makeWorkflowId } from "./audit.js";
+import { normalizeSnapshot, } from "./domain.js";
+import { StellarisError } from "./errors.js";
+import { evaluateSnapshotPolicy } from "./policy.js";
+import { generateProofFromSnapshot, verifyLocal } from "./prove.js";
+export class AttestationPipeline {
+    client;
+    artifacts;
+    signer;
+    policy;
+    auditSink;
+    requireLocalVerification;
+    constructor(options) {
+        this.client = options.client;
+        this.artifacts = options.artifacts;
+        this.signer = options.signer;
+        if (options.policy !== undefined) {
+            this.policy = options.policy;
+        }
+        this.auditSink = options.auditSink ?? new InMemoryAuditSink();
+        this.requireLocalVerification = options.requireLocalVerification ?? true;
+    }
+    async run(snapshot) {
+        const normalized = normalizeSnapshot(snapshot);
+        const workflowId = makeWorkflowId(this.signer.publicKey, normalized.periodId);
+        const localAudit = new InMemoryAuditSink();
+        const record = async (name, status, context) => {
+            const step = makeAuditStep(context === undefined ? { name, status } : { name, status, context });
+            localAudit.record(step);
+            await this.auditSink.record(step);
+        };
+        await record("snapshot.normalized", "accepted", {
+            periodId: normalized.periodId.toString(),
+            accountCount: normalized.accounts.length,
+        });
+        const policyReport = evaluateSnapshotPolicy(normalized, this.policy);
+        await record("policy.evaluated", policyReport.accepted ? "accepted" : "rejected", {
+            findings: policyReport.findings.map((finding) => finding.code),
+            reserveRatioBps: policyReport.reserveRatioBps?.toString() ?? null,
+        });
+        if (!policyReport.accepted) {
+            throw StellarisError.validation("snapshot rejected by policy", { workflowId, policyReport });
+        }
+        const proof = await generateProofFromSnapshot(normalized, this.artifacts);
+        await record("proof.generated", "accepted", {
+            solvent: proof.parsed.solvent,
+            commitment: proof.parsed.commitment,
+        });
+        if (!proof.parsed.solvent) {
+            await record("proof.solvency", "rejected");
+            throw StellarisError.validation("generated proof public signals report insolvency", { workflowId });
+        }
+        if (this.requireLocalVerification) {
+            if (!this.artifacts.verificationKey) {
+                await record("proof.local_verification", "failed", { reason: "missing_verification_key" });
+                throw StellarisError.configuration("local verification requires a verification key", { context: { workflowId } });
+            }
+            const verified = await verifyLocal(this.artifacts.verificationKey, proof);
+            await record("proof.local_verification", verified ? "accepted" : "rejected");
+            if (!verified) {
+                throw StellarisError.verification("local proof verification failed", { context: { workflowId } });
+            }
+        }
+        const receipt = await this.client.attest({ issuer: this.signer.publicKey, bundle: proof, signer: this.signer });
+        await record("contract.attest", "submitted", {
+            transactionHash: receipt.transactionHash,
+            ledger: receipt.ledger?.toString(),
+        });
+        return {
+            proof,
+            policyReport,
+            receipt,
+            auditLog: makeAuditLog({
+                workflowId,
+                issuer: this.signer.publicKey,
+                periodId: normalized.periodId,
+                deployment: this.client.deployment,
+                steps: localAudit.snapshot(),
+                publicSignals: proof.parsed,
+                policyReport,
+                receipt,
+            }),
+        };
+    }
+}
+export function createAttestationPipeline(options) {
+    return new AttestationPipeline(options);
+}

package/dist/policy.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Policy layer for issuer snapshots.
+ *
+ * Mature protocol SDKs separate policy from mechanics: proving can be valid even
+ * when an issuer-level policy rejects the snapshot. This lets integrators enforce
+ * stricter business rules before expensive proving or transaction submission.
+ */
+import { NormalizedReserveSnapshot } from "./domain.js";
+export interface PolicyFinding {
+    readonly code: string;
+    readonly severity: "info" | "warning" | "error";
+    readonly message: string;
+}
+export interface SnapshotPolicy {
+    readonly minReserveRatioBps?: bigint;
+    readonly maxAccounts?: number;
+    readonly requireMetadata?: boolean;
+    readonly requireExternalReportUri?: boolean;
+    readonly allowZeroBalanceAccounts?: boolean;
+}
+export interface PolicyReport {
+    readonly accepted: boolean;
+    readonly reserveRatioBps: bigint | null;
+    readonly findings: readonly PolicyFinding[];
+}
+export declare const DEFAULT_SNAPSHOT_POLICY: Required<SnapshotPolicy>;
+export declare function evaluateSnapshotPolicy(snapshot: NormalizedReserveSnapshot, policy?: SnapshotPolicy): PolicyReport;

package/dist/policy.js

@@ -0,0 +1,60 @@
+/**
+ * Policy layer for issuer snapshots.
+ *
+ * Mature protocol SDKs separate policy from mechanics: proving can be valid even
+ * when an issuer-level policy rejects the snapshot. This lets integrators enforce
+ * stricter business rules before expensive proving or transaction submission.
+ */
+import { totalReserves } from "./domain.js";
+export const DEFAULT_SNAPSHOT_POLICY = {
+    minReserveRatioBps: 10000n,
+    maxAccounts: 16,
+    requireMetadata: false,
+    requireExternalReportUri: false,
+    allowZeroBalanceAccounts: true,
+};
+export function evaluateSnapshotPolicy(snapshot, policy = DEFAULT_SNAPSHOT_POLICY) {
+    const effective = { ...DEFAULT_SNAPSHOT_POLICY, ...policy };
+    const findings = [];
+    const reserves = totalReserves(snapshot);
+    const ratio = snapshot.liabilities === 0n ? null : (reserves * 10000n) / snapshot.liabilities;
+    if (snapshot.accounts.length > effective.maxAccounts) {
+        findings.push({
+            code: "too_many_accounts",
+            severity: "error",
+            message: `snapshot has ${snapshot.accounts.length} accounts; max is ${effective.maxAccounts}`,
+        });
+    }
+    if (ratio !== null && ratio < effective.minReserveRatioBps) {
+        findings.push({
+            code: "insufficient_reserve_ratio",
+            severity: "error",
+            message: `reserve ratio ${ratio} bps below required ${effective.minReserveRatioBps} bps`,
+        });
+    }
+    if (!effective.allowZeroBalanceAccounts) {
+        const zero = snapshot.accounts.find((account) => account.balance === 0n);
+        if (zero) {
+            findings.push({
+                code: "zero_balance_account",
+                severity: "warning",
+                message: `account ${zero.label} has zero balance`,
+            });
+        }
+    }
+    if (effective.requireMetadata && !snapshot.metadata) {
+        findings.push({ code: "metadata_missing", severity: "error", message: "snapshot metadata is required" });
+    }
+    if (effective.requireExternalReportUri && !snapshot.metadata?.externalReportUri) {
+        findings.push({
+            code: "external_report_missing",
+            severity: "error",
+            message: "external report URI is required by policy",
+        });
+    }
+    return {
+        accepted: findings.every((finding) => finding.severity !== "error"),
+        reserveRatioBps: ratio,
+        findings,
+    };
+}

package/dist/prove.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Groth16 proof generation for Stellaris.
+ *
+ * This module owns witness construction and local proof verification only. It has
+ * no Stellar RPC dependency and no UI/demo behavior.
+ */
+import { ProvingBackend, WitnessInput } from "./backend.js";
+import { NormalizedReserveSnapshot, ProofBundle, ProvingArtifacts, ReserveSnapshot } from "./domain.js";
+export interface ReserveInput {
+    readonly balances: readonly bigint[];
+    readonly salt: bigint;
+    readonly liabilities: bigint;
+    readonly periodId: bigint;
+}
+export declare function validateReserveInput(input: ReserveInput): void;
+export declare function buildWitnessInput(input: ReserveInput): WitnessInput;
+export declare function generateProofFromInput(input: ReserveInput, artifacts: ProvingArtifacts, backend?: ProvingBackend): Promise<ProofBundle>;
+export declare function generateProofFromSnapshot(snapshot: ReserveSnapshot | NormalizedReserveSnapshot, artifacts: ProvingArtifacts, backend?: ProvingBackend): Promise<ProofBundle>;
+export declare function verifyLocal(verificationKey: Record<string, unknown>, bundle: ProofBundle, backend?: ProvingBackend): Promise<boolean>;
+export declare function toContractArgs(bundle: ProofBundle): {
+    readonly proof: {
+        readonly a: readonly [string, string];
+        readonly b: readonly [readonly [string, string], readonly [string, string]];
+        readonly c: readonly [string, string];
+    };
+    readonly pubSignals: readonly string[];
+};

package/dist/prove.js

@@ -0,0 +1,76 @@
+/**
+ * Groth16 proof generation for Stellaris.
+ *
+ * This module owns witness construction and local proof verification only. It has
+ * no Stellar RPC dependency and no UI/demo behavior.
+ */
+import { DEFAULT_PROVING_BACKEND } from "./backend.js";
+import { MAX_RESERVE, N_RESERVES } from "./constants.js";
+import { normalizeSnapshot, toReserveInput, } from "./domain.js";
+import { StellarisError } from "./errors.js";
+export function validateReserveInput(input) {
+    if (input.balances.length === 0) {
+        throw StellarisError.validation("balances must include at least one value");
+    }
+    if (input.balances.length > N_RESERVES) {
+        throw StellarisError.validation(`balances length exceeds max ${N_RESERVES}`);
+    }
+    for (let i = 0; i < input.balances.length; i++) {
+        const balance = input.balances[i];
+        if (typeof balance !== "bigint" || balance < 0n || balance > MAX_RESERVE) {
+            throw StellarisError.validation(`balance ${i} is outside uint64 range`);
+        }
+    }
+    if (input.salt < 0n) {
+        throw StellarisError.validation("salt must be non-negative");
+    }
+    if (input.liabilities < 0n) {
+        throw StellarisError.validation("liabilities must be non-negative");
+    }
+    if (input.periodId < 0n) {
+        throw StellarisError.validation("periodId must be non-negative");
+    }
+}
+export function buildWitnessInput(input) {
+    validateReserveInput(input);
+    const padded = [...input.balances];
+    while (padded.length < N_RESERVES) {
+        padded.push(0n);
+    }
+    return {
+        r: padded.map((balance) => balance.toString()),
+        salt: input.salt.toString(),
+        liabilities_in: input.liabilities.toString(),
+        period_in: input.periodId.toString(),
+    };
+}
+export async function generateProofFromInput(input, artifacts, backend = DEFAULT_PROVING_BACKEND) {
+    const witnessInput = buildWitnessInput(input);
+    return backend.prove(witnessInput, artifacts);
+}
+export async function generateProofFromSnapshot(snapshot, artifacts, backend = DEFAULT_PROVING_BACKEND) {
+    const normalized = "accounts" in snapshot && "balances" in snapshot
+        ? snapshot
+        : normalizeSnapshot(snapshot);
+    return generateProofFromInput(toReserveInput(normalized), artifacts, backend);
+}
+export async function verifyLocal(verificationKey, bundle, backend = DEFAULT_PROVING_BACKEND) {
+    return backend.verify(verificationKey, bundle);
+}
+export function toContractArgs(bundle) {
+    const p = bundle.proof;
+    if (!p.pi_a || !p.pi_b || !p.pi_c) {
+        throw StellarisError.encoding("proof is missing pi_a, pi_b, or pi_c");
+    }
+    return {
+        proof: {
+            a: [p.pi_a[0], p.pi_a[1]],
+            b: [
+                [p.pi_b[0][0], p.pi_b[0][1]],
+                [p.pi_b[1][0], p.pi_b[1][1]],
+            ],
+            c: [p.pi_c[0], p.pi_c[1]],
+        },
+        pubSignals: [...bundle.publicSignals],
+    };
+}

package/dist/reconciler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic registry reconciliation jobs.
+ *
+ * This layer turns the registry/indexer primitives into an operational subsystem:
+ * each run refreshes issuer state, persists checkpoints, emits redacted audit
+ * steps, and classifies partial failures with bounded retry/backoff behavior.
+ */
+import { AuditSink } from "./audit.js";
+import { PublicKey } from "./domain.js";
+import { FileCheckpointRepository } from "./persistence.js";
+import { AttestationRegistry, RegistrySnapshot } from "./registry.js";
+export type ReconciliationStatus = "succeeded" | "failed";
+export interface ReconciliationTarget {
+    readonly issuer: PublicKey;
+    readonly required?: boolean;
+}
+export interface ReconciliationFailure {
+    readonly issuer: PublicKey;
+    readonly attempt: number;
+    readonly message: string;
+    readonly retryable: boolean;
+}
+export interface ReconciliationResult {
+    readonly runId: string;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly status: ReconciliationStatus;
+    readonly attempts: number;
+    readonly snapshots: readonly RegistrySnapshot[];
+    readonly failures: readonly ReconciliationFailure[];
+}
+export interface BackoffPolicy {
+    readonly maxAttempts: number;
+    readonly baseDelayMs: number;
+    readonly maxDelayMs: number;
+}
+export interface ReconcilerClock {
+    now(): Date;
+    sleep(ms: number): Promise<void>;
+}
+export interface RegistryReconcilerOptions {
+    readonly registry: AttestationRegistry;
+    readonly targets: readonly ReconciliationTarget[];
+    readonly checkpoint?: FileCheckpointRepository;
+    readonly auditSink?: AuditSink;
+    readonly backoff?: Partial<BackoffPolicy>;
+    readonly clock?: ReconcilerClock;
+}
+export declare class RegistryReconciler {
+    private readonly registry;
+    private readonly targets;
+    private readonly checkpoint?;
+    private readonly auditSink;
+    private readonly backoff;
+    private readonly clock;
+    constructor(options: RegistryReconcilerOptions);
+    runOnce(): Promise<ReconciliationResult>;
+    runMany(count: number): Promise<readonly ReconciliationResult[]>;
+    private refreshWithRetry;
+    private audit;
+}
+export declare function makeRegistryReconciler(options: RegistryReconcilerOptions): RegistryReconciler;
+export declare function normalizeBackoff(input?: Partial<BackoffPolicy>): BackoffPolicy;
+export declare function nextDelayMs(policy: BackoffPolicy, failedAttempt: number): number;
+export declare function makeRunId(now: Date): string;

package/dist/reconciler.js

@@ -0,0 +1,152 @@
+/**
+ * Deterministic registry reconciliation jobs.
+ *
+ * This layer turns the registry/indexer primitives into an operational subsystem:
+ * each run refreshes issuer state, persists checkpoints, emits redacted audit
+ * steps, and classifies partial failures with bounded retry/backoff behavior.
+ */
+import { InMemoryAuditSink, makeAuditStep } from "./audit.js";
+import { StellarisError } from "./errors.js";
+export class RegistryReconciler {
+    registry;
+    targets;
+    checkpoint;
+    auditSink;
+    backoff;
+    clock;
+    constructor(options) {
+        if (options.targets.length === 0) {
+            throw StellarisError.configuration("registry reconciler requires at least one target issuer");
+        }
+        this.registry = options.registry;
+        this.targets = options.targets;
+        if (options.checkpoint !== undefined) {
+            this.checkpoint = options.checkpoint;
+        }
+        this.auditSink = options.auditSink ?? new InMemoryAuditSink();
+        this.backoff = normalizeBackoff(options.backoff);
+        this.clock = options.clock ?? systemClock;
+    }
+    async runOnce() {
+        const runId = makeRunId(this.clock.now());
+        const startedAt = this.clock.now().toISOString();
+        const snapshots = [];
+        const failures = [];
+        let attempts = 0;
+        await this.audit("reconciler.started", "started", { runId, targets: this.targets.length });
+        for (const target of this.targets) {
+            const outcome = await this.refreshWithRetry(target);
+            attempts += outcome.attempts;
+            if (outcome.snapshot) {
+                snapshots.push(outcome.snapshot);
+            }
+            failures.push(...outcome.failures);
+        }
+        const firstSnapshot = snapshots[0];
+        if (this.checkpoint !== undefined && firstSnapshot !== undefined) {
+            const records = snapshots.flatMap((snapshot) => [...snapshot.attestations]);
+            await this.checkpoint.saveRecords(firstSnapshot.deployment, records);
+        }
+        const requiredFailure = failures.some((failure) => {
+            const target = this.targets.find((item) => item.issuer === failure.issuer);
+            return target?.required ?? true;
+        });
+        const status = requiredFailure ? "failed" : "succeeded";
+        await this.audit(status === "succeeded" ? "reconciler.completed" : "reconciler.failed", status === "succeeded" ? "accepted" : "failed", {
+            runId,
+            snapshots: snapshots.length,
+            failures: failures.length,
+        });
+        return {
+            runId,
+            startedAt,
+            finishedAt: this.clock.now().toISOString(),
+            status,
+            attempts,
+            snapshots,
+            failures,
+        };
+    }
+    async runMany(count) {
+        if (!Number.isInteger(count) || count <= 0) {
+            throw StellarisError.validation("reconciler run count must be a positive integer", { count });
+        }
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            results.push(await this.runOnce());
+        }
+        return results;
+    }
+    async refreshWithRetry(target) {
+        const failures = [];
+        for (let attempt = 1; attempt <= this.backoff.maxAttempts; attempt++) {
+            try {
+                await this.audit("issuer.refresh.started", "started", { issuer: target.issuer, attempt });
+                const snapshot = await this.registry.refreshIssuer(target.issuer);
+                await this.audit("issuer.refresh.completed", "accepted", {
+                    issuer: target.issuer,
+                    attempt,
+                    periods: snapshot.periods.length,
+                    gaps: snapshot.diagnostics.missingPeriods.length,
+                });
+                return { attempts: attempt, snapshot, failures };
+            }
+            catch (cause) {
+                const retryable = isRetryableFailure(cause);
+                const failure = makeFailure(target.issuer, attempt, cause, retryable);
+                failures.push(failure);
+                await this.audit("issuer.refresh.failed", "failed", {
+                    issuer: target.issuer,
+                    attempt,
+                    retryable,
+                    message: failure.message,
+                });
+                if (!retryable || attempt === this.backoff.maxAttempts) {
+                    return { attempts: attempt, failures };
+                }
+                await this.clock.sleep(nextDelayMs(this.backoff, attempt));
+            }
+        }
+        return { attempts: this.backoff.maxAttempts, failures };
+    }
+    async audit(name, status, context) {
+        await this.auditSink.record(makeAuditStep({ name, status, context }));
+    }
+}
+export function makeRegistryReconciler(options) {
+    return new RegistryReconciler(options);
+}
+export function normalizeBackoff(input = {}) {
+    const maxAttempts = input.maxAttempts ?? 3;
+    const baseDelayMs = input.baseDelayMs ?? 250;
+    const maxDelayMs = input.maxDelayMs ?? 5_000;
+    if (maxAttempts <= 0 || baseDelayMs < 0 || maxDelayMs < baseDelayMs) {
+        throw StellarisError.configuration("invalid reconciler backoff policy", { maxAttempts, baseDelayMs, maxDelayMs });
+    }
+    return { maxAttempts, baseDelayMs, maxDelayMs };
+}
+export function nextDelayMs(policy, failedAttempt) {
+    const exponential = policy.baseDelayMs * 2 ** Math.max(0, failedAttempt - 1);
+    return Math.min(policy.maxDelayMs, exponential);
+}
+export function makeRunId(now) {
+    return `stellaris-reconcile-${now.toISOString()}`;
+}
+function makeFailure(issuer, attempt, cause, retryable) {
+    return {
+        issuer,
+        attempt,
+        retryable,
+        message: cause instanceof Error ? cause.message : String(cause),
+    };
+}
+function isRetryableFailure(cause) {
+    if (cause instanceof StellarisError) {
+        return cause.kind === "transport";
+    }
+    return !(cause instanceof Error);
+}
+const systemClock = {
+    now: () => new Date(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};

package/dist/registry.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Attestation registry/indexing layer.
+ *
+ * Protocol SDKs usually expose a state-oriented subsystem in addition to direct
+ * RPC calls. This module reconciles contract state into a local store, detects
+ * period gaps/replays, and gives backend services a stable query surface without
+ * introducing frontend/demo code.
+ */
+import { Attestation, ContractDeployment, PeriodId, PublicKey } from "./domain.js";
+import { StellarisClient } from "./stellar.js";
+export interface IndexedAttestation {
+    readonly attestation: Attestation;
+    readonly deployment: ContractDeployment;
+    readonly indexedAt: string;
+    readonly source: "contract" | "receipt" | "manual";
+}
+export interface RegistrySnapshot {
+    readonly issuer: PublicKey;
+    readonly deployment: ContractDeployment;
+    readonly indexedAt: string;
+    readonly periods: readonly PeriodId[];
+    readonly attestations: readonly IndexedAttestation[];
+    readonly diagnostics: RegistryDiagnostics;
+}
+export interface RegistryDiagnostics {
+    readonly duplicatePeriods: readonly PeriodId[];
+    readonly missingPeriods: readonly PeriodGap[];
+    readonly nonSolventPeriods: readonly PeriodId[];
+    readonly newestPeriod: PeriodId | null;
+    readonly oldestPeriod: PeriodId | null;
+}
+export interface PeriodGap {
+    readonly after: PeriodId;
+    readonly before: PeriodId;
+    readonly missing: readonly PeriodId[];
+}
+export interface AttestationStore {
+    put(record: IndexedAttestation): Promise<void> | void;
+    get(issuer: PublicKey, periodId: PeriodId): Promise<IndexedAttestation | null> | IndexedAttestation | null;
+    list(issuer: PublicKey): Promise<readonly IndexedAttestation[]> | readonly IndexedAttestation[];
+    clear?(issuer?: PublicKey): Promise<void> | void;
+}
+export interface RegistryRefreshOptions {
+    readonly source?: IndexedAttestation["source"];
+    readonly failOnMissingAttestation?: boolean;
+}
+export declare class InMemoryAttestationStore implements AttestationStore {
+    private readonly records;
+    put(record: IndexedAttestation): void;
+    get(issuer: PublicKey, periodId: PeriodId): IndexedAttestation | null;
+    list(issuer: PublicKey): readonly IndexedAttestation[];
+    clear(issuer?: PublicKey): void;
+}
+export declare class AttestationRegistry {
+    private readonly client;
+    private readonly store;
+    constructor(input: {
+        readonly client: StellarisClient;
+        readonly store?: AttestationStore;
+    });
+    put(record: IndexedAttestation): Promise<void>;
+    get(issuer: PublicKey, periodId: PeriodId): Promise<IndexedAttestation | null>;
+    refreshIssuer(issuer: PublicKey, options?: RegistryRefreshOptions): Promise<RegistrySnapshot>;
+    snapshot(issuer: PublicKey): Promise<RegistrySnapshot>;
+}
+export declare function indexAttestation(attestation: Attestation, deployment: ContractDeployment, source?: IndexedAttestation["source"]): IndexedAttestation;
+export declare function analyzeRegistry(records: readonly IndexedAttestation[]): RegistryDiagnostics;
+export declare function findPeriodGaps(periods: readonly PeriodId[]): readonly PeriodGap[];
+export declare function findDuplicatePeriods(periods: readonly PeriodId[]): readonly PeriodId[];
+export declare function dedupeAndSort(periods: readonly PeriodId[]): readonly PeriodId[];
+export declare function comparePeriod(a: PeriodId, b: PeriodId): number;