openttt 0.1.2 → 0.2.0

package/README.md

@@ -10,7 +10,9 @@ OpenTTT brings cryptographic time verification to blockchain transaction orderin
 [![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)
 [![CI](https://github.com/Helm-Protocol/OpenTTT/actions/workflows/ci.yml/badge.svg)](https://github.com/Helm-Protocol/OpenTTT/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/Helm-Protocol/OpenTTT/branch/main/graph/badge.svg)](https://codecov.io/gh/Helm-Protocol/OpenTTT)
-[![Tests](https://img.shields.io/badge/tests-273%20passing%20%C2%B7%2029%20suites-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-386%20passing%20%C2%B7%2032%20suites-brightgreen)]()
+
+> If this project is useful to you, please [star it on GitHub](https://github.com/Helm-Protocol/OpenTTT) — it helps others find it.
 
 ```
 npm install openttt
@@ -27,7 +29,7 @@ Current MEV protection relies on **trust**: builders promise fair ordering, prot
 | **Mechanism** | Social contract (request) | Physical verification (proof) |
 | **Enforcement** | Reputation, exclusion | Economic natural selection |
 | **Bad actors** | Must be identified and removed | Naturally unprofitable, self-selecting out |
-| **Time source** | Block timestamp (miner-controlled) | Multi-source NTP synthesis (NIST, KRISS, Google) |
+| **Time source** | Block timestamp (miner-controlled) | Multi-source NTP synthesis (NIST, Google, Apple) |
 
 **The core insight**: Rollups generate precise timestamps and deliver them to builders with a receipt. The Adaptive GRG pipeline then verifies whether the builder respected that ordering:
 
@@ -40,7 +42,22 @@ No governance vote. No slashing committee. Cheating is simply bad business.
 
 ## Quick Start
 
-Three lines to start minting TimeTokens:
+### Try it in 30 seconds — No ETH, No Wallet
+
+```typescript
+import { HttpOnlyClient } from "openttt";
+
+const client = new HttpOnlyClient();
+const pot = await client.generatePoT();
+console.log(pot.timestamp, pot.confidence, pot.sources);
+
+const valid = client.verifyPoT(pot);
+console.log("Valid:", valid); // true
+```
+
+No blockchain. No wallet. No gas fees. Just verified time from 4 independent HTTPS sources (NIST, Apple, Google, Cloudflare). Start here, upgrade to on-chain when ready.
+
+### On-Chain Mode (Full Power)
 
 ```typescript
 import { TTTClient } from "openttt";
@@ -49,9 +66,7 @@ const ttt = await TTTClient.forBase({ privateKey: process.env.OPERATOR_PK! });
 ttt.startAutoMint();
 ```
 
-That is it. The SDK connects to Base Mainnet, synthesizes time from three atomic clock sources, and begins minting Proof-of-Time tokens at your configured tier interval.
-
-> **Shorthand**: Pass `privateKey` directly as a string instead of the full `signer` config object. The verbose form `{ signer: { type: "privateKey", key: "0x..." } }` still works for when you need other signer types (Turnkey, KMS, Privy).
+Connects to Base, synthesizes time from atomic clock sources, and mints Proof-of-Time tokens on-chain.
 
 ---
 
@@ -95,7 +110,7 @@ const ttt = await TTTClient.create({
   tier: "T1_block",
   contractAddress: "0x...",
   poolAddress: "0x...",
-  timeSources: ["nist", "kriss", "google"],
+  timeSources: ["nist", "google", "cloudflare", "apple"],
   protocolFeeRate: 0.05,
   enableGracefulShutdown: true,
 });
@@ -246,8 +261,8 @@ const ttt = await TTTClient.create({
 
 | Method | Description |
 |---|---|
-| `GrgPipeline.processForward(data)` | Encode: Golomb compression -> Reed-Solomon erasure coding -> Golay verification |
-| `GrgPipeline.processInverse(shards, length)` | Decode: Golay verify -> Reed-Solomon reconstruct -> Golomb decompress |
+| `GrgPipeline.processForward(data)` | Encode data through the multi-layer integrity pipeline, producing verifiable shards |
+| `GrgPipeline.processInverse(shards, length)` | Decode shards back to original data with integrity verification |
 
 ### AdaptiveSwitch
 
@@ -264,37 +279,23 @@ const ttt = await TTTClient.create({
 ```
 TTTClient (entry point)
 |-- AutoMintEngine         Periodic minting loop
-|   |-- TimeSynthesis      NTP multi-source median synthesis (NIST, KRISS, Google)
+|   |-- TimeSynthesis      NTP multi-source median synthesis (NIST, Google, Apple)
 |   |-- DynamicFeeEngine   Oracle-based pricing
 |   |-- EVMConnector       On-chain mint/burn/events (ethers v6)
 |   '-- ProtocolFee        EIP-712 signed fee collection
 |-- AdaptiveSwitch         TURBO/FULL mode state machine
-|-- GRG Pipeline           Golomb + Reed-Solomon + Golay error correction
+|-- GRG Pipeline           Multi-layer data integrity (proprietary)
 |-- PoolRegistry           Multi-pool statistics tracking
 '-- Signer Abstraction     PrivateKey | Turnkey | Privy | KMS
 ```
 
-### The GRG Pipeline
+### Data Integrity: GRG Pipeline
 
-GRG (Golomb-Reed-Golay) is the data integrity backbone of OpenTTT, analogous to how the TLS record protocol protects HTTP payloads.
+GRG is a multi-layer data integrity pipeline that protects PoT payloads — analogous to how the TLS record protocol protects HTTP payloads. It provides compression, erasure coding, and error correction in a single pass.
 
-```
-              FORWARD (Encode)
-  Raw Data --> Golomb-Rice Compression
-           --> Reed-Solomon Erasure Coding
-           --> Golay(24,12) Verification Codes
-           --> Shards
-
-              INVERSE (Decode)
-  Shards   --> Golay(24,12) Error Detection
-           --> Reed-Solomon Reconstruction
-           --> Golomb-Rice Decompression
-           --> Raw Data
-```
+The pipeline produces verifiable shards that can be independently validated and reconstructed, ensuring PoT integrity even under partial data loss.
 
-**Golomb-Rice** compresses timestamp deltas efficiently (small integers compress well).
-**Reed-Solomon** adds erasure coding so data survives shard loss.
-**Golay(24,12)** detects and corrects up to 3-bit errors per 24-bit codeword.
+> Implementation details are proprietary. See the [IETF Draft](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) for the abstract specification.
 
 ### Adaptive Mode Switching
 
@@ -311,7 +312,7 @@ This asymmetry is deliberate: it is hard to earn trust and easy to lose it.
 OpenTTT queries multiple atomic clock-synchronized NTP sources in parallel and produces a median-synthesized timestamp with confidence scoring:
 
 - **NIST** (time.nist.gov) -- US national standard
-- **KRISS** (time.kriss.re.kr) -- Korean national standard
+- **Apple** (time.apple.com) -- Apple global time service
 - **Google** (time.google.com) -- Leap-smeared public NTP
 
 All readings must fall within a stratum-dependent tolerance of the synthesized median (10ms for stratum 1, 25ms for stratum 2, 50ms for stratum 3+), or the Proof of Time is rejected. Single-source operation triggers a degraded-confidence warning.
@@ -390,4 +391,25 @@ Copyright 2026 Helm Protocol.
 
 ---
 
+## Learn More
+
+- [IETF Draft: draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
+- [Yellow Paper](https://github.com/Helm-Protocol/OpenTTT/blob/main/YELLOW_PAPER.md) — Technical Deep Dive
+- [MCP Server](https://github.com/Helm-Protocol/OpenTTT/tree/main/mcp) — AI Agent Integration (`@helm-protocol/ttt-mcp`)
+- [Subgraph (The Graph)](https://api.studio.thegraph.com/query/1744392/openttt-base-sepolia/v0.2.0) — On-chain PoT Data
+- [Base Sepolia Contracts](https://sepolia.basescan.org/address/0xde357135cA493e59680182CDE9E1c6A4dA400811) — TTT ERC-1155
+- [Helm Protocol](https://github.com/Helm-Protocol) — GitHub Organization
+
 [GitHub](https://github.com/Helm-Protocol/OpenTTT) | Built by [Helm Protocol](https://github.com/Helm-Protocol)
+
+---
+
+## Contributing
+
+Contributions are welcome. If you find a bug, have a feature request, or want to improve the documentation, please open an issue or submit a pull request on [GitHub](https://github.com/Helm-Protocol/OpenTTT).
+
+- **Bug reports**: Open an issue with a minimal reproduction case.
+- **Feature requests**: Open an issue describing the use case and expected behavior.
+- **Pull requests**: Fork the repo, make your changes, ensure all tests pass (`npm test`), and open a PR against `main`.
+
+For significant changes, please open an issue first to discuss the approach.

package/dist/adaptive_switch.d.ts

@@ -12,6 +12,8 @@ export interface Block {
     txs: string[];
     data: Uint8Array;
 }
+/** Tier-based dynamic tolerance (ms) — auditor-requested upgrade */
+export declare const TIER_TOLERANCE_MS: Record<string, number>;
 export declare class AdaptiveSwitch {
     private windowSize;
     private threshold;
@@ -22,23 +24,36 @@ export declare class AdaptiveSwitch {
     private consecutiveFailures;
     private turboEntryThreshold;
     private turboMaintainThreshold;
+    private tolerance;
+    constructor(options?: {
+        tolerance?: number;
+    });
     /**
-     * TTT의 핵심 메커니즘: 타임스탬프 순서 일치율에 따른 Turbo/Full 모드 전환
+     * Core TTT mechanism: switches between Turbo/Full mode based on timestamp ordering match rate.
      */
-    verifyBlock(block: Block, tttRecord: TTTRecord): AdaptiveMode;
+    verifyBlock(block: Block, tttRecord: TTTRecord, chainId: number, poolAddress: string, tier?: string): AdaptiveMode;
     /**
-     * 모드에 따른 수수료 할인율 반환
-     * TURBO: 20% 할인 (수익 증가 유도)
-     * FULL: 할인 없음
+     * Return fee discount rate based on current mode.
+     * TURBO: 20% discount (incentivizes profitability).
+     * FULL: No discount.
      */
     getFeeDiscount(): number;
     /**
-     * 현재 모드 조회
+     * Get current adaptive mode.
      */
     getCurrentMode(): AdaptiveMode;
     /**
-     * 테스트용: 이력 초기화
+     * Reset history (for testing).
      */
     reset(): void;
+    /**
+     * Serialize internal state to JSON for persistence across restarts.
+     * Allows operators to avoid re-learning over 20 blocks after a restart.
+     */
+    serialize(): string;
+    /**
+     * Reconstruct an AdaptiveSwitch from previously serialized JSON state.
+     */
+    static deserialize(json: string): AdaptiveSwitch;
     private compareTransactionOrder;
 }

package/dist/adaptive_switch.js

@@ -2,15 +2,22 @@
 // sdk/src/adaptive_switch.ts — Adaptive Mode Switcher
 // Turbo (50ms) vs Full (127ms)
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AdaptiveSwitch = exports.AdaptiveMode = void 0;
-const grg_inverse_1 = require("./grg_inverse");
+exports.AdaptiveSwitch = exports.TIER_TOLERANCE_MS = exports.AdaptiveMode = void 0;
+const helm_crypto_1 = require("../vendor/helm-crypto");
 const logger_1 = require("./logger");
 var AdaptiveMode;
 (function (AdaptiveMode) {
     AdaptiveMode["TURBO"] = "TURBO";
     AdaptiveMode["FULL"] = "FULL";
 })(AdaptiveMode || (exports.AdaptiveMode = AdaptiveMode = {}));
-const TOLERANCE = 100; // 100ms tolerance for KTSat sync
+// const TOLERANCE = 100; // 100ms tolerance for KTSat sync (now configurable via constructor)
+/** Tier-based dynamic tolerance (ms) — auditor-requested upgrade */
+exports.TIER_TOLERANCE_MS = {
+    T0_epoch: 2000, // 6.4min tick → 2s tolerance
+    T1_block: 200, // 2s tick → 200ms
+    T2_slot: 500, // 12s tick → 500ms
+    T3_micro: 10, // 100ms tick → 10ms (10%)
+};
 class AdaptiveSwitch {
     windowSize = 20; // B1-9: Updated from 10 to 20
     threshold = 0.9; // B1-9: Updated from 0.8 to 0.9
@@ -21,17 +28,22 @@ class AdaptiveSwitch {
     consecutiveFailures = 0; // P2-1: Track consecutive failures for exponential backoff
     turboEntryThreshold = 0.95; // P2-2: Hysteresis — stricter entry
     turboMaintainThreshold = 0.85; // P2-2: Hysteresis — relaxed maintenance
+    tolerance;
+    constructor(options) {
+        this.tolerance = options?.tolerance ?? 100;
+    }
     /**
-     * TTT의 핵심 메커니즘: 타임스탬프 순서 일치율에 따른 Turbo/Full 모드 전환
+     * Core TTT mechanism: switches between Turbo/Full mode based on timestamp ordering match rate.
      */
-    verifyBlock(block, tttRecord) {
-        // 1. 타임스탬프 순서 및 시간 일치 여부 확인
+    verifyBlock(block, tttRecord, chainId, poolAddress, tier) {
+        // 1. Check timestamp ordering and time match
         const orderMatch = this.compareTransactionOrder(block.txs, tttRecord.txOrder);
-        const timeMatch = Math.abs(block.timestamp - tttRecord.time) < TOLERANCE;
+        const tolerance = tier ? (exports.TIER_TOLERANCE_MS[tier] ?? this.tolerance) : this.tolerance;
+        const timeMatch = Math.abs(block.timestamp - tttRecord.time) < tolerance;
         let sequenceOk = orderMatch && timeMatch;
         // B1-1: Do not skip GrgInverse.verify() in TURBO mode
         // We check integrity regardless of mode
-        const integrityOk = grg_inverse_1.GrgInverse.verify(block.data, tttRecord.grgPayload);
+        const integrityOk = helm_crypto_1.GrgInverse.verify(block.data, tttRecord.grgPayload, chainId, poolAddress);
         if (!integrityOk) {
             logger_1.logger.error(`[AdaptiveSwitch] GRG integrity check FAILED`);
             sequenceOk = false; // Mark as false if integrity fails
@@ -42,7 +54,7 @@ class AdaptiveSwitch {
                 this.penaltyCooldown = 20 * Math.pow(2, this.consecutiveFailures - 1); // 20, 40, 80, 160, 320
             }
         }
-        // 2. 이력 업데이트 (Sliding Window)
+        // 2. Update history (Sliding Window)
         this.history.push(sequenceOk);
         if (this.history.length > this.windowSize) {
             this.history.shift();
@@ -50,7 +62,7 @@ class AdaptiveSwitch {
         if (this.penaltyCooldown > 0) {
             this.penaltyCooldown--;
         }
-        // 3. 일치율 계산 및 모드 전환
+        // 3. Calculate match rate and switch mode
         const matchCount = this.history.filter(h => h).length;
         const matchRate = this.history.length > 0 ? matchCount / this.history.length : 0;
         // P2-2: Hysteresis — different thresholds for entering vs maintaining TURBO
@@ -73,21 +85,21 @@ class AdaptiveSwitch {
         return this.currentMode;
     }
     /**
-     * 모드에 따른 수수료 할인율 반환
-     * TURBO: 20% 할인 (수익 증가 유도)
-     * FULL: 할인 없음
+     * Return fee discount rate based on current mode.
+     * TURBO: 20% discount (incentivizes profitability).
+     * FULL: No discount.
      */
     getFeeDiscount() {
         return this.currentMode === AdaptiveMode.TURBO ? 0.2 : 0.0;
     }
     /**
-     * 현재 모드 조회
+     * Get current adaptive mode.
      */
     getCurrentMode() {
         return this.currentMode;
     }
     /**
-     * 테스트용: 이력 초기화
+     * Reset history (for testing).
      */
     reset() {
         this.history = [];
@@ -95,6 +107,31 @@ class AdaptiveSwitch {
         this.penaltyCooldown = 0;
         this.consecutiveFailures = 0;
     }
+    /**
+     * Serialize internal state to JSON for persistence across restarts.
+     * Allows operators to avoid re-learning over 20 blocks after a restart.
+     */
+    serialize() {
+        return JSON.stringify({
+            history: this.history,
+            currentMode: this.currentMode,
+            consecutiveFailures: this.consecutiveFailures,
+            penaltyCooldown: this.penaltyCooldown,
+            tolerance: this.tolerance,
+        });
+    }
+    /**
+     * Reconstruct an AdaptiveSwitch from previously serialized JSON state.
+     */
+    static deserialize(json) {
+        const data = JSON.parse(json);
+        const instance = new AdaptiveSwitch({ tolerance: data.tolerance ?? 100 });
+        instance.history = data.history;
+        instance.currentMode = data.currentMode;
+        instance.consecutiveFailures = data.consecutiveFailures;
+        instance.penaltyCooldown = data.penaltyCooldown;
+        return instance;
+    }
     compareTransactionOrder(blockTxs, expectedOrder) {
         if (blockTxs.length !== expectedOrder.length)
             return false;

package/dist/auto_mint.d.ts

@@ -1,8 +1,9 @@
+import { TimeSynthesis } from "./time_synthesis";
 import { EVMConnector } from "./evm_connector";
 import { AutoMintConfig, MintResult } from "./types";
 /**
- * AutoMintEngine - TTT 자동 민팅 엔진
- * 시간 합성, 동적 수수료 계산, EVM 민팅을 하나의 루프로 결합
+ * AutoMintEngine - Automatic TTT minting engine.
+ * Combines time synthesis, dynamic fee calculation, and EVM minting into a single loop.
  */
 export declare class AutoMintEngine {
     private config;
@@ -20,26 +21,40 @@ export declare class AutoMintEngine {
     private consecutiveFailures;
     private maxConsecutiveFailures;
     private potSigner;
+    /** Monotonic counter appended to tokenId hash to prevent collision when two mints share the same nanosecond timestamp. */
+    private mintNonce;
+    /** Fire the GRG >50ms performance warning at most once per engine session. */
+    private warnedGrgSlow;
     constructor(config: AutoMintConfig);
     getEvmConnector(): EVMConnector;
+    getTimeSynthesis(): TimeSynthesis;
     setOnMint(callback: (result: MintResult) => void): void;
     setOnFailure(callback: (error: Error) => void): void;
     setOnLatency(callback: (ms: number) => void): void;
     /**
-     * 엔진 초기화 (RPC 연결 및 컨트랙트 설정)
+     * Initialize the engine (RPC connection and contract setup).
      */
     initialize(): Promise<void>;
     /**
-     * 자동 민팅 루프 시작
+     * Start the automatic minting loop.
      */
     start(): void;
     /**
-     * 자동 민팅 루프 정지
+     * Stop the automatic minting loop.
      */
     stop(): void;
     /**
-     * 단일 민트 틱 실행
-     * 시간합성 → tokenId 생성 → EVM mint 호출 → 수수료 계산/차감
+     * Resume the minting loop after a circuit breaker trip.
+     * Resets the consecutive failure counter and restarts the loop.
+     */
+    resume(): void;
+    /**
+     * Sleep helper for retry backoff.
+     */
+    private sleep;
+    /**
+     * Execute a single mint tick.
+     * Time synthesis -> tokenId generation -> EVM mint call -> fee calculation/deduction.
      */
     mintTick(): Promise<void>;
     private signFeeMessage;