openttt 0.1.2 → 0.2.0

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.
      */

package/dist/evm_connector.js

@@ -14,14 +14,22 @@ class EVMConnector {
     eventListeners = []; // P2-6: Track listeners for cleanup
     // P1-7: Timeout wrapper for gas estimation
     static GAS_TIMEOUT_MS = 5000;
-    constructor() { }
+    primaryRpcUrl = "";
+    fallbackRpcUrls = [];
+    signerOrKey = null;
+    maxReconnectAttempts;
+    connected = false;
+    constructor(options) {
+        this.fallbackRpcUrls = options?.fallbackRpcUrls ?? [];
+        this.maxReconnectAttempts = options?.maxReconnectAttempts ?? 3;
+    }
     /**
      * P1-7: Race estimateGas against timeout to prevent DoS
      */
     async withTimeout(promise, ms = EVMConnector.GAS_TIMEOUT_MS) {
         return Promise.race([
             promise,
-            new Promise((_, reject) => setTimeout(() => reject(new errors_1.TTTNetworkError(`[EVM] Operation timed out`, `RPC did not respond within ${ms}ms`, `Check your RPC provider status or increase timeout.`)), ms))
+            new Promise((_, reject) => setTimeout(() => reject(new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_CONNECTION_FAILED, `[EVM] Operation timed out`, `RPC did not respond within ${ms}ms`, `Check your RPC provider status or increase timeout.`)), ms))
         ]);
     }
     /**
@@ -29,36 +37,116 @@ class EVMConnector {
      */
     async connect(rpcUrl, signerOrKey) {
         if (!rpcUrl || typeof rpcUrl !== "string")
-            throw new errors_1.TTTNetworkError("[EVM] Invalid RPC URL", "The provided RPC URL is empty or not a string", "Pass a valid RPC URL (e.g., https://mainnet.base.org)");
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_INVALID_RPC, "[EVM] Invalid RPC URL", "The provided RPC URL is empty or not a string", "Pass a valid RPC URL (e.g., https://mainnet.base.org)");
+        this.primaryRpcUrl = rpcUrl;
+        this.signerOrKey = signerOrKey;
         try {
             this.provider = new ethers_1.JsonRpcProvider(rpcUrl);
             if (typeof signerOrKey === "string") {
                 if (!signerOrKey.startsWith("0x") || signerOrKey.length !== 66) {
-                    throw new errors_1.TTTContractError("[EVM] Invalid Private Key format", "Private key must be 0x + 64 hex characters", "Provide a valid 32-byte hex private key.");
+                    throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_INVALID_KEY_FORMAT, "[EVM] Invalid Private Key format", "Private key must be 0x + 64 hex characters", "Provide a valid 32-byte hex private key.");
                 }
                 this.signer = new ethers_1.ethers.Wallet(signerOrKey, this.provider);
             }
             else {
-                // Signer might already be connected to a provider, but we ensure it's linked to ours
                 this.signer = signerOrKey.connect ? signerOrKey.connect(this.provider) : signerOrKey;
             }
             const network = await this.provider.getNetwork();
