@rialo/ts-cdk 0.1.3 → 0.1.4

package/dist/index.js

@@ -451,8 +451,8 @@ var RialoError = class _RialoError extends Error {
 
 // src/constants.ts
 var DEFAULT_NUM_ACCOUNTS = 1;
-var URL_MAINNET = "https://mainnet.rialo.io:4100";
-var URL_TESTNET = "https://testnet.rialo.io:4100";
+var URL_MAINNET = "https://mainnet.rialo.io:4101";
+var URL_TESTNET = "https://testnet.rialo.io:4101";
 var URL_DEVNET = "https://devnet.rialo.io:4101";
 var URL_LOCALNET = "http://localhost:4100";
 var RIALO_MAINNET_CHAIN = {
@@ -6603,6 +6603,7 @@ var RpcErrorCode = /* @__PURE__ */ ((RpcErrorCode2) => {
   RpcErrorCode2["INTERNAL_ERROR"] = "INTERNAL_ERROR";
   RpcErrorCode2["TRANSACTION_REJECTED"] = "TRANSACTION_REJECTED";
   RpcErrorCode2["INSUFFICIENT_FUNDS"] = "INSUFFICIENT_FUNDS";
+  RpcErrorCode2["TRANSACTION_CONFIRMATION_TIMEOUT"] = "TRANSACTION_CONFIRMATION_TIMEOUT";
   RpcErrorCode2["ACCOUNT_NOT_FOUND"] = "ACCOUNT_NOT_FOUND";
   RpcErrorCode2["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
   RpcErrorCode2["NODE_UNHEALTHY"] = "NODE_UNHEALTHY";
@@ -6688,7 +6689,7 @@ var RpcError = class _RpcError extends Error {
 // src/rpc/clients/base-client.ts
 var BaseRpcClient = class {
   transport;
-  requestId = 1;
+  requestId = 0;
   constructor(transport) {
     this.transport = transport;
   }
@@ -6698,7 +6699,7 @@ var BaseRpcClient = class {
    * Handles request serialization, response validation, and error mapping.
    */
   async call(method, params = []) {
-    const requestId = this.requestId++;
+    const requestId = this.nextRequestId();
     const request = {
       jsonrpc: "2.0",
       id: requestId,
@@ -6739,6 +6740,14 @@ var BaseRpcClient = class {
     const response = data;
     return response.jsonrpc === "2.0" && typeof response.id === "number" && ("result" in response || "error" in response);
   }
+  /**
+   * Generates the next request ID with Overflow Protection.
+   * @returns The next request ID.
+   */
+  nextRequestId() {
+    this.requestId = (this.requestId + 1) % Number.MAX_SAFE_INTEGER;
+    return this.requestId;
+  }
   /**
    * Returns the configured RPC endpoint URL.
    */
@@ -6801,7 +6810,16 @@ function getLocalnetUrl() {
 // src/rpc/clients/query-client.ts
 var QueryRpcClient = class 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`);
+   * ```
    */
   async getBalance(pubkey) {
     const result = await this.call("getBalance", [
@@ -6810,7 +6828,23 @@ var QueryRpcClient = class extends BaseRpcClient {
     return BigInt(result.value);
   }
   /**
-   * 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`);
+   * }
+   * ```
    */
   async getAccountInfo(pubkey) {
     const result = await this.call("getAccountInfo", [{ address: pubkey.toString(), encoding: "base64" }]);
@@ -6826,14 +6860,42 @@ var QueryRpcClient = class extends BaseRpcClient {
     };
   }
   /**
-   * 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}`);
+   * ```
    */
   async getBlockHeight() {
     const result = await this.call("getBlockHeight", []);
     return BigInt(result);
   }
   /**
-   * 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}`);
+   *   }
+   * }
+   * ```
    */
   async getTransaction(signature) {
     const result = await this.call("getTransaction", [signature]);
@@ -6842,20 +6904,45 @@ var QueryRpcClient = class extends BaseRpcClient {
     }
     return {
       signature,
-      slot: BigInt(result.slot),
-      blockTime: result.blockTime ? BigInt(result.blockTime) : void 0,
-      err: result.err
+      blockHeight: BigInt(result.block_height ?? 0),
+      err: result.err ?? result.meta?.err ?? void 0
     };
   }
   /**
-   * 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}`);
+   * ```
    */
   async getTransactionCount() {
     const result = await this.call("getTransactionCount", []);
     return BigInt(result);
   }
   /**
-   * 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`);
+   *   }
+   * });
+   * ```
    */
   async getSignatureStatuses(signatures) {
     const result = await this.call("getSignatureStatuses", [signatures]);
@@ -6865,13 +6952,26 @@ var QueryRpcClient = class extends BaseRpcClient {
       }
       return {
         slot: BigInt(status.slot),
-        confirmations: status.confirmations,
+        executed: status.executed,
         err: status.err
       };
     });
   }
   /**
-   * 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}`);
+   * ```
    */
   async getEpochInfo() {
     const result = await this.call("getEpochInfo", []);
@@ -6885,7 +6985,22 @@ var QueryRpcClient = class extends BaseRpcClient {
     };
   }
   /**
-   * 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}`);
+   * }
+   * ```
    */
   async getHealth() {
     const result = await this.call("getHealth", []);
@@ -6894,9 +7009,32 @@ var QueryRpcClient = class extends BaseRpcClient {
 };
 
 // src/rpc/clients/transaction-client.ts
+var DEFAULT_MAX_RETRIES = 10;
+var DEFAULT_RETRY_DELAY_MS = 200;
 var TransactionRpcClient = class 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,
+   * });
+   * ```
    */
   async sendTransaction(transaction, options) {
     const base64Tx = toBase64(transaction);
@@ -6912,15 +7050,162 @@ var TransactionRpcClient = class extends BaseRpcClient {
     return signature;
   }
   /**
-   * 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
+   */
+  async confirmTransaction(signature, options) {
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      if (attempt > 0) {
+        await this.sleep(retryDelay);
+      }
+      try {
+        const txInfo = await this.getTransaction(signature);
+        if (!txInfo) {
+          continue;
+        }
+        if (txInfo.err) {
+          return {
+            signature,
+            executed: false,
+            err: txInfo.err
+          };
+        }
+        if (txInfo.blockHeight && txInfo.blockHeight > 0n) {
+          return {
+            signature,
+            executed: true,
+            err: void 0
+          };
+        }
+      } catch (error) {
+        if (error instanceof RpcError && error.code === "TRANSACTION_REJECTED" /* TRANSACTION_REJECTED */) {
+          throw error;
+        }
+      }
+    }
+    throw new RpcError(
+      "TRANSACTION_CONFIRMATION_TIMEOUT" /* TRANSACTION_CONFIRMATION_TIMEOUT */,
+      "Transaction confirmation timed out",
+      {
+        signature,
+        maxRetries
+      }
+    );
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async sendAndConfirmTransaction(transaction, options) {
+    const signature = await this.sendTransaction(transaction, options);
+    return await this.confirmTransaction(signature, options);
+  }
+  /**
+   * 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}`);
+   * ```
    */
   async requestAirdrop(pubkey, amount) {
+    if (amount > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new RpcError(
+        "INVALID_PARAMS" /* INVALID_PARAMS */,
+        `Airdrop amount ${amount} exceeds maximum safe value`
+      );
+    }
     const signature = await this.call("requestAirdrop", [
       pubkey.toString(),
       Number(amount)
     ]);
     return signature;
   }
+  /**
+   * 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!");
+   * }
+   * ```
+   */
+  async requestAirdropAndConfirm(pubkey, amount, options) {
+    const signature = await this.requestAirdrop(pubkey, amount);
+    return await this.confirmTransaction(signature, options);
+  }
+  async getTransaction(signature) {
+    const result = await this.call("getTransaction", [signature]);
+    if (!result) {
+      return null;
+    }
+    return {
+      signature,
+      blockHeight: BigInt(result.block_height ?? 0),
+      err: result.err ?? result.meta?.err ?? void 0
+    };
+  }
+  /**
+   * 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.
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
 };
 
 // src/rpc/clients/client.ts
@@ -6947,6 +7232,12 @@ var RialoClient = class {
   getChainIdentifier() {
     return this.chain.id;
   }
+  /**
+   * Returns the chain configuration.
+   */
+  getChainConfig() {
+    return this.chain;
+  }
   /**
    * Retrieves the balance of an account in kelvins (smallest unit).
    */
@@ -7023,6 +7314,49 @@ var RialoClient = class {
   async requestAirdrop(pubkey, amount) {
     return await this.transactionClient.requestAirdrop(pubkey, amount);
   }
+  /**
+   * 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}`);
+   * ```
+   */
+  async sendAndConfirmTransaction(transaction, options) {
+    return await this.transactionClient.sendAndConfirmTransaction(
+      transaction,
+      options
+    );
+  }
+  /**
+   * Waits for a transaction to be confirmed.
+   *
+   * @param signature - Transaction signature to monitor
+   * @param options - Confirmation options
+   * @returns Confirmed transaction details
+   */
+  async confirmTransaction(signature, options) {
+    return await this.transactionClient.confirmTransaction(signature, options);
+  }
+  /**
+   * Requests an airdrop and waits for confirmation.
+   *
+   * **Note**: Only available on devnet and testnet.
+   */
+  async requestAirdropAndConfirm(pubkey, amount, options) {
+    return await this.transactionClient.requestAirdropAndConfirm(
+      pubkey,
+      amount,
+      options
+    );
+  }
 };
 
 // src/rpc/http-transport.ts
@@ -7124,46 +7458,71 @@ var HttpTransport = class {
     }
   }
   /**
-   * 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.
    */
   async handleHttpError(response, requestDetails, attempt) {
     const status = response.status;
+    const isRetryable = status >= 500 || status === 429;
+    const baseDetails = {
+      ...requestDetails,
+      httpStatus: status,
+      url: this.url,
+      attempts: attempt + 1
+    };
+    const { message, rpcCode, errorData } = await this.parseErrorResponse(
+      response,
+      status
+    );
     if (status === 429) {
       return RpcError.rateLimitExceeded({
-        ...requestDetails,
-        httpStatus: status,
-        url: this.url,
-        attempts: attempt + 1
+        ...baseDetails,
+        serverError: errorData
+      });
+    }
+    if (rpcCode !== void 0) {
+      return RpcError.fromRpcCode(rpcCode, message, {
+        ...baseDetails,
+        serverError: errorData
       });
     }
     if (status >= 500) {
-      return RpcError.networkError(`Server error: ${status}`, {
-        ...requestDetails,
-        httpStatus: status,
-        url: this.url,
-        attempts: attempt + 1
+      return RpcError.networkError(message, {
+        ...baseDetails,
+        serverError: errorData
       });
     }
+    return new RpcError("NETWORK_ERROR" /* NETWORK_ERROR */, message, baseDetails, isRetryable);
+  }
+  /**
+   * 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
+   */
+  async parseErrorResponse(response, status) {
     let message = `HTTP ${status}: ${response.statusText}`;
+    let rpcCode;
+    let errorData;
     try {
-      const errorData = await response.json();
-      if (errorData && typeof errorData === "object" && "message" in errorData) {
-        message = String(errorData.message);
+      errorData = await response.json();
+      if (errorData && typeof errorData === "object") {
+        const data = errorData;
+        if (data.error && typeof data.error === "object" && "message" in data.error) {
+          const rpcError = data.error;
+          message = String(rpcError.message);
+          rpcCode = typeof rpcError.code === "number" ? rpcError.code : void 0;
+        } else if ("message" in data) {
+          message = String(data.message);
+        }
       }
     } catch {
     }
-    return new RpcError(
-      "NETWORK_ERROR" /* NETWORK_ERROR */,
-      message,
-      {
-        ...requestDetails,
-        httpStatus: status,
-        url: this.url,
-        attempts: attempt + 1
-      },
-      false
-      // 4xx errors are not retryable
-    );
+    return { message, rpcCode, errorData };
   }
   /**
    * Returns the configured RPC endpoint URL.
@@ -7175,10 +7534,9 @@ var HttpTransport = class {
 
 // src/rpc/index.ts
 function createRialoClient(config) {
-  const { chain: chain2, endpoint, transport } = config;
-  const url = endpoint ?? chain2.rpcUrl;
-  const httpTransport = new HttpTransport(url, transport);
-  return new RialoClient(httpTransport, config.chain);
+  const { chain: chain2, transport } = config;
+  const httpTransport = new HttpTransport(chain2.rpcUrl, transport);
+  return new RialoClient(httpTransport, chain2);
 }
 function getDefaultRialoClientConfig(network) {
   switch (network) {