@lombard.finance/sdk 3.7.3 → 4.0.0

package/src/chains/solana/actions/unstake/SolanaUnstake.ts

@@ -0,0 +1,151 @@
+/**
+ * Solana Unstake Action
+ *
+ * Burns LBTC on Solana and releases BTC on Bitcoin.
+ *
+ * @module chains/solana/actions/unstake/SolanaUnstake
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+import { z } from 'zod';
+
+import { StepStatus } from '../../../../core';
+import { BaseAction } from '../../../../shared/actions/BaseAction';
+import { NonEvmUnstakeStatus } from '../../../../shared/constants/statusConstants';
+import type { SolanaCoreContext } from '../../../../shared/context';
+import { LombardError } from '../../../../shared/errors';
+import type { UnstakeEventMap } from '../../../../shared/events';
+import {
+  amountSchema,
+  validatePrepareParams,
+} from '../../../../shared/validation';
+import { toSatoshi } from '../../../../utils/satoshi';
+import { isBtcUnstakeSupported,solanaToBtcConfig } from './config';
+import type {
+  ISolanaUnstake,
+  SolanaUnstakeParams,
+  SolanaUnstakePrepareParams,
+} from './types';
+
+/**
+ * Map environment to Solana network
+ */
+function envToSolanaNetwork(env: Env): string {
+  switch (env) {
+    case 'prod':
+      return 'mainnet-beta';
+    case 'testnet':
+      return 'testnet';
+    case 'stage':
+    case 'dev':
+    case 'ibc':
+    default:
+      return 'devnet';
+  }
+}
+
+export class SolanaUnstake
+  extends BaseAction<UnstakeEventMap, NonEvmUnstakeStatus>
+  implements ISolanaUnstake
+{
+  private _amount?: string;
+  private _recipient?: string;
+  private _txHash?: string;
+  private readonly env: Env;
+
+  constructor(
+    private readonly ctx: SolanaCoreContext,
+    private readonly params: SolanaUnstakeParams,
+  ) {
+    super(NonEvmUnstakeStatus.IDLE);
+    this.env = ctx.env;
+
+    // Validate route is supported
+    if (!isBtcUnstakeSupported(params.sourceChain, this.env)) {
+      throw LombardError.routeNotFound({
+        assetOut: params.assetOut,
+        sourceChain: params.sourceChain,
+        destChain: params.destChain,
+        env: this.env,
+      });
+    }
+  }
+
+  get amount(): string | undefined {
+    return this._amount;
+  }
+
+  get recipient(): string | undefined {
+    return this._recipient;
+  }
+
+  get txHash(): string | undefined {
+    return this._txHash;
+  }
+
+  async prepare(params: SolanaUnstakePrepareParams): Promise<void> {
+    this.assertStatus(NonEvmUnstakeStatus.IDLE, 'prepare');
+
+    return this.act(async () => {
+      const validated = validatePrepareParams(this.prepareSchema, params, {
+        destChain: this.params.destChain,
+      });
+      this._amount = validated.amount;
+      this._recipient = validated.recipient;
+
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.READY,
+        steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+      });
+    }, NonEvmUnstakeStatus.READY);
+  }
+
+  async execute(): Promise<{ txHash: string }> {
+    this.assertStatus(NonEvmUnstakeStatus.READY, 'execute');
+
+    return this.act(async () => {
+      const amount = this._amount;
+      const recipient = this._recipient;
+
+      if (!amount || !recipient) {
+        throw LombardError.missingParameter('amount or recipient');
+      }
+
+      // Emit burning step
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.READY,
+        steps: { burning: StepStatus.PENDING, releasing: StepStatus.IDLE },
+      });
+
+      // Convert amount to base units (satoshis)
+      const amountInSatoshis = toSatoshi(amount).toString();
+      const network = envToSolanaNetwork(this.env);
+
+      // Call the Solana service to execute unstake
+      const { txHash } = await this.ctx.solana.unstake({
+        amount: amountInSatoshis,
+        btcAddress: recipient,
+        network,
+      });
+
+      this._txHash = txHash;
+
+      // Emit completed steps
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.COMPLETED,
+        steps: { burning: StepStatus.COMPLETE, releasing: StepStatus.PENDING },
+      });
+
+      this.emitCompleted();
+
+      return { txHash };
+    }, NonEvmUnstakeStatus.COMPLETED);
+  }
+
+  private get prepareSchema() {
+    return z.object({
+      amount: amountSchema,
+      recipient: solanaToBtcConfig.recipientSchema,
+    });
+  }
+}

