@tuwaio/pulsar-solana 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 FOP Tkach Oleksandr
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,162 @@
+# Pulsar Solana Adapter & Toolkit
+
+[](https://www.npmjs.com/package/@tuwaio/pulsar-solana)
+[](https://www.google.com/search?q=./LICENSE)
+[](https://github.com/TuwaIO/pulsar-core/actions)
+
+An advanced toolkit for the Pulsar Engine that adds comprehensive support for tracking transactions on the Solana blockchain. It integrates seamlessly with **`@solana/kit`** and the **`@solana/wallet-adapter-react`** ecosystem.
+
+-----
+
+## 🏛️ What is `@tuwaio/pulsar-solana`?
+
+This package is a powerful, official adapter for `@tuwaio/pulsar-core`. It contains all the necessary logic to interact with the Solana blockchain, acting as the primary logic provider for Solana-based dApps using Pulsar.
+
+While its main export is the `solanaAdapter`, it also includes a suite of standalone trackers and utilities that can be used for advanced or custom implementations. The architecture is designed for robustness, ensuring transactions can be tracked even after a page reload by storing the relevant RPC endpoint within each transaction object.
+
+-----
+
+## ✨ Core Features
+
+- **🔌 Simple Integration:** A single `solanaAdapter` factory function to easily plug full Solana support into `@tuwaio/pulsar-core`.
+- **🛰️ Robust Polling Tracker:** A durable transaction tracker that polls for signature statuses until finality, built on Pulsar's generic polling utility.
+- **🔗 RPC Persistence:** The tracker is designed to be self-contained, storing the `rpcUrl` within each transaction to guarantee tracking can resume after page reloads, independent of the current wallet connection.
+- **🌐 Network Verification:** Includes a utility (`checkSolanaChain`) to robustly verify the connected network via its genesis hash, preventing transactions from being sent to the wrong cluster.
+- **👤 Name Service Support:** Built-in support for **Solana Name Service (SNS)** via Bonfida, allowing for easy resolution of `.sol` domain names and associated avatars.
+- **🛠️ Utility Suite:** Exports a rich set of helpers, including the SNS resolvers (`getSolanaName`, `getSolanaAvatar`) and an explorer link generator (`selectSolanaTxExplorerLink`).
+
+-----
+
+## 💾 Installation
+
+This package is designed for use in a React environment with `@solana/wallet-adapter-react` and requires `@solana/kit`. Install all necessary packages together:
+
+```bash
+# Using pnpm
+pnpm add @tuwaio/pulsar-solana @tuwaio/pulsar-core @solana/kit @solana/wallet-adapter-react zustand immer
+
+# Using npm
+npm install @tuwaio/pulsar-solana @tuwaio/pulsar-core @solana/kit @solana/wallet-adapter-react zustand immer
+
+# Using yarn
+yarn add @tuwaio/pulsar-solana @tuwaio/pulsar-core @solana/kit @solana/wallet-adapter-react zustand immer
+```
+
+-----
+
+## 🚀 Usage
+
+### 1\. Primary Usage: The `solanaAdapter`
+
+For most applications, you'll need to import the `solanaAdapter` and pass it to your `createPulsarStore` configuration. The adapter should be initialized within a React component to access the necessary hooks from `@solana/wallet-adapter-react`.
+
+```tsx
+// src/store/pulsarStore.ts
+import { createPulsarStore } from '@tuwaio/pulsar-core';
+import { solanaAdapter } from '@tuwaio/pulsar-solana';
+import { useConnection, useWallet } from '@solana/wallet-adapter-react';
+import { useMemo } from 'react';
+
+// It's best to create the store instance via a hook to access wallet/connection hooks.
+export const useMyPulsarStore = () => {
+  const wallet = useWallet();
+  const connection = useConnection();
+
+  // useMemo ensures the store is created only once.
+  return useMemo(() => {
+    return createPulsarStore({
+      // A unique name for localStorage persistence
+      name: 'my-solana-dapp-transactions',
+      // Provide the solanaAdapter with the hook contexts
+      adapters: [solanaAdapter({ wallet, connection })],
+      // Optional: Add global callbacks for all successful transactions
+      onSucceedCallbacks: (tx) => {
+        console.log(`Transaction ${tx.txKey} succeeded!`);
+      },
+    });
+  }, [wallet, connection]);
+};
+```
+
+### 2\. Initiating a Transaction
+
+When calling `handleTransaction`, you must now provide the `rpcUrl` for the transaction. This ensures the tracker can function correctly even after a page reload.
+
+```tsx
+// src/components/MyTransactionButton.tsx
+import { usePulsar } from '@tuwaio/pulsar-react'; // Or your custom hook
+import { useConnection } from '@solana/wallet-adapter-react';
+import { TransactionAdapter } from '@tuwaio/pulsar-core';
+
+// An example action that returns a transaction signature
+async function mySolanaAction(): Promise<string> {
+  // ... your logic to build and send a transaction ...
+  const signature = await sendTransaction(...);
+  return signature;
+}
+
+function MyTransactionButton() {
+  const { handleTransaction } = usePulsar();
+  const { connection } = useConnection();
+
+  const handleClick = async () => {
+    await handleTransaction({
+      actionFunction: () => mySolanaAction(),
+      params: {
+        adapter: TransactionAdapter.SOLANA,
+        // The RPC endpoint must be provided for tracking.
+        rpcUrl: connection.rpcEndpoint,
+        desiredChainID: 'mainnet-beta', // The cluster name for the pre-flight check
+        type: 'MY_ACTION',
+        title: 'My Action',
+        description: 'Executing my custom action.',
+      },
+    });
+  };
+
+  return <button onClick={handleClick}>Execute Action</button>;
+}
+```
+
+### 3\. Using Standalone Utilities
+
+You can use exported utilities, like the SNS resolvers, to enrich your UI.
+
+**Example: Displaying a user's .sol domain name**
+
+```tsx
+// src/components/DisplayName.tsx
+import { getSolanaName } from '@tuwaio/pulsar-solana';
+import { useConnection, useWallet } from '@solana/wallet-adapter-react';
+import { useEffect, useState } from 'react';
+
+function DisplayName() {
+  const { publicKey } = useWallet();
+  const connection = useConnection();
+  const [name, setName] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (publicKey && connection) {
+      getSolanaName(connection, publicKey.toBase58()).then(setName);
+    }
+  }, [publicKey, connection]);
+
+  if (!publicKey) return null;
+
+  return <span>{name || publicKey.toBase58()}</span>;
+}
+```
+
+---
+
+## 🤝 Contributing & Support
+
+Contributions are welcome! Please read our main **[Contribution Guidelines](https://github.com/TuwaIO/workflows/blob/main/CONTRIBUTING.md)**.
+
+If you find this library useful, please consider supporting its development. Every contribution helps!
+
+[**➡️ View Support Options**](https://github.com/TuwaIO/workflows/blob/main/Donation.md)
+
+## 📄 License
+
+This project is licensed under the **Apache-2.0 License** - see the [LICENSE](./LICENSE) file for details.

package/dist/index.d.mts

@@ -0,0 +1,179 @@
+import { Transaction, TxAdapter, PollingTrackerConfig, ITxTrackingStore } from '@tuwaio/pulsar-core';
+import { WalletContextState, ConnectionContextState } from '@solana/wallet-adapter-react';
+import { TransactionError } from '@solana/kit';
+
+/**
+ * @file Defines the core types and enums specific to the @tuwaio/pulsar-solana package.
+ */
+
+/**
+ * Defines the possible Solana network clusters.
+ */
+type SolanaCluster = 'mainnet-beta' | 'devnet' | 'testnet';
+/**
+ * Configuration object for the `solanaAdapter`.
+ * All properties are optional and are typically derived from the Solana wallet adapter hooks.
+ *
+ * @property {WalletContextState} [wallet] - The state object from `useWallet()`. Required for actions that need a connected wallet, like signing or retrying transactions.
+ * @property {ConnectionContextState} [connection] - The state object from `useConnection()`. Required for on-chain operations like checking the network or using the Solana Name Service.
+ * @property {string} [explorerUrl] - The base URL for the transaction explorer (e.g., "https://solscan.io"). Defaults to Solscan if not provided.
+ * @property {SolanaCluster} [cluster] - The specific cluster the app is connected to. Used for generating correct explorer links.
+ */
+interface SolanaAdapterConfig {
+    wallet?: WalletContextState;
+    connection?: ConnectionContextState;
+    explorerUrl?: string;
+    cluster?: SolanaCluster;
+}
+/**
+ * Defines the tracker identifiers available in the Solana adapter.
+ */
+declare enum SolanaTransactionTracker {
+    /** The default tracker for monitoring standard Solana transaction signatures. */
+    Solana = "solana"
+}
+/**
+ * Represents the unique key returned by a transaction-creating action on Solana.
+ * For standard Solana transactions, this is always the transaction signature as a base58 string.
+ */
+type SolanaActionTxKey = string;
+
+/**
+ * @file This file contains the factory function for creating the Solana adapter for Pulsar.
+ */
+
+/**
+ * Factory function to create a Solana adapter for Pulsar.
+ * This adapter provides all the necessary logic to interact with the Solana ecosystem,
+ * including wallet interactions, transaction tracking, and name services.
+ *
+ * @param {SolanaAdapterConfig} config - The configuration object, typically derived from Solana wallet adapter hooks.
+ * @returns {TxAdapter} An object conforming to the `TxAdapter` interface.
+ */
+declare function solanaAdapter<T extends Transaction<SolanaTransactionTracker>>(config: SolanaAdapterConfig): TxAdapter<SolanaTransactionTracker, T, SolanaActionTxKey>;
+
+/**
+ * @file This file defines custom error classes for the @tuwaio/pulsar-solana package.
+ */
+
+/**
+ * Thrown when the connected Solana cluster does not match the required cluster for a transaction.
+ *
+ * This allows consuming applications to `catch` this specific error and
+ * implement custom logic, such as prompting the user to switch networks.
+ */
+declare class SolanaChainMismatchError extends Error {
+    /** The name of the error, for easy identification. */
+    name: string;
+    /** The cluster that the transaction requires (e.g., 'mainnet-beta'). */
+    requiredCluster: SolanaCluster;
+    /** The cluster the wallet is currently connected to. */
+    currentCluster: SolanaCluster | string;
+    constructor(requiredCluster: SolanaCluster, currentCluster: SolanaCluster | string);
+}
+
+/**
+ * @file Implements the transaction tracking logic for standard Solana transactions.
+ * It uses a polling mechanism to query the `getSignatureStatuses` RPC method.
+ */
+
+/**
+ * The shape of the status object returned for each signature from `getSignatureStatuses`.
+ * @internal
+ */
+type SolanaSignatureStatusResponse = {
+    slot: bigint;
+    confirmations: number | null;
+    err: TransactionError | null;
+    confirmationStatus: 'processed' | 'confirmed' | 'finalized' | null;
+};
+/**
+ * The parameters for our specific fetcher function.
+ * @internal
+ */
+type SolanaFetcherParams = Parameters<PollingTrackerConfig<SolanaSignatureStatusResponse, Transaction<SolanaTransactionTracker>, SolanaTransactionTracker>['fetcher']>[0];
+/**
+ * A reusable fetcher for `initializePollingTracker` that queries the Solana RPC for a transaction's signature status.
+ * This is the core polling logic that powers the tracker.
+ */
+declare function solanaFetcher({ tx, stopPolling, onSuccess, onFailure, onIntervalTick }: SolanaFetcherParams): Promise<void>;
+/**
+ * A higher-level wrapper that integrates the Solana polling logic with the Pulsar store.
+ * It uses the generic `solanaFetcher` and provides store-specific callbacks.
+ *
+ * @template T - The application-specific transaction type, constrained to Transaction.
+ */
+declare function solanaTrackerForStore<T extends Transaction<SolanaTransactionTracker>>({ tx, ...rest }: Pick<ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'> & {
+    tx: T;
+}): Promise<void>;
+
+/**
+ * @file This file contains the primary router for initializing transaction trackers.
+ */
+
+/**
+ * Initializes the correct background tracker for a given Solana transaction.
+ * This function acts as a router, selecting the appropriate tracker based on the `tx.tracker` property.
+ *
+ * @template T - The transaction type, constrained to Solana transactions.
+ * @param {object} params - The parameters for initializing the tracker.
+ * @param {T} params.tx - The transaction object to be tracked.
+ * @param {SolanaTransactionTracker} params.tracker - The specific tracker to use.
+ * @param {object} params.rest - The rest of the store's methods and state needed by the tracker.
+ * @returns {Promise<void>} A promise that resolves when the tracker has been initialized.
+ */
+declare function checkAndInitializeTrackerInStore<T extends Transaction<SolanaTransactionTracker>>({ tx, tracker, ...rest }: {
+    tx: T;
+    tracker: SolanaTransactionTracker;
+} & Pick<ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'>): Promise<void>;
+
+/**
+ * @file This file contains a utility to robustly verify the Solana cluster by its genesis hash.
+ */
+
+/**
+ * Checks if an RPC endpoint is connected to the required Solana cluster.
+ * It fetches the genesis hash from the RPC endpoint and compares it
+ * with a known hash for the specified cluster.
+ *
+ * @param {string} rpcUrl - The RPC endpoint URL to check.
+ * @param {SolanaCluster} requiredCluster - The cluster that the transaction requires (e.g., 'mainnet-beta').
+ * @throws {SolanaChainMismatchError} If the connected chain does not match the required cluster.
+ * @throws {Error} If the cluster name is unknown or if the RPC call fails for other reasons.
+ */
+declare const checkSolanaChain: (rpcUrl: string, requiredCluster: SolanaCluster) => Promise<void>;
+
+/**
+ * @file This file contains a utility function for generating Solana transaction explorer links.
+ */
+
+/**
+ * Generates a full URL to a transaction on a Solana explorer like Solscan.
+ *
+ * @param {string} baseUrl - The base URL of the explorer (e.g., "https://solscan.io").
+ * @param {string} txKey - The transaction signature (hash).
+ * @param {SolanaCluster} [cluster] - The optional cluster name ('devnet', 'testnet') to add as a query parameter.
+ * @returns {string} The full URL to the transaction on the explorer.
+ */
+declare const selectSolanaTxExplorerLink: (baseUrl: string, txKey: string, cluster?: SolanaCluster) => string;
+
+/**
+ * @file This file contains utility functions for interacting with the Solana Name Service (SNS) provided by Bonfida.
+ */
+
+/**
+ * Performs a reverse lookup to find the .sol domain name for a given wallet address.
+ * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.
+ * @param {string} address - The public key of the wallet as a string.
+ * @returns {Promise<string | null>} The .sol domain name (e.g., "bonfida.sol") or null if not found.
+ */
+declare const getSolanaName: (connection: ConnectionContextState, address: string) => Promise<string | null>;
+/**
+ * Retrieves the avatar URL from the 'pic' record of a .sol domain name.
+ * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.
+ * @param {string} name - The .sol domain name (e.g., "bonfida.sol").
+ * @returns {Promise<string | null>} The URL of the avatar or null if not found or set.
+ */
+declare const getSolanaAvatar: (connection: ConnectionContextState, name: string) => Promise<string | null>;
+
+export { type SolanaActionTxKey, type SolanaAdapterConfig, SolanaChainMismatchError, type SolanaCluster, SolanaTransactionTracker, checkAndInitializeTrackerInStore, checkSolanaChain, getSolanaAvatar, getSolanaName, selectSolanaTxExplorerLink, solanaAdapter, solanaFetcher, solanaTrackerForStore };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+import { Transaction, TxAdapter, PollingTrackerConfig, ITxTrackingStore } from '@tuwaio/pulsar-core';
+import { WalletContextState, ConnectionContextState } from '@solana/wallet-adapter-react';
+import { TransactionError } from '@solana/kit';
+
+/**
+ * @file Defines the core types and enums specific to the @tuwaio/pulsar-solana package.
+ */
+
+/**
+ * Defines the possible Solana network clusters.
+ */
+type SolanaCluster = 'mainnet-beta' | 'devnet' | 'testnet';
+/**
+ * Configuration object for the `solanaAdapter`.
+ * All properties are optional and are typically derived from the Solana wallet adapter hooks.
+ *
+ * @property {WalletContextState} [wallet] - The state object from `useWallet()`. Required for actions that need a connected wallet, like signing or retrying transactions.
+ * @property {ConnectionContextState} [connection] - The state object from `useConnection()`. Required for on-chain operations like checking the network or using the Solana Name Service.
+ * @property {string} [explorerUrl] - The base URL for the transaction explorer (e.g., "https://solscan.io"). Defaults to Solscan if not provided.
+ * @property {SolanaCluster} [cluster] - The specific cluster the app is connected to. Used for generating correct explorer links.
+ */
+interface SolanaAdapterConfig {
+    wallet?: WalletContextState;
+    connection?: ConnectionContextState;
+    explorerUrl?: string;
+    cluster?: SolanaCluster;
+}
+/**
+ * Defines the tracker identifiers available in the Solana adapter.
+ */
+declare enum SolanaTransactionTracker {
+    /** The default tracker for monitoring standard Solana transaction signatures. */
+    Solana = "solana"
+}
+/**
+ * Represents the unique key returned by a transaction-creating action on Solana.
+ * For standard Solana transactions, this is always the transaction signature as a base58 string.
+ */
+type SolanaActionTxKey = string;
+
+/**
+ * @file This file contains the factory function for creating the Solana adapter for Pulsar.
+ */
+
+/**
+ * Factory function to create a Solana adapter for Pulsar.
+ * This adapter provides all the necessary logic to interact with the Solana ecosystem,
+ * including wallet interactions, transaction tracking, and name services.
+ *
+ * @param {SolanaAdapterConfig} config - The configuration object, typically derived from Solana wallet adapter hooks.
+ * @returns {TxAdapter} An object conforming to the `TxAdapter` interface.
+ */
+declare function solanaAdapter<T extends Transaction<SolanaTransactionTracker>>(config: SolanaAdapterConfig): TxAdapter<SolanaTransactionTracker, T, SolanaActionTxKey>;
+
+/**
+ * @file This file defines custom error classes for the @tuwaio/pulsar-solana package.
+ */
+
+/**
+ * Thrown when the connected Solana cluster does not match the required cluster for a transaction.
+ *
+ * This allows consuming applications to `catch` this specific error and
+ * implement custom logic, such as prompting the user to switch networks.
+ */
+declare class SolanaChainMismatchError extends Error {
+    /** The name of the error, for easy identification. */
+    name: string;
+    /** The cluster that the transaction requires (e.g., 'mainnet-beta'). */
+    requiredCluster: SolanaCluster;
+    /** The cluster the wallet is currently connected to. */
+    currentCluster: SolanaCluster | string;
+    constructor(requiredCluster: SolanaCluster, currentCluster: SolanaCluster | string);
+}
+
+/**
+ * @file Implements the transaction tracking logic for standard Solana transactions.
+ * It uses a polling mechanism to query the `getSignatureStatuses` RPC method.
+ */
+
+/**
+ * The shape of the status object returned for each signature from `getSignatureStatuses`.
+ * @internal
+ */
+type SolanaSignatureStatusResponse = {
+    slot: bigint;
+    confirmations: number | null;
+    err: TransactionError | null;
+    confirmationStatus: 'processed' | 'confirmed' | 'finalized' | null;
+};
+/**
+ * The parameters for our specific fetcher function.
+ * @internal
+ */
+type SolanaFetcherParams = Parameters<PollingTrackerConfig<SolanaSignatureStatusResponse, Transaction<SolanaTransactionTracker>, SolanaTransactionTracker>['fetcher']>[0];
+/**
+ * A reusable fetcher for `initializePollingTracker` that queries the Solana RPC for a transaction's signature status.
+ * This is the core polling logic that powers the tracker.
+ */
+declare function solanaFetcher({ tx, stopPolling, onSuccess, onFailure, onIntervalTick }: SolanaFetcherParams): Promise<void>;
+/**
+ * A higher-level wrapper that integrates the Solana polling logic with the Pulsar store.
+ * It uses the generic `solanaFetcher` and provides store-specific callbacks.
+ *
+ * @template T - The application-specific transaction type, constrained to Transaction.
+ */
+declare function solanaTrackerForStore<T extends Transaction<SolanaTransactionTracker>>({ tx, ...rest }: Pick<ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'> & {
+    tx: T;
+}): Promise<void>;
+
+/**
+ * @file This file contains the primary router for initializing transaction trackers.
+ */
+
+/**
+ * Initializes the correct background tracker for a given Solana transaction.
+ * This function acts as a router, selecting the appropriate tracker based on the `tx.tracker` property.
+ *
+ * @template T - The transaction type, constrained to Solana transactions.
+ * @param {object} params - The parameters for initializing the tracker.
+ * @param {T} params.tx - The transaction object to be tracked.
+ * @param {SolanaTransactionTracker} params.tracker - The specific tracker to use.
+ * @param {object} params.rest - The rest of the store's methods and state needed by the tracker.
+ * @returns {Promise<void>} A promise that resolves when the tracker has been initialized.
+ */
+declare function checkAndInitializeTrackerInStore<T extends Transaction<SolanaTransactionTracker>>({ tx, tracker, ...rest }: {
+    tx: T;
+    tracker: SolanaTransactionTracker;
+} & Pick<ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>, 'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'>): Promise<void>;
+
+/**
+ * @file This file contains a utility to robustly verify the Solana cluster by its genesis hash.
+ */
+
+/**
+ * Checks if an RPC endpoint is connected to the required Solana cluster.
+ * It fetches the genesis hash from the RPC endpoint and compares it
+ * with a known hash for the specified cluster.
+ *
+ * @param {string} rpcUrl - The RPC endpoint URL to check.
+ * @param {SolanaCluster} requiredCluster - The cluster that the transaction requires (e.g., 'mainnet-beta').
+ * @throws {SolanaChainMismatchError} If the connected chain does not match the required cluster.
+ * @throws {Error} If the cluster name is unknown or if the RPC call fails for other reasons.
+ */
+declare const checkSolanaChain: (rpcUrl: string, requiredCluster: SolanaCluster) => Promise<void>;
+
+/**
+ * @file This file contains a utility function for generating Solana transaction explorer links.
+ */
+
+/**
+ * Generates a full URL to a transaction on a Solana explorer like Solscan.
+ *
+ * @param {string} baseUrl - The base URL of the explorer (e.g., "https://solscan.io").
+ * @param {string} txKey - The transaction signature (hash).
+ * @param {SolanaCluster} [cluster] - The optional cluster name ('devnet', 'testnet') to add as a query parameter.
+ * @returns {string} The full URL to the transaction on the explorer.
+ */
+declare const selectSolanaTxExplorerLink: (baseUrl: string, txKey: string, cluster?: SolanaCluster) => string;
+
+/**
+ * @file This file contains utility functions for interacting with the Solana Name Service (SNS) provided by Bonfida.
+ */
+
+/**
+ * Performs a reverse lookup to find the .sol domain name for a given wallet address.
+ * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.
+ * @param {string} address - The public key of the wallet as a string.
+ * @returns {Promise<string | null>} The .sol domain name (e.g., "bonfida.sol") or null if not found.
+ */
+declare const getSolanaName: (connection: ConnectionContextState, address: string) => Promise<string | null>;
+/**
+ * Retrieves the avatar URL from the 'pic' record of a .sol domain name.
+ * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.
+ * @param {string} name - The .sol domain name (e.g., "bonfida.sol").
+ * @returns {Promise<string | null>} The URL of the avatar or null if not found or set.
+ */
+declare const getSolanaAvatar: (connection: ConnectionContextState, name: string) => Promise<string | null>;
+
+export { type SolanaActionTxKey, type SolanaAdapterConfig, SolanaChainMismatchError, type SolanaCluster, SolanaTransactionTracker, checkAndInitializeTrackerInStore, checkSolanaChain, getSolanaAvatar, getSolanaName, selectSolanaTxExplorerLink, solanaAdapter, solanaFetcher, solanaTrackerForStore };

package/dist/index.js

@@ -0,0 +1,3 @@
+'use strict';var kit=require('@solana/kit'),pulsarCore=require('@tuwaio/pulsar-core'),u=require('dayjs'),splNameService=require('@bonfida/spl-name-service');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var u__default=/*#__PURE__*/_interopDefault(u);var S=(n=>(n.Solana="solana",n))(S||{});var d=new Map,b=r=>{if(d.has(r))return d.get(r);let n=kit.createSolanaRpc(r);return d.set(r,n),n};async function N({tx:r,stopPolling:n,onSuccess:t,onFailure:a,onIntervalTick:i}){if(r.adapter!==pulsarCore.TransactionAdapter.SOLANA||!r.rpcUrl)throw new Error("RPC URL is missing from the Solana transaction.");let s=(await b(r.rpcUrl).getSignatureStatuses([r.txKey]).send())?.value[0];if(!s)return;let c=s;if(i?.(c),c.err){a(c);return}c.confirmationStatus==="finalized"&&t(c),u__default.default().diff(u__default.default.unix(r.localTimestamp),"minute")>=30&&(n({withoutRemoving:true}),a(c));}async function x({tx:r,...n}){return pulsarCore.initializePollingTracker({tx:r,fetcher:N,removeTxFromPool:n.removeTxFromPool,pollingInterval:2500,maxRetries:720,onSuccess:t=>{n.updateTxParams(r.txKey,{status:pulsarCore.TransactionStatus.Success,pending:false,isError:false,finishedTimestamp:u__default.default().unix(),confirmations:t.confirmations??1,slot:Number(t.slot)});let a=n.transactionsPool[r.txKey];n.onSucceedCallbacks&&a&&n.onSucceedCallbacks(a);},onIntervalTick:t=>{n.updateTxParams(r.txKey,{confirmations:t.confirmations??0,slot:Number(t.slot)});},onFailure:t=>{let a=t?.err?`Transaction failed: ${JSON.stringify(t.err)}`:"Transaction tracking timed out or the transaction was not found.";n.updateTxParams(r.txKey,{status:pulsarCore.TransactionStatus.Failed,pending:false,isError:true,errorMessage:a,finishedTimestamp:u__default.default().unix()});}})}async function y({tx:r,tracker:n,...t}){switch(n){case "solana":await x({tx:r,...t});break;default:console.error(`Unknown tracker type for Solana adapter: ${n}`),t.updateTxParams(r.txKey,{status:pulsarCore.TransactionStatus.Failed,pending:false,isError:true,errorMessage:`Unsupported tracker type: "${n}"`});break}}var m=class extends Error{name="SolanaChainMismatchError";requiredCluster;currentCluster;constructor(n,t){let a=`Wrong network. The transaction requires ${n}, but you are connected to ${t}.`;super(a),this.requiredCluster=n,this.currentCluster=t;}};var k={"mainnet-beta":"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d",devnet:"GH7ome3EiwEr7tu9JuTh2dpYWBJK3z69Xm1ZE3MEE6JC",testnet:"4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY"},h=async(r,n)=>{let t=k[n];if(!t)throw new Error(`Unknown Solana cluster specified: ${n}`);let i=await kit.createSolanaRpc(r).getGenesisHash().send();if(i!==t){let o=Object.entries(k).find(([,e])=>e===i)?.[0]||"an unknown network";throw new m(n,o)}};var C=(r,n,t)=>{let a=r.endsWith("/")?r.slice(0,-1):r,i=t?`?cluster=${t}`:"";return `${a}/tx/${n}${i}`};var f=class{_bn;constructor(n){this._bn=kit.getBase58Encoder().encode(n);}toBuffer(){return Buffer.from(this._bn)}toString(){let[n]=kit.getBase58Decoder().decode(this._bn);return n}},w=async(r,n)=>{try{let t=new f(n),a=await splNameService.getDomainKeysWithReverses(r.connection,t);return a.length===0?null:`${await splNameService.performReverseLookup(r.connection,a[0])}.sol`}catch{return null}},A=async(r,n)=>{try{let t=await splNameService.getRecord(r.connection,n,splNameService.Record.Pic);return !t||!t.data?null:t.data.toString("utf-8")}catch{return null}};function Kn(r){let{wallet:n,connection:t,explorerUrl:a,cluster:i}=r;return {key:pulsarCore.TransactionAdapter.SOLANA,getWalletInfo:()=>({walletAddress:n?.publicKey?.toBase58()??"0x0",walletType:n?.wallet?.adapter.name.toLowerCase()??"unknown"}),checkChainForTx:async o=>{let e=t?.connection.rpcEndpoint;if(!e){console.warn("Cannot check chain: connection context not provided to adapter.");return}await h(e,o);},checkTransactionsTracker:o=>({tracker:"solana",txKey:o}),checkAndInitializeTrackerInStore:({tx:o,...e})=>y({tracker:o.tracker,tx:o,...e}),getExplorerUrl:()=>a??"https://solscan.io",getExplorerTxUrl:(o,e)=>C(a??"https://solscan.io",e,i),getName:async o=>t?w(t,o):(console.warn("Cannot get name: connection context not provided to adapter."),null),getAvatar:async o=>t?A(t,o):(console.warn("Cannot get avatar: connection context not provided to adapter."),null),retryTxAction:async({actions:o,onClose:e,txKey:s,handleTransaction:c,tx:l})=>{if(e(s),!n)throw new Error("Retry failed: A wallet must be connected to retry a transaction.");if(!c)throw new Error("Retry failed: handleTransaction function is not provided.");let p=l.actionKey;if(!p||!o?.[p])throw new Error(`Retry failed: No action found for actionKey "${p}".`);let R=o[p],T=l.rpcUrl??t?.connection.rpcEndpoint;if(!T)throw new Error("Retry failed: Could not determine RPC endpoint.");let P=kit.createSolanaRpc(T);await c({actionFunction:()=>R({wallet:n,connection:t?.connection,rpc:P,...l.payload}),params:l,defaultTracker:"solana"});}}}
+exports.SolanaChainMismatchError=m;exports.SolanaTransactionTracker=S;exports.checkAndInitializeTrackerInStore=y;exports.checkSolanaChain=h;exports.getSolanaAvatar=A;exports.getSolanaName=w;exports.selectSolanaTxExplorerLink=C;exports.solanaAdapter=Kn;exports.solanaFetcher=N;exports.solanaTrackerForStore=x;//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/trackers/solanaTracker.ts","../src/utils/checkAndInitializeTrackerInStore.ts","../src/errors.ts","../src/utils/checkSolanaChain.ts","../src/utils/selectSolanaTxExplorerLink.ts","../src/utils/snsUtils.ts","../src/adapters/solanaAdapter.ts"],"names":["SolanaTransactionTracker","rpcCache","getRpcClient","rpcUrl","newRpc","createSolanaRpc","solanaFetcher","tx","stopPolling","onSuccess","onFailure","onIntervalTick","TransactionAdapter","status","typedStatus","dayjs","solanaTrackerForStore","rest","initializePollingTracker","response","TransactionStatus","updatedTx","errorMessage","checkAndInitializeTrackerInStore","tracker","SolanaChainMismatchError","requiredCluster","currentCluster","message","SOLANA_GENESIS_HASHES","checkSolanaChain","expectedGenesisHash","currentGenesisHash","currentClusterName","hash","selectSolanaTxExplorerLink","baseUrl","txKey","cluster","sanitizedBaseUrl","clusterParam","PublicKey","value","getBase58Encoder","decodedString","getBase58Decoder","getSolanaName","connection","address","pubKey","domainKeys","getDomainKeysWithReverses","performReverseLookup","getSolanaAvatar","name","record","getRecord","Record","solanaAdapter","config","wallet","explorerUrl","txCluster","currentRpcUrl","actionTxKey","txPool","actions","onClose","handleTransaction","actionKey","retryAction","rpcUrlForRetry","rpcForRetry"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @file Defines the core types and enums specific to the @tuwaio/pulsar-solana package.\n */\n\nimport { ConnectionContextState, WalletContextState } from '@solana/wallet-adapter-react';\n\n/**\n * Defines the possible Solana network clusters.\n */\nexport type SolanaCluster = 'mainnet-beta' | 'devnet' | 'testnet';\n\n/**\n * Configuration object for the `solanaAdapter`.\n * All properties are optional and are typically derived from the Solana wallet adapter hooks.\n *\n * @property {WalletContextState} [wallet] - The state object from `useWallet()`. Required for actions that need a connected wallet, like signing or retrying transactions.\n * @property {ConnectionContextState} [connection] - The state object from `useConnection()`. Required for on-chain operations like checking the network or using the Solana Name Service.\n * @property {string} [explorerUrl] - The base URL for the transaction explorer (e.g., \"https://solscan.io\"). Defaults to Solscan if not provided.\n * @property {SolanaCluster} [cluster] - The specific cluster the app is connected to. Used for generating correct explorer links.\n */\nexport interface SolanaAdapterConfig {\n  wallet?: WalletContextState;\n  connection?: ConnectionContextState;\n  explorerUrl?: string;\n  cluster?: SolanaCluster;\n}\n\n/**\n * Defines the tracker identifiers available in the Solana adapter.\n */\nexport enum SolanaTransactionTracker {\n  /** The default tracker for monitoring standard Solana transaction signatures. */\n  Solana = 'solana',\n}\n\n/**\n * Represents the unique key returned by a transaction-creating action on Solana.\n * For standard Solana transactions, this is always the transaction signature as a base58 string.\n */\nexport type SolanaActionTxKey = string;\n","/**\n * @file Implements the transaction tracking logic for standard Solana transactions.\n * It uses a polling mechanism to query the `getSignatureStatuses` RPC method.\n */\n\nimport { createSolanaRpc, Rpc, Signature, SolanaRpcApi, TransactionError } from '@solana/kit';\nimport {\n  initializePollingTracker,\n  ITxTrackingStore,\n  PollingTrackerConfig,\n  Transaction,\n  TransactionAdapter,\n  TransactionStatus,\n} from '@tuwaio/pulsar-core';\nimport dayjs from 'dayjs';\n\nimport { SolanaActionTxKey, SolanaTransactionTracker } from '../types';\n\n// --- RPC Client Caching ---\n\n/**\n * An in-memory cache for RPC clients to avoid re-creating them on every poll.\n * @internal\n */\nconst rpcCache = new Map<string, Rpc<SolanaRpcApi>>();\n\n/**\n * Retrieves a cached RPC client for a given URL or creates a new one.\n * @param rpcUrl - The RPC endpoint URL.\n * @returns The RPC client instance.\n * @internal\n */\nconst getRpcClient = (rpcUrl: string): Rpc<SolanaRpcApi> => {\n  if (rpcCache.has(rpcUrl)) {\n    return rpcCache.get(rpcUrl)!;\n  }\n  const newRpc = createSolanaRpc(rpcUrl);\n  rpcCache.set(rpcUrl, newRpc);\n  return newRpc;\n};\n\n// --- Types ---\n\n/**\n * The shape of the status object returned for each signature from `getSignatureStatuses`.\n * @internal\n */\ntype SolanaSignatureStatusResponse = {\n  slot: bigint;\n  confirmations: number | null;\n  err: TransactionError | null;\n  confirmationStatus: 'processed' | 'confirmed' | 'finalized' | null;\n};\n\n/**\n * The parameters for our specific fetcher function.\n * @internal\n */\ntype SolanaFetcherParams = Parameters<\n  PollingTrackerConfig<\n    SolanaSignatureStatusResponse,\n    Transaction<SolanaTransactionTracker>,\n    SolanaTransactionTracker\n  >['fetcher']\n>[0];\n\n// --- Fetcher Implementation ---\n\n/**\n * A reusable fetcher for `initializePollingTracker` that queries the Solana RPC for a transaction's signature status.\n * This is the core polling logic that powers the tracker.\n */\nexport async function solanaFetcher({ tx, stopPolling, onSuccess, onFailure, onIntervalTick }: SolanaFetcherParams) {\n  if (tx.adapter !== TransactionAdapter.SOLANA || !tx.rpcUrl) {\n    // This should not happen if the types are correct, but it's a good runtime safeguard.\n    throw new Error('RPC URL is missing from the Solana transaction.');\n  }\n\n  const rpc = getRpcClient(tx.rpcUrl);\n  const statuses = await rpc.getSignatureStatuses([tx.txKey as Signature]).send();\n  const status = statuses?.value[0];\n\n  if (!status) {\n    // Continue polling if the transaction is not yet found by the RPC node.\n    // The polling tracker will handle the retry delay.\n    return;\n  }\n\n  const typedStatus = status as SolanaSignatureStatusResponse;\n  onIntervalTick?.(typedStatus);\n\n  if (typedStatus.err) {\n    onFailure(typedStatus); // Terminal failure state\n    return;\n  }\n\n  if (typedStatus.confirmationStatus === 'finalized') {\n    onSuccess(typedStatus); // Terminal success state\n  }\n\n  // Safeguard: Stop polling for very old pending transactions.\n  if (dayjs().diff(dayjs.unix(tx.localTimestamp), 'minute') >= 30) {\n    stopPolling({ withoutRemoving: true });\n    // When a timeout occurs, we call `onFailure` with the last known status,\n    // but the tracker itself will provide the specific timeout error message.\n    onFailure(typedStatus);\n  }\n}\n\n// --- Store-Connected Tracker ---\n\n/**\n * A higher-level wrapper that integrates the Solana polling logic with the Pulsar store.\n * It uses the generic `solanaFetcher` and provides store-specific callbacks.\n *\n * @template T - The application-specific transaction type, constrained to Transaction.\n */\nexport async function solanaTrackerForStore<T extends Transaction<SolanaTransactionTracker>>({\n  tx,\n  ...rest\n}: Pick<\n  ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>,\n  'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'\n> & {\n  tx: T;\n}) {\n  return initializePollingTracker<SolanaSignatureStatusResponse, T, SolanaTransactionTracker>({\n    tx,\n    fetcher: solanaFetcher,\n    removeTxFromPool: rest.removeTxFromPool,\n    pollingInterval: 2500,\n    maxRetries: 720, // 30 minutes timeout (720 intervals * 2.5s = 1800s)\n    onSuccess: (response) => {\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Success,\n        pending: false,\n        isError: false,\n        finishedTimestamp: dayjs().unix(),\n        confirmations: response.confirmations ?? 1,\n        slot: Number(response.slot),\n      });\n\n      const updatedTx = rest.transactionsPool[tx.txKey];\n      if (rest.onSucceedCallbacks && updatedTx) {\n        rest.onSucceedCallbacks(updatedTx);\n      }\n    },\n    onIntervalTick: (response) => {\n      rest.updateTxParams(tx.txKey, {\n        confirmations: response.confirmations ?? 0,\n        slot: Number(response.slot),\n      });\n    },\n    onFailure: (response) => {\n      // If `response` is undefined, it means the polling timed out from `initializePollingTracker`.\n      // Otherwise, the transaction failed on-chain.\n      const errorMessage = response?.err\n        ? `Transaction failed: ${JSON.stringify(response.err)}`\n        : 'Transaction tracking timed out or the transaction was not found.';\n\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Failed,\n        pending: false,\n        isError: true,\n        errorMessage,\n        finishedTimestamp: dayjs().unix(),\n      });\n    },\n  });\n}\n","/**\n * @file This file contains the primary router for initializing transaction trackers.\n */\n\nimport { ITxTrackingStore, Transaction, TransactionStatus } from '@tuwaio/pulsar-core';\n\nimport { solanaTrackerForStore } from '../trackers/solanaTracker';\nimport { SolanaActionTxKey, SolanaTransactionTracker } from '../types';\n\n/**\n * Initializes the correct background tracker for a given Solana transaction.\n * This function acts as a router, selecting the appropriate tracker based on the `tx.tracker` property.\n *\n * @template T - The transaction type, constrained to Solana transactions.\n * @param {object} params - The parameters for initializing the tracker.\n * @param {T} params.tx - The transaction object to be tracked.\n * @param {SolanaTransactionTracker} params.tracker - The specific tracker to use.\n * @param {object} params.rest - The rest of the store's methods and state needed by the tracker.\n * @returns {Promise<void>} A promise that resolves when the tracker has been initialized.\n */\nexport async function checkAndInitializeTrackerInStore<T extends Transaction<SolanaTransactionTracker>>({\n  tx,\n  tracker,\n  ...rest\n}: {\n  tx: T;\n  tracker: SolanaTransactionTracker;\n} & Pick<\n  ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>,\n  'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'\n>): Promise<void> {\n  switch (tracker) {\n    case SolanaTransactionTracker.Solana:\n      await solanaTrackerForStore({\n        tx,\n        ...rest,\n      });\n      break;\n    default:\n      console.error(`Unknown tracker type for Solana adapter: ${tracker}`);\n      // If an unsupported tracker is specified, mark the transaction as failed.\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Failed,\n        pending: false,\n        isError: true,\n        errorMessage: `Unsupported tracker type: \"${tracker}\"`,\n      });\n      break;\n  }\n}\n","/**\n * @file This file defines custom error classes for the @tuwaio/pulsar-solana package.\n */\n\nimport { SolanaCluster } from './types';\n\n/**\n * Thrown when the connected Solana cluster does not match the required cluster for a transaction.\n *\n * This allows consuming applications to `catch` this specific error and\n * implement custom logic, such as prompting the user to switch networks.\n */\nexport class SolanaChainMismatchError extends Error {\n  /** The name of the error, for easy identification. */\n  name = 'SolanaChainMismatchError';\n  /** The cluster that the transaction requires (e.g., 'mainnet-beta'). */\n  requiredCluster: SolanaCluster;\n  /** The cluster the wallet is currently connected to. */\n  currentCluster: SolanaCluster | string;\n\n  constructor(requiredCluster: SolanaCluster, currentCluster: SolanaCluster | string) {\n    const message = `Wrong network. The transaction requires ${requiredCluster}, but you are connected to ${currentCluster}.`;\n    super(message);\n    this.requiredCluster = requiredCluster;\n    this.currentCluster = currentCluster;\n  }\n}\n","/**\n * @file This file contains a utility to robustly verify the Solana cluster by its genesis hash.\n */\n\nimport { createSolanaRpc } from '@solana/kit';\n\nimport { SolanaChainMismatchError } from '../errors';\nimport { SolanaCluster } from '../types';\n\nconst SOLANA_GENESIS_HASHES: Record<SolanaCluster, string> = {\n  'mainnet-beta': '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',\n  devnet: 'GH7ome3EiwEr7tu9JuTh2dpYWBJK3z69Xm1ZE3MEE6JC',\n  testnet: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY',\n};\n\n/**\n * Checks if an RPC endpoint is connected to the required Solana cluster.\n * It fetches the genesis hash from the RPC endpoint and compares it\n * with a known hash for the specified cluster.\n *\n * @param {string} rpcUrl - The RPC endpoint URL to check.\n * @param {SolanaCluster} requiredCluster - The cluster that the transaction requires (e.g., 'mainnet-beta').\n * @throws {SolanaChainMismatchError} If the connected chain does not match the required cluster.\n * @throws {Error} If the cluster name is unknown or if the RPC call fails for other reasons.\n */\nexport const checkSolanaChain = async (rpcUrl: string, requiredCluster: SolanaCluster): Promise<void> => {\n  const expectedGenesisHash = SOLANA_GENESIS_HASHES[requiredCluster];\n  if (!expectedGenesisHash) {\n    throw new Error(`Unknown Solana cluster specified: ${requiredCluster}`);\n  }\n\n  // Note: For optimal performance in a high-traffic app, the created RPC client could be cached.\n  // However, for a one-off check like this, creating it on the fly is perfectly fine.\n  const rpc = createSolanaRpc(rpcUrl);\n  const currentGenesisHash = await rpc.getGenesisHash().send();\n\n  if (currentGenesisHash !== expectedGenesisHash) {\n    const currentClusterName =\n      Object.entries(SOLANA_GENESIS_HASHES).find(([, hash]) => hash === currentGenesisHash)?.[0] ||\n      'an unknown network';\n\n    throw new SolanaChainMismatchError(requiredCluster, currentClusterName as SolanaCluster | string);\n  }\n};\n","/**\n * @file This file contains a utility function for generating Solana transaction explorer links.\n */\n\nimport { SolanaCluster } from '../types';\n\n/**\n * Generates a full URL to a transaction on a Solana explorer like Solscan.\n *\n * @param {string} baseUrl - The base URL of the explorer (e.g., \"https://solscan.io\").\n * @param {string} txKey - The transaction signature (hash).\n * @param {SolanaCluster} [cluster] - The optional cluster name ('devnet', 'testnet') to add as a query parameter.\n * @returns {string} The full URL to the transaction on the explorer.\n */\nexport const selectSolanaTxExplorerLink = (baseUrl: string, txKey: string, cluster?: SolanaCluster): string => {\n  // Ensure there are no trailing slashes on the base URL for clean URL construction.\n  const sanitizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n\n  // Build the cluster query parameter if provided.\n  const clusterParam = cluster ? `?cluster=${cluster}` : '';\n\n  return `${sanitizedBaseUrl}/tx/${txKey}${clusterParam}`;\n};\n","/**\n * @file This file contains utility functions for interacting with the Solana Name Service (SNS) provided by Bonfida.\n */\n\nimport { getDomainKeysWithReverses, getRecord, performReverseLookup, Record } from '@bonfida/spl-name-service';\nimport { getBase58Decoder, getBase58Encoder } from '@solana/kit';\nimport { ConnectionContextState } from '@solana/wallet-adapter-react';\n\n// A minimal PublicKey class to satisfy the @bonfida/spl-name-service dependency\n// without importing the entire @solana/web3.js package. This is a form of duck typing.\nclass PublicKey {\n  private readonly _bn: Uint8Array;\n\n  constructor(value: string) {\n    // The return type of `encode` is `ReadonlyUint8Array`, which we cast to `Uint8Array`.\n    this._bn = getBase58Encoder().encode(value) as Uint8Array;\n  }\n\n  toBuffer(): Buffer {\n    return Buffer.from(this._bn);\n  }\n\n  toString(): string {\n    // The decoder returns a tuple [decodedString, bytesRead], we need the first element.\n    const [decodedString] = getBase58Decoder().decode(this._bn);\n    return decodedString;\n  }\n}\n\n/**\n * Performs a reverse lookup to find the .sol domain name for a given wallet address.\n * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.\n * @param {string} address - The public key of the wallet as a string.\n * @returns {Promise<string | null>} The .sol domain name (e.g., \"bonfida.sol\") or null if not found.\n */\nexport const getSolanaName = async (connection: ConnectionContextState, address: string): Promise<string | null> => {\n  try {\n    const pubKey = new PublicKey(address);\n\n    // @ts-expect-error We are duck-typing the PublicKey to avoid a full dependency.\n    const domainKeys = await getDomainKeysWithReverses(connection.connection, pubKey);\n\n    if (domainKeys.length === 0) {\n      return null;\n    }\n\n    // @ts-expect-error Duck-typing continued for the result.\n    const domainName = await performReverseLookup(connection.connection, domainKeys[0]);\n    return `${domainName}.sol`;\n  } catch {\n    // Fails silently if no domain is found.\n    return null;\n  }\n};\n\n/**\n * Retrieves the avatar URL from the 'pic' record of a .sol domain name.\n * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.\n * @param {string} name - The .sol domain name (e.g., \"bonfida.sol\").\n * @returns {Promise<string | null>} The URL of the avatar or null if not found or set.\n */\nexport const getSolanaAvatar = async (connection: ConnectionContextState, name: string): Promise<string | null> => {\n  try {\n    const record = await getRecord(connection.connection, name, Record.Pic);\n\n    if (!record || !record.data) {\n      return null;\n    }\n\n    return record.data.toString('utf-8');\n  } catch {\n    // Fails silently if the record doesn't exist.\n    return null;\n  }\n};\n","/**\n * @file This file contains the factory function for creating the Solana adapter for Pulsar.\n */\n\nimport { createSolanaRpc } from '@solana/kit';\nimport { Transaction, TransactionAdapter, TransactionPool, TxAdapter } from '@tuwaio/pulsar-core';\n\nimport { SolanaActionTxKey, SolanaAdapterConfig, SolanaCluster, SolanaTransactionTracker } from '../types';\nimport { checkAndInitializeTrackerInStore } from '../utils/checkAndInitializeTrackerInStore';\nimport { checkSolanaChain } from '../utils/checkSolanaChain';\nimport { selectSolanaTxExplorerLink } from '../utils/selectSolanaTxExplorerLink';\nimport { getSolanaAvatar, getSolanaName } from '../utils/snsUtils';\n\n/**\n * Factory function to create a Solana adapter for Pulsar.\n * This adapter provides all the necessary logic to interact with the Solana ecosystem,\n * including wallet interactions, transaction tracking, and name services.\n *\n * @param {SolanaAdapterConfig} config - The configuration object, typically derived from Solana wallet adapter hooks.\n * @returns {TxAdapter} An object conforming to the `TxAdapter` interface.\n */\nexport function solanaAdapter<T extends Transaction<SolanaTransactionTracker>>(\n  config: SolanaAdapterConfig,\n): TxAdapter<SolanaTransactionTracker, T, SolanaActionTxKey> {\n  const { wallet, connection, explorerUrl, cluster } = config;\n\n  return {\n    key: TransactionAdapter.SOLANA,\n\n    // --- Core Methods ---\n    getWalletInfo: () => ({\n      walletAddress: wallet?.publicKey?.toBase58() ?? '0x0',\n      walletType: wallet?.wallet?.adapter.name.toLowerCase() ?? 'unknown',\n    }),\n\n    checkChainForTx: async (txCluster) => {\n      // Use the rpcEndpoint from the main connection context for pre-flight checks.\n      const currentRpcUrl = connection?.connection.rpcEndpoint;\n      if (!currentRpcUrl) {\n        // This can happen if the adapter is used in a read-only mode without a provider.\n        // We warn but do not throw, allowing tracking to continue if the rpcUrl is in the tx.\n        console.warn('Cannot check chain: connection context not provided to adapter.');\n        return;\n      }\n      await checkSolanaChain(currentRpcUrl, txCluster as SolanaCluster);\n    },\n\n    checkTransactionsTracker: (actionTxKey) => {\n      // For Solana, the actionTxKey is always the transaction signature.\n      return { tracker: SolanaTransactionTracker.Solana, txKey: actionTxKey };\n    },\n\n    checkAndInitializeTrackerInStore: ({ tx, ...rest }) => {\n      // Delegate to the tracker router utility.\n      return checkAndInitializeTrackerInStore({\n        tracker: tx.tracker,\n        tx,\n        ...rest,\n      });\n    },\n\n    // --- UI & Explorer Methods ---\n    getExplorerUrl: () => {\n      return explorerUrl ?? 'https://solscan.io';\n    },\n\n    getExplorerTxUrl: (txPool: TransactionPool<any, any>, txKey: string) => {\n      const baseUrl = explorerUrl ?? 'https://solscan.io';\n      return selectSolanaTxExplorerLink(baseUrl, txKey, cluster);\n    },\n\n    // --- Optional Name Service Methods ---\n    getName: async (address: string) => {\n      if (!connection) {\n        console.warn('Cannot get name: connection context not provided to adapter.');\n        return null;\n      }\n      return getSolanaName(connection, address);\n    },\n\n    getAvatar: async (name: string) => {\n      if (!connection) {\n        console.warn('Cannot get avatar: connection context not provided to adapter.');\n        return null;\n      }\n      return getSolanaAvatar(connection, name);\n    },\n\n    // --- Optional Actions ---\n    retryTxAction: async ({ actions, onClose, txKey, handleTransaction, tx }) => {\n      onClose(txKey);\n\n      if (!wallet) {\n        throw new Error('Retry failed: A wallet must be connected to retry a transaction.');\n      }\n      if (!handleTransaction) {\n        throw new Error('Retry failed: handleTransaction function is not provided.');\n      }\n\n      const actionKey = tx.actionKey;\n      if (!actionKey || !actions?.[actionKey]) {\n        throw new Error(`Retry failed: No action found for actionKey \"${actionKey}\".`);\n      }\n\n      const retryAction = actions[actionKey];\n\n      // Prioritize the RPC URL from the original transaction, falling back to the current connection.\n      const rpcUrlForRetry = tx.rpcUrl ?? connection?.connection.rpcEndpoint;\n      if (!rpcUrlForRetry) {\n        throw new Error('Retry failed: Could not determine RPC endpoint.');\n      }\n\n      const rpcForRetry = createSolanaRpc(rpcUrlForRetry);\n\n      await handleTransaction({\n        actionFunction: () =>\n          (retryAction as any)({\n            wallet,\n            connection: connection?.connection,\n            rpc: rpcForRetry,\n            ...tx.payload,\n          }),\n        params: tx,\n        defaultTracker: SolanaTransactionTracker.Solana,\n      });\n    },\n  };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import {createSolanaRpc,getBase58Encoder,getBase58Decoder}from'@solana/kit';import {TransactionAdapter,initializePollingTracker,TransactionStatus}from'@tuwaio/pulsar-core';import u from'dayjs';import {getDomainKeysWithReverses,performReverseLookup,getRecord,Record}from'@bonfida/spl-name-service';var S=(n=>(n.Solana="solana",n))(S||{});var d=new Map,b=r=>{if(d.has(r))return d.get(r);let n=createSolanaRpc(r);return d.set(r,n),n};async function N({tx:r,stopPolling:n,onSuccess:t,onFailure:a,onIntervalTick:i}){if(r.adapter!==TransactionAdapter.SOLANA||!r.rpcUrl)throw new Error("RPC URL is missing from the Solana transaction.");let s=(await b(r.rpcUrl).getSignatureStatuses([r.txKey]).send())?.value[0];if(!s)return;let c=s;if(i?.(c),c.err){a(c);return}c.confirmationStatus==="finalized"&&t(c),u().diff(u.unix(r.localTimestamp),"minute")>=30&&(n({withoutRemoving:true}),a(c));}async function x({tx:r,...n}){return initializePollingTracker({tx:r,fetcher:N,removeTxFromPool:n.removeTxFromPool,pollingInterval:2500,maxRetries:720,onSuccess:t=>{n.updateTxParams(r.txKey,{status:TransactionStatus.Success,pending:false,isError:false,finishedTimestamp:u().unix(),confirmations:t.confirmations??1,slot:Number(t.slot)});let a=n.transactionsPool[r.txKey];n.onSucceedCallbacks&&a&&n.onSucceedCallbacks(a);},onIntervalTick:t=>{n.updateTxParams(r.txKey,{confirmations:t.confirmations??0,slot:Number(t.slot)});},onFailure:t=>{let a=t?.err?`Transaction failed: ${JSON.stringify(t.err)}`:"Transaction tracking timed out or the transaction was not found.";n.updateTxParams(r.txKey,{status:TransactionStatus.Failed,pending:false,isError:true,errorMessage:a,finishedTimestamp:u().unix()});}})}async function y({tx:r,tracker:n,...t}){switch(n){case "solana":await x({tx:r,...t});break;default:console.error(`Unknown tracker type for Solana adapter: ${n}`),t.updateTxParams(r.txKey,{status:TransactionStatus.Failed,pending:false,isError:true,errorMessage:`Unsupported tracker type: "${n}"`});break}}var m=class extends Error{name="SolanaChainMismatchError";requiredCluster;currentCluster;constructor(n,t){let a=`Wrong network. The transaction requires ${n}, but you are connected to ${t}.`;super(a),this.requiredCluster=n,this.currentCluster=t;}};var k={"mainnet-beta":"5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d",devnet:"GH7ome3EiwEr7tu9JuTh2dpYWBJK3z69Xm1ZE3MEE6JC",testnet:"4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY"},h=async(r,n)=>{let t=k[n];if(!t)throw new Error(`Unknown Solana cluster specified: ${n}`);let i=await createSolanaRpc(r).getGenesisHash().send();if(i!==t){let o=Object.entries(k).find(([,e])=>e===i)?.[0]||"an unknown network";throw new m(n,o)}};var C=(r,n,t)=>{let a=r.endsWith("/")?r.slice(0,-1):r,i=t?`?cluster=${t}`:"";return `${a}/tx/${n}${i}`};var f=class{_bn;constructor(n){this._bn=getBase58Encoder().encode(n);}toBuffer(){return Buffer.from(this._bn)}toString(){let[n]=getBase58Decoder().decode(this._bn);return n}},w=async(r,n)=>{try{let t=new f(n),a=await getDomainKeysWithReverses(r.connection,t);return a.length===0?null:`${await performReverseLookup(r.connection,a[0])}.sol`}catch{return null}},A=async(r,n)=>{try{let t=await getRecord(r.connection,n,Record.Pic);return !t||!t.data?null:t.data.toString("utf-8")}catch{return null}};function Kn(r){let{wallet:n,connection:t,explorerUrl:a,cluster:i}=r;return {key:TransactionAdapter.SOLANA,getWalletInfo:()=>({walletAddress:n?.publicKey?.toBase58()??"0x0",walletType:n?.wallet?.adapter.name.toLowerCase()??"unknown"}),checkChainForTx:async o=>{let e=t?.connection.rpcEndpoint;if(!e){console.warn("Cannot check chain: connection context not provided to adapter.");return}await h(e,o);},checkTransactionsTracker:o=>({tracker:"solana",txKey:o}),checkAndInitializeTrackerInStore:({tx:o,...e})=>y({tracker:o.tracker,tx:o,...e}),getExplorerUrl:()=>a??"https://solscan.io",getExplorerTxUrl:(o,e)=>C(a??"https://solscan.io",e,i),getName:async o=>t?w(t,o):(console.warn("Cannot get name: connection context not provided to adapter."),null),getAvatar:async o=>t?A(t,o):(console.warn("Cannot get avatar: connection context not provided to adapter."),null),retryTxAction:async({actions:o,onClose:e,txKey:s,handleTransaction:c,tx:l})=>{if(e(s),!n)throw new Error("Retry failed: A wallet must be connected to retry a transaction.");if(!c)throw new Error("Retry failed: handleTransaction function is not provided.");let p=l.actionKey;if(!p||!o?.[p])throw new Error(`Retry failed: No action found for actionKey "${p}".`);let R=o[p],T=l.rpcUrl??t?.connection.rpcEndpoint;if(!T)throw new Error("Retry failed: Could not determine RPC endpoint.");let P=createSolanaRpc(T);await c({actionFunction:()=>R({wallet:n,connection:t?.connection,rpc:P,...l.payload}),params:l,defaultTracker:"solana"});}}}
+export{m as SolanaChainMismatchError,S as SolanaTransactionTracker,y as checkAndInitializeTrackerInStore,h as checkSolanaChain,A as getSolanaAvatar,w as getSolanaName,C as selectSolanaTxExplorerLink,Kn as solanaAdapter,N as solanaFetcher,x as solanaTrackerForStore};//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/trackers/solanaTracker.ts","../src/utils/checkAndInitializeTrackerInStore.ts","../src/errors.ts","../src/utils/checkSolanaChain.ts","../src/utils/selectSolanaTxExplorerLink.ts","../src/utils/snsUtils.ts","../src/adapters/solanaAdapter.ts"],"names":["SolanaTransactionTracker","rpcCache","getRpcClient","rpcUrl","newRpc","createSolanaRpc","solanaFetcher","tx","stopPolling","onSuccess","onFailure","onIntervalTick","TransactionAdapter","status","typedStatus","dayjs","solanaTrackerForStore","rest","initializePollingTracker","response","TransactionStatus","updatedTx","errorMessage","checkAndInitializeTrackerInStore","tracker","SolanaChainMismatchError","requiredCluster","currentCluster","message","SOLANA_GENESIS_HASHES","checkSolanaChain","expectedGenesisHash","currentGenesisHash","currentClusterName","hash","selectSolanaTxExplorerLink","baseUrl","txKey","cluster","sanitizedBaseUrl","clusterParam","PublicKey","value","getBase58Encoder","decodedString","getBase58Decoder","getSolanaName","connection","address","pubKey","domainKeys","getDomainKeysWithReverses","performReverseLookup","getSolanaAvatar","name","record","getRecord","Record","solanaAdapter","config","wallet","explorerUrl","txCluster","currentRpcUrl","actionTxKey","txPool","actions","onClose","handleTransaction","actionKey","retryAction","rpcUrlForRetry","rpcForRetry"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @file Defines the core types and enums specific to the @tuwaio/pulsar-solana package.\n */\n\nimport { ConnectionContextState, WalletContextState } from '@solana/wallet-adapter-react';\n\n/**\n * Defines the possible Solana network clusters.\n */\nexport type SolanaCluster = 'mainnet-beta' | 'devnet' | 'testnet';\n\n/**\n * Configuration object for the `solanaAdapter`.\n * All properties are optional and are typically derived from the Solana wallet adapter hooks.\n *\n * @property {WalletContextState} [wallet] - The state object from `useWallet()`. Required for actions that need a connected wallet, like signing or retrying transactions.\n * @property {ConnectionContextState} [connection] - The state object from `useConnection()`. Required for on-chain operations like checking the network or using the Solana Name Service.\n * @property {string} [explorerUrl] - The base URL for the transaction explorer (e.g., \"https://solscan.io\"). Defaults to Solscan if not provided.\n * @property {SolanaCluster} [cluster] - The specific cluster the app is connected to. Used for generating correct explorer links.\n */\nexport interface SolanaAdapterConfig {\n  wallet?: WalletContextState;\n  connection?: ConnectionContextState;\n  explorerUrl?: string;\n  cluster?: SolanaCluster;\n}\n\n/**\n * Defines the tracker identifiers available in the Solana adapter.\n */\nexport enum SolanaTransactionTracker {\n  /** The default tracker for monitoring standard Solana transaction signatures. */\n  Solana = 'solana',\n}\n\n/**\n * Represents the unique key returned by a transaction-creating action on Solana.\n * For standard Solana transactions, this is always the transaction signature as a base58 string.\n */\nexport type SolanaActionTxKey = string;\n","/**\n * @file Implements the transaction tracking logic for standard Solana transactions.\n * It uses a polling mechanism to query the `getSignatureStatuses` RPC method.\n */\n\nimport { createSolanaRpc, Rpc, Signature, SolanaRpcApi, TransactionError } from '@solana/kit';\nimport {\n  initializePollingTracker,\n  ITxTrackingStore,\n  PollingTrackerConfig,\n  Transaction,\n  TransactionAdapter,\n  TransactionStatus,\n} from '@tuwaio/pulsar-core';\nimport dayjs from 'dayjs';\n\nimport { SolanaActionTxKey, SolanaTransactionTracker } from '../types';\n\n// --- RPC Client Caching ---\n\n/**\n * An in-memory cache for RPC clients to avoid re-creating them on every poll.\n * @internal\n */\nconst rpcCache = new Map<string, Rpc<SolanaRpcApi>>();\n\n/**\n * Retrieves a cached RPC client for a given URL or creates a new one.\n * @param rpcUrl - The RPC endpoint URL.\n * @returns The RPC client instance.\n * @internal\n */\nconst getRpcClient = (rpcUrl: string): Rpc<SolanaRpcApi> => {\n  if (rpcCache.has(rpcUrl)) {\n    return rpcCache.get(rpcUrl)!;\n  }\n  const newRpc = createSolanaRpc(rpcUrl);\n  rpcCache.set(rpcUrl, newRpc);\n  return newRpc;\n};\n\n// --- Types ---\n\n/**\n * The shape of the status object returned for each signature from `getSignatureStatuses`.\n * @internal\n */\ntype SolanaSignatureStatusResponse = {\n  slot: bigint;\n  confirmations: number | null;\n  err: TransactionError | null;\n  confirmationStatus: 'processed' | 'confirmed' | 'finalized' | null;\n};\n\n/**\n * The parameters for our specific fetcher function.\n * @internal\n */\ntype SolanaFetcherParams = Parameters<\n  PollingTrackerConfig<\n    SolanaSignatureStatusResponse,\n    Transaction<SolanaTransactionTracker>,\n    SolanaTransactionTracker\n  >['fetcher']\n>[0];\n\n// --- Fetcher Implementation ---\n\n/**\n * A reusable fetcher for `initializePollingTracker` that queries the Solana RPC for a transaction's signature status.\n * This is the core polling logic that powers the tracker.\n */\nexport async function solanaFetcher({ tx, stopPolling, onSuccess, onFailure, onIntervalTick }: SolanaFetcherParams) {\n  if (tx.adapter !== TransactionAdapter.SOLANA || !tx.rpcUrl) {\n    // This should not happen if the types are correct, but it's a good runtime safeguard.\n    throw new Error('RPC URL is missing from the Solana transaction.');\n  }\n\n  const rpc = getRpcClient(tx.rpcUrl);\n  const statuses = await rpc.getSignatureStatuses([tx.txKey as Signature]).send();\n  const status = statuses?.value[0];\n\n  if (!status) {\n    // Continue polling if the transaction is not yet found by the RPC node.\n    // The polling tracker will handle the retry delay.\n    return;\n  }\n\n  const typedStatus = status as SolanaSignatureStatusResponse;\n  onIntervalTick?.(typedStatus);\n\n  if (typedStatus.err) {\n    onFailure(typedStatus); // Terminal failure state\n    return;\n  }\n\n  if (typedStatus.confirmationStatus === 'finalized') {\n    onSuccess(typedStatus); // Terminal success state\n  }\n\n  // Safeguard: Stop polling for very old pending transactions.\n  if (dayjs().diff(dayjs.unix(tx.localTimestamp), 'minute') >= 30) {\n    stopPolling({ withoutRemoving: true });\n    // When a timeout occurs, we call `onFailure` with the last known status,\n    // but the tracker itself will provide the specific timeout error message.\n    onFailure(typedStatus);\n  }\n}\n\n// --- Store-Connected Tracker ---\n\n/**\n * A higher-level wrapper that integrates the Solana polling logic with the Pulsar store.\n * It uses the generic `solanaFetcher` and provides store-specific callbacks.\n *\n * @template T - The application-specific transaction type, constrained to Transaction.\n */\nexport async function solanaTrackerForStore<T extends Transaction<SolanaTransactionTracker>>({\n  tx,\n  ...rest\n}: Pick<\n  ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>,\n  'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'\n> & {\n  tx: T;\n}) {\n  return initializePollingTracker<SolanaSignatureStatusResponse, T, SolanaTransactionTracker>({\n    tx,\n    fetcher: solanaFetcher,\n    removeTxFromPool: rest.removeTxFromPool,\n    pollingInterval: 2500,\n    maxRetries: 720, // 30 minutes timeout (720 intervals * 2.5s = 1800s)\n    onSuccess: (response) => {\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Success,\n        pending: false,\n        isError: false,\n        finishedTimestamp: dayjs().unix(),\n        confirmations: response.confirmations ?? 1,\n        slot: Number(response.slot),\n      });\n\n      const updatedTx = rest.transactionsPool[tx.txKey];\n      if (rest.onSucceedCallbacks && updatedTx) {\n        rest.onSucceedCallbacks(updatedTx);\n      }\n    },\n    onIntervalTick: (response) => {\n      rest.updateTxParams(tx.txKey, {\n        confirmations: response.confirmations ?? 0,\n        slot: Number(response.slot),\n      });\n    },\n    onFailure: (response) => {\n      // If `response` is undefined, it means the polling timed out from `initializePollingTracker`.\n      // Otherwise, the transaction failed on-chain.\n      const errorMessage = response?.err\n        ? `Transaction failed: ${JSON.stringify(response.err)}`\n        : 'Transaction tracking timed out or the transaction was not found.';\n\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Failed,\n        pending: false,\n        isError: true,\n        errorMessage,\n        finishedTimestamp: dayjs().unix(),\n      });\n    },\n  });\n}\n","/**\n * @file This file contains the primary router for initializing transaction trackers.\n */\n\nimport { ITxTrackingStore, Transaction, TransactionStatus } from '@tuwaio/pulsar-core';\n\nimport { solanaTrackerForStore } from '../trackers/solanaTracker';\nimport { SolanaActionTxKey, SolanaTransactionTracker } from '../types';\n\n/**\n * Initializes the correct background tracker for a given Solana transaction.\n * This function acts as a router, selecting the appropriate tracker based on the `tx.tracker` property.\n *\n * @template T - The transaction type, constrained to Solana transactions.\n * @param {object} params - The parameters for initializing the tracker.\n * @param {T} params.tx - The transaction object to be tracked.\n * @param {SolanaTransactionTracker} params.tracker - The specific tracker to use.\n * @param {object} params.rest - The rest of the store's methods and state needed by the tracker.\n * @returns {Promise<void>} A promise that resolves when the tracker has been initialized.\n */\nexport async function checkAndInitializeTrackerInStore<T extends Transaction<SolanaTransactionTracker>>({\n  tx,\n  tracker,\n  ...rest\n}: {\n  tx: T;\n  tracker: SolanaTransactionTracker;\n} & Pick<\n  ITxTrackingStore<SolanaTransactionTracker, T, SolanaActionTxKey>,\n  'transactionsPool' | 'updateTxParams' | 'onSucceedCallbacks' | 'removeTxFromPool'\n>): Promise<void> {\n  switch (tracker) {\n    case SolanaTransactionTracker.Solana:\n      await solanaTrackerForStore({\n        tx,\n        ...rest,\n      });\n      break;\n    default:\n      console.error(`Unknown tracker type for Solana adapter: ${tracker}`);\n      // If an unsupported tracker is specified, mark the transaction as failed.\n      rest.updateTxParams(tx.txKey, {\n        status: TransactionStatus.Failed,\n        pending: false,\n        isError: true,\n        errorMessage: `Unsupported tracker type: \"${tracker}\"`,\n      });\n      break;\n  }\n}\n","/**\n * @file This file defines custom error classes for the @tuwaio/pulsar-solana package.\n */\n\nimport { SolanaCluster } from './types';\n\n/**\n * Thrown when the connected Solana cluster does not match the required cluster for a transaction.\n *\n * This allows consuming applications to `catch` this specific error and\n * implement custom logic, such as prompting the user to switch networks.\n */\nexport class SolanaChainMismatchError extends Error {\n  /** The name of the error, for easy identification. */\n  name = 'SolanaChainMismatchError';\n  /** The cluster that the transaction requires (e.g., 'mainnet-beta'). */\n  requiredCluster: SolanaCluster;\n  /** The cluster the wallet is currently connected to. */\n  currentCluster: SolanaCluster | string;\n\n  constructor(requiredCluster: SolanaCluster, currentCluster: SolanaCluster | string) {\n    const message = `Wrong network. The transaction requires ${requiredCluster}, but you are connected to ${currentCluster}.`;\n    super(message);\n    this.requiredCluster = requiredCluster;\n    this.currentCluster = currentCluster;\n  }\n}\n","/**\n * @file This file contains a utility to robustly verify the Solana cluster by its genesis hash.\n */\n\nimport { createSolanaRpc } from '@solana/kit';\n\nimport { SolanaChainMismatchError } from '../errors';\nimport { SolanaCluster } from '../types';\n\nconst SOLANA_GENESIS_HASHES: Record<SolanaCluster, string> = {\n  'mainnet-beta': '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',\n  devnet: 'GH7ome3EiwEr7tu9JuTh2dpYWBJK3z69Xm1ZE3MEE6JC',\n  testnet: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY',\n};\n\n/**\n * Checks if an RPC endpoint is connected to the required Solana cluster.\n * It fetches the genesis hash from the RPC endpoint and compares it\n * with a known hash for the specified cluster.\n *\n * @param {string} rpcUrl - The RPC endpoint URL to check.\n * @param {SolanaCluster} requiredCluster - The cluster that the transaction requires (e.g., 'mainnet-beta').\n * @throws {SolanaChainMismatchError} If the connected chain does not match the required cluster.\n * @throws {Error} If the cluster name is unknown or if the RPC call fails for other reasons.\n */\nexport const checkSolanaChain = async (rpcUrl: string, requiredCluster: SolanaCluster): Promise<void> => {\n  const expectedGenesisHash = SOLANA_GENESIS_HASHES[requiredCluster];\n  if (!expectedGenesisHash) {\n    throw new Error(`Unknown Solana cluster specified: ${requiredCluster}`);\n  }\n\n  // Note: For optimal performance in a high-traffic app, the created RPC client could be cached.\n  // However, for a one-off check like this, creating it on the fly is perfectly fine.\n  const rpc = createSolanaRpc(rpcUrl);\n  const currentGenesisHash = await rpc.getGenesisHash().send();\n\n  if (currentGenesisHash !== expectedGenesisHash) {\n    const currentClusterName =\n      Object.entries(SOLANA_GENESIS_HASHES).find(([, hash]) => hash === currentGenesisHash)?.[0] ||\n      'an unknown network';\n\n    throw new SolanaChainMismatchError(requiredCluster, currentClusterName as SolanaCluster | string);\n  }\n};\n","/**\n * @file This file contains a utility function for generating Solana transaction explorer links.\n */\n\nimport { SolanaCluster } from '../types';\n\n/**\n * Generates a full URL to a transaction on a Solana explorer like Solscan.\n *\n * @param {string} baseUrl - The base URL of the explorer (e.g., \"https://solscan.io\").\n * @param {string} txKey - The transaction signature (hash).\n * @param {SolanaCluster} [cluster] - The optional cluster name ('devnet', 'testnet') to add as a query parameter.\n * @returns {string} The full URL to the transaction on the explorer.\n */\nexport const selectSolanaTxExplorerLink = (baseUrl: string, txKey: string, cluster?: SolanaCluster): string => {\n  // Ensure there are no trailing slashes on the base URL for clean URL construction.\n  const sanitizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n\n  // Build the cluster query parameter if provided.\n  const clusterParam = cluster ? `?cluster=${cluster}` : '';\n\n  return `${sanitizedBaseUrl}/tx/${txKey}${clusterParam}`;\n};\n","/**\n * @file This file contains utility functions for interacting with the Solana Name Service (SNS) provided by Bonfida.\n */\n\nimport { getDomainKeysWithReverses, getRecord, performReverseLookup, Record } from '@bonfida/spl-name-service';\nimport { getBase58Decoder, getBase58Encoder } from '@solana/kit';\nimport { ConnectionContextState } from '@solana/wallet-adapter-react';\n\n// A minimal PublicKey class to satisfy the @bonfida/spl-name-service dependency\n// without importing the entire @solana/web3.js package. This is a form of duck typing.\nclass PublicKey {\n  private readonly _bn: Uint8Array;\n\n  constructor(value: string) {\n    // The return type of `encode` is `ReadonlyUint8Array`, which we cast to `Uint8Array`.\n    this._bn = getBase58Encoder().encode(value) as Uint8Array;\n  }\n\n  toBuffer(): Buffer {\n    return Buffer.from(this._bn);\n  }\n\n  toString(): string {\n    // The decoder returns a tuple [decodedString, bytesRead], we need the first element.\n    const [decodedString] = getBase58Decoder().decode(this._bn);\n    return decodedString;\n  }\n}\n\n/**\n * Performs a reverse lookup to find the .sol domain name for a given wallet address.\n * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.\n * @param {string} address - The public key of the wallet as a string.\n * @returns {Promise<string | null>} The .sol domain name (e.g., \"bonfida.sol\") or null if not found.\n */\nexport const getSolanaName = async (connection: ConnectionContextState, address: string): Promise<string | null> => {\n  try {\n    const pubKey = new PublicKey(address);\n\n    // @ts-expect-error We are duck-typing the PublicKey to avoid a full dependency.\n    const domainKeys = await getDomainKeysWithReverses(connection.connection, pubKey);\n\n    if (domainKeys.length === 0) {\n      return null;\n    }\n\n    // @ts-expect-error Duck-typing continued for the result.\n    const domainName = await performReverseLookup(connection.connection, domainKeys[0]);\n    return `${domainName}.sol`;\n  } catch {\n    // Fails silently if no domain is found.\n    return null;\n  }\n};\n\n/**\n * Retrieves the avatar URL from the 'pic' record of a .sol domain name.\n * @param {ConnectionContextState} connection - The connection state object from the `useConnection` hook.\n * @param {string} name - The .sol domain name (e.g., \"bonfida.sol\").\n * @returns {Promise<string | null>} The URL of the avatar or null if not found or set.\n */\nexport const getSolanaAvatar = async (connection: ConnectionContextState, name: string): Promise<string | null> => {\n  try {\n    const record = await getRecord(connection.connection, name, Record.Pic);\n\n    if (!record || !record.data) {\n      return null;\n    }\n\n    return record.data.toString('utf-8');\n  } catch {\n    // Fails silently if the record doesn't exist.\n    return null;\n  }\n};\n","/**\n * @file This file contains the factory function for creating the Solana adapter for Pulsar.\n */\n\nimport { createSolanaRpc } from '@solana/kit';\nimport { Transaction, TransactionAdapter, TransactionPool, TxAdapter } from '@tuwaio/pulsar-core';\n\nimport { SolanaActionTxKey, SolanaAdapterConfig, SolanaCluster, SolanaTransactionTracker } from '../types';\nimport { checkAndInitializeTrackerInStore } from '../utils/checkAndInitializeTrackerInStore';\nimport { checkSolanaChain } from '../utils/checkSolanaChain';\nimport { selectSolanaTxExplorerLink } from '../utils/selectSolanaTxExplorerLink';\nimport { getSolanaAvatar, getSolanaName } from '../utils/snsUtils';\n\n/**\n * Factory function to create a Solana adapter for Pulsar.\n * This adapter provides all the necessary logic to interact with the Solana ecosystem,\n * including wallet interactions, transaction tracking, and name services.\n *\n * @param {SolanaAdapterConfig} config - The configuration object, typically derived from Solana wallet adapter hooks.\n * @returns {TxAdapter} An object conforming to the `TxAdapter` interface.\n */\nexport function solanaAdapter<T extends Transaction<SolanaTransactionTracker>>(\n  config: SolanaAdapterConfig,\n): TxAdapter<SolanaTransactionTracker, T, SolanaActionTxKey> {\n  const { wallet, connection, explorerUrl, cluster } = config;\n\n  return {\n    key: TransactionAdapter.SOLANA,\n\n    // --- Core Methods ---\n    getWalletInfo: () => ({\n      walletAddress: wallet?.publicKey?.toBase58() ?? '0x0',\n      walletType: wallet?.wallet?.adapter.name.toLowerCase() ?? 'unknown',\n    }),\n\n    checkChainForTx: async (txCluster) => {\n      // Use the rpcEndpoint from the main connection context for pre-flight checks.\n      const currentRpcUrl = connection?.connection.rpcEndpoint;\n      if (!currentRpcUrl) {\n        // This can happen if the adapter is used in a read-only mode without a provider.\n        // We warn but do not throw, allowing tracking to continue if the rpcUrl is in the tx.\n        console.warn('Cannot check chain: connection context not provided to adapter.');\n        return;\n      }\n      await checkSolanaChain(currentRpcUrl, txCluster as SolanaCluster);\n    },\n\n    checkTransactionsTracker: (actionTxKey) => {\n      // For Solana, the actionTxKey is always the transaction signature.\n      return { tracker: SolanaTransactionTracker.Solana, txKey: actionTxKey };\n    },\n\n    checkAndInitializeTrackerInStore: ({ tx, ...rest }) => {\n      // Delegate to the tracker router utility.\n      return checkAndInitializeTrackerInStore({\n        tracker: tx.tracker,\n        tx,\n        ...rest,\n      });\n    },\n\n    // --- UI & Explorer Methods ---\n    getExplorerUrl: () => {\n      return explorerUrl ?? 'https://solscan.io';\n    },\n\n    getExplorerTxUrl: (txPool: TransactionPool<any, any>, txKey: string) => {\n      const baseUrl = explorerUrl ?? 'https://solscan.io';\n      return selectSolanaTxExplorerLink(baseUrl, txKey, cluster);\n    },\n\n    // --- Optional Name Service Methods ---\n    getName: async (address: string) => {\n      if (!connection) {\n        console.warn('Cannot get name: connection context not provided to adapter.');\n        return null;\n      }\n      return getSolanaName(connection, address);\n    },\n\n    getAvatar: async (name: string) => {\n      if (!connection) {\n        console.warn('Cannot get avatar: connection context not provided to adapter.');\n        return null;\n      }\n      return getSolanaAvatar(connection, name);\n    },\n\n    // --- Optional Actions ---\n    retryTxAction: async ({ actions, onClose, txKey, handleTransaction, tx }) => {\n      onClose(txKey);\n\n      if (!wallet) {\n        throw new Error('Retry failed: A wallet must be connected to retry a transaction.');\n      }\n      if (!handleTransaction) {\n        throw new Error('Retry failed: handleTransaction function is not provided.');\n      }\n\n      const actionKey = tx.actionKey;\n      if (!actionKey || !actions?.[actionKey]) {\n        throw new Error(`Retry failed: No action found for actionKey \"${actionKey}\".`);\n      }\n\n      const retryAction = actions[actionKey];\n\n      // Prioritize the RPC URL from the original transaction, falling back to the current connection.\n      const rpcUrlForRetry = tx.rpcUrl ?? connection?.connection.rpcEndpoint;\n      if (!rpcUrlForRetry) {\n        throw new Error('Retry failed: Could not determine RPC endpoint.');\n      }\n\n      const rpcForRetry = createSolanaRpc(rpcUrlForRetry);\n\n      await handleTransaction({\n        actionFunction: () =>\n          (retryAction as any)({\n            wallet,\n            connection: connection?.connection,\n            rpc: rpcForRetry,\n            ...tx.payload,\n          }),\n        params: tx,\n        defaultTracker: SolanaTransactionTracker.Solana,\n      });\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tuwaio/pulsar-solana",
+  "version": "0.1.0",
+  "private": false,
+  "author": "Oleksandr Tkach",
+  "license": "Apache-2.0",
+  "description": "An adapter for the Pulsar Engine that adds support for tracking transactions on the Solana blockchain. Integrates with @solana/kit and @solana/wallet-adapter-react.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "web3",
+    "solana",
+    "transaction",
+    "tracking",
+    "@solana/kit",
+    "zustand"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TuwaIO/pulsar-core.git",
+    "directory": "packages/pulsar-solana"
+  },
+  "homepage": "https://github.com/TuwaIO/pulsar-core",
+  "bugs": {
+    "url": "https://github.com/TuwaIO/pulsar-core/issues"
+  },
+  "contributors": [
+    {
+      "name": "Oleksandr Tkach",
+      "url": "https://github.com/Argeare5"
+    }
+  ],
+  "peerDependencies": {
+    "@bonfida/spl-name-service": ">=3",
+    "@solana/kit": ">=3",
+    "@solana/wallet-adapter-react": ">=0.15",
+    "@tuwaio/pulsar-core": ">=0",
+    "dayjs": ">=1",
+    "immer": ">=10",
+    "zustand": ">=5"
+  },
+  "devDependencies": {
+    "@bonfida/spl-name-service": "^3.0.16",
+    "@solana/kit": "^3.0.2",
+    "@solana/wallet-adapter-react": "^0.15.39",
+    "dayjs": "^1.11.18",
+    "immer": "^10.1.3",
+    "jsdom": "^26.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4",
+    "zustand": "^5.0.8",
+    "@tuwaio/pulsar-core": "^0.1.0"
+  },
+  "scripts": {
+    "start": "tsup src/index.ts --watch",
+    "build": "tsup",
+    "test": "vitest"
+  }
+}