nexa-wallet-sdk 0.1.2

package/spec.md

@@ -0,0 +1,257 @@
+# Nexa SDK Technical Specification (Draft)
+
+## Motivation
+
+Currently, Nexa lacks an easy-to-use wallet management SDK tailored for client-side web applications. Developers repeatedly face challenges re-implementing wallet functionalities. This SDK aims to simplify integration, standardize common wallet features, and encourage adoption of Nexa by lowering barriers to entry.
+
+## Objectives
+
+* Provide wallet and network management utilities.
+* Simplify transaction signing and verification.
+* Offer seamless dApp ↔ wallet communication.
+* Facilitate interactions with Rostrum (Electrum-based network provider).
+* Abstract away lower-level complexities provided by `libnexa-ts`.
+
+## Dependencies
+
+* `libnexa-ts`: Core Nexa blockchain utilities.
+* `electrum-cash`: Integration with Rostrum for network provider functionality.
+
+## Project Files Structure
+
+```
+src/
+├── wallet/
+│   ├── Wallet.ts             # Wallet instance creation and management
+│   ├── AccountStore.ts       # DefaultAccount management (create, import, export)
+│   └── UTXOStore.ts          # UTXO management (fetching, selection)
+├── network/
+│   ├── NetworkProvider.ts    # Interface for network providers
+│   └── RostrumProvider.ts    # Implementation of Rostrum provider
+├── dapp/
+│   └── DAppConnector.ts      # dApp communication utilities
+├── utils/
+│   ├── CryptoUtils.ts        # Cryptographic operations
+│   └── WalletUtils.ts        # Wallet helpers
+├── index.ts                  # SDK entry point
+└── types.ts                  # Shared types and interfaces
+```
+
+## Core Components
+
+### 1. Wallet Management (`wallet/`)
+
+* **Wallet.ts**
+
+  * Create, import, and manage wallet instances
+  * HD wallets, transaction signing, message signing, broadcasting
+
+* **AccountStore.ts**
+
+  * Multiple account handling within wallets
+
+* **UTXOStore.ts**
+
+  * UTXO fetching, caching, selection, and consolidation
+
+### 2. Network Interaction (`network/`)
+
+* **NetworkProvider.ts**
+
+  * Interface defining required network methods
+
+* **RostrumProvider.ts**
+
+  * Rostrum-specific implementation
+  * Connection handling and network interaction management
+
+### 3. dApp Communication (`dapp/`)
+
+* **DAppConnector.ts**
+
+  * dApp ↔ wallet interaction management
+
+### 4. Utilities (`utils/`)
+
+* **CryptoUtils.ts**
+
+  * Cryptographic tools (hashing, encoding)
+
+* **WalletUtils.ts**
+
+  * Wallet tools
+
+## Example Usage
+
+### Initialize Network Provider
+
+```typescript
+import { RostrumProvider } from 'nexa-sdk';
+
+const provider = new RostrumProvider('wss://rostrum.example.com');
+await provider.connect();
+```
+
+### Create and Initialize Wallet
+
+```typescript
+import { Wallet } from 'nexa-sdk';
+
+const wallet = Wallet.create();
+await wallet.initialize(provider);
+```
+
+### Recover Wallet from Seed Phrase
+
+```typescript
+import { Wallet } from 'nexa-sdk';
+
+const recoveredWallet = Wallet.fromSeedPhrase('your seed phrase here');
+await recoveredWallet.initialize(provider);
+```
+
+### Recover Wallet from Extended Private Key (xpriv)
+
+```typescript
+import { Wallet } from 'nexa-sdk';
+
+const xprivWallet = Wallet.fromXpriv('your xpriv here');
+await xprivWallet.initialize(provider);
+```
+
+### Prepare, Sign, and Broadcast WalletTransactionCreator
+
+```typescript
+const utxos = await wallet.utxoStore.getAvailableUTXOs();
+const txDetails = wallet.prepareTransaction({
+  utxos,
+  outputs: [{ address: 'nexa:q....', amount: 1000 }],
+});
+
+const signedTx = wallet.signTransaction(txDetails);
+await wallet.broadcastTransaction(signedTx);
+```
+
+### Send WalletTransactionCreator (Convenience Method)
+
+```typescript
+await wallet.sendTransaction({
+  outputs: [{ address: 'nexa:q....', amount: 1000 }],
+});
+```
+
+### Export Wallet Data
+
+```typescript
+const exportedData = wallet.export();
+```
+
+## Component Designs
+
+### 1. Wallet.ts
+
+#### Dependencies:
+
+* AccountStore
+* UTXOStore
+* NetworkProvider (interface)
+* CryptoUtils
+* WalletUtils
+
+#### Functions:
+
+* `create(): Wallet`
+* `fromSeedPhrase(phrase: string): Wallet`
+* `fromXpriv(xpriv: string): Wallet`
+* `initialize(provider: NetworkProvider): Promise<void>`
+* `prepareTransaction(details: TransactionDetails): WalletTransactionCreator`
+* `signTransaction(transaction: WalletTransactionCreator): SignedTransaction`
+* `broadcastTransaction(signedTx: SignedTransaction): Promise<void>`
+* `sendTransaction(details: TransactionDetails): Promise<void>`
+* `signMessage(message: string): string`
+* `verifyMessage(message: string, signature: string): boolean`
+* `export(): WalletExport`
+
+### 2. AccountStore.ts
+
+#### Dependencies:
+
+* CryptoUtils
+
+#### Functions:
+
+* `createAccount(): DefaultAccount`
+* `importAccount(accountData: AccountImport): DefaultAccount`
+* `exportAccount(accountId: string): AccountExport`
+* `removeAccount(accountId: string): void`
+* `listAccounts(): DefaultAccount[]`
+
+### 3. UTXOStore.ts
+
+#### Dependencies:
+
+* NetworkProvider (interface)
+
+#### Functions:
+
+* `getAvailableUTXOs(): Promise<UTXO[]>`
+* `selectUTXOs(amount: number): UTXO[]`
+* `consolidateUTXOs(): WalletTransactionCreator`
+
+### 4. NetworkProvider.ts (Interface)
+
+#### Interface Methods:
+
+* `connect(): Promise<void>`
+* `disconnect(): Promise<void>`
+* `getUTXOs(addresses: string[]): Promise<UTXO[]>`
+* `broadcastTransaction(signedTx: SignedTransaction): Promise<void>`
+* `getTransactionHistory(address: string): Promise<TransactionHistory[]>`
+
+### 5. RostrumProvider.ts
+
+#### Dependencies:
+
+* NetworkProvider (interface)
+
+#### Functions:
+
+* Implements all methods defined in NetworkProvider interface
+
+### 6. DAppConnector.ts
+
+#### Dependencies:
+
+* CryptoUtils
+
+#### Functions:
+
+* `authorizeDApp(dAppId: string): Promise<boolean>`
+* `signDAppTransaction(request: DAppTransactionRequest): Promise<SignedTransaction>`
+* `listenToRequests(callback: (request: DAppRequest) => void): void`
+* `respondToRequest(requestId: string, response: DAppResponse): void`
+
+
+## Dependency Graph
+
+```
+Wallet.ts
+├── AccountStore.ts
+│   └── CryptoUtils.ts
+├── UTXOStore.ts
+│   └── NetworkProvider.ts (interface)
+└── DAppConnector.ts
+
+ValidationUtils.ts
+└── CryptoUtils.ts
+```
+
+## Technical Considerations
+
+* Use TypeScript for strong typing and clear interfaces.
+* Implement robust error handling and clear exception messages.
+* Follow modular design principles for easier maintenance and extendability.
+
+## Conclusion
+
+The Nexa Wallet SDK provides a complete, developer-friendly toolkit that simplifies building web3 applications on Nexa. It addresses critical developer pain points, accelerates development cycles, and fosters broader adoption through streamlined wallet and network interactions.

