@0xkaleab/sdk-js 0.2.7

package/dist/types/blockchain/messages.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Transaction message utilities for Lumera blockchain.
+ *
+ * This module provides utility functions for transaction message handling.
+ * For building messages, use the Telescope-generated message composers:
+ *
+ * ```typescript
+ * import { lumera } from '@lumera-protocol/sdk-js';
+ *
+ * // Action messages
+ * lumera.action.v1.MessageComposer.withTypeUrl.requestAction({...});
+ * lumera.action.v1.MessageComposer.withTypeUrl.finalizeAction({...});
+ *
+ * // Supernode messages
+ * lumera.supernode.v1.MessageComposer.withTypeUrl.registerSupernode({...});
+ * ```
+ *
+ * See [`MIGRATION.md`](../../../MIGRATION.md) for complete migration guide.
+ *
+ * @module blockchain/messages
+ */
+import type { EncodeObject } from "@cosmjs/proto-signing";
+/**
+ * Metadata for building a Sense action message.
+ *
+ * This is the input format for constructing MsgRequestAction/MsgFinalizeAction.
+ * Uses `number` types (not `bigint`) as required by protobuf encoding.
+ *
+ * Note: For queried metadata from the blockchain, see `SenseMetadata` in interfaces.ts
+ */
+export interface SenseActionMetadata {
+    /** Data hash - required for RequestAction */
+    data_hash: string;
+    /** DD and fingerprints IC - required for RequestAction */
+    dd_and_fingerprints_ic: number;
+    /** Collection ID - optional for RequestAction */
+    collection_id?: string;
+    /** Group ID - optional for RequestAction */
+    group_id?: string;
+    /** DD and fingerprints max - added by Keeper */
+    dd_and_fingerprints_max?: number;
+    /** DD and fingerprints IDs - required for FinalizeAction */
+    dd_and_fingerprints_ids?: string[];
+    /** Signatures - required for FinalizeAction */
+    signatures?: string;
+}
+/**
+ * Metadata for building a Cascade action message.
+ *
+ * This is the input format for constructing MsgRequestAction/MsgFinalizeAction.
+ * Uses `number` types (not `bigint`) as required by protobuf encoding.
+ *
+ * Note: For queried metadata from the blockchain, see `CascadeMetadata` in interfaces.ts
+ */
+export interface CascadeActionMetadata {
+    /** Data hash - required for RequestAction */
+    data_hash: string;
+    /** File name - required for RequestAction */
+    file_name: string;
+    /** RaptorQ IDs IC - required for RequestAction */
+    rq_ids_ic: number;
+    /** RaptorQ IDs max - added by Keeper */
+    rq_ids_max?: number;
+    /** RaptorQ IDs - required for FinalizeAction */
+    rq_ids_ids?: string[];
+    /** Signatures - required for RequestAction */
+    signatures: string;
+    /** Whether the action is publicly visible */
+    public: boolean;
+}
+/**
+ * Calculate the fee for a Cascade action based on file size.
+ *
+ * Applies ceiling rounding per kilobyte and returns the total fee as a string in uLUME.
+ *
+ * @param fileSizeBytes - File size in bytes
+ * @param feeBase - Base fee component as a string
+ * @param feePerKb - Per-kilobyte fee component as a string
+ * @returns Total fee (base + per-KB component) as a string
+ */
+export declare function calculateCascadeFee(fileSizeBytes: number, feeBase: string, feePerKb: string): string;
+/**
+ * Build a batch of messages for a multi-message transaction.
+ *
+ * Helper function to construct multiple messages that will be included
+ * in a single transaction. Useful for atomic operations.
+ *
+ * @param messages - Array of message builders or EncodeObjects
+ * @returns Array of EncodeObjects ready for signing
+ *
+ * @example
+ * ```typescript
+ * const msgs = buildBatchMessages([
+ *   buildMsgRequestAction(metadata1, price1, expTime1, creator),
+ *   buildMsgRequestAction(metadata2, price2, expTime2, creator),
+ * ]);
+ *
+ * const result = await client.signAndBroadcast(address, msgs, totalFee);
+ * ```
+ */
+export declare function buildBatchMessages(messages: (EncodeObject | (() => EncodeObject))[]): EncodeObject[];
+/**
+ * Estimate gas for a transaction based on message count.
+ *
+ * Provides a rough gas estimate based on the number of messages.
+ * For accurate estimates, use the `simulate` method instead.
+ *
+ * @param messageCount - Number of messages in the transaction
+ * @param baseGas - Base gas amount (default: 100000)
+ * @param gasPerMessage - Gas per additional message (default: 50000)
+ * @returns Estimated gas amount
+ *
+ * @example
+ * ```typescript
+ * const estimatedGas = estimateGas(2); // 2 messages
+ * console.log("Estimated gas:", estimatedGas);
+ * ```
+ */
+export declare function estimateGas(messageCount: number, baseGas?: number, gasPerMessage?: number): number;

