openttt 0.1.0

package/dist/grg_inverse.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrgInverse = void 0;
+const crypto_1 = require("crypto");
+const golay_1 = require("./golay");
+const logger_1 = require("./logger");
+const reed_solomon_1 = require("./reed_solomon");
+class GrgInverse {
+    // 1. Golay Decoding & Integrity Check 🔱
+    static golayDecodeWrapper(data) {
+        if (data.length < 8)
+            throw new Error("GRG shard too short for checksum");
+        // Split data and checksum (last 8 bytes)
+        const encoded = data.subarray(0, data.length - 8);
+        const checksum = data.subarray(data.length - 8);
+        // Verify SHA-256 Checksum (B1-5: 4 -> 8 bytes)
+        const hash = (0, crypto_1.createHash)("sha256").update(Buffer.from(encoded)).digest();
+        const expected = hash.subarray(0, 8);
+        if (!Buffer.from(checksum).equals(Buffer.from(expected))) {
+            throw new Error("GRG tamper detected: SHA-256 checksum mismatch");
+        }
+        // Proceed to Golay decode
+        const res = (0, golay_1.golayDecode)(encoded);
+        if (res.uncorrectable) {
+            throw new Error("GRG tamper detected: uncorrectable bit errors in Golay codeword");
+        }
+        return res.data;
+    }
+    // 2. RedStuff Decoding (Reed-Solomon GF(2^8))
+    static redstuffDecode(shards, dataShardCount = 4, parityShardCount = 2) {
+        return reed_solomon_1.ReedSolomon.decode(shards, dataShardCount, parityShardCount);
+    }
+    // 3. Golomb-Rice Decompression
+    // R4-P2-3: Max unary run length to prevent amplification DoS
+    static MAX_GOLOMB_Q = 1_000_000;
+    static golombDecode(data, m = 16) {
+        if (m < 2)
+            throw new Error("[GRG] Golomb parameter m must be >= 2");
+        const k = Math.log2(m);
+        let bits = "";
+        for (const byte of data) {
+            bits += byte.toString(2).padStart(8, "0");
+        }
+        const result = [];
+        let i = 0;
+        while (i < bits.length) {
+            let q = 0;
+            while (bits[i] === "1") {
+                q++;
+                i++;
+                if (q > this.MAX_GOLOMB_Q)
+                    throw new Error(`[GRG] Golomb decode: unary run exceeds ${this.MAX_GOLOMB_Q} — malformed or malicious input`);
+            }
+            if (bits[i] === "0")
+                i++;
+            const rStr = bits.substring(i, i + k);
+            if (rStr.length < k)
+                break;
+            const r = parseInt(rStr, 2);
+            result.push(q * m + r);
+            i += k;
+        }
+        return new Uint8Array(result);
+    }
+    static verify(data, originalShards) {
+        try {
+            const decodedShards = originalShards.map(s => {
+                try {
+                    return this.golayDecodeWrapper(s);
+                }
+                catch {
+                    return null;
+                }
+            });
+            const withLen = this.redstuffDecode(decodedShards);
+            // Extract original length
+            if (withLen.length < 4)
+                return false;
+            const origLen = (withLen[0] << 24) | (withLen[1] << 16) | (withLen[2] << 8) | withLen[3];
+            const compressed = withLen.subarray(4);
+            const decoded = this.golombDecode(compressed);
+            const final = decoded.subarray(0, origLen);
+            if (final.length !== data.length)
+                return false;
+            for (let i = 0; i < data.length; i++) {
+                if (final[i] !== data[i])
+                    return false;
+            }
+            return true;
+        }
+        catch (e) {
+            logger_1.logger.warn(`[GRG Inverse] Verification failed: ${e}`);
+            return false;
+        }
+    }
+}
+exports.GrgInverse = GrgInverse;

package/dist/grg_pipeline.d.ts

@@ -0,0 +1,13 @@
+export declare class GrgPipeline {
+    static readonly MAX_INPUT_SIZE: number;
+    /**
+     * Runs the full forward pipeline:
+     * Golomb-Rice -> RedStuff (Erasure) -> Golay(24,12)
+     */
+    static processForward(data: Uint8Array): Uint8Array[];
+    /**
+     * Runs the full inverse pipeline:
+     * Golay(24,12) -> RedStuff (Reconstruction) -> Golomb-Rice Decompression
+     */
+    static processInverse(shards: Uint8Array[], originalLength: number): Uint8Array;
+}

