openttt 0.1.3 → 0.2.1

package/README.md

@@ -10,7 +10,9 @@ OpenTTT brings cryptographic time verification to blockchain transaction orderin
 [![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](LICENSE)
 [![CI](https://github.com/Helm-Protocol/OpenTTT/actions/workflows/ci.yml/badge.svg)](https://github.com/Helm-Protocol/OpenTTT/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/Helm-Protocol/OpenTTT/branch/main/graph/badge.svg)](https://codecov.io/gh/Helm-Protocol/OpenTTT)
-[![Tests](https://img.shields.io/badge/tests-273%20passing%20%C2%B7%2029%20suites-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-386%20passing%20%C2%B7%2032%20suites-brightgreen)]()
+
+> If this project is useful to you, please [star it on GitHub](https://github.com/Helm-Protocol/OpenTTT) — it helps others find it.
 
 ```
 npm install openttt
@@ -40,7 +42,22 @@ No governance vote. No slashing committee. Cheating is simply bad business.
 
 ## Quick Start
 
-Three lines to start minting TimeTokens:
+### Try it in 30 seconds — No ETH, No Wallet
+
+```typescript
+import { HttpOnlyClient } from "openttt";
+
+const client = new HttpOnlyClient();
+const pot = await client.generatePoT();
+console.log(pot.timestamp, pot.confidence, pot.sources);
+
+const valid = client.verifyPoT(pot);
+console.log("Valid:", valid); // true
+```
+
+No blockchain. No wallet. No gas fees. Just verified time from 4 independent HTTPS sources (NIST, Apple, Google, Cloudflare). Start here, upgrade to on-chain when ready.
+
+### On-Chain Mode (Full Power)
 
 ```typescript
 import { TTTClient } from "openttt";
@@ -49,9 +66,7 @@ const ttt = await TTTClient.forBase({ privateKey: process.env.OPERATOR_PK! });
 ttt.startAutoMint();
 ```
 
-That is it. The SDK connects to Base Mainnet, synthesizes time from three atomic clock sources, and begins minting Proof-of-Time tokens at your configured tier interval.
-
-> **Shorthand**: Pass `privateKey` directly as a string instead of the full `signer` config object. The verbose form `{ signer: { type: "privateKey", key: "0x..." } }` still works for when you need other signer types (Turnkey, KMS, Privy).
+Connects to Base, synthesizes time from atomic clock sources, and mints Proof-of-Time tokens on-chain.
 
 ---
 
@@ -246,8 +261,8 @@ const ttt = await TTTClient.create({
 
 | Method | Description |
 |---|---|
-| `GrgPipeline.processForward(data)` | Encode: Golomb compression -> Reed-Solomon erasure coding -> Golay verification |
-| `GrgPipeline.processInverse(shards, length)` | Decode: Golay verify -> Reed-Solomon reconstruct -> Golomb decompress |
+| `GrgPipeline.processForward(data)` | Encode data through the multi-layer integrity pipeline, producing verifiable shards |
+| `GrgPipeline.processInverse(shards, length)` | Decode shards back to original data with integrity verification |
 
 ### AdaptiveSwitch
 
@@ -269,32 +284,18 @@ TTTClient (entry point)
 |   |-- EVMConnector       On-chain mint/burn/events (ethers v6)
 |   '-- ProtocolFee        EIP-712 signed fee collection
 |-- AdaptiveSwitch         TURBO/FULL mode state machine
-|-- GRG Pipeline           Golomb + Reed-Solomon + Golay error correction
+|-- GRG Pipeline           Multi-layer data integrity (proprietary)
 |-- PoolRegistry           Multi-pool statistics tracking
 '-- Signer Abstraction     PrivateKey | Turnkey | Privy | KMS
 ```
 
-### The GRG Pipeline
+### Data Integrity: GRG Pipeline
 
-GRG (Golomb-Reed-Golay) is the data integrity backbone of OpenTTT, analogous to how the TLS record protocol protects HTTP payloads.
+GRG is a multi-layer data integrity pipeline that protects PoT payloads — analogous to how the TLS record protocol protects HTTP payloads. It provides compression, erasure coding, and error correction in a single pass.
 
-```
-              FORWARD (Encode)
-  Raw Data --> Golomb-Rice Compression
-           --> Reed-Solomon Erasure Coding
-           --> Golay(24,12) Verification Codes
-           --> Shards
-
-              INVERSE (Decode)
-  Shards   --> Golay(24,12) Error Detection
-           --> Reed-Solomon Reconstruction
-           --> Golomb-Rice Decompression
-           --> Raw Data
-```
+The pipeline produces verifiable shards that can be independently validated and reconstructed, ensuring PoT integrity even under partial data loss.
 
-**Golomb-Rice** compresses timestamp deltas efficiently (small integers compress well).
-**Reed-Solomon** adds erasure coding so data survives shard loss.
-**Golay(24,12)** detects and corrects up to 3-bit errors per 24-bit codeword.
+> Implementation details are proprietary. See the [IETF Draft](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) for the abstract specification.
 
 ### Adaptive Mode Switching
 
@@ -390,4 +391,25 @@ Copyright 2026 Helm Protocol.
 
 ---
 
+## Learn More
+
+- [IETF Draft: draft-helmprotocol-tttps-00](https://datatracker.ietf.org/doc/draft-helmprotocol-tttps/) — TTTPS Protocol Specification
+- [Yellow Paper](https://github.com/Helm-Protocol/OpenTTT/blob/main/YELLOW_PAPER.md) — Technical Deep Dive
+- [MCP Server](https://github.com/Helm-Protocol/OpenTTT/tree/main/mcp) — AI Agent Integration (`@helm-protocol/ttt-mcp`)
+- [Subgraph (The Graph)](https://api.studio.thegraph.com/query/1744392/openttt-base-sepolia/v0.2.0) — On-chain PoT Data
+- [Base Sepolia Contracts](https://sepolia.basescan.org/address/0xde357135cA493e59680182CDE9E1c6A4dA400811) — TTT ERC-1155
+- [Helm Protocol](https://github.com/Helm-Protocol) — GitHub Organization
+
 [GitHub](https://github.com/Helm-Protocol/OpenTTT) | Built by [Helm Protocol](https://github.com/Helm-Protocol)
+
+---
+
+## Contributing
+
+Contributions are welcome. If you find a bug, have a feature request, or want to improve the documentation, please open an issue or submit a pull request on [GitHub](https://github.com/Helm-Protocol/OpenTTT).
+
+- **Bug reports**: Open an issue with a minimal reproduction case.
+- **Feature requests**: Open an issue describing the use case and expected behavior.
+- **Pull requests**: Fork the repo, make your changes, ensure all tests pass (`npm test`), and open a PR against `main`.
+
+For significant changes, please open an issue first to discuss the approach.

package/dist/adaptive_switch.js

@@ -43,7 +43,7 @@ class AdaptiveSwitch {
         let sequenceOk = orderMatch && timeMatch;
         // B1-1: Do not skip GrgInverse.verify() in TURBO mode
         // We check integrity regardless of mode
-        const integrityOk = helm_crypto_1.GrgInverse.verify(block.data, tttRecord.grgPayload, chainId, poolAddress);
+        const integrityOk = helm_crypto_1.IntegrityDecoder.verify(block.data, tttRecord.grgPayload, chainId, poolAddress);
         if (!integrityOk) {
             logger_1.logger.error(`[AdaptiveSwitch] GRG integrity check FAILED`);
             sequenceOk = false; // Mark as false if integrity fails

package/dist/auto_mint.js

@@ -220,10 +220,10 @@ class AutoMintEngine {
         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 call — run full GRG pipeline (Golomb → Reed-Solomon → Golay+HMAC)
+        // 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 grgShards = helm_crypto_1.IntegrityEncoder.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) {

package/dist/http_client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * TTTClient.httpOnly() — Zero-friction Proof of Time
+ * No ETH, no signer, no on-chain. Just verified time.
+ *
+ * Usage:
+ *   const client = TTTClient.httpOnly();
+ *   const pot = await client.generatePoT();
+ *   console.log(pot.timestamp, pot.confidence);
+ *
+ * Time sources: NIST, Apple, Google, Cloudflare HTTPS Date headers.
+ * HMAC-SHA256 signature — no ethers.js dependency required.
+ */
+import { ProofOfTime } from "./types";
+export interface HttpPoT {
+    /** Synthesized timestamp in Unix nanoseconds (bigint). */
+    timestamp: bigint;
+    /** Fraction of configured sources that responded (0.0–1.0). */
+    confidence: number;
+    /** Lowest NTP stratum observed across sources (2 for HTTPS Date headers). */
+    stratum: number;
+    /** Number of sources that successfully responded. */
+    sources: number;
+    /** Per-source readings used to compute the median. */
+    sourceReadings: {
+        source: string;
+        timestamp: bigint;
+        uncertainty: number;
+        stratum?: number;
+    }[];
+    /** Replay-protection nonce (hex). */
+    nonce: string;
+    /** Expiry timestamp in Unix milliseconds (bigint). */
+    expiresAt: bigint;
+    /** HMAC-SHA256 over canonical fields, hex-encoded. */
+    hmac: string;
+}
+export interface HttpPoTVerifyResult {
+    valid: boolean;
+    reason?: string;
+}
+export interface HttpOnlyClientOptions {
+    /**
+     * Override HMAC secret for non-sandbox usage.
+     * Defaults to a fixed sandbox key — sufficient for local verification only.
+     */
+    hmacSecret?: string;
+    /**
+     * Per-source request timeout in ms. Default: 3000.
+     */
+    timeoutMs?: number;
+    /**
+     * PoT validity window in seconds. Default: 60.
+     */
+    expirySeconds?: number;
+    /**
+     * Maximum divergence allowed between sources in nanoseconds.
+     * Default: 2_000_000_000n (2 seconds — lenient for HTTPS Date 1s resolution).
+     */
+    toleranceNs?: bigint;
+}
+/**
+ * HttpOnlyClient — zero-dependency Proof of Time over HTTPS.
+ *
+ * Fetches time from NIST, Apple, Google, and Cloudflare HTTPS endpoints,
+ * computes the median, and returns a PoT with HMAC integrity protection.
+ *
+ * No ETH, no signer, no on-chain interaction required.
+ */
+export declare class HttpOnlyClient {
+    private readonly hmacSecret;
+    private readonly timeoutMs;
+    private readonly expirySeconds;
+    private readonly toleranceNs;
+    private readonly usedNonces;
+    private readonly NONCE_TTL_MS;
+    private readonly MAX_NONCE_CACHE;
+    constructor(options?: HttpOnlyClientOptions);
+    /**
+     * Fetch time from all four HTTPS sources, compute median, return PoT.
+     * Requires at least 1 source to succeed.
+     */
+    generatePoT(): Promise<HttpPoT>;
+    /**
+     * Verify an HttpPoT:
+     * - HMAC integrity check
+     * - Expiry check
+     * - Nonce replay protection
+     * - Source divergence tolerance check
+     *
+     * No on-chain interaction. Pure local verification.
+     */
+    verifyPoT(pot: HttpPoT): HttpPoTVerifyResult;
+    /**
+     * Convert HttpPoT to the standard ProofOfTime shape used by the rest of the SDK.
+     * The issuerSignature field is omitted (no on-chain signer in httpOnly mode).
+     */
+    static toProofOfTime(pot: HttpPoT): ProofOfTime;
+}

package/dist/http_client.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * TTTClient.httpOnly() — Zero-friction Proof of Time
+ * No ETH, no signer, no on-chain. Just verified time.
+ *
+ * Usage:
+ *   const client = TTTClient.httpOnly();
+ *   const pot = await client.generatePoT();
+ *   console.log(pot.timestamp, pot.confidence);
+ *
+ * Time sources: NIST, Apple, Google, Cloudflare HTTPS Date headers.
+ * HMAC-SHA256 signature — no ethers.js dependency required.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpOnlyClient = void 0;
+const crypto = __importStar(require("crypto"));
+const https = __importStar(require("https"));
+const SOURCES = [
+    { name: "nist", url: "https://time.nist.gov/" },
+    { name: "apple", url: "https://time.apple.com/" },
+    { name: "google", url: "https://time.google.com/" },
+    { name: "cloudflare", url: "https://time.cloudflare.com/" },
+];
+function fetchHttpsDate(name, url, timeoutMs = 3000) {
+    return new Promise((resolve, reject) => {
+        const t1 = BigInt(Date.now()) * 1000000n;
+        const timer = setTimeout(() => {
+            req.destroy();
+            reject(new Error(`[httpOnly] Timeout: ${name} (${timeoutMs}ms)`));
+        }, timeoutMs);
+        const req = https.request(url, { method: "HEAD" }, (res) => {
+            clearTimeout(timer);
+            res.resume(); // drain so socket is freed
+            const t4 = BigInt(Date.now()) * 1000000n;
+            const dateHeader = res.headers["date"];
+            if (!dateHeader) {
+                reject(new Error(`[httpOnly] No Date header from ${name}`));
+                return;
+            }
+            const parsed = new Date(dateHeader).getTime();
+            if (isNaN(parsed)) {
+                reject(new Error(`[httpOnly] Invalid Date header from ${name}: ${dateHeader}`));
+                return;
+            }
+            const serverNs = BigInt(parsed) * 1000000n;
+            const rttNs = t4 - t1;
+            // Offset-corrected: server time + half RTT
+            const corrected = serverNs + rttNs / 2n;
+            const rttMs = Number(rttNs) / 1_000_000;
+            resolve({
+                source: name,
+                timestamp: corrected,
+                uncertainty: rttMs / 2 + 500, // 500ms base — HTTP Date has 1s resolution
+                stratum: 2,
+            });
+        });
+        req.on("error", (err) => {
+            clearTimeout(timer);
+            reject(new Error(`[httpOnly] Request error for ${name}: ${err.message}`));
+        });
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// HMAC helpers — default sandbox key derived from fixed chain+address strings
+// ---------------------------------------------------------------------------
+const SANDBOX_HMAC_SECRET = "openttt-sandbox:chainId=0:address=0x0000000000000000000000000000000000000000";
+function computeHmac(timestamp, nonce, expiresAt, sources, secret = SANDBOX_HMAC_SECRET) {
+    // Canonical message: deterministic field concatenation
+    const msg = `${timestamp.toString()}:${nonce}:${expiresAt.toString()}:${sources}`;
+    return crypto.createHmac("sha256", secret).update(msg).digest("hex");
+}
+/**
+ * HttpOnlyClient — zero-dependency Proof of Time over HTTPS.
+ *
+ * Fetches time from NIST, Apple, Google, and Cloudflare HTTPS endpoints,
+ * computes the median, and returns a PoT with HMAC integrity protection.
+ *
+ * No ETH, no signer, no on-chain interaction required.
+ */
+class HttpOnlyClient {
+    hmacSecret;
+    timeoutMs;
+    expirySeconds;
+    toleranceNs;
+    usedNonces = new Map();
+    NONCE_TTL_MS = 300_000; // 5 min
+    MAX_NONCE_CACHE = 10_000;
+    constructor(options = {}) {
+        this.hmacSecret = options.hmacSecret ?? SANDBOX_HMAC_SECRET;
+        this.timeoutMs = options.timeoutMs ?? 3000;
+        this.expirySeconds = options.expirySeconds ?? 60;
+        this.toleranceNs = options.toleranceNs ?? 2000000000n; // 2 s
+    }
+    /**
+     * Fetch time from all four HTTPS sources, compute median, return PoT.
+     * Requires at least 1 source to succeed.
+     */
+    async generatePoT() {
+        const results = await Promise.allSettled(SOURCES.map((s) => fetchHttpsDate(s.name, s.url, this.timeoutMs)));
+        const readings = [];
+        for (const r of results) {
+            if (r.status === "fulfilled")
+                readings.push(r.value);
+        }
+        if (readings.length === 0) {
+            throw new Error("[httpOnly] All HTTPS time sources failed. Check network connectivity.");
+        }
+        // Sort by timestamp for median selection
+        readings.sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));
+        let finalTs;
+        let finalUnc;
+        let finalStratum;
+        if (readings.length === 1) {
+            finalTs = readings[0].timestamp;
+            finalUnc = readings[0].uncertainty;
+            finalStratum = readings[0].stratum;
+        }
+        else if (readings.length === 2) {
+            finalTs = (readings[0].timestamp + readings[1].timestamp) / 2n;
+            finalUnc = (readings[0].uncertainty + readings[1].uncertainty) / 2;
+            finalStratum = Math.min(readings[0].stratum, readings[1].stratum);
+        }
+        else {
+            const mid = Math.floor(readings.length / 2);
+            finalTs = readings[mid].timestamp;
+            finalUnc = readings[mid].uncertainty;
+            finalStratum = readings[mid].stratum;
+        }
+        const nonce = crypto.randomBytes(16).toString("hex");
+        const expiresAt = BigInt(Date.now()) + BigInt(this.expirySeconds * 1000);
+        const sourceReadings = readings.map((r) => ({
+            source: r.source,
+            timestamp: r.timestamp,
+            uncertainty: r.uncertainty,
+            stratum: r.stratum,
+        }));
+        const hmac = computeHmac(finalTs, nonce, expiresAt, readings.length, this.hmacSecret);
+        return {
+            timestamp: finalTs,
+            confidence: readings.length / SOURCES.length,
+            stratum: finalStratum,
+            sources: readings.length,
+            sourceReadings,
+            nonce,
+            expiresAt,
+            hmac,
+        };
+    }
+    /**
+     * Verify an HttpPoT:
+     * - HMAC integrity check
+     * - Expiry check
+     * - Nonce replay protection
+     * - Source divergence tolerance check
+     *
+     * No on-chain interaction. Pure local verification.
+     */
+    verifyPoT(pot) {
+        // 1. Expiry
+        if (BigInt(Date.now()) > pot.expiresAt) {
+            return { valid: false, reason: "PoT expired" };
+        }
+        // 2. HMAC integrity
+        const expected = computeHmac(pot.timestamp, pot.nonce, pot.expiresAt, pot.sources, this.hmacSecret);
+        if (!crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(pot.hmac, "hex"))) {
+            return { valid: false, reason: "HMAC mismatch — PoT may have been tampered" };
+        }
+        // 3. Nonce replay (bounded cache + TTL)
+        const now = Date.now();
+        if (this.usedNonces.size > this.MAX_NONCE_CACHE / 2) {
+            for (const [k, ts] of this.usedNonces) {
+                if (now - ts > this.NONCE_TTL_MS)
+                    this.usedNonces.delete(k);
+            }
+        }
+        if (this.usedNonces.has(pot.nonce)) {
+            return { valid: false, reason: "Duplicate nonce — replay detected" };
+        }
+        if (this.usedNonces.size >= this.MAX_NONCE_CACHE) {
+            const oldest = this.usedNonces.keys().next().value;
+            if (oldest !== undefined)
+                this.usedNonces.delete(oldest);
+        }
+        this.usedNonces.set(pot.nonce, now);
+        // 4. Source divergence
+        for (const reading of pot.sourceReadings) {
+            const diff = reading.timestamp > pot.timestamp
+                ? reading.timestamp - pot.timestamp
+                : pot.timestamp - reading.timestamp;
+            if (diff > this.toleranceNs) {
+                return {
+                    valid: false,
+                    reason: `Source ${reading.source} diverges by ${diff}ns (tolerance: ${this.toleranceNs}ns)`,
+                };
+            }
+        }
+        return { valid: true };
+    }
+    /**
+     * Convert HttpPoT to the standard ProofOfTime shape used by the rest of the SDK.
+     * The issuerSignature field is omitted (no on-chain signer in httpOnly mode).
+     */
+    static toProofOfTime(pot) {
+        return {
+            timestamp: pot.timestamp,
+            uncertainty: pot.sourceReadings.length > 0
+                ? pot.sourceReadings.reduce((sum, r) => sum + r.uncertainty, 0) / pot.sourceReadings.length
+                : 500,
+            sources: pot.sources,
+            stratum: pot.stratum,
+            confidence: pot.confidence,
+            sourceReadings: pot.sourceReadings,
+            nonce: pot.nonce,
+            expiresAt: pot.expiresAt,
+        };
+    }
+}
+exports.HttpOnlyClient = HttpOnlyClient;

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./v4_hook";
 export * from "./logger";
 export * from "./types";
 export * from "./ttt_client";
+export * from "./http_client";
 export * from "./auto_mint";
 export * from "./time_synthesis";
 export * from "./dynamic_fee";
@@ -19,3 +20,4 @@ export * from "./pot_signer";
 export * from "./ct_log";
 export * from "./trust_store";
 export * from "./revenue_tiers";
+export * from "./integrity_client";

package/dist/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./v4_hook"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./ttt_client"), exports);
+__exportStar(require("./http_client"), exports);
 __exportStar(require("./auto_mint"), exports);
 __exportStar(require("./time_synthesis"), exports);
 __exportStar(require("./dynamic_fee"), exports);
@@ -36,3 +37,4 @@ __exportStar(require("./pot_signer"), exports);
 __exportStar(require("./ct_log"), exports);
 __exportStar(require("./trust_store"), exports);
 __exportStar(require("./revenue_tiers"), exports);
+__exportStar(require("./integrity_client"), exports);

package/dist/integrity_client.d.ts

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

package/dist/integrity_client.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Integrity Client — replaces local integrity computation with server-side API call.
+ * Core pipeline source code stays in Helm private repo. Only API calls go through npm SDK.
+ *
+ * Drop-in replacement interface for local encode() and verify() operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrityClient = void 0;
+exports.getDefaultIntegrityClient = getDefaultIntegrityClient;
+exports.setDefaultIntegrityClient = setDefaultIntegrityClient;
+class IntegrityClient {
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl = "https://integrity.helmprotocol.com/api/v1", options) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeoutMs = options?.timeoutMs ?? 5000;
+    }
+    /**
+     * Forward pass: encode data through integrity pipeline (server-side).
+     *
+     * @returns Array of Uint8Array shards
+     */
+    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(`Integrity 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 data integrity (server-side).
+     *
+     * @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(`Integrity API error: ${resp.status} ${resp.statusText}`);
+            }
+            const result = await resp.json();
+            return result.valid;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Health check — ping the integrity 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.IntegrityClient = IntegrityClient;
+/**
+ * Singleton default client — uses production integrity API endpoint.
+ * Can be overridden via setDefaultIntegrityClient() for testing/staging.
+ */
+let _defaultClient = null;
+function getDefaultIntegrityClient() {
+    if (!_defaultClient) {
+        _defaultClient = new IntegrityClient();
+    }
+    return _defaultClient;
+}
+function setDefaultIntegrityClient(client) {
+    _defaultClient = client;
+}