package/src/chains/solana/actions/unstake/config/btc.ts

@@ -0,0 +1,47 @@
+/**
+ * BTC Destination Configuration for Solana Unstake
+ *
+ * Handles unstaking LBTC from Solana to BTC on Bitcoin.
+ *
+ * @module chains/solana/actions/unstake/config/btc
+ */
+
+import { Chain, Env } from '../../../../../core';
+import { bitcoinAddressSchema } from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+/**
+ * Solana → BTC configuration
+ *
+ * Burns LBTC on Solana, releases BTC on Bitcoin network.
+ */
+export const solanaToBtcConfig: ChainConfig = {
+  chainType: 'solana',
+
+  routes: [
+    // Production: Solana Mainnet → Bitcoin Mainnet
+    {
+      sourceChains: [Chain.SOLANA_MAINNET],
+      destChain: Chain.BITCOIN_MAINNET,
+      envs: [Env.prod],
+    },
+    // Testnet: Solana Devnet → Bitcoin Signet
+    {
+      sourceChains: [Chain.SOLANA_DEVNET],
+      destChain: Chain.BITCOIN_SIGNET,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  recipientSchema: bitcoinAddressSchema,
+};
+
+/**
+ * Check if unstake to BTC is supported from this Solana chain
+ */
+export function isBtcUnstakeSupported(sourceChain: Chain, env: Env): boolean {
+  return solanaToBtcConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}

package/src/chains/solana/actions/unstake/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Solana Unstake Chain Configuration Registry
+ *
+ * @module chains/solana/actions/unstake/config
+ */
+
+export { isBtcUnstakeSupported,solanaToBtcConfig } from './btc';
+export type { ChainConfig, RouteDefinition } from './types';

package/src/chains/solana/actions/unstake/config/solana.ts

@@ -0,0 +1,47 @@
+/**
+ * BTC Destination Configuration for Solana Unstake
+ *
+ * Handles unstaking LBTC from Solana to BTC on Bitcoin.
+ *
+ * @module chains/solana/actions/unstake/config/btc
+ */
+
+import { Chain, Env } from '../../../../../core';
+import { bitcoinAddressSchema } from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+/**
+ * Solana → BTC configuration
+ *
+ * Burns LBTC on Solana, releases BTC on Bitcoin network.
+ */
+export const solanaToBtcConfig: ChainConfig = {
+  chainType: 'solana',
+
+  routes: [
+    // Production: Solana Mainnet → Bitcoin Mainnet
+    {
+      sourceChains: [Chain.SOLANA_MAINNET],
+      destChain: Chain.BITCOIN_MAINNET,
+      envs: [Env.prod],
+    },
+    // Testnet: Solana Devnet → Bitcoin Signet
+    {
+      sourceChains: [Chain.SOLANA_DEVNET],
+      destChain: Chain.BITCOIN_SIGNET,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  recipientSchema: bitcoinAddressSchema,
+};
+
+/**
+ * Check if unstake to BTC is supported from this Solana chain
+ */
+export function isBtcUnstakeSupported(sourceChain: Chain, env: Env): boolean {
+  return solanaToBtcConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}

package/src/chains/solana/actions/unstake/config/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Solana Unstake Chain Configuration Types
+ *
+ * @module chains/solana/actions/unstake/config/types
+ */
+
+import type { z } from 'zod';
+
+import type { Chain, ChainType, Env } from '../../../../../core';
+
+/**
+ * Route definition for Solana unstake operations
+ */
+export interface RouteDefinition {
+  /** Source chain (Solana network) */
+  sourceChains: Chain[];
+  /** Destination chain (where BTC/BTC.b is received) */
+  destChain: Chain;
+  /** Supported environments */
+  envs: Env[];
+}
+
+/**
+ * Chain-specific configuration for Solana unstake operations
+ */
+export interface ChainConfig {
+  /** Chain type identifier */
+  chainType: ChainType;
+
+  /** Supported routes for this chain type */
+  routes: RouteDefinition[];
+
+  /** Recipient address validation Zod schema */
+  recipientSchema: z.ZodType<string>;
+}

package/src/chains/solana/actions/unstake/factory.ts

@@ -0,0 +1,34 @@
+/**
+ * Solana Unstake Factory Functions
+ *
+ * @module chains/solana/actions/unstake/factory
+ */
+
+import type { LombardConfig } from '../../../../config/types';
+import type { SolanaCoreContext } from '../../../../shared/context';
+import { SolanaUnstake } from './SolanaUnstake';
+import type { ISolanaUnstake,SolanaUnstakeParams } from './types';
+
+/**
+ * Create Solana unstake from context
+ */
+export function createSolanaUnstake(
+  ctx: SolanaCoreContext,
+  params: SolanaUnstakeParams,
+): ISolanaUnstake {
+  return new SolanaUnstake(ctx, params);
+}
+
+/**
+ * Create Solana unstake from config
+ *
+ * This is a placeholder - requires createSolanaCoreContext to be implemented.
+ */
+export function solanaUnstake(
+  _config: LombardConfig,
+  _params: SolanaUnstakeParams,
+): ISolanaUnstake {
+  throw new Error(
+    'solanaUnstake() from config is not yet supported. Use sdk.chain.solana.unstake() instead.',
+  );
+}

package/src/chains/solana/actions/unstake/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Solana Unstake Action
+ *
+ * @module chains/solana/actions/unstake
+ */
+
+export { createSolanaUnstake, solanaUnstake } from './factory';
+export { SolanaUnstake } from './SolanaUnstake';
+export type {
+  ISolanaUnstake,
+  SolanaUnstakeParams,
+  SolanaUnstakePrepareParams,
+  SolanaUnstakeProgress,
+} from './types';

package/src/chains/solana/actions/unstake/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Solana Unstake Action Types
+ *
+ * @module chains/solana/actions/unstake/types
+ */
+
+import type {
+  AssetId,
+  Chain,
+  StepStatus,
+  StrategyProgress,
+} from '../../../../core';
+import type { MonitorableAction } from '../../../../shared/actions/BaseAction';
+import type { NonEvmUnstakeStatus } from '../../../../shared/constants/statusConstants';
+
+/**
+ * Solana Unstake parameters
+ */
+export interface SolanaUnstakeParams {
+  assetIn: AssetId;
+  assetOut: AssetId;
+  sourceChain: Chain;
+  destChain: Chain;
+}
+
+/**
+ * Solana Unstake progress
+ */
+export interface SolanaUnstakeProgress
+  extends StrategyProgress<NonEvmUnstakeStatus> {
+  status: NonEvmUnstakeStatus;
+  steps: {
+    burning: StepStatus;
+    releasing: StepStatus;
+  };
+  txHash?: string;
+  releaseTxHash?: string;
+}
+
+/**
+ * Solana Unstake prepare params
+ */
+export interface SolanaUnstakePrepareParams {
+  amount: string;
+  recipient: string;
+}
+
+/**
+ * Solana Unstake interface
+ */
+export interface ISolanaUnstake extends MonitorableAction {
+  readonly status: NonEvmUnstakeStatus;
+  readonly amount?: string;
+  readonly recipient?: string;
+
+  prepare(params: SolanaUnstakePrepareParams): Promise<void>;
+  execute(): Promise<{ txHash: string }>;
+}

package/src/chains/solana/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Solana Namespace
+ *
+ * @module chains/solana
+ */
+
+export * from './actions';
+export { SolanaActions, solanaActions } from './SolanaActions';

package/src/chains/starknet/StarknetActions.ts

@@ -0,0 +1,85 @@
+/**
+ * Starknet Actions
+ *
+ * Provides factory methods for Starknet operations (unstake).
+ *
+ * Note: Starknet module must be registered before using these actions.
+ *
+ * @example
+ * ```typescript
+ * import { starknetActions } from '@lombard.finance/sdk';
+ *
+ * const starknet = starknetActions(config);
+ * const unstake = starknet.unstake({ ... });
+ * ```
+ */
+
+import type { StarknetService } from '@lombard.finance/sdk-common';
+
+import { PartnerConfiguration } from '../../client/PartnerConfiguration';
+import type { LombardConfig } from '../../config/types';
+import { getProviderGetter } from '../../config/types';
+import { CapabilityRegistry } from '../../modules/CapabilityRegistry';
+import type { StarknetCoreContext } from '../../shared/context';
+import { StarknetUnstake } from './actions/unstake/StarknetUnstake';
+import type {
+  IStarknetUnstake,
+  StarknetUnstakeParams,
+} from './actions/unstake/types';
+
+/**
+ * Create Starknet core context from config
+ * Only called when an action is invoked (lazy initialization)
+ */
+function createStarknetCoreContext(config: LombardConfig): StarknetCoreContext {
+  const registry = new CapabilityRegistry(config.modules, config);
+  const starknet = registry.require('starknet') as StarknetService;
+
+  return {
+    env: config.env,
+    partner: new PartnerConfiguration(config.partner),
+    getProvider: async key => {
+      const getter = getProviderGetter(config.providers, key);
+      if (!getter) return undefined;
+      return getter();
+    },
+    starknet,
+  };
+}
+
+/**
+ * Starknet Actions
+ *
+ * Actions are lazy-loaded - the starknet module is only required when
+ * an action is actually called.
+ */
+export class StarknetActions {
+  private _ctx: StarknetCoreContext | null = null;
+
+  constructor(private readonly config: LombardConfig) {}
+
+  private get ctx(): StarknetCoreContext {
+    if (!this._ctx) {
+      this._ctx = createStarknetCoreContext(this.config);
+    }
+    return this._ctx;
+  }
+
+  /**
+   * Unstake LBTC → BTC
+   *
+   * Burns LBTC on Starknet and releases BTC on Bitcoin.
+   *
+   * @throws LombardError if starknet module is not registered
+   */
+  unstake(params: StarknetUnstakeParams): IStarknetUnstake {
+    return new StarknetUnstake(this.ctx, params);
+  }
+}
+
+/**
+ * Create Starknet actions from config
+ */
+export function starknetActions(config: LombardConfig): StarknetActions {
+  return new StarknetActions(config);
+}

package/src/chains/starknet/actions/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Starknet Actions
+ *
+ * @module chains/starknet/actions
+ */
+
+export * from './unstake';

package/src/chains/starknet/actions/unstake/StarknetUnstake.ts

@@ -0,0 +1,128 @@
+/**
+ * Starknet Unstake Action
+ *
+ * Burns LBTC on Starknet and releases BTC on Bitcoin.
+ *
+ * @module chains/starknet/actions/unstake/StarknetUnstake
+ */
+
+import type { Env } from '@lombard.finance/sdk-common';
+import { z } from 'zod';
+
+import { StepStatus } from '../../../../core';
+import { BaseAction } from '../../../../shared/actions/BaseAction';
+import { NonEvmUnstakeStatus } from '../../../../shared/constants/statusConstants';
+import type { StarknetCoreContext } from '../../../../shared/context';
+import { LombardError } from '../../../../shared/errors';
+import type { UnstakeEventMap } from '../../../../shared/events';
+import {
+  amountSchema,
+  validatePrepareParams,
+} from '../../../../shared/validation';
+import { isBtcUnstakeSupported,starknetToBtcConfig } from './config';
+import type {
+  IStarknetUnstake,
+  StarknetUnstakeParams,
+  StarknetUnstakePrepareParams,
+} from './types';
+
+export class StarknetUnstake
+  extends BaseAction<UnstakeEventMap, NonEvmUnstakeStatus>
+  implements IStarknetUnstake
+{
+  private _amount?: string;
+  private _recipient?: string;
+  private _txHash?: string;
+  private readonly env: Env;
+
+  constructor(
+    private readonly ctx: StarknetCoreContext,
+    private readonly params: StarknetUnstakeParams,
+  ) {
+    super(NonEvmUnstakeStatus.IDLE);
+    this.env = ctx.env;
+
+    if (!isBtcUnstakeSupported(params.sourceChain, this.env)) {
+      throw LombardError.routeNotFound({
+        assetOut: params.assetOut,
+        sourceChain: params.sourceChain,
+        destChain: params.destChain,
+        env: this.env,
+      });
+    }
+  }
+
+  get amount(): string | undefined {
+    return this._amount;
+  }
+
+  get recipient(): string | undefined {
+    return this._recipient;
+  }
+
+  get txHash(): string | undefined {
+    return this._txHash;
+  }
+
+  async prepare(params: StarknetUnstakePrepareParams): Promise<void> {
+    this.assertStatus(NonEvmUnstakeStatus.IDLE, 'prepare');
+
+    return this.act(async () => {
+      const validated = validatePrepareParams(this.prepareSchema, params, {
+        destChain: this.params.destChain,
+      });
+      this._amount = validated.amount;
+      this._recipient = validated.recipient;
+
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.READY,
+        steps: { burning: StepStatus.IDLE, releasing: StepStatus.IDLE },
+      });
+    }, NonEvmUnstakeStatus.READY);
+  }
+
+  async execute(): Promise<{ txHash: string }> {
+    this.assertStatus(NonEvmUnstakeStatus.READY, 'execute');
+
+    return this.act(async () => {
+      const amount = this._amount;
+      const recipient = this._recipient;
+
+      if (!amount || !recipient) {
+        throw LombardError.missingParameter('amount or recipient');
+      }
+
+      // Emit burning step
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.READY,
+        steps: { burning: StepStatus.PENDING, releasing: StepStatus.IDLE },
+      });
+
+      // Call the Starknet service to execute unstake
+      const { txHash } = await this.ctx.starknet.unstake({
+        amount,
+        btcAddress: recipient,
+        env: this.env,
+      });
+
+      this._txHash = txHash;
+
+      // Emit completed steps
+      this.emitProgress({
+        status: NonEvmUnstakeStatus.COMPLETED,
+        steps: { burning: StepStatus.COMPLETE, releasing: StepStatus.PENDING },
+      });
+
+      this.emitCompleted();
+
+      return { txHash };
+    }, NonEvmUnstakeStatus.COMPLETED);
+  }
+
+  private get prepareSchema() {
+    return z.object({
+      amount: amountSchema,
+      recipient: starknetToBtcConfig.recipientSchema,
+    });
+  }
+}

