@stellaris-lab/por-sdk 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @stellaris-lab/por-sdk
+
+TypeScript/JavaScript SDK for Stellaris proof-of-reserves and solvency-gated minting flows on Stellar Soroban.
+
+The SDK provides deterministic protocol utilities, local proof verification helpers, public-signal parsing/encoding, and Soroban client abstractions for issuer, verifier, and operator applications.
+
+## Install
+
+```bash
+npm install @stellaris-lab/por-sdk
+```
+
+## Requirements
+
+- Node.js 20+
+- ESM-compatible runtime
+- Circuit artifacts when generating proofs locally
+
+## Public Signal Parsing
+
+```ts
+import { parsePublicSignalsV3, encodePublicSignalsV3 } from "@stellaris-lab/por-sdk";
+
+const signals = [
+  "1",
+  "28184704509896798694171806401809735674629341338708097298840167762771603184872",
+  "38920107329329417419205137842949329405942847694151540866319542913651737474578",
+  "0",
+  "1",
+  "1",
+  "1",
+  "9",
+];
+
+const parsed = parsePublicSignalsV3(signals);
+const encoded = encodePublicSignalsV3(parsed);
+```
+
+## Local Proof Verification
+
+```ts
+import { verifyLocal } from "@stellaris-lab/por-sdk";
+
+const ok = await verifyLocal(verificationKey, proofBundle);
+```
+
+## Protocol Compatibility
+
+This package is tested against the language-neutral vectors in:
+
+```txt
+../protocol-spec/test-vectors/public-signals.json
+```
+
+The same vectors are also used by the Rust SDK, which keeps JS, TS, and Rust implementations aligned on public-signal order and validation rules.
+
+## Publish Checklist
+
+Before publishing a release:
+
+```bash
+npm run check
+npm pack --dry-run
+npm publish --access public
+```
+
+The package intentionally publishes only:
+
+```txt
+dist/
+README.md
+package.json
+```
+
+## Status
+
+Version `0.1.0` is a developer-preview SDK for audited testnet/demo flows. Production users should pin exact versions and verify deployed contract IDs, WASM hashes, circuit artifacts, and verification keys.

package/dist/audit.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Audit artifacts for prover/Stellaris workflows.
+ *
+ * These records are safe to persist in backend logs or attach to operational run
+ * books. They intentionally exclude reserve balances and salts.
+ */
+import { AttestationReceipt, ContractDeployment, PeriodId, PublicKey, PublicSignals } from "./domain.js";
+import { PolicyReport } from "./policy.js";
+export type AuditStepStatus = "started" | "accepted" | "rejected" | "failed" | "submitted";
+export interface AuditStep {
+    readonly at: string;
+    readonly name: string;
+    readonly status: AuditStepStatus;
+    readonly message?: string;
+    readonly context?: Record<string, unknown>;
+}
+export interface AttestationAuditLog {
+    readonly schemaVersion: "stellaris.audit.v1";
+    readonly workflowId: string;
+    readonly issuer: PublicKey;
+    readonly periodId: PeriodId;
+    readonly deployment: ContractDeployment;
+    readonly publicSignals?: PublicSignals;
+    readonly policyReport?: PolicyReport;
+    readonly receipt?: AttestationReceipt;
+    readonly steps: readonly AuditStep[];
+}
+export interface AuditSink {
+    record(step: AuditStep): void | Promise<void>;
+}
+export declare class InMemoryAuditSink implements AuditSink {
+    private readonly entries;
+    record(step: AuditStep): void;
+    snapshot(): readonly AuditStep[];
+}
+export declare function makeWorkflowId(issuer: PublicKey, periodId: PeriodId): string;
+export declare function redactPublicSignals(signals: PublicSignals): PublicSignals;
+export declare function makeAuditStep(input: {
+    readonly name: string;
+    readonly status: AuditStepStatus;
+    readonly message?: string;
+    readonly context?: Record<string, unknown>;
+}): AuditStep;
+export declare function makeAuditLog(input: {
+    readonly workflowId: string;
+    readonly issuer: PublicKey;
+    readonly periodId: PeriodId;
+    readonly deployment: ContractDeployment;
+    readonly steps: readonly AuditStep[];
+    readonly publicSignals?: PublicSignals;
+    readonly policyReport?: PolicyReport;
+    readonly receipt?: AttestationReceipt;
+}): AttestationAuditLog;

