Sui Signer SDK for Ledger

A TypeScript SDK for interacting with Sui blockchain through Ledger hardware wallets using the Device Management Kit (DMK).

Features

• 🔐 Secure Signing: Uses Ledger hardware wallet for secure key management
• 🚀 DMK Integration: Built on top of Ledger's Device Management Kit
• 📱 Sui App Support: Native support for Sui blockchain app on Ledger
• 🔑 Address Generation: Generate Sui addresses with derivation path support
• 🎯 TypeScript: Full TypeScript support with proper type definitions

Installation

npm install sui-test-le

Dependencies

{
  "@ledgerhq/device-management-kit": "^0.8.0",
  "@ledgerhq/device-transport-kit-web-hid": "^1.2.0",
  "@ledgerhq/signer-utils": "^1.0.6",
  "rxjs": "^7.8.2"
}

Quick Start

1. Basic Usage

import { SuiSigner } from "sui-test-le";
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import {
  webHidTransportFactory,
  webHidIdentifier,
} from "@ledgerhq/device-transport-kit-web-hid";
import { firstValueFrom } from "rxjs";

async function connectToLedger() {
  // Initialize DMK
  const dmk = new DeviceManagementKitBuilder()
    .addTransport(webHidTransportFactory)
    .build();

  // Discover and connect to device
  const device = await firstValueFrom(
    dmk.startDiscovering({ transport: webHidIdentifier })
  );
  const sessionId = await dmk.connect({ device });

  // Create Sui signer
  const suiSigner = new SuiSigner(dmk, sessionId);

  return suiSigner;
}

2. Generate Sui Address

async function getSuiAddress() {
  const suiSigner = await connectToLedger();

  try {
    // Open Sui app on Ledger
    await suiSigner.openSuiApp();

    // Get address (will display on device for verification)
    const address = await suiSigner.getAddress("m/44'/784'/0'/0'/0'", true);

    console.log("Public Key:", address.publicKey);
    console.log("Address:", address.address);

    // Close app when done
    await suiSigner.closeSuiApp();

    return address;
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

3. React Component Example

import { useState } from "react";
import { firstValueFrom } from "rxjs";
import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit";
import {
  webHidTransportFactory,
  webHidIdentifier,
} from "@ledgerhq/device-transport-kit-web-hid";
import { SuiSigner } from "sui-test-le";

const SuiTest = () => {
  const [sdk] = useState(() =>
    new DeviceManagementKitBuilder()
      .addTransport(webHidTransportFactory)
      .build()
  );

  const [suiSigner, setSuiSigner] = useState<SuiSigner | null>(null);
  const [status, setStatus] = useState("Not connected");
  const [address, setAddress] = useState(null);

  const connectDevice = async () => {
    try {
      setStatus("Connecting...");
      const device = await firstValueFrom(
        sdk.startDiscovering({ transport: webHidIdentifier })
      );
      const sessionId = await sdk.connect({ device });

      const signer = new SuiSigner(sdk, sessionId);
      setSuiSigner(signer);
      setStatus("✅ Connected");
    } catch (error) {
      setStatus(`❌ Connection failed: ${error.message}`);
    }
  };

  const getAddress = async () => {
    if (!suiSigner) return;

    try {
      setStatus("Opening Sui app...");
      await suiSigner.openSuiApp();

      setStatus("Getting address...");
      const result = await suiSigner.getAddress("m/44'/784'/0'/0'/0'", true);
      setAddress(result);
      setStatus("✅ Address generated!");
    } catch (error) {
      setStatus(`❌ Failed: ${error.message}`);
    }
  };

  return (
    <div>
      <h2>Sui Ledger Integration</h2>
      <p>Status: {status}</p>

      {!suiSigner && <button onClick={connectDevice}>Connect Ledger</button>}

      {suiSigner && <button onClick={getAddress}>Get Sui Address</button>}

      {address && (
        <div>
          <h3>Address Generated:</h3>
          <p>
            <strong>Public Key:</strong> {address.publicKey}
          </p>
          <p>
            <strong>Address:</strong> {address.address}
          </p>
        </div>
      )}
    </div>
  );
};

export default SuiTest;

API Reference

SuiSigner Class

Constructor

constructor(dmk: DeviceManagementKit, sessionId: DeviceSessionId)

Methods

openSuiApp(): Promise<void>

Opens the Sui app on the connected Ledger device.

getAddress(derivationPath: string, display: boolean): Promise<GetAddressCommandResponse>

Generates a Sui address for the given derivation path.

• derivationPath: BIP32 derivation path (default: "m/44'/784'/0'/0'/0'")
• display: Whether to display the address on device for verification

Returns:

{
  publicKey: string; // Hex string with 0x prefix
  address: string; // Hex string with 0x prefix
}

getAddressDirect(derivationPath: string, display: boolean): Promise<SuiAddress>

Alternative method that directly sends APDU commands (useful for debugging).

closeSuiApp(): Promise<void>

Closes the Sui app on the connected Ledger device.

Types

export interface SuiAddress {
  publicKey: string;
  address: string;
}

export interface GetAddressCommandResponse {
  publicKey: string;
  address: string;
}

export interface GetAddressCommandArgs {
  derivationPath: string;
  checkOnDevice?: boolean;
}

Derivation Paths

The SDK supports standard BIP32 derivation paths. For Sui, the recommended path is:

m/44'/784'/0'/0'/0'

Where:

• 44' = BIP44 standard
• 784' = Sui coin type (hardened)
• 0' = Account index (hardened)
• 0' = Change (hardened)
• 0' = Address index (hardened)

Error Handling

The SDK provides comprehensive error handling with specific error codes:

export type SuiErrorCodes =
  | "6000" // Generic error
  | "6700" // Incorrect length
  | "6982" // Security condition not satisfied
  | "6985" // User refused
  | "6a80" // Incorrect data
  | "6a81" // Function not supported
  | "6a82" // File not found
  | "6d00" // Instruction not supported
  | "6e00"; // Class not supported

Troubleshooting

Common Issues

1. Device not found: Ensure your Ledger device is connected and unlocked
2. Sui app not installed: Install the Sui app from Ledger Live
3. Permission denied: Grant WebHID permissions in your browser
4. APDU errors: Check that the Sui app is open and ready

Debug Mode

Use the getAddressDirect method for debugging APDU communication:

try {
  const address = await suiSigner.getAddressDirect("m/44'/784'/0'/0'/0'", true);
  console.log("Direct result:", address);
} catch (error) {
  console.error("Direct method error:", error);
}

Development

Building

npm run build

Testing

npm test

Development Mode

npm run dev

License

ISC

Contributing

This is a reference implementation for integrating Sui with Ledger devices using the Device Management Kit. Feel free to fork and modify for your specific needs.