package/dist/types/blockchain/registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Registry and Amino types for Lumera blockchain.
+ *
+ * This module re-exports the Telescope-generated registry and Amino type functions
+ * from the codegen directory. For new code, use the generated functions directly
+ * from `../codegen/lumera/client`.
+ *
+ * @module blockchain/registry
+ */
+export { lumeraProtoRegistry, lumeraAminoConverters, getSigningLumeraClientOptions, getSigningLumeraClient, 
+/**
+ * @deprecated Use `getSigningLumeraClientOptions()` from `../codegen/lumera/client` instead.
+ * This provides both registry and aminoTypes in a single call.
+ *
+ * This function will be removed in v2.0.0.
+ *
+ * @example
+ * ```typescript
+ * import { getSigningLumeraClientOptions } from "@lumera-protocol/sdk-js/codegen/lumera/client";
+ *
+ * const { registry, aminoTypes } = getSigningLumeraClientOptions();
+ * const client = await SigningStargateClient.connectWithSigner(
+ *   rpcUrl,
+ *   signer,
+ *   { registry, aminoTypes, gasPrice }
+ * );
+ * ```
+ */
+getSigningLumeraClientOptions as createLumeraRegistry } from "../codegen/lumera/client";

package/dist/types/cascade/client.d.ts

