@hsuite/connect-angular

Type-safe Angular/Ionic SDK for building multi-chain dApps with unified wallet connectivity via HSuite Channel Protocol and WalletConnect v2.

Features

• HSuite Channel Protocol - Native hsc: protocol with Nostr + P2P transport
• WalletConnect v2 - Universal wallet connectivity
• Reactive State - Angular signals for real-time updates
• Pre-built Components - Ready-to-use UI components
• Transaction Builders - Type-safe transaction construction for Hedera and XRPL
• Multi-Account Support - Manage multiple accounts across ledgers

Quick Start

# Install in your project
npm install @hsuite/connect-angular
# or
pnpm add @hsuite/connect-angular

# Build from source
pnpm --filter @hsuite/connect-angular build

# Run tests
pnpm --filter @hsuite/connect-angular test

Installation & Setup

The SDK supports both module-based and standalone Angular applications.

Option A: Module-Based Apps (Traditional Angular)

// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { IonicModule } from '@ionic/angular';
import { HsuiteWalletModule } from '@hsuite/connect-angular';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    IonicModule.forRoot(),
    HsuiteWalletModule, // Add this line
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

Option B: Standalone Components (Modern Angular)

// home.component.ts
import { Component, inject } from '@angular/core';
import { 
  WalletConnectButtonComponent,
  WalletSessionDisplayComponent,
  UnifiedWalletService 
} from '@hsuite/connect-angular';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [
    WalletConnectButtonComponent,
    WalletSessionDisplayComponent,
  ],
  template: `
    <wallet-connect-button [walletConnectProjectId]="'YOUR_PROJECT_ID'">
    </wallet-connect-button>
    <wallet-session-display></wallet-session-display>
  `
})
export class HomeComponent {
  wallet = inject(UnifiedWalletService);
}

Core Services

UnifiedWalletService

Central service for multi-protocol wallet management:

import { Component, inject } from '@angular/core';
import { UnifiedWalletService } from '@hsuite/connect-angular';

@Component({
  template: `
    <button (click)="connectHsuiteNative()">Connect via HSuite</button>
    <button (click)="connectWalletConnect()">Connect via WalletConnect</button>
    <div *ngIf="account()">Connected: {{ account()!.address }}</div>
  `
})
export class MyComponent {
  wallet = inject(UnifiedWalletService);
  account = this.wallet.activeAccount; // Signal

  // Connect via HSuite Native (hsc: protocol)
  async connectHsuiteNative() {
    await this.wallet.connect('hsuite-native', {
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
      appId: 'my-dapp',
      appName: 'My dApp',
    });
  }

  // Connect via WalletConnect v2
  async connectWalletConnect() {
    await this.wallet.connect('walletconnect-v2', {
      projectId: 'YOUR_PROJECT_ID',
      ledgerId: 'hedera',
      networkId: 'hedera:testnet'
    });
  }
}

Convenience Methods

const wallet = inject(UnifiedWalletService);

// Connection state
wallet.isConnected();              // boolean - any provider connected?
wallet.getConnectedLedgers();      // string[] - ['hedera', 'xrpl']

// Account management
wallet.getAccountsByLedger('hedera');        // UnifiedAccount[]
wallet.hasAccountsForLedger('xrpl');         // boolean
wallet.getPrimaryAccountForLedger('hedera'); // UnifiedAccount | undefined
wallet.switchAccount(accountId);             // boolean - switch by ID

// Active account (signal)
wallet.activeAccount();  // UnifiedAccount | null

ChannelClientService (HSuite Native)

Angular wrapper for the HSuite Channel Protocol:

import { Component, inject } from '@angular/core';
import { ChannelClientService } from '@hsuite/connect-angular';

@Component({
  template: `
    <div>State: {{ state() }}</div>
    <div>Transport: {{ transportState() }}</div>
    <div *ngIf="accounts().length">
      Accounts: {{ accounts() | json }}
    </div>
    <button (click)="connect()">Connect</button>
  `
})
export class ChannelComponent {
  private channelService = inject(ChannelClientService);

