@stellaris-lab/por-sdk 0.1.0

package/dist/registry.js

@@ -0,0 +1,167 @@
+/**
+ * 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 { StellarisError } from "./errors.js";
+export class InMemoryAttestationStore {
+    records = new Map();
+    put(record) {
+        this.records.set(keyOf(record.attestation.issuer, record.attestation.periodId), record);
+    }
+    get(issuer, periodId) {
+        return this.records.get(keyOf(issuer, periodId)) ?? null;
+    }
+    list(issuer) {
+        return [...this.records.values()]
+            .filter((record) => record.attestation.issuer === issuer)
+            .sort((a, b) => comparePeriod(a.attestation.periodId, b.attestation.periodId));
+    }
+    clear(issuer) {
+        if (issuer === undefined) {
+            this.records.clear();
+            return;
+        }
+        for (const key of [...this.records.keys()]) {
+            if (key.startsWith(`${issuer}:`)) {
+                this.records.delete(key);
+            }
+        }
+    }
+}
+export class AttestationRegistry {
+    client;
+    store;
+    constructor(input) {
+        this.client = input.client;
+        this.store = input.store ?? new InMemoryAttestationStore();
+    }
+    async put(record) {
+        validateIndexedAttestation(record, this.client.deployment);
+        await this.store.put(record);
+    }
+    async get(issuer, periodId) {
+        const cached = await this.store.get(issuer, periodId);
+        if (cached) {
+            return cached;
+        }
+        const attestation = await this.client.getAttestation(issuer, periodId);
+        if (!attestation) {
+            return null;
+        }
+        const record = indexAttestation(attestation, this.client.deployment, "contract");
+        await this.store.put(record);
+        return record;
+    }
+    async refreshIssuer(issuer, options = {}) {
+        const periods = dedupeAndSort(await this.client.listPeriods(issuer));
+        const source = options.source ?? "contract";
+        for (const periodId of periods) {
+            const attestation = await this.client.getAttestation(issuer, periodId);
+            if (!attestation) {
+                if (options.failOnMissingAttestation ?? true) {
+                    throw StellarisError.contract("contract listed period without attestation", {
+                        issuer,
+                        periodId: periodId.toString(),
+                    });
+                }
+                continue;
+            }
+            await this.store.put(indexAttestation(attestation, this.client.deployment, source));
+        }
+        return this.snapshot(issuer);
+    }
+    async snapshot(issuer) {
+        const attestations = await this.store.list(issuer);
+        const periods = attestations.map((record) => record.attestation.periodId);
+        return {
+            issuer,
+            deployment: this.client.deployment,
+            indexedAt: new Date().toISOString(),
+            periods,
+            attestations,
+            diagnostics: analyzeRegistry(attestations),
+        };
+    }
+}
+export function indexAttestation(attestation, deployment, source = "manual") {
+    return {
+        attestation,
+        deployment,
+        source,
+        indexedAt: new Date().toISOString(),
+    };
+}
+export function analyzeRegistry(records) {
+    const periods = records.map((record) => record.attestation.periodId).sort(comparePeriod);
+    const duplicatePeriods = findDuplicatePeriods(periods);
+    const missingPeriods = findPeriodGaps(dedupeAndSort(periods));
+    const nonSolventPeriods = records
+        .filter((record) => !record.attestation.solvent)
+        .map((record) => record.attestation.periodId)
+        .sort(comparePeriod);
+    return {
+        duplicatePeriods,
+        missingPeriods,
+        nonSolventPeriods,
+        newestPeriod: periods.length === 0 ? null : periods[periods.length - 1] ?? null,
+        oldestPeriod: periods.length === 0 ? null : periods[0] ?? null,
+    };
+}
+export function findPeriodGaps(periods) {
+    const sorted = dedupeAndSort(periods);
+    const gaps = [];
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous === undefined || current === undefined || current <= previous + 1n) {
+            continue;
+        }
+        const missing = [];
+        for (let period = previous + 1n; period < current; period++) {
+            missing.push(period);
+        }
+        gaps.push({ after: previous, before: current, missing });
+    }
+    return gaps;
+}
+export function findDuplicatePeriods(periods) {
+    const seen = new Set();
+    const duplicated = new Set();
+    for (const period of periods) {
+        const key = period.toString();
+        if (seen.has(key)) {
+            duplicated.add(key);
+        }
+        seen.add(key);
+    }
+    return [...duplicated].map((period) => BigInt(period)).sort(comparePeriod);
+}
+export function dedupeAndSort(periods) {
+    return [...new Set(periods.map((period) => period.toString()))]
+        .map((period) => BigInt(period))
+        .sort(comparePeriod);
+}
+export function comparePeriod(a, b) {
+    return a === b ? 0 : a < b ? -1 : 1;
+}
+function validateIndexedAttestation(record, deployment) {
+    if (record.deployment.contractId !== deployment.contractId) {
+        throw StellarisError.validation("indexed attestation belongs to a different contract", {
+            expected: deployment.contractId,
+            actual: record.deployment.contractId,
+        });
+    }
+    if (record.deployment.networkPassphrase !== deployment.networkPassphrase) {
+        throw StellarisError.validation("indexed attestation belongs to a different network", {
+            expected: deployment.networkPassphrase,
+            actual: record.deployment.networkPassphrase,
+        });
+    }
+}
+function keyOf(issuer, periodId) {
+    return `${issuer}:${periodId}`;
+}

package/dist/signals.d.ts

@@ -0,0 +1,36 @@
+/** Public signal parsing and validation. */
+import { FieldElement, PublicSignals, PublicSignalsV2, PublicSignalsV3 } from "./domain.js";
+export declare function assertFieldElement(value: string, label: string): void;
+export declare function parsePublicSignals(signals: readonly FieldElement[]): PublicSignals;
+export declare function encodePublicSignals(signals: PublicSignals): readonly FieldElement[];
+/**
+ * Parse the v2 public-signal layout, mirroring the on-chain
+ * `parse_public_signals_v2` (contracts/stellaris/src/signals.rs):
+ *   [ solvent, reserveCommitment, liabRoot, liabTotal, period ]
+ *
+ * `reserveCommitment` and `liabRoot` are full-width field elements (hashes) kept
+ * as decimal strings; `liabTotal` is the SNARK-proven total liabilities.
+ */
+export declare function parsePublicSignalsV2(signals: readonly FieldElement[]): PublicSignalsV2;
+export declare function encodePublicSignalsV2(signals: PublicSignalsV2): readonly FieldElement[];
+/**
+ * Parse the v3 multi-asset public-signal layout, mirroring the on-chain
+ * `parse_public_signals_v3` (contracts/stellaris/src/signals.rs):
+ *   [ aggregateSolvent, reserveCommitment, priceCommitment,
+ *     assetSolvent[0..N_ASSETS_V3-1], period ]
+ *
+ * `reserveCommitment`/`priceCommitment` are full-width field elements kept as
+ * decimal strings; the aggregate flag and each per-asset flag must be 0 or 1.
+ */
+export declare function parsePublicSignalsV3(signals: readonly FieldElement[]): PublicSignalsV3;
+/**
+ * Encode the v3 multi-asset public-signal layout, the inverse of
+ * {@link parsePublicSignalsV3}. Produces the exact decimal-string vector the
+ * on-chain `parse_public_signals_v3` expects:
+ *   [ aggregateSolvent, reserveCommitment, priceCommitment,
+ *     assetSolvent[0..N_ASSETS_V3-1], period ]
+ *
+ * `assetSolvent` must contain exactly `N_ASSETS_V3` flags; a different length is
+ * a programming error and is rejected rather than silently padded/truncated.
+ */
+export declare function encodePublicSignalsV3(signals: PublicSignalsV3): readonly FieldElement[];

