@n1xyz/wallet-widget 0.0.1 → 0.0.5

package/LICENSE

@@ -0,0 +1,44 @@
+SOFTWARE LICENSE AGREEMENT
+
+Copyright (c) 2024 N1 Labs. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are protected by copyright laws 
+and international treaties. The following terms govern your use of the Software:
+
+1. PERMISSIONS
+   You are permitted to:
+   a) Install and use the Software through official npm packages
+   b) Use the Software as part of your applications
+   c) Create and distribute applications that use the Software as a dependency
+
+2. RESTRICTIONS
+   You may not:
+   a) Modify, adapt, or create derivative works of the Software
+   b) Reverse engineer, decompile, or disassemble the Software
+   c) Remove or modify any copyright or proprietary notices
+   d) Redistribute the Software except through official npm package dependencies
+   e) Fork or create alternate distributions of the Software
+
+3. OWNERSHIP
+   The Software is owned by N1 Labs and is protected by copyright laws and international treaty 
+   provisions. N1 Labs retains all rights not expressly granted to you in this Agreement.
+
+4. DISTRIBUTION
+   The Software may only be distributed through the official npm registry as a package dependency.
+   You may list this package as a dependency in your package.json, but may not include its source
+   code in your projects.
+
+5. NO WARRANTIES
+   The Software is provided "AS IS" without warranty of any kind. N1 Labs disclaims all 
+   warranties, expressed or implied, including but not limited to the implied warranties 
+   of merchantability and fitness for a particular purpose.
+
+6. LIMITATION OF LIABILITY
+   In no event shall N1 Labs be liable for any damages whatsoever arising out of the use 
+   of or inability to use the Software.
+
+7. TERMINATION
+   This license will terminate automatically if you fail to comply with any of the terms 
+   and conditions of this Agreement. Upon termination, you must cease all use of the Software.
+
+For licensing inquiries, please contact: legal@n1.xyz 

package/README.md

@@ -0,0 +1,210 @@
+# N1 Wallet Widget
+
+A React component library for integrating N1 wallet functionality into your application. This widget provides a seamless way to connect to blockchain wallets, manage sessions, and perform wallet operations.
+
+## Features
+
+- Wallet connection and authentication
+- Session management (Nord and NTS modes)
+- Transaction signing
+- Message signing
+- Balance display
+- Error handling
+- Dark/light mode support
+- Customizable UI
+
+## Installation
+
+```bash
+npm install @n1xyz/wallet-widget
+# or
+yarn add @n1xyz/wallet-widget
+```
+
+## Quick Start
+
+```jsx
+import { N1WalletProvider, N1SessionMode } from '@n1xyz/wallet-widget';
+import { Nord } from '@n1xyz/nord-ts';
+
+// Initialize Nord client
+const nord = new Nord({
+  // Your Nord configuration
+});
+
+function App() {
+  return (
+    <N1WalletProvider 
+      providedSessionMode={N1SessionMode.Nord} 
+      appId="your-app-id"
+      nord={nord}
+    >
+      {/* Your application components */}
+    </N1WalletProvider>
+  );
+}
+```
+
+## Usage
+
+The wallet widget provides a React context that can be accessed throughout your application to interact with the wallet functionality.
+
+### Accessing Wallet Context
+
+```jsx
+import { useN1WalletContext } from '@n1xyz/wallet-widget';
+
+function WalletInfo() {
+  const { 
+    address, 
+    isConnected, 
+    balances, 
+    username,
+    setShowLogin
+  } = useN1WalletContext();
+
+  return (
+    <div>
+      {isConnected ? (
+        <>
+          <p>Connected as: {username}</p>
+          <p>Address: {address}</p>
+          <p>Balances: {balances.map(b => `${b.balance} ${b.appType}`).join(', ')}</p>
+        </>
+      ) : (
+        <button onClick={() => setShowLogin(true)}>Connect Wallet</button>
+      )}
+    </div>
+  );
+}
+```
+
+### Signing Messages and Transactions
+
+```jsx
+import { useN1WalletContext } from '@n1xyz/wallet-widget';
+
+function SigningExample() {
+  const { 
+    signMessageWithSessionKey,
+    signMessageWithWalletKey,
+    signTransactionWithWalletKey
+  } = useN1WalletContext();
+
+  const handleSignMessage = async () => {
+    if (signMessageWithSessionKey) {
+      const message = { content: "Hello, world!" };
+      const signature = await signMessageWithSessionKey(message);
+      console.log("Signature:", signature);
+    }
+  };
+
+  return (
+    <button onClick={handleSignMessage}>Sign Message</button>
+  );
+}
+```
+
+## API Reference
+
+### N1WalletProvider Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| children | React.ReactNode | Yes | - | Child components |
+| providedSessionMode | N1SessionMode | Yes | - | Session mode (Nord or NTS) |
+| appId | string | Yes | - | Your application ID |
+| darkMode | boolean | No | true | Enable dark mode UI |
+| onError | (error: WalletError) => void | No | - | Error handler callback |
+| faucetUrl | string | No | - | URL for faucet service |
+| nord | Nord | No | - | Nord instance (required for Nord mode) |
+
+### N1SessionMode
+
+```typescript
+enum N1SessionMode {
+  Nord,
+  NTS
+}
+```
+
+### N1WalletContext
+
+The context provides the following values:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| address | string | User's wallet address |
+| appId | string | Application ID |
+| balances | Balance[] | User's token balances |
+| chain | string | Current blockchain |
+| isConnected | boolean | Connection status |
+| sessionMode | N1SessionMode | Current session mode |
+| sessionPubKey | Uint8Array | Session public key |
+| setShowLogin | (show: boolean) => void | Show/hide login modal |
+| showLogin | boolean | Login modal visibility state |
+| signMessageWithSessionKey | (message: any) => Promise<any> | Sign message with session key |
+| signMessageWithWalletKey | (message: any) => Promise<any> | Sign message with wallet key |
+| signTransactionWithWalletKey | (transaction: any) => Promise<any> | Sign transaction with wallet key |
+| username | string | User's username |
+| walletPubKey | Uint8Array | Wallet public key |
+
+## Error Handling
+
+The wallet widget includes a built-in error boundary that catches and processes wallet-related errors. You can provide a custom error handler through the `onError` prop:
+
+```jsx
+<N1WalletProvider
+  providedSessionMode={N1SessionMode.Nord}
+  appId="your-app-id"
+  onError={(error) => {
+    console.error("Wallet error:", error.code, error.message);
+    // Handle error appropriately
+  }}
+>
+  {/* Your application */}
+</N1WalletProvider>
+```
+
+## Examples
+
+### Nord Mode Integration
+
+```jsx
+import { useEffect, useState } from 'react';
+import { N1WalletProvider, N1SessionMode } from '@n1xyz/wallet-widget';
+import { Nord } from '@n1xyz/nord-ts';
+
+function App() {
+  const [nord, setNord] = useState(null);
+
+  useEffect(() => {
+    async function initNord() {
+      const nordClient = new Nord({
+        // Your Nord configuration
+      });
+      await nordClient.initialize();
+      setNord(nordClient);
+    }
+    
+    initNord();
+  }, []);
+
+  if (!nord) return <div>Loading...</div>;
+
+  return (
+    <N1WalletProvider 
+      providedSessionMode={N1SessionMode.Nord} 
+      appId="your-app-id"
+      faucetUrl="https://your-faucet-url.com/api/faucet"
+      nord={nord}
+    >
+      <YourApplication />
+    </N1WalletProvider>
+  );
+}
+```
+
+## License
+
+[MIT License](LICENSE)

package/dist/Logic/sessionManager.d.ts

@@ -0,0 +1,53 @@
+import { N1SessionMode } from '../Provider/types';
+/**
+ * Interface for session key data stored in local storage
+ */
+export interface SessionKeyData {
+    ed25519PrivateKey: Uint8Array;
+    walletPublicKey: string;
+    chainName: string;
+    createdAt: string;
+    sessionMode: N1SessionMode;
+}
+/**
+ * Generate a new session key pair
+ * @returns Promise resolving to the generated key pair
+ */
+export declare function generateSessionKeys(): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}>;
+/**
+ * Create a signing function for the given key pair
+ * @param privateKey The private key to use for signing
+ * @returns A function that signs messages with the private key
+ */
+export declare function createSigningFunction(privateKey: Uint8Array): (message: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Store session keys in local storage
+ * @param data The session key data to store
+ */
+export declare function storeSessionKeys({ privKey, walletPublicKey, chainName, sessionMode }: {
+    privKey: Uint8Array;
+    walletPublicKey: string;
+    chainName: string;
+    sessionMode: N1SessionMode;
+}): void;
+/**
+ * Retrieve session keys from local storage
+ * @param walletPublicKey The wallet public key to retrieve session keys for
+ * @returns The session key data or null if not found
+ */
+export declare function getSessionKeys(walletPublicKey: string): SessionKeyData | null;
+/**
+ * Remove session keys from local storage
+ * @param walletPublicKey The wallet public key to remove session keys for
+ */
+export declare function removeSessionKeys(walletPublicKey: string): void;
+/**
+ * Check if a session exists and is valid
+ * @param walletPublicKey The wallet public key to check
+ * @param sessionMode The session mode to check
+ * @returns Whether a valid session exists
+ */
+export declare function hasValidSession(walletPublicKey: string, sessionMode: N1SessionMode): Promise<boolean>;

package/dist/Logic/sessionManager.js

@@ -0,0 +1,178 @@
+var __awaiter = (this && this.__awaiter) || function (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());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { generateSessionKeyPair, signEd25519 } from '@n1xyz/nts-sdk';
+import { N1SessionMode } from '../Provider/types';
+import { logger } from '../utils/logger';
+import { arrayBufferToBase64, base64ToUint8Array } from './utils';
+/**
+ * Generate a new session key pair
+ * @returns Promise resolving to the generated key pair
+ */
+export function generateSessionKeys() {
+    return __awaiter(this, void 0, void 0, function () {
+        var error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, generateSessionKeyPair()];
+                case 1: return [2 /*return*/, _a.sent()];
+                case 2:
+                    error_1 = _a.sent();
+                    logger.error('Failed to generate session keys', error_1);
+                    throw error_1;
+                case 3: return [2 /*return*/];
+            }
+        });
+    });
+}
+/**
+ * Create a signing function for the given key pair
+ * @param privateKey The private key to use for signing
+ * @returns A function that signs messages with the private key
+ */
+export function createSigningFunction(privateKey) {
+    var _this = this;
+    return function (message) { return __awaiter(_this, void 0, void 0, function () {
+        var error_2;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, signEd25519(message, privateKey)];
+                case 1: return [2 /*return*/, _a.sent()];
+                case 2:
+                    error_2 = _a.sent();
+                    logger.error('Error signing with session key', error_2);
+                    throw error_2;
+                case 3: return [2 /*return*/];
+            }
+        });
+    }); };
+}
+/**
+ * Store session keys in local storage
+ * @param data The session key data to store
+ */
+export function storeSessionKeys(_a) {
+    var privKey = _a.privKey, walletPublicKey = _a.walletPublicKey, chainName = _a.chainName, sessionMode = _a.sessionMode;
+    var storageKey = "n1_sessionKey_".concat(walletPublicKey);
+    var data = {
+        ed25519PrivateKey: arrayBufferToBase64(privKey),
+        walletPublicKey: walletPublicKey,
+        chainName: chainName,
+        createdAt: new Date().toISOString(),
+        sessionMode: sessionMode.toString()
+    };
+    localStorage.setItem(storageKey, JSON.stringify(data));
+    logger.debug('Session keys stored in local storage', { walletPublicKey: walletPublicKey, sessionMode: sessionMode });
+}
+/**
+ * Retrieve session keys from local storage
+ * @param walletPublicKey The wallet public key to retrieve session keys for
+ * @returns The session key data or null if not found
+ */
+export function getSessionKeys(walletPublicKey) {
+    var storageKey = "n1_sessionKey_".concat(walletPublicKey);
+    var data = localStorage.getItem(storageKey);
+    if (!data) {
+        return null;
+    }
+    try {
+        var parsedData = JSON.parse(data);
+        if (parsedData.ed25519PrivateKey) {
+            parsedData.ed25519PrivateKey = base64ToUint8Array(parsedData.ed25519PrivateKey);
+        }
+        // Convert sessionMode string to enum value
+        if (typeof parsedData.sessionMode === 'string') {
+            parsedData.sessionMode = parsedData.sessionMode === N1SessionMode.Nord.toString()
+                ? N1SessionMode.Nord
+                : N1SessionMode.NTS;
+        }
+        else if (parsedData.sessionMode === undefined) {
+            // For backward compatibility, default to NTS mode if not specified
+            parsedData.sessionMode = N1SessionMode.NTS;
+        }
+        return parsedData;
+    }
+    catch (error) {
+        logger.error('Failed to parse session key data', error);
+        return null;
+    }
+}
+/**
+ * Remove session keys from local storage
+ * @param walletPublicKey The wallet public key to remove session keys for
+ */
+export function removeSessionKeys(walletPublicKey) {
+    var storageKey = "n1_sessionKey_".concat(walletPublicKey);
+    localStorage.removeItem(storageKey);
+    logger.debug('Session keys removed from local storage', { walletPublicKey: walletPublicKey });
+}
+/**
+ * Check if a session exists and is valid
+ * @param walletPublicKey The wallet public key to check
+ * @param sessionMode The session mode to check
+ * @returns Whether a valid session exists
+ */
+export function hasValidSession(walletPublicKey, sessionMode) {
+    return __awaiter(this, void 0, void 0, function () {
+        var sessionData, createdAt, now, sessionAgeMs, maxSessionAgeMs;
+        return __generator(this, function (_a) {
+            sessionData = getSessionKeys(walletPublicKey);
+            if (!sessionData) {
+                return [2 /*return*/, false];
+            }
+            // Check if the session mode matches
+            if (sessionData.sessionMode !== sessionMode) {
+                return [2 /*return*/, false];
+            }
+            createdAt = new Date(sessionData.createdAt);
+            now = new Date();
+            sessionAgeMs = now.getTime() - createdAt.getTime();
+            maxSessionAgeMs = 7 * 24 * 60 * 60 * 1000;
+            if (sessionAgeMs > maxSessionAgeMs) {
+                // Session is expired, remove it
+                removeSessionKeys(walletPublicKey);
+                return [2 /*return*/, false];
+            }
+            // TODO: Add additional validation based on session mode
+            // For example, verify the session with the backend
+            return [2 /*return*/, true];
+        });
+    });
+}

package/dist/Logic/transactionManager.d.ts

@@ -0,0 +1,41 @@
+import { N1SessionMode } from '../Provider/types';
+/**
+ * Interface for transaction data
+ */
+export interface TransactionData {
+    chainId: string;
+    amount: string;
+    tokenSymbol: string;
+    walletAddress: string;
+    sessionMode: N1SessionMode;
+}
+/**
+ * Interface for transaction result
+ */
+export interface TransactionResult {
+    success: boolean;
+    transactionId: string;
+    amount: string;
+    tokenSymbol: string;
+    fromAddress: string;
+    toAddress: string;
+    networkName: string;
+    status: 'Completed' | 'Failed' | 'Pending';
+    explorerUrl?: string;
+    error?: Error;
+}
+/**
+ * Create and send a transaction
+ * @param data Transaction data
+ * @param signMessage Function to sign messages with wallet
+ * @returns Transaction result
+ */
+export declare function createAndSendTransaction(data: TransactionData, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<TransactionResult>;
+/**
+ * Get explorer URL for a transaction
+ */
+export declare function getExplorerUrl(transactionId: string, chainId: string): string;
+/**
+ * Check transaction status
+ */
+export declare function checkTransactionStatus(transactionId: string, chainId: string, sessionMode: N1SessionMode): Promise<'Completed' | 'Failed' | 'Pending'>;