@0xkaleab/sdk-js 0.2.7

package/dist/cjs/cascade/uploader.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * CascadeUploader - High-level API for Cascade file uploads
+ *
+ * This module provides a streamlined interface for uploading files to the
+ * Cascade storage network. It orchestrates the complete upload workflow:
+ *
+ * 1. File preprocessing (hashing, layout generation)
+ * 2. Index file construction per LEP-1 specification
+ * 3. Upload initiation via sn-api
+ * 4. Task monitoring until completion
+ *
+ * @example
+ * ```typescript
+ * const uploader = new CascadeUploader(snapiClient, blockchainParams);
+ *
+ * try {
+ *   const result = await uploader.uploadFile(fileBlob, {
+ *     actionId: 'action-123',
+ *     rq_ids_max: 10000
+ *   });
+ *   console.log('Upload successful:', result);
+ * } catch (error) {
+ *   console.error('Upload failed:', error);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CascadeUploader = void 0;
+const task_1 = require("./task");
+const hash_1 = require("../internal/hash");
+const encoding_1 = require("../internal/encoding");
+const lep1_1 = require("../wasm/lep1");
+const prompter_1 = require("../wallets/prompter");
+/**
+ * CascadeUploader manages the complete file upload workflow.
+ *
+ * This class integrates all components of the storage layer to provide
+ * a simple, high-level API for uploading files to Cascade. It handles:
+ *
+ * - File hashing and integrity verification
+ * - RaptorQ layout generation
+ * - LEP-1 compliant index file construction
+ * - Upload task initiation and monitoring
+ */
+class CascadeUploader {
+    /**
+     * Create a new CascadeUploader instance
+     *
+     * @param client - SNApiClient for making sn-api requests
+     * @param chainPort - Port for accessing blockchain capabilities
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     * @param options - Optional configuration
+     */
+    constructor(client, chainPort, signerAddress, signer, chainId, options = {}) {
+        this.client = client;
+        this.chainPort = chainPort;
+        this.signerAddress = signerAddress;
+        this.signer = signer;
+        this.chainId = chainId;
+    }
+    /**
+     * Step 1: Prepare file for upload
+     *
+     * Converts the file to bytes and calculates its BLAKE3 hash.
+     * This is required before registering an action or creating an auth signature.
+     *
+     * @param file - The file to prepare (as Blob, ArrayBuffer, or Uint8Array)
+     * @returns Promise resolving to prepared file data
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * console.log('File hash:', prepared.dataHash);
+     * ```
+     */
+    async prepareFile(file) {
+        // Step 3: Convert file to bytes
+        const fileBytes = await this.toBytes(file);
+        console.debug('CascadeUploader.prepareFile fileBytes', { length: fileBytes.length });
+        // Step 4: Calculate data_hash using BLAKE3
+        const dataHash = await (0, hash_1.blake3Hash)(fileBytes);
+        console.debug('CascadeUploader.prepareFile dataHash', { dataHash });
+        return { fileBytes, dataHash };
+    }
+    /**
+     * Step 2: Register action on blockchain
+     *
+     * This method performs the complete action registration workflow:
+     * - Fetches action parameters from blockchain
+     * - Generates RaptorQ layout and signs it
+     * - Builds LEP-1 index file and signs it
+     * - Creates auth signature for upload
+     * - Registers the action on-chain via transaction
+     *
+     * @param preparedFile - Result from prepareFile()
+     * @param params - Registration parameters
+     * @returns Promise resolving to registered action details
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * const registered = await uploader.registerAction(prepared, {
+     *   fileName: 'document.pdf',
+     *   isPublic: true,
+     *   expirationTime: '1234567890'
+     * });
+     * ```
+     */
+    async registerAction(preparedFile, params) {
+        const operationStartMs = Date.now();
+        const signaturePrompter = params.signaturePrompter;
+        const prompterWithReset = signaturePrompter;
+        try {
+            const { fileBytes, dataHash } = preparedFile;
+            // Step 1: Get action params from blockchain
+            const actionParams = await this.chainPort.getActionParams();
+            const rq_ids_max = actionParams.max_raptor_q_symbols;
+            console.debug('CascadeUploader.registerAction actionParams', { actionParams });
+            // Step 2: Generate random initial counter for layout ID derivation
+            const rq_ids_ic = Math.floor(Math.random() * rq_ids_max);
+            console.debug('CascadeUploader.registerAction generated rq_ids_ic', { rq_ids_ic });
+            // Step 5: Generate LEP-1 layout using rq-wasm
+            const layoutBytes = await (0, lep1_1.createSingleBlockLayout)(fileBytes);
+            // Remove whitespace from WASM output to match Go's compact json.Marshal()
+            // WASM outputs pretty-printed JSON; we need compact format for signature matching
+            let compactLayoutBytes;
+            let compactLayoutJSON;
+            try {
+                const layoutObj = JSON.parse(new TextDecoder().decode(layoutBytes));
+                compactLayoutJSON = JSON.stringify(layoutObj); // Compact, no whitespace
+                compactLayoutBytes = new TextEncoder().encode(compactLayoutJSON);
+            }
+            catch (error) {
+                throw new Error(`Failed to parse WASM layout output: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const layoutBytesB64 = (0, encoding_1.toBase64)(compactLayoutBytes);
+            console.debug('JS SDK LAYOUT DETAILS (compact JSON):', {
+                rawWasmLength: layoutBytes.length,
+                compactLength: compactLayoutBytes.length,
+                layoutBytesB64,
+                layoutJSON: compactLayoutJSON
+            });
+            console.debug('CascadeUploader.registerAction layoutBytesB64', { layoutBytesB64 });
+            // Sign the layout using wallet (ADR-036 signArbitrary)
+            const layoutSignatureResponse = await this.requestSignature("layout", layoutBytesB64, signaturePrompter, operationStartMs);
+            const layoutSignatureB64 = layoutSignatureResponse.signature;
+            console.debug('CascadeUploader.registerAction layoutSignatureB64', { layoutSignatureB64 });
+            // Step 6: Generate layout IDs using the new algorithm
+            const layoutIds = await (0, lep1_1.generateIds)(layoutBytesB64, layoutSignatureB64, rq_ids_ic, rq_ids_max);
+            console.debug('CascadeUploader.registerAction layoutIds', { layoutIds });
+            // Step 7: Build index_file
+            const indexFile = (0, lep1_1.buildIndexFile)(layoutIds, layoutSignatureB64);
+            const indexFileBytes = (0, encoding_1.toCanonicalJsonBytes)(indexFile);
+            const indexFileB64 = (0, encoding_1.toBase64)(indexFileBytes);
+            const indexFileString = new TextDecoder().decode(indexFileBytes);
+            console.debug('CascadeUploader.registerAction indexFile', { indexFileB64 });
+            const indexSignatureResponse = await this.requestSignature("index", indexFileString, signaturePrompter, operationStartMs);
+            const indexWithSignature = `${indexFileB64}.${indexSignatureResponse.signature}`;
+            console.debug('CascadeUploader.registerAction indexWithSignature', { indexWithSignature });
+            // Step 8: Prepare auth_signature for upload
+            const authSignatureResponse = await this.requestSignature("auth", dataHash, signaturePrompter, operationStartMs);
+            const authSignature = authSignatureResponse.signature;
+            console.debug('CascadeUploader.registerAction authSignature', { authSignature });
+            // Step 9: Register the action on-chain
+            const txOutcome = await this.chainPort.requestActionTx({
+                msg: {
+                    data_hash: dataHash,
+                    file_name: params.fileName,
+                    rq_ids_ic,
+                    signatures: indexWithSignature,
+                    public: params.isPublic,
+                },
+                expirationTime: params.expirationTime,
+                txPrompter: params.txPrompter,
+            }, fileBytes.length);
+            console.debug('CascadeUploader.registerAction tx outcome:', txOutcome);
+            if (!txOutcome.actionId) {
+                throw new Error('Failed to extract action ID from transaction outcome. ' +
+                    'The transaction may not have emitted an action_registered event.');
+            }
+            const actionId = txOutcome.actionId;
+            console.debug('CascadeUploader.registerAction actionId', { actionId });
+            return { actionId, authSignature };
+        }
+        finally {
+            if (prompterWithReset?.reset) {
+                console.debug('CascadeUploader.registerAction invoking signaturePrompter.reset');
+                try {
+                    prompterWithReset.reset();
+                }
+                catch (resetError) {
+                    console.warn('CascadeUploader.registerAction signaturePrompter.reset threw', { resetError });
+                }
+            }
+        }
+    }
+    /**
+     * Create auth signature for an existing action
+     *
+     * This is useful when you already have an action ID and need to create
+     * a new auth signature for uploading the file. Uses a single signature prompt.
+     *
+     * @param actionId - Existing action ID from blockchain
+     * @param dataHash - BLAKE3 hash of file (from prepareFile)
+     * @returns Promise resolving to auth signature (Base64 encoded)
+     *
+     * @example
+     * ```typescript
+     * const prepared = await uploader.prepareFile(fileBlob);
+     * const authSig = await uploader.makeAuthSignature(
+     *   'action-123',
+     *   prepared.dataHash
+     * );
+     * ```
+     */
+    async makeAuthSignature(actionId, dataHash) {
+        const operationStartMs = Date.now();
+        console.debug('CascadeUploader.makeAuthSignature', { actionId, dataHash });
+        // Create a single signature prompter with custom message
+        const singleSignaturePrompter = (0, prompter_1.createDefaultSignaturePrompter)();
+        const authSignatureResponse = await this.requestSignature("auth", dataHash, singleSignaturePrompter, operationStartMs);
+        console.debug('CascadeUploader.makeAuthSignature created', {
+            actionId,
+            signature: authSignatureResponse.signature
+        });
+        return authSignatureResponse.signature;
+    }
+    /**
+     * Step 3: Send file to supernodes
+     *
+     * Initiates the upload via sn-api and monitors the task until completion.
+     *
+     * @param actionId - Action ID from registerAction()
+     * @param authSignature - Auth signature from registerAction() or makeAuthSignature()
+     * @param file - Original file or fileBytes from prepareFile()
+     * @param params - Send parameters
+     * @returns Promise resolving to completed upload task
+     *
+     * @example
+     * ```typescript
+     * const task = await uploader.sendFileToSupernodes(
+     *   registered.actionId,
+     *   registered.authSignature,
+     *   fileBlob,
+     *   { taskOptions: { timeout: 300000 } }
+     * );
+     * ```
+     */
+    async sendFileToSupernodes(actionId, authSignature, file, params = {}) {
+        // Step 10: Convert file to Blob if needed for FormData
+        const fileBytes = await this.toBytes(file);
+        let fileBlob;
+        if (file instanceof Blob) {
+            fileBlob = file;
+        }
+        else {
+            const normalizedBytes = fileBytes.byteOffset === 0 && fileBytes.byteLength === fileBytes.buffer.byteLength
+                ? fileBytes
+                : fileBytes.slice();
+            const copy = new Uint8Array(normalizedBytes);
+            fileBlob = new Blob([copy.buffer], { type: "application/octet-stream" });
+        }
+        console.debug("CascadeUploader.sendFileToSupernodes startCascade", {
+            actionId,
+            inputType: file instanceof Blob ? "Blob" : file.constructor?.name ?? typeof file,
+            blobSize: fileBlob.size,
+            blobType: fileBlob.type || "application/octet-stream",
+        });
+        // Step 11: Initiate upload via sn-api with required fields
+        const response = await this.client.startCascade({
+            actionId,
+            signature: authSignature,
+            file: fileBlob,
+        });
+        console.debug('CascadeUploader.sendFileToSupernodes startCascade response', { response });
+        // Step 12: Monitor upload task until completion
+        const taskManager = new task_1.TaskManager(this.client, response.task_id, params.taskOptions);
+        console.debug('CascadeUploader.sendFileToSupernodes taskManager created', { taskId: response.task_id });
+        const completedTask = await taskManager.waitForCompletion();
+        console.debug('CascadeUploader.sendFileToSupernodes upload completed', { completedTask });
+        return completedTask;
+    }
+    /**
+     * Upload a file to Cascade storage (unified workflow)
+     *
+     * This method orchestrates the complete upload workflow by calling:
+     * 1. prepareFile() - Convert to bytes and hash
+     * 2. registerAction() - Generate layout, register on-chain (handles prompter reset internally)
+     * 3. sendFileToSupernodes() - Upload and monitor
+     *
+     * @param file - The file to upload (as Blob, ArrayBuffer, or Uint8Array)
+     * @param params - Upload parameters
+     * @returns Promise resolving to the completed upload task
+     * @throws {Error} If any step of the upload workflow fails
+     *
+     * @example
+     * ```typescript
+     * const uploader = new CascadeUploader(snapiClient, chainPort);
+     *
+     * const result = await uploader.uploadFile(file, {
+     *   fileName: 'document.pdf',
+     *   isPublic: true,
+     *   expirationTime: '1234567890',
+     *   taskOptions: {
+     *     pollInterval: 2000,
+     *     timeout: 300000
+     *   }
+     * });
+     *
+     * console.log('Upload complete:', result);
+     * ```
+     */
+    async uploadFile(file, params) {
+        // Step 1: Prepare file
+        const preparedFile = await this.prepareFile(file);
+        // Step 2: Register action (handles prompter reset internally)
+        const registeredAction = await this.registerAction(preparedFile, {
+            fileName: params.fileName,
+            isPublic: params.isPublic,
+            expirationTime: params.expirationTime,
+            signaturePrompter: params.signaturePrompter,
+            txPrompter: params.txPrompter,
+        });
+        // Step 3: Send file to supernodes
+        const task = await this.sendFileToSupernodes(registeredAction.actionId, registeredAction.authSignature, file, { taskOptions: params.taskOptions });
+        return task;
+    }
+    async requestSignature(kind, data, prompter, uploadStartMs) {
+        const context = {
+            kind,
+            chainId: this.chainId,
+            signerAddress: this.signerAddress,
+            data,
+        };
+        console.debug('CascadeUploader.uploadFile signature requested', {
+            kind,
+            viaPrompter: Boolean(prompter),
+            elapsedMs: Date.now() - uploadStartMs,
+            chainId: this.chainId,
+            signerAddress: this.signerAddress,
+        });
+        let invoked = false;
+        const sign = async () => {
+            if (invoked) {
+                throw new Error("signArbitrary has already been invoked for this request");
+            }
+            invoked = true;
+            return this.signer.signArbitrary(this.chainId, this.signerAddress, data);
+        };
+        const response = prompter ? await prompter(context, sign) : await sign();
+        console.debug('CascadeUploader.uploadFile signature received', {
+            kind,
+            elapsedMs: Date.now() - uploadStartMs,
+            signerAddress: this.signerAddress,
+        });
+        return response;
+    }
+    /**
+     * Convert various file formats to Uint8Array
+     *
+     * @param file - File in any supported format
+     * @returns Promise resolving to Uint8Array of file contents
+     */
+    async toBytes(file) {
+        if (file instanceof Uint8Array) {
+            return file;
+        }
+        if (file instanceof ArrayBuffer) {
+            return new Uint8Array(file);
+        }
+        // Blob
+        const arrayBuffer = await file.arrayBuffer();
+        return new Uint8Array(arrayBuffer);
+    }
+}
+exports.CascadeUploader = CascadeUploader;

package/dist/cjs/client.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Main LumeraClient facade - unified entry point for the Lumera SDK
+ *
+ * This module provides the top-level client that composes blockchain and storage
+ * operations into a single, user-friendly interface. It handles configuration,
+ * chain presets, and initialization of all underlying clients.
+ *
+ * @module client
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LumeraClient = exports.CHAIN_PRESETS = void 0;
+exports.createLumeraClient = createLumeraClient;
+const client_1 = require("./blockchain/client");
+const cascade_port_1 = require("./blockchain/adapters/cascade-port");
+const http_1 = require("./internal/http");
+const client_2 = require("./cascade/client");
+const uploader_1 = require("./cascade/uploader");
+const downloader_1 = require("./cascade/downloader");
+/**
+ * Predefined chain presets for Lumera networks
+ */
+exports.CHAIN_PRESETS = {
+    testnet: {
+        chainId: "lumera-testnet-2",
+        rpcUrl: "https://rpc.testnet.lumera.io",
+        lcdUrl: "https://lcd.testnet.lumera.io",
+        snapiUrl: "https://snapi.testnet.lumera.io",
+    },
+    mainnet: {
+        chainId: "lumera-mainnet-1",
+        rpcUrl: "https://rpc.lumera.io",
+        lcdUrl: "https://lcd.lumera.io",
+        snapiUrl: "https://snapi.lumera.io",
+    },
+};
+/**
+ * Main LumeraClient facade
+ *
+ * The primary entry point for the Lumera SDK, composing blockchain and storage
+ * operations into a unified interface. This client provides:
+ *
+ * - `Blockchain`: Full blockchain client (transactions and queries)
+ * - `Cascade.uploader`: File upload operations
+ * - `Cascade.downloader`: File download operations
+ *
+ * @example
+ * ```typescript
+ * import { createLumeraClient } from "@lumera-protocol/sdk-js";
+ * import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
+ *
+ * // Create a wallet
+ * const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+ *   prefix: "lumera"
+ * });
+ * const [account] = await wallet.getAccounts();
+ *
+ * // Create the client using testnet preset
+ * const client = await createLumeraClient({
+ *   preset: "testnet",
+ *   signer: wallet,
+ *   address: account.address
+ * });
+ *
+ * // Query blockchain
+ * const params = await client.Blockchain.Action.getParams();
+ *
+ * // Upload a file to Cascade
+ * const result = await client.Cascade.uploader.uploadFile(file, {
+ *   actionId: "action-123",
+ *   rq_ids_ic: 1000,
+ *   rq_ids_max: params.rq_ids_max
+ * });
+ *
+ * // Download a file from Cascade
+ * const stream = await client.Cascade.downloader.download("action-456");
+ * ```
+ */
+class LumeraClient {
+    /**
+     * Create a new LumeraClient instance
+     *
+     * @param blockchain - Initialized blockchain client
+     * @param snapiClient - Initialized SN-API client
+     * @param chainPort - Port for Cascade to access blockchain capabilities
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     *
+     * @remarks
+     * This constructor is typically not called directly. Use the `createLumeraClient`
+     * factory function instead, which handles all initialization automatically.
+     */
+    constructor(blockchain, snapiClient, chainPort, signerAddress, signer, chainId) {
+        this.Blockchain = blockchain;
+        this.Cascade = {
+            uploader: new uploader_1.CascadeUploader(snapiClient, chainPort, signerAddress, signer, chainId),
+            downloader: new downloader_1.CascadeDownloader(snapiClient, signerAddress, signer, chainId),
+        };
+    }
+}
+exports.LumeraClient = LumeraClient;
+/**
+ * Create a new LumeraClient with automatic configuration
+ *
+ * This factory function simplifies client creation by:
+ * - Applying chain presets (testnet/mainnet)
+ * - Initializing all sub-clients
+ * - Configuring HTTP settings
+ * - Connecting to blockchain and storage endpoints
+ *
+ * @param config - Client configuration options
+ * @returns Promise resolving to a fully initialized LumeraClient
+ * @throws {Error} If configuration is invalid or connection fails
+ *
+ * @example
+ * Using a chain preset:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   preset: "testnet",
+ *   signer: wallet,
+ *   address: account.address
+ * });
+ * ```
+ *
+ * @example
+ * Using custom endpoints:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   rpcUrl: "https://custom-rpc.example.com",
+ *   lcdUrl: "https://custom-lcd.example.com",
+ *   chainId: "lumera-custom-1",
+ *   snapiUrl: "https://custom-snapi.example.com",
+ *   signer: wallet,
+ *   address: account.address,
+ *   gasPrice: "0.05ulume"
+ * });
+ * ```
+ *
+ * @example
+ * With custom HTTP settings:
+ * ```typescript
+ * const client = await createLumeraClient({
+ *   preset: "mainnet",
+ *   signer: wallet,
+ *   address: account.address,
+ *   http: {
+ *     timeout: 60000,
+ *     maxRetries: 5
+ *   }
+ * });
+ * ```
+ */
+async function createLumeraClient(config) {
+    // Apply chain preset if specified
+    let chainId;
+    let rpcUrl;
+    let lcdUrl;
+    let snapiUrl;
+    if (config.preset) {
+        const preset = exports.CHAIN_PRESETS[config.preset];
+        chainId = config.chainId ?? preset.chainId;
+        rpcUrl = config.rpcUrl ?? preset.rpcUrl;
+        lcdUrl = config.lcdUrl ?? preset.lcdUrl;
+        snapiUrl = config.snapiUrl ?? preset.snapiUrl;
+    }
+    else {
+        // Require essential endpoints if no preset is specified (lcdUrl is optional)
+        if (!config.rpcUrl || !config.chainId || !config.snapiUrl) {
+            throw new Error("Either 'preset' or all of 'rpcUrl', 'chainId', and 'snapiUrl' must be provided");
+        }
+        chainId = config.chainId;
+        rpcUrl = config.rpcUrl;
+        lcdUrl = config.lcdUrl;
+        snapiUrl = config.snapiUrl;
+    }
+    console.debug(`Creating LumeraClient for chainId=${chainId}, rpcUrl=${rpcUrl}, lcdUrl=${lcdUrl ?? 'none'}, snapiUrl=${snapiUrl}`);
+    // Initialize WASM bridge
+    console.debug(`Initializing WASM proxy`);
+    const { RaptorQProxy } = await Promise.resolve().then(() => require('./wasm/raptorq-proxy.js'));
+    const proxy = RaptorQProxy.getInstance();
+    await proxy.initialize();
+    console.debug("WASM bridge initialized");
+    // Initialize blockchain client
+    const blockchain = await (0, client_1.makeBlockchainClient)({
+        rpcUrl,
+        lcdUrl,
+        chainId,
+        signer: config.signer,
+        address: config.address,
+        gasPrice: config.gasPrice ?? "0.025ulume",
+    });
+    console.debug("Blockchain client initialized");
+    console.debug("Initializing SN-API client");
+    // Initialize HTTP client for sn-api
+    const httpClient = new http_1.HttpClient({
+        baseUrl: snapiUrl,
+        timeout: config.http?.timeout ?? 30000,
+        retry: {
+            maxAttempts: config.http?.maxRetries ?? 3,
+        },
+    });
+    // Initialize SN-API client
+    const snapiClient = new client_2.SNApiClient(httpClient);
+    console.debug("SN-API client initialized");
+    console.debug("Creating Cascade blockchain adapter");
+    // Create blockchain adapter for Cascade operations
+    const chainPort = new cascade_port_1.BlockchainActionAdapter(blockchain, config.address, {
+        paramsCacheTtlMs: 300000, // 5 minutes
+        defaultGasPrice: config.gasPrice ?? "0.025ulume",
+        gasMultiplier: 1.3, // 30% gas buffer
+    });
+    console.debug("Cascade blockchain adapter created");
+    console.debug("Creating LumeraClient instance");
+    // Cast signer to UniversalSigner (assumes it implements signArbitrary)
+    const universalSigner = config.signer;
+    // Create and return the unified client
+    return new LumeraClient(blockchain, snapiClient, chainPort, config.address, universalSigner, chainId);
+}

package/dist/cjs/codegen/amino/amino.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/codegen/amino/bundle.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.amino = void 0;
+// @ts-nocheck
+/* eslint-disable */
+const _216 = require("./amino");
+exports.amino = {
+    ..._216
+};