WizardConnect/packages/wallet/src/wallet-adapter.ts

// Copyright (C) 2026 Whiterun LLC,
// This software is licensed under the GNU Lesser General Public License (LGPL), version 3.0 or later.
// A copy of the license can be found in the LICENSE file or at https://www.gnu.org/licenses/lgpl-3.0.html

import { DerivationPath } from "./derivation-path.js";
import { SignTransactionRequest, PathXpub } from "@wizardconnect/core";

export interface SignTransactionResult {
  signedTransaction: string;
}

/**
 * Abstract interface that wallets implement to integrate with WizardConnect.
 */
export interface WalletAdapter {
  /** Human-readable wallet name shown to dapps */
  walletName: string;
  /** URL to wallet icon (used in wallet_ready handshake) */
  walletIcon: string;

  /**
   * Return the relay identity private key for a given connection URI.
   * Should be deterministic per URI so that reconnecting to the same URI
   * produces the same Nostr identity (relay recognizes the wallet after reload).
   * Different URIs should yield different keys for privacy (dapps can't correlate).
   */
  getRelayPrivateKey(uri: string): Uint8Array;

  /**
   * Derive the compressed public key (33 bytes) for a given HD path and index.
   */
  getPublicKey(path: DerivationPath, index: bigint): Uint8Array;

  /**
   * BIP32 xpub string for the given derivation path.
   * Used to allow dapps to derive all needed pubkeys locally without round-trips.
   */
  getXpub(path: DerivationPath): string;

  /**
   * Sign a transaction request from a dapp.
   * The wallet should verify the request and return the signed transaction hex,
   * or throw if the user rejects or signing fails.
   */
  signTransaction(
    request: SignTransactionRequest,
  ): Promise<SignTransactionResult>;

  /**
   * Optional additional paths beyond receive/change/defi to include in the
   * hdwalletv1 session handshake (e.g. stealth_scan, stealth_spend, rpa).
   * See docs/extensions.md for conventions.
   */
  getAdditionalPaths?(): PathXpub[];

  /**
   * Optional extension data to include in the hdwalletv1 session handshake.
   * Each key is an extension name; its presence indicates wallet support.
   * See docs/extensions.md for conventions.
   */
  getExtensions?(): Record<string, unknown>;
}