package/dist/audit.js

@@ -0,0 +1,48 @@
+/**
+ * Audit artifacts for prover/Stellaris workflows.
+ *
+ * These records are safe to persist in backend logs or attach to operational run
+ * books. They intentionally exclude reserve balances and salts.
+ */
+export class InMemoryAuditSink {
+    entries = [];
+    record(step) {
+        this.entries.push(step);
+    }
+    snapshot() {
+        return [...this.entries];
+    }
+}
+export function makeWorkflowId(issuer, periodId) {
+    return `stellaris:${issuer}:${periodId}:${Date.now()}`;
+}
+export function redactPublicSignals(signals) {
+    return {
+        solvent: signals.solvent,
+        commitment: signals.commitment,
+        liabilities: signals.liabilities,
+        periodId: signals.periodId,
+    };
+}
+export function makeAuditStep(input) {
+    return {
+        at: new Date().toISOString(),
+        name: input.name,
+        status: input.status,
+        ...(input.message === undefined ? {} : { message: input.message }),
+        ...(input.context === undefined ? {} : { context: input.context }),
+    };
+}
+export function makeAuditLog(input) {
+    return {
+        schemaVersion: "stellaris.audit.v1",
+        workflowId: input.workflowId,
+        issuer: input.issuer,
+        periodId: input.periodId,
+        deployment: input.deployment,
+        steps: [...input.steps],
+        ...(input.publicSignals === undefined ? {} : { publicSignals: redactPublicSignals(input.publicSignals) }),
+        ...(input.policyReport === undefined ? {} : { policyReport: input.policyReport }),
+        ...(input.receipt === undefined ? {} : { receipt: input.receipt }),
+    };
+}

package/dist/backend.d.ts

@@ -0,0 +1,70 @@
+/**
+ * backend.ts — swappable proving-backend seam (Milestone D1, SDK side).
+ *
+ * The contract abstracts verification behind a `VerifierBackend` trait
+ * (contracts/stellaris/src/verifier.rs); this is the symmetric SDK abstraction
+ * for PROOF GENERATION. `prove.ts` historically hardcoded `snarkjs.groth16`;
+ * this interface makes Groth16 ONE implementation, not a baked-in assumption, so
+ * a future PLONK / post-quantum backend can plug in without touching the attest
+ * pipeline, the public-signal ABI, or the byte-encoding boundary.
+ *
+ * Design (deliberately minimal — no speculative second backend is shipped):
+ *   - `ProvingBackend`   : interface { version, prove(witnessInput, artifacts),
+ *                          verify(vk, bundle) }
+ *   - `Groth16Backend`   : the real, only implementation (snarkjs groth16)
+ *   - `ProvingVersion`   : on-the-wire backend tag, mirrors the contract's
+ *                          `VerifierVersion` (Groth16 = 1; 0 is unset/invalid)
+ *
+ * The proof-shape (`SnarkJsGroth16Proof`) and `ProofBundle` are unchanged: only
+ * the call seam is abstracted. Witness construction stays in prove.ts because it
+ * is statement-specific (reserve vector), not backend-specific.
+ */
+import { ProofBundle, ProvingArtifacts } from "./domain.js";
+/**
+ * On-the-wire backend selector. Mirrors the contract's `VerifierVersion`
+ * (verifier.rs): Groth16 is `1`, leaving `0` as an explicit "unset/invalid"
+ * sentinel. A manifest or SDK caller can request a specific backend by tag.
+ */
+export declare enum ProvingVersion {
+    Groth16 = 1
+}
+/** The witness input shape a backend feeds its prover (statement-specific). */
+export interface WitnessInput {
+    readonly [signal: string]: string | string[];
+}
+/**
+ * A proof-generation/verification backend. Groth16 is the only backend today;
+ * a future backend implements this same interface so `generateProofFromInput`
+ * and the attest pipeline are backend-agnostic.
+ */
+export interface ProvingBackend {
+    /** The on-the-wire version tag this backend answers to. */
+    readonly version: ProvingVersion;
+    /** Generate a proof bundle from a witness input + proving artifacts. */
+    prove(witnessInput: WitnessInput, artifacts: ProvingArtifacts): Promise<ProofBundle>;
+    /** Verify a proof bundle locally against a verification key document. */
+    verify(verificationKey: Record<string, unknown>, bundle: ProofBundle): Promise<boolean>;
+}
+/**
+ * The Groth16 backend — the real, only implementation. Wraps snarkjs groth16,
+ * the exact code path `prove.ts` used before the seam existed.
+ */
+export declare class Groth16Backend implements ProvingBackend {
+    readonly version = ProvingVersion.Groth16;
+    prove(witnessInput: WitnessInput, artifacts: ProvingArtifacts): Promise<ProofBundle>;
+    verify(verificationKey: Record<string, unknown>, bundle: ProofBundle): Promise<boolean>;
+}
+/**
+ * Resolve a backend by version tag. Today only Groth16 resolves. Unknown tags
+ * throw, mirroring the contract's `WrongVerifierVersion`.
+ *
+ * SCOPE (honest boundary): a new SDK backend is one more arm here, but that is
+ * only the proving half. A different proof shape also needs a contract entrypoint
+ * that accepts it (the Soroban `attest*` signatures bind the concrete proof type
+ * into XDR) plus its own on-chain verifier — NOT just a `dispatch_verify` arm.
+ * This resolver is the SDK-side version-routing seam, not a claim that a new
+ * proving system is free.
+ */
+export declare function backendFor(version: ProvingVersion): ProvingBackend;
+/** The default backend the SDK uses when no explicit backend is requested. */
+export declare const DEFAULT_PROVING_BACKEND: ProvingBackend;

