@0xkaleab/sdk-js 0.2.7

package/dist/esm/wasm/lep1.js

@@ -0,0 +1,187 @@
+/**
+ * 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
+ */
+import { RaptorQProxy } from './raptorq-proxy.js';
+import { blake3HashBytes } from './../internal/hash.js';
+import { compress } from './../internal/zstd.js';
+import bs58 from '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);
+ * ```
+ */
+export async function createSingleBlockLayout(fileBytes) {
+    const proxy = 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);
+ * ```
+ */
+export 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]);
+ * ```
+ */
+export 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 compress(input);
+        // Hash with BLAKE3 (get bytes directly for Base58 encoding)
+        const hashBytes = await blake3HashBytes(compressed);
+        // Encode with Base58
+        const layoutId = bs58.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);
+ * ```
+ */
+export 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/esm/wasm/raptorq-proxy.js

@@ -0,0 +1,288 @@
+/**
+ * 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.
+ */
+// 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 import("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 import("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 import("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 import("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);
+ * ```
+ */
+export 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;
+    }
+}
+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
+ */
+export function parseLayoutFile(layoutBytes) {
+    const text = new TextDecoder().decode(layoutBytes);
+    return JSON.parse(text);
+}
+// Re-export filesystem utilities as lazy async wrappers
+export async function writeFileChunk(...args) {
+    const rq = await getRqModule();
+    return rq.writeFileChunk(...args);
+}
+export async function readFileChunk(...args) {
+    const rq = await getRqModule();
+    return rq.readFileChunk(...args);
+}
+export async function getFileSize(...args) {
+    const rq = await getRqModule();
+    return rq.getFileSize(...args);
+}
+export async function createDirAll(...args) {
+    const rq = await getRqModule();
+    return rq.createDirAll(...args);
+}
+export async function dirExists(...args) {
+    const rq = await getRqModule();
+    return rq.dirExists(...args);
+}
+export async function syncDirExists(...args) {
+    const rq = await getRqModule();
+    return rq.syncDirExists(...args);
+}
+export async function flushFile(...args) {
+    const rq = await getRqModule();
+    return rq.flushFile(...args);
+}

package/dist/esm/wasm/types.js

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export {};

package/dist/types/blockchain/adapters/cascade-port.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Adapter implementing CascadeChainPort for blockchain operations.
+ *
+ * This adapter bridges the Cascade layer and the Blockchain layer, providing a
+ * minimal, decoupled interface for Cascade components to access blockchain capabilities.
+ *
+ * @module blockchain/adapters/cascade-port
+ */
+import type { CascadeChainPort, CascadeActionParams, RequestActionTxInput, TxOutcome } from "../../cascade/ports";
+import type { BlockchainClient } from "../interfaces";
+/**
+ * Configuration options for the BlockchainActionAdapter.
+ */
+export interface BlockchainActionAdapterOptions {
+    /**
+     * TTL (Time-To-Live) for cached action parameters in milliseconds.
+     * Default: 300000 (5 minutes)
+     * Set to 0 to disable caching.
+     */
+    paramsCacheTtlMs?: number;
+    /**
+     * Gas price to use for transactions (e.g., "0.025ulume").
+     * If not provided, uses the blockchain client's default.
+     */
+    defaultGasPrice?: string;
+    /**
+     * Safety multiplier for gas estimation.
+     * The simulated gas is multiplied by this factor to account for
+     * state changes between simulation and execution.
+     * Default: 1.3 (30% buffer)
+     */
+    gasMultiplier?: number;
+}
+/**
+ * Adapter implementing CascadeChainPort using a BlockchainClient.
+ *
+ * This adapter:
+ * - Fetches and caches action parameters with a configurable TTL
+ * - Provides a single-call transaction flow (simulate → sign → broadcast)
+ * - Maps blockchain responses to plain DTOs for Cascade
+ *
+ * @example
+ * ```typescript
+ * const adapter = new BlockchainActionAdapter(blockchainClient, signerAddress, {
+ *   paramsCacheTtlMs: 300000, // 5 minutes
+ *   defaultGasPrice: "0.025ulume",
+ *   gasMultiplier: 1.3
+ * });
+ *
+ * // Cascade can now use the adapter
+ * const params = await adapter.getActionParams();
+ * const outcome = await adapter.requestActionTx({
+ *   actionId: 'my-action',
+ *   msg: { data_hash: '...', ... }
+ * });
+ * ```
+ */
+export declare class BlockchainActionAdapter implements CascadeChainPort {
+    private readonly blockchainClient;
+    private readonly signerAddress;
+    private paramsCache;
+    private paramsFetchPromise;
+    private readonly paramsCacheTtlMs;
+    private readonly defaultGasPrice;
+    private readonly gasMultiplier;
+    /**
+     * Create a new blockchain action adapter.
+     *
+     * @param blockchainClient - The blockchain client to use for queries and transactions
+     * @param signerAddress - Address of the account that will sign transactions
+     * @param options - Configuration options
+     */
+    constructor(blockchainClient: BlockchainClient, signerAddress: string, options?: BlockchainActionAdapterOptions);
+    /**
+     * Get action module parameters with TTL caching and single-flight protection.
+     *
+     * This method caches the action parameters for the configured TTL to avoid
+     * repeated LCD queries. If multiple calls are made before the first completes,
+     * they will all wait for and share the same underlying fetch promise (single-flight).
+     *
+     * @returns Action parameters including max_raptor_q_symbols
+     * @throws {Error} If the query fails
+     */
+    getActionParams(): Promise<CascadeActionParams>;
+    /**
+     * Internal method to fetch action parameters from the blockchain.
+     */
+    private fetchActionParams;
+    /**
+     * Request an action transaction (single-call: simulate → sign → broadcast).
+     *
+     * This method orchestrates the complete transaction flow:
+     * 1. Fetches the action fee from the blockchain based on file size
+     * 2. Builds the RequestAction message with the provided payload
+     * 3. Simulates the transaction to get the exact gas required
+     * 4. Calculates the fee based on simulated gas and gas price
+     * 5. Signs the transaction
+     * 6. Broadcasts the transaction
+     * 7. Returns the transaction outcome
+     *
+     * @param input - Transaction input parameters
+     * @param fileSize - Size of the file in bytes
+     * @returns Transaction outcome with hash, height, code, gas, and fee
+     * @throws {Error} If any step fails (simulation, signing, or broadcast)
+     *
+     * @example
+     * ```typescript
+     * const outcome = await adapter.requestActionTx({
+     *   actionId: 'cascade-123',
+     *   msg: {
+     *     data_hash: 'abc...',
+     *     file_name: 'example.txt',
+     *     rq_ids_ic: 100,
+     *     signatures: 'sig...',
+     *     public: false
+     *   }
+     * }, 1024000); // 1MB file
+     *
+     * console.log(`TX ${outcome.txHash} succeeded with code ${outcome.code}`);
+     * ```
+     */
+    requestActionTx(input: RequestActionTxInput, fileSize: number): Promise<TxOutcome>;
+    /**
+     * Invalidate the cached action parameters.
+     *
+     * Forces the next call to getActionParams() to fetch fresh data from the blockchain.
+     * Useful if you know the parameters have changed on-chain.
+     */
+    invalidateCache(): void;
+    /**
+     * Check if the cache is currently valid.
+     *
+     * @returns true if cached params exist and haven't expired, false otherwise
+     */
+    isCacheValid(): boolean;
+    /**
+     * Extract action_id from transaction response.
+     *
+     * Searches for the `action_registered` event in the transaction events
+     * and extracts the `action_id` attribute value.
+     *
+     * @param txResponse - Transaction response from getTx query
+     * @returns The action_id value
+     * @throws {Error} If action_registered event or action_id attribute is not found
+     */
+    private extractActionIdFromTx;
+}