@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/stark-settlement/application/aggregator-service.js

@@ -0,0 +1,256 @@
+/**
+ * Aggregator Service
+ *
+ * Orchestrates the tiered recursive STARK proof aggregation:
+ * - Tier-1: Aggregates 128 base proofs into a single Tier-1 proof
+ * - Tier-2: Aggregates 64 Tier-1 proofs into a final Block Proof
+ *
+ * The aggregator maintains idempotency keys through all tiers
+ * for exactly-once settlement semantics.
+ *
+ * @see domain/ports.ts for StarkProofGeneratorPort interface
+ */
+/**
+ * Aggregator service for recursive STARK proof composition.
+ */
+export class AggregatorService {
+    ctx;
+    config;
+    constructor(ctx, config) {
+        this.ctx = ctx;
+        // Get batch sizes from the STARK prover if it's a flexible adapter
+        const prover = ctx.starkProver;
+        const defaultSizes = prover.getBatchSizes?.() ?? { tier1: 128, tier2: 64 };
+        this.config = {
+            tier1BatchSize: config?.tier1BatchSize ?? defaultSizes.tier1,
+            tier2BatchSize: config?.tier2BatchSize ?? defaultSizes.tier2,
+        };
+    }
+    /**
+     * Get the current batch sizes.
+     */
+    getBatchSizes() {
+        return {
+            tier1: this.config.tier1BatchSize,
+            tier2: this.config.tier2BatchSize,
+            totalTxsPerBlock: this.config.tier1BatchSize * this.config.tier2BatchSize,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Aggregation Pipeline
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Process available proofs through the aggregation pipeline.
+     *
+     * Attempts to:
+     * 1. Aggregate base proofs into Tier-1 proofs
+     * 2. Aggregate Tier-1 proofs into a Tier-2 block proof
+     *
+     * @returns Aggregation result with statistics
+     */
+    async processAggregation() {
+        let baseProofsProcessed = 0;
+        let tier1ProofsGenerated = 0;
+        // Step 1: Aggregate base proofs into Tier-1 proofs
+        while (true) {
+            const baseProofs = await this.ctx.ledgerStore.getUnaggregatedBaseProofs(this.config.tier1BatchSize);
+            if (baseProofs.length < this.config.tier1BatchSize) {
+                break; // Not enough base proofs for a Tier-1 aggregation
+            }
+            const tier1Proof = await this.aggregateTier1(baseProofs);
+            baseProofsProcessed += baseProofs.length;
+            tier1ProofsGenerated++;
+            // Emit event
+            this.ctx.events.emit({
+                type: "proof:tier1:generated",
+                proof: tier1Proof,
+            });
+        }
+        // Step 2: Aggregate Tier-1 proofs into a Tier-2 block proof
+        const tier1Proofs = await this.ctx.ledgerStore.getUnaggregatedTier1Proofs(this.config.tier2BatchSize);
+        if (tier1Proofs.length < this.config.tier2BatchSize) {
+            return {
+                blockProof: null,
+                baseProofsProcessed,
+                tier1ProofsGenerated,
+                blockGenerated: false,
+            };
+        }
+        const blockProof = await this.aggregateTier2(tier1Proofs);
+        // Emit event
+        this.ctx.events.emit({ type: "proof:tier2:generated", proof: blockProof });
+        return {
+            blockProof,
+            baseProofsProcessed,
+            tier1ProofsGenerated,
+            blockGenerated: true,
+        };
+    }
+    /**
+     * Aggregate base proofs into a Tier-1 proof.
+     */
+    async aggregateTier1(baseProofs) {
+        if (baseProofs.length !== this.config.tier1BatchSize) {
+            throw new Error(`Tier-1 aggregation requires exactly ${this.config.tier1BatchSize} base proofs, got ${baseProofs.length}`);
+        }
+        const tier1Proof = await this.ctx.starkProver.aggregateTier1(baseProofs);
+        // Save to ledger store
+        await this.ctx.ledgerStore.saveTier1Proof(tier1Proof);
+        // Update transaction statuses
+        for (const baseProof of baseProofs) {
+            await this.ctx.ledgerStore.updateTransactionStatus(baseProof.txId, "aggregated");
+        }
+        // Log audit record
+        await this.ctx.auditLog.append({
+            eventType: "proof_aggregated",
+            entityId: tier1Proof.proofId,
+            entityType: "tier1_proof",
+            actor: "aggregator",
+            timestamp: this.ctx.clock.now(),
+            data: {
+                baseProofCount: baseProofs.length,
+                txCount: tier1Proof.txCount,
+                preStateRoot: tier1Proof.preStateRoot,
+                postStateRoot: tier1Proof.postStateRoot,
+            },
+        });
+        return tier1Proof;
+    }
+    /**
+     * Aggregate Tier-1 proofs into a Tier-2 block proof.
+     */
+    async aggregateTier2(tier1Proofs) {
+        if (tier1Proofs.length !== this.config.tier2BatchSize) {
+            throw new Error(`Tier-2 aggregation requires exactly ${this.config.tier2BatchSize} Tier-1 proofs, got ${tier1Proofs.length}`);
+        }
+        const blockProof = await this.ctx.starkProver.aggregateTier2(tier1Proofs);
+        // Save to ledger store
+        await this.ctx.ledgerStore.saveTier2Proof(blockProof);
+        // Update transaction statuses for all covered transactions
+        // (This would require tracking txIds through the proof chain)
+        // Log audit record
+        await this.ctx.auditLog.append({
+            eventType: "proof_aggregated",
+            entityId: blockProof.blockProofId,
+            entityType: "tier2_proof",
+            actor: "aggregator",
+            timestamp: this.ctx.clock.now(),
+            data: {
+                tier1ProofCount: tier1Proofs.length,
+                txCount: blockProof.txCount,
+                blockNumber: blockProof.blockNumber.toString(),
+                stateRoot: blockProof.stateRoot,
+            },
+        });
+        return blockProof;
+    }
+    /**
+     * Process proofs until a block is generated or no more proofs are available.
+     *
+     * Convenience method for demo/testing - processes multiple batches.
+     */
+    async processToBlockProof() {
+        // Keep processing until we get a block or run out of proofs
+        let result = await this.processAggregation();
+        while (!result.blockGenerated && result.baseProofsProcessed > 0) {
+            result = await this.processAggregation();
+        }
+        return result.blockProof;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Outbox Management
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create outbox entries for a block proof.
+     *
+     * Computes net transfers per asset type and creates outbox entries
+     * for settlement.
+     *
+     * @param blockProof - The block proof to create entries for
+     * @param netTransfersByAsset - Pre-computed net transfers by asset type
+     */
+    async createOutboxEntries(blockProof, netTransfersByAsset) {
+        const entries = [];
+        const now = this.ctx.clock.now();
+        for (const [assetType, transfers] of netTransfersByAsset) {
+            if (transfers.length === 0)
+                continue;
+            const entry = {
+                entryId: this.ctx.clock.uuid(),
+                blockProofId: blockProof.blockProofId,
+                assetType,
+                netTransfers: transfers,
+                status: "pending",
+                retryCount: 0,
+                maxRetries: 3,
+                createdAt: now,
+                settledAt: null,
+                settlementTxId: null,
+                errorMessage: null,
+                offset: 0n, // Placeholder - outbox store assigns the real sequential offset
+            };
+            // Store entry and get back the entry with the real assigned offset
+            const storedEntry = await this.ctx.outboxStore.appendEntry(entry);
+            entries.push(storedEntry);
+            // Emit event with the stored entry (which has the real offset)
+            this.ctx.events.emit({
+                type: "settlement:initiated",
+                entry: storedEntry,
+            });
+        }
+        return entries;
+    }
+    /**
+     * Compute net transfers from transaction history.
+     *
+     * Groups transactions by external address and computes the net
+     * amount change for each address.
+     */
+    computeNetTransfers(transactions, accountAddresses) {
+        const netByAddress = new Map();
+        for (const tx of transactions) {
+            // Withdrawals: debit from external address
+            if (tx.type === "withdrawal" && tx.fromAccountId) {
+                const address = accountAddresses.get(tx.fromAccountId);
+                if (address) {
+                    const current = netByAddress.get(address) ?? 0n;
+                    netByAddress.set(address, current - tx.amount);
+                }
+            }
+            // Deposits: credit to external address
+            if (tx.type === "deposit" && tx.toAccountId) {
+                const address = accountAddresses.get(tx.toAccountId);
+                if (address) {
+                    const current = netByAddress.get(address) ?? 0n;
+                    netByAddress.set(address, current + tx.amount);
+                }
+            }
+            // Transfers: Internal only, no external settlement needed
+            // (unless transferring to a withdrawal-pending account)
+        }
+        return netByAddress;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Verification
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Verify a block proof.
+     */
+    async verifyBlockProof(blockProof) {
+        return this.ctx.starkProver.verifyBlockProof(blockProof);
+    }
+    /**
+     * Get aggregation statistics.
+     */
+    async getStats() {
+        const baseProofs = await this.ctx.ledgerStore.getUnaggregatedBaseProofs(this.config.tier1BatchSize * this.config.tier2BatchSize);
+        const tier1Proofs = await this.ctx.ledgerStore.getUnaggregatedTier1Proofs(this.config.tier2BatchSize);
+        const latestBlock = await this.ctx.ledgerStore.getLatestBlockProof();
+        return {
+            pendingBaseProofs: baseProofs.length,
+            pendingTier1Proofs: tier1Proofs.length,
+            latestBlockNumber: latestBlock?.blockNumber ?? null,
+            totalTxsPerBlock: this.config.tier1BatchSize * this.config.tier2BatchSize,
+        };
+    }
+}

package/dist/stark-settlement/application/ledger-service.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Ledger Service
+ *
+ * Orchestrates the ZKP ledger operations:
+ * - Account management (create, query, update)
+ * - Transaction submission with ML-DSA-65 signing
+ * - State transition proof generation
+ * - Audit logging
+ *
+ * All transactions are signed with post-quantum ML-DSA-65 signatures.
+ *
+ * @see domain/ports.ts for port interfaces
+ */
+import type { AssetType, MirrorAccount, LedgerTransaction, TransactionType, BaseProof } from "../domain/entities.js";
+import type { SettlementContext } from "../index.js";
+import { StateRoot } from "../domain/value-objects.js";
+/**
+ * Options for creating a mirror account.
+ */
+export interface CreateAccountOptions {
+    /** External chain address (Solana pubkey, BTC address, fiat account) */
+    externalAddress: string;
+    /** Asset type */
+    assetType: AssetType;
+    /** Initial balance (default: 0) */
+    initialBalance?: bigint;
+    /** Optional metadata */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for submitting a transaction.
+ */
+export interface SubmitTransactionOptions {
+    /** Transaction type */
+    type: TransactionType;
+    /** Source account ID (required for transfer/withdrawal) */
+    fromAccountId?: string;
+    /** Destination account ID (required for deposit/transfer) */
+    toAccountId?: string;
+    /** Asset type */
+    assetType: AssetType;
+    /** Amount in atomic units */
+    amount: bigint;
+    /** Signer's secret key (ML-DSA-65) */
+    signerSecretKey: Uint8Array;
+    /** Signer's public key (ML-DSA-65) */
+    signerPublicKey: Uint8Array;
+    /** Optional metadata */
+    metadata?: Record<string, string>;
+    /** Optional idempotency key (auto-generated if not provided) */
+    idempotencyKey?: string;
+}
+/**
+ * Result of submitting a transaction.
+ */
+export interface SubmitTransactionResult {
+    /** The submitted transaction */
+    transaction: LedgerTransaction;
+    /** The base proof for this transaction */
+    baseProof: BaseProof;
+    /** Whether this was a duplicate (idempotent replay) */
+    isDuplicate: boolean;
+}
+/**
+ * Ledger service for managing accounts and transactions.
+ */
+export declare class LedgerService {
+    private readonly ctx;
+    private currentStateRoot;
+    constructor(ctx: SettlementContext);
+    /**
+     * Create a new mirror account.
+     */
+    createAccount(options: CreateAccountOptions): Promise<MirrorAccount>;
+    /**
+     * Get an account by ID.
+     */
+    getAccount(accountId: string): Promise<MirrorAccount | null>;
+    /**
+     * Get an account by external address and asset type.
+     */
+    getAccountByAddress(externalAddress: string, assetType: AssetType): Promise<MirrorAccount | null>;
+    /**
+     * Get all accounts for an asset type.
+     */
+    getAccountsByAssetType(assetType: AssetType): Promise<readonly MirrorAccount[]>;
+    /**
+     * Submit a transaction to the ledger.
+     *
+     * The transaction is:
+     * 1. Validated (balances, account existence)
+     * 2. Signed with ML-DSA-65
+     * 3. Recorded in the ledger
+     * 4. A base STARK proof is generated
+     * 5. Account balances are updated
+     *
+     * @returns The transaction and its base proof
+     * @throws If validation fails
+     */
+    submitTransaction(options: SubmitTransactionOptions): Promise<SubmitTransactionResult>;
+    /**
+     * Get pending transactions that need proof generation.
+     */
+    getPendingTransactions(limit?: number): Promise<readonly LedgerTransaction[]>;
+    /**
+     * Get the current state root.
+     */
+    getCurrentStateRoot(): StateRoot;
+    private validateTransaction;
+    private validateAccountExists;
+    private validateSufficientBalance;
+    private applyTransaction;
+}
+//# sourceMappingURL=ledger-service.d.ts.map

package/dist/stark-settlement/application/ledger-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-service.d.ts","sourceRoot":"","sources":["../../../src/stark-settlement/application/ledger-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EAEjB,eAAe,EACf,SAAS,EACV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,mCAAmC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uBAAuB;IACvB,IAAI,EAAE,eAAe,CAAC;IACtB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,eAAe,EAAE,UAAU,CAAC;IAC5B,sCAAsC;IACtC,eAAe,EAAE,UAAU,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,gCAAgC;IAChC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,0CAA0C;IAC1C,SAAS,EAAE,SAAS,CAAC;IACrB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,gBAAgB,CAAY;gBAEP,GAAG,EAAE,iBAAiB;IAQnD;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IA8C1E;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIlE;;OAEG;IACG,mBAAmB,CACvB,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAIhC;;OAEG;IACG,sBAAsB,CAC1B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAQpC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC;IAuInC;;OAEG;IACG,sBAAsB,CAC1B,KAAK,SAAO,GACX,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;IAIxC;;OAEG;IACH,mBAAmB,IAAI,SAAS;YAQlB,mBAAmB;YAkFnB,qBAAqB;YAkBrB,yBAAyB;YAazB,gBAAgB;CA8C/B"}