@nockchain/rose 0.1.4-nightly.5

package/sdk/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Rose Wallet SDK
+ * TypeScript SDK for interacting with Rose wallet extension
+ */
+
+export * from './types.js';
+export * from './provider.js';
+export * from './transaction.js';
+export * from './errors.js';
+export * from './constants.js';
+export * from './hooks/index.js';
+export * as wasm from './wasm.js';

package/sdk/src/provider.ts

@@ -0,0 +1,396 @@
+/**
+ * NockchainProvider - Main SDK class for interacting with Rose wallet
+ */
+
+import type { Transaction, NockchainEvent, EventListener, InjectedNockchain } from './types.js';
+import { TransactionBuilder } from './transaction.js';
+import { WalletNotInstalledError, UserRejectedError, RpcError, NoAccountError } from './errors.js';
+import { PROVIDER_METHODS } from './constants.js';
+
+/**
+ * NockchainProvider class - Main interface for dApps to interact with Rose wallet
+ *
+ * @example
+ * ```typescript
+ * const nockchain = new NockchainProvider();
+ *
+ * // Connect wallet
+ * const accounts = await nockchain.requestAccounts();
+ *
+ * // Build and send transaction
+ * const tx = nockchain.transaction()
+ *   .to('recipient_address')
+ *   .amount(1_000_000)
+ *   .build();
+ *
+ * const txId = await nockchain.sendTransaction(tx);
+ * ```
+ */
+export class NockchainProvider {
+  private injected: InjectedNockchain;
+  private eventListeners: Map<NockchainEvent, Set<EventListener>>;
+  private _accounts: string[] = [];
+  private _chainId: string | null = null;
+  private _messageHandler?: (event: MessageEvent) => void;
+
+  /**
+   * Create a new NockchainProvider instance
+   * @throws {WalletNotInstalledError} If the Rose extension is not installed
+   */
+  constructor() {
+    if (typeof window === 'undefined') {
+      throw new Error('NockchainProvider can only be used in a browser environment');
+    }
+
+    // Verify Rose extension is installed and authentic
+    if (!NockchainProvider.isInstalled()) {
+      throw new WalletNotInstalledError();
+    }
+
+    const injected = window.nockchain;
+
+    // TODO: remove this duplicate check
+    if (!injected) {
+      throw new WalletNotInstalledError();
+    }
+
+    this.injected = injected;
+    this.eventListeners = new Map();
+
+    // Initialize event listeners for wallet events
+    this.setupEventListeners();
+  }
+
+  /**
+   * Connect to the wallet and request access
+   * This will prompt the user to approve the connection
+   * @returns Promise resolving to wallet info with PKH and gRPC endpoint
+   * @throws {UserRejectedError} If the user rejects the request
+   * @throws {RpcError} If the RPC call fails
+   */
+  async connect(): Promise<{ pkh: string; grpcEndpoint: string }> {
+    const info = await this.request<{ pkh: string; grpcEndpoint: string }>({
+      method: PROVIDER_METHODS.CONNECT,
+    });
+
+    // Store the PKH as the connected account
+    this._accounts = [info.pkh];
+    return info;
+  }
+
+  /**
+   * Get the currently connected accounts (if any)
+   * @returns Array of connected account addresses (PKH)
+   */
+  get accounts(): string[] {
+    return [...this._accounts];
+  }
+
+  /**
+   * Get the current chain ID
+   * @returns The current chain ID or null if not connected
+   */
+  get chainId(): string | null {
+    return this._chainId;
+  }
+
+  /**
+   * Check if the wallet is connected
+   * @returns true if wallet is connected
+   */
+  get isConnected(): boolean {
+    return this._accounts.length > 0;
+  }
+
+  /**
+   * Send a transaction
+   * @param transaction - The transaction object to send
+   * @returns Promise resolving to the transaction ID
+   * @throws {NoAccountError} If no account is connected
+   * @throws {UserRejectedError} If the user rejects the transaction
+   * @throws {RpcError} If the RPC call fails
+   */
+  async sendTransaction(transaction: Transaction): Promise<string> {
+    if (!this.isConnected) {
+      throw new NoAccountError();
+    }
+
+    return this.request<string>({
+      method: PROVIDER_METHODS.SEND_TRANSACTION,
+      params: [transaction],
+    });
+  }
+
+  /**
+   * Sign an arbitrary message with the current account
+   * @param message - The message to sign
+   * @returns Promise resolving to the signature and public key hex (for verification)
+   * @throws {NoAccountError} If no account is connected
+   * @throws {UserRejectedError} If the user rejects the signing request
+   * @throws {RpcError} If the RPC call fails
+   */
+  async signMessage(message: string): Promise<{ signature: string; publicKeyHex: string }> {
+    if (!this.isConnected) {
+      throw new NoAccountError();
+    }
+
+    return this.request<{ signature: string; publicKeyHex: string }>({
+      method: PROVIDER_METHODS.SIGN_MESSAGE,
+      params: [message],
+    });
+  }
+
+  /**
+   * Sign a raw transaction
+   * Accepts either wasm objects (with toProtobuf() method) or protobuf JS objects
+   * @param params - The transaction parameters (rawTx, notes, spendConditions)
+   * @returns Promise resolving to the signed raw transaction as protobuf Uint8Array
+   * @throws {NoAccountError} If no account is connected
+   * @throws {UserRejectedError} If the user rejects the signing request
+   * @throws {RpcError} If the RPC call fails
+   *
+   * @example
+   * ```typescript
+   * // Option 1: Pass wasm objects directly (auto-converts to protobuf)
+   * const rawTx = builder.build();
+   * const txNotes = builder.allNotes();
+   *
+   * const signedTx = await provider.signRawTx({
+   *   rawTx: rawTx,  // wasm RawTx object
+   *   notes: txNotes.notes,  // array of wasm Note objects
+   *   spendConditions: txNotes.spendConditions  // array of wasm SpendCondition objects
+   * });
+   *
+   * // Option 2: Pass protobuf JS objects directly
+   * const signedTx = await provider.signRawTx({
+   *   rawTx: rawTxProtobufObject,  // protobuf JS object
+   *   notes: noteProtobufObjects,  // array of protobuf JS objects
+   *   spendConditions: spendCondProtobufObjects  // array of protobuf JS objects
+   * });
+   * ```
+   */
+  async signRawTx(params: {
+    rawTx: any;
+    notes: any[];
+    spendConditions: any[];
+  }): Promise<Uint8Array> {
+    if (!this.isConnected) {
+      throw new NoAccountError();
+    }
+
+    // Helper to convert to protobuf if it's a wasm object
+    const toProtobuf = (obj: any): any => {
+      // If object has toProtobuf method, it's a wasm object - convert it
+      if (obj && typeof obj.toProtobuf === 'function') {
+        return obj.toProtobuf();
+      }
+      // Otherwise assume it's already a protobuf JS object
+      return obj;
+    };
+
+    // Convert wasm objects to protobuf (if needed)
+    const protobufParams = {
+      rawTx: toProtobuf(params.rawTx),
+      notes: params.notes.map(toProtobuf),
+      spendConditions: params.spendConditions.map(toProtobuf),
+    };
+
+    return this.request<Uint8Array>({
+      method: PROVIDER_METHODS.SIGN_RAW_TX,
+      params: [protobufParams],
+    });
+  }
+
+  /**
+   * Create a new transaction builder
+   * @returns A new TransactionBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const tx = provider.transaction()
+   *   .to('recipient_address')
+   *   .amount(1_000_000)
+   *   .fee(50_000)
+   *   .build();
+   * ```
+   */
+  transaction(): TransactionBuilder {
+    return new TransactionBuilder();
+  }
+
+  /**
+   * Add an event listener for wallet events
+   * @param event - The event to listen for
+   * @param listener - The callback function to invoke when the event occurs
+   *
+   * @example
+   * ```typescript
+   * provider.on('accountsChanged', (accounts) => {
+   *   console.log('Accounts changed:', accounts);
+   * });
+   * ```
+   */
+  on<T = unknown>(event: NockchainEvent, listener: EventListener<T>): void {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, new Set());
+    }
+    this.eventListeners.get(event)!.add(listener as EventListener);
+  }
+
+  /**
+   * Remove an event listener
+   * @param event - The event to stop listening for
+   * @param listener - The callback function to remove
+   */
+  off<T = unknown>(event: NockchainEvent, listener: EventListener<T>): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(listener as EventListener);
+    }
+  }
+
+  /**
+   * Remove all event listeners for a specific event or all events
+   * @param event - Optional event to remove listeners for (removes all if not specified)
+   */
+  removeAllListeners(event?: NockchainEvent): void {
+    if (event) {
+      this.eventListeners.delete(event);
+    } else {
+      this.eventListeners.clear();
+    }
+  }
+
+  /**
+   * Make a raw RPC request to the wallet extension (EIP-1193 compatible)
+   * @param args - The RPC request arguments
+   * @returns Promise resolving to the result
+   * @throws {UserRejectedError} If the user rejects the request
+   * @throws {RpcError} If the RPC call fails
+   */
+  public async request<T = unknown>(args: { method: string; params?: unknown[] }): Promise<T> {
+    try {
+      const result = await this.injected.request<T>(args);
+      return result;
+    } catch (error) {
+      // Handle RPC errors and map known error codes
+      if (error && typeof error === 'object' && 'code' in error && 'message' in error) {
+        const { code, message, data } = error as { code: number; message: string; data?: unknown };
+        const rpcError = new RpcError(code, message, data);
+
+        // Map EIP-1193 error codes to typed errors
+        if (this.isUserRejected(rpcError)) {
+          throw new UserRejectedError(message);
+        }
+
+        throw rpcError;
+      }
+      // Re-throw other errors as-is
+      throw error;
+    }
+  }
+
+  /**
+   * Check if an error represents user rejection
+   * Uses EIP-1193 standard error code 4001
+   */
+  private isUserRejected(error: RpcError | unknown): boolean {
+    // EIP-1193 standard: 4001 = User Rejected Request
+    const USER_REJECTED_CODES = new Set([4001]);
+
+    if (error instanceof RpcError) {
+      return USER_REJECTED_CODES.has(error.code);
+    }
+
+    // Fallback: check message for common rejection phrases
+    if (error instanceof Error) {
+      return /reject|denied|cancel/i.test(error.message);
+    }
+
+    return false;
+  }
+
+  /**
+   * Set up event listeners for wallet events
+   * This listens for events from the extension and forwards them to registered listeners
+   */
+  private setupEventListeners(): void {
+    if (typeof window === 'undefined') return;
+
+    this._messageHandler = (event: MessageEvent) => {
+      // Only accept messages from the same window
+      if (event.source !== window) return;
+
+      const payload = event.data;
+
+      // SECURITY: Verify the message is from Rose extension
+      // This prevents malicious scripts from forging wallet events
+      if (!payload || payload.__rose !== true) return;
+
+      // Check if this is a valid wallet event
+      if (typeof payload.type !== 'string' || !payload.type.startsWith('nockchain_')) return;
+
+      const eventType = payload.type.replace('nockchain_', '') as NockchainEvent;
+      const eventData = payload.data;
+
+      // Update internal state based on event type
+      if (eventType === 'accountsChanged' && Array.isArray(eventData)) {
+        this._accounts = eventData;
+      } else if (eventType === 'chainChanged' && typeof eventData === 'string') {
+        this._chainId = eventData;
+      } else if (eventType === 'disconnect') {
+        // Clear state on disconnect
+        this._accounts = [];
+        this._chainId = null;
+      }
+
+      // Emit to registered listeners
+      this.emit(eventType, eventData);
+    };
+
+    window.addEventListener('message', this._messageHandler);
+  }
+
+  /**
+   * Clean up event listeners and resources
+   * Call this when the provider is no longer needed (e.g., on component unmount)
+   */
+  public dispose(): void {
+    if (this._messageHandler && typeof window !== 'undefined') {
+      window.removeEventListener('message', this._messageHandler);
+      this._messageHandler = undefined;
+    }
+    this.removeAllListeners();
+  }
+
+  /**
+   * Emit an event to all registered listeners
+   * @param event - The event to emit
+   * @param data - The data to pass to listeners
+   */
+  private emit<T = unknown>(event: NockchainEvent, data: T): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.forEach(listener => {
+        try {
+          listener(data);
+        } catch (error) {
+          console.error(`Error in ${event} listener:`, error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Check if the Rose extension is installed and authentic
+   * @returns true if the extension is installed
+   */
+  static isInstalled(): boolean {
+    if (typeof window === 'undefined' || !window.nockchain?.providers) {
+      return false;
+    }
+    return window.nockchain.providers.some(
+      (provider: { name?: string }) => provider && provider.name === 'rose'
+    );
+  }
+}

package/sdk/src/transaction.ts

@@ -0,0 +1,163 @@
+/**
+ * Transaction builder with fluent API for constructing Nockchain transactions
+ */
+
+import { base58 } from '@scure/base';
+import type { Transaction } from './types.js';
+import { InvalidAddressError, InvalidTransactionError } from './errors.js';
+
+/**
+ * Conversion rate: 1 NOCK = 65,536 nicks (2^16)
+ */
+export const NOCK_TO_NICKS = 65_536;
+
+/**
+ * Default transaction fee in nicks (32,768 nicks = 0.5 NOCK)
+ */
+export const DEFAULT_FEE = 32_768;
+
+/**
+ * Minimum amount in nicks (must be positive)
+ */
+export const MIN_AMOUNT = 1;
+
+/**
+ * TransactionBuilder class implementing the builder pattern for type-safe transaction construction
+ *
+ * @example
+ * ```typescript
+ * const tx = new TransactionBuilder()
+ *   .to('nock1recipient_address')
+ *   .amount(1_000_000)
+ *   .fee(50_000)
+ *   .build();
+ * ```
+ */
+export class TransactionBuilder {
+  private _to?: string;
+  private _amount?: number;
+  private _fee?: number;
+
+  /**
+   * Set the recipient address for the transaction
+   * @param address - Base58-encoded Nockchain V1 PKH address (40 bytes, ~54-55 chars)
+   * @returns A new TransactionBuilder instance with the address set
+   * @throws {InvalidAddressError} If the address format is invalid
+   */
+  to(address: string): TransactionBuilder {
+    if (!this.isValidAddress(address)) {
+      throw new InvalidAddressError(address);
+    }
+
+    const builder = new TransactionBuilder();
+    builder._to = address;
+    builder._amount = this._amount;
+    builder._fee = this._fee;
+    return builder;
+  }
+
+  /**
+   * Set the amount to send in nicks (1 NOCK = 65,536 nicks)
+   * @param nicks - Amount in nicks (must be a positive integer)
+   * @returns A new TransactionBuilder instance with the amount set
+   * @throws {InvalidTransactionError} If the amount is invalid
+   */
+  amount(nicks: number): TransactionBuilder {
+    if (!Number.isInteger(nicks)) {
+      throw new InvalidTransactionError('Amount must be an integer');
+    }
+    if (nicks < MIN_AMOUNT) {
+      throw new InvalidTransactionError(`Amount must be at least ${MIN_AMOUNT} nick`);
+    }
+    // Note: MIN_AMOUNT = 1, so the above check already covers negative amounts
+
+    const builder = new TransactionBuilder();
+    builder._to = this._to;
+    builder._amount = nicks;
+    builder._fee = this._fee;
+    return builder;
+  }
+
+  /**
+   * Set the transaction fee in nicks (optional, defaults to 32,768 nicks)
+   * @param nicks - Fee amount in nicks (must be a positive integer)
+   * @returns A new TransactionBuilder instance with the fee set
+   * @throws {InvalidTransactionError} If the fee is invalid
+   */
+  fee(nicks: number): TransactionBuilder {
+    if (!Number.isInteger(nicks)) {
+      throw new InvalidTransactionError('Fee must be an integer');
+    }
+    if (nicks < 0) {
+      throw new InvalidTransactionError('Fee must be non-negative');
+    }
+
+    const builder = new TransactionBuilder();
+    builder._to = this._to;
+    builder._amount = this._amount;
+    builder._fee = nicks;
+    return builder;
+  }
+
+  /**
+   * Build and validate the transaction
+   * @returns The constructed Transaction object
+   * @throws {InvalidTransactionError} If required fields are missing
+   */
+  build(): Transaction {
+    if (!this._to) {
+      throw new InvalidTransactionError('Missing required field: to (recipient address)');
+    }
+    if (this._amount === undefined || this._amount === null) {
+      throw new InvalidTransactionError('Missing required field: amount');
+    }
+
+    return {
+      to: this._to,
+      amount: this._amount,
+      fee: this._fee ?? DEFAULT_FEE,
+    };
+  }
+
+  /**
+   * Validate a Nockchain V1 PKH address format
+   * V1 PKH addresses are TIP5 hash (40 bytes) of public key, base58-encoded
+   *
+   * Validates by decoding the base58 string and checking for exactly 40 bytes
+   * rather than relying on character count which can vary
+   *
+   * @param address - The address to validate
+   * @returns true if valid, false otherwise
+   */
+  private isValidAddress(address: string): boolean {
+    try {
+      const trimmed = (address || '').trim();
+      if (trimmed.length === 0) return false;
+
+      const bytes = base58.decode(trimmed);
+      return bytes.length === 40;
+    } catch {
+      // Invalid base58 encoding
+      return false;
+    }
+  }
+
+  /**
+   * Create a transaction builder from an existing transaction object
+   * Useful for modifying existing transactions
+   * @param tx - The transaction to create a builder from
+   * @returns A new TransactionBuilder instance with values from the transaction
+   * @throws {InvalidAddressError} If the transaction address is invalid
+   * @throws {InvalidTransactionError} If the transaction amount or fee is invalid
+   */
+  static fromTransaction(tx: Transaction): TransactionBuilder {
+    // Use setters to ensure validation is applied
+    let builder = new TransactionBuilder().to(tx.to).amount(tx.amount);
+
+    if (typeof tx.fee === 'number') {
+      builder = builder.fee(tx.fee);
+    }
+
+    return builder;
+  }
+}

package/sdk/src/types/rose-wasm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type declarations for Rose WASM JS entrypoint.
+ *
+ * With `moduleResolution: "bundler"`, TypeScript can fail to associate the
+ * package-provided `.d.ts` with the `.js` entrypoint path, so we bridge it here.
+ */
+
+/// <reference path="@nockchain/rose-wasm/rose_wasm.d.ts" />
+
+declare module '@nockchain/rose-wasm/rose_wasm.js' {
+  export * from '@nockchain/rose-wasm/rose_wasm';
+  import init from '@nockchain/rose-wasm/rose_wasm';
+  export default init;
+}

package/sdk/src/types.ts

@@ -0,0 +1,97 @@
+/**
+ * TypeScript type definitions for Rose SDK
+ */
+
+/**
+ * Transaction object representing a Nockchain transaction
+ */
+export interface Transaction {
+  /** Recipient address (base58-encoded public key hash / PKH) */
+  to: string;
+  /** Amount to send in nicks (1 NOCK = 65,536 nicks) */
+  amount: number;
+  /** Transaction fee in nicks (optional, defaults to 32,768 = 0.5 NOCK) */
+  fee?: number;
+}
+
+/**
+ * RPC request object for communicating with the extension
+ */
+export interface RpcRequest {
+  /** The RPC method to call */
+  method: string;
+  /** Optional parameters for the method */
+  params?: unknown[];
+  /** Optional timeout for the request */
+  timeout?: number;
+}
+
+/**
+ * RPC response object from the extension
+ */
+export interface RpcResponse<T = unknown> {
+  /** The result of the RPC call */
+  result?: T;
+  /** Error information if the call failed */
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+/**
+ * Event types that the provider can emit
+ */
+export type NockchainEvent = 'accountsChanged' | 'chainChanged' | 'connect' | 'disconnect';
+
+/**
+ * Event listener callback function
+ */
+export type EventListener<T = unknown> = (data: T) => void;
+
+/**
+ * Interface for the injected window.nockchain object
+ */
+export interface InjectedNockchain {
+  /**
+   * Make an RPC request to the wallet extension
+   * @param request - The RPC request object
+   * @returns Promise resolving to the result
+   */
+  request<T = unknown>(request: RpcRequest): Promise<T>;
+
+  /**
+   * Provider names and versions (e.g., 'rose', 'iris')
+   */
+  providers?: { name: string; version: string }[];
+}
+
+/**
+ * Extended Window interface with nockchain property
+ */
+declare global {
+  interface Window {
+    nockchain?: InjectedNockchain;
+  }
+}
+
+/**
+ * Chain information
+ */
+export interface ChainInfo {
+  /** Chain ID (e.g., 'mainnet', 'testnet') */
+  chainId: string;
+  /** Network name */
+  name: string;
+}
+
+/**
+ * Account information
+ */
+export interface AccountInfo {
+  /** Account address */
+  address: string;
+  /** Account balance in nicks (optional, may not be available) */
+  balance?: number;
+}

package/sdk/src/wasm.ts

@@ -0,0 +1,13 @@
+/**
+ * `@nockchain/sdk/wasm`
+ *
+ * Convenience re-export of the Rose WASM package so consumers can import:
+ *   - `@nockchain/sdk/wasm`
+ * instead of:
+ *   - `@nockchain/rose-wasm/rose_wasm.js`
+ *
+ * This mirrors the "SDK owns WASM surface" pattern used elsewhere in the repo.
+ */
+
+export * from '@nockchain/rose-wasm/rose_wasm.js';
+export { default } from '@nockchain/rose-wasm/rose_wasm.js';