@dynamic-labs/spark 4.30.0

package/src/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Global window interface extension for Spark wallet providers
+ */
+declare global {
+    interface IWindowSpark {
+        SparkProvider: ISparkProvider;
+    }
+    interface Window {
+        magicEden?: {
+            spark: ISparkProvider;
+        };
+    }
+}
+/**
+ * Interface that all Spark wallet providers must implement.
+ *
+ * This interface defines the contract that any Spark wallet provider must fulfill
+ * to be compatible with the Dynamic SDK. It includes core functionality for
+ * connection, authentication, and transactions.
+ *
+ * ## Design Philosophy
+ * This interface is designed to be **flexible and extensible** while maintaining
+ * a consistent contract. Different wallet implementations can use different
+ * naming conventions and return formats without breaking compatibility.
+ *
+ * ## Flexibility Features
+ * - **Dual Naming Support**: Supports both `sparkAddress`/`address` naming conventions
+ * - **Flexible Return Types**: Methods can return different formats (objects, strings, etc.)
+ * - **Optional Parameters**: Advanced features like `isTaproot` are optional with sensible defaults
+ * - **Extensible**: Additional properties are allowed via `[key: string]: unknown`
+ *
+ * ## Usage Examples
+ * ```typescript
+ * // Magic Eden style (sparkAddress naming)
+ * const result = await provider.connect();
+ * // result can be: string | { sparkAddress: string, sparkTaprootAddress?: string }
+ *
+ * // Generic style (address naming)
+ * const address = await provider.getAddress();
+ * // address can be: string | { address: string, taprootAddress?: string }
+ *
+ * // Simple message signing
+ * const signature = await provider.signMessage("Hello World");
+ * // Advanced signing with Taproot
+ * const signature = await provider.signMessage({ message: "Hello", isTaproot: true });
+ * ```
+ */
+export interface ISparkProvider {
+    /** Whether the wallet is currently connected */
+    isConnected: boolean;
+    /** The current network chain ID (e.g., '301' for mainnet) */
+    chainId?: string;
+    /** The current network name (e.g., 'mainnet', 'testnet') */
+    network?: string;
+    /**
+     * Establishes a connection to the wallet
+     * @returns Promise resolving to connection result with address information
+     */
+    connect(): Promise<SparkConnectionResult | string>;
+    /**
+     * Disconnects from the wallet
+     * @returns Promise that resolves when disconnected
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Retrieves the current wallet address
+     * @returns Promise resolving to address information
+     */
+    getAddress(): Promise<SparkAddressResult>;
+    /**
+     * Signs a message for authentication
+     * @param message - Message to sign or signing request object
+     * @returns Promise resolving to signature result
+     */
+    signMessage(message: string | SparkSignMessageRequest): Promise<SparkSignatureResult>;
+    /**
+     * Signs a message using Taproot protocol
+     * @param message - Message to sign
+     * @returns Promise resolving to signature result
+     */
+    signMessageWithTaproot(message: string): Promise<SparkSignatureResult>;
+    /**
+     * Transfers Bitcoin to another Spark address
+     * @param params - Transfer parameters
+     * @param params.receiverSparkAddress - The recipient's Spark address
+     * @param params.amountSats - Amount to transfer in satoshis
+     * @param params.isTaproot - Whether to use Taproot (defaults to false)
+     * @returns Promise resolving to transaction hash
+     */
+    transferBitcoin(params: {
+        receiverSparkAddress: string;
+        amountSats: bigint;
+        isTaproot?: boolean;
+    }): Promise<string>;
+    /**
+     * Transfers tokens to another Spark address
+     * @param params - Transfer parameters
+     * @param params.tokenPublicKey - The token's public key
+     * @param params.receiverSparkAddress - The recipient's Spark address
+     * @param params.tokenAmount - Amount of tokens to transfer
+     * @param params.isTaproot - Whether to use Taproot (defaults to false)
+     * @returns Promise resolving to transaction hash
+     */
+    transferTokens(params: {
+        tokenPublicKey: string;
+        receiverSparkAddress: string;
+        tokenAmount: number;
+        isTaproot?: boolean;
+    }): Promise<string>;
+    /**
+     * Generic RPC method for custom requests
+     * @param method - The RPC method name
+     * @param params - Optional parameters for the method
+     * @returns Promise resolving to the method result
+     */
+    request(method: string, params?: unknown): Promise<unknown>;
+    /** Additional properties that providers may implement */
+    [key: string]: unknown;
+}
+/**
+ * Result from wallet connection, supporting different naming conventions
+ */
+export type SparkConnectionResult = {
+    sparkAddress: string;
+    sparkTaprootAddress?: string;
+} | {
+    address: string;
+    taprootAddress?: string;
+};
+/**
+ * Result from address retrieval, supporting different formats
+ */
+export type SparkAddressResult = SparkConnectionResult | string;
+/**
+ * Message signing request, supporting both simple and advanced options
+ */
+export type SparkSignMessageRequest = {
+    message: string;
+    isTaproot?: boolean;
+} | string;
+/**
+ * Result from message signing, supporting different return formats
+ */
+export type SparkSignatureResult = {
+    signature: string;
+} | string;

