Skip to main content

Wallets – TypeScript SDK Reference

Overview​

The wallet module in the TypeScript SDK is responsible for:

  • Representing a ULedger wallet (Wallet / UL_Wallet)
  • Generating wallets from mnemonics, keys, or JSON
  • Exporting wallet data (WalletData) and reconstructing wallets from stored data
  • Managing BIP-39 entropy, mnemonics, and mnemonic-to-seed conversion
  • Signing and verifying messages

A wallet combines:

  • An address (derived from the public key)
  • Permission groups (AuthGroups)
  • A cryptographic keypair (used to sign transactions and messages)

The TypeScript SDK is built on top of the Go SDK compiled to WebAssembly (WASM). Cryptographic primitives are executed through a WASM backend.

Imports​

import { initULedgerSDK, KeyType } from "@uledgerinc/typescript-sdk";

const sdk = await initULedgerSDK();
const wallet = sdk.generateWallet({ keyType: KeyType.Secp256k1 });

Direct wallet imports (low-level)​

import {
  Wallet,
  WASMBackend,
  generateMnemonic,
  validateMnemonic,
  parseAddress,
  mnemonicToSeed,
} from "@uledgerinc/typescript-sdk";

SDK entrypoints​

initULedgerSDK​

export declare function initULedgerSDK(
  config?: ULedgerSDKConfig
): Promise<ULedgerSDK>;

Initializes the SDK with the WASM backend (main Node.js entrypoint).

initULedgerSDKWithBackend​

export declare function initULedgerSDKWithBackend(
  backend: WASMBackend,
  config?: ULedgerSDKConfig
): ULedgerSDK;

Initializes the SDK with a custom backend instance.

getULedgerSDK​

export declare function getULedgerSDK(): Promise<ULedgerSDK>;

Convenience function that returns an initialized ULedgerSDK.

ULedgerSDK wallet API​

Class: ULedgerSDK​

export declare class ULedgerSDK {
  constructor(backend: WASMBackend, config?: ULedgerSDKConfig);

  getInfo(): SDKInfo;

  generateWallet(options?: GenerateWalletOptions): Wallet;
  walletFromMnemonic(mnemonic: string, options?: RestoreWalletOptions): Wallet;
  walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
  walletFromJson(jsonString: string, password?: string): Wallet;
  walletFromData(data: WalletData, password?: string): Wallet;

  generateMnemonic(entropyBits?: number): string;
  validateMnemonic(mnemonic: string): boolean;
  mnemonicToSeed(mnemonic: string, passphrase?: string): string;

  parseAddress(publicKeyHex: string): string;

  signMessage(
    publicKeyHex: string,
    privateKeyHex: string,
    message: string,
    keyType?: KeyType
  ): SignatureResult;

  verifySignature(
    publicKeyHex: string,
    message: string,
    signatureHex: string,
    keyType?: KeyType
  ): VerificationResult;
}

These methods provide the most common wallet workflows without directly importing Wallet factory methods.

Core types​

UL_AuthPermission​

export interface UL_AuthPermission {
  create: boolean;
  read: boolean;
  update: boolean;
  delete: boolean;
}

Defines CRUD permissions for a given group name.

AuthGroups​

export type AuthGroups = Record<string, UL_AuthPermission>;

A map of group name → permissions.

WalletData (persistence shape)​

export interface WalletData {
  address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;
  mnemonic?: string;
  keyType: KeyType;
  publicKeyHex: string;
  privateKeyHex?: string;
}

This is the JSON-friendly structure used for exporting/importing wallets and as the wallet input for WASM transaction signing.

UL_Wallet​

export interface UL_Wallet {
  address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;
}

Public wallet fields.

FullWallet​

export interface FullWallet extends UL_Wallet {
  mnemonic?: string;
  keyType: KeyType;
  publicKeyHex: string;
  privateKeyHex: string;
}

Full wallet structure including key material (internal/crypto contexts).

Auth group name constant & helpers​

WALLET_GROUP_NAME​

export declare const WALLET_GROUP_NAME = "wallet";

createFullPermissions / createReadOnlyPermissions​

export declare function createFullPermissions(): UL_AuthPermission;
export declare function createReadOnlyPermissions(): UL_AuthPermission;

WASM backend interface (advanced)​

The wallet and transaction modules rely on a WASM backend implementing:

export interface WASMBackend {
  generateWallet(options: { keyType?: string; password?: string; parent?: string; entropy?: number; }): FullWallet;
  walletFromMnemonic(mnemonic: string, options: { password?: string; keyType?: string; }): FullWallet;
  walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: string): FullWallet;
  walletFromJson(jsonString: string, password?: string): FullWallet;

  signMessage(publicKeyHex: string, privateKeyHex: string, message: string, keyType?: string): SignatureResult;
  signWithWallet(wallet: FullWallet, message: string): SignatureResult;
  verifySignature(publicKeyHex: string, message: string, signatureHex: string, keyType?: string): VerificationResult;

  parseAddress(publicKeyHex: string): { address: string };

  generateMnemonic(entropyBits?: number): { mnemonic: string };
  validateMnemonic(mnemonic: string): { valid: boolean };
  mnemonicToSeed(mnemonic: string, passphrase?: string): { seedHex: string };

  signTransactionInput(
    transactionInput: TransactionInputForSigning,
    wallet: WalletData,
    password?: string
  ): SignedTransactionInput;
}

