@txnlab/use-wallet 4.5.0 → 5.0.0-rc.1

package/dist/adapter.d.ts

@@ -0,0 +1,18 @@
+import { C as WalletKey, E as WalletTransaction, M as LogLevel, T as WalletState, _ as Siwa, a as setActiveAccount, b as WalletAdapterConfig, c as JsonRpcRequest, d as SignData, f as SignDataError, g as SignerTransaction, h as SignTxnsError, i as State, l as MultisigMetadata, m as SignMetadata, o as AdapterConstructorParams, p as SignDataResponse, s as AdapterStoreAccessor, t as BaseWallet, u as ScopeType, w as WalletMetadata, y as WalletAccount } from "./base-BKrq-rUH.js";
+import { a as SecureKeyContainer, c as withSecureKeySync, i as custom, l as zeroMemory, n as CustomWallet, o as deriveAlgorandAccountFromEd25519, r as CustomWalletOptions, s as withSecureKey, t as CustomProvider, u as zeroString } from "./custom-BXQKth41.js";
+import algosdk from "algosdk";
+
+//#region src/utils.d.ts
+declare function compareAccounts(accounts: WalletAccount[], compareTo: WalletAccount[]): boolean;
+declare function base64ToByteArray(blob: string): Uint8Array;
+declare function byteArrayToBase64(array: Uint8Array): string;
+declare function stringToByteArray(str: string): Uint8Array;
+declare function byteArrayToString(array: Uint8Array): string;
+declare function isSignedTxn(txnObj: any): boolean;
+declare function isTransaction(item: any): item is algosdk.Transaction;
+declare function isTransactionArray(txnGroup: any): txnGroup is algosdk.Transaction[] | algosdk.Transaction[][];
+declare function flattenTxnGroup<T>(txnGroup: T[]): T[];
+declare function formatJsonRpcRequest<T = any>(method: string, params: T): JsonRpcRequest<T>;
+//#endregion
+export { type AdapterConstructorParams, type AdapterStoreAccessor, BaseWallet, type CustomProvider, CustomWallet, type CustomWalletOptions, type JsonRpcRequest, LogLevel, type MultisigMetadata, ScopeType, SecureKeyContainer, type SignData, SignDataError, type SignDataResponse, type SignMetadata, SignTxnsError, type SignerTransaction, type Siwa, type State, type WalletAccount, type WalletAdapterConfig, type WalletKey, type WalletMetadata, type WalletState, type WalletTransaction, base64ToByteArray, byteArrayToBase64, byteArrayToString, compareAccounts, custom, deriveAlgorandAccountFromEd25519, flattenTxnGroup, formatJsonRpcRequest, isSignedTxn, isTransaction, isTransactionArray, setActiveAccount, stringToByteArray, withSecureKey, withSecureKeySync, zeroMemory, zeroString };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.js

@@ -0,0 +1,3 @@
+import { h as LogLevel, s as setActiveAccount } from "./store-CM2Y4xMP.js";
+import { S as zeroString, _ as SecureKeyContainer, a as custom, b as withSecureKeySync, c as byteArrayToString, d as formatJsonRpcRequest, f as isSignedTxn, g as BaseWallet, h as stringToByteArray, i as CustomWallet, l as compareAccounts, m as isTransactionArray, n as SignDataError, o as base64ToByteArray, p as isTransaction, r as SignTxnsError, s as byteArrayToBase64, t as ScopeType, u as flattenTxnGroup, v as deriveAlgorandAccountFromEd25519, x as zeroMemory, y as withSecureKey } from "./types-BduS9cZw.js";
+export { BaseWallet, CustomWallet, LogLevel, ScopeType, SecureKeyContainer, SignDataError, SignTxnsError, base64ToByteArray, byteArrayToBase64, byteArrayToString, compareAccounts, custom, deriveAlgorandAccountFromEd25519, flattenTxnGroup, formatJsonRpcRequest, isSignedTxn, isTransaction, isTransactionArray, setActiveAccount, stringToByteArray, withSecureKey, withSecureKeySync, zeroMemory, zeroString };

package/dist/base-BKrq-rUH.d.ts