+            this.connected = true;
             logger_1.logger.info(`[EVM] Connected to Chain ID: ${network.chainId}`);
         }
         catch (error) {
             if (error instanceof errors_1.TTTContractError || error instanceof errors_1.TTTNetworkError)
                 throw error;
-            throw new errors_1.TTTNetworkError(`[EVM] Connection failed`, error instanceof Error ? error.message : String(error), `Verify your RPC URL and network connectivity.`);
+            // Try fallback RPCs before giving up
+            for (const fallback of this.fallbackRpcUrls) {
+                try {
+                    logger_1.logger.warn(`[EVM] Primary RPC failed, trying fallback: ${fallback}`);
+                    this.provider = new ethers_1.JsonRpcProvider(fallback);
+                    if (typeof signerOrKey === "string") {
+                        this.signer = new ethers_1.ethers.Wallet(signerOrKey, this.provider);
+                    }
+                    else {
+                        this.signer = signerOrKey.connect ? signerOrKey.connect(this.provider) : signerOrKey;
+                    }
+                    const network = await this.provider.getNetwork();
+                    this.connected = true;
+                    logger_1.logger.info(`[EVM] Connected via fallback to Chain ID: ${network.chainId}`);
+                    return;
+                }
+                catch {
+                    continue;
+                }
+            }
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_CONNECTION_FAILED, `[EVM] Connection failed`, error instanceof Error ? error.message : String(error), `Verify your RPC URL and network connectivity.`);
+        }
+    }
+    /**
+     * Reconnect using stored credentials. Tries primary first, then fallbacks.
+     */
+    async reconnect() {
+        if (!this.signerOrKey)
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_CANNOT_RECONNECT, "[EVM] Cannot reconnect", "No previous connection credentials stored", "Call connect() first.");
+        this.disconnect();
+        const allUrls = [this.primaryRpcUrl, ...this.fallbackRpcUrls].filter(Boolean);
+        for (let attempt = 0; attempt < Math.min(this.maxReconnectAttempts, allUrls.length); attempt++) {
+            try {
+                const url = allUrls[attempt % allUrls.length];
+                logger_1.logger.info(`[EVM] Reconnect attempt ${attempt + 1}/${this.maxReconnectAttempts} → ${url}`);
+                this.provider = new ethers_1.JsonRpcProvider(url);
+                if (typeof this.signerOrKey === "string") {
+                    this.signer = new ethers_1.ethers.Wallet(this.signerOrKey, this.provider);
+                }
+                else {
+                    this.signer = this.signerOrKey.connect ? this.signerOrKey.connect(this.provider) : this.signerOrKey;
+                }
+                await this.provider.getNetwork();
+                this.connected = true;
+                logger_1.logger.info(`[EVM] Reconnected successfully`);
+                return;
+            }
+            catch {
+                logger_1.logger.warn(`[EVM] Reconnect attempt ${attempt + 1} failed`);
+            }
+        }
+        this.connected = false;
+        throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_RECONNECTION_EXHAUSTED, "[EVM] Reconnection failed", `All ${this.maxReconnectAttempts} attempts exhausted`, "Check RPC provider status and network connectivity.");
+    }
+    /**
+     * Disconnect and release all resources.
+     */
+    disconnect() {
+        this.unsubscribeAll();
+        if (this.provider) {
+            this.provider.destroy();
         }
+        this.provider = null;
+        this.signer = null;
+        this.tttContract = null;
+        this.protocolFeeContract = null;
+        this.connected = false;
+        logger_1.logger.info("[EVM] Disconnected and resources released");
+    }
+    /**
+     * Check if the connector is currently connected.
+     */
+    isConnected() {
+        return this.connected && this.provider !== null;
     }