package/src/utils/address.cjs

@@ -0,0 +1,27 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Utility functions for address handling
+ */
+/**
+ * Extracts address from flexible address result formats
+ * @param addressResult - The address result from a provider
+ * @returns The extracted address string, or undefined if not found
+ */
+const extractAddress = (addressResult) => {
+    if (!addressResult) {
+        return undefined;
+    }
+    if (typeof addressResult === 'string') {
+        return addressResult;
+    }
+    if (typeof addressResult === 'object') {
+        return addressResult.sparkAddress || addressResult.address;
+    }
+    return undefined;
+};
+
+exports.extractAddress = extractAddress;

package/src/utils/address.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for address handling
+ */
+/**
+ * Extracts address from flexible address result formats
+ * @param addressResult - The address result from a provider
+ * @returns The extracted address string, or undefined if not found
+ */
+export declare const extractAddress: (addressResult: string | {
+    sparkAddress?: string;
+    address?: string;
+}) => string | undefined;

package/src/utils/address.js

@@ -0,0 +1,23 @@
+'use client'
+/**
+ * Utility functions for address handling
+ */
+/**
+ * Extracts address from flexible address result formats
+ * @param addressResult - The address result from a provider
+ * @returns The extracted address string, or undefined if not found
+ */
+const extractAddress = (addressResult) => {
+    if (!addressResult) {
+        return undefined;
+    }
+    if (typeof addressResult === 'string') {
+        return addressResult;
+    }
+    if (typeof addressResult === 'object') {
+        return addressResult.sparkAddress || addressResult.address;
+    }
+    return undefined;
+};
+
+export { extractAddress };

package/src/utils/connection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility functions for connection result processing
+ */
+/**
+ * Extracts address from connection result objects
+ * @param connectResult - The result from a provider's connect() method
+ * @returns The extracted address string, or undefined if not found
+ */
+export declare const extractConnectionAddress: (connectResult: unknown) => string | undefined;

package/src/utils/provider.cjs

@@ -0,0 +1,23 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Utility functions for provider validation and error handling
+ */
+/**
+ * Asserts that a provider is available and throws an error if not
+ * @param provider - The provider to validate
+ * @param providerName - Human-readable name for error messages
+ * @returns The validated provider
+ * @throws {Error} If provider is not available
+ */
+const assertProvider = (provider, providerName) => {
+    if (!provider) {
+        throw new Error(`${providerName} provider not available`);
+    }
+    return provider;
+};
+
+exports.assertProvider = assertProvider;

package/src/utils/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility functions for provider validation and error handling
+ */
+/**
+ * Asserts that a provider is available and throws an error if not
+ * @param provider - The provider to validate
+ * @param providerName - Human-readable name for error messages
+ * @returns The validated provider
+ * @throws {Error} If provider is not available
+ */
+export declare const assertProvider: <T>(provider: T | undefined, providerName: string) => T;
+/**
+ * Creates a standardized error message for provider operations
+ * @param operation - The operation that failed (e.g., 'connect', 'sign message')
+ * @param providerName - The name of the provider
+ * @param error - The original error
+ * @returns A new Error with formatted message
+ */
+export declare const createProviderError: (operation: string, providerName: string, error: unknown) => Error;

package/src/utils/provider.js

@@ -0,0 +1,19 @@
+'use client'
+/**
+ * Utility functions for provider validation and error handling
+ */
+/**
+ * Asserts that a provider is available and throws an error if not
+ * @param provider - The provider to validate
+ * @param providerName - Human-readable name for error messages
+ * @returns The validated provider
+ * @throws {Error} If provider is not available
+ */
+const assertProvider = (provider, providerName) => {
+    if (!provider) {
+        throw new Error(`${providerName} provider not available`);
+    }
+    return provider;
+};
+
+export { assertProvider };

package/src/wallet/SparkWallet.cjs