@@ -0,0 +1,365 @@
+import { Store } from "@tanstack/store";
+import algosdk from "algosdk";
+
+//#region src/logger.d.ts
+declare enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3
+}
+declare class Logger {
+  private static instance;
+  private level;
+  private isClient;
+  private constructor();
+  static getInstance(): Logger;
+  static setLevel(level: LogLevel): void;
+  private log;
+  createScopedLogger(scope: string): {
+    debug: (message: string, ...args: any[]) => void;
+    info: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+    error: (message: string, ...args: any[]) => void;
+  };
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+  setIsClient(isClient: boolean): void;
+}
+declare const logger: Logger;
+//#endregion
+//#region src/network.d.ts
+interface AlgodConfig {
+  token: string | algosdk.AlgodTokenHeader | algosdk.CustomTokenHeader | algosdk.BaseHTTPClient;
+  baseServer: string;
+  port?: string | number;
+  headers?: Record<string, string>;
+}
+interface NetworkConfig {
+  algod: AlgodConfig;
+  genesisHash?: string;
+  genesisId?: string;
+  isTestnet?: boolean;
+  caipChainId?: string;
+}
+declare const DEFAULT_NETWORK_CONFIG: Record<string, NetworkConfig>;
+type DefaultNetworkConfig = Omit<Partial<NetworkConfig>, 'genesisHash' | 'genesisId' | 'caipChainId'>;
+declare class NetworkConfigBuilder {
+  private networks;
+  constructor();
+  mainnet(config: DefaultNetworkConfig): this;
+  testnet(config: DefaultNetworkConfig): this;
+  betanet(config: DefaultNetworkConfig): this;
+  fnet(config: DefaultNetworkConfig): this;
+  localnet(config: Partial<NetworkConfig>): this;
+  addNetwork(id: string, config: NetworkConfig): this;
+  build(): {
+    [k: string]: NetworkConfig;
+  };
+}
+declare enum NetworkId {
+  MAINNET = "mainnet",
+  TESTNET = "testnet",
+  BETANET = "betanet",
+  FNET = "fnet",
+  LOCALNET = "localnet"
+}
+//#endregion
+//#region src/wallets/types.d.ts
+/**
+ * Wallet identifier. In v5 this is an open string type — each adapter
+ * package exports its own ID constant (e.g. `export const WALLET_ID = 'pera' as const`).
+ */
+type WalletId = string;
+/**
+ * Unique key for a wallet instance in the store.
+ * Usually equals the wallet ID, but can be a composite key for
+ * skinned WalletConnect instances (e.g. 'walletconnect:biatec').
+ */
+type WalletKey = string;
+type WalletMetadata = {
+  name: string;
+  icon: string;
+};
+type WalletAccount = {
+  name: string;
+  address: string;
+  metadata?: Record<string, unknown>;
+};
+/**
+ * Declares which networks a wallet adapter supports.
+ *
+ * Design: Option 5 — `supportedNetworks` + `excludedNetworks`.
+ *
+ * Most wallets list the networks they work with via `supportedNetworks`.
+ * Omitting both means "all networks". For wallets that work on all
+ * networks *except* specific ones (e.g. Mnemonic excludes MainNet for
+ * security), use `excludedNetworks`. Setting both is invalid.
+ */
+interface WalletCapabilities {
+  /** If set, the wallet is only available on these networks. */
+  supportedNetworks?: string[];
+  /** If set, the wallet is available on all networks EXCEPT these. */
+  excludedNetworks?: string[];
+}
+/**
+ * Scoped store accessor provided to each adapter instance.
+ * All mutations are pre-bound to the adapter's wallet key —
+ * adapters cannot accidentally modify another wallet's state.
+ */
+interface AdapterStoreAccessor {
+  getWalletState(): WalletState | undefined;
+  getActiveWallet(): WalletKey | null;
+  getActiveNetwork(): string;
+  getState(): State;
+  addWallet(wallet: WalletState): void;
+  removeWallet(): void;
+  setAccounts(accounts: WalletAccount[]): void;
+  setActiveAccount(address: string): void;
+  setActive(): void;
+}
+/**
+ * Constructor parameters for adapter classes.
+ * Generic over the options type so adapters receive typed options
+ * without unsafe casts.
+ */
+interface AdapterConstructorParams<TOptions = Record<string, unknown>> {
+  id: string;
+  metadata: WalletMetadata;
+  store: AdapterStoreAccessor;
+  subscribe: (callback: (state: State) => void) => () => void;
+  getAlgodClient: () => algosdk.Algodv2;
+  options?: TOptions;
+}
+/**
+ * Return type of adapter factory functions.
+ * Uses `Record<string, unknown>` for options (type erasure) because
+ * the manager handles heterogeneous adapter configs in a single array.
+ * Type safety lives in the factory function signature, not here.
+ */
+interface WalletAdapterConfig {
+  /** Unique identifier for this wallet adapter */
+  id: string;
+  /** Display metadata (name, icon) */
+  metadata: WalletMetadata;
+  /** The adapter class constructor */
+  Adapter: new (params: AdapterConstructorParams) => BaseWallet;
+  /** Wallet-specific options, passed through to the adapter constructor */
+  options?: Record<string, unknown>;
+  /** Network capabilities — which networks this wallet supports */
+  capabilities?: WalletCapabilities;
+}
+/**
+ * The public-facing wallet shape returned by framework hooks
+ * (e.g. `useWallet()` in React). Defined in core so all framework
+ * adapters share a single type.
+ */
+interface Wallet {
+  id: string;
+  walletKey: string;
+  metadata: WalletMetadata;
+  accounts: WalletAccount[];
+  activeAccount: WalletAccount | null;
+  isConnected: boolean;
+  isActive: boolean;
+  canSignData: boolean;
+  canUsePrivateKey: boolean;
+  connect: (args?: Record<string, any>) => Promise<WalletAccount[]>;
+  disconnect: () => Promise<void>;
+  setActive: () => void;
+  setActiveAccount: (address: string) => void;
+}
+type WalletState = {
+  accounts: WalletAccount[];
+  activeAccount: WalletAccount | null;
+};
+/** @see https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0001.md#interface-multisigmetadata */
+interface MultisigMetadata {
+  /**
+   * Multisig version.
+   */
+  version: number;
+  /**
+   * Multisig threshold value. Authorization requires a subset of signatures,
+   * equal to or greater than the threshold value.
+   */
+  threshold: number;
+  /**
+   * List of Algorand addresses of possible signers for this
+   * multisig. Order is important.
+   */
+  addrs: string[];
+}
+/** @see https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0001.md#interface-wallettransaction */
+interface WalletTransaction {
+  /**
+   * Base64 encoding of the canonical msgpack encoding of a Transaction.
+   */
+  txn: string;
+  /**
+   * Optional authorized address used to sign the transaction when the account
+   * is rekeyed. Also called the signor/sgnr.
+   */
+  authAddr?: string;
+  /**
+   * Multisig metadata used to sign the transaction
+   */
+  msig?: MultisigMetadata;
+  /**
+   * Optional list of addresses that must sign the transactions
+   */
+  signers?: string[];
+  /**
+   * Optional base64 encoding of the canonical msgpack encoding of a
+   * SignedTxn corresponding to txn, when signers=[]
+   */
+  stxn?: string;
+  /**
+   * Optional message explaining the reason of the transaction
+   */
+  message?: string;
+  /**
+   * Optional message explaining the reason of this group of transaction
+   * Field only allowed in the first transaction of a group
+   */
+  groupMessage?: string;
+}
+/** @see https://github.com/perawallet/connect/blob/1.3.4/src/util/model/peraWalletModels.ts */
+interface SignerTransaction {
+  txn: algosdk.Transaction;
+  /**
+   * Optional authorized address used to sign the transaction when
+   * the account is rekeyed. Also called the signor/sgnr.
+   */
+  authAddr?: string;
+  /**
+   * Optional list of addresses that must sign the transactions.
+   * Wallet skips to sign this txn if signers is empty array.
+   * If undefined, wallet tries to sign it.
+   */
+  signers?: string[];
+  /**
+   * Optional message explaining the reason of the transaction
+   */
+  message?: string;
+}
+interface JsonRpcRequest<T = any> {
+  id: number;
+  jsonrpc: string;
+  method: string;
+  params: T;
+}
+declare class SignTxnsError extends Error {
+  code: number;
+  data?: any;
+  constructor(message: string, code: number, data?: any);
+}
+interface Siwa {
+  domain: string;
+  account_address: string;
+  uri: string;
+  version: string;
+  statement?: string;
+  nonce?: string;
+  'issued-at'?: string;
+  'expiration-time'?: string;
+  'not-before'?: string;
+  'request-id'?: string;
+  chain_id: '283';
+  resources?: string[];
+  type: 'ed25519';
+}
+declare class SignDataError extends Error {
+  code: number;
+  data?: any;
+  constructor(message: string, code: number, data?: any);
+}
+interface SignData {
+  data: string;
+  signer: Uint8Array;
+  domain: string;
+  authenticatorData: Uint8Array;
+  requestId?: string;
+  hdPath?: string;
+  signature?: Uint8Array;
+}
+interface SignDataResponse extends SignData {
+  signature: Uint8Array;
+}
+declare enum ScopeType {
+  UNKNOWN = -1,
+  AUTH = 1
+}
+interface SignMetadata {
+  scope: ScopeType;
+  encoding: string;
+}
+//#endregion
+//#region src/store.d.ts
+type WalletStateMap = Partial<Record<WalletKey, WalletState>>;
+type ManagerStatus = 'initializing' | 'ready';
+interface State {
+  wallets: WalletStateMap;
+  activeWallet: WalletKey | null;
+  activeNetwork: string;
+  algodClient: algosdk.Algodv2;
+  managerStatus: ManagerStatus;
+  networkConfig: Record<string, NetworkConfig>;
+  customNetworkConfigs: Record<string, Partial<NetworkConfig>>;
+}
+declare const DEFAULT_STATE: State;
+declare function setActiveAccount(store: Store<State>, {
+  walletId,
+  address
+}: {
+  walletId: WalletKey;
+  address: string;
+}): void;
+//#endregion
+//#region src/wallets/base.d.ts
+declare abstract class BaseWallet<TOptions = Record<string, unknown>> {
+  readonly id: string;
+  readonly walletKey: string;
+  metadata: WalletMetadata;
+  protected options: TOptions;
+  protected store: AdapterStoreAccessor;
+  protected getAlgodClient: () => algosdk.Algodv2;
+  subscribe: (callback: (state: State) => void) => () => void;
+  protected logger: ReturnType<typeof logger.createScopedLogger>;
+  protected constructor({
+    id,
+    metadata,
+    store,
+    subscribe,
+    getAlgodClient,
+    options
+  }: AdapterConstructorParams<TOptions>);
+  static defaultMetadata: WalletMetadata;
+  abstract connect(args?: Record<string, any>): Promise<WalletAccount[]>;
+  abstract disconnect(): Promise<void>;
+  abstract resumeSession(): Promise<void>;
+  setActive: () => void;
+  setActiveAccount: (account: string) => void;
+  abstract signTransactions<T extends algosdk.Transaction[] | Uint8Array[]>(txnGroup: T | T[], indexesToSign?: number[]): Promise<(Uint8Array | null)[]>;
+  transactionSigner: (txnGroup: algosdk.Transaction[], indexesToSign: number[]) => Promise<Uint8Array[]>;
+  canSignData: boolean;
+  signData: (_data: string, _metadata: SignMetadata) => Promise<SignDataResponse>;
+  canUsePrivateKey: boolean;
+  withPrivateKey: <T>(_callback: (secretKey: Uint8Array) => Promise<T>) => Promise<T>;
+  get name(): string;
+  get accounts(): WalletAccount[];
+  get addresses(): string[];
+  get activeAccount(): WalletAccount | null;
+  get activeAddress(): string | null;
+  get activeNetwork(): string;
+  get isConnected(): boolean;
+  get isActive(): boolean;
+  get activeNetworkConfig(): NetworkConfig;
+  protected onDisconnect: () => void;
+  protected updateMetadata(updates: Partial<WalletMetadata>): void;
+}
+//#endregion
+export { NetworkConfigBuilder as A, WalletKey as C, AlgodConfig as D, WalletTransaction as E, LogLevel as M, DEFAULT_NETWORK_CONFIG as O, WalletId as S, WalletState as T, Siwa as _, setActiveAccount as a, WalletAdapterConfig as b, JsonRpcRequest as c, SignData as d, SignDataError as f, SignerTransaction as g, SignTxnsError as h, State as i, NetworkId as j, NetworkConfig as k, MultisigMetadata as l, SignMetadata as m, DEFAULT_STATE as n, AdapterConstructorParams as o, SignDataResponse as p, ManagerStatus as r, AdapterStoreAccessor as s, BaseWallet as t, ScopeType as u, Wallet as v, WalletMetadata as w, WalletCapabilities as x, WalletAccount as y };
+//# sourceMappingURL=base-BKrq-rUH.d.ts.map

