@dolaned/wallet-sdk-ts/spec.md

Wallet SDK for the Nexa blockchain

# 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.