openttt 0.1.2 → 0.2.0

package/dist/pool_registry.js

@@ -125,5 +125,42 @@ class PoolRegistry {
     listPools() {
         return Array.from(this.pools.keys());
     }
+    /**
+     * Serialize registry state to JSON for persistence across restarts.
+     * Allows operators to restore pool registrations and stats without re-registering.
+     */
+    serialize() {
+        const poolsArray = Array.from(this.pools.entries()).map(([address, stats]) => ({
+            address,
+            chainId: stats.chainId,
+            minted: stats.minted.toString(),
+            burned: stats.burned.toString(),
+        }));
+        const tokenMappings = Array.from(this.tokenToPool.entries()).map(([tokenId, poolAddr]) => ({
+            tokenId,
+            poolAddress: poolAddr,
+        }));
+        return JSON.stringify({ pools: poolsArray, tokenMappings });
+    }
+    /**
+     * Reconstruct a PoolRegistry from previously serialized JSON state.
+     */
+    static deserialize(json) {
+        const data = JSON.parse(json);
+        const instance = new PoolRegistry();
+        for (const p of data.pools) {
+            instance.pools.set(p.address, {
+                chainId: p.chainId,
+                minted: BigInt(p.minted),
+                burned: BigInt(p.burned),
+            });
+        }
+        if (data.tokenMappings) {
+            for (const t of data.tokenMappings) {
+                instance.tokenToPool.set(t.tokenId, t.poolAddress);
+            }
+        }
+        return instance;
+    }
 }
 exports.PoolRegistry = PoolRegistry;

package/dist/pot_signer.d.ts

@@ -25,5 +25,20 @@ export declare class PotSigner {
      * @param expectedPubKey - optional: reject if issuerPubKey doesn't match
      * @returns true if signature is valid
      */
+    /**
+     * Load a PotSigner from a PKCS8 DER hex file.
+     * @param path - path to file containing hex-encoded PKCS8 DER private key
+     */
+    static fromFile(path: string): PotSigner;
+    /**
+     * Load a PotSigner from file if it exists, otherwise generate a new one and save it.
+     * @param path - path to file for persistent key storage
+     */
+    static createOrLoad(path: string): PotSigner;
+    /**
+     * Save the private key (PKCS8 DER hex) to a file with mode 0o600.
+     * @param path - destination file path
+     */
+    saveToFile(path: string): void;
     static verifyPotSignature(potHash: string, potSig: PotSignature, expectedPubKey?: string): boolean;
 }

package/dist/pot_signer.js

@@ -4,6 +4,7 @@ exports.PotSigner = void 0;
 // sdk/src/pot_signer.ts — Ed25519 signing for Proof of Time (Non-repudiation)
 // Uses Node.js built-in crypto.sign/verify with Ed25519
 const crypto_1 = require("crypto");