package/dist/custom-BXQKth41.d.ts

@@ -0,0 +1,107 @@
+import { b as WalletAdapterConfig, m as SignMetadata, o as AdapterConstructorParams, p as SignDataResponse, t as BaseWallet, w as WalletMetadata, y as WalletAccount } from "./base-BKrq-rUH.js";
+import algosdk from "algosdk";
+
+//#region src/secure-key.d.ts
+/**
+ * Secure key handling utilities for managing sensitive cryptographic material.
+ *
+ * These utilities provide defense-in-depth for private key handling:
+ * 1. Memory zeroing - Overwrites key material before releasing references
+ * 2. Scoped key access - Keys are only available within controlled callbacks
+ * 3. Automatic cleanup - Keys are cleared after use via try/finally patterns
+ * 4. No persistence - Keys are never stored to disk/localStorage
+ */
+/**
+ * Securely zeros out a Uint8Array by overwriting all bytes with zeros.
+ * This helps prevent key material from lingering in memory.
+ *
+ * Note: JavaScript doesn't guarantee immediate memory clearing due to GC,
+ * but this provides defense-in-depth by:
+ * 1. Overwriting the buffer contents immediately
+ * 2. Reducing the window where key material is accessible
+ * 3. Preventing accidental key leakage through references
+ */
+declare function zeroMemory(buffer: Uint8Array): void;
+/**
+ * Securely zeros out a string by creating a mutable copy and clearing it.
+ * Returns an empty string. The original string in memory may still exist
+ * due to string immutability in JS, but this clears any mutable references.
+ */
+declare function zeroString(str: string): string;
+/**
+ * A secure container for holding private key material.
+ * Provides controlled access and automatic cleanup.
+ */
+declare class SecureKeyContainer {
+  private _secretKey;
+  private _isCleared;
+  constructor(secretKey: Uint8Array);
+  /**
+   * Check if the key has been cleared
+   */
+  get isCleared(): boolean;
+  /**
+   * Execute a callback with access to the secret key.
+   * The key is automatically cleared if an error occurs.
+   */
+  useKey<T>(callback: (secretKey: Uint8Array) => Promise<T>): Promise<T>;
+  /**
+   * Execute a synchronous callback with access to the secret key.
+   */
+  useKeySync<T>(callback: (secretKey: Uint8Array) => T): T;
+  /**
+   * Securely clear the key from memory.
+   * This should be called when the key is no longer needed.
+   */
+  clear(): void;
+}
+/**
+ * Execute a function with a temporary secret key that is automatically
+ * cleared after the function completes (success or error).
+ *
+ * This is the preferred pattern for one-time key operations.
+ */
+declare function withSecureKey<T>(secretKey: Uint8Array, callback: (container: SecureKeyContainer) => Promise<T>): Promise<T>;
+/**
+ * Synchronous version of withSecureKey for non-async operations.
+ */
+declare function withSecureKeySync<T>(secretKey: Uint8Array, callback: (container: SecureKeyContainer) => T): T;
+/**
+ * Derive an Algorand account from an ed25519 private key seed.
+ * The input key should be 32 bytes (seed).
+ *
+ * SECURITY: The returned account contains a secret key reference.
+ * The caller is responsible for zeroing account.sk after use.
+ */
+declare function deriveAlgorandAccountFromEd25519(ed25519Seed: Uint8Array): Promise<{
+  addr: string;
+  sk: Uint8Array;
+}>;
+//#endregion
+//#region src/wallets/custom.d.ts
+type CustomProvider = {
+  connect?(args?: Record<string, any>): Promise<WalletAccount[]>;
+  disconnect?(): Promise<void>;
+  resumeSession?(): Promise<WalletAccount[] | void>;
+  signTransactions?<T extends algosdk.Transaction[] | Uint8Array[]>(txnGroup: T | T[], indexesToSign?: number[]): Promise<(Uint8Array | null)[]>;
+  transactionSigner?(txnGroup: algosdk.Transaction[], indexesToSign: number[]): Promise<Uint8Array[]>;
+  signData?(data: string, metadata: SignMetadata): Promise<SignDataResponse>;
+};
+interface CustomWalletOptions {
+  provider: CustomProvider;
+}
+declare class CustomWallet extends BaseWallet<CustomWalletOptions> {
+  private provider;
+  constructor(params: AdapterConstructorParams<CustomWalletOptions>);
+  static defaultMetadata: WalletMetadata;
+  connect: (args?: Record<string, any>) => Promise<WalletAccount[]>;
+  disconnect: () => Promise<void>;
+  resumeSession: () => Promise<void>;
+  signTransactions: <T extends algosdk.Transaction[] | Uint8Array[]>(txnGroup: T | T[], indexesToSign?: number[]) => Promise<(Uint8Array | null)[]>;
+  transactionSigner: (txnGroup: algosdk.Transaction[], indexesToSign: number[]) => Promise<Uint8Array[]>;
+  signData: (data: string, metadata: SignMetadata) => Promise<SignDataResponse>;
+}
+declare function custom(options: CustomWalletOptions): WalletAdapterConfig;
+//#endregion
+export { SecureKeyContainer as a, withSecureKeySync as c, custom as i, zeroMemory as l, CustomWallet as n, deriveAlgorandAccountFromEd25519 as o, CustomWalletOptions as r, withSecureKey as s, CustomProvider as t, zeroString as u };
+//# sourceMappingURL=custom-BXQKth41.d.ts.map