package/dist/backend.js

@@ -0,0 +1,91 @@
+/**
+ * backend.ts — swappable proving-backend seam (Milestone D1, SDK side).
+ *
+ * The contract abstracts verification behind a `VerifierBackend` trait
+ * (contracts/stellaris/src/verifier.rs); this is the symmetric SDK abstraction
+ * for PROOF GENERATION. `prove.ts` historically hardcoded `snarkjs.groth16`;
+ * this interface makes Groth16 ONE implementation, not a baked-in assumption, so
+ * a future PLONK / post-quantum backend can plug in without touching the attest
+ * pipeline, the public-signal ABI, or the byte-encoding boundary.
+ *
+ * Design (deliberately minimal — no speculative second backend is shipped):
+ *   - `ProvingBackend`   : interface { version, prove(witnessInput, artifacts),
+ *                          verify(vk, bundle) }
+ *   - `Groth16Backend`   : the real, only implementation (snarkjs groth16)
+ *   - `ProvingVersion`   : on-the-wire backend tag, mirrors the contract's
+ *                          `VerifierVersion` (Groth16 = 1; 0 is unset/invalid)
+ *
+ * The proof-shape (`SnarkJsGroth16Proof`) and `ProofBundle` are unchanged: only
+ * the call seam is abstracted. Witness construction stays in prove.ts because it
+ * is statement-specific (reserve vector), not backend-specific.
+ */
+import { StellarisError, wrapUnknown } from "./errors.js";
+import { assertVerificationKeyShape } from "./manifest.js";
+import { parsePublicSignals } from "./signals.js";
+/**
+ * On-the-wire backend selector. Mirrors the contract's `VerifierVersion`
+ * (verifier.rs): Groth16 is `1`, leaving `0` as an explicit "unset/invalid"
+ * sentinel. A manifest or SDK caller can request a specific backend by tag.
+ */
+export var ProvingVersion;
+(function (ProvingVersion) {
+    ProvingVersion[ProvingVersion["Groth16"] = 1] = "Groth16";
+})(ProvingVersion || (ProvingVersion = {}));
+/**
+ * The Groth16 backend — the real, only implementation. Wraps snarkjs groth16,
+ * the exact code path `prove.ts` used before the seam existed.
+ */
+export class Groth16Backend {
+    version = ProvingVersion.Groth16;
+    async prove(witnessInput, artifacts) {
+        if (artifacts.verificationKey) {
+            assertVerificationKeyShape(artifacts.verificationKey);
+        }
+        try {
+            const snarkjs = await import("snarkjs");
+            const { proof, publicSignals } = await snarkjs.groth16.fullProve(witnessInput, artifacts.wasmUrl, artifacts.zkeyUrl);
+            const parsed = parsePublicSignals(publicSignals);
+            return {
+                proof: proof,
+                publicSignals,
+                parsed,
+            };
+        }
+        catch (cause) {
+            if (cause instanceof StellarisError) {
+                throw cause;
+            }
+            throw wrapUnknown("proving", "failed to generate Groth16 proof", cause);
+        }
+    }
+    async verify(verificationKey, bundle) {
+        try {
+            const snarkjs = await import("snarkjs");
+            return await snarkjs.groth16.verify(verificationKey, bundle.publicSignals, bundle.proof);
+        }
+        catch (cause) {
+            throw wrapUnknown("verification", "failed to verify proof locally", cause);
+        }
+    }
+}
+/**
+ * Resolve a backend by version tag. Today only Groth16 resolves. Unknown tags
+ * throw, mirroring the contract's `WrongVerifierVersion`.
+ *
+ * SCOPE (honest boundary): a new SDK backend is one more arm here, but that is
+ * only the proving half. A different proof shape also needs a contract entrypoint
+ * that accepts it (the Soroban `attest*` signatures bind the concrete proof type
+ * into XDR) plus its own on-chain verifier — NOT just a `dispatch_verify` arm.
+ * This resolver is the SDK-side version-routing seam, not a claim that a new
+ * proving system is free.
+ */
+export function backendFor(version) {
+    switch (version) {
+        case ProvingVersion.Groth16:
+            return new Groth16Backend();
+        default:
+            throw StellarisError.validation(`unsupported proving backend version: ${version}`);
+    }
+}
+/** The default backend the SDK uses when no explicit backend is requested. */
+export const DEFAULT_PROVING_BACKEND = new Groth16Backend();

