@lombard.finance/sdk-devtools

@lombard.finance/sdk-devtools

Developer tools for the Lombard SDK. Provides debugging, inspection, and testing utilities for developers integrating with the Lombard protocol.

How It Works

The SDK DevTools automatically hooks into SDK actions to collect events and state:

┌─────────────────────────────────────────────────────────────────────────────┐
│                                YOUR APP                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌─────────────────────┐        ┌─────────────────────┐                    │
│   │    Lombard SDK      │        │     DevTools        │                    │
│   │                     │        │                     │                    │
│   │  const stake = sdk  │───────▶│  Automatically      │                    │
│   │    .btc.stake(...)  │ events │  collects events,   │                    │
│   │                     │        │  tracks status      │                    │
│   └─────────────────────┘        └──────────┬──────────┘                    │
│                                              │                               │
│                                              ▼                               │
│                               ┌─────────────────────────┐                   │
│                               │    DevToolsPanel        │                   │
│                               │    (Visual debugger)    │                   │
│                               └─────────────────────────┘                   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Installation

yarn add @lombard.finance/sdk-devtools
# or
npm install @lombard.finance/sdk-devtools

Quick Start

1. Wrap Your App with DevToolsProvider

import { DevToolsProvider } from '@lombard.finance/sdk-devtools';

function App() {
  return (
    <DevToolsProvider enabled={process.env.NODE_ENV !== 'production'}>
      <MyApp />
    </DevToolsProvider>
  );
}

2. Register SDK Actions

import { useDevToolsContext } from '@lombard.finance/sdk-devtools';
import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';

function StakeComponent() {
  const { registerAction } = useDevToolsContext();
  const [stake, setStake] = useState(null);

  // Create and register the action
  useEffect(() => {
    async function init() {
      const sdk = await createLombardSDK({
        env: 'testnet',
        providers: { evm: () => window.ethereum },
      });

      const action = sdk.btc.stake({
        destChain: Chain.ETHEREUM,
        assetOut: AssetId.LBTC,
      });

      // Register with DevTools - events are now collected automatically!
      const unregister = registerAction('btc-stake', action, {
        category: 'btc',
      });

      setStake(action);

      return unregister;
    }

    init();
  }, [registerAction]);

  // Use the action normally
  async function handleStake() {
    await stake.prepare({ amount: '0.001', recipient: '0x...' });
    await stake.authorize();
    const address = await stake.generateDepositAddress();
    console.log('Deposit to:', address);
  }

  return <button onClick={handleStake}>Stake BTC</button>;
}

3. Display DevTools Panel

import { DevToolsPanel, useDevToolsContext } from '@lombard.finance/sdk-devtools';

function DebugPanel() {
  const { events, clearEvents, actions } = useDevToolsContext();

  // Get state summary for all registered actions
  const stateSummary = useMemo(() => {
    const summary = {};
    actions.forEach((reg, name) => {
      summary[name] = {
        status: reg.action.status,
        isLoading: reg.action.isLoading,
      };
    });
    return summary;
  }, [actions]);

  return (
    <DevToolsPanel
      events={events}
      onClearEvents={clearEvents}
      state={stateSummary}
    />
  );
}

Alternative: Without Provider

For simpler setups or non-React apps, use the bridge directly:

import { DevToolsBridge, DevToolsPanel } from '@lombard.finance/sdk-devtools';

// Create bridge
const bridge = new DevToolsBridge({ consoleLogging: true });

// Register action
const stake = sdk.btc.stake({ ... });
const unregister = bridge.registerAction('stake', stake);

// Get events for display
const events = bridge.getEvents();

// In React:
function DebugView() {
  const [events, setEvents] = useState([]);

  useEffect(() => {
    return bridge.onEvent(() => {
      setEvents(bridge.getEvents());
    });
  }, []);

  return (
    <DevToolsPanel
      events={events}
      onClearEvents={() => bridge.clearEvents()}
    />
  );
}

Using Hook for Single Action

For monitoring a single action with full state:

