@0xkaleab/sdk-js 0.2.7

package/dist/esm/blockchain/adapters/cascade-port.js

@@ -0,0 +1,261 @@
+/**
+ * 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 { lumera } from "../../codegen";
+/**
+ * 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 class BlockchainActionAdapter {
+    /**
+     * 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, signerAddress, options = {}) {
+        this.blockchainClient = blockchainClient;
+        this.signerAddress = signerAddress;
+        this.paramsCache = null;
+        this.paramsFetchPromise = null;
+        this.paramsCacheTtlMs = options.paramsCacheTtlMs ?? 300000; // Default 5 minutes
+        this.defaultGasPrice = options.defaultGasPrice ?? "0.025ulume";
+        this.gasMultiplier = options.gasMultiplier ?? 1.3;
+    }
+    /**
+     * 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
+     */
+    async getActionParams() {
+        const now = Date.now();
+        // Return cached value if still valid
+        if (this.paramsCache && this.paramsCache.expiresAt > now) {
+            return this.paramsCache.value;
+        }
+        // Single-flight: if a fetch is already in progress, wait for it
+        if (this.paramsFetchPromise) {
+            return this.paramsFetchPromise;
+        }
+        // Create new fetch promise
+        this.paramsFetchPromise = this.fetchActionParams()
+            .then((params) => {
+            // Cache the result if TTL > 0
+            if (this.paramsCacheTtlMs > 0) {
+                this.paramsCache = {
+                    value: params,
+                    expiresAt: now + this.paramsCacheTtlMs,
+                };
+            }
+            this.paramsFetchPromise = null;
+            return params;
+        })
+            .catch((error) => {
+            // Clear the promise on error so next call can retry
+            this.paramsFetchPromise = null;
+            throw error;
+        });
+        return this.paramsFetchPromise;
+    }
+    /**
+     * Internal method to fetch action parameters from the blockchain.
+     */
+    async fetchActionParams() {
+        const params = await this.blockchainClient.Action.getParams();
+        // Parse max_raptor_q_symbols from string to number
+        const maxRaptorQSymbols = parseInt(params.max_raptor_q_symbols, 10);
+        if (isNaN(maxRaptorQSymbols) || maxRaptorQSymbols <= 0) {
+            throw new Error(`Invalid max_raptor_q_symbols: ${params.max_raptor_q_symbols}`);
+        }
+        return {
+            max_raptor_q_symbols: maxRaptorQSymbols,
+        };
+    }
+    /**
+     * 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}`);
+     * ```
+     */
+    async requestActionTx(input, fileSize) {
+        // Step 1: Fetch action fee from blockchain based on data size (in KB, rounded up)
+        // Must match supernode-side verification: (bytes + 1023) / 1024.
+        const fileSizeKbs = fileSize > 0 ? Math.ceil(fileSize / 1024) : 0;
+        const feeInfo = await this.blockchainClient.Action.getActionFee(fileSizeKbs);
+        const priceAmount = feeInfo.amount;
+        const metadata = input.msg; // Type assertion for the metadata payload
+        // Step 3: Build the RequestAction message using the new fromPartial API
+        const msg = {
+            typeUrl: '/lumera.action.v1.MsgRequestAction',
+            value: lumera.action.v1.MsgRequestAction.fromPartial({
+                creator: this.signerAddress,
+                actionType: "cascade",
+                metadata: JSON.stringify({
+                    data_hash: metadata.data_hash,
+                    file_name: metadata.file_name,
+                    rq_ids_ic: metadata.rq_ids_ic,
+                    signatures: metadata.signatures,
+                    public: metadata.public,
+                }),
+                price: priceAmount + "ulume",
+                expirationTime: input.expirationTime,
+                fileSizeKbs: fileSizeKbs.toString(),
+            }),
+        };
+        console.log("Built MsgRequestAction:", msg);
+        // Step 4: Simulate to get exact gas
+        const gasEstimate = await this.blockchainClient.Tx.simulate(this.signerAddress, [msg], input.memo);
+        // Apply safety multiplier
+        const gasWithBuffer = BigInt(Math.ceil(Number(gasEstimate) * this.gasMultiplier));
+        console.log(`Simulated gas: ${gasEstimate}, with buffer: ${gasWithBuffer}`);
+        // Step 5: Calculate transaction fee from gas
+        const gasPrice = input.gasPrice ?? this.defaultGasPrice;
+        const gasPriceNum = parseFloat(gasPrice.replace(/[^0-9.]/g, ''));
+        const denom = gasPrice.replace(/[0-9.]/g, '');
+        const txFeeAmount = Math.ceil(Number(gasWithBuffer) * gasPriceNum).toString();
+        console.log(`Calculated tx fee: ${txFeeAmount} ${denom} (gas price: ${gasPrice})`);
+        // Step 6: Sign and broadcast (with optional user gesture via txPrompter)
+        if (!this.blockchainClient.Tx.signAndBroadcast) {
+            throw new Error("Transaction client does not support signAndBroadcast");
+        }
+        // Define the submission function that returns TxOutcome
+        const submit = async () => {
+            const broadcastResult = await this.blockchainClient.Tx.signAndBroadcast(this.signerAddress, [msg], {
+                amount: [{ denom, amount: txFeeAmount }],
+                gas: gasWithBuffer.toString(),
+            }, input.memo ?? "");
+            console.log(`Transaction broadcast successful: ${broadcastResult.txHash}`);
+            // Query the transaction to get the full response with events
+            console.log(`Querying transaction to extract action_id...`);
+            if (!this.blockchainClient.Tx.getTx) {
+                throw new Error("Transaction client does not support getTx");
+            }
+            const txResponse = await this.blockchainClient.Tx.getTx(broadcastResult.txHash);
+            // Extract action_id from the transaction events
+            const actionId = this.extractActionIdFromTx(txResponse);
+            console.log(`Extracted action_id: ${actionId}`);
+            // Map to TxOutcome DTO
+            return {
+                txHash: broadcastResult.txHash,
+                height: broadcastResult.height.toString(),
+                code: broadcastResult.response.code,
+                gasUsed: broadcastResult.response.gasUsed.toString(),
+                feePaid: txFeeAmount,
+                rawLog: broadcastResult.response.rawLog,
+                actionId,
+            };
+        };
+        // Use txPrompter if provided, otherwise submit directly
+        const outcome = input.txPrompter
+            ? await input.txPrompter({
+                messages: [msg],
+                memo: input.memo,
+            }, submit)
+            : await submit();
+        // Step 7: Return the outcome
+        return outcome;
+    }
+    /**
+     * 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() {
+        this.paramsCache = null;
+    }
+    /**
+     * Check if the cache is currently valid.
+     *
+     * @returns true if cached params exist and haven't expired, false otherwise
+     */
+    isCacheValid() {
+        return this.paramsCache !== null && this.paramsCache.expiresAt > Date.now();
+    }
+    /**
+     * 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
+     */
+    extractActionIdFromTx(txResponse) {
+        if (!txResponse.events || txResponse.events.length === 0) {
+            throw new Error("No events found in transaction response");
+        }
+        // Find the action_registered event
+        const actionRegisteredEvent = txResponse.events.find((event) => event.type === "action_registered");
+        if (!actionRegisteredEvent) {
+            throw new Error("action_registered event not found in transaction. " +
+                `Available events: ${txResponse.events.map(e => e.type).join(", ")}`);
+        }
+        // Find the action_id attribute
+        const actionIdAttr = actionRegisteredEvent.attributes.find((attr) => attr.key === "action_id");
+        if (!actionIdAttr) {
+            throw new Error("action_id attribute not found in action_registered event. " +
+                `Available attributes: ${actionRegisteredEvent.attributes.map(a => a.key).join(", ")}`);
+        }
+        return actionIdAttr.value;
+    }
+}

