openttt 0.1.0

package/dist/evm_connector.d.ts

@@ -0,0 +1,88 @@
+import { JsonRpcProvider, Signer, TransactionReceipt } from "ethers";
+import { TTTRecord } from "./adaptive_switch";
+export interface VerificationResult {
+    valid: boolean;
+    blockNumber: number;
+    timestamp: number;
+    txCount: number;
+    latency: number;
+}
+export declare class EVMConnector {
+    private provider;
+    private signer;
+    private tttContract;
+    private protocolFeeContract;
+    private eventListeners;
+    private static readonly GAS_TIMEOUT_MS;
+    constructor();
+    /**
+     * P1-7: Race estimateGas against timeout to prevent DoS
+     */
+    private withTimeout;
+    /**
+     * Connect to an EVM chain using either a private key or a pre-configured signer.
+     */
+    connect(rpcUrl: string, signerOrKey: string | Signer): Promise<void>;
+    /**
+     * Attach the TTT Token contract.
+     */
+    attachContract(address: string, abi: any[]): void;
+    /**
+     * Attach the ProtocolFee contract.
+     */
+    attachProtocolFeeContract(address: string, abi: any[]): void;
+    /**
+     * Generic TTT Record Submission (Burn)
+     */
+    submitTTTRecord(record: TTTRecord, amount: bigint, tier: number): Promise<TransactionReceipt>;
+    /**
+     * Mint TTT (Owner only)
+     */
+    mintTTT(to: string, amount: bigint, grgHash: string, potHash?: string): Promise<TransactionReceipt>;
+    /**
+     * Burn TTT (Simple wrapper)
+     */
+    burnTTT(amount: bigint, grgHash: string, tierLevel: number): Promise<{
+        hash: string;
+    }>;
+    /**
+     * Get TTT Balance (ERC-1155)
+     */
+    getTTTBalance(user: string, tokenId: bigint): Promise<bigint>;
+    /**
+     * Swap tokens on a DEX (Uniswap V4 Simulation)
+     */
+    swap(routerAddress: string, tokenIn: string, tokenOut: string, amountIn: bigint, minAmountOut: bigint): Promise<TransactionReceipt>;
+    /**
+     * Subscribe to TTT and Fee events.
+     */
+    subscribeToEvents(callbacks: {
+        onMinted?: (to: string, tokenId: bigint, amount: bigint) => void;
+        onBurned?: (from: string, tokenId: bigint, amount: bigint, tier: bigint) => void;
+        onFeeCollected?: (payer: string, amount: bigint, nonce: bigint) => void;
+    }): Promise<void>;
+    /**
+     * P2-6: Unsubscribe all event listeners to prevent memory leaks.
+     */
+    unsubscribeAll(): void;
+    /**
+     * Verify Block Data
+     */
+    verifyBlock(blockNum: number): Promise<VerificationResult>;
+    /**
+     * Get pending transactions for the current provider.
+     */
+    getPendingTransactions(): Promise<string[]>;
+    /**
+     * Get the provider instance.
+     */
+    getProvider(): JsonRpcProvider;
+    /**
+     * Get the signer instance.
+     */
+    getSigner(): Signer;
+    /**
+     * Extract human-readable revert reason from ethers error.
+     */
+    private extractRevertReason;
+}

package/dist/evm_connector.js

