@dynamic-labs/spark 4.30.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Dynamic Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @dynamic-labs/spark
+
+A Spark wallet connector package for the Dynamic SDK that enables seamless integration with Spark network wallets.
+
+## Features
+
+- **Magic Eden Wallet Support** - Full integration with Magic Eden's Spark wallet
+- **Flexible Provider Interface** - Easy to add support for additional Spark wallets
+- **Bitcoin Transfers** - Send Bitcoin to Spark addresses with optional Taproot support
+- **Token Transfers** - Transfer tokens between Spark addresses
+- **Message Signing** - Sign messages for authentication with optional Taproot support
+- **Mainnet Support** - Currently supports Spark mainnet (chain ID 301)
+
+## Installation
+
+```bash
+npm install @dynamic-labs/spark
+```
+
+## 🔌 Supported Wallets
+
+### Magic Eden
+
+The package includes full support for Magic Eden's Spark wallet implementation, which provides:
+
+- **Connection Management** - Seamless wallet connection and disconnection
+- **Address Retrieval** - Get current wallet address
+- **Message Signing** - Sign messages for authentication with optional Taproot support
+- **Bitcoin Transfers** - Send Bitcoin to other Spark addresses
+- **Token Transfers** - Transfer tokens between Spark addresses
+
+## Architecture
+
+### Base Connector Class
+
+The `SparkWalletConnector` provides a robust foundation for all Spark wallet integrations:
+
+- **Abstract Implementation** - Handles common wallet operations
+- **Error Handling** - Comprehensive error handling and logging
+- **Mainnet Focus** - Currently optimized for mainnet usage
+
+### Provider Interface
+
+All Spark wallet providers must implement the `ISparkProvider` interface:
+
+```typescript
+interface ISparkProvider {
+  isConnected: boolean;
+  chainId?: string;
+  network?: string;
+
+  connect(): Promise<SparkConnectionResult | string>;
+  disconnect(): Promise<void>;
+  getAddress(): Promise<SparkAddressResult>;
+  signMessage(
+    message: string | SparkSignMessageRequest,
+  ): Promise<SparkSignatureResult>;
+  signMessageWithTaproot(message: string): Promise<SparkSignatureResult>;
+  transferBitcoin(params: {
+    receiverSparkAddress: string;
+    amountSats: bigint;
+    isTaproot?: boolean;
+  }): Promise<string>;
+  transferTokens(params: {
+    tokenPublicKey: string;
+    receiverSparkAddress: string;
+    tokenAmount: number;
+    isTaproot?: boolean;
+  }): Promise<string>;
+  request(method: string, params?: unknown): Promise<unknown>;
+
+  [key: string]: unknown; // Extensible for additional properties
+}
+```
+
+## 🌐 Supported Networks
+
+| Network     | Chain ID | Description        | Block Explorer                         |
+| ----------- | -------- | ------------------ | -------------------------------------- |
+| **Mainnet** | 301      | Production network | [mempool.space](https://mempool.space) |
+
+> **Note**: Currently only mainnet is supported. Testnet, signet, and regtest support may be added in future versions.
+
+## 📖 Usage
+
+### Basic Integration
+
+```typescript
+import { DynamicContextProvider } from '@dynamic-labs/sdk-react-core';
+import { SparkWalletConnectors } from '@dynamic-labs/spark';
+
+function App() {
+  return (
+    <DynamicContextProvider
+      settings={{
+        environmentId: 'your-environment-id',
+        walletConnectors: [SparkWalletConnectors()],
+      }}
+    >
+      {/* Your app content */}
+    </DynamicContextProvider>
+  );
+}
+```
+
+### Using the SparkWallet
+
+```typescript
+import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
+import { SparkWallet } from '@dynamic-labs/spark';
+
+function MyComponent() {
+  const { primaryWallet } = useDynamicContext();
+
+  const handleSendBitcoin = async () => {
+    if (primaryWallet instanceof SparkWallet) {
+      // Send Bitcoin
+      const txHash = await primaryWallet.sendBalance({
+        amount: '100000', // 100,000 satoshis
+        toAddress: 'sp1recipient123456789abcdef',
+        isTaproot: false,
+      });
+
+      // Or use the direct transferBitcoin method
+      const txHash2 = await primaryWallet.transferBitcoin({
+        amount: '50000',
+        toAddress: 'sp1recipient123456789abcdef',
+        isTaproot: true,
+      });
+    }
+  };
+
+  const handleSendTokens = async () => {
+    if (primaryWallet instanceof SparkWallet) {
+      const txHash = await primaryWallet.transferTokens({
+        tokenPublicKey: 'token123',
+        receiverSparkAddress: 'sp1recipient123456789abcdef',
+        tokenAmount: 1000,
+        isTaproot: false,
+      });
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleSendBitcoin}>Send Bitcoin</button>
+      <button onClick={handleSendTokens}>Send Tokens</button>
+    </div>
+  );
+}
+```
+
+### Custom Connector Implementation
+
+To add support for a new Spark wallet:
+
+```typescript
+import { SparkWalletConnector } from '@dynamic-labs/spark';
+
+export class YourSparkConnector extends SparkWalletConnector {
+  override name = 'Your Spark Wallet';
+  override overrideKey = 'yourspark';
+
+  public override getProvider(): ISparkProvider | undefined {
+    return window.yourProvider;
+  }
+}
+```
+
+### Type Checking
+
+Use the `isSparkWallet` type guard to safely work with Spark wallets:
+
+```typescript
+import { isSparkWallet } from '@dynamic-labs/spark';
+
+function handleWallet(wallet: Wallet) {
+  if (isSparkWallet(wallet)) {
+    // TypeScript now knows this is a SparkWallet
+    wallet.transferBitcoin({
+      amount: '100000',
+      toAddress: 'sp1recipient123456789abcdef',
+    });
+  }
+}
+```
+
+## 🧪 Testing
+
+### Run Tests
+
+```bash
+npx nx test spark
+```
+
+### Build Package
+
+```bash
+npx nx build spark
+```
+
+### Test in Demo App
+
+1. Start the demo app: `npm run start`
+2. Navigate to the Spark wallet section
+3. Test connection, address retrieval, and message signing
+
+## 📚 API Reference
+
+### Core Exports
+
+- `SparkWalletConnectors()` - Factory function returning all available connectors
+- `SparkWalletConnector` - Base class for custom implementations
+- `SparkWallet` - Wallet class with Bitcoin and token transfer methods
+- `ISparkProvider` - Interface for wallet providers
+- `isSparkWallet` - Type guard for Spark wallets
+
+### SparkWallet Methods
+
+- `sendBalance(params)` - Send Bitcoin (alias for transferBitcoin)
+- `transferBitcoin(params)` - Send Bitcoin to a Spark address
+- `transferTokens(params)` - Send tokens to a Spark address
+
+### Type Definitions
+
+- `SparkConnectionResult` - Result from wallet connection
+- `SparkAddressResult` - Result from address retrieval
+- `SparkSignMessageRequest` - Message signing request options
+- `SparkSignatureResult` - Result from message signing
+
+## 🔗 Related Packages
+
+- **@dynamic-labs/sdk-react-core** - React SDK core functionality
+- **@dynamic-labs/wallet-connector-core** - Base wallet connector classes
+- **@dynamic-labs/types** - Common type definitions
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [contributing guidelines](https://github.com/dynamic-labs/dynamic-sdk/blob/main/CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Run tests: `npx nx test spark`
+4. Build package: `npx nx build spark`
+
+### Adding New Wallets
+
+1. Create a new connector class extending `SparkWalletConnector`
+2. Implement the `getProvider()` method
+3. Add comprehensive tests
+4. Update the `SparkWalletConnectors()` factory function
+
+## 📄 License
+
+This package is part of the Dynamic SDK and follows the same licensing terms. See [LICENSE](https://github.com/dynamic-labs/dynamic-sdk/blob/main/LICENSE) for details.
+
+## 🆘 Support
+
+- **Documentation**: [docs.dynamic.xyz](https://docs.dynamic.xyz)
+- **GitHub Issues**: [Report bugs or request features](https://github.com/dynamic-labs/dynamic-sdk/issues)
+- **Discord**: [Join our community](https://discord.gg/dynamic)
+
+---
+
+**Built with ❤️ by the Dynamic Labs team**

package/_virtual/_tslib.cjs

@@ -0,0 +1,36 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+exports.__awaiter = __awaiter;

package/_virtual/_tslib.js

@@ -0,0 +1,32 @@
+'use client'
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+export { __awaiter };

package/package.cjs

@@ -0,0 +1,8 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var version = "4.30.0";
+
+exports.version = version;

package/package.js

@@ -0,0 +1,4 @@
+'use client'
+var version = "4.30.0";
+
+export { version };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dynamic-labs/spark",
+  "version": "4.30.0",
+  "description": "A React SDK for implementing wallet web3 authentication and authorization to your website.",
+  "author": "Dynamic Labs, Inc.",
+  "license": "MIT",
+  "main": "./src/index.cjs",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "homepage": "https://www.dynamic.xyz/",
+  "dependencies": {
+    "@dynamic-labs/assert-package-version": "4.30.0",
+    "@dynamic-labs/types": "4.30.0",
+    "@dynamic-labs/utils": "4.30.0",
+    "@dynamic-labs/wallet-book": "4.30.0",
+    "@dynamic-labs/wallet-connector-core": "4.30.0"
+  },
+  "peerDependencies": {}
+}

package/src/connectors/MagicEdenSparkConnector/MagicEdenSparkConnector.cjs

@@ -0,0 +1,57 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../../_virtual/_tslib.cjs');
+var walletBook = require('@dynamic-labs/wallet-book');
+var utils = require('@dynamic-labs/utils');
+var SparkWalletConnector = require('../SparkWalletConnector/SparkWalletConnector.cjs');
+
+/**
+ * Magic Eden Spark wallet connector implementation.
+ *
+ * Handles Magic Eden's specific interface requirements while leveraging
+ * the base class's flexible type handling.
+ */
+class MagicEdenSparkConnector extends SparkWalletConnector.SparkWalletConnector {
+    /**
+     * Creates a new Magic Eden Spark connector
+     * @param opts - Configuration options
+     */
+    constructor(opts) {
+        super(opts);
+        /** Human-readable connector name */
+        this.name = 'Magic Eden Spark';
+        /** Unique identifier for this connector type */
+        this.overrideKey = 'magicedenspark';
+    }
+    /**
+     * Returns the Magic Eden Spark provider from the window object
+     * @returns The SparkProvider instance, or undefined if not available
+     */
+    getProvider() {
+        const providers = utils.getProvidersFromWindow('magicEden.spark');
+        return providers[0];
+    }
+    /**
+     * Retrieves the wallet address with Magic Eden specific error handling
+     * @returns The wallet address as a string, or undefined if unavailable
+     */
+    getAddress() {
+        const _super = Object.create(null, {
+            getAddress: { get: () => super.getAddress }
+        });
+        return _tslib.__awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield _super.getAddress.call(this);
+            }
+            catch (error) {
+                walletBook.logger.warn('Failed to get address from Magic Eden Spark wallet:', error);
+                return undefined;
+            }
+        });
+    }
+}
+
+exports.MagicEdenSparkConnector = MagicEdenSparkConnector;

package/src/connectors/MagicEdenSparkConnector/MagicEdenSparkConnector.d.ts

@@ -0,0 +1,29 @@
+import { SparkWalletConnector, SparkWalletConnectorOpts } from '../SparkWalletConnector';
+import type { ISparkProvider } from '../../types';
+/**
+ * Magic Eden Spark wallet connector implementation.
+ *
+ * Handles Magic Eden's specific interface requirements while leveraging
+ * the base class's flexible type handling.
+ */
+export declare class MagicEdenSparkConnector extends SparkWalletConnector {
+    /** Human-readable connector name */
+    name: string;
+    /** Unique identifier for this connector type */
+    overrideKey: string;
+    /**
+     * Creates a new Magic Eden Spark connector
+     * @param opts - Configuration options
+     */
+    constructor(opts: SparkWalletConnectorOpts);
+    /**
+     * Returns the Magic Eden Spark provider from the window object
+     * @returns The SparkProvider instance, or undefined if not available
+     */
+    getProvider(): ISparkProvider | undefined;
+    /**
+     * Retrieves the wallet address with Magic Eden specific error handling
+     * @returns The wallet address as a string, or undefined if unavailable
+     */
+    getAddress(): Promise<string | undefined>;
+}

package/src/connectors/MagicEdenSparkConnector/MagicEdenSparkConnector.js

@@ -0,0 +1,53 @@
+'use client'
+import { __awaiter } from '../../../_virtual/_tslib.js';
+import { logger } from '@dynamic-labs/wallet-book';
+import { getProvidersFromWindow } from '@dynamic-labs/utils';
+import { SparkWalletConnector } from '../SparkWalletConnector/SparkWalletConnector.js';
+
+/**
+ * Magic Eden Spark wallet connector implementation.
+ *
+ * Handles Magic Eden's specific interface requirements while leveraging
+ * the base class's flexible type handling.
+ */
+class MagicEdenSparkConnector extends SparkWalletConnector {
+    /**
+     * Creates a new Magic Eden Spark connector
+     * @param opts - Configuration options
+     */
+    constructor(opts) {
+        super(opts);
+        /** Human-readable connector name */
+        this.name = 'Magic Eden Spark';
+        /** Unique identifier for this connector type */
+        this.overrideKey = 'magicedenspark';
+    }
+    /**
+     * Returns the Magic Eden Spark provider from the window object
+     * @returns The SparkProvider instance, or undefined if not available
+     */
+    getProvider() {
+        const providers = getProvidersFromWindow('magicEden.spark');
+        return providers[0];
+    }
+    /**
+     * Retrieves the wallet address with Magic Eden specific error handling
+     * @returns The wallet address as a string, or undefined if unavailable
+     */
+    getAddress() {
+        const _super = Object.create(null, {
+            getAddress: { get: () => super.getAddress }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield _super.getAddress.call(this);
+            }
+            catch (error) {
+                logger.warn('Failed to get address from Magic Eden Spark wallet:', error);
+                return undefined;
+            }
+        });
+    }
+}
+
+export { MagicEdenSparkConnector };

package/src/connectors/MagicEdenSparkConnector/index.d.ts

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