openttt 0.1.2 → 0.1.3

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);
 }

package/dist/errors.js

@@ -1,18 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TTTFeeError = exports.TTTTimeSynthesisError = exports.TTTContractError = exports.TTTNetworkError = exports.TTTSignerError = exports.TTTConfigError = exports.TTTBaseError = void 0;
+exports.TTTFeeError = exports.TTTTimeSynthesisError = exports.TTTContractError = exports.TTTNetworkError = exports.TTTSignerError = exports.TTTConfigError = exports.TTTBaseError = exports.ERROR_CODES = void 0;
+/**
+ * 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
+ */
+exports.ERROR_CODES = {
+    // Config errors (TTT_E001-E009)
+    CONFIG_MISSING_SIGNER: "TTT_E001",
+    CONFIG_INVALID: "TTT_E002",
+    // Signer errors (TTT_E010-E019)
+    SIGNER_NOT_INITIALIZED: "TTT_E010",
+    SIGNER_MISSING_KEY: "TTT_E011",
+    SIGNER_INVALID_KEY_FORMAT: "TTT_E012",
+    SIGNER_NO_EIP712: "TTT_E013",
+    SIGNER_PRIVY_NOT_IMPLEMENTED: "TTT_E014",
+    SIGNER_KMS_AWS_INIT_FAILED: "TTT_E015",
+    SIGNER_KMS_GCP_MISSING_FIELDS: "TTT_E016",
+    SIGNER_KMS_GCP_INIT_FAILED: "TTT_E017",
+    SIGNER_KMS_UNSUPPORTED_PROVIDER: "TTT_E018",
+    SIGNER_UNSUPPORTED_TYPE: "TTT_E019",
+    // Network errors (TTT_E020-E029)
+    NETWORK_INVALID_RPC: "TTT_E020",
+    NETWORK_CONNECTION_FAILED: "TTT_E021",
+    NETWORK_CANNOT_RECONNECT: "TTT_E022",
+    NETWORK_RECONNECTION_EXHAUSTED: "TTT_E023",
+    NETWORK_TX_DROPPED: "TTT_E024",
+    NETWORK_PROVIDER_NOT_CONNECTED: "TTT_E025",
+    NETWORK_BLOCK_NOT_FOUND: "TTT_E026",
+    // Contract errors (TTT_E030-E039)
+    CONTRACT_SIGNER_NOT_CONNECTED: "TTT_E030",
+    CONTRACT_INVALID_ADDRESS: "TTT_E031",
+    CONTRACT_NOT_ATTACHED: "TTT_E032",
+    CONTRACT_BURN_FAILED: "TTT_E033",
+    CONTRACT_MINT_FAILED: "TTT_E034",
+    CONTRACT_BALANCE_QUERY_FAILED: "TTT_E035",
+    CONTRACT_SWAP_FAILED: "TTT_E036",
+    CONTRACT_INVALID_KEY_FORMAT: "TTT_E037",
+    // TimeSynthesis errors (TTT_E040-E049)
+    TIME_SYNTHESIS_INTEGRITY_FAILED: "TTT_E040",
+    TIME_SYNTHESIS_INSUFFICIENT_CONFIDENCE: "TTT_E041",
+    TIME_SYNTHESIS_SOURCE_NOT_FOUND: "TTT_E042",
+    TIME_SYNTHESIS_ALL_SOURCES_FAILED: "TTT_E043",
+    TIME_SYNTHESIS_POT_ALL_FAILED: "TTT_E044",
+    TIME_SYNTHESIS_SELF_VERIFY_FAILED: "TTT_E045",
+    // Fee errors (TTT_E050-E059)
+    FEE_CALCULATION_FAILED: "TTT_E050",
+};
 /**
  * Base error class for TTT SDK errors with storytelling capabilities.
  */
 class TTTBaseError extends Error {
-    message;
-    reason;
-    fix;
-    constructor(message, reason, fix) {
-        super(`${message} (Reason: ${reason}. Fix: ${fix})`);
-        this.message = message;
-        this.reason = reason;
-        this.fix = fix;
+    code;
+    constructor(codeOrMessage, messageOrReason, reasonOrFix, fix) {
+        // Support both old (message, reason, fix) and new (code, message, reason, fix) signatures
+        const hasCode = fix !== undefined;
+        const code = hasCode ? codeOrMessage : "TTT_E002";
+        const message = hasCode ? messageOrReason : codeOrMessage;
+        const reason = hasCode ? reasonOrFix : messageOrReason;
+        const fixStr = hasCode ? fix : reasonOrFix;
+        super(`[${code}] ${message} (Reason: ${reason}. Fix: ${fixStr})`);
+        this.code = code;
         this.name = this.constructor.name;
         Object.setPrototypeOf(this, new.target.prototype);
     }
@@ -22,53 +71,20 @@ exports.TTTBaseError = TTTBaseError;
  * Errors related to SDK or Engine configuration.
  */
 class TTTConfigError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTConfigError = TTTConfigError;
-/**
- * Errors related to Signer (PrivateKey, Turnkey, Privy, KMS) acquisition or usage.
- */
 class TTTSignerError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTSignerError = TTTSignerError;
-/**
- * Errors related to Network (RPC, ChainID, Connectivity).
- */
 class TTTNetworkError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTNetworkError = TTTNetworkError;
-/**
- * Errors related to Smart Contract interaction (TTT.sol, ProtocolFee.sol).
- */
 class TTTContractError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTContractError = TTTContractError;
-/**
- * Errors related to NTP/KTSat Time Synthesis.
- */
 class TTTTimeSynthesisError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTTimeSynthesisError = TTTTimeSynthesisError;
-/**
- * Errors related to Dynamic Fee Engine or Protocol Fee collection.
- */
 class TTTFeeError extends TTTBaseError {
-    constructor(message, reason, fix) {
-        super(message, reason, fix);
-    }
 }
 exports.TTTFeeError = TTTFeeError;

package/dist/evm_connector.d.ts

@@ -7,6 +7,10 @@ export interface VerificationResult {
     txCount: number;
     latency: number;
 }
+export interface EVMConnectorOptions {
+    fallbackRpcUrls?: string[];
+    maxReconnectAttempts?: number;
+}
 export declare class EVMConnector {
     private provider;
     private signer;
@@ -14,7 +18,12 @@ export declare class EVMConnector {
     private protocolFeeContract;
     private eventListeners;
     private static readonly GAS_TIMEOUT_MS;
-    constructor();
+    private primaryRpcUrl;
+    private fallbackRpcUrls;
+    private signerOrKey;
+    private maxReconnectAttempts;
+    private connected;
+    constructor(options?: EVMConnectorOptions);
     /**
      * P1-7: Race estimateGas against timeout to prevent DoS
      */
@@ -23,6 +32,24 @@ export declare class EVMConnector {
      * Connect to an EVM chain using either a private key or a pre-configured signer.
      */
     connect(rpcUrl: string, signerOrKey: string | Signer): Promise<void>;
+    /**
+     * Reconnect using stored credentials. Tries primary first, then fallbacks.
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Disconnect and release all resources.
+     */
+    disconnect(): void;
+    /**
+     * Check if the connector is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * CT Log Equivalent: PoTAnchored event ABI fragment.
+     * Every Proof-of-Time anchor is publicly auditable on-chain,
+     * analogous to Certificate Transparency logs in TLS.
+     */
+    static readonly POT_ANCHORED_EVENT_ABI = "event PoTAnchored(uint64 indexed timestamp, bytes32 grgHash, uint8 stratum, bytes32 potHash)";
     /**
      * Attach the TTT Token contract.
      */