openttt 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,48 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:           Helm Protocol Foundation
+Licensed Work:      TikitakaTime SDK v0.1.0 (OpenTTT)
+Additional Use
+Grant:              Non-production evaluation and testing.
+Change Date:        March 14, 2030
+Change License:     Apache License, Version 2.0
+
+1.  Grant of License. Licensor hereby grants you a world-wide, royalty-free,
+    non-exclusive, non-sublicensable, non-transferable license to use the
+    Licensed Work, subject to the conditions set forth in this License.
+
+2.  Conditions. You may use the Licensed Work for any purpose, except for
+    Commercial Use.
+
+3.  Commercial Use. Commercial Use means any use of the Licensed Work that is
+    intended for or directed toward commercial advantage or monetary
+    compensation.
+
+4.  Change. On the Change Date, this License shall terminate and the Licensor
+    hereby grants you a license to the Licensed Work under the Change License.
+
+5.  Intellectual Property. This License does not grant you any rights in the
+    Intellectual Property of the Licensor, except for the license to use the
+    Licensed Work as set forth in Section 1.
+
+6.  Termination. This License shall terminate automatically if you fail to
+    comply with any of its terms and conditions.
+
+7.  Disclaimer of Warranty. THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT
+    WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+    WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+    LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE LICENSED WORK.
+
+8.  Limitation of Liability. IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+    OUT OF THE USE OF THE LICENSED WORK, EVEN IF ADVISED OF THE POSSIBILITY OF
+    SUCH DAMAGE.

package/README.md

@@ -1,12 +1,16 @@
 # OpenTTT
 
+> **Reference implementation of [draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/)**
+
 **OpenSSL for Transaction Ordering** -- TLS-grade Proof of Time for DeFi.
 
 OpenTTT brings cryptographic time verification to blockchain transaction ordering. Where TLS made HTTP trustworthy, OpenTTT makes transaction sequencing verifiable. No trust assumptions. No gentleman's agreements. Physics.
 
 [![npm](https://img.shields.io/npm/v/openttt)](https://www.npmjs.com/package/openttt)
 [![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-104%20passing%20%C2%B7%2018%20suites-brightgreen)]()
+[![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)]()
 
 ```
 npm install openttt
@@ -23,7 +27,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:
 
@@ -41,14 +45,14 @@ Three lines to start minting TimeTokens:
 ```typescript
 import { TTTClient } from "openttt";
 
-const ttt = await TTTClient.forBase({
-  signer: { type: "privateKey", envVar: "OPERATOR_PK" },
-});
+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).
+
 ---
 
 ## Progressive Disclosure
@@ -60,9 +64,7 @@ OpenTTT is designed around progressive disclosure. Start simple, add control as
 ```typescript
 import { TTTClient } from "openttt";
 
-const ttt = await TTTClient.forBase({
-  signer: { type: "privateKey", envVar: "OPERATOR_PK" },
-});
+const ttt = await TTTClient.forBase({ privateKey: process.env.OPERATOR_PK! });
 ttt.startAutoMint();
 ```
 
@@ -70,7 +72,7 @@ ttt.startAutoMint();
 
 ```typescript
 const ttt = await TTTClient.forSepolia({
-  signer: { type: "privateKey", key: process.env.OPERATOR_PK! },
+  privateKey: process.env.OPERATOR_PK!,
   rpcUrl: "https://my-rpc.example.com",
   tier: "T2_slot",
 });
@@ -93,7 +95,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,
 });
@@ -111,7 +113,7 @@ OpenTTT abstracts away signer complexity. Use a raw private key for development,
 |---|---|---|
 | `privateKey` | Development, small operators | `{ type: "privateKey", key: "0x..." }` or `{ type: "privateKey", envVar: "OPERATOR_PK" }` |
 | `turnkey` | Production, TEE-backed institutional custody | `{ type: "turnkey", apiBaseUrl, organizationId, privateKeyId, apiPublicKey, apiPrivateKey }` |
-| `privy` | Embedded wallets, consumer-facing apps | `{ type: "privy", appId, appSecret }` |
+| `privy` | Embedded wallets, consumer-facing apps (coming soon) | `{ type: "privy", appId, appSecret }` |
 | `kms` | Cloud HSM (AWS KMS or GCP Cloud KMS) | `{ type: "kms", provider: "aws"\|"gcp", keyId, ... }` |
 
 **AWS KMS** requires `@aws-sdk/client-kms`. **GCP KMS** requires `@google-cloud/kms`. Both are optional peer dependencies -- install only what you use.
@@ -262,7 +264,7 @@ 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
@@ -309,10 +311,10 @@ 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 100ms tolerance of the synthesized median, or the Proof of Time is rejected. Single-source operation triggers a degraded-confidence warning.
+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.
 
 ---
 

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;