package/dist/grg_pipeline.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrgPipeline = void 0;
+const grg_forward_1 = require("./grg_forward");
+const grg_inverse_1 = require("./grg_inverse");
+const logger_1 = require("./logger");
+class GrgPipeline {
+    // P1-3: Max input size to prevent OOM attacks (100 MB)
+    static MAX_INPUT_SIZE = 100 * 1024 * 1024;
+    /**
+     * Runs the full forward pipeline:
+     * Golomb-Rice -> RedStuff (Erasure) -> Golay(24,12)
+     */
+    static processForward(data) {
+        if (data.length > this.MAX_INPUT_SIZE) {
+            throw new Error(`[GRG] Input size ${data.length} exceeds MAX_INPUT_SIZE ${this.MAX_INPUT_SIZE}`);
+        }
+        logger_1.logger.info("Starting GRG forward pipeline...");
+        try {
+            const shards = grg_forward_1.GrgForward.encode(data);
+            logger_1.logger.info(`GRG forward pipeline complete. Generated ${shards.length} shards.`);
+            return shards;
+        }
+        catch (error) {
+            logger_1.logger.error(`GRG forward pipeline failed: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Runs the full inverse pipeline:
+     * Golay(24,12) -> RedStuff (Reconstruction) -> Golomb-Rice Decompression
+     */
+    static processInverse(shards, originalLength) {
+        logger_1.logger.info("Starting GRG inverse pipeline...");
+        try {
+            const decodedShards = shards.map(s => {
+                try {
+                    return grg_inverse_1.GrgInverse.golayDecodeWrapper(s);
+                }
+                catch (e) {
+                    logger_1.logger.warn(`Golay decode failed for a shard: ${e}`);
+                    return null;
+                }
+            });
+            const withLen = grg_inverse_1.GrgInverse.redstuffDecode(decodedShards);
+            // Extract original length from the first 4 bytes
+            const decodedLength = (withLen[0] << 24) | (withLen[1] << 16) | (withLen[2] << 8) | withLen[3];
+            const compressed = withLen.subarray(4);
+            const decompressed = grg_inverse_1.GrgInverse.golombDecode(compressed);
+            const final = decompressed.subarray(0, decodedLength);
+            // P1-4 FIX: Length mismatch is a corruption signal — throw instead of warn
+            if (final.length !== originalLength) {
+                throw new Error(`[GRG] Length mismatch in inverse: expected ${originalLength}, got ${final.length}`);
+            }
+            logger_1.logger.info("GRG inverse pipeline complete.");
+            return final;
+        }
+        catch (error) {
+            logger_1.logger.error(`GRG inverse pipeline failed: ${error}`);
+            throw error;
+        }
+    }
+}
+exports.GrgPipeline = GrgPipeline;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./grg_forward";
+export * from "./grg_inverse";
+export * from "./adaptive_switch";
+export * from "./evm_connector";
+export * from "./x402_enforcer";
+export * from "./ttt_builder";
+export * from "./protocol_fee";
+export * from "./pool_registry";
+export * from "./v4_hook";
+export * from "./logger";
+export * from "./types";
+export * from "./ttt_client";
+export * from "./auto_mint";
+export * from "./time_synthesis";
+export * from "./dynamic_fee";
+export * from "./golay";
+export * from "./grg_pipeline";
+export * from "./signer";
+export * from "./networks";
+export * from "./reed_solomon";
+export * from "./errors";

package/dist/index.js

@@ -0,0 +1,38 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// sdk/src/index.ts
+__exportStar(require("./grg_forward"), exports);
+__exportStar(require("./grg_inverse"), exports);
+__exportStar(require("./adaptive_switch"), exports);
+__exportStar(require("./evm_connector"), exports);
+__exportStar(require("./x402_enforcer"), exports);
+__exportStar(require("./ttt_builder"), exports);
+__exportStar(require("./protocol_fee"), exports);
+__exportStar(require("./pool_registry"), exports);
+__exportStar(require("./v4_hook"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./ttt_client"), exports);
+__exportStar(require("./auto_mint"), exports);
+__exportStar(require("./time_synthesis"), exports);
+__exportStar(require("./dynamic_fee"), exports);
+__exportStar(require("./golay"), exports);
+__exportStar(require("./grg_pipeline"), exports);
+__exportStar(require("./signer"), exports);
+__exportStar(require("./networks"), exports);
+__exportStar(require("./reed_solomon"), exports);
+__exportStar(require("./errors"), exports);

package/dist/logger.d.ts

@@ -0,0 +1,18 @@
+export declare enum LogLevel {
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    DEBUG = "DEBUG"
+}
+export declare class Logger {
+    private static instance;
+    private namespace;
+    private constructor();
+    static getInstance(namespace?: string): Logger;
+    private formatMessage;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string, error?: Error): void;
+    debug(message: string): void;
+}
+export declare const logger: Logger;

package/dist/logger.js

@@ -0,0 +1,51 @@
+"use strict";
+// sdk/src/logger.ts — Structured Logging Wrapper
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.Logger = exports.LogLevel = void 0;
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["INFO"] = "INFO";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+    LogLevel["DEBUG"] = "DEBUG";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+class Logger {
+    static instance;
+    namespace;
+    constructor(namespace = "TTT-SDK") {
+        this.namespace = namespace;
+    }
+    static getInstance(namespace) {
+        if (!Logger.instance) {
+            Logger.instance = new Logger(namespace);
+        }
+        return Logger.instance;
+    }
+    formatMessage(level, message) {
+        const timestamp = new Date().toISOString();
+        return `[${timestamp}] [${level}] [${this.namespace}] ${message}`;
+    }
+    info(message) {
+        console.log(this.formatMessage(LogLevel.INFO, message));
+    }
+    warn(message) {
+        console.warn(this.formatMessage(LogLevel.WARN, message));
+    }
+    error(message, error) {
+        let msg = message;
+        if (error) {
+            msg += ` | Error: ${error.message}`;
+            if (error.stack) {
+                msg += `\nStack: ${error.stack}`;
+            }
+        }
+        console.error(this.formatMessage(LogLevel.ERROR, msg));
+    }
+    debug(message) {
+        if (process.env.DEBUG) {
+            console.debug(this.formatMessage(LogLevel.DEBUG, message));
+        }
+    }
+}
+exports.Logger = Logger;
+exports.logger = Logger.getInstance();

package/dist/networks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Network configuration for TTT SDK
+ */
+export interface NetworkConfig {
+    chainId: number;
+    rpcUrl: string;
+    tttAddress: string;
+    protocolFeeAddress: string;
+    usdcAddress: string;
+}
+export declare const BASE_MAINNET: NetworkConfig;
+export declare const BASE_SEPOLIA: NetworkConfig;
+export declare const NETWORKS: Record<string, NetworkConfig>;

package/dist/networks.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NETWORKS = exports.BASE_SEPOLIA = exports.BASE_MAINNET = void 0;
+// ⚠️ MAINNET ADDRESSES NOT YET DEPLOYED — must be overridden via TTTClientConfig.contractAddress
+// Using these defaults without override will throw at runtime (validated in TTTClient.create)
+exports.BASE_MAINNET = {
+    chainId: 8453,
+    rpcUrl: "https://mainnet.base.org",
+    tttAddress: "0x0000000000000000000000000000000000000000",
+    protocolFeeAddress: "0x0000000000000000000000000000000000000000",
+    usdcAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+};
+exports.BASE_SEPOLIA = {
+    chainId: 84532,
+    rpcUrl: "https://sepolia.base.org",
+    tttAddress: "0xde357135cA493e59680182CDE9E1c6A4dA400811",
+    protocolFeeAddress: "0xE289337d3a79b22753BDA03510a8b8E4D1040F21",
+    usdcAddress: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+};
+exports.NETWORKS = {
+    base: exports.BASE_MAINNET,
+    sepolia: exports.BASE_SEPOLIA,
+};

package/dist/pool_registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PoolRegistry - TTT Pool Registry
+ * Manages registration of pools and tracks minting/burning statistics.
+ */
+export declare class PoolRegistry {
+    private static readonly MAX_POOLS;
+    private pools;
+    private static readonly MAX_TOKEN_MAPPINGS;
+    private tokenToPool;
+    /**
+     * Register a new pool for TTT isolation.
+     * @param chainId The chain ID where the pool is located.
+     * @param poolAddress The address of the pool.
+     */
+    registerPool(chainId: number, poolAddress: string): Promise<void>;
+    /**
+     * Generate keccak256 tokenId based on chainId, poolAddress, timestamp and slotIndex.
+     * @param chainId The chain ID.
+     * @param poolAddress The pool address.
+     * @param timestamp The timestamp of the TTT.
+     * @param slotIndex The slot index.
+     * @returns The generated tokenId as a hex string.
+     */
+    getTokenId(chainId: number, poolAddress: string, timestamp: bigint, slotIndex: number): string;
+    /**
+     * Verify if a tokenId belongs to a specific pool.
+     * @param tokenId The tokenId to verify.
+     * @param poolAddress The pool address to check against.
+     * @returns True if the tokenId belongs to the pool.
+     */
+    isValidForPool(tokenId: string, poolAddress: string): boolean;
+    /**
+     * Get minting/burning statistics for a pool.
+     * @param poolAddress The pool address.
+     * @returns Statistics for the pool or null if not registered.
+     */
+    getPoolStats(poolAddress: string): {
+        minted: bigint;
+        burned: bigint;
+    } | null;
+    /**
+     * Record a minting event for a pool. (Internal/Helper method)
+     * @param poolAddress The pool address.
+     * @param amount The amount minted.
+     */
+    recordMint(poolAddress: string, amount: bigint): void;
+    /**
+     * Record a burning event for a pool. (Internal/Helper method)
+     * @param poolAddress The pool address.
+     * @param amount The amount burned.
+     */
+    recordBurn(poolAddress: string, amount: bigint): void;
+    /**
+     * List all registered pool addresses.
+     * @returns Array of pool addresses.
+     */
+    listPools(): string[];
+}

package/dist/pool_registry.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolRegistry = void 0;
+const ethers_1 = require("ethers");
+/**
+ * PoolRegistry - TTT Pool Registry
+ * Manages registration of pools and tracks minting/burning statistics.
+ */
+class PoolRegistry {
+    // R4-P1-4: Capacity limit to prevent Sybil DoS
+    static MAX_POOLS = 10000;
+    pools = new Map();
+    // R8-5: Bounded token-to-pool map to prevent unbounded memory growth
+    static MAX_TOKEN_MAPPINGS = 100000;
+    tokenToPool = new Map();
+    /**
+     * Register a new pool for TTT isolation.
+     * @param chainId The chain ID where the pool is located.
+     * @param poolAddress The address of the pool.
+     */
+    async registerPool(chainId, poolAddress) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            throw new Error(`[PoolRegistry] Invalid pool address: ${poolAddress}`);
+        const key = poolAddress.toLowerCase();
+        if (!this.pools.has(key)) {
+            // R4-P1-4: Sybil DoS prevention
+            if (this.pools.size >= PoolRegistry.MAX_POOLS) {
+                throw new Error(`[PoolRegistry] Registry full (max ${PoolRegistry.MAX_POOLS} pools). Cannot register more.`);
+            }
+            this.pools.set(key, { chainId, minted: 0n, burned: 0n });
+        }
+    }
+    /**
+     * Generate keccak256 tokenId based on chainId, poolAddress, timestamp and slotIndex.
+     * @param chainId The chain ID.
+     * @param poolAddress The pool address.
+     * @param timestamp The timestamp of the TTT.
+     * @param slotIndex The slot index.
+     * @returns The generated tokenId as a hex string.
+     */
+    getTokenId(chainId, poolAddress, timestamp, slotIndex) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            throw new Error(`[PoolRegistry] Invalid pool address: ${poolAddress}`);
+        // R2-P2-4: Validate slotIndex fits in uint32
+        if (slotIndex < 0 || slotIndex > 0xFFFFFFFF || !Number.isInteger(slotIndex)) {
+            throw new Error(`[PoolRegistry] slotIndex must be integer in [0, ${0xFFFFFFFF}], got: ${slotIndex}`);
+        }
+        // uint64 max value check
+        if (timestamp > 18446744073709551615n) {
+            throw new Error(`[PoolRegistry] Timestamp overflow: ${timestamp} exceeds uint64 max`);
+        }
+        const normalizedAddress = poolAddress.toLowerCase();
+        const abiCoder = ethers_1.ethers.AbiCoder.defaultAbiCoder();
+        const tokenId = ethers_1.ethers.keccak256(abiCoder.encode(["uint256", "address", "uint64", "uint32"], [BigInt(chainId), normalizedAddress, timestamp, slotIndex]));
+        // Store mapping to support isValidForPool
+        // R8-5: Evict oldest entry if at capacity (FIFO via Map insertion order)
+        if (this.tokenToPool.size >= PoolRegistry.MAX_TOKEN_MAPPINGS) {
+            const oldest = this.tokenToPool.keys().next().value;
+            if (oldest !== undefined)
+                this.tokenToPool.delete(oldest);
+        }
+        this.tokenToPool.set(tokenId, normalizedAddress);
+        return tokenId;
+    }
+    /**
+     * Verify if a tokenId belongs to a specific pool.
+     * @param tokenId The tokenId to verify.
+     * @param poolAddress The pool address to check against.
+     * @returns True if the tokenId belongs to the pool.
+     */
+    isValidForPool(tokenId, poolAddress) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            return false;
+        const normalizedAddress = poolAddress.toLowerCase();
+        const registeredPool = this.tokenToPool.get(tokenId);
+        return registeredPool === normalizedAddress;
+    }
+    /**
+     * Get minting/burning statistics for a pool.
+     * @param poolAddress The pool address.
+     * @returns Statistics for the pool or null if not registered.
+     */
+    getPoolStats(poolAddress) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            return null;
+        const normalizedAddress = poolAddress.toLowerCase();
+        const stats = this.pools.get(normalizedAddress);
+        if (!stats) {
+            return null;
+        }
+        return { minted: stats.minted, burned: stats.burned };
+    }
+    /**
+     * Record a minting event for a pool. (Internal/Helper method)
+     * @param poolAddress The pool address.
+     * @param amount The amount minted.
+     */
+    recordMint(poolAddress, amount) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            return;
+        const normalizedAddress = poolAddress.toLowerCase();
+        const stats = this.pools.get(normalizedAddress);
+        if (stats) {
+            stats.minted += amount;
+        }
+    }
+    /**
+     * Record a burning event for a pool. (Internal/Helper method)
+     * @param poolAddress The pool address.
+     * @param amount The amount burned.
+     */
+    recordBurn(poolAddress, amount) {
+        if (!poolAddress || !ethers_1.ethers.isAddress(poolAddress.toLowerCase()))
+            return;
+        const normalizedAddress = poolAddress.toLowerCase();
+        const stats = this.pools.get(normalizedAddress);
+        if (stats) {
+            stats.burned += amount;
+        }
+    }
+    /**
+     * List all registered pool addresses.
+     * @returns Array of pool addresses.
+     */
+    listPools() {
+        return Array.from(this.pools.keys());
+    }
+}
+exports.PoolRegistry = PoolRegistry;

package/dist/protocol_fee.d.ts

@@ -0,0 +1,56 @@
+import { FeeCalculation } from "./dynamic_fee";
+import { EVMConnector } from "./evm_connector";
+/**
+ * ProtocolFeeCollector - Helm 프로토콜 수수료 수취 및 검증 담당
+ * x402 컴플라이언스를 위해 EIP-712 서명 검증을 포함
+ */
+export declare class ProtocolFeeCollector {
+    private totalCollected;
+    private chainId;
+    private verifyingContract;
+    private usedSignatures;
+    private readonly MAX_REPLAY_CACHE;
+    private readonly REPLAY_TTL_MS;
+    private evmConnector;
+    private protocolFeeRecipient;
+    private feeContract;
+    constructor(chainId: number, verifyingContract: string, evmConnector: EVMConnector, protocolFeeRecipient: string);
+    /**
+     * R3-P0-2: Verify chainId matches the actual connected network.
+     * Must be called after EVMConnector.connect() to prevent cross-chain signature replay.
+     */
+    validateChainId(): Promise<void>;
+    private getFeeContract;
+    /**
+     * 민팅 수수료 수취 (Stablecoin)
+     * @param feeCalc - DynamicFeeEngine에서 계산된 수수료 정보
+     * @param signature - EIP-712 서명 (필수, x402 검증용)
+     * @param user - 서명자 주소
+     * @param nonce - 중복 방지 nonce
+     * @param deadline - 서명 유효 기한
+     */
+    collectMintFee(feeCalc: FeeCalculation, signature: string, user: string, nonce: bigint, deadline: number): Promise<void>;
+    /**
+     * 소각 수수료 수취
+     * @param feeCalc - DynamicFeeEngine에서 계산된 수수료 정보
+     * @param signature - EIP-712 서명 (필수)
+     * @param user - 서명자 주소
+     * @param nonce - 중복 방지 nonce
+     * @param deadline - 서명 유효 기한
+     */
+    collectBurnFee(feeCalc: FeeCalculation, signature: string, user: string, nonce: bigint, deadline: number): Promise<void>;
+    /**
+     * 현재까지 수취한 총 수수료 반환
+     */
+    getCollectedFees(): Promise<bigint>;
+    /**
+     * P1-2: Prune expired signatures from replay cache
+     */
+    private lastPruneTime;
+    private static readonly PRUNE_INTERVAL_MS;
+    private pruneExpiredSignatures;
+    /**
+     * EIP-712 서명 검증 (x402 compliance)
+     */
+    private verifySignature;
+}