package/src/index.ts

@@ -0,0 +1,93 @@
+// @ts-ignore
+import { version } from '../package.json';
+import Wallet from "./wallet/Wallet";
+
+/**
+ * Guards against multiple instances of the wallet SDK being loaded.
+ * This prevents conflicts and ensures only one version is active at a time.
+ * @param version - The version string to check
+ * @throws {Error} When multiple instances are detected
+ */
+function versionGuard(version: string): void {
+    if (version !== undefined) {
+        let message = 'More than one instance of Wallet SDK' +
+            'Please make sure to require Wallet SDK and check that submodules do' +
+            ' not also include their own Wallet SDK dependency.';
+        throw new Error(message);
+    }
+}
+
+versionGuard((global as any)._walletSdk_ver);
+(global as any)._walletSdk_ver = `v${version}`;
+
+/**
+ * Wallet SDK - A TypeScript SDK for the Nexa blockchain
+ *
+ * This SDK provides comprehensive wallet functionality including:
+ * - Creating and managing wallets from seed phrases or private keys
+ * - Account management with different account types
+ * - Transaction building and signing
+ * - Token operations and management
+ * - Message signing and verification
+ *
+ * @example
+ * ```typescript
+ * import { Wallet } from 'wallet-sdk-ts';
+ *
+ * // Create a new wallet
+ * const wallet = Wallet.create();
+ *
+ * // Or restore from seed phrase
+ * const wallet = Wallet.fromSeedPhrase('your seed phrase here');
+ *
+ * // Initialize and discover accounts
+ * await wallet.initialize();
+ * ```
+ */
+const walletSdk = {
+    versionGuard,
+    version: `v${version}`,
+    Wallet
+}
+
+export default walletSdk
+
+export { default as Wallet } from './wallet/Wallet'
+export { default as WatchOnlyWallet } from './wallet/WatchOnlyWallet'
+
+// Export utility enums and types
+export { AccountType, TxTokenType } from './utils/WalletUtils'
+
+// Export account interfaces and classes
+export { BaseAccount } from './wallet/accounts/interfaces/BaseAccountInterface'
+export { default as DefaultAccount } from './wallet/accounts/models/DefaultAccount'
+export { default as DappAccount } from './wallet/accounts/models/DappAccount'
+export { default as VaultAccount } from './wallet/accounts/models/VaultAccount'
+export { default as AccountStore } from './wallet/accounts/AccountStore'
+
+// Export transaction creators
+export { default as WalletTransactionCreator } from './wallet/transactions/WalletTransactionCreator'
+export { default as WatchOnlyTransactionCreator } from './wallet/transactions/WatchOnlyTransactionCreator'
+
+// Export network provider
+export { rostrumProvider } from './network/RostrumProvider'
+
+// Export entity types and interfaces
+export type {
+    AccountKeys,
+    AccountIndexes,
+    AddressKey,
+    Balance,
+    WatchOnlyAddress,
+    TxStatus,
+    HodlStatus
+} from './models/wallet.entities'
+
+export type {
+    TxEntityState,
+    TxTemplateData,
+    TxOptions,
+    TokenAction,
+    PermissionLabel,
+    TransactionEntity
+} from './models/transaction.entities'