import { useActionEvents } from '@lombard.finance/sdk-devtools';

function StakeProgress({ action }) {
  const { events, status, isLoading, error, isFailed } = useActionEvents(action);

  return (
    <div>
      <StatusBadge status={status} />
      {isLoading && <Spinner />}
      {isFailed && <Error message={error.message} />}
      <EventLog events={events} onClear={() => {}} />
    </div>
  );
}

Components

DevToolsPanel

Full debug panel with tabs for events, actions, and state:

<DevToolsPanel
  events={events}
  onClearEvents={clearEvents}
  reducerLogs={logs}             // Optional: Redux-style action log
  onClearReducerLogs={clearLogs} // Optional
  state={{ status: 'ready' }}    // Optional: State to inspect
  initialTab="events"            // Optional: 'events' | 'reducer' | 'state'
  title="SDK Debug"              // Optional
/>

Individual Components

import {
  EventLog,
  StateInspector,
  StatusBadge,
  StepIndicator,
  createSteps,
} from '@lombard.finance/sdk-devtools';

// Status Badge
<StatusBadge status="needs_fee_authorization" />

// Step Indicator
const steps = [
  { id: 'create', label: 'Create' },
  { id: 'prepare', label: 'Prepare' },
  { id: 'authorize', label: 'Authorize' },
  { id: 'execute', label: 'Execute' },
];

<StepIndicator
  steps={createSteps(steps, currentStep)}
  currentStep={currentStep}
/>

// Event Log (standalone)
<EventLog events={events} onClear={clearEvents} />

// State Inspector (JSON tree viewer)
<StateInspector state={{ amount: '0.001' }} title="Transaction" />

Mock Wallet

Test flows without connecting a real wallet:

import { useMockWallet, MOCK_ADDRESSES } from '@lombard.finance/sdk-devtools';

function WalletSection() {
  const mockWallet = useMockWallet();

  return (
    <div>
      {!mockWallet.isEnabled ? (
        <button onClick={mockWallet.enable}>Use Mock Wallet</button>
      ) : (
        <div>
          <p>Mock Address: {mockWallet.address}</p>
          <p>⚠️ Cannot sign transactions</p>
          <button onClick={mockWallet.disable}>Disable Mock</button>
        </div>
      )}
    </div>
  );
}

// Available mock addresses
console.log(MOCK_ADDRESSES.evm);      // 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
console.log(MOCK_ADDRESSES.bitcoin);  // bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
console.log(MOCK_ADDRESSES.solana);   // DRpbCBMxVnDK7maPMxTm9dRYNLGhPEYALmJY9VvUdWTm

SDK Events Collected

The bridge automatically subscribes to these SDK events:

Event	Description
status-change	Action status changed (e.g., idle → needs_fee_authorization)
loading	Loading state changed
error	An error occurred
completed	Action completed successfully
failed	Action failed
progress	Progress update with step details

API Reference

Provider

Export	Description
DevToolsProvider	React context provider
useDevToolsContext	Hook to access DevTools context
useRegisterAction	Hook to register an action

Bridge

Export	Description
DevToolsBridge	Core bridge class
getDevToolsBridge	Get global singleton bridge
resetDevToolsBridge	Reset global bridge

Hooks

Hook	Description
useDevTools	Full DevTools state and methods
useMonitoredAction	Create and auto-register an action
useActionEvents	Subscribe to events from a single action
useMockWallet	Mock wallet for testing

Components

Component	Description
DevToolsPanel	Full tabbed debug panel
EventLog	SDK event stream
ReducerLog	Redux-style action log
StateInspector	JSON tree viewer
StatusBadge	Status indicator
StepIndicator	Progress steps

Styling

Components use Tailwind CSS classes. For best results, ensure Tailwind is configured in your project. Components support dark mode via dark: prefix classes.

Production

DevTools is automatically disabled in production when using DevToolsProvider:

<DevToolsProvider enabled={process.env.NODE_ENV !== 'production'}>

Or disable manually:

<DevToolsProvider enabled={false}>

License

MIT