package/dist/esm/blockchain/client.js

@@ -0,0 +1,263 @@
+/**
+ * Blockchain client facade for the Lumera blockchain.
+ *
+ * This module provides the main entry point for blockchain operations, composing
+ * transaction and query clients into a unified interface. It orchestrates CosmJS
+ * for transaction operations and uses RPC-based query clients generated by Telescope
+ * for type-safe module queries.
+ *
+ * @module blockchain/client
+ */
+import { SigningStargateClient, GasPrice, QueryClient, createProtobufRpcClient } from "@cosmjs/stargate";
+import { connectComet } from "@cosmjs/tendermint-rpc";
+import { CosmjsTxClient } from "./cosmjs";
+import { QueryClientImpl as ActionQueryClient } from "../codegen/lumera/action/v1/query.rpc.Query";
+import { QueryClientImpl as SupernodeQueryClient } from "../codegen/lumera/supernode/v1/query.rpc.Query";
+import { getSigningLumeraClientOptions } from "../codegen/lumera/client";
+import { safeJsonStringify } from "../internal/encoding";
+/**
+ * RPC-based Action query client adapter.
+ *
+ * Wraps the generated Telescope RPC query client and adapts it to the ActionQuery interface.
+ * Provides backward compatibility while using the type-safe generated clients internally.
+ */
+class RpcActionQuery {
+    constructor(client) {
+        this.client = client;
+    }
+    async getParams() {
+        const response = await this.client.params({});
+        const params = response.params;
+        return {
+            fee_base: params?.baseActionFee?.amount ?? "0",
+            fee_per_kb: params?.feePerKbyte?.amount ?? "0",
+            max_raptor_q_symbols: params?.maxRaptorQSymbols?.toString() ?? "0",
+        };
+    }
+    async getAction(actionId) {
+        const response = await this.client.getAction({ actionID: actionId });
+        if (!response.action) {
+            throw new Error(`Action not found: ${actionId}`);
+        }
+        const action = response.action;
+        // Decode the metadata bytes as JSON
+        const decodedMetadata = JSON.parse(new TextDecoder().decode(action.metadata));
+        const result = {
+            creator: action.creator,
+            actionID: action.actionID,
+            actionType: action.actionType,
+            metadata: decodedMetadata,
+            price: action.price,
+            expirationTime: Number(action.expirationTime),
+            fileSizeKbs: Number(action.fileSizeKbs),
+            state: action.state,
+            blockHeight: Number(action.blockHeight),
+            superNodes: action.superNodes,
+        };
+        // Convert any BigInt values to strings to prevent precision loss
+        return JSON.parse(safeJsonStringify(result));
+    }
+    async getActionFee(dataSize) {
+        const response = await this.client.getActionFee({ dataSize: dataSize.toString() });
+        return {
+            amount: response.amount ?? "0",
+        };
+    }
+}
+/**
+ * RPC-based Supernode query client adapter.
+ *
+ * Wraps the generated Telescope RPC query client and adapts it to the SupernodeQuery interface.
+ * Now returns generated SuperNode types directly without conversion.
+ */
+class RpcSupernodeQuery {
+    constructor(client) {
+        this.client = client;
+    }
+    async getParams() {
+        const response = await this.client.params({});
+        // Return the params object as-is, since SupernodeParams accepts any fields
+        return response.params ? { ...response.params } : {};
+    }
+    async getSupernode(validatorAddress) {
+        const response = await this.client.getSuperNode({ validatorAddress });
+        if (!response.supernode) {
+            throw new Error(`Supernode not found: ${validatorAddress}`);
+        }
+        return response.supernode;
+    }
+    async getSupernodeByAddress(supernodeAddress) {
+        const response = await this.client.getSuperNodeBySuperNodeAddress({
+            supernodeAddress,
+        });
+        if (!response.supernode) {
+            throw new Error(`Supernode not found: ${supernodeAddress}`);
+        }
+        // Convert any BigInt values to strings to prevent precision loss
+        return JSON.parse(safeJsonStringify(response.supernode));
+    }
+    async listSupernodes() {
+        const response = await this.client.listSuperNodes({});
+        const supernodes = response.supernodes || [];
+        // Convert any BigInt values to strings to prevent precision loss
+        return JSON.parse(safeJsonStringify(supernodes));
+    }
+}
+/**
+ * Helper function to create RPC query clients from an RPC endpoint.
+ *
+ * Creates a direct CometClient connection and instantiates the generated
+ * query clients for the Lumera modules.
+ *
+ * @param rpcEndpoint - The Tendermint RPC endpoint URL
+ * @returns Promise resolving to object containing instantiated query clients
+ */
+async function createQueryClients(rpcEndpoint) {
+    // Create a direct CometClient connection using connectComet
+    const tmClient = await connectComet(rpcEndpoint);
+    // Create a QueryClient wrapper
+    const queryClient = new QueryClient(tmClient);
+    // Create protobuf RPC client
+    const rpc = createProtobufRpcClient(queryClient);
+    // Instantiate generated query clients
+    return {
+        action: new ActionQueryClient(rpc),
+        supernode: new SupernodeQueryClient(rpc),
+    };
+}
+/**
+ * Implementation of BlockchainClient using CosmJS for transactions and RPC for queries.
+ *
+ * This class provides a complete RPC-based blockchain interaction interface, using
+ * CosmJS for transaction signing and broadcasting, and Telescope-generated RPC clients
+ * for type-safe module queries. It serves as the facade for all blockchain operations.
+ */
+export class CosmjsRpcBlockchainClient {
+    /**
+     * Create a new blockchain client instance.
+     *
+     * @param Tx - Transaction client for signing and broadcasting
+     * @param Action - Action module query client
+     * @param Supernode - Supernode module query client
+     * @param chainId - Blockchain network identifier
+     * @param bech32Address - Signer's bech32 address
+     */
+    constructor(Tx, Action, Supernode, chainId, bech32Address) {
+        this.Tx = Tx;
+        this.Action = Action;
+        this.Supernode = Supernode;
+        this.chainId = chainId;
+        this.bech32Address = bech32Address;
+    }
+    /**
+     * Get the chain ID.
+     *
+     * @returns Chain ID (e.g., "lumera-testnet-2")
+     */
+    async getChainId() {
+        return this.chainId;
+    }
+    /**
+     * Get the signer's address.
+     *
+     * @returns Bech32 address of the account associated with this client
+     */
+    async getAddress() {
+        return this.bech32Address;
+    }
+}
+/**
+ * Create a new RPC-based blockchain client.
+ *
+ * This factory function initializes a complete blockchain client using RPC for all
+ * operations. It uses CosmJS for transaction signing and broadcasting via RPC, and
+ * Telescope-generated type-safe RPC clients for all module queries.
+ *
+ * @param opts - Configuration options for the client
+ * @returns Promise resolving to a configured BlockchainClient
+ * @throws {Error} If connection to RPC fails or configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
+ * import { makeBlockchainClient, lumera } from "@lumera-protocol/sdk-js";
+ *
+ * // Create a wallet
+ * const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
+ *   prefix: "lumera"
+ * });
+ * const [account] = await wallet.getAccounts();
+ *
+ * // Create the RPC-based blockchain client
+ * const client = await makeBlockchainClient({
+ *   rpcUrl: "https://rpc.testnet.lumera.io",
+ *   chainId: "lumera-testnet-2",
+ *   signer: wallet,
+ *   address: account.address,
+ *   gasPrice: "0.025ulume"
+ * });
+ *
+ * // Type-safe RPC queries using generated clients
+ * const params = await client.Action.getParams();
+ * console.log("Max RaptorQ Symbols:", params.max_raptor_q_symbols);
+ *
+ * // Build messages using generated MessageComposer
+ * const msg = lumera.action.v1.MessageComposer.withTypeUrl.requestAction({
+ *   creator: account.address,
+ *   actionType: "cascade",
+ *   metadata: JSON.stringify(metadata),
+ *   price: "100000",
+ *   expirationTime: "1735689600"
+ * });
+ *
+ * // Simulate and broadcast a transaction via RPC
+ * const gas = await client.Tx.simulate(account.address, [msg]);
+ * const result = await client.Tx.signAndBroadcast(
+ *   account.address,
+ *   [msg],
+ *   { amount: [{ denom: "ulume", amount: "5000" }], gas: gas.toString() }
+ * );
+ * console.log("TX Hash:", result.txHash);
+ * ```
+ */
+export async function makeBlockchainClient(opts) {
+    // Create registry and amino types with Lumera-specific message types using generated helper
+    const { registry, aminoTypes } = getSigningLumeraClientOptions();
+    console.debug("Created registry and amino types from generated code");
+    console.debug("Connecting to RPC endpoint:", opts.rpcUrl);
+    // Connect to Tendermint RPC via CosmJS SigningStargateClient
+    const signingClient = await SigningStargateClient.connectWithSigner(opts.rpcUrl, opts.signer, {
+        registry,
+        aminoTypes,
+        gasPrice: opts.gasPrice ? GasPrice.fromString(opts.gasPrice) : undefined,
+    });
+    console.debug("Connected to RPC and created SigningStargateClient");
+    // Verify chain ID matches configuration
+    const actualChainId = await signingClient.getChainId();
+    if (actualChainId !== opts.chainId) {
+        throw new Error(`Chain ID mismatch: configured ${opts.chainId}, but RPC reports ${actualChainId}`);
+    }
+    console.debug("Created transaction client");
+    // Create transaction client
+    const txClient = new CosmjsTxClient(signingClient, {
+        gasMultiplier: 1.5,
+    });
+    console.debug("Created transaction client");
+    console.debug("Creating RPC query clients");
+    // Create RPC query clients using a direct CometClient connection
+    const rpcClients = await createQueryClients(opts.rpcUrl);
+    console.debug("Created RPC query clients");
+    console.debug("Wrapping query clients with adapters");
+    // Wrap generated clients with adapter classes for backward compatibility
+    const actionQuery = new RpcActionQuery(rpcClients.action);
+    const supernodeQuery = new RpcSupernodeQuery(rpcClients.supernode);
+    console.debug("Wrapped query clients with adapters");
+    console.debug("Blockchain client creation complete");
+    // Compose into the unified blockchain client facade
+    return new CosmjsRpcBlockchainClient(txClient, actionQuery, supernodeQuery, opts.chainId, opts.address);
+}
+// Export classes and types for direct use if needed
+export { CosmjsTxClient } from "./cosmjs";
+export * from "./interfaces";
+export * from "./messages";
+export * from "./registry";