package/dist/codec.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Encoding boundary for contract arguments.
+ *
+ * Keep all low-level proof/public-signal encoding in one module. When Stellar SDK
+ * exposes first-class BLS12-381 XDR helpers, only this file should change.
+ */
+import { Attestation, AttestationV2, AttestationV3, ProofBundle, SnarkJsGroth16Proof } from "./domain.js";
+import { ContractProofBytes } from "./encoding.js";
+export interface ContractProofArgs {
+    readonly a: readonly [string, string];
+    readonly b: readonly [readonly [string, string], readonly [string, string]];
+    readonly c: readonly [string, string];
+}
+export interface ContractAttestArgs {
+    readonly proof: ContractProofArgs;
+    readonly publicSignals: readonly string[];
+}
+/**
+ * Byte-exact `attest` arguments ready for ScVal wrapping by a transport.
+ * `proof` holds the G1/G2 uncompressed buffers; `publicSignals` are 32-byte
+ * big-endian U256 buffers in circuit declaration order. This is the single
+ * shared on-chain encoding — see `encoding.ts`.
+ */
+export interface ContractAttestBytes {
+    readonly proof: ContractProofBytes;
+    readonly publicSignals: readonly Uint8Array[];
+}
+export declare function proofToContractArgs(proof: SnarkJsGroth16Proof): ContractProofArgs;
+export declare function bundleToContractArgs(bundle: ProofBundle): ContractAttestArgs;
+/**
+ * Serialize a proof bundle to the byte-exact `attest` arguments the on-chain
+ * verifier consumes. This is the production encoding path: G1 points -> 96-byte
+ * uncompressed buffers, G2 -> 192-byte (with the c1||c0 Fp2 ordering), and each
+ * public signal -> a 32-byte big-endian U256 buffer. A transport only needs to
+ * wrap these in ScVal (ScBytes / ScU256) — no field math at the transport layer.
+ */
+export declare function bundleToContractBytes(bundle: ProofBundle): ContractAttestBytes;
+export declare function decodeAttestation(raw: unknown): Attestation;
+/**
+ * Decode a v2 attestation (solvency with SNARK-proven liabilities). `liabRoot`
+ * is a full-width field element (a hash) kept as a string; `liabTotal` is the
+ * proven total liabilities.
+ */
+export declare function decodeAttestationV2(raw: unknown): AttestationV2;
+/**
+ * Decode a v3 multi-asset attestation. `assetSolvent` is the per-asset flag
+ * vector (Soroban returns it as an array of bools); `reserveCommitment` and
+ * `priceCommitment` are full-width field elements kept as strings.
+ */
+export declare function decodeAttestationV3(raw: unknown): AttestationV3;