package/src/models/rostrum.entities.ts

@@ -0,0 +1,159 @@
+export type RostrumTransportScheme = 'ws' | 'wss';
+
+export const RostrumScheme = {
+    WS: 'ws',
+    WSS: 'wss'
+}
+
+export interface RostrumParams {
+    scheme: RostrumTransportScheme;
+    host: string;
+    port: number;
+}
+
+export interface BlockTip {
+    height: number;
+    hex: string;
+}
+
+export interface IFirstUse {
+    block_hash: string;
+    block_height: number;
+    height: number;
+    tx_hash: string;
+}
+
+export interface ITokenGenesis {
+    decimal_places?: number,
+    document_hash?: string;
+    document_url?: string;
+    group: string;
+    height: number;
+    name?: string;
+    op_return?: string;
+    ticker?: string;
+    token_id_hex: string;
+    txid: string;
+    txidem: string;
+    op_return_id: number;
+}
+
+export interface ITokensBalance {
+    cursor?: any;
+    confirmed: Record<string, bigint | number>;
+    unconfirmed: Record<string, bigint | number>;
+}
+
+export interface ITokenListUnspent {
+    cursor?: any;
+    unspent: ITokenUtxo[];
+}
+
+export interface ITokenUtxo {
+    group: string;
+    height: number;
+    outpoint_hash: string;
+    token_amount: number | bigint;
+    token_id_hex: string;
+    tx_hash: string;
+    tx_pos: number;
+    value: number;
+}
+
+export interface IListUnspentRecord {
+    has_token: boolean;
+    height: number;
+    outpoint_hash: string;
+    tx_hash: string;
+    tx_pos: number;
+    value: number;
+}
+
+export interface IUtxo {
+    addresses: string[];
+    amount: number;
+    group: string;
+    group_authority: bigint | number;
+    group_quantity: bigint | number;
+    height: number;
+    scripthash: string;
+    scriptpubkey: string;
+    spent: ISpent;
+    status: string;
+    template_argumenthash: string;
+    template_scripthash: string;
+    token_id_hex: string;
+    tx_hash: string;
+    tx_idem: string;
+    tx_pos: number;
+}
+
+export interface ISpent {
+    height: number;
+    tx_hash: string;
+    tx_pos: number;
+}
+
+export interface ITransaction {
+    blockhash: string;
+    blocktime: number;
+    confirmations: number;
+    fee: number;
+    fee_satoshi: number;
+    hash: string;
+    height: number;
+    hex: string;
+    locktime: number;
+    size: number;
+    time: number;
+    txid: string;
+    txidem: string;
+    version: number;
+    vin: ITXInput[];
+    vout: ITXOutput[];
+}
+
+export interface ITXInput {
+    outpoint: string;
+    scriptSig: IScriptSig;
+    sequence: number;
+    value: number;
+    value_satoshi: bigint | number;
+    addresses: string[];
+    group: string;
+    groupAuthority: bigint | number;
+    groupQuantity: bigint | number;
+}
+
+export interface ITXOutput {
+    n: number;
+    outpoint_hash: string;
+    scriptPubKey: IScriptPubKey;
+    type: number;
+    value: number;
+    value_satoshi: bigint | number;
+}
+
+export interface IScriptSig {
+    asm: string;
+    hex: string;
+}
+
+export interface IScriptPubKey {
+    addresses: string[];
+    argHash: string;
+    asm: string;
+    group: string;
+    groupAuthority: bigint | number;
+    groupQuantity: bigint | number;
+    hex: string;
+    scriptHash: string;
+    token_id_hex?: string;
+    type: string;
+}
+
+export interface ITXHistory {
+    fee?: number;
+    height: number;
+    tx_hash: string;
+}

