@stellaris-lab/por-sdk 0.1.0

package/dist/stellar.js

@@ -0,0 +1,256 @@
+/**
+ * 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 { bundleToContractArgs, decodeAttestation, decodeAttestationV2, decodeAttestationV3, } from "./codec.js";
+import { StellarisError } from "./errors.js";
+import { UnconfiguredSorobanTransport } from "./transport.js";
+export var ContractErrorCode;
+(function (ContractErrorCode) {
+    ContractErrorCode[ContractErrorCode["NotInitialized"] = 1] = "NotInitialized";
+    ContractErrorCode[ContractErrorCode["AlreadyInitialized"] = 2] = "AlreadyInitialized";
+    ContractErrorCode[ContractErrorCode["Unauthorized"] = 3] = "Unauthorized";
+    ContractErrorCode[ContractErrorCode["ProofInvalid"] = 4] = "ProofInvalid";
+    ContractErrorCode[ContractErrorCode["NotSolvent"] = 5] = "NotSolvent";
+    ContractErrorCode[ContractErrorCode["PeriodAlreadyAttested"] = 6] = "PeriodAlreadyAttested";
+    ContractErrorCode[ContractErrorCode["BadPublicSignals"] = 7] = "BadPublicSignals";
+    ContractErrorCode[ContractErrorCode["BadProofEncoding"] = 8] = "BadProofEncoding";
+    ContractErrorCode[ContractErrorCode["BadLiabilityRoot"] = 9] = "BadLiabilityRoot";
+    ContractErrorCode[ContractErrorCode["WrongVerifierVersion"] = 10] = "WrongVerifierVersion";
+    ContractErrorCode[ContractErrorCode["OracleMismatch"] = 11] = "OracleMismatch";
+    ContractErrorCode[ContractErrorCode["OracleNotConfigured"] = 12] = "OracleNotConfigured";
+    ContractErrorCode[ContractErrorCode["CustodianNotConfigured"] = 13] = "CustodianNotConfigured";
+    ContractErrorCode[ContractErrorCode["CustodianSigInvalid"] = 14] = "CustodianSigInvalid";
+})(ContractErrorCode || (ContractErrorCode = {}));
+const ERROR_MESSAGES = {
+    [ContractErrorCode.NotInitialized]: "Contract not initialized",
+    [ContractErrorCode.AlreadyInitialized]: "Contract already initialized",
+    [ContractErrorCode.Unauthorized]: "Issuer authorization missing",
+    [ContractErrorCode.ProofInvalid]: "Groth16 proof verification failed",
+    [ContractErrorCode.NotSolvent]: "Issuer is not solvent",
+    [ContractErrorCode.PeriodAlreadyAttested]: "Period already attested",
+    [ContractErrorCode.BadPublicSignals]: "Bad public signals",
+    [ContractErrorCode.BadProofEncoding]: "Bad proof encoding",
+    [ContractErrorCode.BadLiabilityRoot]: "Bad liability root",
+    [ContractErrorCode.WrongVerifierVersion]: "Unsupported verifier backend version",
+    [ContractErrorCode.OracleMismatch]: "Price commitment does not match the published oracle commitment",
+    [ContractErrorCode.OracleNotConfigured]: "No designated price oracle configured",
+    [ContractErrorCode.CustodianNotConfigured]: "No designated custodian configured",
+    [ContractErrorCode.CustodianSigInvalid]: "Custodian BLS signature verification failed",
+};
+export class ContractError extends Error {
+    code;
+    constructor(code) {
+        super(`[ContractError(${code})] ${ERROR_MESSAGES[code] ?? "Unknown contract error"}`);
+        this.name = "ContractError";
+        this.code = code;
+    }
+}
+export class StellarisClient {
+    deployment;
+    transport;
+    constructor(options) {
+        this.deployment = options.deployment;
+        this.transport = options.transport ?? new UnconfiguredSorobanTransport();
+    }
+    async init(params) {
+        this.assertSigner(params.admin, params.signer);
+        const plan = this.plan("init", [params.admin, params.verificationKey]);
+        await this.transport.invoke(plan, params.signer);
+    }
+    async attest(params) {
+        this.assertSigner(params.issuer, params.signer);
+        // Validate bundle consistency (commitment vs. public signals) before submit.
+        // This throws on a malformed bundle without mutating anything.
+        bundleToContractArgs(params.bundle);
+        // Pass the raw snarkjs proof object + decimal public signals. The transport's
+        // contract codec serializes them to the on-chain byte layout through the
+        // single shared SDK encoder (encoding.ts). The decimal `{a,b,c}` tuple from
+        // bundleToContractArgs is a display/inspection shape only — not submitted.
+        const plan = this.plan("attest", [
+            params.issuer,
+            params.bundle.proof,
+            [...params.bundle.publicSignals],
+        ]);
+        const result = await this.transport.invoke(plan, params.signer);
+        const attestation = decodeAttestation(result.value);
+        return {
+            attestation,
+            networkPassphrase: this.deployment.networkPassphrase,
+            contractId: this.deployment.contractId,
+            ...(result.transactionHash === undefined ? {} : { transactionHash: result.transactionHash }),
+            ...(result.ledger === undefined ? {} : { ledger: result.ledger }),
+        };
+    }
+    async getAttestation(issuer, periodId) {
+        const plan = this.plan("get_attestation", [issuer, periodId.toString()]);
+        const value = await this.transport.simulate(plan);
+        return value === null ? null : decodeAttestation(value);
+    }
+    /**
+     * 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.
+     */
+    async attestV2(params) {
+        this.assertSigner(params.issuer, params.signer);
+        const plan = this.plan("attest_v2", [
+            params.issuer,
+            params.bundle.proof,
+            [...params.bundle.publicSignals],
+        ]);
+        const result = await this.transport.invoke(plan, params.signer);
+        const attestation = decodeAttestationV2(result.value);
+        return {
+            attestation,
+            networkPassphrase: this.deployment.networkPassphrase,
+            contractId: this.deployment.contractId,
+            ...(result.transactionHash === undefined ? {} : { transactionHash: result.transactionHash }),
+            ...(result.ledger === undefined ? {} : { ledger: result.ledger }),
+        };
+    }
+    async getAttestationV2(issuer, periodId) {
+        const plan = this.plan("get_attestation_v2", [issuer, periodId.toString()]);
+        const value = await this.transport.simulate(plan);
+        return value === null ? null : decodeAttestationV2(value);
+    }
+    /**
+     * 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.
+     */
+    async attestV3(params) {
+        this.assertSigner(params.issuer, params.signer);
+        const plan = this.plan("attest_v3", [
+            params.issuer,
+            params.bundle.proof,
+            [...params.bundle.publicSignals],
+        ]);
+        const result = await this.transport.invoke(plan, params.signer);
+        const attestation = decodeAttestationV3(result.value);
+        return {
+            attestation,
+            networkPassphrase: this.deployment.networkPassphrase,
+            contractId: this.deployment.contractId,
+            ...(result.transactionHash === undefined ? {} : { transactionHash: result.transactionHash }),
+            ...(result.ledger === undefined ? {} : { ledger: result.ledger }),
+        };
+    }
+    async getAttestationV3(issuer, periodId) {
+        const plan = this.plan("get_attestation_v3", [issuer, periodId.toString()]);
+        const value = await this.transport.simulate(plan);
+        return value === null ? null : decodeAttestationV3(value);
+    }
+    async listPeriods(issuer) {
+        const plan = this.plan("list_periods", [issuer]);
+        const value = await this.transport.simulate(plan);
+        return value.map((period) => BigInt(String(period)));
+    }
+    async getVerificationKey() {
+        const plan = this.plan("get_vk", []);
+        return this.transport.simulate(plan);
+    }
+    async getAdmin() {
+        const plan = this.plan("get_admin", []);
+        const value = await this.transport.simulate(plan);
+        return value === null ? null : String(value);
+    }
+    // --- C3: designated price-oracle + per-period commitment binding ---------
+    /**
+     * Designate the price-oracle authority (admin-gated on-chain). `admin` must be
+     * the contract admin and must sign.
+     */
+    async setOracle(params) {
+        this.assertSigner(params.admin, params.signer);
+        const plan = this.plan("set_oracle", [params.oracle]);
+        await this.transport.invoke(plan, params.signer);
+    }
+    /**
+     * 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`.
+     */
+    async publishOracleCommitment(params) {
+        this.assertSigner(params.oracle, params.signer);
+        const plan = this.plan("publish_oracle_commitment", [
+            params.periodId.toString(),
+            params.commitment,
+        ]);
+        await this.transport.invoke(plan, params.signer);
+    }
+    async getOracle() {
+        const plan = this.plan("get_oracle", []);
+        const value = await this.transport.simulate(plan);
+        return value === null ? null : String(value);
+    }
+    async getOracleCommitment(periodId) {
+        const plan = this.plan("get_oracle_commitment", [periodId.toString()]);
+        const value = await this.transport.simulate(plan);
+        return value === null || value === undefined ? null : String(value);
+    }
+    // --- C2: designated custodian + BLS-signed reserve attestation -----------
+    /**
+     * 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.
+     */
+    async setCustodian(params) {
+        this.assertSigner(params.admin, params.signer);
+        const plan = this.plan("set_custodian", [params.custodianPublicKey]);
+        await this.transport.invoke(plan, params.signer);
+    }
+    /**
+     * 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.
+     */
+    async attestV3Signed(params) {
+        this.assertSigner(params.issuer, params.signer);
+        const plan = this.plan("attest_v3_signed", [
+            params.issuer,
+            params.bundle.proof,
+            [...params.bundle.publicSignals],
+            params.custodianSig,
+        ]);
+        const result = await this.transport.invoke(plan, params.signer);
+        const attestation = decodeAttestationV3(result.value);
+        return {
+            attestation,
+            networkPassphrase: this.deployment.networkPassphrase,
+            contractId: this.deployment.contractId,
+            ...(result.transactionHash === undefined ? {} : { transactionHash: result.transactionHash }),
+            ...(result.ledger === undefined ? {} : { ledger: result.ledger }),
+        };
+    }
+    async getCustodian() {
+        const plan = this.plan("get_custodian", []);
+        const value = await this.transport.simulate(plan);
+        return value === null || value === undefined ? null : String(value);
+    }
+    plan(operation, args) {
+        return {
+            operation,
+            contractId: this.deployment.contractId,
+            args,
+            deployment: this.deployment,
+        };
+    }
+    assertSigner(expectedPublicKey, signer) {
+        if (signer.publicKey !== expectedPublicKey) {
+            throw StellarisError.validation("signer public key does not match requested account", {
+                expectedPublicKey,
+                signerPublicKey: signer.publicKey,
+            });
+        }
+    }
+}
+export function createStellarisClient(options) {
+    return new StellarisClient(options);
+}