+const fs_1 = require("fs");
 class PotSigner {
     privateKey;
     publicKey;
@@ -52,6 +53,33 @@ class PotSigner {
      * @param expectedPubKey - optional: reject if issuerPubKey doesn't match
      * @returns true if signature is valid
      */
+    /**
+     * Load a PotSigner from a PKCS8 DER hex file.
+     * @param path - path to file containing hex-encoded PKCS8 DER private key
+     */
+    static fromFile(path) {
+        const hex = (0, fs_1.readFileSync)(path, 'utf-8').trim();
+        return new PotSigner(hex);
+    }
+    /**
+     * Load a PotSigner from file if it exists, otherwise generate a new one and save it.
+     * @param path - path to file for persistent key storage
+     */
+    static createOrLoad(path) {
+        if ((0, fs_1.existsSync)(path)) {
+            return PotSigner.fromFile(path);
+        }
+        const signer = new PotSigner();
+        signer.saveToFile(path);
+        return signer;
+    }
+    /**
+     * Save the private key (PKCS8 DER hex) to a file with mode 0o600.
+     * @param path - destination file path
+     */
+    saveToFile(path) {
+        (0, fs_1.writeFileSync)(path, this.getPrivateKeyHex(), { mode: 0o600 });
+    }
     static verifyPotSignature(potHash, potSig, expectedPubKey) {
         if (expectedPubKey && potSig.issuerPubKey !== expectedPubKey)
             return false;

package/dist/protocol_fee.d.ts

@@ -1,20 +1,42 @@
 import { FeeCalculation } from "./dynamic_fee";
 import { EVMConnector } from "./evm_connector";
 /**
- * ProtocolFeeCollector - Helm 프로토콜 수수료 수취 및 검증 담당
- * x402 컴플라이언스를 위해 EIP-712 서명 검증을 포함
+ * Pluggable replay cache interface for signature deduplication.
+ * Implement this to use Redis, database, or other external stores.
+ */
+export interface ReplayCache {
+    has(key: string): Promise<boolean>;
+    set(key: string, ttlMs: number): Promise<void>;
+}
+/**
+ * Default in-memory replay cache with bounded size and TTL eviction.
+ * Suitable for single-process deployments; use a distributed ReplayCache
+ * implementation (e.g., Redis) for multi-node setups.
+ */
+export declare class InMemoryReplayCache implements ReplayCache {
+    private entries;
+    private readonly maxEntries;
+    private readonly defaultTtlMs;
+    private lastPruneTime;
+    private static readonly PRUNE_INTERVAL_MS;
+    constructor(maxEntries?: number, defaultTtlMs?: number);
+    has(key: string): Promise<boolean>;
+    set(key: string, ttlMs: number): Promise<void>;
+    private pruneIfNeeded;
+}
+/**
+ * ProtocolFeeCollector - Handles Helm protocol fee collection and verification.
+ * Includes EIP-712 signature verification for x402 compliance.
  */
 export declare class ProtocolFeeCollector {
     private totalCollected;
     private chainId;
     private verifyingContract;
-    private usedSignatures;
-    private readonly MAX_REPLAY_CACHE;
-    private readonly REPLAY_TTL_MS;
+    private replayCache;
     private evmConnector;
     private protocolFeeRecipient;
     private feeContract;
-    constructor(chainId: number, verifyingContract: string, evmConnector: EVMConnector, protocolFeeRecipient: string);
+    constructor(chainId: number, verifyingContract: string, evmConnector: EVMConnector, protocolFeeRecipient: string, replayCache?: ReplayCache);
     /**
      * R3-P0-2: Verify chainId matches the actual connected network.
      * Must be called after EVMConnector.connect() to prevent cross-chain signature replay.
@@ -22,35 +44,29 @@ export declare class ProtocolFeeCollector {
     validateChainId(): Promise<void>;
     private getFeeContract;
     /**
-     * 민팅 수수료 수취 (Stablecoin)
-     * @param feeCalc - DynamicFeeEngine에서 계산된 수수료 정보
-     * @param signature - EIP-712 서명 (필수, x402 검증용)
-     * @param user - 서명자 주소
-     * @param nonce - 중복 방지 nonce
-     * @param deadline - 서명 유효 기한
+     * Collect minting fee (Stablecoin).
+     * @param feeCalc - Fee calculation result from DynamicFeeEngine.
+     * @param signature - EIP-712 signature (required, for x402 verification).
+     * @param user - Signer address.
+     * @param nonce - Anti-replay nonce.
+     * @param deadline - Signature expiration timestamp.
      */
     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 - 서명 유효 기한
+     * Collect burn fee.
+     * @param feeCalc - Fee calculation result from DynamicFeeEngine.
+     * @param signature - EIP-712 signature (required).
+     * @param user - Signer address.
+     * @param nonce - Anti-replay nonce.
+     * @param deadline - Signature expiration timestamp.
      */
     collectBurnFee(feeCalc: FeeCalculation, signature: string, user: string, nonce: bigint, deadline: number): Promise<void>;
     /**
-     * 현재까지 수취한 총 수수료 반환
+     * Return total fees collected so far.
      */
     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)
+     * EIP-712 signature verification (x402 compliance).
      */
     private verifySignature;
 }

package/dist/protocol_fee.js

@@ -1,24 +1,74 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProtocolFeeCollector = void 0;
+exports.ProtocolFeeCollector = exports.InMemoryReplayCache = void 0;
 const ethers_1 = require("ethers");
 const logger_1 = require("./logger");
 /**
- * ProtocolFeeCollector - Helm 프로토콜 수수료 수취 및 검증 담당
- * x402 컴플라이언스를 위해 EIP-712 서명 검증을 포함
+ * Default in-memory replay cache with bounded size and TTL eviction.
+ * Suitable for single-process deployments; use a distributed ReplayCache
+ * implementation (e.g., Redis) for multi-node setups.
+ */
+class InMemoryReplayCache {
+    entries = new Map();
+    maxEntries;
+    defaultTtlMs;
+    lastPruneTime = 0;
+    static PRUNE_INTERVAL_MS = 60000;
+    constructor(maxEntries = 10000, defaultTtlMs = 3600000) {
+        this.maxEntries = maxEntries;
+        this.defaultTtlMs = defaultTtlMs;
+    }
+    async has(key) {
+        this.pruneIfNeeded();
+        const ts = this.entries.get(key);
+        if (ts === undefined)
+            return false;
+        if (Date.now() - ts > this.defaultTtlMs) {
+            this.entries.delete(key);
+            return false;
+        }
+        return true;
+    }
+    async set(key, ttlMs) {
+        this.pruneIfNeeded();
+        this.entries.set(key, Date.now());
+    }
+    pruneIfNeeded() {
+        const now = Date.now();
+        if (now - this.lastPruneTime < InMemoryReplayCache.PRUNE_INTERVAL_MS &&
+            this.entries.size <= this.maxEntries) {
+            return;
+        }
+        this.lastPruneTime = now;
+        for (const [sig, ts] of this.entries) {
+            if (now - ts > this.defaultTtlMs) {
+                this.entries.delete(sig);
+            }
+        }
+        // If still over limit, remove oldest entries
+        if (this.entries.size > this.maxEntries) {
+            const sorted = [...this.entries.entries()].sort((a, b) => a[1] - b[1]);
+            const toRemove = sorted.slice(0, sorted.length - this.maxEntries);
+            for (const [sig] of toRemove) {
+                this.entries.delete(sig);
+            }
+        }
+    }
+}
+exports.InMemoryReplayCache = InMemoryReplayCache;
+/**
+ * ProtocolFeeCollector - Handles Helm protocol fee collection and verification.
+ * Includes EIP-712 signature verification for x402 compliance.
  */
 class ProtocolFeeCollector {
     totalCollected = 0n;
     chainId;
     verifyingContract;
-    // P1-2 FIX: Bounded LRU replay cache (max 10K entries, 1h TTL) instead of unbounded Set
-    usedSignatures = new Map();
-    MAX_REPLAY_CACHE = 10000;
-    REPLAY_TTL_MS = 3600000; // 1 hour
+    replayCache;
     evmConnector;
     protocolFeeRecipient;
     feeContract = null;
-    constructor(chainId, verifyingContract, evmConnector, protocolFeeRecipient) {
+    constructor(chainId, verifyingContract, evmConnector, protocolFeeRecipient, replayCache) {
         // R3-P0-2: Validate chainId is a positive integer to prevent cross-chain replay
         if (!Number.isInteger(chainId) || chainId <= 0) {
             throw new Error(`[ProtocolFee] Invalid chainId: ${chainId}. Must be a positive integer.`);
@@ -27,6 +77,7 @@ class ProtocolFeeCollector {
         this.verifyingContract = ethers_1.ethers.getAddress(verifyingContract);
         this.evmConnector = evmConnector;
         this.protocolFeeRecipient = ethers_1.ethers.getAddress(protocolFeeRecipient);
+        this.replayCache = replayCache ?? new InMemoryReplayCache();
     }
     /**
      * R3-P0-2: Verify chainId matches the actual connected network.
@@ -50,12 +101,12 @@ class ProtocolFeeCollector {
         return this.feeContract;
     }
     /**
-     * 민팅 수수료 수취 (Stablecoin)
-     * @param feeCalc - DynamicFeeEngine에서 계산된 수수료 정보
-     * @param signature - EIP-712 서명 (필수, x402 검증용)
-     * @param user - 서명자 주소
-     * @param nonce - 중복 방지 nonce
-     * @param deadline - 서명 유효 기한
+     * Collect minting fee (Stablecoin).
+     * @param feeCalc - Fee calculation result from DynamicFeeEngine.
+     * @param signature - EIP-712 signature (required, for x402 verification).
+     * @param user - Signer address.
+     * @param nonce - Anti-replay nonce.
+     * @param deadline - Signature expiration timestamp.
      */
     async collectMintFee(feeCalc, signature, user, nonce, deadline) {
         try {
@@ -72,12 +123,12 @@ class ProtocolFeeCollector {
         }
     }
     /**
-     * 소각 수수료 수취
-     * @param feeCalc - DynamicFeeEngine에서 계산된 수수료 정보
-     * @param signature - EIP-712 서명 (필수)
-     * @param user - 서명자 주소
-     * @param nonce - 중복 방지 nonce
-     * @param deadline - 서명 유효 기한
+     * Collect burn fee.
+     * @param feeCalc - Fee calculation result from DynamicFeeEngine.
+     * @param signature - EIP-712 signature (required).
+     * @param user - Signer address.
+     * @param nonce - Anti-replay nonce.
+     * @param deadline - Signature expiration timestamp.
      */
     async collectBurnFee(feeCalc, signature, user, nonce, deadline) {
         try {
@@ -94,45 +145,17 @@ class ProtocolFeeCollector {
         }
     }
     /**
-     * 현재까지 수취한 총 수수료 반환
+     * Return total fees collected so far.
      */
     async getCollectedFees() {
         return this.totalCollected;
     }
     /**
-     * P1-2: Prune expired signatures from replay cache
-     */
-    lastPruneTime = 0;
-    static PRUNE_INTERVAL_MS = 60000; // R3-P1-5: Prune at most once per minute
-    pruneExpiredSignatures() {
-        const now = Date.now();
-        // R3-P1-5: Only prune periodically, not on every call — prevents O(n) DoS
-        if (now - this.lastPruneTime < ProtocolFeeCollector.PRUNE_INTERVAL_MS &&
-            this.usedSignatures.size <= this.MAX_REPLAY_CACHE) {
-            return;
-        }
-        this.lastPruneTime = now;
-        for (const [sig, ts] of this.usedSignatures) {
-            if (now - ts > this.REPLAY_TTL_MS) {
-                this.usedSignatures.delete(sig);
-            }
-        }
-        // If still over limit, remove oldest entries
-        if (this.usedSignatures.size > this.MAX_REPLAY_CACHE) {
-            const entries = [...this.usedSignatures.entries()].sort((a, b) => a[1] - b[1]);
-            const toRemove = entries.slice(0, entries.length - this.MAX_REPLAY_CACHE);
-            for (const [sig] of toRemove) {
-                this.usedSignatures.delete(sig);
-            }
-        }
-    }
-    /**
-     * EIP-712 서명 검증 (x402 compliance)
+     * EIP-712 signature verification (x402 compliance).
      */
     async verifySignature(feeCalc, signature, user, nonce, deadline) {
-        // B1-2 + P1-2: Bounded replay protection with TTL
-        this.pruneExpiredSignatures();
-        if (this.usedSignatures.has(signature)) {
+        // B1-2 + P1-2: Replay protection via pluggable cache
+        if (await this.replayCache.has(signature)) {
             throw new Error("Signature already used (replay protection)");
         }
         // B1-2: Deadline check
@@ -142,7 +165,7 @@ class ProtocolFeeCollector {
         }
         const normalizedUser = ethers_1.ethers.getAddress(user);
         const domain = {
-            name: "Helm Protocol",
+            name: "OpenTTT_ProtocolFee",
             version: "1",
             chainId: this.chainId,
             verifyingContract: this.verifyingContract
@@ -166,7 +189,7 @@ class ProtocolFeeCollector {
             if (ethers_1.ethers.getAddress(recoveredAddress) !== normalizedUser) {
                 throw new Error("Invalid EIP-712 signature: signer mismatch");
             }
-            this.usedSignatures.set(signature, Date.now()); // Mark as used with timestamp
+            await this.replayCache.set(signature, 3600000); // Mark as used with 1h TTL
         }
         catch (error) {
             throw new Error(`[ProtocolFee] Signature verification failed: ${(error instanceof Error ? error.message : String(error))}`);

package/dist/revenue_tiers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Revenue Tier Configuration
+ * Reflects the TTT Labs pricing strategy: Free/Sponsor-backed T0 up to Institutional T3.
+ */
+export declare enum RevenueTier {
+    T0_EPOCH = "T0_EPOCH",
+    T1_BLOCK = "T1_BLOCK",
+    T2_SLOT = "T2_SLOT",
+    T3_MICRO = "T3_MICRO"
+}
+export interface TierConfig {
+    tier: RevenueTier;
+    name: string;
+    interval: string;
+    pricePerTick: number;
+    currency: string;
+    model: string;
+    target: string;
+    sponsorEligible: boolean;
+}
+export interface SponsorConfig {
+    sponsor: string;
+    tier: RevenueTier;
+    monthlyBudgetUsd: number;
+    startDate: string;
+    endDate: string;
+}
+export declare const REVENUE_TIERS: Record<RevenueTier, TierConfig>;
+/**
+ * Calculate projected monthly cost based on tier and throughput.
+ */
+export declare function calculateMonthlyCost(tier: RevenueTier, ticksPerDay: number): number;
+/**
+ * Determine the appropriate tier based on a usage description.
+ */
+export declare function getTierForUseCase(useCase: string): RevenueTier;

package/dist/revenue_tiers.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Revenue Tier Configuration
+ * Reflects the TTT Labs pricing strategy: Free/Sponsor-backed T0 up to Institutional T3.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVENUE_TIERS = exports.RevenueTier = void 0;
+exports.calculateMonthlyCost = calculateMonthlyCost;
+exports.getTierForUseCase = getTierForUseCase;
+var RevenueTier;
+(function (RevenueTier) {
+    RevenueTier["T0_EPOCH"] = "T0_EPOCH";
+    RevenueTier["T1_BLOCK"] = "T1_BLOCK";
+    RevenueTier["T2_SLOT"] = "T2_SLOT";
+    RevenueTier["T3_MICRO"] = "T3_MICRO";
+})(RevenueTier || (exports.RevenueTier = RevenueTier = {}));
+exports.REVENUE_TIERS = {
+    [RevenueTier.T0_EPOCH]: {
+        tier: RevenueTier.T0_EPOCH,
+        name: "Standard Epoch",
+        interval: "6.4 min",
+        pricePerTick: 0,
+        currency: "USDC",
+        model: "sponsor", // Let's Encrypt model: free to user, sponsor-backed
+        target: "Standard L1 Swaps / LP Integration",
+        sponsorEligible: true
+    },
+    [RevenueTier.T1_BLOCK]: {
+        tier: RevenueTier.T1_BLOCK,
+        name: "Fast Block",
+        interval: "2 sec",
+        pricePerTick: 0.01,
+        currency: "USDC",
+        model: "sdk_license",
+        target: "L2 Sequencer / Standard DeFi",
+        sponsorEligible: false
+    },
+    [RevenueTier.T2_SLOT]: {
+        tier: RevenueTier.T2_SLOT,
+        name: "High-Frequency Slot",
+        interval: "12 sec",
+        pricePerTick: 0.05,
+        currency: "USDC",
+        model: "sdk_license",
+        target: "Active Traders / Arbitrage",
+        sponsorEligible: false
+    },
+    [RevenueTier.T3_MICRO]: {
+        tier: RevenueTier.T3_MICRO,
+        name: "Institutional Micro-Tick",
+        interval: "100 ms",
+        pricePerTick: 0.10,
+        currency: "USDC",
+        model: "enterprise",
+        target: "Institutional / HFT Pipelines",
+        sponsorEligible: false
+    }
+};
+/**
+ * Calculate projected monthly cost based on tier and throughput.
+ */
+function calculateMonthlyCost(tier, ticksPerDay) {
+    const config = exports.REVENUE_TIERS[tier];
+    if (config.pricePerTick === 0)
+        return 0;
+    return config.pricePerTick * ticksPerDay * 30;
+}
+/**
+ * Determine the appropriate tier based on a usage description.
+ */
+function getTierForUseCase(useCase) {
+    const lowerCase = useCase.toLowerCase();
+    if (lowerCase.includes("institutional") || lowerCase.includes("hft") || lowerCase.includes("micro")) {
+        return RevenueTier.T3_MICRO;
+    }
+    if (lowerCase.includes("arbitrage") || lowerCase.includes("trader") || lowerCase.includes("slot")) {
+        return RevenueTier.T2_SLOT;
+    }
+    if (lowerCase.includes("l2") || lowerCase.includes("block") || lowerCase.includes("sequencer")) {
+        return RevenueTier.T1_BLOCK;
+    }
+    return RevenueTier.T0_EPOCH;
+}

package/dist/signer.d.ts

@@ -1,5 +1,4 @@
 import { Signer, Wallet } from "ethers";
-import { TurnkeySigner } from "@turnkey/ethers";
 /**
  * Supported signer types in TTT SDK
  */
@@ -56,7 +55,7 @@ export declare class PrivateKeySigner extends TTTAbstractSigner {
  * TEE-based institution-grade signer (Turnkey)
  */
 export declare class TurnkeySignerWrapper extends TTTAbstractSigner {
-    constructor(signer: TurnkeySigner);
+    constructor(signer: Signer);
 }
 /**
  * Social/Embedded wallet signer (Privy)