@0xkaleab/sdk-js 0.2.7

package/dist/cjs/wasm/lep1.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * LEP-1 Helper Functions for RaptorQ Layout Operations
+ *
+ * This module implements the LEP-1 (Lumera Enhancement Proposal 1) specification
+ * for RaptorQ layout generation and index file construction. LEP-1 defines how
+ * Cascade uploads derive layout IDs and construct the index file metadata.
+ *
+ * @see https://github.com/LumeraProtocol/LEPs/blob/main/LEP-1.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSingleBlockLayout = createSingleBlockLayout;
+exports.parseLayoutFile = parseLayoutFile;
+exports.generateIds = generateIds;
+exports.buildIndexFile = buildIndexFile;
+const raptorq_proxy_js_1 = require("./raptorq-proxy.js");
+const hash_js_1 = require("./../internal/hash.js");
+const zstd_js_1 = require("./../internal/zstd.js");
+const bs58_1 = require("bs58");
+/**
+ * Creates a single-block RaptorQ layout from file bytes.
+ *
+ * This function generates a deterministic RaptorQ layout suitable for encoding
+ * the provided file data into a single source block. The layout is computed by
+ * the rq-wasm library and includes all parameters needed for encoding and decoding.
+ *
+ * @param fileBytes - The complete file content as a Uint8Array
+ * @returns A promise that resolves to the raw layout file bytes (JSON format)
+ *
+ * @throws {Error} If the WASM module fails to initialize or layout creation fails
+ *
+ * @remarks
+ * - The layout generation is deterministic: identical input always produces identical output
+ * - This is critical for LEP-1 compliance and data integrity verification
+ * - The layout bytes are what should be signed for LEP-1 compliance
+ * - Use parseLayoutFile() to parse the bytes into a Layout object if needed for verification
+ *
+ * @example
+ * ```typescript
+ * const fileData = new TextEncoder().encode('Hello, Lumera!');
+ * const layoutBytes = await createSingleBlockLayout(fileData);
+ *
+ * // Parse if needed for verification
+ * const layout = parseLayoutFile(layoutBytes);
+ * console.log('Transfer length:', layout.transfer_length);
+ * console.log('Symbol size:', layout.symbol_size);
+ * ```
+ */
+async function createSingleBlockLayout(fileBytes) {
+    const proxy = raptorq_proxy_js_1.RaptorQProxy.getInstance();
+    return proxy.createSingleBlockLayout(fileBytes);
+}
+/**
+ * Parses raw layout file bytes into a Layout object.
+ *
+ * This utility function decodes and parses the JSON layout file returned by
+ * createSingleBlockLayout. It's useful when you need to inspect layout properties
+ * for verification or debugging purposes.
+ *
+ * @param layoutBytes - The raw layout file bytes (UTF-8 encoded JSON)
+ * @returns The parsed Layout object
+ *
+ * @throws {Error} If the bytes cannot be decoded or parsed as valid JSON
+ *
+ * @example
+ * ```typescript
+ * const layoutBytes = await createSingleBlockLayout(fileData);
+ * const layout = parseLayoutFile(layoutBytes);
+ * console.log('Transfer length:', layout.transfer_length);
+ * console.log('Symbol size:', layout.symbol_size);
+ * console.log('Number of source blocks:', layout.num_source_blocks);
+ * ```
+ */
+function parseLayoutFile(layoutBytes) {
+    try {
+        const layoutJson = new TextDecoder('utf-8').decode(layoutBytes);
+        return JSON.parse(layoutJson);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse layout file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Derives a sequence of layout IDs according to LEP-1 specification.
+ *
+ * This function generates a deterministic sequence of layout IDs by:
+ * 1. Creating layout_with_signature = Base64(layout_file) + "." + Base64(layout_signature)
+ * 2. For each index i in [0, rq_ids_max):
+ *    - counter_i = rq_ids_ic + i
+ *    - layout_id_i = Base58(BLAKE3(zstd(layout_with_signature + "." + decimal(counter_i))))
+ *
+ * @param layoutFileB64 - The RaptorQ layout file as a Base64 string
+ * @param layoutSignatureB64 - The cryptographic signature over the layout data as a Base64 string
+ * @param rq_ids_ic - The initial counter value from blockchain action parameters
+ * @param rq_ids_max - The number of layout IDs to generate
+ * @returns A promise resolving to an array of Base58-encoded layout IDs
+ *
+ * @throws {Error} If rq_ids_max is zero or negative
+ * @throws {Error} If layoutFile or layoutSignature is empty
+ *
+ * @remarks
+ * - The derivation is deterministic and must match on-chain validation
+ * - LEP-1 specifies count=50 for standard Cascade uploads
+ * - Uses zstd compression, BLAKE3 hashing, and Base58 encoding
+ *
+ * @example
+ * ```typescript
+ * const layoutFile = new Uint8Array([...]);
+ * const layoutSignature = new Uint8Array([...]);
+ * const layoutIds = await generateIds(layoutFile, layoutSignature, 1000, 50);
+ * console.log('First ID:', layoutIds[0]);
+ * console.log('Last ID:', layoutIds[49]);
+ * ```
+ */
+async function generateIds(layoutFileB64, layoutSignatureB64, rq_ids_ic, rq_ids_max) {
+    // Validate inputs
+    if (rq_ids_max <= 0) {
+        throw new Error(`rq_ids_max must be positive, got ${rq_ids_max}`);
+    }
+    if (layoutFileB64.length === 0) {
+        throw new Error("layoutFile must not be empty");
+    }
+    if (layoutSignatureB64.length === 0) {
+        throw new Error("layoutSignature must not be empty");
+    }
+    // Create layout_with_signature = Base64(layout_file) + "." + Base64(layout_signature)
+    const layoutWithSignature = `${layoutFileB64}.${layoutSignatureB64}`;
+    // Generate layout IDs
+    const layoutIds = [];
+    for (let i = 0; i < rq_ids_max; i++) {
+        const counter = rq_ids_ic + i;
+        // Create the input string: layout_with_signature + "." + counter
+        const input = `${layoutWithSignature}.${counter}`;
+        // Compress with zstd
+        const compressed = await (0, zstd_js_1.compress)(input);
+        // Hash with BLAKE3 (get bytes directly for Base58 encoding)
+        const hashBytes = await (0, hash_js_1.blake3HashBytes)(compressed);
+        // Encode with Base58
+        const layoutId = bs58_1.default.encode(hashBytes);
+        layoutIds.push(layoutId);
+    }
+    return layoutIds;
+}
+/**
+ * Constructs the index file for a LEP-1 Cascade upload.
+ *
+ * The index file contains metadata about the RaptorQ layout and includes
+ * a cryptographic signature to ensure data integrity. It must be serialized
+ * using canonical JSON when computing signatures or transmitting to the chain.
+ *
+ * @param layout_ids - Array of derived layout IDs (typically 50 for LEP-1)
+ * @param layout_signature - Cryptographic signature over the layout data (Base64-encoded bytes)
+ * @returns The constructed index file object
+ *
+ * @throws {Error} If layout_ids is empty
+ * @throws {Error} If layout_signature is empty
+ *
+ * @remarks
+ * - The version is currently fixed at 1 per LEP-1 specification
+ * - layout_ids must be derived using {@link generateIds}
+ * - layout_signature is computed by signing the canonical JSON bytes of the layout
+ *   using ADR-036 signArbitrary with the uploader's wallet
+ * - The index file must be serialized deterministically (canonical JSON) for on-chain verification
+ *
+ * @example
+ * ```typescript
+ * // Typical LEP-1 workflow
+ * const layoutIds = await generateIds(layoutFile, layoutSignature, rq_ids_ic, rq_ids_max);
+ *
+ * // Sign the layout (done by wallet via ADR-036 signArbitrary)
+ * const layoutBytes = canonicalJsonBytes(layout);
+ * const signature = await wallet.signArbitrary(chainId, signerAddress, layoutBytes);
+ * const signatureBytes = fromBase64(signature.signature);
+ *
+ * // Build the index file
+ * const indexFile = buildIndexFile(layoutIds, signatureBytes);
+ * ```
+ */
+function buildIndexFile(layout_ids, layout_signature) {
+    // Validate inputs
+    if (layout_ids.length === 0) {
+        throw new Error("layout_ids must not be empty");
+    }
+    if (layout_signature.length === 0) {
+        throw new Error("layout_signature must not be empty");
+    }
+    // Construct the index file per LEP-1 specification
+    return {
+        version: 1, // LEP-1 version
+        layout_ids,
+        layout_signature,
+    };
+}

package/dist/cjs/wasm/raptorq-proxy.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * RaptorQ WASM Proxy
+ *
+ * This module provides a proxy layer to the RaptorQ WASM library (rq-library-wasm).
+ * It handles initialization, in-memory filesystem operations, and provides a clean
+ * interface for RaptorQ operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RaptorQProxy = void 0;
+exports.parseLayoutFile = parseLayoutFile;
+exports.writeFileChunk = writeFileChunk;
+exports.readFileChunk = readFileChunk;
+exports.getFileSize = getFileSize;
+exports.createDirAll = createDirAll;
+exports.dirExists = dirExists;
+exports.syncDirExists = syncDirExists;
+exports.flushFile = flushFile;
+// Lazy-load rq-library-wasm to avoid eager evaluation of browser-only code (window)
+let _rqMod = null;
+async function getRqModule() {
+    if (!_rqMod) {
+        // Shim window for Node.js — rq-library-wasm's browser_fs_mem.js expects it
+        if (typeof globalThis.window === "undefined") {
+            globalThis.window = globalThis;
+        }
+        _rqMod = await Promise.resolve().then(() => require("rq-library-wasm"));
+    }
+    return _rqMod;
+}
+async function getWasmSource() {
+    if (typeof window === "undefined") {
+        // Node.js: read the .wasm file from disk as a buffer
+        const { readFileSync } = await Promise.resolve().then(() => require("node:fs"));
+        // Use require.resolve if available (CJS), otherwise createRequire (ESM)
+        let wasmPath;
+        if (typeof require !== "undefined" && typeof require.resolve === "function") {
+            wasmPath = require.resolve("rq-library-wasm/rq_library_bg.wasm");
+        }
+        else {
+            const { createRequire } = await Promise.resolve().then(() => require("node:module"));
+            // @ts-ignore - import.meta.url is only available in ESM
+            const req = createRequire(import.meta.url);
+            wasmPath = req.resolve("rq-library-wasm/rq_library_bg.wasm");
+        }
+        return readFileSync(wasmPath);
+    }
+    else {
+        // Browser: use the Vite ?url import
+        const mod = await Promise.resolve().then(() => require("rq-library-wasm/rq_library_bg.wasm?url"));
+        return mod.default;
+    }
+}
+/**
+ * Proxy to the rq-library-wasm package for RaptorQ operations.
+ *
+ * This class handles initialization of the WASM module and provides a clean API
+ * for creating RaptorQ layouts using in-memory filesystem operations.
+ *
+ * @remarks
+ * The proxy implements the singleton pattern to ensure only one WASM instance
+ * is created. Files are stored in browser's in-memory filesystem before processing.
+ *
+ * @example
+ * ```typescript
+ * const proxy = RaptorQProxy.getInstance();
+ * await proxy.initialize();
+ *
+ * // Create a layout from file data
+ * const layoutBytes = await proxy.createSingleBlockLayout(fileBytes);
+ * ```
+ */
+class RaptorQProxy {
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
+    constructor() {
+        this.initPromise = null;
+        this.initialized = false;
+    }
+    /**
+     * Gets the singleton instance of the RaptorQProxy.
+     *
+     * @returns The RaptorQProxy singleton instance
+     */
+    static getInstance() {
+        if (!RaptorQProxy.instance) {
+            RaptorQProxy.instance = new RaptorQProxy();
+        }
+        return RaptorQProxy.instance;
+    }
+    /**
+     * Resets the singleton instance.
+     *
+     * @remarks
+     * Primarily useful for testing purposes. Should not be used in production code.
+     *
+     * @internal
+     */
+    static resetInstance() {
+        RaptorQProxy.instance = null;
+    }
+    /**
+     * Ensures the WASM module is initialized.
+     *
+     * @remarks
+     * This method is idempotent - multiple calls will only initialize once.
+     *
+     * @private
+     */
+    async ensureInitialized() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = this.initialize();
+        await this.initPromise;
+    }
+    /**
+     * Initializes the WASM module.
+     *
+     * @remarks
+     * This loads the WASM module using the rq-library-wasm package.
+     * The package handles all platform-specific initialization automatically.
+     *
+     * @throws {Error} If the WASM module cannot be loaded
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            // Pass the wasmUrl to the init function for browser environments
+            // The init() function will use the URL to fetch the WASM module
+            const wasmSource = await getWasmSource();
+            const rq = await getRqModule();
+            await rq.default(wasmSource);
+            this.initialized = true;
+        }
+        catch (error) {
+            this.initPromise = null;
+            throw new Error(`Failed to initialize WASM module: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Creates a RaptorQ session with the specified parameters.
+     *
+     * @param symbolSize - Size of each symbol in bytes (default: 65535)
+     * @param redundancyFactor - Redundancy factor for encoding (default: 10)
+     * @param maxMemoryMb - Maximum memory in MB (default: 1024)
+     * @param concurrencyLimit - Concurrency limit (default: 4)
+     * @returns A new RaptorQSession instance
+     *
+     * @throws {Error} If WASM module is not initialized
+     */
+    async createSession(symbolSize = RaptorQProxy.DEFAULT_SYMBOL_SIZE, redundancyFactor = RaptorQProxy.DEFAULT_REDUNDANCY_FACTOR, maxMemoryMb = RaptorQProxy.DEFAULT_MAX_MEMORY_MB, concurrencyLimit = RaptorQProxy.DEFAULT_CONCURRENCY_LIMIT) {
+        await this.ensureInitialized();
+        const rq = await getRqModule();
+        return new rq.RaptorQSession(symbolSize, redundancyFactor, maxMemoryMb, concurrencyLimit);
+    }
+    /**
+     * Creates a single-block RaptorQ layout from file bytes.
+     *
+     * This generates metadata for a file by:
+     * 1. Writing the file bytes to the in-memory filesystem
+     * 2. Creating a RaptorQ session
+     * 3. Calling create_metadata to generate the layout
+     * 4. Reading the layout file from in-memory filesystem
+     * 5. Cleaning up temporary files
+     *
+     * @param fileBytes - The file content as a Uint8Array
+     * @returns A promise that resolves to the raw layout file bytes (JSON format)
+     *
+     * @throws {Error} If layout creation fails
+     *
+     * @remarks
+     * **IMPORTANT**: The file MUST be loaded into in-memory FS before creating RaptorQSession.
+     * This method follows the correct workflow:
+     * - Save file to in-memory FS
+     * - Create session
+     * - Call create_metadata
+     * - Read and return the layout file
+     */
+    async createSingleBlockLayout(fileBytes) {
+        await this.ensureInitialized();
+        // Generate unique temporary paths to avoid conflicts
+        const timestamp = Date.now();
+        const inputPath = `/temp_input_${timestamp}.bin`;
+        const layoutPath = `/temp_layout_${timestamp}.json`;
+        try {
+            const rq = await getRqModule();
+            // Step 1: Write file bytes to in-memory FS
+            // IMPORTANT: File must be in FS before creating session!
+            await rq.writeFileChunk(inputPath, 0, fileBytes);
+            // Step 2: Create a session for metadata generation
+            const session = await this.createSession();
+            // Step 3: Call create_metadata to generate the layout
+            // block_size = 0 means auto-calculate
+            const metadata = await session.create_metadata(inputPath, layoutPath, 0);
+            // Step 4: Read the layout file from in-memory FS
+            const layoutSize = rq.getFileSize(layoutPath);
+            const layoutBytes = await rq.readFileChunk(layoutPath, 0, layoutSize);
+            // Step 5: Clean up
+            session.free();
+            // Note: We could delete the temp files here, but the in-memory FS
+            // will be cleared on page reload anyway
+            return layoutBytes;
+        }
+        catch (error) {
+            throw new Error(`Failed to create RaptorQ layout: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Gets the recommended block size for a given file size.
+     *
+     * @param fileSize - The file size in bytes
+     * @returns The recommended block size
+     *
+     * @throws {Error} If WASM module is not initialized
+     */
+    async getRecommendedBlockSize(fileSize) {
+        await this.ensureInitialized();
+        const session = await this.createSession();
+        const blockSize = session.get_recommended_block_size(fileSize);
+        session.free();
+        return blockSize;
+    }
+    /**
+     * Gets the RaptorQ library version.
+     *
+     * @returns The library version string
+     *
+     * @throws {Error} If WASM module is not initialized
+     */
+    async getVersion() {
+        await this.ensureInitialized();
+        const rq = await getRqModule();
+        return rq.RaptorQSession.version();
+    }
+    /**
+     * Checks if the WASM module is currently initialized.
+     *
+     * @returns True if the module is initialized, false otherwise
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+}
+exports.RaptorQProxy = RaptorQProxy;
+RaptorQProxy.instance = null;
+/**
+ * Default RaptorQ session parameters
+ */
+RaptorQProxy.DEFAULT_SYMBOL_SIZE = 65535; // 64KB - 1
+RaptorQProxy.DEFAULT_REDUNDANCY_FACTOR = 6;
+RaptorQProxy.DEFAULT_MAX_MEMORY_MB = 4096n; // 4GB
+RaptorQProxy.DEFAULT_CONCURRENCY_LIMIT = 1n;
+RaptorQProxy.DEFAULT_BLOCK_SIZE = 1280 * 1024 * 1024; // 1,280 MiB
+/**
+ * Parse layout file bytes into a Layout object.
+ *
+ * @param layoutBytes - The raw layout file bytes (JSON format)
+ * @returns The parsed Layout object
+ * @throws {Error} If parsing fails
+ */
+function parseLayoutFile(layoutBytes) {
+    const text = new TextDecoder().decode(layoutBytes);
+    return JSON.parse(text);
+}
+// Re-export filesystem utilities as lazy async wrappers
+async function writeFileChunk(...args) {
+    const rq = await getRqModule();
+    return rq.writeFileChunk(...args);
+}
+async function readFileChunk(...args) {
+    const rq = await getRqModule();
+    return rq.readFileChunk(...args);
+}
+async function getFileSize(...args) {
+    const rq = await getRqModule();
+    return rq.getFileSize(...args);
+}
+async function createDirAll(...args) {
+    const rq = await getRqModule();
+    return rq.createDirAll(...args);
+}
+async function dirExists(...args) {
+    const rq = await getRqModule();
+    return rq.dirExists(...args);
+}
+async function syncDirExists(...args) {
+    const rq = await getRqModule();
+    return rq.syncDirExists(...args);
+}
+async function flushFile(...args) {
+    const rq = await getRqModule();
+    return rq.flushFile(...args);
+}

package/dist/cjs/wasm/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * WASM Layer Types for LEP-1 Operations
+ *
+ * This module defines the core types used by the WASM layer for RaptorQ
+ * layout generation and LEP-1 (Lumera Enhancement Proposal 1) operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });