@qrlwallet/connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalGuards
+
+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,247 @@
+# @qrlwallet/connect
+
+Connect your dApp to QRL Wallet. Users scan a QR code (desktop) or tap a button (mobile) to pair their wallet, then approve transactions right from the app.
+
+## How it works
+
+1. Your dApp generates a connection URI and shows it as a QR code
+2. User scans with the QRL Wallet app (or taps a deep link on mobile)
+3. An encrypted channel is established through our relay server
+4. Your dApp sends JSON-RPC requests, the wallet prompts for approval
+5. Signed results come back to your dApp
+
+All communication is end-to-end encrypted (ECIES). The relay server never sees your data.
+
+## Install
+
+```bash
+npm install @qrlwallet/connect
+```
+
+## Quick start
+
+```typescript
+import { QRLConnect } from '@qrlwallet/connect';
+
+const qrl = new QRLConnect({
+  dappMetadata: {
+    name: 'My QRL dApp',
+    url: 'https://mydapp.com',
+  },
+});
+
+// Get the connection URI
+const uri = await qrl.getConnectionURI();
+
+// Desktop: render as QR code (use any QR library)
+// Mobile: redirect to open the wallet app
+if (qrl.isMobile()) {
+  window.location.href = uri;
+} else {
+  // render uri as QR code
+}
+
+// Listen for connection
+qrl.on('connect', ({ chainId }) => {
+  console.log('Wallet connected on chain', chainId);
+});
+
+qrl.on('accountsChanged', (accounts) => {
+  console.log('Connected accounts:', accounts);
+});
+
+qrl.on('statusChanged', (status) => {
+  console.log('Connection status:', status);
+});
+
+// Use as an EIP-1193 provider
+const accounts = await qrl.request({ method: 'qrl_requestAccounts' });
+
+const txHash = await qrl.request({
+  method: 'qrl_sendTransaction',
+  params: [{
+    from: accounts[0],
+    to: '0x...',
+    value: '0x2386F26FC10000', // 0.01 QRL
+  }],
+});
+```
+
+## Configuration
+
+```typescript
+const qrl = new QRLConnect({
+  // Required
+  dappMetadata: {
+    name: 'QuantaPool',
+    url: 'https://quantapool.com',
+    icon: 'https://quantapool.com/icon.png', // optional
+  },
+
+  // Optional
+  relayUrl: 'https://qrlwallet.com',  // default relay
+  chainId: '0x0',                      // QRL chain ID
+  autoReconnect: true,                 // reconnect on page load (default: true)
+  debug: false,                        // console logging
+});
+```
+
+## API
+
+### `QRLConnect`
+
+The main class. Creates a connection manager and EIP-1193 provider.
+
+| Method | Description |
+|--------|-------------|
+| `getConnectionURI()` | Returns the `qrlconnect://` URI for QR codes or deep links |
+| `request({ method, params })` | Send a JSON-RPC request to the wallet |
+| `isMobile()` | Check if the user is on a mobile browser |
+| `getAppStoreUrl()` | Get the app store link for QRL Wallet |
+| `isConnected()` | Whether the wallet is connected |
+| `getAccounts()` | Get connected accounts |
+| `getStatus()` | Current connection status |
+| `hasStoredSession()` | Check if a reconnectable session exists in local storage |
+| `newConnection()` | Reset current pairing and generate a new channel/URI |
+| `disconnect()` | End the session |
+| `getChannelId()` | Get the current relay channel ID (useful for debugging) |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `connect` | `{ chainId }` | Wallet connected |
+| `disconnect` | `{ code, message }` | Wallet disconnected |
+| `accountsChanged` | `string[]` | Account list changed |
+| `chainChanged` | `string` | Chain switched |
+| `statusChanged` | `ConnectionStatus` | Intermediate lifecycle states (see values below) |
+| `connection_lost` | — | Emitted after 5 failed reconnection attempts |
+
+#### `ConnectionStatus` values
+
+| Value | Meaning |
+|-------|---------|
+| `disconnected` | No active connection |
+| `connecting` | Connecting to relay server |
+| `waiting` | QR displayed, waiting for wallet to scan |
+| `key_exchange` | ECIES key exchange in progress |
+| `connected` | Wallet connected, ready for requests |
+| `reconnecting` | Attempting to restore a previous session |
+
+### Supported RPC methods
+
+**Require user approval:**
+`qrl_requestAccounts`, `qrl_sendTransaction`, `qrl_signTransaction`, `qrl_sign`, `personal_sign`, `qrl_signTypedData_v4`, `wallet_addQrlChain`, `wallet_switchQrlChain`
+
+**Auto-proxied (no approval needed):**
+`qrl_getBalance`, `qrl_call`, `qrl_estimateGas`, `qrl_blockNumber`, `qrl_chainId`, `qrl_getTransactionReceipt`, and 30+ more read-only methods.
+
+## Sessions
+
+Sessions persist in `localStorage` for 7 days. When a user returns to your dApp, the SDK can automatically reconnect without requiring a new QR scan.
+
+Recommended lifecycle:
+
+- Use `hasStoredSession()` on page load to decide whether to show reconnect state/UI
+- Keep a single `QRLConnect` instance for the page lifetime
+- Use `newConnection()` when the user explicitly wants to pair a different wallet
+- Use `statusChanged` for UI state transitions instead of relying on internals
+
+## How the relay works
+
+The relay is a lightweight Socket.IO server that routes encrypted messages between your dApp and the wallet. It runs at `wss://qrlwallet.com/relay`.
+
+- Messages are ECIES-encrypted end-to-end (the relay sees only ciphertext)
+- Max 2 participants per channel
+- Messages are buffered for up to 5 minutes if the wallet is temporarily offline (e.g., app backgrounded)
+- Channels auto-expire after 30 minutes of inactivity
+
+## Self-hosting the relay
+
+The relay is part of [myqrlwallet-backend](https://github.com/DigitalGuards/myqrlwallet-backend). To use your own:
+
+```typescript
+const qrl = new QRLConnect({
+  dappMetadata: { name: 'My dApp', url: 'https://mydapp.com' },
+  relayUrl: 'https://my-relay-server.com',
+});
+```
+
+## Bundler setup
+
+The SDK depends on Node's `Buffer` via `eciesjs`. If you're using Vite, add the polyfill plugin:
+
+```bash
+npm install vite-plugin-node-polyfills
+```
+
+```js
+// vite.config.js
+import { nodePolyfills } from 'vite-plugin-node-polyfills';
+
+export default defineConfig({
+  plugins: [
+    nodePolyfills({
+      include: ['buffer'],
+      globals: { Buffer: true },
+    }),
+  ],
+  define: { global: 'globalThis' },
+});
+```
+
+For webpack 5, add `buffer` to `resolve.fallback` and the `ProvidePlugin` for `Buffer`.
+
+## Development
+
+```bash
+# Build (CJS + ESM + .d.ts)
+npm run build
+
+# Watch mode (rebuilds on change)
+npm run dev
+
+# Type-check
+npm run typecheck
+
+# Unit tests (vitest)
+npm test
+
+# Lint
+npm run lint
+
+# E2E test (starts a local relay, simulates dApp + wallet handshake)
+node test-e2e.js
+```
+
+## Running the example dApp
+
+The `example/` directory contains a Vite test dApp with QR code generation, transaction sending, message signing, and read-only RPC calls.
+
+> **Want to try it without any setup?** The same example is hosted live at [zondscan.com/dapp-example](https://zondscan.com/dapp-example) — it pairs with the production relay and MyQRLWallet mobile app out of the box.
+
+```bash
+# 1. Build the SDK first (the example links to it locally)
+npm run build
+
+# 2. Install example dependencies
+cd example && npm install
+
+# 3. Start the dev server (opens http://localhost:5174)
+npm run dev
+```
+
+The example connects to the production relay at `wss://qrlwallet.com/relay` by default. To use a local relay, start `myqrlwallet-backend` and change `RELAY_URL` in `example/main.js`.
+
+## Security
+
+- Private keys and seeds never leave the wallet
+- All relay traffic is ECIES-encrypted (Elliptic Curve Integrated Encryption Scheme)
+- Key exchange uses a 3-step SYN/SYNACK/ACK handshake
+- PIN or biometric authentication required for every transaction
+- dApp URL is displayed to the user before connecting
+- Unknown RPC methods are rejected with `-32601`
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+import EventEmitter from 'eventemitter3';
+
+/** dApp metadata shown to user in approval UI */
+interface DAppMetadata {
+    name: string;
+    url: string;
+    icon?: string;
+}
+/** Stored session for reconnection */
+interface DAppSession {
+    channelId: string;
+    privateKey: string;
+    otherPublicKey: string | null;
+    dappMetadata: DAppMetadata;
+    connectedAccounts: string[];
+    chainId: string;
+    createdAt: number;
+    lastActivity: number;
+}
+/** Pending JSON-RPC request awaiting wallet response */
+interface PendingRequest {
+    id: string | number;
+    method: string;
+    params?: unknown[];
+    resolve: (result: unknown) => void;
+    reject: (error: Error) => void;
+    timestamp: number;
+}
+/** Key exchange message types */
+declare enum KeyExchangeMessageType {
+    SYN = "key_handshake_SYN",
+    SYNACK = "key_handshake_SYNACK",
+    ACK = "key_handshake_ACK"
+}
+/** Message types for the relay protocol */
+declare enum MessageType {
+    KEY_EXCHANGE = "key_exchange",
+    JSONRPC = "jsonrpc",
+    WALLET_INFO = "wallet_info",
+    ORIGINATOR_INFO = "originator_info",
+    TERMINATE = "terminate",
+    PING = "ping",
+    READY = "ready"
+}
+/** Wire message format sent through the relay */
+interface RelayMessage {
+    id: string;
+    clientType: 'dapp' | 'wallet';
+    message: string | object;
+    seq?: number;
+}
+/** Connection state */
+declare enum ConnectionStatus {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    WAITING = "waiting",
+    KEY_EXCHANGE = "key_exchange",
+    CONNECTED = "connected",
+    RECONNECTING = "reconnecting"
+}
+/** EIP-1193 provider events */
+interface ProviderEvents {
+    connect: (info: {
+        chainId: string;
+    }) => void;
+    disconnect: (error: {
+        code: number;
+        message: string;
+    }) => void;
+    chainChanged: (chainId: string) => void;
+    accountsChanged: (accounts: string[]) => void;
+    message: (message: {
+        type: string;
+        data: unknown;
+    }) => void;
+    statusChanged: (status: ConnectionStatus) => void;
+}
+/** JSON-RPC request */
+interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number;
+    method: string;
+    params?: unknown[];
+}
+/** JSON-RPC response */
+interface JsonRpcResponse {
+    jsonrpc: string;
+    id: string | number;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/** QRL Connect configuration */
+interface QRLConnectOptions {
+    dappMetadata: DAppMetadata;
+    relayUrl?: string;
+    chainId?: string;
+    /** Auto-reconnect to stored session on init */
+    autoReconnect?: boolean;
+    /** Session storage key prefix */
+    storageKey?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * QRL Connect EIP-1193 Provider.
+ * Bridges JSON-RPC requests from dApp to QRL Wallet via the relay.
+ */
+
+declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
+    private connectionManager;
+    private pendingRequests;
+    private options;
+    readonly isQRLConnect = true;
+    constructor(options: QRLConnectOptions);
+    private setupConnectionListeners;
+    /**
+     * Generate a connection URI for QR code display or deep link redirect.
+     */
+    getConnectionURI(): Promise<string>;
+    /**
+     * Check if the current browser is mobile.
+     */
+    isMobile(): boolean;
+    /**
+     * Get the app store URL for the QRL Wallet app.
+     */
+    getAppStoreUrl(): string;
+    /**
+     * EIP-1193 request method.
+     */
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    /**
+     * Get the current connection status.
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Get connected accounts.
+     */
+    getAccounts(): string[];
+    /**
+     * Get the channel ID for this connection.
+     */
+    getChannelId(): string;
+    /**
+     * Check if connected and keys exchanged.
+     */
+    isConnected(): boolean;
+    /**
+     * Check if a stored session exists that can be reconnected.
+     */
+    hasStoredSession(): boolean;
+    /**
+     * Reset the connection and start a fresh pairing with a new channel.
+     * Use this when the user wants to create a new connection instead of
+     * reconnecting to an existing session.
+     */
+    newConnection(): Promise<string>;
+    /**
+     * Disconnect from wallet and clean up.
+     */
+    disconnect(): void;
+}
+
+/**
+ * Connection Manager - Orchestrates socket connection, key exchange,
+ * and encrypted message routing. Manages session persistence and reconnection.
+ */
+
+interface ConnectionManagerEvents {
+    status_changed: (status: ConnectionStatus) => void;
+    accounts_changed: (accounts: string[]) => void;
+    chain_changed: (chainId: string) => void;
+    jsonrpc_response: (response: JsonRpcResponse) => void;
+    wallet_info: (info: {
+        accounts: string[];
+        chainId: string;
+    }) => void;
+    connection_lost: () => void;
+    error: (error: Error) => void;
+}
+declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
+    private socketClient;
+    private ecies;
+    private keyExchange;
+    private status;
+    private channelId;
+    private dappMetadata;
+    private chainId;
+    private relayUrl;
+    private connectedAccounts;
+    private storageKey;
+    private unresponsiveTimer;
+    private synRetryTimer;
+    private failedReconnects;
+    private synSent;
+    private synAttempts;
+    private walletPresent;
+    private static MAX_RECONNECT_FAILURES;
+    private static SYN_RETRY_MS;
+    private static MAX_SYN_ATTEMPTS;
+    constructor(options: {
+        dappMetadata: DAppMetadata;
+        relayUrl?: string;
+        chainId?: string;
+        storageKey?: string;
+    });
+    private setupSocketListeners;
+    private setupKeyExchangeListeners;
+    /**
+     * Generate the connection URI and start listening for wallet connection.
+     */
+    getConnectionURI(retryOnConflict?: boolean): Promise<string>;
+    /**
+     * Reconnect to an existing session.
+     */
+    reconnect(): Promise<boolean>;
+    /**
+     * Send a JSON-RPC request to the wallet.
+     */
+    sendJsonRpc(request: JsonRpcRequest): void;
+    /**
+     * Handle an incoming relay message.
+     */
+    private handleRelayMessage;
+    private handleKeyExchangeMessage;
+    private handleDecryptedMessage;
+    /** Send a plaintext (unencrypted) message through the relay. */
+    private sendPlaintext;
+    /** Send an encrypted message through the relay. */
+    private sendEncrypted;
+    private startUnresponsiveTimer;
+    private clearUnresponsiveTimer;
+    private sendSYN;
+    private scheduleSynRetry;
+    private clearSynRetryTimer;
+    private setStatus;
+    private isDappParticipantConflictError;
+    private areArraysEqual;
+    getStatus(): ConnectionStatus;
+    getAccounts(): string[];
+    getChainId(): string;
+    getChannelId(): string;
+    /** Check if a stored session exists (without loading/restoring it). */
+    hasStoredSession(): boolean;
+    /**
+     * Reset the connection and create a new channel for a fresh pairing.
+     * Disconnects any existing session, generates a new channel ID and keys.
+     */
+    resetForNewChannel(): void;
+    /** Disconnect and clean up. */
+    disconnect(): void;
+    private saveSession;
+    private loadSession;
+    private clearSession;
+}
+
+/**
+ * ECIES encryption/decryption client.
+ * Adapted from MetaMask SDK's ECIES.ts pattern.
+ */
+declare class ECIESClient {
+    private privateKey;
+    constructor(existingPrivateKey?: string);
+    /** Get public key as hex string */
+    getPublicKey(): string;
+    /** Get private key as hex string (for session persistence) */
+    getPrivateKeyHex(): string;
+    /** Encrypt a string message for the given public key. Returns base64. */
+    encrypt(data: string, otherPublicKey: string): string;
+    /** Decrypt a base64-encoded message using our private key. */
+    decrypt(encryptedBase64: string): string;
+}
+
+/**
+ * Key Exchange - 3-step SYN/SYNACK/ACK handshake protocol.
+ * Adapted from MetaMask SDK's KeyExchange.ts.
+ */
+
+interface KeyExchangeEvents {
+    keys_exchanged: () => void;
+    step_change: (step: KeyExchangeMessageType) => void;
+}
+declare class KeyExchange extends EventEmitter<KeyExchangeEvents> {
+    private ecies;
+    private otherPublicKey;
+    private keysExchanged;
+    private awaitingSynAck;
+    private awaitingAck;
+    private step;
+    private isOriginator;
+    constructor(ecies: ECIESClient, isOriginator: boolean, otherPublicKey?: string);
+    /** Get the SYN message to start the handshake (originator/dApp side). */
+    createSYN(): object;
+    /**
+     * Process an incoming key exchange message.
+     * Returns a response message to send back, or null if handshake is complete.
+     */
+    onMessage(message: {
+        type: KeyExchangeMessageType;
+        pubkey?: string;
+        v?: number;
+    }): object | null;
+    /** Encrypt a message for the counterparty. */
+    encryptMessage(data: string): string;
+    /** Decrypt a message from the counterparty. */
+    decryptMessage(encryptedBase64: string): string;
+    /** Reset key exchange state for a fresh handshake (e.g. new QR code). */
+    reset(): void;
+    areKeysExchanged(): boolean;
+    getOtherPublicKey(): string | null;
+    getCurrentStep(): KeyExchangeMessageType;
+}
+
+/**
+ * Socket.IO client wrapper for relay communication.
+ */
+
+interface SocketClientEvents {
+    message: (data: RelayMessage) => void;
+    connected: () => void;
+    disconnected: (reason: string) => void;
+    reconnected: () => void;
+    participants_changed: (data: {
+        event: string;
+        clientType?: string;
+    }) => void;
+    error: (err: Error) => void;
+}
+declare class SocketClient extends EventEmitter<SocketClientEvents> {
+    private socket;
+    private relayUrl;
+    private channelId;
+    private clientType;
+    private seq;
+    private pendingJoin;
+    constructor(relayUrl: string, clientType: 'dapp' | 'wallet');
+    /**
+     * Connect to the relay server.
+     */
+    connect(): void;
+    /**
+     * Join a relay channel.
+     */
+    joinChannel(channelId: string): Promise<{
+        bufferedMessages: unknown[];
+    }>;
+    private joinChannelNow;
+    /**
+     * Send a message through the relay.
+     */
+    sendMessage(data: RelayMessage): Promise<{
+        success: boolean;
+        buffered: boolean;
+    }>;
+    /**
+     * Leave the current channel.
+     */
+    leaveChannel(): void;
+    /**
+     * Disconnect from the relay.
+     */
+    disconnect(): void;
+    isConnected(): boolean;
+    getChannelId(): string | null;
+}
+
+interface QRConnectParams {
+    channelId: string;
+    pubKey: string;
+    name: string;
+    url: string;
+    icon?: string;
+    chainId: string;
+    relayUrl: string;
+}
+/**
+ * Generate a qrlconnect:// URI for QR code or deep link.
+ */
+declare function generateConnectionURI(params: QRConnectParams): string;
+/**
+ * Parse a qrlconnect:// URI back into its components.
+ */
+declare function parseConnectionURI(uri: string): QRConnectParams | null;
+
+/**
+ * Detect if the current browser is on a mobile device.
+ */
+declare function isMobileBrowser(): boolean;
+/**
+ * Check if the QRL Wallet app is likely installed by attempting a deep link.
+ * Falls back to app store URL after timeout.
+ */
+declare function getAppStoreUrl(): string;
+
+declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
+/** RPC methods that require user approval in the wallet */
+declare const RESTRICTED_METHODS: Set<string>;
+/** RPC methods that can be auto-proxied without approval */
+declare const UNRESTRICTED_METHODS: Set<string>;
+
+export { ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, ECIESClient, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, MessageType, type PendingRequest, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, RESTRICTED_METHODS, type RelayMessage, SocketClient, UNRESTRICTED_METHODS, generateConnectionURI, getAppStoreUrl, isMobileBrowser, parseConnectionURI };