Action lifecycle

This section explains how SDK actions are structured, executed, and managed throughout their lifecycle.

---

Overview

Actions are the core building blocks of the SDK. Each action represents a multi-step blockchain operation with:

• Predictable state machine

• Event-driven progress updates

• Built-in error handling

• Retry support without state reset

---

Action Pattern

All actions follow the same pattern:

1. Create — Initialize with configuration

2. Prepare — Validate parameters and check requirements

3. Authorize — Sign any required messages or transactions

4. Execute — Perform the main operation

import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
import { config } from './lib/lombard';

const sdk = createLombardSDK(config);

// 1. Create
const stake = sdk.chain.btc.stake({
  destChain: Chain.ETHEREUM,
  assetOut: AssetId.LBTC,
});

// 2. Prepare
await stake.prepare({
  amount: '0.1',
  recipient: '0x1234567890abcdef1234567890abcdef12345678',
});

// 3. Authorize
await stake.authorize();

// 4. Execute
const result = await stake.generateDepositAddress();
// result: 'bc1q...'

---

Status States

Actions have a status property that indicates their current state.

BTC Action Status

const BtcActionStatus = {
  IDLE: 'idle',
  NEEDS_FEE_AUTHORIZATION: 'needs_fee_authorization',
  NEEDS_ADDRESS_CONFIRMATION: 'needs_address_confirmation',
  NEEDS_DEPLOY_AUTHORIZATION: 'needs_deploy_authorization',
  READY: 'ready',
  ADDRESS_READY: 'address_ready',
  AWAITING_DEPOSIT: 'awaiting_deposit',
};

EVM Operation Status

const EvmOperationStatus = {
  IDLE: 'idle',
  NEEDS_APPROVAL: 'needs-approval',
  READY: 'ready',
  CONFIRMING: 'confirming',
  COMPLETED: 'completed',
};

---

Orthogonal Properties

Actions have three independent properties:

Property	Type	Description
status	string	Current step in the flow
isLoading	boolean	Whether an async operation is in progress
error	Error	null

These are independent. An action can be in any status with or without an error.

---

Error Recovery

When an error occurs, the status stays at the step where it happened. This enables retry without resetting state.

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

await stake.prepare({ amount: '0.1', recipient: '0x...' });
// status: 'needs_fee_authorization'

try {
  await stake.authorize();
} catch (error) {
  // status is still 'needs_fee_authorization'
  // User can retry
  await stake.authorize();
}

---

Checking Status

import { BtcActionStatus, Chain, AssetId } from '@lombard.finance/sdk';

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

if (stake.status === BtcActionStatus.IDLE) {
  // Ready for prepare()
}

if (
	stake.status === BtcActionStatus.NEEDS_FEE_AUTHORIZATION
	|| stake.status === BtcActionStatus.NEEDS_ADDRESS_CONFIRMATION
  || stake.status === BtcActionStatus.NEEDS_DEPLOY_AUTHORIZATION
) {
  // Ready for authorize()
}

if (stake.status === BtcActionStatus.READY) {
  // Ready for generateDepositAddress()
}

---