Most users interact with the backend through ULedgerSDK and the Wallet class.

Wallet class​

Class: Wallet​

export declare class Wallet implements UL_Wallet {
  readonly address: string;
  enabled: boolean;
  parent: string;
  authGroups: AuthGroups;

  static generate(backend: WASMBackend, options?: GenerateWalletOptions): Wallet;
  static fromMnemonic(backend: WASMBackend, mnemonic: string, options?: RestoreWalletOptions): Wallet;
  static fromHex(backend: WASMBackend, publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
  static fromJson(backend: WASMBackend, jsonString: string, password?: string): Wallet;
  static fromWalletData(backend: WASMBackend, data: WalletData, password?: string): Wallet;

  get keyType(): KeyType;
  get publicKeyHex(): string;
  get privateKeyHex(): string;
  get mnemonic(): string | undefined;

  get canSign(): boolean;

  sign(message: string): SignatureResult;
  verify(message: string, signatureHex: string): boolean;

  toWalletData(includePrivateKey?: boolean): WalletData;
  toJson(includePrivateKey?: boolean): string;

  toFullWallet(): FullWallet;
}

Creating wallets​

sdk.generateWallet / Wallet.generate​

generateWallet(options?: GenerateWalletOptions): Wallet;
static generate(backend: WASMBackend, options?: GenerateWalletOptions): Wallet;

Generates a new wallet with a random mnemonic.

GenerateWalletOptions:

export interface GenerateWalletOptions {
  keyType?: KeyType;
  password?: string;
  parent?: string;
  entropy?: number; // 128, 160, 192, 224, 256 (default: 256)
  authGroups?: AuthGroups;
}

sdk.walletFromMnemonic / Wallet.fromMnemonic​

walletFromMnemonic(mnemonic: string, options?: RestoreWalletOptions): Wallet;
static fromMnemonic(backend: WASMBackend, mnemonic: string, options?: RestoreWalletOptions): Wallet;

Restores a wallet from a mnemonic phrase.

RestoreWalletOptions:

export interface RestoreWalletOptions {
  password?: string;
  keyType?: KeyType;
}

sdk.walletFromHex / Wallet.fromHex​

walletFromHex(publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;
static fromHex(backend: WASMBackend, publicKeyHex: string, privateKeyHex: string, keyType?: KeyType): Wallet;

Creates a wallet directly from key material.

sdk.walletFromJson / Wallet.fromJson​

walletFromJson(jsonString: string, password?: string): Wallet;
static fromJson(backend: WASMBackend, jsonString: string, password?: string): Wallet;

Parses a wallet from a JSON string (typically matching the WalletData structure). This is the TS analogue of Go’s wallet.FromJson.

sdk.walletFromData / Wallet.fromWalletData​

walletFromData(data: WalletData, password?: string): Wallet;
static fromWalletData(backend: WASMBackend, data: WalletData, password?: string): Wallet;

Creates a wallet from an already-parsed WalletData object.

Exporting and serialization​

wallet.toWalletData(includePrivateKey?)​

toWalletData(includePrivateKey?: boolean): WalletData;
  • includePrivateKey = false → omits privateKeyHex
  • includePrivateKey = true → includes privateKeyHex

wallet.toJson(includePrivateKey?)​

toJson(includePrivateKey?: boolean): string;

Exports the wallet as a JSON string.

Mnemonic and address utilities​

sdk.generateMnemonic​

generateMnemonic(entropyBits?: number): string;

Generates a BIP-39 mnemonic.

sdk.validateMnemonic​

validateMnemonic(mnemonic: string): boolean;

Validates a BIP-39 mnemonic.

sdk.mnemonicToSeed​

mnemonicToSeed(mnemonic: string, passphrase?: string): string;

Converts mnemonic + optional passphrase into a seed (hex).

sdk.parseAddress​

parseAddress(publicKeyHex: string): string;

Computes address from public key.

Message signing and verification​

sdk.signMessage​

signMessage(
  publicKeyHex: string,
  privateKeyHex: string,
  message: string,
  keyType?: KeyType
): SignatureResult;

Signs a message using raw key hex.

sdk.verifySignature​

verifySignature(
  publicKeyHex: string,
  message: string,
  signatureHex: string,
  keyType?: KeyType
): VerificationResult;

Verifies a signature using a public key.

This page is intended as a reference. For step-by-step guides see our tutorial section.