@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/stark-settlement/domain/value-objects.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Value Objects for Aggregated STARK Settlement Layer
+ *
+ * Immutable, self-validating value types that encapsulate domain concepts:
+ * - FieldElement: Arithmetic in the STARK prime field
+ * - IdempotencyKey: Collision-resistant exactly-once keys
+ * - ProofCommitment: Succinct commitment to a STARK proof
+ * - StateRoot: Merkle root of ledger state
+ *
+ * Value objects are equal if their values are equal (no identity).
+ * All validation happens at construction time.
+ *
+ * @see modules/mpc/src/field.ts for field arithmetic patterns
+ */
+/**
+ * STARK prime field: 2^251 + 17 * 2^192 + 1
+ * This is the prime used by StarkNet/Cairo for field operations.
+ */
+export declare const STARK_PRIME = 3618502788666131213697322783095070105623107215331596699973092056135872020481n;
+/**
+ * Generator of the multiplicative group of the STARK field.
+ */
+export declare const STARK_GENERATOR = 3n;
+/**
+ * An element in the STARK prime field.
+ *
+ * Supports modular arithmetic operations and serialization.
+ * Immutable - all operations return new instances.
+ */
+export declare class FieldElement {
+    #private;
+    readonly value: bigint;
+    readonly prime: bigint;
+    private constructor();
+    /**
+     * Create a field element from a bigint.
+     * Value is automatically reduced modulo prime.
+     */
+    static fromBigInt(value: bigint, prime?: bigint): FieldElement;
+    /**
+     * Create a field element from a hex string.
+     */
+    static fromHex(hex: string, prime?: bigint): FieldElement;
+    /**
+     * Create a field element from a byte array (big-endian).
+     */
+    static fromBytes(bytes: Uint8Array, prime?: bigint): FieldElement;
+    /**
+     * Generate a random field element.
+     */
+    static random(prime?: bigint): FieldElement;
+    /**
+     * Zero element in the field.
+     */
+    static zero(prime?: bigint): FieldElement;
+    /**
+     * One (multiplicative identity) in the field.
+     */
+    static one(prime?: bigint): FieldElement;
+    /**
+     * Modular addition: (this + other) mod prime
+     */
+    add(other: FieldElement): FieldElement;
+    /**
+     * Modular subtraction: (this - other) mod prime
+     */
+    sub(other: FieldElement): FieldElement;
+    /**
+     * Modular multiplication: (this * other) mod prime
+     */
+    mul(other: FieldElement): FieldElement;
+    /**
+     * Modular exponentiation: this^exp mod prime
+     * Uses square-and-multiply for O(log exp) complexity.
+     */
+    pow(exp: bigint): FieldElement;
+    /**
+     * Modular multiplicative inverse: this^(-1) mod prime
+     * Uses Fermat's little theorem: a^(-1) = a^(p-2) mod p
+     */
+    inverse(): FieldElement;
+    /**
+     * Modular division: this / other mod prime
+     */
+    div(other: FieldElement): FieldElement;
+    /**
+     * Negation: -this mod prime
+     */
+    neg(): FieldElement;
+    /**
+     * Check if this is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Check equality with another field element.
+     */
+    equals(other: FieldElement): boolean;
+    /**
+     * Convert to hex string (64 characters, zero-padded).
+     */
+    toHex(): string;
+    /**
+     * Convert to byte array (big-endian, 32 bytes).
+     */
+    toBytes(): Uint8Array;
+    /**
+     * String representation for debugging.
+     */
+    toString(): string;
+}
+/**
+ * A collision-resistant idempotency key for exactly-once processing.
+ *
+ * Generated from a combination of source, transaction ID, and timestamp.
+ * SHA-256 hash ensures collision resistance.
+ */
+export declare class IdempotencyKey {
+    readonly value: string;
+    private constructor();
+    /**
+     * Create an idempotency key from source components.
+     */
+    static create(source: string, txId: string, timestamp: number): IdempotencyKey;
+    /**
+     * Create from an existing key string (must be 64 hex chars).
+     */
+    static fromString(value: string): IdempotencyKey;
+    /**
+     * Generate a random idempotency key.
+     */
+    static random(): IdempotencyKey;
+    /**
+     * Check equality with another key.
+     */
+    equals(other: IdempotencyKey): boolean;
+    /**
+     * String representation.
+     */
+    toString(): string;
+}
+/**
+ * A succinct commitment to a STARK proof.
+ *
+ * Used for on-chain anchoring without storing the full proof.
+ * Computed as SHA-256(proofId || starkProof || publicInputs).
+ */
+export declare class ProofCommitment {
+    readonly value: string;
+    private constructor();
+    /**
+     * Create a commitment from proof components.
+     */
+    static create(proofId: string, starkProof: Uint8Array, publicInputs: readonly string[]): ProofCommitment;
+    /**
+     * Create from an existing commitment string (must be 64 hex chars).
+     */
+    static fromString(value: string): ProofCommitment;
+    /**
+     * Check equality with another commitment.
+     */
+    equals(other: ProofCommitment): boolean;
+    /**
+     * String representation.
+     */
+    toString(): string;
+    /**
+     * Convert to bytes for on-chain storage.
+     */
+    toBytes(): Uint8Array;
+}
+/**
+ * A Merkle root representing the state of the ledger.
+ *
+ * Computed as the root of a Merkle tree over all account states.
+ * Used to prove state transitions in STARK proofs.
+ */
+export declare class StateRoot {
+    readonly value: string;
+    private constructor();
+    /**
+     * Create a state root from a hex string.
+     */
+    static fromHex(hex: string): StateRoot;
+    /**
+     * Create the genesis (empty) state root.
+     */
+    static genesis(): StateRoot;
+    /**
+     * Compute a new state root by hashing with another value.
+     * Used for incremental state updates.
+     */
+    hash(data: Uint8Array): StateRoot;
+    /**
+     * Check equality with another state root.
+     */
+    equals(other: StateRoot): boolean;
+    /**
+     * String representation.
+     */
+    toString(): string;
+    /**
+     * Convert to bytes.
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Convert to field element for STARK circuits.
+     */
+    toFieldElement(): FieldElement;
+}
+/**
+ * A validated amount with decimal conversion utilities.
+ *
+ * Stores value in atomic units (lamports, satoshis, cents).
+ * Provides conversion to/from human-readable format.
+ */
+export declare class Amount {
+    #private;
+    readonly atomicValue: bigint;
+    readonly decimals: number;
+    private constructor();
+    /**
+     * Create from atomic units (e.g., lamports, satoshis, cents).
+     */
+    static fromAtomic(value: bigint, decimals: number): Amount;
+    /**
+     * Create from a decimal string (e.g., "1.5" SOL = 1500000000 lamports).
+     */
+    static fromDecimal(value: string, decimals: number): Amount;
+    /**
+     * Add two amounts.
+     */
+    add(other: Amount): Amount;
+    /**
+     * Subtract another amount.
+     */
+    sub(other: Amount): Amount;
+    /**
+     * Check if this amount is zero.
+     */
+    isZero(): boolean;
+    /**
+     * Compare with another amount.
+     * Returns -1 if this < other, 0 if equal, 1 if this > other.
+     */
+    compare(other: Amount): -1 | 0 | 1;
+    /**
+     * Convert to decimal string (e.g., "1.500000000" for 1.5 SOL).
+     */
+    toDecimal(): string;
+    /**
+     * String representation.
+     */
+    toString(): string;
+}
+/**
+ * Compute SHA-256 hash of a string.
+ */
+export declare function sha256(input: string): string;
+/**
+ * Compute SHA-256 hash of bytes.
+ */
+export declare function sha256Bytes(input: Uint8Array): Uint8Array;
+/**
+ * Compute Pedersen hash (placeholder - actual implementation would use Cairo's Pedersen).
+ * For now, uses SHA-256 as a stand-in.
+ */
+export declare function pedersenHash(a: FieldElement, b: FieldElement): FieldElement;
+//# sourceMappingURL=value-objects.d.ts.map

package/dist/stark-settlement/domain/value-objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-objects.d.ts","sourceRoot":"","sources":["../../../src/stark-settlement/domain/value-objects.ts"],"names":[],"mappings":"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"}