@@ -0,0 +1,297 @@
+"use strict";
+// sdk/src/evm_connector.ts — Production EVM Chain Connector
+// Supports EIP-1559, Gas Estimation, and TTT Operations.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVMConnector = void 0;
+const ethers_1 = require("ethers");
+const logger_1 = require("./logger");
+const errors_1 = require("./errors");
+class EVMConnector {
+    provider = null;
+    signer = null;
+    tttContract = null;
+    protocolFeeContract = null;
+    eventListeners = []; // P2-6: Track listeners for cleanup
+    // P1-7: Timeout wrapper for gas estimation
+    static GAS_TIMEOUT_MS = 5000;
+    constructor() { }
+    /**
+     * P1-7: Race estimateGas against timeout to prevent DoS
+     */
+    async withTimeout(promise, ms = EVMConnector.GAS_TIMEOUT_MS) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new errors_1.TTTNetworkError(`[EVM] Operation timed out`, `RPC did not respond within ${ms}ms`, `Check your RPC provider status or increase timeout.`)), ms))
+        ]);
+    }
+    /**
+     * Connect to an EVM chain using either a private key or a pre-configured signer.
+     */
+    async connect(rpcUrl, signerOrKey) {
+        if (!rpcUrl || typeof rpcUrl !== "string")
+            throw new errors_1.TTTNetworkError("[EVM] Invalid RPC URL", "The provided RPC URL is empty or not a string", "Pass a valid RPC URL (e.g., https://mainnet.base.org)");
+        try {
+            this.provider = new ethers_1.JsonRpcProvider(rpcUrl);
+            if (typeof signerOrKey === "string") {
+                if (!signerOrKey.startsWith("0x") || signerOrKey.length !== 66) {
+                    throw new errors_1.TTTContractError("[EVM] Invalid Private Key format", "Private key must be 0x + 64 hex characters", "Provide a valid 32-byte hex private key.");
+                }
+                this.signer = new ethers_1.ethers.Wallet(signerOrKey, this.provider);
+            }
+            else {
+                // Signer might already be connected to a provider, but we ensure it's linked to ours
+                this.signer = signerOrKey.connect ? signerOrKey.connect(this.provider) : signerOrKey;
+            }
+            const network = await this.provider.getNetwork();
+            logger_1.logger.info(`[EVM] Connected to Chain ID: ${network.chainId}`);
+        }
+        catch (error) {
+            if (error instanceof errors_1.TTTContractError || error instanceof errors_1.TTTNetworkError)
+                throw error;
+            throw new errors_1.TTTNetworkError(`[EVM] Connection failed`, error instanceof Error ? error.message : String(error), `Verify your RPC URL and network connectivity.`);
+        }
+    }
+    /**
+     * Attach the TTT Token contract.
+     */
+    attachContract(address, abi) {
+        if (!this.signer)
+            throw new errors_1.TTTContractError("Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
+        if (!address || !ethers_1.ethers.isAddress(address))
+            throw new errors_1.TTTContractError(`[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
+        this.tttContract = new ethers_1.Contract(address, abi, this.signer);
+    }
+    /**
+     * Attach the ProtocolFee contract.
+     */
+    attachProtocolFeeContract(address, abi) {
+        if (!this.signer)
+            throw new errors_1.TTTContractError("Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
+        if (!address || !ethers_1.ethers.isAddress(address))
+            throw new errors_1.TTTContractError(`[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
+        this.protocolFeeContract = new ethers_1.Contract(address, abi, this.signer);
+    }
+    /**
+     * Generic TTT Record Submission (Burn)
+     */
+    async submitTTTRecord(record, amount, tier) {
+        if (!this.tttContract)
+            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() with valid TTT address before burning.");
+        const grgHash = ethers_1.ethers.keccak256(ethers_1.ethers.concat(record.grgPayload));
+        try {
+            // P1-7: Gas estimation with timeout
+            const gasLimit = await this.withTimeout(this.tttContract.burn.estimateGas(amount, grgHash, tier));
+            const tx = await this.tttContract.burn(amount, grgHash, tier, {
+                gasLimit: (gasLimit * 120n) / 100n
+            });
+            logger_1.logger.info(`[EVM] TTT Record TX Sent: ${tx.hash}`);
+            const receipt = await tx.wait();
+            // P2-5: Null check for dropped transactions
+            if (!receipt)
+                throw new errors_1.TTTNetworkError(`[EVM] Transaction failed`, `Transaction was dropped from mempool or null receipt`, `Check block explorer for tx status.`);
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof errors_1.TTTNetworkError || error instanceof errors_1.TTTContractError)
+                throw error;
+            const reason = this.extractRevertReason(error);
+            throw new errors_1.TTTContractError(`[EVM] Burn failed`, reason, `Verify your TTT balance and tier parameters.`);
+        }
+    }
+    /**
+     * Mint TTT (Owner only)
+     */
+    async mintTTT(to, amount, grgHash, potHash) {
+        if (!this.tttContract)
+            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before minting.");
+        if (!to || !ethers_1.ethers.isAddress(to))
+            throw new errors_1.TTTContractError(`[EVM] Invalid recipient address`, `Address '${to}' is not a valid EVM address`, `Provide a valid destination address.`);
+        try {
+            if (potHash) {
+                logger_1.logger.info(`[EVM] Recording PoT fingerprint: ${potHash}`);
+            }
+            const tx = await this.tttContract.mint(to, amount, grgHash);
+            const receipt = await tx.wait();
+            if (!receipt)
+                throw new errors_1.TTTNetworkError(`[EVM] Mint TX dropped`, `Transaction was dropped from mempool`, `Check operator account for nonce collisions.`);
+            return receipt;
+        }
+        catch (error) {
+            const reason = this.extractRevertReason(error);
+            throw new errors_1.TTTContractError(`[EVM] Mint failed`, reason, `Ensure operator has minter role and sufficient gas.`);
+        }
+    }
+    /**
+     * Burn TTT (Simple wrapper)
+     */
+    async burnTTT(amount, grgHash, tierLevel) {
+        if (!this.tttContract)
+            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before burning.");
+        try {
+            const tx = await this.tttContract.burn(amount, grgHash, tierLevel);
+            const receipt = await tx.wait();
+            if (!receipt)
+                throw new errors_1.TTTNetworkError(`[EVM] Burn TX dropped`, `Transaction was dropped from mempool`, `Verify account balance.`);
+            return { hash: receipt.hash };
+        }
+        catch (error) {
+            const reason = this.extractRevertReason(error);
+            throw new errors_1.TTTContractError(`[EVM] Burn failed`, reason, `Check TTT balance.`);
+        }
+    }
+    /**
+     * Get TTT Balance (ERC-1155)
+     */
+    async getTTTBalance(user, tokenId) {
+        if (!this.tttContract)
+            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before querying balance.");
+        try {
+            return await this.tttContract.balanceOf(user, tokenId);
+        }
+        catch (error) {
+            const reason = this.extractRevertReason(error);
+            throw new errors_1.TTTContractError(`[EVM] Balance query failed`, reason, `Check RPC connection and contract address.`);
+        }
+    }
+    /**
+     * Swap tokens on a DEX (Uniswap V4 Simulation)
+     */
+    async swap(routerAddress, tokenIn, tokenOut, amountIn, minAmountOut) {
+        if (!this.signer)
+            throw new errors_1.TTTContractError("Not connected to signer", "Signer is null", "Initialize connection.");
+        if (!routerAddress || !ethers_1.ethers.isAddress(routerAddress))
+            throw new errors_1.TTTContractError(`[EVM] Invalid router address`, `Address '${routerAddress}' is invalid`, `Provide valid V4 SwapRouter address.`);
+        logger_1.logger.info(`[EVM] Swapping ${amountIn} of ${tokenIn} for ${tokenOut} via ${routerAddress}`);
+        // Realistic Uniswap V4-like SwapRouter ABI for simulation/integration
+        const swapRouterAbi = [
+            "function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 amountOutMinimum) external returns (uint256)"
+        ];
+        const routerContract = new ethers_1.ethers.Contract(routerAddress, swapRouterAbi, this.signer);
+        try {
+            // P1-7: Gas estimation with timeout
+            const gasLimit = await this.withTimeout(routerContract.swap.estimateGas(tokenIn, tokenOut, amountIn, minAmountOut));
+            const tx = await routerContract.swap(tokenIn, tokenOut, amountIn, minAmountOut, {
+                gasLimit: (gasLimit * 120n) / 100n
+            });
+            logger_1.logger.info(`[EVM] Swap TX Sent: ${tx.hash}`);
+            const receipt = await tx.wait();
+            if (!receipt)
+                throw new errors_1.TTTNetworkError(`[EVM] Swap TX dropped`, `Transaction dropped`, `Check gas price.`);
+            return receipt;
+        }
+        catch (error) {
+            if (error instanceof errors_1.TTTNetworkError || error instanceof errors_1.TTTContractError)
+                throw error;
+            const reason = this.extractRevertReason(error);
+            throw new errors_1.TTTContractError(`[EVM] Swap failed`, reason, `Verify slippage and token balances.`);
+        }
+    }
+    /**
+     * Subscribe to TTT and Fee events.
+     */
+    async subscribeToEvents(callbacks) {
+        // R2-P1-1: Auto-cleanup previous listeners before re-subscribing (idempotency)
+        if (this.eventListeners.length > 0) {
+            this.unsubscribeAll();
+        }
+        if (this.tttContract) {
+            if (callbacks.onMinted) {
+                const handler = (to, tokenId, amount) => {
+                    callbacks.onMinted(to, tokenId, amount);
+                };
+                this.tttContract.on("TTTMinted", handler);
+                // R6-P1-2: Store direct handler reference for reliable .off() cleanup
+                const contract = this.tttContract;
+                this.eventListeners.push(() => contract.off("TTTMinted", handler));
+            }
+            if (callbacks.onBurned) {
+                const handler = (from, tokenId, amount, tier) => {
+                    callbacks.onBurned(from, tokenId, amount, tier);
+                };
+                this.tttContract.on("TTTBurned", handler);
+                const contract = this.tttContract;
+                this.eventListeners.push(() => contract.off("TTTBurned", handler));
+            }
+        }
+        if (this.protocolFeeContract && callbacks.onFeeCollected) {
+            const handler = (payer, amount, nonce) => {
+                callbacks.onFeeCollected(payer, amount, nonce);
+            };
+            this.protocolFeeContract.on("FeeCollected", handler);
+            const contract = this.protocolFeeContract;
+            this.eventListeners.push(() => contract.off("FeeCollected", handler));
+        }
+        logger_1.logger.info("[EVM] Subscribed to TTT and Fee events");
+    }
+    /**
+     * P2-6: Unsubscribe all event listeners to prevent memory leaks.
+     */
+    unsubscribeAll() {
+        for (const unsub of this.eventListeners) {
+            try {
+                unsub();
+            }
+            catch { /* already removed */ }
+        }
+        this.eventListeners = [];
+        logger_1.logger.info(`[EVM] All event listeners unsubscribed`);
+    }
+    /**
+     * Verify Block Data
+     */
+    async verifyBlock(blockNum) {
+        if (!this.provider)
+            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+        const block = await this.provider.getBlock(blockNum);
+        if (!block)
+            throw new errors_1.TTTNetworkError(`Block not found`, `RPC returned null for block ${blockNum}`, `Verify if block number exists on chain.`);
+        return {
+            valid: true,
+            blockNumber: blockNum,
+            timestamp: block.timestamp,
+            txCount: block.transactions.length,
+            latency: Math.floor(Date.now() / 1000) - block.timestamp
+        };
+    }
+    /**
+     * Get pending transactions for the current provider.
+     */
+    async getPendingTransactions() {
+        if (!this.provider)
+            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+        const block = await this.provider.send("eth_getBlockByNumber", ["pending", false]);
+        return block ? block.transactions : [];
+    }
+    /**
+     * Get the provider instance.
+     */
+    getProvider() {
+        if (!this.provider)
+            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+        return this.provider;
+    }
+    /**
+     * Get the signer instance.
+     */
+    getSigner() {
+        if (!this.signer)
+            throw new errors_1.TTTContractError("Signer not connected", "Signer is null", "Call connect() first.");
+        return this.signer;
+    }
+    /**
+     * Extract human-readable revert reason from ethers error.
+     */
+    extractRevertReason(error) {
+        if (error && typeof error === "object") {
+            const e = error;
+            if (typeof e.reason === "string")
+                return e.reason;
+            if (e.data && typeof e.data === "object" && typeof e.data.message === "string")
+                return e.data.message;
+            if (typeof e.message === "string")
+                return e.message;
+        }
+        return String(error ?? "Unknown EVM error");
+    }
+}
+exports.EVMConnector = EVMConnector;

package/dist/golay.d.ts

@@ -0,0 +1,6 @@
+export declare function golayEncode(data: Uint8Array): Uint8Array;
+export declare function golayDecode(encoded: Uint8Array): {
+    data: Uint8Array;
+    corrected: number;
+    uncorrectable: boolean;
+};

package/dist/golay.js

@@ -0,0 +1,166 @@
+"use strict";
+// sdk/src/golay.ts
+// 🔱 Golay(24,12) Extended Binary Golay Code (RE-SURGERY)
+// Corrects up to 3 bit errors, detects 4 bit errors.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.golayEncode = golayEncode;
+exports.golayDecode = golayDecode;
+// Standard Golay Parity Matrix P (12x12) - Systematic Form [I12 | P]
+// Every row has weight 7.
+// Verified: P*P^T = I (mod 2), all rows weight 7.
+// Derived from g(x) = x^11+x^10+x^6+x^5+x^4+x^2+1 with parity extension.
+const P = [
+    0xC75, 0x49F, 0xD4B, 0x6E3, 0x9B3, 0xB66,
+    0xECC, 0x1ED, 0x3DA, 0x7B4, 0xB1D, 0xE3A
+];
+// R7-P0-1: P^T (transpose of P) — required for second syndrome computation.
+// P is NOT symmetric, so s2 = s*P^T must use this separate matrix.
+// Without this, decodeWord fails ~24% of weight-2 and ~50% of weight-3 error patterns.
+const PT = [
+    0xAE3, 0xF25, 0x16F, 0x2DE, 0x5BC, 0xB78,
+    0x9D5, 0xC8F, 0x63B, 0xC76, 0x7C9, 0xF92
+];
+const UNIT_VECTORS = [
+    0x800, 0x400, 0x200, 0x100, 0x080, 0x040,
+    0x020, 0x010, 0x008, 0x004, 0x002, 0x001
+];
+/**
+ * Calculates weight (number of set bits).
+ */
+function weight(n) {
+    let count = 0;
+    let temp = n & 0xFFF;
+    while (temp > 0) {
+        temp &= (temp - 1);
+        count++;
+    }
+    return count;
+}
+/**
+ * Multiplies a 12-bit vector by the parity matrix P.
+ */
+function multiplyP(v) {
+    let res = 0;
+    for (let i = 0; i < 12; i++) {
+        if ((v >> (11 - i)) & 1) {
+            res ^= P[i];
+        }
+    }
+    return res & 0xFFF;
+}
+/**
+ * R7-P0-1: Multiplies a 12-bit vector by P^T (transpose of P).
+ * Required for second syndrome computation in decodeWord steps 3-5.
+ */
+function multiplyPT(v) {
+    let res = 0;
+    for (let i = 0; i < 12; i++) {
+        if ((v >> (11 - i)) & 1) {
+            res ^= PT[i];
+        }
+    }
+    return res & 0xFFF;
+}
+function encodeWord(msg) {
+    const parity = multiplyP(msg & 0xFFF);
+    return ((msg & 0xFFF) << 12) | parity;
+}
+/**
+ * Full Syndrome Decoding for Golay(24,12)
+ */
+function decodeWord(received) {
+    let r_m = (received >> 12) & 0xFFF;
+    const r_p = received & 0xFFF;
+    // Syndrome s = r_m * P + r_p
+    const s = multiplyP(r_m) ^ r_p;
+    if (s === 0)
+        return { msg: r_m, corrected: 0, uncorrectable: false };
+    // 1. wt(s) <= 3 -> Error in parity
+    if (weight(s) <= 3) {
+        return { msg: r_m, corrected: weight(s), uncorrectable: false };
+    }
+    // 2. wt(s + P_i) <= 2 -> Error in msg bit i (+ possible 1-2 errors in parity)
+    for (let i = 0; i < 12; i++) {
+        if (weight(s ^ P[i]) <= 2) {
+            return { msg: r_m ^ UNIT_VECTORS[i], corrected: weight(s ^ P[i]) + 1, uncorrectable: false };
+        }
+    }
+    // 3. R7-P0-1: Second syndrome s2 = s * P^T (NOT s * P — P is not symmetric!)
+    const s2 = multiplyPT(s);
+    // 4. wt(s2) <= 3 -> Error in message
+    if (weight(s2) <= 3) {
+        return { msg: r_m ^ s2, corrected: weight(s2), uncorrectable: false };
+    }
+    // 5. wt(s2 + PT_i) <= 2 -> Error in parity bit i + message errors
+    // R7-P0-1: Must use PT rows (columns of P), not P rows
+    for (let i = 0; i < 12; i++) {
+        if (weight(s2 ^ PT[i]) <= 2) {
+            const error_m = s2 ^ PT[i];
+            return { msg: r_m ^ error_m, corrected: weight(s2 ^ PT[i]) + 1, uncorrectable: false };
+        }
+    }
+    return { msg: r_m, corrected: 0, uncorrectable: true };
+}
+function golayEncode(data) {
+    // B1-6: Correct output size calculation to avoid buffer overflow
+    const out = new Uint8Array(Math.ceil(data.length / 3) * 6);
+    let outIdx = 0;
+    // Process in 3-byte blocks -> two 12-bit words -> two 24-bit (3-byte) codewords
+    for (let i = 0; i < data.length; i += 3) {
+        const b1 = data[i];
+        const b2 = i + 1 < data.length ? data[i + 1] : 0;
+        const b3 = i + 2 < data.length ? data[i + 2] : 0;
+        // Word 1 (12 bits)
+        const w1 = (b1 << 4) | (b2 >> 4);
+        const c1 = encodeWord(w1);
+        out[outIdx++] = (c1 >> 16) & 0xFF;
+        out[outIdx++] = (c1 >> 8) & 0xFF;
+        out[outIdx++] = c1 & 0xFF;
+        if (i + 1 < data.length) {
+            // Word 2 (12 bits)
+            const w2 = ((b2 & 0x0F) << 8) | b3;
+            const c2 = encodeWord(w2);
+            out[outIdx++] = (c2 >> 16) & 0xFF;
+            out[outIdx++] = (c2 >> 8) & 0xFF;
+            out[outIdx++] = c2 & 0xFF;
+        }
+    }
+    return out;
+}
+function golayDecode(encoded) {
+    // B1-6: Throws if length is not a multiple of 6
+    if (encoded.length % 6 !== 0) {
+        throw new Error("Invalid Golay encoded data: length must be multiple of 6");
+    }
+    const outLen = Math.floor(encoded.length / 2);
+    const out = new Uint8Array(outLen);
+    let outIdx = 0;
+    let totalCorrected = 0;
+    let anyUncorrectable = false;
+    for (let i = 0; i < encoded.length; i += 6) {
+        const c1 = (encoded[i] << 16) | (encoded[i + 1] << 8) | encoded[i + 2];
+        const res1 = decodeWord(c1);
+        totalCorrected += res1.corrected;
+        if (res1.uncorrectable)
+            anyUncorrectable = true;
+        if (outIdx < outLen)
+            out[outIdx++] = (res1.msg >> 4) & 0xFF;
+        const b2_high = (res1.msg & 0x0F) << 4;
+        if (i + 3 < encoded.length) {
+            const c2 = (encoded[i + 3] << 16) | (encoded[i + 4] << 8) | encoded[i + 5];
+            const res2 = decodeWord(c2);
+            totalCorrected += res2.corrected;
+            if (res2.uncorrectable)
+                anyUncorrectable = true;
+            if (outIdx < outLen)
+                out[outIdx++] = b2_high | (res2.msg >> 8);
+            if (outIdx < outLen)
+                out[outIdx++] = res2.msg & 0xFF;
+        }
+        else {
+            if (outIdx < outLen)
+                out[outIdx++] = b2_high;
+        }
+    }
+    return { data: out, corrected: totalCorrected, uncorrectable: anyUncorrectable };
+}

package/dist/grg_forward.d.ts

@@ -0,0 +1,6 @@
+export declare class GrgForward {
+    static golombEncode(data: Uint8Array, m?: number): Uint8Array;
+    static redstuffEncode(data: Uint8Array, shards?: number, parity?: number): Uint8Array[];
+    static golayEncodeWrapper(data: Uint8Array): Uint8Array;
+    static encode(data: Uint8Array): Uint8Array[];
+}

package/dist/grg_forward.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrgForward = void 0;
+const crypto_1 = require("crypto");
+const golay_1 = require("./golay");
+const reed_solomon_1 = require("./reed_solomon");
+class GrgForward {
+    // 1. Golomb-Rice Compression
+    static golombEncode(data, m = 16) {
+        if (m < 2)
+            throw new Error("[GRG] Golomb parameter m must be >= 2");
+        const k = Math.log2(m);
+        if (!Number.isInteger(k))
+            throw new Error("M must be power of 2");
+        let bits = "";
+        for (const byte of data) {
+            const q = Math.floor(byte / m);
+            const r = byte % m;
+            bits += "1".repeat(q) + "0" + r.toString(2).padStart(k, "0");
+        }
+        const bytes = [];
+        for (let i = 0; i < bits.length; i += 8) {
+            bytes.push(parseInt(bits.substring(i, i + 8).padEnd(8, "0"), 2));
+        }
+        return new Uint8Array(bytes);
+    }
+    // 2. RedStuff Erasure Coding (Reed-Solomon GF(2^8))
+    static redstuffEncode(data, shards = 4, parity = 2) {
+        return reed_solomon_1.ReedSolomon.encode(data, shards, parity);
+    }
+    // 3. Golay(24,12) Error Correction Encoding
+    static golayEncodeWrapper(data) {
+        const encoded = (0, golay_1.golayEncode)(data);
+        // 🔱 Integrity: Append 8-byte SHA-256 hash of the encoded shard (B1-5: 4 -> 8 bytes)
+        const hash = (0, crypto_1.createHash)("sha256").update(Buffer.from(encoded)).digest();
+        const checksum = hash.subarray(0, 8);
+        const final = new Uint8Array(encoded.length + 8);
+        final.set(encoded);
+        final.set(checksum, encoded.length);
+        return final;
+    }
+    static encode(data) {
+        // R3-P0-3: Reject empty input — roundtrip breaks ([] → [0])
+        if (data.length === 0) {
+            throw new Error("[GRG] Cannot encode empty input — roundtrip identity violation");
+        }
+        const compressed = this.golombEncode(data);
+        // Prepend original length (4 bytes, big-endian) for exact roundtrip
+        const withLen = new Uint8Array(4 + compressed.length);
+        withLen[0] = (data.length >> 24) & 0xFF;
+        withLen[1] = (data.length >> 16) & 0xFF;
+        withLen[2] = (data.length >> 8) & 0xFF;
+        withLen[3] = data.length & 0xFF;
+        withLen.set(compressed, 4);
+        const shards = this.redstuffEncode(withLen);
+        return shards.map(s => this.golayEncodeWrapper(s));
+    }
+}
+exports.GrgForward = GrgForward;

package/dist/grg_inverse.d.ts

@@ -0,0 +1,7 @@
+export declare class GrgInverse {
+    static golayDecodeWrapper(data: Uint8Array): Uint8Array;
+    static redstuffDecode(shards: (Uint8Array | null)[], dataShardCount?: number, parityShardCount?: number): Uint8Array;
+    private static readonly MAX_GOLOMB_Q;
+    static golombDecode(data: Uint8Array, m?: number): Uint8Array;
+    static verify(data: Uint8Array, originalShards: Uint8Array[]): boolean;
+}