package/dist/transport.d.ts

@@ -0,0 +1,70 @@
+/** Transport abstractions for Soroban RPC and generated bindings. */
+import { ContractDeployment, PublicKey } from "./domain.js";
+import { ContractOperation } from "./operations.js";
+export interface TransactionSigner {
+    readonly publicKey: PublicKey;
+    sign(transactionXdr: string, networkPassphrase: string): Promise<string>;
+}
+export interface TransactionPlan<Name extends ContractOperation = ContractOperation> {
+    readonly operation: Name;
+    readonly contractId: string;
+    readonly args: readonly unknown[];
+    readonly deployment: ContractDeployment;
+    readonly idempotencyKey?: string;
+    readonly timeoutMs?: number;
+}
+export interface TransactionResult<T> {
+    readonly value: T;
+    readonly transactionHash?: string;
+    readonly ledger?: bigint;
+    readonly envelopeXdr?: string;
+    readonly diagnosticEvents?: readonly unknown[];
+}
+export interface SorobanTransport {
+    invoke<T>(plan: TransactionPlan, signer?: TransactionSigner): Promise<TransactionResult<T>>;
+    simulate<T>(plan: TransactionPlan): Promise<T>;
+}
+export interface ContractInvocationRequest {
+    readonly contractId: string;
+    readonly operation: ContractOperation;
+    readonly args: readonly unknown[];
+    readonly deployment: ContractDeployment;
+    readonly signerPublicKey?: PublicKey;
+    readonly idempotencyKey?: string;
+    readonly timeoutMs?: number;
+}
+export interface ContractInvocationResponse<T = unknown> {
+    readonly value: T;
+    readonly transactionHash?: string;
+    readonly ledger?: bigint | number | string;
+    readonly envelopeXdr?: string;
+    readonly diagnosticEvents?: readonly unknown[];
+}
+export interface ContractInvoker {
+    invoke<T>(request: ContractInvocationRequest, signer?: TransactionSigner): Promise<ContractInvocationResponse<T>>;
+    simulate<T>(request: ContractInvocationRequest): Promise<T>;
+}
+export interface RetryingTransportOptions {
+    readonly invoker: ContractInvoker;
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly retryable?: (error: unknown, attempt: number, plan: TransactionPlan) => boolean;
+}
+export declare class BindingSorobanTransport implements SorobanTransport {
+    private readonly invoker;
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly retryable;
+    constructor(options: RetryingTransportOptions);
+    invoke<T>(plan: TransactionPlan, signer?: TransactionSigner): Promise<TransactionResult<T>>;
+    simulate<T>(plan: TransactionPlan): Promise<T>;
+    private validatePlan;
+    private toRequest;
+    private withRetry;
+}
+export declare class UnconfiguredSorobanTransport implements SorobanTransport {
+    invoke<T>(plan: TransactionPlan, _signer?: TransactionSigner): Promise<TransactionResult<T>>;
+    simulate<T>(plan: TransactionPlan): Promise<T>;
+}
+export declare function normalizeTransactionResult<T>(response: ContractInvocationResponse<T>): TransactionResult<T>;
+export declare function defaultRetryable(error: unknown, _attempt: number, _plan: TransactionPlan): boolean;

