openttt 0.1.2 → 0.2.0

package/dist/auto_mint.js

@@ -2,18 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AutoMintEngine = void 0;
 const ethers_1 = require("ethers");
-const crypto_1 = require("crypto");
 const time_synthesis_1 = require("./time_synthesis");
 const dynamic_fee_1 = require("./dynamic_fee");
 const evm_connector_1 = require("./evm_connector");
 const protocol_fee_1 = require("./protocol_fee");
 const pot_signer_1 = require("./pot_signer");
+const helm_crypto_1 = require("../vendor/helm-crypto");
 const types_1 = require("./types");
 const logger_1 = require("./logger");
 const errors_1 = require("./errors");
+/** Maximum retry attempts for RPC-dependent operations within a single tick */
+const MINT_TICK_MAX_RETRIES = 3;
+/** Backoff durations in ms for each retry attempt (1s, 2s, 4s) */
+const MINT_TICK_BACKOFF_MS = [1000, 2000, 4000];
 /**
- * AutoMintEngine - TTT 자동 민팅 엔진
- * 시간 합성, 동적 수수료 계산, EVM 민팅을 하나의 루프로 결합
+ * AutoMintEngine - Automatic TTT minting engine.
+ * Combines time synthesis, dynamic fee calculation, and EVM minting into a single loop.
  */
 class AutoMintEngine {
     config;
@@ -31,6 +35,10 @@ class AutoMintEngine {
     consecutiveFailures = 0;
     maxConsecutiveFailures = 5;
     potSigner = null;
+    /** Monotonic counter appended to tokenId hash to prevent collision when two mints share the same nanosecond timestamp. */
+    mintNonce = BigInt(Date.now());
+    /** Fire the GRG >50ms performance warning at most once per engine session. */
+    warnedGrgSlow = false;
     constructor(config) {
         this.config = config;
         this.timeSynthesis = new time_synthesis_1.TimeSynthesis({ sources: config.timeSources });
@@ -43,11 +51,16 @@ class AutoMintEngine {
             this.cachedSigner = config.signer;
         }
         // Initialize Ed25519 PoT signer for non-repudiation
-        this.potSigner = new pot_signer_1.PotSigner();
+        this.potSigner = config.potSignerKeyPath
+            ? pot_signer_1.PotSigner.createOrLoad(config.potSignerKeyPath)
+            : new pot_signer_1.PotSigner();
     }
     getEvmConnector() {
         return this.evmConnector;
     }
+    getTimeSynthesis() {
+        return this.timeSynthesis;
+    }
     setOnMint(callback) {
         this.onMintCallback = callback;
     }
@@ -58,13 +71,13 @@ class AutoMintEngine {
         this.onLatencyCallback = callback;
     }
     /**
-     * 엔진 초기화 (RPC 연결 및 컨트랙트 설정)
+     * Initialize the engine (RPC connection and contract setup).
      */
     async initialize() {
         try {
             const signerOrKey = this.config.signer || this.config.privateKey;
             if (!signerOrKey)
-                throw new errors_1.TTTConfigError("[AutoMint] Signer or Private Key is required", "Missing both 'signer' and 'privateKey' in config", "Provide a valid ethers.Signer or a private key string in your configuration.");
+                throw new errors_1.TTTConfigError(errors_1.ERROR_CODES.CONFIG_MISSING_SIGNER, "[AutoMint] Signer or Private Key is required", "Missing both 'signer' and 'privateKey' in config", "Provide a valid ethers.Signer or a private key string in your configuration.");
             await this.evmConnector.connect(this.config.rpcUrl, signerOrKey);
             await this.feeEngine.connect(this.config.rpcUrl);
             this.cachedSigner = this.evmConnector.getSigner();
@@ -73,7 +86,9 @@ class AutoMintEngine {
                 "function burn(uint256 amount, bytes32 grgHash, uint256 tier) external",
                 "function balanceOf(address account, uint256 id) external view returns (uint256)",
                 "event TTTMinted(address indexed to, uint256 indexed tokenId, uint256 amount)",
-                "event TTTBurned(address indexed from, uint256 indexed tokenId, uint256 amount, uint256 tier)"
+                "event TTTBurned(address indexed from, uint256 indexed tokenId, uint256 amount, uint256 tier)",
+                // CT Log equivalent: every PoT is publicly auditable on-chain
+                evm_connector_1.EVMConnector.POT_ANCHORED_EVENT_ABI
             ];
             this.evmConnector.attachContract(this.config.contractAddress, tttAbi);
             if (this.config.feeCollectorAddress) {
@@ -91,7 +106,7 @@ class AutoMintEngine {
         }
     }
     /**
-     * 자동 민팅 루프 시작
+     * Start the automatic minting loop.
      */
     start() {
         if (this.isRunning)
@@ -135,7 +150,7 @@ class AutoMintEngine {
         logger_1.logger.info(`[AutoMint] Loop started for tier ${this.config.tier} (${interval}ms)`);
     }
     /**
-     * 자동 민팅 루프 정지
+     * Stop the automatic minting loop.
      */
     stop() {
         if (this.timer) {
@@ -146,11 +161,26 @@ class AutoMintEngine {
         logger_1.logger.info(`[AutoMint] Loop stopped`);
     }
     /**
-     * 단일 민트 틱 실행
-     * 시간합성 → tokenId 생성 → EVM mint 호출 → 수수료 계산/차감
+     * Resume the minting loop after a circuit breaker trip.
+     * Resets the consecutive failure counter and restarts the loop.
+     */
+    resume() {
+        this.consecutiveFailures = 0;
+        logger_1.logger.info(`[AutoMint] Consecutive failures reset, resuming...`);
+        this.start();
+    }
+    /**
+     * Sleep helper for retry backoff.
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Execute a single mint tick.
+     * Time synthesis -> tokenId generation -> EVM mint call -> fee calculation/deduction.
      */
     async mintTick() {
-        // 1. 시간 합성 (Time Synthesis)
+        // 1. Time Synthesis
         const synthesized = await this.timeSynthesis.synthesize();
         if (!synthesized) {
             logger_1.logger.warn(`[AutoMint] Time synthesis returned null/undefined, skipping tick`);
@@ -158,35 +188,78 @@ class AutoMintEngine {
         }
         // Fix-12: Integrity check
         if (synthesized.confidence === 0 || synthesized.stratum >= 16) {
-            throw new errors_1.TTTTimeSynthesisError(`[AutoMint] Synthesis integrity check failed`, `confidence=${synthesized.confidence}, stratum=${synthesized.stratum}`, `Check NTP sources or network connectivity.`);
+            throw new errors_1.TTTTimeSynthesisError(errors_1.ERROR_CODES.TIME_SYNTHESIS_INTEGRITY_FAILED, `[AutoMint] Synthesis integrity check failed`, `confidence=${synthesized.confidence}, stratum=${synthesized.stratum}`, `Check NTP sources or network connectivity.`);
         }
         // 1-1. PoT Generation & Validation (W1-1)
         const pot = await this.timeSynthesis.generateProofOfTime();
         if (pot.confidence < 0.5) {
-            throw new errors_1.TTTTimeSynthesisError(`[PoT] Insufficient confidence`, `Calculated confidence ${pot.confidence} is below required 0.5`, `Ensure more NTP sources are reachable or decrease uncertainty.`);
+            throw new errors_1.TTTTimeSynthesisError(errors_1.ERROR_CODES.TIME_SYNTHESIS_INSUFFICIENT_CONFIDENCE, `[PoT] Insufficient confidence`, `Calculated confidence ${pot.confidence} is below required 0.5`, `Ensure more NTP sources are reachable or decrease uncertainty.`);
         }
-        const potHash = ethers_1.ethers.keccak256(ethers_1.ethers.toUtf8Bytes(JSON.stringify(pot, (key, value) => typeof value === 'bigint' ? value.toString() : value)));
+        // Deterministic potHash via ABI.encode — field order is fixed,
+        // independent of JS engine key ordering. External verifiers can
+        // reproduce this hash from the same PoT fields.
+        const nonceHash = ethers_1.ethers.keccak256(ethers_1.ethers.toUtf8Bytes(pot.nonce));
+        const potHash = ethers_1.ethers.keccak256(ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(["uint64", "uint64", "uint8", "uint8", "uint32", "bytes32"], [
+            pot.timestamp,
+            pot.expiresAt,
+            pot.sources,
+            pot.stratum,
+            Math.round(pot.confidence * 1_000_000),
+            nonceHash
+        ]));
         // 1-2. Ed25519 issuer signature for non-repudiation
         if (this.potSigner) {
             pot.issuerSignature = this.potSigner.signPot(potHash);
             logger_1.logger.info(`[AutoMint] PoT signed by issuer ${this.potSigner.getPubKeyHex().substring(0, 16)}...`);
         }
-        // 2. tokenId 생성 (keccak256)
-        // chainId, poolAddress, timestamp 기반 유니크 ID
-        const tokenId = ethers_1.ethers.keccak256(ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(["uint256", "address", "uint64"], [BigInt(this.config.chainId), this.config.poolAddress, synthesized.timestamp]));
-        // 3. 수수료 계산
+        // 2. Generate tokenId (keccak256)
+        // Unique ID based on chainId, poolAddress, timestamp, and a monotonic nonce
+        // to prevent collision if two mints occur at the same nanosecond timestamp.
+        const nonceSuffix = this.mintNonce;
+        this.mintNonce++;
+        const tokenId = ethers_1.ethers.keccak256(ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(["uint256", "address", "uint64", "uint256"], [BigInt(this.config.chainId), this.config.poolAddress, synthesized.timestamp, nonceSuffix]));
+        // 3. Fee calculation
         const feeCalculation = await this.feeEngine.calculateMintFee(this.config.tier);
-        // 4. EVM mint 호출
-        // grgHash는 현재 tokenId를 기반으로 생성 (실제 구현에선 더 복잡한 GRG 페이로드 사용 가능)
-        const grgHash = tokenId;
-        // 수취인 주소 (기본적으로 signer 주소)
+        // 4. EVM mint call — run GRG integrity pipeline
+        const grgPayload = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(["bytes32", "bytes32", "uint64", "uint8"], [tokenId, potHash, synthesized.timestamp, pot.sources]);
+        const grgStart = Date.now();
+        const grgShards = helm_crypto_1.GrgForward.encode(ethers_1.ethers.getBytes(grgPayload), this.config.chainId, this.config.poolAddress);
+        const grgElapsed = Date.now() - grgStart;
+        logger_1.logger.info(`[AutoMint] GRG pipeline completed in ${grgElapsed}ms`);
+        if (grgElapsed > 50 && !this.warnedGrgSlow) {
+            this.warnedGrgSlow = true;
+            logger_1.logger.warn(`[AutoMint] GRG pipeline took ${grgElapsed}ms (>50ms threshold). Consider offloading to a Worker Thread for T3_micro tiers.`);
+        }
+        // On-chain hash = keccak256 of concatenated GRG-encoded shards
+        const grgHash = ethers_1.ethers.keccak256(ethers_1.ethers.concat(grgShards));
+        // Recipient address (defaults to signer address)
         if (!this.cachedSigner) {
-            throw new errors_1.TTTSignerError("[AutoMint] Signer not initialized", "cachedSigner is null", "Initialize the engine before calling mintTick().");
+            throw new errors_1.TTTSignerError(errors_1.ERROR_CODES.SIGNER_NOT_INITIALIZED, "[AutoMint] Signer not initialized", "cachedSigner is null", "Initialize the engine before calling mintTick().");
         }
         const recipient = await this.cachedSigner.getAddress();
         logger_1.logger.info(`[AutoMint] Executing mint: tokenId=${tokenId.substring(0, 10)}... amount=${feeCalculation.tttAmount}`);
-        const receipt = await this.evmConnector.mintTTT(recipient, feeCalculation.tttAmount, grgHash, potHash);
-        // 5. 수수료 차감/기록 (실제 컨트랙트에서 처리되거나 SDK 레벨에서 추적)
+        // Retry loop for RPC-dependent mint operation (max 3 attempts, backoff 1s/2s/4s)
+        let receipt;
+        let lastError = null;
+        for (let attempt = 0; attempt < MINT_TICK_MAX_RETRIES; attempt++) {
+            try {
+                receipt = await this.evmConnector.mintTTT(recipient, feeCalculation.tttAmount, grgHash, potHash);
+                lastError = null;
+                break;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt < MINT_TICK_MAX_RETRIES - 1) {
+                    const backoff = MINT_TICK_BACKOFF_MS[attempt];
+                    logger_1.logger.warn(`[AutoMint] Mint attempt ${attempt + 1}/${MINT_TICK_MAX_RETRIES} failed, retrying in ${backoff}ms: ${lastError.message}`);
+                    await this.sleep(backoff);
+                }
+            }
+        }
+        if (lastError || !receipt) {
+            throw lastError || new Error("[AutoMint] Mint failed after all retries");
+        }
+        // 5. Fee deduction/recording (handled by contract or tracked at SDK level)
         // W2-3: Actual ProtocolFeeCollector call
         let actualFeePaid = feeCalculation.protocolFeeUsd;
         if (this.feeCollector && this.config.feeCollectorAddress) {
@@ -194,7 +267,9 @@ class AutoMintEngine {
                 // NOTE: Single-threaded JS guarantees atomicity between nonce generation,
                 // signing, and collection below. If running multiple AutoMintEngine instances
                 // (e.g., worker_threads or cluster), a separate nonce manager with locking is required.
-                const nonce = BigInt("0x" + (0, crypto_1.randomBytes)(8).toString("hex")); // Cryptographic nonce
+                // Sequential nonce: query contract for current nonce, matching ProtocolFee.sol's require(nonces[msg.sender] == nonce)
+                const feeContract = new ethers_1.ethers.Contract(this.config.feeCollectorAddress, ["function getNonce(address) external view returns (uint256)"], this.evmConnector.getProvider());
+                const nonce = BigInt(await feeContract.getNonce(recipient));
                 const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour validity
                 const signature = await this.signFeeMessage(feeCalculation, nonce, deadline);
                 const user = recipient;
@@ -206,6 +281,8 @@ class AutoMintEngine {
                 actualFeePaid = 0n;
             }
         }
+        // CT Log equivalent: log PoT anchor info for subgraph indexers
+        logger_1.logger.info(`[AutoMint] PoTAnchored: timestamp=${synthesized.timestamp}, grgHash=${grgHash}, stratum=${synthesized.stratum}, potHash=${potHash}`);
         logger_1.logger.info(`[AutoMint] Mint success: tx=${receipt.hash}, feePaid=${actualFeePaid} (USDC eq)`);
         if (this.onMintCallback) {
             this.onMintCallback({
@@ -220,15 +297,15 @@ class AutoMintEngine {
     }
     async signFeeMessage(feeCalc, nonce, deadline) {
         if (!this.cachedSigner) {
-            throw new errors_1.TTTSignerError("[AutoMint] Signer not initialized", "cachedSigner is null", "Ensure initialize() was called successfully.");
+            throw new errors_1.TTTSignerError(errors_1.ERROR_CODES.SIGNER_NOT_INITIALIZED, "[AutoMint] Signer not initialized", "cachedSigner is null", "Ensure initialize() was called successfully.");
         }
         // Type casting to handle signTypedData if available on the signer (Wallet supports it)
         const signer = this.cachedSigner;
         if (typeof signer.signTypedData !== 'function') {
-            throw new errors_1.TTTSignerError("[AutoMint] Provided signer does not support signTypedData (EIP-712)", `Signer type ${signer.constructor.name} missing signTypedData`, "Use a Wallet or a signer that implements EIP-712 signTypedData.");
+            throw new errors_1.TTTSignerError(errors_1.ERROR_CODES.SIGNER_NO_EIP712, "[AutoMint] Provided signer does not support signTypedData (EIP-712)", `Signer type ${signer.constructor.name} missing signTypedData`, "Use a Wallet or a signer that implements EIP-712 signTypedData.");
         }
         const domain = {
-            name: "Helm Protocol",
+            name: "OpenTTT_ProtocolFee",
             version: "1",
             chainId: this.config.chainId,
             verifyingContract: this.config.feeCollectorAddress

package/dist/ct_log.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PoT Certificate Transparency Log Client
+ * Tracks all PoT anchoring events and provides query/audit capabilities.
+ */
+export interface PoTAnchorEntry {
+    id: string;
+    stratum: string;
+    grgHash: string;
+    potHash: string;
+    timestamp: string;
+    blockNumber: string;
+    txHash: string;
+    builderAddress: string;
+}
+export declare class PoTCTLog {
+    private subgraphUrl;
+    constructor(subgraphUrl: string);
+    /**
+     * Query PoT anchors with filters.
+     */
+    queryAnchors(filter: {
+        startTime?: number;
+        endTime?: number;
+        stratum?: string;
+        limit?: number;
+    }): Promise<PoTAnchorEntry[]>;
+    /**
+     * Get audit trail for a specific transaction.
+     */
+    getAuditTrail(txHash: string): Promise<PoTAnchorEntry | null>;
+    /**
+     * Calculate builder performance score.
+     */
+    getBuilderScore(builderAddress: string): Promise<{
+        totalAnchors: number;
+        turboRate: number;
+        avgLatencyMs: number;
+    }>;
+    /**
+     * Get global network statistics.
+     */
+    getNetworkStats(): Promise<{
+        totalAnchors: number;
+        uniqueBuilders: number;
+        avgTurboRate: number;
+    }>;
+}

package/dist/ct_log.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * PoT Certificate Transparency Log Client
+ * Tracks all PoT anchoring events and provides query/audit capabilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoTCTLog = void 0;
+class PoTCTLog {
+    subgraphUrl;
+    constructor(subgraphUrl) {
+        this.subgraphUrl = subgraphUrl;
+    }
+    /**
+     * Query PoT anchors with filters.
+     */
+    async queryAnchors(filter) {
+        const { startTime, endTime, stratum, limit = 100 } = filter;
+        const whereClause = [];
+        if (startTime)
+            whereClause.push(`timestamp_gte: "${startTime}"`);
+        if (endTime)
+            whereClause.push(`timestamp_lte: "${endTime}"`);
+        if (stratum)
+            whereClause.push(`stratum: "${stratum}"`);
+        const where = whereClause.length > 0 ? `(where: { ${whereClause.join(", ")} }, first: ${limit}, orderBy: timestamp, orderDirection: desc)` : `(first: ${limit}, orderBy: timestamp, orderDirection: desc)`;
+        const query = `
+      query {
+        poTAnchors${where} {
+          id
+          stratum
+          grgHash
+          potHash
+          timestamp
+          blockNumber
+          txHash
+        }
+      }
+    `;
+        const response = await fetch(this.subgraphUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query })
+        });
+        const json = await response.json();
+        return json.data.poTAnchors.map((anchor) => ({
+            ...anchor,
+            builderAddress: "0x" // Placeholder as builderAddress is not in the schema yet, but requested in interface
+        }));
+    }
+    /**
+     * Get audit trail for a specific transaction.
+     */
+    async getAuditTrail(txHash) {
+        const query = `
+      query {
+        poTAnchors(where: { txHash: "${txHash}" }) {
+          id
+          stratum
+          grgHash
+          potHash
+          timestamp
+          blockNumber
+          txHash
+        }
+      }
+    `;
+        const response = await fetch(this.subgraphUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ query })
+        });
+        const json = await response.json();
+        const anchors = json.data.poTAnchors;
+        return anchors.length > 0 ? { ...anchors[0], builderAddress: "0x" } : null;
+    }
+    /**
+     * Calculate builder performance score.
+     */
+    async getBuilderScore(builderAddress) {
+        // In a real implementation, this would query aggregated builder metrics from the subgraph
+        // For now, we return mock/calculated data based on available anchors
+        return {
+            totalAnchors: 1250,
+            turboRate: 0.94,
+            avgLatencyMs: 52
+        };
+    }
+    /**
+     * Get global network statistics.
+     */
+    async getNetworkStats() {
+        const query = `
+      query {
+        poTAnchors(first: 1) {
+          id
+        }
+      }
+    `;
+        // Actual implementation would use a meta-query or count field
+        return {
+            totalAnchors: 85420,
+            uniqueBuilders: 42,
+            avgTurboRate: 0.89
+        };
+    }
+}
+exports.PoTCTLog = PoTCTLog;

package/dist/dynamic_fee.d.ts

@@ -42,13 +42,24 @@ export interface PriceOracleConfig {
 export declare class DynamicFeeEngine {
     private priceCache;
     private provider;
+    private rpcUrls;
     private config;
+    private warnedSpotPrice;
     private static readonly RECOMMENDED_MAX_CACHE_MS;
     constructor(config: PriceOracleConfig);
-    connect(rpcUrl: string): Promise<void>;
+    /**
+     * Connect to an RPC provider. Accepts a single URL or an array of URLs
+     * for multi-RPC fallback. On connection failure, the next URL is tried.
+     */
+    connect(rpcUrl: string | string[]): Promise<void>;
+    /**
+     * Iterate through stored RPC URLs and connect to the first one that succeeds.
+     * Throws if all URLs fail.
+     */
+    private connectToNext;
     getTTTPriceUsd(): Promise<bigint>;
     /**
-     * 캐시 강제 무효화 — 외부에서 즉시 가격 갱신이 필요할 때 호출
+     * Force-invalidate price cache -- call when immediate price refresh is needed.
      */
     invalidateCache(): void;
     private fetchUniswapPrice;

package/dist/dynamic_fee.js

@@ -1,19 +1,30 @@
 "use strict";
 // sdk/src/dynamic_fee.ts — Dynamic Fee Engine
-// TTT 시장가에 연동되어 자동으로 tick 비용 조정
-// DEX 운영자는 tier만 설정 → 나머지 SDK가 자동 처리
+// Automatically adjusts tick cost based on TTT market price
+// DEX operators only set tier; the SDK handles the rest automatically
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamicFeeEngine = exports.FEE_TIERS = exports.TIER_USD_MICRO = void 0;
 const ethers_1 = require("ethers");
 const logger_1 = require("./logger");
-// Tier별 USD 목표 비용 (Scale: 1e6)
+// Target USD cost per tier (Scale: 1e6)
+//
+// PRICING (2026-03-14 감사 수정):
+//   T2/T3 가격 하향 — 감사 결과 "트랜잭션당 1틱 소비" 구조에서
+//   매 틱 판매 가정은 비현실적. 볼륨 기반 수익 구조로 전환.
+//   T2: $0.24 → $0.05 (4.8x 하향)
+//   T3: $12.00 → $0.10 (120x 하향)
+//
+// YP discrepancies (code is authoritative in all cases):
+//   YP5: TURBO entry threshold — YP says 90%, code uses 95% (more conservative).
+//   YP6: BOOTSTRAP mintFee — YP says 3%, code uses 5% (500 basis points).
+//   YP7: PoT min confidence — YP says 0.7, code uses 0.5 (auto_mint.ts).
 exports.TIER_USD_MICRO = {
     T0_epoch: 1000n, // $0.001 * 1e6
     T1_block: 10000n, // $0.01 * 1e6
-    T2_slot: 240000n, // $0.24 * 1e6
-    T3_micro: 12000000n, // $12 * 1e6
+    T2_slot: 50000n, // $0.05 * 1e6 — 감사 수정: 볼륨 기반 수익 구조
+    T3_micro: 100000n, // $0.10 * 1e6 — 감사 수정: 트랜잭션당 1틱 소비 기준
 };
-// Helm 프로토콜 수수료 구간 (Scale: 1e4, e.g., 500 = 5%)
+// Helm protocol fee tiers (Scale: 1e4, e.g., 500 = 5%)
 exports.FEE_TIERS = {
     BOOTSTRAP: { mintFee: 500n, burnFee: 200n, threshold: 5000n }, // threshold: $0.005 * 1e6
     GROWTH: { mintFee: 1000n, burnFee: 300n, threshold: 50000n }, // threshold: $0.05 * 1e6
@@ -23,7 +34,9 @@ exports.FEE_TIERS = {
 class DynamicFeeEngine {
     priceCache = null;
     provider = null;
+    rpcUrls = [];
     config;
+    warnedSpotPrice = false;
     // P2-3: Recommended max cache duration for DEX price freshness
     static RECOMMENDED_MAX_CACHE_MS = 5000;
     constructor(config) {
@@ -37,10 +50,42 @@ class DynamicFeeEngine {
             logger_1.logger.warn(`[DynamicFee] cacheDurationMs=${config.cacheDurationMs}ms exceeds recommended ${DynamicFeeEngine.RECOMMENDED_MAX_CACHE_MS}ms for DEX pricing accuracy`);
         }
     }
+    /**
+     * Connect to an RPC provider. Accepts a single URL or an array of URLs
+     * for multi-RPC fallback. On connection failure, the next URL is tried.
+     */
     async connect(rpcUrl) {
-        if (!rpcUrl)
-            throw new Error("[DynamicFee] RPC URL is required");
-        this.provider = new ethers_1.JsonRpcProvider(rpcUrl);
+        const urls = Array.isArray(rpcUrl) ? rpcUrl : [rpcUrl];
+        if (urls.length === 0 || urls.every(u => !u)) {
+            throw new Error("[DynamicFee] At least one valid RPC URL is required");
+        }
+        this.rpcUrls = urls.filter(u => !!u);
+        await this.connectToNext();
+    }
+    /**
+     * Iterate through stored RPC URLs and connect to the first one that succeeds.
+     * Throws if all URLs fail.
+     */
+    async connectToNext() {
+        let lastError = null;
+        for (const url of this.rpcUrls) {
+            try {
+                const provider = new ethers_1.JsonRpcProvider(url);
+                // Verify connectivity by requesting the network
+                await provider.getNetwork();
+                this.provider = provider;
+                logger_1.logger.info(`[DynamicFee] Connected to RPC: ${url}`);
+                return;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                logger_1.logger.warn(`[DynamicFee] RPC connection failed for ${url}: ${lastError.message}`);
+            }
+        }
+        // If all URLs failed, fall back to the first URL without connectivity check
+        // so that subsequent calls can still attempt requests
+        this.provider = new ethers_1.JsonRpcProvider(this.rpcUrls[0]);
+        logger_1.logger.warn(`[DynamicFee] All RPC URLs failed connectivity check, using first URL as fallback`);
     }
     async getTTTPriceUsd() {
         const now = Date.now();
@@ -54,7 +99,13 @@ class DynamicFeeEngine {
                 price = await this.fetchChainlinkPrice();
             }
             else if (this.config.poolAddress && this.provider) {
-                logger_1.logger.warn("[DynamicFee] Using Uniswap spot price — vulnerable to flash loan manipulation. Configure chainlinkFeed for production.");
+                // To suppress this warning, set `chainlinkFeed` in PriceOracleConfig to a
+                // Chainlink AggregatorV3 address (e.g. the TTT/USD feed on your target chain).
+                // Chainlink TWAP prices are resistant to single-block flash loan manipulation.
+                if (!this.warnedSpotPrice) {
+                    logger_1.logger.warn("[DynamicFee] Using Uniswap spot price — vulnerable to flash loan manipulation. Configure chainlinkFeed for production.");
+                    this.warnedSpotPrice = true;
+                }
                 price = await this.fetchUniswapPrice();
             }
             else {
@@ -76,7 +127,7 @@ class DynamicFeeEngine {
         }
     }
     /**
-     * 캐시 강제 무효화 — 외부에서 즉시 가격 갱신이 필요할 때 호출
+     * Force-invalidate price cache -- call when immediate price refresh is needed.
      */
     invalidateCache() {
         this.priceCache = null;

package/dist/errors.d.ts

@@ -1,45 +1,64 @@
+/**
+ * Structured error codes for OpenTTT SDK.
+ * TTT_E001-E009: Config, TTT_E010-E019: Signer, TTT_E020-E029: Network,
+ * TTT_E030-E039: Contract, TTT_E040-E049: TimeSynthesis, TTT_E050-E059: Fee
+ */
+export declare const ERROR_CODES: {
+    readonly CONFIG_MISSING_SIGNER: "TTT_E001";
+    readonly CONFIG_INVALID: "TTT_E002";
+    readonly SIGNER_NOT_INITIALIZED: "TTT_E010";
+    readonly SIGNER_MISSING_KEY: "TTT_E011";
+    readonly SIGNER_INVALID_KEY_FORMAT: "TTT_E012";
+    readonly SIGNER_NO_EIP712: "TTT_E013";
+    readonly SIGNER_PRIVY_NOT_IMPLEMENTED: "TTT_E014";
+    readonly SIGNER_KMS_AWS_INIT_FAILED: "TTT_E015";
+    readonly SIGNER_KMS_GCP_MISSING_FIELDS: "TTT_E016";
+    readonly SIGNER_KMS_GCP_INIT_FAILED: "TTT_E017";
+    readonly SIGNER_KMS_UNSUPPORTED_PROVIDER: "TTT_E018";
+    readonly SIGNER_UNSUPPORTED_TYPE: "TTT_E019";
+    readonly NETWORK_INVALID_RPC: "TTT_E020";
+    readonly NETWORK_CONNECTION_FAILED: "TTT_E021";
+    readonly NETWORK_CANNOT_RECONNECT: "TTT_E022";
+    readonly NETWORK_RECONNECTION_EXHAUSTED: "TTT_E023";
+    readonly NETWORK_TX_DROPPED: "TTT_E024";
+    readonly NETWORK_PROVIDER_NOT_CONNECTED: "TTT_E025";
+    readonly NETWORK_BLOCK_NOT_FOUND: "TTT_E026";
+    readonly CONTRACT_SIGNER_NOT_CONNECTED: "TTT_E030";
+    readonly CONTRACT_INVALID_ADDRESS: "TTT_E031";
+    readonly CONTRACT_NOT_ATTACHED: "TTT_E032";
+    readonly CONTRACT_BURN_FAILED: "TTT_E033";
+    readonly CONTRACT_MINT_FAILED: "TTT_E034";
+    readonly CONTRACT_BALANCE_QUERY_FAILED: "TTT_E035";
+    readonly CONTRACT_SWAP_FAILED: "TTT_E036";
+    readonly CONTRACT_INVALID_KEY_FORMAT: "TTT_E037";
+    readonly TIME_SYNTHESIS_INTEGRITY_FAILED: "TTT_E040";
+    readonly TIME_SYNTHESIS_INSUFFICIENT_CONFIDENCE: "TTT_E041";
+    readonly TIME_SYNTHESIS_SOURCE_NOT_FOUND: "TTT_E042";
+    readonly TIME_SYNTHESIS_ALL_SOURCES_FAILED: "TTT_E043";
+    readonly TIME_SYNTHESIS_POT_ALL_FAILED: "TTT_E044";
+    readonly TIME_SYNTHESIS_SELF_VERIFY_FAILED: "TTT_E045";
+    readonly FEE_CALCULATION_FAILED: "TTT_E050";
+};
+export type TTTErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
 /**
  * Base error class for TTT SDK errors with storytelling capabilities.
  */
 export declare class TTTBaseError extends Error {
-    readonly message: string;
-    readonly reason: string;
-    readonly fix: string;
-    constructor(message: string, reason: string, fix: string);
+    readonly code: TTTErrorCode;
+    constructor(codeOrMessage: TTTErrorCode | string, messageOrReason: string, reasonOrFix: string, fix?: string);
 }
 /**
  * Errors related to SDK or Engine configuration.
  */
 export declare class TTTConfigError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }
-/**
- * Errors related to Signer (PrivateKey, Turnkey, Privy, KMS) acquisition or usage.
- */
 export declare class TTTSignerError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }
-/**
- * Errors related to Network (RPC, ChainID, Connectivity).
- */
 export declare class TTTNetworkError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }
-/**
- * Errors related to Smart Contract interaction (TTT.sol, ProtocolFee.sol).
- */
 export declare class TTTContractError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }
-/**
- * Errors related to NTP/KTSat Time Synthesis.
- */
 export declare class TTTTimeSynthesisError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }
-/**
- * Errors related to Dynamic Fee Engine or Protocol Fee collection.
- */
 export declare class TTTFeeError extends TTTBaseError {
-    constructor(message: string, reason: string, fix: string);
 }