package/src/chains/starknet/actions/unstake/config/btc.ts

@@ -0,0 +1,43 @@
+/**
+ * BTC Destination Configuration for Starknet Unstake
+ *
+ * Handles unstaking LBTC from Starknet to BTC on Bitcoin.
+ *
+ * @module chains/starknet/actions/unstake/config/btc
+ */
+
+import { Chain, Env } from '../../../../../core';
+import { bitcoinAddressSchema } from '../../../../../shared/validation';
+import type { ChainConfig } from './types';
+
+/**
+ * Starknet → BTC configuration
+ */
+export const starknetToBtcConfig: ChainConfig = {
+  chainType: 'starknet',
+
+  routes: [
+    {
+      sourceChains: [Chain.STARKNET_MAINNET],
+      destChain: Chain.BITCOIN_MAINNET,
+      envs: [Env.prod],
+    },
+    {
+      sourceChains: [Chain.STARKNET_SEPOLIA],
+      destChain: Chain.BITCOIN_SIGNET,
+      envs: [Env.testnet, Env.stage, Env.dev, Env.ibc],
+    },
+  ],
+
+  recipientSchema: bitcoinAddressSchema,
+};
+
+/**
+ * Check if unstake to BTC is supported from this Starknet chain
+ */
+export function isBtcUnstakeSupported(sourceChain: Chain, env: Env): boolean {
+  return starknetToBtcConfig.routes.some(
+    route =>
+      route.sourceChains.includes(sourceChain) && route.envs.includes(env),
+  );
+}

package/src/chains/starknet/actions/unstake/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Starknet Unstake Chain Configuration Registry
+ *
+ * @module chains/starknet/actions/unstake/config
+ */
+
+export { isBtcUnstakeSupported,starknetToBtcConfig } from './btc';
+export type { ChainConfig, RouteDefinition } from './types';