@@ -0,0 +1,42 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../_virtual/_tslib.cjs');
+var walletConnectorCore = require('@dynamic-labs/wallet-connector-core');
+
+class SparkWallet extends walletConnectorCore.Wallet {
+    sendBalance(_a) {
+        return _tslib.__awaiter(this, arguments, void 0, function* ({ amount, toAddress, isTaproot, }) {
+            return this.transferBitcoin({
+                amount,
+                isTaproot,
+                toAddress,
+            });
+        });
+    }
+    transferBitcoin(_a) {
+        return _tslib.__awaiter(this, arguments, void 0, function* ({ amount, toAddress, isTaproot, }) {
+            yield this.sync();
+            return this._connector.transferBitcoin({
+                amountSats: BigInt(amount),
+                isTaproot,
+                receiverSparkAddress: toAddress,
+            });
+        });
+    }
+    transferTokens(_a) {
+        return _tslib.__awaiter(this, arguments, void 0, function* ({ tokenPublicKey, receiverSparkAddress, tokenAmount, isTaproot, }) {
+            yield this.sync();
+            return this._connector.transferTokens({
+                isTaproot,
+                receiverSparkAddress,
+                tokenAmount,
+                tokenPublicKey,
+            });
+        });
+    }
+}
+
+exports.SparkWallet = SparkWallet;

package/src/wallet/SparkWallet.d.ts

@@ -0,0 +1,20 @@
+import { Wallet } from '@dynamic-labs/wallet-connector-core';
+import type { SparkWalletConnector } from '../connectors/SparkWalletConnector';
+export declare class SparkWallet extends Wallet<SparkWalletConnector> {
+    sendBalance({ amount, toAddress, isTaproot, }: {
+        amount: string;
+        toAddress: string;
+        isTaproot?: boolean;
+    }): Promise<string | undefined>;
+    transferBitcoin({ amount, toAddress, isTaproot, }: {
+        amount: string;
+        toAddress: string;
+        isTaproot?: boolean;
+    }): Promise<string | undefined>;
+    transferTokens({ tokenPublicKey, receiverSparkAddress, tokenAmount, isTaproot, }: {
+        tokenPublicKey: string;
+        receiverSparkAddress: string;
+        tokenAmount: number;
+        isTaproot?: boolean;
+    }): Promise<string | undefined>;
+}

package/src/wallet/SparkWallet.js

@@ -0,0 +1,38 @@
+'use client'
+import { __awaiter } from '../../_virtual/_tslib.js';
+import { Wallet } from '@dynamic-labs/wallet-connector-core';
+
+class SparkWallet extends Wallet {
+    sendBalance(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ amount, toAddress, isTaproot, }) {
+            return this.transferBitcoin({
+                amount,
+                isTaproot,
+                toAddress,
+            });
+        });
+    }
+    transferBitcoin(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ amount, toAddress, isTaproot, }) {
+            yield this.sync();
+            return this._connector.transferBitcoin({
+                amountSats: BigInt(amount),
+                isTaproot,
+                receiverSparkAddress: toAddress,
+            });
+        });
+    }
+    transferTokens(_a) {
+        return __awaiter(this, arguments, void 0, function* ({ tokenPublicKey, receiverSparkAddress, tokenAmount, isTaproot, }) {
+            yield this.sync();
+            return this._connector.transferTokens({
+                isTaproot,
+                receiverSparkAddress,
+                tokenAmount,
+                tokenPublicKey,
+            });
+        });
+    }
+}
+
+export { SparkWallet };

package/src/wallet/index.d.ts

@@ -0,0 +1,2 @@
+export { SparkWallet } from './SparkWallet';
+export * from './isSparkWallet';

package/src/wallet/isSparkWallet/index.d.ts

@@ -0,0 +1 @@
+export * from './isSparkWallet';

package/src/wallet/isSparkWallet/isSparkWallet.cjs

@@ -0,0 +1,8 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const isSparkWallet = (wallet) => wallet.chain === 'SPARK';
+
+exports.isSparkWallet = isSparkWallet;

package/src/wallet/isSparkWallet/isSparkWallet.d.ts

@@ -0,0 +1,3 @@
+import { Wallet } from '@dynamic-labs/wallet-connector-core';
+import type { SparkWalletConnector } from '../../connectors/SparkWalletConnector';
+export declare const isSparkWallet: (wallet: Wallet) => wallet is Wallet<SparkWalletConnector>;

package/src/wallet/isSparkWallet/isSparkWallet.js

@@ -0,0 +1,4 @@
+'use client'
+const isSparkWallet = (wallet) => wallet.chain === 'SPARK';
+
+export { isSparkWallet };