@hsuite/native-connect-angular 1.0.0 → 2.1.1

package/dist/index.d.ts

@@ -1,16 +1,17 @@
 import * as i0 from '@angular/core';
-import { Signal, NgZone, EventEmitter, OnInit, TemplateRef, OnDestroy, Provider } from '@angular/core';
+import { Signal, NgZone, EventEmitter, OnInit, TemplateRef, OnDestroy, InjectionToken, Provider } from '@angular/core';
 import * as i1 from '@angular/common';
 import * as i2 from '@ionic/angular';
 import { ModalController as ModalController$1 } from '@ionic/angular';
 import { ModalController, AlertController, ToastController } from '@ionic/angular/standalone';
 import * as _hsuite_native_connect_sdk from '@hsuite/native-connect-sdk';
-import { TransportState, Logger, TransportProvider, ChannelState, ChannelAccount, ChannelInvite, ChannelType } from '@hsuite/native-connect-sdk';
+import { SupportedLedger, TransportState, Logger, TransportProvider, ChannelState, ChannelAccount, ChannelInvite, ChannelType } from '@hsuite/native-connect-sdk';
 export { ChannelAccount, ChannelInvite, ChannelMessage, ChannelState, ChannelType, HederaTransactionEncoder, MessageType, TransportState, XrplTransactionEncoder } from '@hsuite/native-connect-sdk';
 import * as _hsuite_native_connect_angular from '@hsuite/native-connect-angular';
 import { Observable } from 'rxjs';
-import { MessageEnvelope } from '@hsuite/native-connect-types';
-export { RpcEnvelope, RpcRequest, RpcResponse, SessionApproval } from '@hsuite/native-connect-types';
+import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpInterceptorFn } from '@angular/common/http';
+import { MessageEnvelope, LedgerId } from '@hsuite/native-connect-types';
+export { LedgerId, RpcEnvelope, RpcRequest, RpcResponse, SessionApproval } from '@hsuite/native-connect-types';
 import SignClient from '@walletconnect/sign-client';
 import { WalletConnectModal } from '@walletconnect/modal';
 import { ISignClient } from '@walletconnect/types';