@@ -0,0 +1,202 @@
+import { HttpClient } from "../internal/http";
+import type { operations } from "../types/snapi.gen";
+/**
+ * Request body for starting a Cascade action
+ * Maps to POST /api/v1/actions/cascade
+ */
+export type StartCascadeBody = operations["startCascade"]["requestBody"]["content"]["multipart/form-data"];
+export type StartCascadeFile = StartCascadeBody["file"] | Blob | Uint8Array | ArrayBuffer;
+export type StartCascadeRequest = {
+    actionId: string;
+    signature: string;
+    file?: StartCascadeFile;
+};
+/**
+ * Response from starting a Cascade action
+ */
+export type StartCascadeResponse = operations["startCascade"]["responses"]["202"]["content"]["application/json"];
+/**
+ * Request body for requesting a download
+ * Maps to POST /api/v1/actions/cascade/{action_id}/downloads
+ *
+ * NOTE: The bundled OpenAPI spec in docs/snapi-swagger.json is slightly out of
+ * date and omits this body. The running sn-api (see sn-api-server swagger) expects
+ * a JSON object containing a non-empty `signature` field.
+ */
+export interface RequestDownloadBody {
+    /** Download signature (typically ADR-36 over the action ID) */
+    signature: string;
+}
+/**
+ * Response from requesting a download
+ */
+export type RequestDownloadResponse = operations["requestCascadeDownload"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Task information
+ * Maps to GET /api/v1/actions/cascade/tasks/{task_id}
+ */
+export type Task = operations["getCascadeTask"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Task status information
+ * Maps to GET /api/v1/actions/cascade/tasks/{task_id}/status
+ */
+export type TaskStatus = operations["getCascadeTaskStatus"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Typed REST client for interacting with sn-api endpoints.
+ *
+ * This client provides a thin, type-safe wrapper around the HttpClient
+ * for Cascade storage operations. It maps directly to the sn-api REST
+ * endpoints defined in the OpenAPI specification.
+ *
+ * @example
+ * ```typescript
+ * const httpClient = new HttpClient({ baseUrl: 'https://sn-api.example.com' });
+ * const client = new SNApiClient(httpClient);
+ *
+ * // Start a cascade action
+ * const response = await client.startCascade({ file: fileBlob });
+ * console.log('Task ID:', response.taskId);
+ *
+ * // Check task status
+ * const status = await client.getTaskStatus(response.taskId);
+ * console.log('Status:', status.status);
+ * ```
+ */
+export declare class SNApiClient {
+    private readonly http;
+    /**
+     * Create a new SNApiClient
+     *
+     * @param http - HttpClient instance for making REST requests
+     */
+    constructor(http: HttpClient);
+    /**
+     * Start a new Cascade storage action
+     *
+     * Initiates a new Cascade storage action by uploading a file with required authentication.
+     * Maps to: POST /api/v1/actions/cascade
+     *
+     * @param body - Request body containing the action ID, signature, and file to upload
+     * @returns Promise resolving to the response with task ID
+     * @throws {HttpError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const response = await client.startCascade({
+     *   actionId: 'action-123',
+     *   signature: 'base64_signature',
+     *   file: myFile
+     * });
+     * console.log('Started task:', response.task_id);
+     * ```
+     */
+    startCascade(body: StartCascadeRequest): Promise<StartCascadeResponse>;
+    private normalizeFilePart;
+    /**
+     * Get information about a specific task
+     *
+     * Retrieves detailed information about a Cascade task, including
+     * its status and progress.
+     * Maps to: GET /api/v1/actions/cascade/tasks/{task_id}
+     *
+     * @param taskId - The task ID to query
+     * @returns Promise resolving to task information
+     * @throws {HttpError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const task = await client.getTask('task-456');
+     * console.log('Task status:', task.status);
+     * console.log('Progress:', task.progress);
+     * ```
+     */
+    getTask(taskId: string): Promise<Task>;
+    /**
+     * Get the status of a specific task
+     *
+     * Retrieves just the status information for a Cascade task,
+     * which is lighter weight than getting the full task details.
+     * Maps to: GET /api/v1/actions/cascade/tasks/{task_id}/status
+     *
+     * @param taskId - The task ID to query
+     * @returns Promise resolving to task status
+     * @throws {HttpError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const status = await client.getTaskStatus('task-456');
+     * if (status.status === 'completed') {
+     *   console.log('Task completed!');
+     * }
+     * ```
+     */
+    getTaskStatus(taskId: string): Promise<TaskStatus>;
+    /**
+     * Request a download for a specific Cascade action
+     *
+     * Initiates a download task for a previously stored Cascade action.
+     * Maps to: POST /api/v1/actions/cascade/{action_id}/downloads
+     *
+     * @param actionId - The action ID to download
+     * @param body - Request body (currently unused in spec)
+     * @returns Promise resolving to the response with download task ID
+     * @throws {HttpError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const response = await client.requestDownload('action-123', {});
+     * console.log('Download task:', response.taskId);
+     * ```
+     */
+    requestDownload(actionId: string, body: RequestDownloadBody): Promise<RequestDownloadResponse>;
+    /**
+     * Download the file associated with a task
+     *
+     * Downloads the file data as a ReadableStream for efficient streaming
+     * of large files without loading them entirely into memory.
+     * Maps to: GET /api/v1/downloads/cascade/{task_id}/file
+     *
+     * @param taskId - The task ID to download
+     * @returns Promise resolving to a ReadableStream of the file data
+     * @throws {HttpError} If the request fails
+     *
+     * @example
+     * ```typescript
+     * const stream = await client.downloadFile('task-456');
+     * // Stream can be piped to a file or processed in chunks
+     * const reader = stream.getReader();
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   // Process chunk...
+     * }
+     * ```
+     */
+    downloadFile(taskId: string): Promise<ReadableStream>;
+    /**
+     * Watch download task status via Server-Sent Events (SSE)
+     *
+     * Creates an EventSource connection to monitor task status updates in real-time.
+     * The SSE stream will emit events until the task completes or fails.
+     * Maps to: GET /api/v1/downloads/cascade/{task_id}/status
+     *
+     * @param taskId - The task ID to watch
+     * @returns EventSource instance for receiving status updates
+     *
+     * @example
+     * ```typescript
+     * const eventSource = client.watchDownloadTask('task-456');
+     *
+     * eventSource.addEventListener('sdk:completed', (event) => {
+     *   console.log('Task completed:', event.data);
+     *   eventSource.close();
+     * });
+     *
+     * eventSource.addEventListener('error', (event) => {
+     *   console.error('Task error:', event);
+     *   eventSource.close();
+     * });
+     * ```
+     */
+    watchDownloadTask(taskId: string): EventSource;
+}

package/dist/types/cascade/downloader.d.ts

@@ -0,0 +1,175 @@
+/**
+ * CascadeDownloader - High-level API for Cascade file downloads
+ *
+ * This module provides a streamlined interface for downloading files from the
+ * Cascade storage network. It orchestrates the complete download workflow:
+ *
+ * 1. Authentication signature preparation (for private files)
+ * 2. Download task initiation via sn-api
+ * 3. Task monitoring until file is ready
+ * 4. File stream retrieval
+ *
+ * @example
+ * ```typescript
+ * const downloader = new CascadeDownloader(snapiClient);
+ *
+ * try {
+ *   const stream = await downloader.downloadFile('action-123');
+ *   // Process the stream...
+ *   const reader = stream.getReader();
+ *   while (true) {
+ *     const { done, value } = await reader.read();
+ *     if (done) break;
+ *     // Handle chunk...
+ *   }
+ * } catch (error) {
+ *   console.error('Download failed:', error);
+ * }
+ * ```
+ */
+import type { SNApiClient } from './client';
+import { TaskManagerOptions } from './task';
+import type { UniversalSigner } from '../wallets/signer';
+/**
+ * Parameters for a Cascade download operation
+ */
+export interface DownloadParams {
+    /**
+     * The blockchain action ID to download
+     */
+    actionId: string;
+    /**
+     * Optional task monitoring configuration
+     */
+    taskOptions?: TaskManagerOptions;
+}
+/**
+ * CascadeDownloader manages the complete file download workflow.
+ *
+ * This class integrates the SNApiClient and TaskManager to provide
+ * a simple, high-level API for downloading files from Cascade. It handles:
+ *
+ * - Download authentication for private files
+ * - Download task initiation
+ * - Task status monitoring until file is ready
+ * - File stream retrieval
+ *
+ * @remarks
+ * The current implementation uses a simulated signature for `download_auth`.
+ * In production, this should be replaced with a real wallet signature over
+ * the action ID using ADR-036 signArbitrary for private downloads.
+ */
+export declare class CascadeDownloader {
+    private readonly client;
+    private readonly signerAddress;
+    private readonly signer;
+    private readonly chainId;
+    /**
+     * Create a new CascadeDownloader instance
+     *
+     * @param client - SNApiClient for making sn-api requests
+     * @param signerAddress - Bech32 address of the signer
+     * @param signer - Universal signer for signing operations
+     * @param chainId - Chain ID for signing operations
+     */
+    constructor(client: SNApiClient, signerAddress: string, signer: UniversalSigner, chainId: string);
+    /**
+     * Download a file from Cascade storage
+     *
+     * This method orchestrates the complete download workflow:
+     *
+     * 1. Prepares the download_auth signature (for private downloads)
+     * 2. Initiates a download task via sn-api
+     * 3. Monitors the task using SSE until the file is ready
+     * 4. Retrieves and returns the file as a ReadableStream
+     *
+     * The returned stream can be processed incrementally, making it suitable
+     * for large files without loading them entirely into memory.
+     *
+     * @param params - Download parameters including action ID and options
+     * @returns Promise resolving to a ReadableStream of the file data
+     * @throws {Error} If any step of the download workflow fails
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient, signerAddress, signer, chainId);
+     *
+     * // Download a public file
+     * const stream = await downloader.downloadFile({
+     *   actionId: 'action-123'
+     * });
+     *
+     * // Download a private file (requires authentication)
+     * const privateStream = await downloader.downloadFile({
+     *   actionId: 'action-456',
+     *   taskOptions: {
+     *     pollInterval: 2000,
+     *     timeout: 300000
+     *   }
+     * });
+     *
+     * // Process the stream
+     * const reader = stream.getReader();
+     * const chunks: Uint8Array[] = [];
+     *
+     * while (true) {
+     *   const { done, value } = await reader.read();
+     *   if (done) break;
+     *   chunks.push(value);
+     * }
+     *
+     * // Combine chunks into a single Uint8Array
+     * const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+     * const fileData = new Uint8Array(totalLength);
+     * let offset = 0;
+     * for (const chunk of chunks) {
+     *   fileData.set(chunk, offset);
+     *   offset += chunk.length;
+     * }
+     * ```
+     */
+    downloadFile(params: DownloadParams): Promise<ReadableStream>;
+    /**
+     * Convenience method to download a file by action ID
+     *
+     * This is a shorthand for calling downloadFile with just an action ID.
+     * Defaults to public download (no authentication).
+     *
+     * @param actionId - The blockchain action ID to download
+     * @param taskOptions - Optional task monitoring configuration
+     * @returns Promise resolving to a ReadableStream of the file data
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient);
+     * const stream = await downloader.download('action-123');
+     * ```
+     */
+    download(actionId: string, taskOptions?: TaskManagerOptions): Promise<ReadableStream>;
+    /**
+     * Convenience method to download a private file
+     *
+     * This is a shorthand for downloading a file that requires authentication.
+     *
+     * @param actionId - The blockchain action ID to download
+     * @param taskOptions - Optional task monitoring configuration
+     * @returns Promise resolving to a ReadableStream of the file data
+     *
+     * @example
+     * ```typescript
+     * const downloader = new CascadeDownloader(snapiClient);
+     * const stream = await downloader.downloadPrivate('action-456');
+     * ```
+     */
+    downloadPrivate(actionId: string, taskOptions?: TaskManagerOptions): Promise<ReadableStream>;
+    /**
+     * Generate download signature for private file authentication
+     *
+     * Signs the action ID using ADR-036 signArbitrary with the wallet.
+     * This signature authenticates the download request for private files.
+     *
+     * @param actionId - The action ID to sign
+     * @returns Promise resolving to Base64-encoded signature
+     */
+    private simulateDownloadSignature;
+}

package/dist/types/cascade/ports.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Port interface and DTOs for Cascade layer to access blockchain capabilities.
+ *
+ * This interface defines the minimal surface that Cascade components need from the blockchain,
+ * allowing the blockchain layer to evolve independently while keeping Cascade decoupled.
+ *
+ * @module cascade/ports
+ */
+import type { EncodeObject } from '@cosmjs/proto-signing';
+/**
+ * Context for transaction prompt
+ */
+export interface TxPromptContext {
+    messages: readonly EncodeObject[];
+    memo?: string;
+}
+/**
+ * Transaction prompter type - wraps transaction submission in a user gesture
+ */
+export type TxPrompter = (context: TxPromptContext, submit: () => Promise<TxOutcome>) => Promise<TxOutcome>;
+/**
+ * Action module parameters needed for Cascade operations.
+ *
+ * These parameters are fetched from the on-chain action module and cached
+ * to avoid repeated LCD queries.
+ */
+export interface CascadeActionParams {
+    /**
+     * Maximum number of RaptorQ symbols allowed per action.
+     * Used for layout ID derivation in LEP-1.
+     */
+    max_raptor_q_symbols: number;
+}
+/**
+ * Input parameters for requesting an action transaction.
+ */
+export interface RequestActionTxInput {
+    /**
+     * The message payload to include in the transaction
+     */
+    msg: unknown;
+    /**
+     * Expiration time for the action (Unix timestamp in seconds)
+     */
+    expirationTime: string;
+    /**
+     * Optional gas price override (e.g., "0.025ulume")
+     * If not provided, uses the client's default gas price
+     */
+    gasPrice?: string;
+    /**
+     * Optional memo to include in the transaction
+     */
+    memo?: string;
+    /**
+     * Optional transaction prompter for user gesture requirement.
+     * If provided, wraps the signAndBroadcast call in a user gesture.
+     */
+    txPrompter?: TxPrompter;
+}
+/**
+ * Result of a successfully broadcast transaction.
+ *
+ * This DTO is intentionally plain (no CosmJS types) to keep the Cascade layer
+ * decoupled from blockchain implementation details.
+ */
+export interface TxOutcome {
+    /**
+     * Transaction hash (hex string)
+     */
+    txHash: string;
+    /**
+     * Block height where transaction was included
+     */
+    height: string;
+    /**
+     * Response code (0 = success, non-zero = error)
+     */
+    code: number;
+    /**
+     * Actual gas used by the transaction
+     */
+    gasUsed: string;
+    /**
+     * Total fee paid for the transaction
+     */
+    feePaid: string;
+    /**
+     * Raw log output from the transaction (optional)
+     */
+    rawLog?: string;
+    /**
+     * Action ID extracted from transaction events (optional)
+     * Present when transaction registers an action (e.g., MsgRequestAction)
+     */
+    actionId?: string;
+}
+/**
+ * Port interface for Cascade components to access blockchain capabilities.
+ *
+ * This interface is implemented by an adapter in the blockchain layer,
+ * allowing Cascade to remain decoupled from blockchain implementation details.
+ *
+ * @example
+ * ```typescript
+ * // In Cascade uploader
+ * const params = await this.chainPort.getActionParams();
+ * const outcome = await this.chainPort.requestActionTx({
+ *   actionId: 'my-action-123',
+ *   msg: registerActionMsg
+ * });
+ * ```
+ */
+export interface CascadeChainPort {
+    /**
+     * Fetch action module parameters from the blockchain.
+     *
+     * This method is typically cached with a TTL to avoid repeated LCD queries.
+     *
+     * @returns Action parameters including max_raptor_q_symbols
+     * @throws {Error} If the query fails or returns invalid data
+     */
+    getActionParams(): Promise<CascadeActionParams>;
+    /**
+     * Request an action transaction (single-call: simulate → sign → broadcast).
+     *
+     * This method:
+     * 1. Fetches the action fee from the blockchain based on file size
+     * 2. Builds the RegisterAction message with the provided payload
+     * 3. Simulates the transaction to compute the exact gas needed
+     * 4. Calculates the fee based on gas used and gas price
+     * 5. Signs the transaction using the configured signer
+     * 6. Broadcasts the transaction to the network
+     * 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 simulation, signing, or broadcast fails
+     *
+     * @example
+     * ```typescript
+     * const outcome = await chainPort.requestActionTx({
+     *   actionId: 'cascade-upload-123',
+     *   msg: { data_hash: '...', index_file: '...' },
+     *   gasPrice: '0.025ulume'
+     * }, 1024000); // 1MB file
+     *
+     * console.log(`Tx ${outcome.txHash} at height ${outcome.height}`);
+     * ```
+     */
+    requestActionTx(input: RequestActionTxInput, fileSize: number): Promise<TxOutcome>;
+}