package/dist/transport.js

@@ -0,0 +1,94 @@
+/** Transport abstractions for Soroban RPC and generated bindings. */
+import { StellarisError, wrapUnknown } from "./errors.js";
+import { assertOperationArgs, getOperationSpec, isReadOperation } from "./operations.js";
+export class BindingSorobanTransport {
+    invoker;
+    maxAttempts;
+    baseDelayMs;
+    retryable;
+    constructor(options) {
+        this.invoker = options.invoker;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.baseDelayMs = options.baseDelayMs ?? 250;
+        this.retryable = options.retryable ?? defaultRetryable;
+    }
+    async invoke(plan, signer) {
+        this.validatePlan(plan, "write");
+        const request = this.toRequest(plan, signer?.publicKey);
+        const response = await this.withRetry(plan, () => this.invoker.invoke(request, signer));
+        return normalizeTransactionResult(response);
+    }
+    async simulate(plan) {
+        this.validatePlan(plan, "read");
+        const request = this.toRequest(plan);
+        return this.withRetry(plan, () => this.invoker.simulate(request));
+    }
+    validatePlan(plan, mode) {
+        assertOperationArgs(plan.operation, plan.args);
+        const spec = getOperationSpec(plan.operation);
+        if (mode === "read" && !isReadOperation(plan.operation)) {
+            throw StellarisError.transport(`cannot simulate mutating operation ${plan.operation}`);
+        }
+        if (mode === "write" && spec.mutability !== "write") {
+            throw StellarisError.transport(`cannot invoke read-only operation ${plan.operation}`);
+        }
+    }
+    toRequest(plan, signerPublicKey) {
+        return {
+            contractId: plan.contractId,
+            operation: plan.operation,
+            args: plan.args,
+            deployment: plan.deployment,
+            ...(signerPublicKey === undefined ? {} : { signerPublicKey }),
+            ...(plan.idempotencyKey === undefined ? {} : { idempotencyKey: plan.idempotencyKey }),
+            ...(plan.timeoutMs === undefined ? {} : { timeoutMs: plan.timeoutMs }),
+        };
+    }
+    async withRetry(plan, action) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                return await action();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt >= this.maxAttempts || !this.retryable(error, attempt, plan)) {
+                    throw wrapUnknown("transport", `transport failed for ${plan.operation}`, error);
+                }
+                await delay(this.baseDelayMs * 2 ** (attempt - 1));
+            }
+        }
+        throw wrapUnknown("transport", `transport failed for ${plan.operation}`, lastError);
+    }
+}
+export class UnconfiguredSorobanTransport {
+    async invoke(plan, _signer) {
+        throw StellarisError.transport(`no Soroban transport configured for ${plan.operation}`, {
+            context: { operation: plan.operation, contractId: plan.contractId },
+        });
+    }
+    async simulate(plan) {
+        throw StellarisError.transport(`no Soroban transport configured for ${plan.operation}`, {
+            context: { operation: plan.operation, contractId: plan.contractId },
+        });
+    }
+}
+export function normalizeTransactionResult(response) {
+    return {
+        value: response.value,
+        ...(response.transactionHash === undefined ? {} : { transactionHash: response.transactionHash }),
+        ...(response.ledger === undefined ? {} : { ledger: BigInt(String(response.ledger)) }),
+        ...(response.envelopeXdr === undefined ? {} : { envelopeXdr: response.envelopeXdr }),
+        ...(response.diagnosticEvents === undefined ? {} : { diagnosticEvents: response.diagnosticEvents }),
+    };
+}
+export function defaultRetryable(error, _attempt, _plan) {
+    if (error instanceof StellarisError) {
+        return error.kind === "transport";
+    }
+    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    return message.includes("timeout") || message.includes("rate") || message.includes("temporar");
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stellaris-lab/por-sdk",
+  "version": "0.1.0",
+  "description": "Stellaris proof-of-reserves SDK: circuits, proving, contract encoding, and Soroban client abstractions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test \"test/*.test.ts\"",
+    "check": "npm run lint && npm test",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "stellar",
+    "soroban",
+    "proof-of-reserves",
+    "rwa",
+    "stablecoin",
+    "zk",
+    "groth16"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "dependencies": {
+    "@stellar/stellar-sdk": "^13.1.0",
+    "snarkjs": "^0.7.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}