package/dist/signals.js

@@ -0,0 +1,194 @@
+/** Public signal parsing and validation. */
+import { N_PUBLIC_SIGNALS, N_PUBLIC_SIGNALS_V2, SIGNAL_INDEX_COMMITMENT, SIGNAL_INDEX_LIABILITIES, SIGNAL_INDEX_PERIOD, SIGNAL_INDEX_SOLVENT, SIGNAL_INDEX_V2_LIAB_ROOT, SIGNAL_INDEX_V2_LIAB_TOTAL, SIGNAL_INDEX_V2_PERIOD, SIGNAL_INDEX_V2_RESERVE_COMMITMENT, SIGNAL_INDEX_V2_SOLVENT, N_ASSETS_V3, N_PUBLIC_SIGNALS_V3, SIGNAL_INDEX_V3_AGGREGATE_SOLVENT, SIGNAL_INDEX_V3_ASSET_SOLVENT_BASE, SIGNAL_INDEX_V3_PERIOD, SIGNAL_INDEX_V3_PRICE_COMMITMENT, SIGNAL_INDEX_V3_RESERVE_COMMITMENT, } from "./constants.js";
+import { StellarisError } from "./errors.js";
+const FIELD_DECIMAL = /^(0|[1-9][0-9]*)$/;
+export function assertFieldElement(value, label) {
+    if (!FIELD_DECIMAL.test(value)) {
+        throw StellarisError.validation(`${label} must be a decimal field element string`, { value });
+    }
+}
+export function parsePublicSignals(signals) {
+    if (signals.length !== N_PUBLIC_SIGNALS) {
+        throw StellarisError.validation(`expected ${N_PUBLIC_SIGNALS} public signals, got ${signals.length}`);
+    }
+    for (let i = 0; i < signals.length; i++) {
+        const value = signals[i];
+        if (value === undefined) {
+            throw StellarisError.validation(`publicSignals[${i}] is missing`);
+        }
+        assertFieldElement(value, `publicSignals[${i}]`);
+    }
+    const solventRaw = signals[SIGNAL_INDEX_SOLVENT];
+    const commitment = signals[SIGNAL_INDEX_COMMITMENT];
+    const liabilities = signals[SIGNAL_INDEX_LIABILITIES];
+    const period = signals[SIGNAL_INDEX_PERIOD];
+    if (solventRaw === undefined ||
+        commitment === undefined ||
+        liabilities === undefined ||
+        period === undefined) {
+        throw StellarisError.validation("public signals are missing required entries");
+    }
+    if (solventRaw !== "0" && solventRaw !== "1") {
+        throw StellarisError.validation("solvent public signal must be 0 or 1", { solventRaw });
+    }
+    return {
+        solvent: solventRaw === "1",
+        commitment,
+        liabilities: BigInt(liabilities),
+        periodId: BigInt(period),
+    };
+}
+export function encodePublicSignals(signals) {
+    if (signals.liabilities < 0n) {
+        throw StellarisError.validation("liabilities must be non-negative");
+    }
+    if (signals.periodId < 0n) {
+        throw StellarisError.validation("periodId must be non-negative");
+    }
+    assertFieldElement(signals.commitment, "commitment");
+    return [
+        signals.solvent ? "1" : "0",
+        signals.commitment,
+        signals.liabilities.toString(),
+        signals.periodId.toString(),
+    ];
+}
+/**
+ * Parse the v2 public-signal layout, mirroring the on-chain
+ * `parse_public_signals_v2` (contracts/stellaris/src/signals.rs):
+ *   [ solvent, reserveCommitment, liabRoot, liabTotal, period ]
+ *
+ * `reserveCommitment` and `liabRoot` are full-width field elements (hashes) kept
+ * as decimal strings; `liabTotal` is the SNARK-proven total liabilities.
+ */
+export function parsePublicSignalsV2(signals) {
+    if (signals.length !== N_PUBLIC_SIGNALS_V2) {
+        throw StellarisError.validation(`expected ${N_PUBLIC_SIGNALS_V2} v2 public signals, got ${signals.length}`);
+    }
+    for (let i = 0; i < signals.length; i++) {
+        const value = signals[i];
+        if (value === undefined) {
+            throw StellarisError.validation(`publicSignals[${i}] is missing`);
+        }
+        assertFieldElement(value, `publicSignals[${i}]`);
+    }
+    const solventRaw = signals[SIGNAL_INDEX_V2_SOLVENT];
+    const reserveCommitment = signals[SIGNAL_INDEX_V2_RESERVE_COMMITMENT];
+    const liabRoot = signals[SIGNAL_INDEX_V2_LIAB_ROOT];
+    const liabTotal = signals[SIGNAL_INDEX_V2_LIAB_TOTAL];
+    const period = signals[SIGNAL_INDEX_V2_PERIOD];
+    if (solventRaw === undefined ||
+        reserveCommitment === undefined ||
+        liabRoot === undefined ||
+        liabTotal === undefined ||
+        period === undefined) {
+        throw StellarisError.validation("v2 public signals are missing required entries");
+    }
+    if (solventRaw !== "0" && solventRaw !== "1") {
+        throw StellarisError.validation("solvent public signal must be 0 or 1", { solventRaw });
+    }
+    return {
+        solvent: solventRaw === "1",
+        reserveCommitment,
+        liabRoot,
+        liabTotal: BigInt(liabTotal),
+        periodId: BigInt(period),
+    };
+}
+export function encodePublicSignalsV2(signals) {
+    if (signals.liabTotal < 0n) {
+        throw StellarisError.validation("liabTotal must be non-negative");
+    }
+    if (signals.periodId < 0n) {
+        throw StellarisError.validation("periodId must be non-negative");
+    }
+    assertFieldElement(signals.reserveCommitment, "reserveCommitment");
+    assertFieldElement(signals.liabRoot, "liabRoot");
+    return [
+        signals.solvent ? "1" : "0",
+        signals.reserveCommitment,
+        signals.liabRoot,
+        signals.liabTotal.toString(),
+        signals.periodId.toString(),
+    ];
+}
+/**
+ * Parse the v3 multi-asset public-signal layout, mirroring the on-chain
+ * `parse_public_signals_v3` (contracts/stellaris/src/signals.rs):
+ *   [ aggregateSolvent, reserveCommitment, priceCommitment,
+ *     assetSolvent[0..N_ASSETS_V3-1], period ]
+ *
+ * `reserveCommitment`/`priceCommitment` are full-width field elements kept as
+ * decimal strings; the aggregate flag and each per-asset flag must be 0 or 1.
+ */
+export function parsePublicSignalsV3(signals) {
+    if (signals.length !== N_PUBLIC_SIGNALS_V3) {
+        throw StellarisError.validation(`expected ${N_PUBLIC_SIGNALS_V3} v3 public signals, got ${signals.length}`);
+    }
+    for (let i = 0; i < signals.length; i++) {
+        const value = signals[i];
+        if (value === undefined) {
+            throw StellarisError.validation(`publicSignals[${i}] is missing`);
+        }
+        assertFieldElement(value, `publicSignals[${i}]`);
+    }
+    const parseFlag = (value, label) => {
+        if (value === "1")
+            return true;
+        if (value === "0")
+            return false;
+        throw StellarisError.validation(`${label} must be 0 or 1`, { value });
+    };
+    const aggregateRaw = signals[SIGNAL_INDEX_V3_AGGREGATE_SOLVENT];
+    const reserveCommitment = signals[SIGNAL_INDEX_V3_RESERVE_COMMITMENT];
+    const priceCommitment = signals[SIGNAL_INDEX_V3_PRICE_COMMITMENT];
+    const period = signals[SIGNAL_INDEX_V3_PERIOD];
+    if (aggregateRaw === undefined ||
+        reserveCommitment === undefined ||
+        priceCommitment === undefined ||
+        period === undefined) {
+        throw StellarisError.validation("v3 public signals are missing required entries");
+    }
+    const assetSolvent = [];
+    for (let a = 0; a < N_ASSETS_V3; a++) {
+        const flag = signals[SIGNAL_INDEX_V3_ASSET_SOLVENT_BASE + a];
+        if (flag === undefined) {
+            throw StellarisError.validation(`assetSolvent[${a}] is missing`);
+        }
+        assetSolvent.push(parseFlag(flag, `assetSolvent[${a}]`));
+    }
+    return {
+        aggregateSolvent: parseFlag(aggregateRaw, "aggregateSolvent"),
+        reserveCommitment,
+        priceCommitment,
+        assetSolvent,
+        periodId: BigInt(period),
+    };
+}
+/**
+ * Encode the v3 multi-asset public-signal layout, the inverse of
+ * {@link parsePublicSignalsV3}. Produces the exact decimal-string vector the
+ * on-chain `parse_public_signals_v3` expects:
+ *   [ aggregateSolvent, reserveCommitment, priceCommitment,
+ *     assetSolvent[0..N_ASSETS_V3-1], period ]
+ *
+ * `assetSolvent` must contain exactly `N_ASSETS_V3` flags; a different length is
+ * a programming error and is rejected rather than silently padded/truncated.
+ */
+export function encodePublicSignalsV3(signals) {
+    if (signals.assetSolvent.length !== N_ASSETS_V3) {
+        throw StellarisError.validation(`assetSolvent must have exactly ${N_ASSETS_V3} entries, got ${signals.assetSolvent.length}`);
+    }
+    if (signals.periodId < 0n) {
+        throw StellarisError.validation("periodId must be non-negative");
+    }
+    assertFieldElement(signals.reserveCommitment, "reserveCommitment");
+    assertFieldElement(signals.priceCommitment, "priceCommitment");
+    return [
+        signals.aggregateSolvent ? "1" : "0",
+        signals.reserveCommitment,
+        signals.priceCommitment,
+        ...signals.assetSolvent.map((flag) => (flag ? "1" : "0")),
+        signals.periodId.toString(),
+    ];
+}