+    /**
+     * 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 POT_ANCHORED_EVENT_ABI = "event PoTAnchored(uint64 indexed timestamp, bytes32 grgHash, uint8 stratum, bytes32 potHash)";
     /**
      * Attach the TTT Token contract.
      */
     attachContract(address, abi) {
         if (!this.signer)
-            throw new errors_1.TTTContractError("Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_SIGNER_NOT_CONNECTED, "Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
         if (!address || !ethers_1.ethers.isAddress(address))
-            throw new errors_1.TTTContractError(`[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_INVALID_ADDRESS, `[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
         this.tttContract = new ethers_1.Contract(address, abi, this.signer);
     }
     /**
@@ -66,9 +154,9 @@ class EVMConnector {
      */
     attachProtocolFeeContract(address, abi) {
         if (!this.signer)
-            throw new errors_1.TTTContractError("Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_SIGNER_NOT_CONNECTED, "Not connected to signer", "EVMConnector.connect() must be called first", "Initialize connection before attaching contracts.");
         if (!address || !ethers_1.ethers.isAddress(address))
-            throw new errors_1.TTTContractError(`[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_INVALID_ADDRESS, `[EVM] Invalid contract address`, `Address '${address}' is not a valid EVM address`, `Check your config and provide a valid checksummed address.`);
         this.protocolFeeContract = new ethers_1.Contract(address, abi, this.signer);
     }
     /**
@@ -76,7 +164,7 @@ class EVMConnector {
      */
     async submitTTTRecord(record, amount, tier) {
         if (!this.tttContract)
-            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() with valid TTT address before burning.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_NOT_ATTACHED, "Contract not attached", "TTT contract instance is null", "Call attachContract() with valid TTT address before burning.");
         const grgHash = ethers_1.ethers.keccak256(ethers_1.ethers.concat(record.grgPayload));
         try {
             // P1-7: Gas estimation with timeout
@@ -88,14 +176,14 @@ class EVMConnector {
             const receipt = await tx.wait();
             // P2-5: Null check for dropped transactions
             if (!receipt)
-                throw new errors_1.TTTNetworkError(`[EVM] Transaction failed`, `Transaction was dropped from mempool or null receipt`, `Check block explorer for tx status.`);
+                throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_TX_DROPPED, `[EVM] Transaction failed`, `Transaction was dropped from mempool or null receipt`, `Check block explorer for tx status.`);
             return receipt;
         }
         catch (error) {
             if (error instanceof errors_1.TTTNetworkError || error instanceof errors_1.TTTContractError)
                 throw error;
             const reason = this.extractRevertReason(error);
-            throw new errors_1.TTTContractError(`[EVM] Burn failed`, reason, `Verify your TTT balance and tier parameters.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_BURN_FAILED, `[EVM] Burn failed`, reason, `Verify your TTT balance and tier parameters.`);
         }
     }
     /**
@@ -103,22 +191,26 @@ class EVMConnector {
      */
     async mintTTT(to, amount, grgHash, potHash) {
         if (!this.tttContract)
-            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before minting.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_NOT_ATTACHED, "Contract not attached", "TTT contract instance is null", "Call attachContract() before minting.");
         if (!to || !ethers_1.ethers.isAddress(to))
-            throw new errors_1.TTTContractError(`[EVM] Invalid recipient address`, `Address '${to}' is not a valid EVM address`, `Provide a valid destination address.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_INVALID_ADDRESS, `[EVM] Invalid recipient address`, `Address '${to}' is not a valid EVM address`, `Provide a valid destination address.`);
         try {
             if (potHash) {
                 logger_1.logger.info(`[EVM] Recording PoT fingerprint: ${potHash}`);
             }
-            const tx = await this.tttContract.mint(to, amount, grgHash);
+            // Gas estimation with 20% buffer and timeout (matching burnTTT pattern)
+            const gasLimit = await this.withTimeout(this.tttContract.mint.estimateGas(to, amount, grgHash));
+            const tx = await this.tttContract.mint(to, amount, grgHash, {
+                gasLimit: (gasLimit * 120n) / 100n
+            });
             const receipt = await tx.wait();
             if (!receipt)
-                throw new errors_1.TTTNetworkError(`[EVM] Mint TX dropped`, `Transaction was dropped from mempool`, `Check operator account for nonce collisions.`);
+                throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_TX_DROPPED, `[EVM] Mint TX dropped`, `Transaction was dropped from mempool`, `Check operator account for nonce collisions.`);
             return receipt;
         }
         catch (error) {
             const reason = this.extractRevertReason(error);
-            throw new errors_1.TTTContractError(`[EVM] Mint failed`, reason, `Ensure operator has minter role and sufficient gas.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_MINT_FAILED, `[EVM] Mint failed`, reason, `Ensure operator has minter role and sufficient gas.`);
         }
     }
     /**
@@ -126,17 +218,17 @@ class EVMConnector {
      */
     async burnTTT(amount, grgHash, tierLevel) {
         if (!this.tttContract)
-            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before burning.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_NOT_ATTACHED, "Contract not attached", "TTT contract instance is null", "Call attachContract() before burning.");
         try {
             const tx = await this.tttContract.burn(amount, grgHash, tierLevel);
             const receipt = await tx.wait();
             if (!receipt)
-                throw new errors_1.TTTNetworkError(`[EVM] Burn TX dropped`, `Transaction was dropped from mempool`, `Verify account balance.`);
+                throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_TX_DROPPED, `[EVM] Burn TX dropped`, `Transaction was dropped from mempool`, `Verify account balance.`);
             return { hash: receipt.hash };
         }
         catch (error) {
             const reason = this.extractRevertReason(error);
-            throw new errors_1.TTTContractError(`[EVM] Burn failed`, reason, `Check TTT balance.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_BURN_FAILED, `[EVM] Burn failed`, reason, `Check TTT balance.`);
         }
     }
     /**
@@ -144,13 +236,13 @@ class EVMConnector {
      */
     async getTTTBalance(user, tokenId) {
         if (!this.tttContract)
-            throw new errors_1.TTTContractError("Contract not attached", "TTT contract instance is null", "Call attachContract() before querying balance.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_NOT_ATTACHED, "Contract not attached", "TTT contract instance is null", "Call attachContract() before querying balance.");
         try {
             return await this.tttContract.balanceOf(user, tokenId);
         }
         catch (error) {
             const reason = this.extractRevertReason(error);
-            throw new errors_1.TTTContractError(`[EVM] Balance query failed`, reason, `Check RPC connection and contract address.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_BALANCE_QUERY_FAILED, `[EVM] Balance query failed`, reason, `Check RPC connection and contract address.`);
         }
     }
     /**
@@ -158,9 +250,9 @@ class EVMConnector {
      */
     async swap(routerAddress, tokenIn, tokenOut, amountIn, minAmountOut) {
         if (!this.signer)
-            throw new errors_1.TTTContractError("Not connected to signer", "Signer is null", "Initialize connection.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_SIGNER_NOT_CONNECTED, "Not connected to signer", "Signer is null", "Initialize connection.");
         if (!routerAddress || !ethers_1.ethers.isAddress(routerAddress))
-            throw new errors_1.TTTContractError(`[EVM] Invalid router address`, `Address '${routerAddress}' is invalid`, `Provide valid V4 SwapRouter address.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_INVALID_ADDRESS, `[EVM] Invalid router address`, `Address '${routerAddress}' is invalid`, `Provide valid V4 SwapRouter address.`);
         logger_1.logger.info(`[EVM] Swapping ${amountIn} of ${tokenIn} for ${tokenOut} via ${routerAddress}`);
         // Realistic Uniswap V4-like SwapRouter ABI for simulation/integration
         const swapRouterAbi = [
@@ -176,14 +268,14 @@ class EVMConnector {
             logger_1.logger.info(`[EVM] Swap TX Sent: ${tx.hash}`);
             const receipt = await tx.wait();
             if (!receipt)
-                throw new errors_1.TTTNetworkError(`[EVM] Swap TX dropped`, `Transaction dropped`, `Check gas price.`);
+                throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_TX_DROPPED, `[EVM] Swap TX dropped`, `Transaction dropped`, `Check gas price.`);
             return receipt;
         }
         catch (error) {
             if (error instanceof errors_1.TTTNetworkError || error instanceof errors_1.TTTContractError)
                 throw error;
             const reason = this.extractRevertReason(error);
-            throw new errors_1.TTTContractError(`[EVM] Swap failed`, reason, `Verify slippage and token balances.`);
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_SWAP_FAILED, `[EVM] Swap failed`, reason, `Verify slippage and token balances.`);
         }
     }
     /**
@@ -241,10 +333,10 @@ class EVMConnector {
      */
     async verifyBlock(blockNum) {
         if (!this.provider)
-            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_PROVIDER_NOT_CONNECTED, "Provider not connected", "RPC provider is null", "Call connect() first.");
         const block = await this.provider.getBlock(blockNum);
         if (!block)
-            throw new errors_1.TTTNetworkError(`Block not found`, `RPC returned null for block ${blockNum}`, `Verify if block number exists on chain.`);
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_BLOCK_NOT_FOUND, `Block not found`, `RPC returned null for block ${blockNum}`, `Verify if block number exists on chain.`);
         return {
             valid: true,
             blockNumber: blockNum,
@@ -258,7 +350,7 @@ class EVMConnector {
      */
     async getPendingTransactions() {
         if (!this.provider)
-            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_PROVIDER_NOT_CONNECTED, "Provider not connected", "RPC provider is null", "Call connect() first.");
         const block = await this.provider.send("eth_getBlockByNumber", ["pending", false]);
         return block ? block.transactions : [];
     }
@@ -267,7 +359,7 @@ class EVMConnector {
      */
     getProvider() {
         if (!this.provider)
-            throw new errors_1.TTTNetworkError("Provider not connected", "RPC provider is null", "Call connect() first.");
+            throw new errors_1.TTTNetworkError(errors_1.ERROR_CODES.NETWORK_PROVIDER_NOT_CONNECTED, "Provider not connected", "RPC provider is null", "Call connect() first.");
         return this.provider;
     }
     /**
@@ -275,7 +367,7 @@ class EVMConnector {
      */
     getSigner() {
         if (!this.signer)
-            throw new errors_1.TTTContractError("Signer not connected", "Signer is null", "Call connect() first.");
+            throw new errors_1.TTTContractError(errors_1.ERROR_CODES.CONTRACT_SIGNER_NOT_CONNECTED, "Signer not connected", "Signer is null", "Call connect() first.");
         return this.signer;
     }
     /**

package/dist/grg_api_client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * GRG API Client — replaces local GRG computation with server-side API call.
+ * GRG source code stays in Helm private repo. Only API calls go through npm SDK.
+ *
+ * Drop-in replacement interface for local GrgForward.encode() and GrgInverse.verify().
+ */
+export interface GrgEncodeResult {
+    /** Hex-encoded serialized shards (joined as JSON array of hex strings) */
+    shards: string[];
+}
+export interface GrgVerifyResult {
+    valid: boolean;
+}
+export declare class GrgApiClient {
+    private baseUrl;
+    private timeoutMs;
+    constructor(baseUrl?: string, options?: {
+        timeoutMs?: number;
+    });
+    /**
+     * Forward pass: encode data through GRG pipeline (server-side).
+     * Same interface contract as local GrgForward.encode().
+     *
+     * @returns Array of Uint8Array shards (same shape as GrgForward.encode())
+     */
+    encode(data: Uint8Array, chainId: number, poolAddress: string): Promise<Uint8Array[]>;
+    /**
+     * Verify: check GRG integrity (server-side).
+     * Same interface contract as local GrgInverse.verify().
+     *
+     * @returns boolean — true if data matches the original shards
+     */
+    verify(data: Uint8Array, originalShards: Uint8Array[], chainId: number, poolAddress: string): Promise<boolean>;
+    /**
+     * Health check — ping the GRG API server.
+     * Returns true if reachable within timeoutMs.
+     */
+    isReachable(): Promise<boolean>;
+}
+export declare function getDefaultGrgApiClient(): GrgApiClient;
+export declare function setDefaultGrgApiClient(client: GrgApiClient): void;

package/dist/grg_api_client.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * GRG API Client — replaces local GRG computation with server-side API call.
+ * GRG source code stays in Helm private repo. Only API calls go through npm SDK.
+ *
+ * Drop-in replacement interface for local GrgForward.encode() and GrgInverse.verify().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrgApiClient = void 0;
+exports.getDefaultGrgApiClient = getDefaultGrgApiClient;
+exports.setDefaultGrgApiClient = setDefaultGrgApiClient;
+class GrgApiClient {
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl = "https://grg.helmprotocol.com/api/v1", options) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeoutMs = options?.timeoutMs ?? 5000;
+    }
+    /**
+     * Forward pass: encode data through GRG pipeline (server-side).
+     * Same interface contract as local GrgForward.encode().
+     *
+     * @returns Array of Uint8Array shards (same shape as GrgForward.encode())
+     */
+    async encode(data, chainId, poolAddress) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/encode`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    data: Buffer.from(data).toString("hex"),
+                    chainId: chainId,
+                    poolAddress,
+                }),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new Error(`GRG API error: ${resp.status} ${resp.statusText}`);
+            }
+            const result = await resp.json();
+            return result.shards.map((hex) => Buffer.from(hex, "hex"));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Verify: check GRG integrity (server-side).
+     * Same interface contract as local GrgInverse.verify().
+     *
+     * @returns boolean — true if data matches the original shards
+     */
+    async verify(data, originalShards, chainId, poolAddress) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/verify`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    data: Buffer.from(data).toString("hex"),
+                    shards: originalShards.map((s) => Buffer.from(s).toString("hex")),
+                    chainId: chainId,
+                    poolAddress,
+                }),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new Error(`GRG API error: ${resp.status} ${resp.statusText}`);
+            }
+            const result = await resp.json();
+            return result.valid;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Health check — ping the GRG API server.
+     * Returns true if reachable within timeoutMs.
+     */
+    async isReachable() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/health`, {
+                method: "GET",
+                signal: controller.signal,
+            });
+            return resp.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.GrgApiClient = GrgApiClient;
+/**
+ * Singleton default client — uses production GRG API endpoint.
+ * Can be overridden via setDefaultGrgApiClient() for testing/staging.
+ */
+let _defaultClient = null;
+function getDefaultGrgApiClient() {
+    if (!_defaultClient) {
+        _defaultClient = new GrgApiClient();
+    }
+    return _defaultClient;
+}
+function setDefaultGrgApiClient(client) {
+    _defaultClient = client;
+}