  // Reactive signals
  readonly state = this.channelService.state;
  readonly transportState = this.channelService.transportState;
  readonly accounts = this.channelService.accounts;

  async connect() {
    const invite = await this.channelService.connect({
      type: 'session',
      appId: 'my-dapp',
      appName: 'My dApp',
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
    });

    // Open wallet with invite URL
    const walletUrl = this.channelService.getWalletInviteUrl(
      invite,
      'https://wallet.hsuite.io'
    );
    window.open(walletUrl, 'hsuite-wallet');
  }

  async signTransaction(payload: Uint8Array) {
    const result = await this.channelService.signTransaction({
      payload,
      accountAddress: this.accounts()[0].address,
      ledgerId: 'hedera',
      networkId: 'hedera:testnet',
    });
    console.log('Signature:', result.signature);
  }
}

Channel States

| State | Description | |-------|-------------| | idle | No active connection | | connecting | Establishing channel | | pending | Waiting for wallet approval | | connected | Session active | | error | Connection failed |

Transport States

| State | Description | |-------|-------------| | nostr-only | Using Nostr relay | | upgrading | Attempting P2P | | p2p-connected | Direct P2P active | | p2p-failed | P2P failed, using Nostr |

HsuiteNativeProvider

Provider implementation for UnifiedWalletService:

/**
 * HsuiteNativeProvider
 * 
 * Implements BaseWalletProvider for HSuite Native Connect.
 * Uses ChannelClientService internally for channel-based communication.
 * 
 * Features:
 * - Automatic session persistence
 * - P2P transport upgrade
 * - Reactive account synchronization
 */
@Injectable({ providedIn: 'root' })
export class HsuiteNativeProvider extends BaseWalletProvider {
  readonly id = 'hsuite-native';
  
  // Status computed from channel state
  readonly status = computed<ConnectionStatus>(() => {
    const state = this.channelService.state();
    // Maps channel states to provider status
  });

  // Accounts from channel service
  readonly accounts = computed<UnifiedAccount[]>(() => {
    return this.channelService.accounts();
  });
}

Transaction Builders

Type-safe transaction construction for Hedera and XRPL:

import { Component, inject } from '@angular/core';
import { 
  HederaTransactionBuilderService,
  XrplTransactionBuilderService,
  UnifiedWalletService 
} from '@hsuite/connect-angular';

@Component({...})
export class TransactionComponent {
  private readonly wallet = inject(UnifiedWalletService);
  private readonly hederaBuilder = inject(HederaTransactionBuilderService);
  private readonly xrplBuilder = inject(XrplTransactionBuilderService);
  
  // Build and sign a Hedera HBAR transfer
  async sendHbar() {
    const payload = await this.hederaBuilder.buildSendHbar(
      '0.0.12345',  // from
      '0.0.67890',  // to
      10            // amount in HBAR
    );
    
    const result = await this.wallet.signAndSubmitTransaction({
      payload,
      ledgerId: 'hedera',
      networkId: 'hedera:testnet'
    });
  }
  
  // Build and sign an XRPL payment
  async sendXrp() {
    const payload = await this.xrplBuilder.buildPayment(
      'rAccountSource',  // from
      'rAccountDest',    // to
      '1000000'          // amount in drops (1 XRP)
    );
    
    const result = await this.wallet.signAndSubmitTransaction({
      payload,
      ledgerId: 'xrpl',
      networkId: 'xrpl:testnet'
    });
  }
}

Hedera Transaction Types

• buildSendHbar() - Transfer HBAR
• buildSendToken() - Transfer fungible tokens
• buildSendNft() - Transfer NFTs
• buildAssociateToken() - Associate tokens
• buildDissociateToken() - Dissociate tokens
• buildTokenCreate() - Create new tokens
• buildTokenMint() / buildTokenBurn() - Mint/burn tokens
• buildTopicCreate() / buildTopicMessageSubmit() - HCS topics
• buildBatchTransaction() - Batch transactions