package/src/models/transaction.entities.ts

@@ -0,0 +1,46 @@
+import {PublicKey, Script} from "libnexa-ts";
+
+export type PermissionLabel = 'authorise' | 'mint' | 'melt' | 'rescript' | 'subgroup';
+
+export type TxEntityState = 'incoming' | 'outgoing' | 'both'
+
+export interface TxTemplateData {
+    templateScript: Script;
+    constraintScript: Script;
+    visibleArgs: any[];
+    publicKey: PublicKey;
+}
+
+export interface TxOptions {
+    isConsolidate?: boolean;
+    toChange?: string;
+    templateData?: TxTemplateData;
+    feeFromAmount?: boolean;
+}
+export interface TokenAction {
+    token?: string
+    parentToken?: string
+    amount: bigint;
+    action: string;
+    extraData?: {
+        perms?: PermissionLabel[],
+        outpoint?: string
+        opReturnData?: string
+        address?: string
+    }
+}
+
+export interface TransactionEntity {
+    txIdem: string
+    txId: string
+    time: number
+    height: number
+    payTo: string
+    state: TxEntityState
+    value: string
+    fee: number
+    token: string
+    extraGroup: string
+    txGroupType: number
+    tokenAmount: string
+}

package/src/models/wallet.entities.ts

@@ -0,0 +1,42 @@
+import type bigDecimal from "js-big-decimal";
+import type {HDPrivateKey, PublicKey} from "libnexa-ts"
+
+export interface AccountKeys {
+    receiveKeys: AddressKey[];
+    changeKeys: AddressKey[];
+}
+export interface WatchOnlyAddress {
+    address: string,
+    xPub? :PublicKey,
+    derivationPath?: string
+}
+
+export interface AccountIndexes {
+    rIndex: number;
+    cIndex: number;
+}
+
+export interface TxStatus {
+    height: number;
+}
+
+export interface HodlStatus {
+    idx: number;
+}
+
+export interface AddressKey {
+    key: HDPrivateKey;
+    address: string;
+    balance: string;
+    tokensBalance: Record<string, Balance>;
+}
+
+export interface Balance {
+    confirmed: string | number;
+    unconfirmed: string | number;
+}
+
+export interface Price {
+    value: bigDecimal;
+    change: bigDecimal;
+}