package/dist/stellar.d.ts

@@ -0,0 +1,129 @@
+/**
+ * High-level Stellaris contract client.
+ *
+ * This module composes codec + transport + domain types. It does not contain
+ * UI or demo mocks. Integrators can supply a real SorobanTransport backed by
+ * @stellar/stellar-sdk, a server signer, or a test harness.
+ */
+import { Attestation, AttestationReceipt, AttestationV2, AttestationReceiptV2, AttestationV3, AttestationReceiptV3, ContractDeployment, FieldElement, ProofBundle, ProofBundleV2, ProofBundleV3, PublicKey, VerificationKeyDocument } from "./domain.js";
+import { TransactionSigner, SorobanTransport, TransactionPlan } from "./transport.js";
+export declare enum ContractErrorCode {
+    NotInitialized = 1,
+    AlreadyInitialized = 2,
+    Unauthorized = 3,
+    ProofInvalid = 4,
+    NotSolvent = 5,
+    PeriodAlreadyAttested = 6,
+    BadPublicSignals = 7,
+    BadProofEncoding = 8,
+    BadLiabilityRoot = 9,
+    WrongVerifierVersion = 10,
+    OracleMismatch = 11,
+    OracleNotConfigured = 12,
+    CustodianNotConfigured = 13,
+    CustodianSigInvalid = 14
+}
+export declare class ContractError extends Error {
+    readonly code: ContractErrorCode;
+    constructor(code: number);
+}
+export interface StellarisClientOptions {
+    readonly deployment: ContractDeployment;
+    readonly transport?: SorobanTransport;
+}
+export interface InitParams {
+    readonly admin: PublicKey;
+    readonly verificationKey: VerificationKeyDocument;
+    readonly signer: TransactionSigner;
+}
+export interface AttestParams {
+    readonly issuer: PublicKey;
+    readonly bundle: ProofBundle;
+    readonly signer: TransactionSigner;
+}
+export interface AttestV2Params {
+    readonly issuer: PublicKey;
+    readonly bundle: ProofBundleV2;
+    readonly signer: TransactionSigner;
+}
+export interface AttestV3Params {
+    readonly issuer: PublicKey;
+    readonly bundle: ProofBundleV3;
+    readonly signer: TransactionSigner;
+}
+export declare class StellarisClient {
+    readonly deployment: ContractDeployment;
+    private readonly transport;
+    constructor(options: StellarisClientOptions);
+    init(params: InitParams): Promise<void>;
+    attest(params: AttestParams): Promise<AttestationReceipt>;
+    getAttestation(issuer: PublicKey, periodId: bigint): Promise<Attestation | null>;
+    /**
+     * v2 attest: solvency with a SNARK-proven liability total. The proof bundle's
+     * public signals carry the circuit-computed `liabRoot`/`liabTotal`; the
+     * contract codec serializes the raw snarkjs proof via the shared encoder.
+     */
+    attestV2(params: AttestV2Params): Promise<AttestationReceiptV2>;
+    getAttestationV2(issuer: PublicKey, periodId: bigint): Promise<AttestationV2 | null>;
+    /**
+     * v3 attest: multi-asset solvency with an oracle-priced aggregate. The proof
+     * bundle's public signals carry the per-asset solvency flags + the aggregate
+     * flag + the reserve/price commitments; the contract requires the AGGREGATE to
+     * be solvent and stores the per-asset breakdown for transparency.
+     */
+    attestV3(params: AttestV3Params): Promise<AttestationReceiptV3>;
+    getAttestationV3(issuer: PublicKey, periodId: bigint): Promise<AttestationV3 | null>;
+    listPeriods(issuer: PublicKey): Promise<readonly bigint[]>;
+    getVerificationKey(): Promise<VerificationKeyDocument | null>;
+    getAdmin(): Promise<PublicKey | null>;
+    /**
+     * Designate the price-oracle authority (admin-gated on-chain). `admin` must be
+     * the contract admin and must sign.
+     */
+    setOracle(params: {
+        readonly admin: PublicKey;
+        readonly oracle: PublicKey;
+        readonly signer: TransactionSigner;
+    }): Promise<void>;
+    /**
+     * Publish the authoritative price commitment for a period (oracle-gated
+     * on-chain). `oracle` must be the designated oracle and must sign. A later
+     * `attestV3` for the same period must present a matching `priceCommitment` or
+     * be rejected with `OracleMismatch`.
+     */
+    publishOracleCommitment(params: {
+        readonly oracle: PublicKey;
+        readonly periodId: bigint;
+        readonly commitment: FieldElement;
+        readonly signer: TransactionSigner;
+    }): Promise<void>;
+    getOracle(): Promise<PublicKey | null>;
+    getOracleCommitment(periodId: bigint): Promise<FieldElement | null>;
+    /**
+     * Designate the custodian BLS12-381 public key (G2), admin-gated on-chain.
+     * `pk` is the serialized G2 point (the transport/codec encodes it); `admin`
+     * must be the contract admin and must sign.
+     */
+    setCustodian(params: {
+        readonly admin: PublicKey;
+        readonly custodianPublicKey: unknown;
+        readonly signer: TransactionSigner;
+    }): Promise<void>;
+    /**
+     * Attest multi-asset solvency WITH a custodian BLS signature over the
+     * reserveCommitment. Like `attestV3` but additionally requires (and the
+     * contract verifies on-chain) a real BLS12-381 signature from the designated
+     * custodian; on success the attestation is stamped `custodianBound=true`.
+     * `custodianSig` is the serialized G1 signature point.
+     */
+    attestV3Signed(params: {
+        readonly issuer: PublicKey;
+        readonly bundle: ProofBundleV3;
+        readonly custodianSig: unknown;
+        readonly signer: TransactionSigner;
+    }): Promise<AttestationReceiptV3>;
+    getCustodian(): Promise<string | null>;
+    plan(operation: TransactionPlan["operation"], args: readonly unknown[]): TransactionPlan;
+    private assertSigner;
+}
+export declare function createStellarisClient(options: StellarisClientOptions): StellarisClient;