XRPL Transaction Types

• buildPayment() - XRP or token payments
• buildTrustSet() - Establish trust lines
• buildOfferCreate() / buildOfferCancel() - DEX orders
• buildEscrowCreate() / buildEscrowFinish() / buildEscrowCancel() - Escrows
• buildNFTMint() / buildNFTBurn() - NFT operations
• buildBatchTransaction() - Batch transactions

Components

| Component | Selector | Description | |-----------|----------|-------------| | WalletConnectButtonComponent | <wallet-connect-button> | Ready-to-use connection button | | WalletSessionDisplayComponent | <wallet-session-display> | Display session information | | WalletTransactionStatusComponent | <wallet-transaction-status> | Transaction status indicator | | AccountSelectorComponent | <wallet-account-selector> | Multi-account dropdown | | WalletAccountDisplayComponent | <wallet-account-display> | Account details display | | WalletConnectPromptComponent | <wallet-connect-prompt> | Connection prompt UI | | WalletConnectedGuardComponent | <wallet-connected-guard> | Guard for protected routes | | WalletConnectionModalComponent | <hsuite-wallet-connection-modal> | Multi-protocol modal |

Directives

| Directive | Usage | Description | |-----------|-------|-------------| | WalletContextDirective | *walletContext | Provides wallet context to templates | | WalletConnectedDirective | *walletConnected | Conditional rendering based on connection | | WalletEventsDirective | walletEvents | Listen to wallet events |

Services

| Service | Description | |---------|-------------| | UnifiedWalletService | Multi-protocol wallet management | | ChannelClientService | HSuite Channel Protocol client | | WalletEventBus | Event system for wallet lifecycle | | WalletContextService | Centralized wallet context | | TransactionService | Transaction helper utilities | | WalletErrorHandler | Automatic error handling | | LoggerService | Scoped logging with production filtering | | HederaTransactionBuilderService | Build Hedera transactions | | XrplTransactionBuilderService | Build XRPL transactions |

Directory Structure

src/lib/
├── components/                    # UI components
│   ├── account-selector/          # Multi-account dropdown
│   ├── wallet-connect-button/     # Connection button
│   ├── wallet-session-display/    # Session info display
│   └── ...
├── directives/                    # Structural directives
│   ├── wallet-connected.directive.ts
│   ├── wallet-context.directive.ts
│   └── wallet-events.directive.ts
├── models/                        # TypeScript interfaces
│   ├── connection-config.model.ts
│   ├── provider-types.ts
│   ├── unified-account.model.ts
│   └── wallet-events.model.ts
├── providers/                     # Wallet providers
│   ├── hsuite-native/             # HSuite Channel Protocol
│   │   └── channel-client.service.ts
│   ├── hsuite-native-provider.ts  # Provider implementation
│   └── walletconnect/             # WalletConnect v2
├── services/                      # Core services
│   ├── unified-wallet.service.ts
│   ├── transaction-builders/
│   │   ├── hedera-transaction-builder.service.ts
│   │   └── xrpl-transaction-builder.service.ts
│   └── ...
└── transports/                    # Transport implementations
    └── chrome-extension-transport.ts

Scripts

| Command | Description | |---------|-------------| | pnpm build | Build library to dist/ | | pnpm test | Run Vitest tests | | pnpm test -- --watch | Watch mode | | pnpm lint | Lint code |

Documentation

📚 Full Documentation: docs/packages/angular-sdk.md

For comprehensive guides including:

• Complete API reference
• Multi-protocol integration
• Channel Protocol integration
• UI components and directives
• Event system
• Best practices

Related

• Main README - Project overview
• Documentation Index - All documentation
• Native Wallet SDK - Core SDK
• Channel Protocol - Protocol specification
• Companion dApp - Working example

Status: ✅ Production Ready | Framework: Angular 20+ | Protocols: HSuite Native + WalletConnect v2 | Tests: 277+ passing