package/dist/codec.js

@@ -0,0 +1,110 @@
+/**
+ * Encoding boundary for contract arguments.
+ *
+ * Keep all low-level proof/public-signal encoding in one module. When Stellar SDK
+ * exposes first-class BLS12-381 XDR helpers, only this file should change.
+ */
+import { proofToBytes, signalToBytes, } from "./encoding.js";
+import { StellarisError } from "./errors.js";
+import { parsePublicSignals } from "./signals.js";
+export function proofToContractArgs(proof) {
+    if (!Array.isArray(proof.pi_a) || !Array.isArray(proof.pi_b) || !Array.isArray(proof.pi_c)) {
+        throw StellarisError.encoding("invalid snarkjs proof shape");
+    }
+    return {
+        a: [proof.pi_a[0], proof.pi_a[1]],
+        b: [
+            [proof.pi_b[0][0], proof.pi_b[0][1]],
+            [proof.pi_b[1][0], proof.pi_b[1][1]],
+        ],
+        c: [proof.pi_c[0], proof.pi_c[1]],
+    };
+}
+export function bundleToContractArgs(bundle) {
+    const parsed = parsePublicSignals(bundle.publicSignals);
+    if (parsed.commitment !== bundle.parsed.commitment) {
+        throw StellarisError.encoding("bundle parsed commitment differs from raw public signals");
+    }
+    return {
+        proof: proofToContractArgs(bundle.proof),
+        publicSignals: [...bundle.publicSignals],
+    };
+}
+/**
+ * Serialize a proof bundle to the byte-exact `attest` arguments the on-chain
+ * verifier consumes. This is the production encoding path: G1 points -> 96-byte
+ * uncompressed buffers, G2 -> 192-byte (with the c1||c0 Fp2 ordering), and each
+ * public signal -> a 32-byte big-endian U256 buffer. A transport only needs to
+ * wrap these in ScVal (ScBytes / ScU256) — no field math at the transport layer.
+ */
+export function bundleToContractBytes(bundle) {
+    const parsed = parsePublicSignals(bundle.publicSignals);
+    if (parsed.commitment !== bundle.parsed.commitment) {
+        throw StellarisError.encoding("bundle parsed commitment differs from raw public signals");
+    }
+    return {
+        proof: proofToBytes(bundle.proof),
+        publicSignals: bundle.publicSignals.map((s) => signalToBytes(s)),
+    };
+}
+export function decodeAttestation(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw StellarisError.encoding("attestation response is not an object");
+    }
+    const value = raw;
+    return {
+        commitment: String(value.commitment),
+        liabilities: BigInt(String(value.liabilities)),
+        solvent: Boolean(value.solvent),
+        ledgerTs: BigInt(String(value.ledgerTs ?? value.ledger_ts ?? 0)),
+        periodId: BigInt(String(value.periodId ?? value.period_id)),
+        issuer: String(value.issuer),
+    };
+}
+/**
+ * Decode a v2 attestation (solvency with SNARK-proven liabilities). `liabRoot`
+ * is a full-width field element (a hash) kept as a string; `liabTotal` is the
+ * proven total liabilities.
+ */
+export function decodeAttestationV2(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw StellarisError.encoding("v2 attestation response is not an object");
+    }
+    const value = raw;
+    return {
+        reserveCommitment: String(value.reserveCommitment ?? value.reserve_commitment),
+        liabRoot: String(value.liabRoot ?? value.liab_root),
+        liabTotal: BigInt(String(value.liabTotal ?? value.liab_total)),
+        solvent: Boolean(value.solvent),
+        ledgerTs: BigInt(String(value.ledgerTs ?? value.ledger_ts ?? 0)),
+        periodId: BigInt(String(value.periodId ?? value.period_id)),
+        issuer: String(value.issuer),
+    };
+}
+/**
+ * Decode a v3 multi-asset attestation. `assetSolvent` is the per-asset flag
+ * vector (Soroban returns it as an array of bools); `reserveCommitment` and
+ * `priceCommitment` are full-width field elements kept as strings.
+ */
+export function decodeAttestationV3(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw StellarisError.encoding("v3 attestation response is not an object");
+    }
+    const value = raw;
+    const rawFlags = value.assetSolvent ?? value.asset_solvent ?? [];
+    if (!Array.isArray(rawFlags)) {
+        throw StellarisError.encoding("v3 assetSolvent is not an array");
+    }
+    const assetSolvent = rawFlags.map((f) => Boolean(typeof f === "string" ? f === "1" || f === "true" : f));
+    return {
+        aggregateSolvent: Boolean(value.aggregateSolvent ?? value.aggregate_solvent),
+        reserveCommitment: String(value.reserveCommitment ?? value.reserve_commitment),
+        priceCommitment: String(value.priceCommitment ?? value.price_commitment),
+        assetSolvent,
+        oracleBound: Boolean(value.oracleBound ?? value.oracle_bound),
+        custodianBound: Boolean(value.custodianBound ?? value.custodian_bound),
+        ledgerTs: BigInt(String(value.ledgerTs ?? value.ledger_ts ?? 0)),
+        periodId: BigInt(String(value.periodId ?? value.period_id)),
+        issuer: String(value.issuer),
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * constants.ts — Public signal order, circuit parameters, and contract metadata.
+ *
+ * These must match:
+ *   - `circuits/PUBLIC_SIGNALS.md`   (generated from snarkjs)
+ *   - `contracts/stellaris/src/types.rs` (SIG_* constants)
+ *
+ * If the circuit compilation changes the signal order, update ONLY
+ * `circuits/PUBLIC_SIGNALS.md`, then synchronize this file.
+ */
+export declare const SIGNAL_INDEX_SOLVENT = 0;
+export declare const SIGNAL_INDEX_COMMITMENT = 1;
+export declare const SIGNAL_INDEX_LIABILITIES = 2;
+export declare const SIGNAL_INDEX_PERIOD = 3;
+export declare const N_PUBLIC_SIGNALS = 4;
+export declare const SIGNAL_INDEX_V2_SOLVENT = 0;
+export declare const SIGNAL_INDEX_V2_RESERVE_COMMITMENT = 1;
+export declare const SIGNAL_INDEX_V2_LIAB_ROOT = 2;
+export declare const SIGNAL_INDEX_V2_LIAB_TOTAL = 3;
+export declare const SIGNAL_INDEX_V2_PERIOD = 4;
+export declare const N_PUBLIC_SIGNALS_V2 = 5;
+export declare const SIGNAL_INDEX_V3_AGGREGATE_SOLVENT = 0;
+export declare const SIGNAL_INDEX_V3_RESERVE_COMMITMENT = 1;
+export declare const SIGNAL_INDEX_V3_PRICE_COMMITMENT = 2;
+export declare const SIGNAL_INDEX_V3_ASSET_SOLVENT_BASE = 3;
+export declare const N_ASSETS_V3 = 4;
+export declare const SIGNAL_INDEX_V3_PERIOD: number;
+export declare const N_PUBLIC_SIGNALS_V3: number;
+/** Number of reserve balance slots in the proof-of-reserves circuit. */
+export declare const N_RESERVES = 16;
+/** Bit-width of each reserve balance (64-bit unsigned integers). */
+export declare const N_BITS = 64;
+/** Maximum reserve balance value (2^64 - 1). */
+export declare const MAX_RESERVE: bigint;
+export declare const CURVE = "bls12381";

package/dist/constants.js

@@ -0,0 +1,60 @@
+/**
+ * constants.ts — Public signal order, circuit parameters, and contract metadata.
+ *
+ * These must match:
+ *   - `circuits/PUBLIC_SIGNALS.md`   (generated from snarkjs)
+ *   - `contracts/stellaris/src/types.rs` (SIG_* constants)
+ *
+ * If the circuit compilation changes the signal order, update ONLY
+ * `circuits/PUBLIC_SIGNALS.md`, then synchronize this file.
+ */
+// ---------------------------------------------------------------------------
+// Public signal indices (lock-step with circuits/PUBLIC_SIGNALS.md)
+// Expected order from snarkjs: [ solvent, commitment, liabilities, period ]
+// ---------------------------------------------------------------------------
+export const SIGNAL_INDEX_SOLVENT = 0;
+export const SIGNAL_INDEX_COMMITMENT = 1;
+export const SIGNAL_INDEX_LIABILITIES = 2;
+export const SIGNAL_INDEX_PERIOD = 3;
+export const N_PUBLIC_SIGNALS = 4;
+// ---------------------------------------------------------------------------
+// v2 public signal indices (solvency with SNARK-proven liabilities).
+// Expected order from snarkjs:
+//   [ solvent, reserveCommitment, liabRoot, liabTotal, period ]
+// Lock-step with contracts/stellaris/src/types.rs (SIG2_* constants).
+// ---------------------------------------------------------------------------
+export const SIGNAL_INDEX_V2_SOLVENT = 0;
+export const SIGNAL_INDEX_V2_RESERVE_COMMITMENT = 1;
+export const SIGNAL_INDEX_V2_LIAB_ROOT = 2;
+export const SIGNAL_INDEX_V2_LIAB_TOTAL = 3;
+export const SIGNAL_INDEX_V2_PERIOD = 4;
+export const N_PUBLIC_SIGNALS_V2 = 5;
+// ---------------------------------------------------------------------------
+// v3 public signal indices (multi-asset solvency with oracle-priced aggregate).
+// Expected order from snarkjs:
+//   [ aggregateSolvent, reserveCommitment, priceCommitment,
+//     assetSolvent[0..N_ASSETS_V3-1], period ]
+// Lock-step with contracts/stellaris/src/types.rs (SIG3_* constants) and
+// circuits/PUBLIC_SIGNALS.md.
+// ---------------------------------------------------------------------------
+export const SIGNAL_INDEX_V3_AGGREGATE_SOLVENT = 0;
+export const SIGNAL_INDEX_V3_RESERVE_COMMITMENT = 1;
+export const SIGNAL_INDEX_V3_PRICE_COMMITMENT = 2;
+export const SIGNAL_INDEX_V3_ASSET_SOLVENT_BASE = 3; // assetSolvent[a] at base + a
+export const N_ASSETS_V3 = 4;
+export const SIGNAL_INDEX_V3_PERIOD = SIGNAL_INDEX_V3_ASSET_SOLVENT_BASE + N_ASSETS_V3; // 7
+export const N_PUBLIC_SIGNALS_V3 = SIGNAL_INDEX_V3_PERIOD + 1; // 8
+// ---------------------------------------------------------------------------
+// Circuit parameters
+// ---------------------------------------------------------------------------
+/** Number of reserve balance slots in the proof-of-reserves circuit. */
+export const N_RESERVES = 16;
+/** Bit-width of each reserve balance (64-bit unsigned integers). */
+export const N_BITS = 64;
+/** Maximum reserve balance value (2^64 - 1). */
+export const MAX_RESERVE = (1n << BigInt(N_BITS)) - 1n;
+// ---------------------------------------------------------------------------
+// Curve identifier matching the compiled circuit and Soroban verifier.
+// BLS12-381 per the official Stellar groth16_verifier example.
+// ---------------------------------------------------------------------------
+export const CURVE = "bls12381";