@rialo/ts-cdk 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -173,9 +173,21 @@ declare class HttpTransport {
      */
     private makeRequest;
     /**
-     * Handle HTTP error responses
+     * Handle HTTP error responses.
+     *
+     * Parses the response body to extract JSON-RPC error details when available,
+     * regardless of HTTP status code. Falls back to HTTP status-based error handling.
      */
     private handleHttpError;
+    /**
+     * Parse error response body to extract message and RPC error code.
+     *
+     * Handles multiple formats:
+     * - JSON-RPC error: { error: { code, message, data? } }
+     * - Simple JSON: { message: "..." }
+     * - Non-JSON responses
+     */
+    private parseErrorResponse;
     /**
      * Returns the configured RPC endpoint URL.
      */
@@ -203,11 +215,6 @@ interface RialoClientConfig {
      * Can be a preset (RIALO_MAINNET) or a custom object.
      */
     chain: ChainDefinition;
-    /**
-     * Optional: Override the RPC endpoint.
-     * Useful for using QuickNode/Ankr while keeping "Mainnet" identity.
-     */
-    endpoint?: string;
     transport?: HttpTransportConfig;
 }
 
@@ -1253,6 +1260,11 @@ declare class BaseRpcClient {
      * Validate JSON-RPC response structure
      */
     private isValidJsonRpcResponse;
+    /**
+     * Generates the next request ID with Overflow Protection.
+     * @returns The next request ID.
+     */
+    private nextRequestId;
     /**
      * Returns the configured RPC endpoint URL.
      */
@@ -1284,21 +1296,8 @@ interface AccountInfo {
 interface TransactionResponse {
     /** Transaction signature */
     signature: string;
-    /** Slot in which the transaction was processed */
-    slot: bigint;
-    /** Block time (Unix timestamp) */
-    blockTime?: bigint;
-    /** Error message if transaction failed */
-    err?: string;
-}
-/**
- * Signature status.
- */
-interface SignatureStatus {
-    /** Slot in which the transaction was processed */
-    slot: bigint;
-    /** Number of confirmations */
-    confirmations?: number;
+    /** Block height */
+    blockHeight?: bigint;
     /** Error message if transaction failed */
     err?: string;
 }
@@ -1437,6 +1436,42 @@ interface GetTransactionsResponse {
     /** Array of transaction data */
     transactions: Array<Record<string, unknown>>;
 }
+/**
+ * Signature status from the RPC.
+ */
+interface SignatureStatus {
+    /** Slot in which the transaction was processed */
+    slot: bigint;
+    /** Whether the transaction has been executed */
+    executed: boolean;
+    /** Error message if transaction failed */
+    err?: string;
+}
+/**
+ * Options for confirming a transaction.
+ */
+interface ConfirmTransactionOptions {
+    /** Maximum number of retry attempts (default: 30) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+}
+/**
+ * Options for sending and confirming a transaction.
+ */
+interface SendAndConfirmOptions extends SendTransactionOptions, ConfirmTransactionOptions {
+}
+/**
+ * Result of a confirmed transaction.
+ */
+interface ConfirmedTransaction {
+    /** Transaction signature */
+    signature: string;
+    /** Whether the transaction was executed */
+    executed: boolean;
+    /** Error message if transaction failed */
+    err?: string;
+}
 
 /**
  * Main Rialo RPC client for blockchain interactions.
@@ -1477,6 +1512,10 @@ declare class RialoClient {
      * Returns the chain identifier.
      */
     getChainIdentifier(): IdentifierString;
+    /**
+     * Returns the chain configuration.
+     */
+    getChainConfig(): ChainDefinition;
     /**
      * Retrieves the balance of an account in kelvins (smallest unit).
      */
@@ -1533,6 +1572,36 @@ declare class RialoClient {
      * @returns Transaction signature
      */
     requestAirdrop(pubkey: PublicKey, amount: bigint): Promise<string>;
+    /**
+     * Submits a signed transaction and waits for confirmation.
+     *
+     * @param transaction - Serialized signed transaction bytes
+     * @param options - Transaction submission and confirmation options
+     * @returns Confirmed transaction details
+     * @throws {TransactionFailedError} If the transaction fails on-chain
+     * @throws {TransactionConfirmationTimeoutError} If confirmation times out
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sendAndConfirmTransaction(signedTx);
+     * console.log(`Confirmed in slot ${result.slot}`);
+     * ```
+     */
+    sendAndConfirmTransaction(transaction: Uint8Array, options?: SendAndConfirmOptions): Promise<ConfirmedTransaction>;
+    /**
+     * Waits for a transaction to be confirmed.
+     *
+     * @param signature - Transaction signature to monitor
+     * @param options - Confirmation options
+     * @returns Confirmed transaction details
+     */
+    confirmTransaction(signature: string, options?: ConfirmTransactionOptions): Promise<ConfirmedTransaction>;
+    /**
+     * Requests an airdrop and waits for confirmation.
+     *
+     * **Note**: Only available on devnet and testnet.
+     */
+    requestAirdropAndConfirm(pubkey: PublicKey, amount: bigint, options?: ConfirmTransactionOptions): Promise<ConfirmedTransaction>;
 }
 
 /**
@@ -1546,35 +1615,142 @@ declare class RialoClient {
  */
 declare class QueryRpcClient extends BaseRpcClient {
     /**
-     * Get the balance of an account
+     * Retrieve the balance of an account in kelvins (smallest unit).
+     *
+     * @param pubkey - The public key of the account to query
+     * @returns The account balance in kelvins
+     *
+     * @example
+     * ```typescript
+     * const balance = await client.getBalance(publicKey);
+     * console.log(`Balance: ${balance} kelvins`);
+     * ```
      */
     getBalance(pubkey: PublicKey): Promise<bigint>;
     /**
-     * Get detailed information about an account
+     * Retrieve detailed information about an account.
+     *
+     * Returns account data including balance, owner program, stored data,
+     * executable status, and rent epoch.
+     *
+     * @param pubkey - The public key of the account to query
+     * @returns Account information, or null if the account does not exist
+     *
+     * @example
+     * ```typescript
+     * const info = await client.getAccountInfo(publicKey);
+     * if (info) {
+     *   console.log(`Owner: ${info.owner}`);
+     *   console.log(`Balance: ${info.balance} kelvins`);
+     *   console.log(`Data length: ${info.data.length} bytes`);
+     * }
+     * ```
      */
     getAccountInfo(pubkey: PublicKey): Promise<AccountInfo | null>;
     /**
-     * Get the current block height
+     * Retrieve the current block height of the blockchain.
+     *
+     * The block height represents the number of blocks that have been
+     * confirmed on the chain since genesis.
+     *
+     * @returns The current block height
+     *
+     * @example
+     * ```typescript
+     * const height = await client.getBlockHeight();
+     * console.log(`Current block height: ${height}`);
+     * ```
      */
     getBlockHeight(): Promise<bigint>;
     /**
-     * Get detailed information about a transaction
+     * Retrieve detailed information about a confirmed transaction.
+     *
+     * Returns transaction metadata including the block height it was
+     * confirmed in and any execution errors.
+     *
+     * @param signature - The transaction signature to query
+     * @returns Transaction information, or null if the transaction is not found
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.getTransaction(signature);
+     * if (tx) {
+     *   console.log(`Confirmed in block: ${tx.blockHeight}`);
+     *   if (tx.err) {
+     *     console.log(`Transaction failed: ${tx.err}`);
+     *   }
+     * }
+     * ```
      */
     getTransaction(signature: string): Promise<TransactionResponse | null>;
     /**
-     * Get the total number of transactions processed since genesis
+     * Retrieve the total number of transactions processed since genesis.
+     *
+     * @returns The total transaction count
+     *
+     * @example
+     * ```typescript
+     * const count = await client.getTransactionCount();
+     * console.log(`Total transactions: ${count}`);
+     * ```
      */
     getTransactionCount(): Promise<bigint>;
     /**
-     * Get the status of multiple transaction signatures
+     * Retrieve the status of multiple transaction signatures in a single request.
+     *
+     * Useful for batch-checking transaction confirmations. Returns null for
+     * signatures that are not found or have expired from the status cache.
+     *
+     * @param signatures - Array of transaction signatures to query
+     * @returns Array of signature statuses (null if signature not found)
+     *
+     * @example
+     * ```typescript
+     * const statuses = await client.getSignatureStatuses([sig1, sig2, sig3]);
+     * statuses.forEach((status, i) => {
+     *   if (status) {
+     *     console.log(`${signatures[i]}: slot ${status.slot}, executed: ${status.executed}`);
+     *   } else {
+     *     console.log(`${signatures[i]}: not found`);
+     *   }
+     * });
+     * ```
      */
     getSignatureStatuses(signatures: string[]): Promise<(SignatureStatus | null)[]>;
     /**
-     * Get epoch information
+     * Retrieve information about the current epoch.
+     *
+     * Returns epoch metadata including the current epoch number, slot position
+     * within the epoch, total slots per epoch, and current block height.
+     *
+     * @returns Current epoch information
+     *
+     * @example
+     * ```typescript
+     * const info = await client.getEpochInfo();
+     * console.log(`Epoch: ${info.epoch}`);
+     * console.log(`Slot ${info.slotIndex} of ${info.slotsInEpoch}`);
+     * console.log(`Block height: ${info.blockHeight}`);
+     * ```
      */
     getEpochInfo(): Promise<EpochInfoResponse>;
     /**
-     * Get the health status of the node
+     * Check the health status of the RPC node.
+     *
+     * Returns "ok" if the node is healthy. If the node is unhealthy,
+     * returns an error message describing the issue.
+     *
+     * @returns "ok" if healthy, otherwise an error message
+     *
+     * @example
+     * ```typescript
+     * const health = await client.getHealth();
+     * if (health === "ok") {
+     *   console.log("Node is healthy");
+     * } else {
+     *   console.log(`Node unhealthy: ${health}`);
+     * }
+     * ```
      */
     getHealth(): Promise<"ok" | string>;
 }
@@ -1590,13 +1766,117 @@ declare class QueryRpcClient extends BaseRpcClient {
  */
 declare class TransactionRpcClient extends BaseRpcClient {
     /**
-     * Submit a signed transaction to the blockchain
+     * Submit a signed transaction to the blockchain.
+     *
+     * Sends the transaction to the network for processing. The transaction
+     * must be fully signed before submission. Returns immediately with the
+     * transaction signature - use {@link confirmTransaction} or
+     * {@link sendAndConfirmTransaction} to wait for confirmation.
+     *
+     * @param transaction - Serialized signed transaction bytes
+     * @param options - Transaction submission options
+     * @returns Transaction signature (base58 encoded)
+     *
+     * @example
+     * ```typescript
+     * const signature = await client.sendTransaction(signedTx);
+     * console.log(`Submitted: ${signature}`);
+     *
+     * // With options
+     * const signature = await client.sendTransaction(signedTx, {
+     *   skipPreflight: true,
+     *   maxRetries: 3,
+     * });
+     * ```
      */
     sendTransaction(transaction: Uint8Array, options?: SendTransactionOptions): Promise<string>;
     /**
-     * Request an airdrop of tokens to an account (devnet/testnet only)
+     * Wait for a transaction to be confirmed.
+     *
+     * A transaction is considered confirmed when:
+     * - It has been processed in a block (`blockHeight > 0`)
+     *
+     * @param signature - Transaction signature to monitor
+     * @param options - Confirmation options
+     * @returns Confirmed transaction details
+     * @throws {TransactionFailedError} If the transaction fails on-chain
+     * @throws {TransactionConfirmationTimeoutError} If confirmation times out
+     */
+    confirmTransaction(signature: string, options?: ConfirmTransactionOptions): Promise<ConfirmedTransaction>;
+    /**
+     * Submit a signed transaction and wait for confirmation.
+     *
+     * Polls the transaction status until it is confirmed (blockHeight > 0),
+     * or until the maximum number of retries is reached.
+     *
+     * @param transaction - Serialized signed transaction bytes
+     * @param options - Transaction submission and confirmation options
+     * @returns Confirmed transaction details
+     * @throws {TransactionFailedError} If the transaction fails on-chain
+     * @throws {TransactionConfirmationTimeoutError} If confirmation times out
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sendAndConfirmTransaction(signedTx);
+     * console.log(`Confirmed in block ${result.blockHeight}, executed: ${result.executed}`);
+     *
+     * // With custom retry settings
+     * const result = await client.sendAndConfirmTransaction(signedTx, {
+     *   maxRetries: 3,
+     *   retryDelay: 500,
+     * });
+     * ```
+     */
+    sendAndConfirmTransaction(transaction: Uint8Array, options?: SendAndConfirmOptions): Promise<ConfirmedTransaction>;
+    /**
+     * Request an airdrop of tokens to an account.
+     *
+     * **Note**: Only available on devnet and testnet networks.
+     *
+     * Returns immediately with the airdrop transaction signature.
+     * Use {@link requestAirdropAndConfirm} to wait for the airdrop to complete.
+     *
+     * @param pubkey - The public key of the account to receive tokens
+     * @param amount - Amount to airdrop in kelvins (smallest unit)
+     * @returns Airdrop transaction signature
+     *
+     * @example
+     * ```typescript
+     * const signature = await client.requestAirdrop(publicKey, 1_000_000_000n);
+     * console.log(`Airdrop requested: ${signature}`);
+     * ```
      */
     requestAirdrop(pubkey: PublicKey, amount: bigint): Promise<string>;
+    /**
+     * Request an airdrop of tokens and wait for confirmation.
+     *
+     * **Note**: Only available on devnet and testnet networks.
+     *
+     * Combines {@link requestAirdrop} and {@link confirmTransaction} into
+     * a single call for convenience.
+     *
+     * @param pubkey - The public key of the account to receive tokens
+     * @param amount - Amount to airdrop in kelvins (smallest unit)
+     * @param options - Confirmation options (max retries, retry delay)
+     * @returns Confirmed transaction details
+     * @throws {RpcError} If the airdrop transaction fails or confirmation times out
+     *
+     * @example
+     * ```typescript
+     * const result = await client.requestAirdropAndConfirm(publicKey, 1_000_000_000n);
+     * if (result.executed) {
+     *   console.log("Airdrop confirmed!");
+     * }
+     * ```
+     */
+    requestAirdropAndConfirm(pubkey: PublicKey, amount: bigint, options?: ConfirmTransactionOptions): Promise<ConfirmedTransaction>;
+    private getTransaction;
+    /**
+     * Sleeps for a given number of milliseconds.
+     * @param ms - The number of milliseconds to sleep.
+     * @returns A promise that resolves when the sleep is complete.
+     */
+    private sleep;
 }
 
 /**
@@ -1615,6 +1895,7 @@ declare enum RpcErrorCode {
     INTERNAL_ERROR = "INTERNAL_ERROR",
     TRANSACTION_REJECTED = "TRANSACTION_REJECTED",
     INSUFFICIENT_FUNDS = "INSUFFICIENT_FUNDS",
+    TRANSACTION_CONFIRMATION_TIMEOUT = "TRANSACTION_CONFIRMATION_TIMEOUT",
     ACCOUNT_NOT_FOUND = "ACCOUNT_NOT_FOUND",
     RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
     NODE_UNHEALTHY = "NODE_UNHEALTHY"
@@ -1657,40 +1938,11 @@ declare class RpcError extends Error {
     };
 }
 
-/**
- * RPC client module for communicating with Rialo blockchain nodes.
- *
- * Provides a high-level client interface with automatic retry logic,
- * connection management, and type-safe RPC methods.
- *
- * @example
- * ```typescript
- * import { createRialoClient, RIALO_DEVNET_CHAIN } from '@rialo/ts-cdk';
- *
- * // Create client with chain definition and custom transport config
- * const client = createRialoClient({
- *   chain: RIALO_DEVNET_CHAIN,
- *   transport: {
- *     timeout: 30000,
- *     maxRetries: 3,
- *   }
- * });
- *
- * // Query blockchain state
- * const balance = await client.getBalance(publicKey);
- * const blockHeight = await client.getBlockHeight();
- *
- * // Send transactions
- * const signature = await client.sendTransaction(signedTx);
- * ```
- */
-
 /**
  * Creates an RPC client with automatic retry and timeout handling.
  *
  * @param config - Client configuration with chain definition and optional transport settings
- * @param config.chain - Chain definition (e.g., RIALO_DEVNET_CHAIN, RIALO_MAINNET_CHAIN)
- * @param config.endpoint - Optional RPC endpoint override (useful for custom RPC providers)
+ * @param config.chain - Chain definition (e.g., RIALO_DEVNET_CHAIN, RIALO_MAINNET_CHAIN) or a custom chain with your own rpcUrl
  * @param config.transport - Optional transport configuration (timeout, retries, headers)
  * @returns Configured RialoClient instance
  *
@@ -1705,10 +1957,13 @@ declare class RpcError extends Error {
  *   transport: { timeout: 30000, maxRetries: 5 }
  * });
  *
- * // With custom RPC endpoint
+ * // With custom RPC URL
  * const client = createRialoClient({
- *   chain: RIALO_MAINNET_CHAIN,
- *   endpoint: 'https://custom-rpc.example.com'
+ *   chain: {
+ *     id: 'rialo:mainnet',
+ *     name: 'Mainnet',
+ *     rpcUrl: 'https://mainnet.custom-rpc.com:4101'
+ *   },
  * });
  * ```
  */
@@ -1736,11 +1991,14 @@ declare function createRialoClient(config: RialoClientConfig): RialoClient;
  *   transport: { timeout: 60000, maxRetries: 5 }
  * });
  *
- * // Use custom endpoint while preserving network identity
+ * // Use custom RPC URL while preserving network identity
  * const config = getDefaultRialoClientConfig('mainnet');
  * const client = createRialoClient({
  *   ...config,
- *   endpoint: 'https://my-rpc-provider.com'
+ *   chain: {
+ *     ...config.chain,
+ *     rpcUrl: 'https://mainnet.custom-rpc.com:4101'
+ *   },
  * });
  * ```
  */
@@ -1790,4 +2048,4 @@ declare function getMainnetUrl(): string;
  */
 declare function getLocalnetUrl(): string;
 
-export { type AccountInfo, type AccountMeta, AccountMetaTable, BASE_DERIVATION_PATH, BaseRpcClient, type ChainDefinition, type CompiledInstruction, CryptoError, CryptoErrorCode, DEFAULT_NUM_ACCOUNTS, type EpochInfoResponse, type GetConnectedFullNodesResponse, type GetFeeForMessageResponse, type GetHealthResponse, type GetSignaturesForAddressConfig, type GetSignaturesForAddressResponse, type GetSubscriptionsResponse, type GetTransactionsConfig, type GetTransactionsResponse, type GetTriggeredTransactionsResponse, type GetValidatorHealthResponse, type GetWorkflowLineageRequest, type GetWorkflowLineageResponse, HttpTransport, type HttpTransportConfig, type IdentifierString, type Instruction, type IsBlockhashValidResponse, KELVIN_PER_RLO, Keypair, KeypairSigner, Message, type MessageHeader, Mnemonic, type MnemonicStrength, type MultipleAccountsResponse, PUBLIC_KEY_LENGTH, PublicKey, QueryRpcClient, RIALO_DEVNET_CHAIN, RIALO_LOCALNET_CHAIN, RIALO_MAINNET_CHAIN, RIALO_TESTNET_CHAIN, RialoClient, type RialoClientConfig, RialoError, RialoErrorType, type RialoNetwork, RpcError, RpcErrorCode, type RpcErrorDetails$1 as RpcErrorDetails, SECRET_KEY_LENGTH, SIGNATURE_LENGTH, SYSTEM_PROGRAM_ID, type SendTransactionOptions, Signature, type SignatureStatus, type Signer, SystemInstruction, Transaction, TransactionBuilder, TransactionError, TransactionErrorCode, type TransactionResponse, TransactionRpcClient, URL_DEVNET, URL_LOCALNET, URL_MAINNET, URL_TESTNET, calculateBackoff, createAccount, createBorshInstruction, createRialoClient, encodeBorshData, fromBase64, getDefaultRialoClientConfig, getDevnetUrl, getLocalnetUrl, getMainnetUrl, getTestnetUrl, sleep, toBase64, transferInstruction };
+export { type AccountInfo, type AccountMeta, AccountMetaTable, BASE_DERIVATION_PATH, BaseRpcClient, type ChainDefinition, type CompiledInstruction, type ConfirmTransactionOptions, type ConfirmedTransaction, CryptoError, CryptoErrorCode, DEFAULT_NUM_ACCOUNTS, type EpochInfoResponse, type GetConnectedFullNodesResponse, type GetFeeForMessageResponse, type GetHealthResponse, type GetSignaturesForAddressConfig, type GetSignaturesForAddressResponse, type GetSubscriptionsResponse, type GetTransactionsConfig, type GetTransactionsResponse, type GetTriggeredTransactionsResponse, type GetValidatorHealthResponse, type GetWorkflowLineageRequest, type GetWorkflowLineageResponse, HttpTransport, type HttpTransportConfig, type IdentifierString, type Instruction, type IsBlockhashValidResponse, KELVIN_PER_RLO, Keypair, KeypairSigner, Message, type MessageHeader, Mnemonic, type MnemonicStrength, type MultipleAccountsResponse, PUBLIC_KEY_LENGTH, PublicKey, QueryRpcClient, RIALO_DEVNET_CHAIN, RIALO_LOCALNET_CHAIN, RIALO_MAINNET_CHAIN, RIALO_TESTNET_CHAIN, RialoClient, type RialoClientConfig, RialoError, RialoErrorType, type RialoNetwork, RpcError, RpcErrorCode, type RpcErrorDetails$1 as RpcErrorDetails, SECRET_KEY_LENGTH, SIGNATURE_LENGTH, SYSTEM_PROGRAM_ID, type SendAndConfirmOptions, type SendTransactionOptions, Signature, type SignatureStatus, type Signer, SystemInstruction, Transaction, TransactionBuilder, TransactionError, TransactionErrorCode, type TransactionResponse, TransactionRpcClient, URL_DEVNET, URL_LOCALNET, URL_MAINNET, URL_TESTNET, calculateBackoff, createAccount, createBorshInstruction, createRialoClient, encodeBorshData, fromBase64, getDefaultRialoClientConfig, getDevnetUrl, getLocalnetUrl, getMainnetUrl, getTestnetUrl, sleep, toBase64, transferInstruction };