@@ -36,6 +37,7 @@ import { ISignClient } from '@walletconnect/types';
  *                  \-> error
  * ```
  */
+
 /**
  * Supported wallet connection protocol types.
  *
@@ -134,7 +136,7 @@ interface HsuiteNativeConfig {
 interface WalletConnectV2Config {
     type: 'walletconnect-v2';
     projectId: string;
-    ledgerId: 'hedera' | 'xrpl';
+    ledgerId: SupportedLedger;
     networkId: string;
     appName?: string;
     appDescription?: string;
@@ -176,7 +178,7 @@ type ConnectionConfig$1 = HsuiteNativeConfig | WalletConnectV2Config | MobileNat
  * visit https://hsuite.finance/licensing
  */
 /**
- * @fileoverview Unified account model that works across all wallet providers.
+ * @file Unified account model that works across all wallet providers.
  *
  * @module models/unified-account
  *
@@ -208,6 +210,8 @@ interface UnifiedAccount {
     id: string;
     /** Account address/public key */
     address: string;
+    /** Public key associated with the account, when available from the provider. */
+    publicKey?: string;
     /** Human-readable label */
     label?: string;
     /** Ledger ID (e.g., 'hedera', 'xrpl') */
@@ -1883,7 +1887,7 @@ declare class UnifiedWalletService {
      * @throws {Error} If provider is not found
      * @throws {Error} If user rejects the signing request
      */
-    signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<unknown>;
+    signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<SignMessageResult>;
     /**
      * Signs and executes a transaction in a single prompt.
      *
@@ -2021,6 +2025,12 @@ declare class WalletConnectButtonComponent {
      * Wallet URL for targeting the wallet window
      */
     walletUrl: string;
+    /**
+     * Pins the connection network and hides the network-selection step in the
+     * modal. When set to `'mainnet'` or `'testnet'`, the dApp decides the network
+     * and the user never sees the picker. When omitted, the user chooses.
+     */
+    network?: 'mainnet' | 'testnet';
     /**
      * Whether to show session information when connected
      * @default true
@@ -2104,7 +2114,7 @@ declare class WalletConnectButtonComponent {
      */
     getConnectedAccounts(): any[];
     static ɵfac: i0.ɵɵFactoryDeclaration<WalletConnectButtonComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<WalletConnectButtonComponent, "wallet-connect-button", never, { "walletConnectProjectId": { "alias": "walletConnectProjectId"; "required": false; }; "appName": { "alias": "appName"; "required": false; }; "appDescription": { "alias": "appDescription"; "required": false; }; "walletUrl": { "alias": "walletUrl"; "required": false; }; "showSessionInfo": { "alias": "showSessionInfo"; "required": false; }; "buttonColor": { "alias": "buttonColor"; "required": false; }; "size": { "alias": "size"; "required": false; }; "connectText": { "alias": "connectText"; "required": false; }; "connectedText": { "alias": "connectedText"; "required": false; }; "multiSessionMode": { "alias": "multiSessionMode"; "required": false; }; }, { "connected": "connected"; "disconnected": "disconnected"; "error": "error"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<WalletConnectButtonComponent, "wallet-connect-button", never, { "walletConnectProjectId": { "alias": "walletConnectProjectId"; "required": false; }; "appName": { "alias": "appName"; "required": false; }; "appDescription": { "alias": "appDescription"; "required": false; }; "walletUrl": { "alias": "walletUrl"; "required": false; }; "network": { "alias": "network"; "required": false; }; "showSessionInfo": { "alias": "showSessionInfo"; "required": false; }; "buttonColor": { "alias": "buttonColor"; "required": false; }; "size": { "alias": "size"; "required": false; }; "connectText": { "alias": "connectText"; "required": false; }; "connectedText": { "alias": "connectedText"; "required": false; }; "multiSessionMode": { "alias": "multiSessionMode"; "required": false; }; }, { "connected": "connected"; "disconnected": "disconnected"; "error": "error"; }, never, never, true, never>;
 }
 
 /**
@@ -3093,13 +3103,18 @@ declare class WalletAccountDisplayComponent {
      * Get multisig threshold info (e.g., "2/3")
      */
     protected readonly multisigInfo: i0.Signal<string>;
+    /**
+     *
+     */
     constructor();
     /**
      * Get color for ledger badge
+     * @param ledgerId
      */
     protected getLedgerColor(ledgerId: string): string;
     /**
      * Format network ID for display
+     * @param networkId
      */
     protected formatNetwork(networkId: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<WalletAccountDisplayComponent, never>;
@@ -3279,7 +3294,7 @@ interface ProtocolOption {
  * Ledger configuration options
  */
 interface LedgerOption {
-    id: 'hedera' | 'xrpl';
+    id: SupportedLedger;
     name: string;
     description: string;
     icon: string;
@@ -3298,13 +3313,22 @@ interface StepConfig {
  * Main wallet connection modal component.
  * Orchestrates the multi-step connection flow.
  */
-declare class WalletConnectionModalComponent {
+declare class WalletConnectionModalComponent implements OnInit {
     private modalController;
     private unifiedWalletService;
     /**
      * WalletConnect project ID (required for WalletConnect)
      */
     projectId?: string;
+    /**
+     * Pins the connection network and hides the network-selection step.
+     *
+     * When set to `'mainnet'` or `'testnet'`, the host dApp decides the network
+     * and the user is never shown the network picker — the modal opens directly
+     * on protocol selection. When omitted (default), the user chooses the network
+     * as the first step.
+     */
+    network?: 'mainnet' | 'testnet';
     /**
      * App name for WalletConnect metadata
      */
@@ -3328,7 +3352,7 @@ declare class WalletConnectionModalComponent {
     readonly selectedNetwork: i0.WritableSignal<string>;
     readonly selectedProtocol: i0.WritableSignal<"hsuite-native" | "walletconnect">;
     readonly selectedConnectionMethod: i0.WritableSignal<ConnectionMethod>;
-    readonly selectedLedger: i0.WritableSignal<"hedera" | "xrpl">;
+    readonly selectedLedger: i0.WritableSignal<SupportedLedger>;
     readonly isConnecting: i0.WritableSignal<boolean>;
     readonly connectionError: i0.WritableSignal<string>;
     readonly pairingOffer: i0.WritableSignal<string>;
@@ -3372,12 +3396,27 @@ declare class WalletConnectionModalComponent {
      * Different protocol paths have different step mappings.
      */
     readonly displayStep: i0.Signal<number>;
+    /**
+     * Whether a back affordance should be offered for the current step.
+     * The first reachable step has no back target — that is protocol selection
+     * when the network is pinned, otherwise network selection. The connection
+     * progress step manages its own retry navigation instead.
+     */
+    readonly canGoBack: i0.Signal<boolean>;
     /**
      *
      * @param modalController
      * @param unifiedWalletService
      */
     constructor(modalController: ModalController$1, unifiedWalletService: UnifiedWalletService);
+    /**
+     * Apply the pinned network (if any) before the first render.
+     *
+     * When the host dApp provides a {@link network}, lock the selection to it and
+     * skip straight to protocol selection so the user never sees — and cannot
+     * change — the network. With no input, the modal opens on network selection.
+     */
+    ngOnInit(): void;
     /**
      * Select a network option (internal, use selectNetworkAndProceed for UI)
      * @param networkId
@@ -3416,13 +3455,13 @@ declare class WalletConnectionModalComponent {
      * Select a ledger option (internal, use selectLedgerAndConnect for UI)
      * @param ledgerId
      */
-    selectLedger(ledgerId: 'hedera' | 'xrpl'): void;
+    selectLedger(ledgerId: SupportedLedger): void;
     /**
      * Select a ledger and automatically initiate connection.
      * This enables direct selection behavior for WalletConnect ledger step.
      * @param ledgerId - The ledger ID to select ('hedera' or 'xrpl')
      */
-    selectLedgerAndConnect(ledgerId: 'hedera' | 'xrpl'): void;
+    selectLedgerAndConnect(ledgerId: SupportedLedger): void;
     /**
      * Proceed to the next step in the wizard
      */
@@ -3476,7 +3515,7 @@ declare class WalletConnectionModalComponent {
      */
     private detectExtension;
     static ɵfac: i0.ɵɵFactoryDeclaration<WalletConnectionModalComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<WalletConnectionModalComponent, "hsuite-wallet-connection-modal", never, { "projectId": { "alias": "projectId"; "required": false; }; "appName": { "alias": "appName"; "required": false; }; "appDescription": { "alias": "appDescription"; "required": false; }; "walletUrl": { "alias": "walletUrl"; "required": false; }; }, { "connected": "connected"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<WalletConnectionModalComponent, "hsuite-wallet-connection-modal", never, { "projectId": { "alias": "projectId"; "required": false; }; "network": { "alias": "network"; "required": false; }; "appName": { "alias": "appName"; "required": false; }; "appDescription": { "alias": "appDescription"; "required": false; }; "walletUrl": { "alias": "walletUrl"; "required": false; }; }, { "connected": "connected"; }, never, never, true, never>;
 }
 
 /**
@@ -4562,7 +4601,7 @@ declare class TransactionService {
      * @param message - Message to sign
      * @returns Sign result with signature
      */
-    signMessage(message: string): Promise<SignResult>;
+    signMessage(message: string): Promise<SignMessageResult>;
     /**
      * Show a success toast notification
      * Uses cssClass-only styling (no Ionic color property) for theme compatibility.
@@ -4692,6 +4731,233 @@ declare class LoggerService {
     static ɵprov: i0.ɵɵInjectableDeclaration<LoggerService>;
 }
 
+/**
+ * Configuration token for {@link SmartSessionService}.
+ */
+declare const SMART_SESSION_CONFIG: InjectionToken<SmartSessionConfig>;
+/**
+ * Configuration for the smart-host session handshake.
+ */
+interface SmartSessionConfig {
+    /**
+     * Base URL for the smart-host API.
+     * @default '' (relative to the current origin)
+     */
+    baseUrl?: string;
+    /**
+     * Health endpoint used to discover the host `appId`.
+     * @default '/api/health'
+     */
+    healthEndpoint?: string;
+    /**
+     * Challenge endpoint used to obtain a message to sign.
+     * @default '/api/auth/challenge'
+     */
+    challengeEndpoint?: string;
+    /**
+     * Verify endpoint used to exchange the signed challenge for a bearer token.
+     * @default '/api/auth/verify'
+     */
+    verifyEndpoint?: string;
+    /**
+     * sessionStorage key used to persist the session token and expiry.
+     * @default 'hsuite.smart-session'
+     */
+    storageKey?: string;
+}
+/**
+ * Health response shape expected from the smart host.
+ */
+interface SmartHostHealth {
+    appId: string;
+    [key: string]: unknown;
+}
+/**
+ * Challenge response shape expected from the smart host.
+ */
+interface SmartHostChallenge {
+    challenge: string;
+    [key: string]: unknown;
+}
+/**
+ * Verify request payload sent to the smart host.
+ */
+interface SmartHostVerifyRequest {
+    appId: string;
+    accountAddress: string;
+    publicKey?: string;
+    signature: string;
+    algorithm?: string;
+    message: string;
+    caipChainId?: string;
+    ledgerId?: string;
+    networkId?: string;
+}
+/**
+ * Verify response shape expected from the smart host.
+ */
+interface SmartHostVerifyResponse {
+    bearer: string;
+    expiresAt?: number;
+    expiresIn?: number;
+    [key: string]: unknown;
+}
+/**
+ * Smart-host customer session helper.
+ *
+ * @service SmartSessionService
+ *
+ * @description
+ * Encapsulates the full challenge → sign → verify → store JWT flow required by
+ * HSuite smart hosts. The service is intentionally thin: it delegates signing to
+ * {@link TransactionService} and relies on standard Angular `HttpClient` for the
+ * host HTTP calls.
+ *
+ * @providedIn root
+ */
+declare class SmartSessionService {
+    private readonly http;
+    private readonly walletService;
+    private readonly transactionService;
+    private readonly config;
+    private get baseUrl();
+    private get healthEndpoint();
+    private get challengeEndpoint();
+    private get verifyEndpoint();
+    private get storageKey();
+    /**
+     * Returns the currently stored bearer token, or `null` if there is no session.
+     *
+     * @returns Bearer token string or null
+     */
+    getBearer(): string | null;
+    /**
+     * Checks whether a non-expired session is available.
+     *
+     * @returns true if logged in and the bearer has not expired
+     */
+    isLoggedIn(): boolean;
+    /**
+     * Performs the full smart-host login handshake.
+     *
+     * @description
+     * 1. Discovers `appId` from the health endpoint.
+     * 2. Fetches a challenge from the challenge endpoint.
+     * 3. Signs the challenge with the active wallet account.
+     * 4. Exchanges the signed challenge for a bearer token.
+     * 5. Stores the bearer and expiry in `sessionStorage`.
+     *
+     * @returns The verify response from the host
+     *
+     * @throws {Error} If no active account is available
+     * @throws {Error} If the health endpoint does not return an `appId`
+     * @throws {Error} If the challenge endpoint does not return a `challenge`
+     * @throws {Error} If the verify call fails
+     */
+    login(): Promise<SmartHostVerifyResponse>;
+    /**
+     * Clears the stored session.
+     */
+    logout(): void;
+    /**
+     * Runs an HTTP operation with automatic 401 recovery.
+     *
+     * @description
+     * Executes the provided operation. If it rejects with an HTTP 401 error,
+     * the service clears the current bearer, performs a fresh login, and retries
+     * the operation once. Any other error is propagated immediately.
+     *
+     * @param operation - Async operation that needs a valid session
+     * @returns The result of the operation
+     *
+     * @throws {Error} The original error if retry is not possible or fails
+     */
+    withSession<T>(operation: () => Promise<T>): Promise<T>;
+    private fetchHealth;
+    private fetchChallenge;
+    private verifyChallenge;
+    private resolveExpiry;
+    private readStoredSession;
+    private storeSession;
+    private clearStoredSession;
+    private isUnauthorizedError;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SmartSessionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SmartSessionService>;
+}
+
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file HTTP interceptor that attaches wallet-attributed auth headers.
+ *
+ * @module services/hsuite-auth-interceptor
+ *
+ * @description
+ * `HsuiteAuthInterceptor` automatically adds the active smart-host bearer token
+ * and wallet ledger identifier to outgoing HTTP requests. When a request fails
+ * with HTTP 401, it delegates recovery to {@link SmartSessionService} for a
+ * single re-login and retry.
+ *
+ * **Registration (standalone apps):**
+ * ```typescript
+ * provideHttpClient(withInterceptors([provideHsuiteAuthInterceptor()]))
+ * ```
+ *
+ * **Registration (module-based apps):**
+ * ```typescript
+ * { provide: HTTP_INTERCEPTORS, useClass: HsuiteAuthInterceptor, multi: true }
+ * ```
+ */
+
+/**
+ * Headers injected by the interceptor.
+ */
+declare const HSUITE_AUTH_HEADER = "Authorization";
+declare const HSUITE_LEDGER_HEADER = "X-Ledger-Id";
+/**
+ * Functional HTTP interceptor that attaches wallet-attributed auth headers.
+ *
+ * @description
+ * Adds:
+ * - `Authorization: Bearer <token>` when {@link SmartSessionService.getBearer} returns a token
+ * - `X-Ledger-Id: <ledgerId>` when a wallet account is active
+ *
+ * On 401 responses, clears the stale bearer and retries once after re-login.
+ *
+ * @param req - The outgoing HTTP request
+ * @param next - The downstream request handler
+ * @returns Observable of HTTP events
+ */
+declare const hsuiteAuthInterceptor: HttpInterceptorFn;
+/**
+ * Class-based HTTP interceptor for module-based Angular apps.
+ *
+ * @description
+ * Provides the same behavior as {@link hsuiteAuthInterceptor} in a class form
+ * suitable for registration via `HTTP_INTERCEPTORS`.
+ */
+declare class HsuiteAuthInterceptor implements HttpInterceptor {
+    private readonly session;
+    private readonly wallet;
+    /**
+     * Intercepts outgoing HTTP requests to attach wallet-attributed auth headers.
+     *
+     * @param req - The outgoing HTTP request
+     * @param next - The downstream request handler
+     * @returns Observable of HTTP events
+     */
+    intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HsuiteAuthInterceptor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HsuiteAuthInterceptor>;
+}
+
 /**
  * Supported inner transaction types for batch transactions.
  * Excludes 'batch-transaction' since batches cannot be nested.
@@ -4856,7 +5122,7 @@ interface AccountCreateOptions {
  * ```
  */
 declare class HederaTransactionBuilderService {
-    private readonly wallet;
+    private readonly accountSource;
     private readonly logger;
     /**
      * Gets the network ID from the active wallet account.
@@ -5461,6 +5727,49 @@ declare class XrplTransactionBuilderService {
  */
 declare function scaleHederaAmountToBaseUnits(amount: number, decimals: number): bigint;
 
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+/**
+ * @file ACTIVE_ACCOUNT_SOURCE: the minimal active-account read surface the
+ * transaction builders need.
+ *
+ * @description
+ * The Hedera transaction builder only reads `activeAccount()` from the wallet
+ * (to pick the network and the entity key config). Injecting the whole
+ * {@link UnifiedWalletService} couples the builder to a heavy root service that
+ * also runs the dApp connect stack on construction. This token narrows that
+ * dependency to a single member.
+ *
+ * The default provider points at {@link UnifiedWalletService}, so existing SDK
+ * consumers that already provide it need NO wiring change (backward
+ * compatible). The embedded widget shell overrides this token with a one-member
+ * account context, which keeps the heavy root service from ever being
+ * constructed inside the wallet.
+ */
+
+/**
+ * The only member the transaction builders read from the active wallet account.
+ * Implemented by {@link UnifiedWalletService} (the default) and by the embedded
+ * shell's one-member account context.
+ */
+interface ActiveAccountSource {
+    readonly activeAccount: Signal<UnifiedAccount | null>;
+}
+/**
+ * Injection token for the active-account read surface. Defaults to
+ * {@link UnifiedWalletService} so consumers that already provide it need no
+ * extra wiring; override it to supply a narrower source (the embedded shell
+ * does this to avoid constructing the root service inside the wallet).
+ */
+declare const ACTIVE_ACCOUNT_SOURCE: InjectionToken<ActiveAccountSource>;
+
 /**
  * HSuite Native Connect
  * Copyright 2024-2025 HSuite (https://hsuite.finance)
@@ -6891,6 +7200,129 @@ declare class ChannelClientService {
     static ɵprov: i0.ɵɵInjectableDeclaration<ChannelClientService>;
 }
 
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @module LedgerUiRegistry
+ *
+ * Single source of truth for **how a ledger is presented** in the Angular SDK —
+ * its display name, native currency, brand colours, and brand icon.
+ *
+ * ## Why a registry
+ *
+ * The core SDK keys everything off the canonical, open {@link LedgerId} type
+ * (`z.string().min(1)` in `@hsuite/native-connect-types`) and discovers chains
+ * dynamically via `WalletCore.registerLedger(adapter)` / `LedgerRegistry`. This
+ * registry mirrors that pattern for the **presentation layer**: ledgers are
+ * registered, not hard-coded into closed `'hedera' | 'xrpl'` maps. Adding a new
+ * chain is a single {@link LedgerUIRegistry.register} call — no union to widen,
+ * no scattered `Record<>` literals to keep in sync.
+ *
+ * Presentation lives in the presentation package (this Angular SDK) so the core
+ * SDK stays headless: the descriptor carries the framework-agnostic data plus
+ * the Ionic-specific icon binding ({@link LedgerUiDescriptor.iconName} /
+ * {@link LedgerUiDescriptor.iconSvg}) that `<ion-icon>` renders.
+ *
+ * @see {@link LedgerUiDescriptor} for the per-ledger contract.
+ * @see `docs/guides/adding-a-new-chain.md` for the end-to-end "add a chain" flow.
+ */
+/**
+ * Presentation contract for one ledger.
+ *
+ * Keyed by the canonical {@link LedgerId} (open `string`) so the registry is
+ * extensible to any number of chains. Built-in ledgers are registered at module
+ * load; first-party chains add a descriptor here, third-party/plugin chains call
+ * {@link LedgerUIRegistry.register} at runtime.
+ */
+interface LedgerUiDescriptor {
+    /** Canonical ledger identity, e.g. `'hedera'`, `'xrpl'` (see {@link LedgerId}). */
+    readonly id: LedgerId;
+    /** Full human-readable name, e.g. `'Hedera'`, `'XRP Ledger'`. */
+    readonly displayName: string;
+    /** Compact name for badges/dense surfaces, e.g. `'Hedera'`, `'XRPL'`. */
+    readonly shortName: string;
+    /** Native currency ticker, e.g. `'HBAR'`, `'XRP'`. */
+    readonly currencySymbol: string;
+    /** Native currency decimal places, e.g. `8` (Hedera), `6` (XRPL). */
+    readonly currencyDecimals: number;
+    /** Brand colour as a hex string, used for CSS accents, e.g. `'#8259ef'`. */
+    readonly brandColor: string;
+    /** Ionic semantic colour name for `<ion-badge color="...">`, e.g. `'success'`. */
+    readonly badgeColor: string;
+    /**
+     * Ionicons name under which {@link iconSvg} is registered, e.g.
+     * `'ledger-hedera'`. Reference it from `<ion-icon [name]="...">`. The SVG is
+     * flushed to Ionicons by {@link LedgerUIRegistry.registerIcons}.
+     */
+    readonly iconName: string;
+    /**
+     * Self-contained brand SVG markup. Inlined (rather than shipped as an asset
+     * file) so the packaged library needs no runtime asset pipeline or external
+     * CDN. `currentColor` fills inherit the host `<ion-icon>` colour; explicit
+     * fills are preserved.
+     */
+    readonly iconSvg: string;
+    /**
+     * Optional CDN URL for a raster icon of the native token, used as a fallback
+     * when an inline brand SVG is not the right surface (e.g. token lists).
+     */
+    readonly tokenIconUrl?: string;
+}
+/**
+ * Open, string-keyed registry of {@link LedgerUiDescriptor}s.
+ *
+ * A static registry (like `AccountLabelManager`) because ledger presentation is
+ * process-global — Ionicons' own icon table is global too. Mirrors the core
+ * `LedgerRegistry` shape (`register` / `get` / `has` / `list`) so the two read
+ * the same way.
+ */
+declare class LedgerUIRegistry {
+    private static readonly descriptors;
+    /** Whether {@link registerIcons} has already flushed SVGs to Ionicons. */
+    private static iconsFlushed;
+    /**
+     * Register (or replace) the presentation descriptor for a ledger.
+     *
+     * If icons were already flushed to Ionicons (i.e. {@link registerIcons} ran),
+     * the new ledger's SVG is registered immediately so late registrations still
+     * render.
+     *
+     * @param descriptor - The ledger's presentation contract.
+     */
+    static register(descriptor: LedgerUiDescriptor): void;
+    /**
+     * Look up a ledger's presentation descriptor.
+     *
+     * @param ledgerId - Canonical ledger id (case-sensitive; callers normalise).
+     * @returns The descriptor, or `undefined` if the ledger is not registered.
+     */
+    static get(ledgerId: LedgerId): LedgerUiDescriptor | undefined;
+    /**
+     * @param ledgerId - Canonical ledger id.
+     * @returns `true` if a descriptor is registered for `ledgerId`.
+     */
+    static has(ledgerId: LedgerId): boolean;
+    /**
+     * @returns All registered descriptors, in registration order.
+     */
+    static list(): LedgerUiDescriptor[];
+    /**
+     * Flush every registered ledger's brand SVG to Ionicons so the icons resolve
+     * by name from `<ion-icon>`. Idempotent and cheap to call repeatedly — call it
+     * before the icons are first rendered (e.g. from a component constructor or
+     * once at app bootstrap).
+     */
+    static registerIcons(): void;
+}
+
 /**
  * HSuite Native Connect
  * Copyright 2024-2025 HSuite (https://hsuite.finance)
@@ -6902,48 +7334,72 @@ declare class ChannelClientService {
  */
 /**
  * @module LedgerIconsUtil
- * Utilities for getting default icon URLs for ledgers and their native tokens.
  *
- * Uses CoinGecko's public CDN for reliable, high-quality token icons.
- * Shared across wallet and dApp for consistency.
+ * Backward-compatible facade over {@link LedgerUIRegistry}.
+ *
+ * Every value here is **derived from the registry** so there is exactly one
+ * source of truth for ledger presentation. New code should prefer
+ * {@link LedgerUIRegistry} directly (it is open/extensible and richer); these
+ * getters and constant maps remain for the existing public API surface.
+ *
+ * The constant maps below are snapshots taken at module load — they include the
+ * built-in ledgers (Hedera, XRPL). Ledgers registered later at runtime are
+ * always reachable through the getters and {@link LedgerUIRegistry}, but will
+ * not retroactively appear in these legacy snapshots; prefer the registry when
+ * extensibility matters.
  */
 /**
- * Default icon URLs for native ledger tokens
+ * Default raster icon URLs for native ledger tokens, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.tokenIconUrl}.
  */
 declare const DEFAULT_LEDGER_ICONS: Record<string, string>;
 /**
- * Brand colors for each ledger
+ * Brand colours (hex) for each ledger, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.brandColor}.
  */
 declare const LEDGER_COLORS: Record<string, string>;
 /**
- * Display names for each ledger
+ * Display names for each ledger, keyed by ledger id.
+ * Derived from {@link LedgerUiDescriptor.displayName}.
  */
 declare const LEDGER_NAMES: Record<string, string>;
 /**
- * Get the default icon URL for a ledger
- * @param ledgerId - Ledger identifier (e.g., 'hedera', 'xrpl')
- * @returns Icon URL or empty string if not found
+ * Ionicons names under which each ledger's brand SVG is registered, keyed by
+ * ledger id. Reference these from `<ion-icon [name]="...">`.
+ * Derived from {@link LedgerUiDescriptor.iconName}.
+ */
+declare const LEDGER_ICON_NAMES: Record<string, string>;
+/**
+ * Register the ledger brand SVGs with Ionicons so they can be referenced by name
+ * (see {@link LEDGER_ICON_NAMES}). Idempotent; safe to call from multiple
+ * consumers. Delegates to {@link LedgerUIRegistry.registerIcons}.
+ */
+declare function registerLedgerIcons(): void;
+/**
+ * Get the default raster token icon URL for a ledger.
+ * @param ledgerId - Ledger identifier (e.g. `'hedera'`, `'xrpl'`)
+ * @returns Icon URL, or empty string if the ledger has none.
  */
 declare function getLedgerIcon(ledgerId: string): string;
 /**
- * Get the brand color for a ledger
+ * Get the brand colour (hex) for a ledger.
  * @param ledgerId - Ledger identifier
- * @returns Hex color string or primary color fallback
+ * @returns Hex colour string, or the Ionic primary CSS variable as fallback.
  */
 declare function getLedgerColor(ledgerId: string): string;
 /**
- * Get the display name for a ledger
+ * Get the display name for a ledger.
  * @param ledgerId - Ledger identifier
- * @returns Human-readable ledger name
+ * @returns Human-readable ledger name, or the raw id if unknown.
  */
 declare function getLedgerName(ledgerId: string): string;
 /**
- * Get token icon URL, falling back to ledger default if not provided
+ * Get a token icon URL, falling back to the ledger default if not provided.
  * @param tokenIconUrl - Specific token icon URL (optional)
  * @param ledgerId - Ledger identifier for fallback
- * @returns Icon URL or empty string
+ * @returns Icon URL, or empty string.
  */
 declare function getTokenIcon(tokenIconUrl: string | undefined, ledgerId: string): string;
 
-export { AccountActionsComponent, AccountFilterComponent, AccountFormattingService, AccountGroupingService, AccountListComponent, AccountSelectorComponent, AccountSelectorService, BaseWalletProvider, ChannelClientService, ChromeExtensionTransport, DEFAULT_LEDGER_ICONS, DEFAULT_WALLET_URL, HederaSigner, HederaTransactionBuilderService, HsuiteNativeProvider, HsuiteWalletModule, LEDGER_COLORS, LEDGER_NAMES, LoggerService, P2PNativeProvider, P2PSessionManager, SignerFactory, TransactionService, UnifiedWalletService, WalletAccountDisplayComponent, WalletConnectButtonComponent, WalletConnectClientManager, WalletConnectPromptComponent, WalletConnectSessionStore, WalletConnectSigningOrchestrator, WalletConnectV2Provider, WalletConnectedDirective, WalletConnectedGuardComponent, WalletConnectionModalComponent, WalletContextDirective, WalletContextService, WalletErrorHandler, WalletEventBus, WalletEventsDirective, WalletSessionDisplayComponent, WalletTransactionStatusComponent, XrplSigner, XrplTransactionBuilderService, getExtensionVersion, getLedgerColor, getLedgerIcon, getLedgerName, getTokenIcon, isExtensionInstalled, isHsuiteNativeConfig, isWalletConnectV2Config, provideWalletErrorHandler, scaleHederaAmountToBaseUnits };
-export type { AccountChangeEvent, AccountCreateOptions, AccountGroupingMode, AccountItem, AccountSelectorConfig, AccountSelectorPresentationMode, AccountWithBalance, AccountsUpdateEvent, ActiveAccountData, BatchInnerTransaction, BatchInnerTransactionType, ChannelConnectConfig, ChromeExtensionTransportOptions, CompactHeaderFormat, CompactHeaderSize, ConnectionConfig, ConnectionEvent, ConnectionStatus, CreateOfferOptions, CreateOfferResult, DisconnectionEvent, HederaKeyConfig, HsuiteNativeConfig, IWalletConnectSigner, LedgerGroup$1 as LedgerGroup, MobileNativeConfig, NetworkGroup, P2PConnectionState, P2PNativeConnectionState, P2PSession, PairingOfferResult, ProtocolGroup, ProviderErrorEvent, ProviderMetadata, ProviderStatusEvent, ProviderType, SelectedAccountData, SessionEvent, SessionMetadata, SignMessageOptions, SignMessageResult, SignResult, SignTransactionOptions, SignerContext, SignerOperationParams, SigningOrchestratorConfig, StoredSessionData, SubmitResult, SubmitTransactionOptions, TokenCreateOptions, TopicCreateOptions, UnifiedAccount, WCAppMetadata, WalletConnectSession, WalletConnectSignerConfig, WalletConnectV2Config, WalletContext, WalletErrorHandlerConfig, WalletSession };
+export { ACTIVE_ACCOUNT_SOURCE, AccountActionsComponent, AccountFilterComponent, AccountFormattingService, AccountGroupingService, AccountListComponent, AccountSelectorComponent, AccountSelectorService, BaseWalletProvider, ChannelClientService, ChromeExtensionTransport, DEFAULT_LEDGER_ICONS, DEFAULT_WALLET_URL, HSUITE_AUTH_HEADER, HSUITE_LEDGER_HEADER, HederaSigner, HederaTransactionBuilderService, HsuiteAuthInterceptor, HsuiteNativeProvider, HsuiteWalletModule, LEDGER_COLORS, LEDGER_ICON_NAMES, LEDGER_NAMES, LedgerUIRegistry, LoggerService, P2PNativeProvider, P2PSessionManager, SMART_SESSION_CONFIG, SignerFactory, SmartSessionService, TransactionService, UnifiedWalletService, WalletAccountDisplayComponent, WalletConnectButtonComponent, WalletConnectClientManager, WalletConnectPromptComponent, WalletConnectSessionStore, WalletConnectSigningOrchestrator, WalletConnectV2Provider, WalletConnectedDirective, WalletConnectedGuardComponent, WalletConnectionModalComponent, WalletContextDirective, WalletContextService, WalletErrorHandler, WalletEventBus, WalletEventsDirective, WalletSessionDisplayComponent, WalletTransactionStatusComponent, XrplSigner, XrplTransactionBuilderService, getExtensionVersion, getLedgerColor, getLedgerIcon, getLedgerName, getTokenIcon, hsuiteAuthInterceptor, isExtensionInstalled, isHsuiteNativeConfig, isWalletConnectV2Config, provideWalletErrorHandler, registerLedgerIcons, scaleHederaAmountToBaseUnits };
+export type { AccountChangeEvent, AccountCreateOptions, AccountGroupingMode, AccountItem, AccountSelectorConfig, AccountSelectorPresentationMode, AccountWithBalance, AccountsUpdateEvent, ActiveAccountData, ActiveAccountSource, BatchInnerTransaction, BatchInnerTransactionType, ChannelConnectConfig, ChromeExtensionTransportOptions, CompactHeaderFormat, CompactHeaderSize, ConnectionConfig, ConnectionEvent, ConnectionStatus, CreateOfferOptions, CreateOfferResult, DisconnectionEvent, HederaKeyConfig, HsuiteNativeConfig, IWalletConnectSigner, LedgerGroup$1 as LedgerGroup, LedgerUiDescriptor, MobileNativeConfig, NetworkGroup, P2PConnectionState, P2PNativeConnectionState, P2PSession, PairingOfferResult, ProtocolGroup, ProviderErrorEvent, ProviderMetadata, ProviderStatusEvent, ProviderType, SelectedAccountData, SessionEvent, SessionMetadata, SignMessageOptions, SignMessageResult, SignResult, SignTransactionOptions, SignerContext, SignerOperationParams, SigningOrchestratorConfig, SmartHostChallenge, SmartHostHealth, SmartHostVerifyRequest, SmartHostVerifyResponse, SmartSessionConfig, StoredSessionData, SubmitResult, SubmitTransactionOptions, TokenCreateOptions, TopicCreateOptions, UnifiedAccount, WCAppMetadata, WalletConnectSession, WalletConnectSignerConfig, WalletConnectV2Config, WalletContext, WalletErrorHandlerConfig, WalletSession };