@dynamic-labs/stellar 4.59.1 → 4.60.0

package/src/types/IStellarProvider.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Unified Stellar Provider Interface
+ *
+ * This is the normalized interface that all Stellar wallet provider adapters
+ * must implement. It provides a consistent API regardless of the underlying
+ * wallet implementation (OneKey, Freighter, Lobstr, etc.)
+ */
+/**
+ * Events emitted by Stellar wallet providers
+ */
+export type StellarProviderEvent = 'accountChanged' | 'networkChanged';
+/**
+ * Callback for Stellar provider events
+ */
+export type StellarEventCallback = (data: unknown) => void;
+/**
+ * Options for signing Stellar transactions
+ */
+export type StellarSignTransactionOptions = {
+    /** Account public key to sign with (for multi-account wallets) */
+    accountToSign?: string;
+    /** Network identifier ('PUBLIC', 'TESTNET', 'FUTURENET') */
+    network?: string;
+    /** Network passphrase for the transaction */
+    networkPassphrase?: string;
+};
+/**
+ * Unified interface that all Stellar wallet providers must implement
+ * after normalization/adaptation.
+ *
+ * @example
+ * ```typescript
+ * // Connect to wallet
+ * const publicKey = await provider.connect();
+ *
+ * // Get address
+ * const address = await provider.getAddress();
+ *
+ * // Sign a transaction
+ * const signedXdr = await provider.sign(transactionXdr, {
+ *   network: 'TESTNET',
+ *   networkPassphrase: 'Test SDF Network ; September 2015'
+ * });
+ *
+ * // Sign a message
+ * const signature = await provider.signMessage("Hello Stellar");
+ *
+ * // Subscribe to events
+ * provider.on('accountChanged', (newAddress) => {
+ *   console.log('Account changed:', newAddress);
+ * });
+ * ```
+ */
+export type IStellarProvider = {
+    /** Close the wallet connection and cleanup resources */
+    close(): void;
+    /** Connect to the wallet and return the user's public key */
+    connect(): Promise<string>;
+    /** Disconnect from the wallet */
+    disconnect(): Promise<void>;
+    /** Get the user's Stellar public key/address */
+    getAddress(): Promise<string>;
+    /** Get the current network (PUBLIC, TESTNET, FUTURENET) */
+    getNetwork(): Promise<string>;
+    /** Check if the wallet is currently unlocked */
+    isUnlocked(): Promise<boolean>;
+    /** Subscribe to wallet events (account/network changes) */
+    on(event: StellarProviderEvent, callback: StellarEventCallback): void;
+    /** Sign a Stellar transaction XDR */
+    sign(transactionXdr: string, options?: StellarSignTransactionOptions): Promise<string>;
+    /** Sign an arbitrary message */
+    signMessage(message: string): Promise<string>;
+};

package/src/types/LobstrProvider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lobstr Signer Extension Provider Types
+ *
+ * Types for the Lobstr Signer Extension API
+ * From @lobstrco/signer-extension-api package
+ */
+/**
+ * Lobstr Signer Extension API
+ * These are the raw methods provided by @lobstrco/signer-extension-api package
+ *
+ * Note: Lobstr uses a functional API (individual exported functions)
+ * rather than a provider object at window.lobstr
+ */
+export type LobstrSignerApi = {
+    /** Get the user's public key */
+    getPublicKey: () => Promise<string>;
+    /** Sign a transaction */
+    signTransaction: (transactionXdr: string) => Promise<string>;
+    /** Check if extension is installed and accessible */
+    isConnected: () => Promise<boolean>;
+    /** Sign a message */
+    signMessage: (message: string) => Promise<{
+        signedMessage: string;
+        signerAddress: string;
+    } | null>;
+};
+/**
+ * Lobstr sign message response
+ */
+export type LobstrSignMessageResponse = {
+    signedMessage: string;
+    signerAddress: string;
+} | null;

package/src/types.d.ts

@@ -1,6 +1,5 @@
-import type { Transaction } from '@stellar/stellar-sdk';
 import type { GenericNetwork } from '@dynamic-labs/types';
-import type { ProviderCondition } from '@dynamic-labs/wallet-connector-core';
+import type { WalletConnectorConstructor } from '@dynamic-labs/wallet-connector-core';
 /**
  * Interface for Stellar wallet providers.
  *
@@ -74,20 +73,15 @@ export type StellarConnectionResult = {
 export type StellarSendBalanceProps = {
     /** Amount to send (in XLM for native transfers) */
     amount: string;
-    /** Optional asset information for non-XLM transfers */
-    asset?: {
-        /** Asset code */
-        code: string;
-        /** Asset issuer */
-        issuer: string;
-    };
-    /** Optional memo */
-    memo?: {
-        type: 'hash' | 'id' | 'return' | 'text';
-        value: string;
-    };
     /** Recipient address (Stellar public key) */
     toAddress: string;
+    /** Optional token information for non-XLM transfers */
+    token?: {
+        /** Token address in format "CODE:ISSUER" (e.g., "USDC:GXXXXXXX...") */
+        address: string;
+        /** Token decimals (optional, Stellar uses 7 decimals by default) */
+        decimals?: number;
+    };
 };
 /**
  * Stellar wallet connector constructor properties
@@ -100,16 +94,6 @@ export type StellarWalletConnectorProps = {
     /** Wallet book schema */
     walletBook: unknown;
 };
-/**
- * Extension locators for identifying Stellar wallet browser extensions.
- * These flags are typically set on the injected provider object to identify
- * which wallet extension is present.
- */
-export type ExtensionLocator = 'isAlbedo' | 'isFreighter' | 'isLobstr' | 'isRabet' | 'isXBull';
-/**
- * Type for Stellar provider condition used in provider lookup.
- */
-export type StellarProviderCondition = ProviderCondition<ExtensionLocator>;
 /**
  * Stellar network names
  */
@@ -119,6 +103,9 @@ export type StellarNetworkName = 'FUTURENET' | 'PUBLIC' | 'TESTNET';
  */
 export type StellarMethodName = 'close' | 'connect' | 'disconnect' | 'getNetwork' | 'isUnlocked' | 'on' | 'sign' | 'signMessage';
 /**
- * Stellar transaction type from the SDK
+ * Stellar wallet connector with isConnected check.
+ * Extends WalletConnectorConstructor with an optional isConnected method.
  */
-export type StellarTransaction = Transaction;
+export interface StellarWalletConnectorWithIsConnected extends WalletConnectorConstructor {
+    isConnected?: () => Promise<boolean>;
+}

package/src/utils/buildPaymentTransaction.cjs

@@ -0,0 +1,37 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var stellarSdk = require('@stellar/stellar-sdk');
+
+const DEFAULT_TIMEOUT = 180;
+/**
+ * Builds a Stellar payment transaction.
+ *
+ * @param params - Transaction parameters
+ * @param params.sourceAccount - The source account
+ * @param params.networkPassphrase - The network passphrase
+ * @param params.toAddress - Recipient address
+ * @param params.amount - Amount to send
+ * @param params.asset - Asset to send
+ * @param params.memo - Optional transaction memo
+ * @returns A built Stellar transaction
+ */
+const buildPaymentTransaction = (params) => {
+    const { sourceAccount, networkPassphrase, toAddress, amount, asset, memo } = params;
+    const transactionBuilder = new stellarSdk.TransactionBuilder(sourceAccount, {
+        fee: stellarSdk.BASE_FEE,
+        networkPassphrase,
+    }).addOperation(stellarSdk.Operation.payment({
+        amount,
+        asset,
+        destination: toAddress,
+    }));
+    if (memo) {
+        transactionBuilder.addMemo(memo);
+    }
+    return transactionBuilder.setTimeout(DEFAULT_TIMEOUT).build();
+};
+
+exports.buildPaymentTransaction = buildPaymentTransaction;

package/src/utils/buildPaymentTransaction.d.ts

@@ -0,0 +1,21 @@
+import { type Asset, type Horizon, type Memo, Transaction } from '@stellar/stellar-sdk';
+/**
+ * Builds a Stellar payment transaction.
+ *
+ * @param params - Transaction parameters
+ * @param params.sourceAccount - The source account
+ * @param params.networkPassphrase - The network passphrase
+ * @param params.toAddress - Recipient address
+ * @param params.amount - Amount to send
+ * @param params.asset - Asset to send
+ * @param params.memo - Optional transaction memo
+ * @returns A built Stellar transaction
+ */
+export declare const buildPaymentTransaction: (params: {
+    amount: string;
+    asset: Asset;
+    memo?: Memo;
+    networkPassphrase: string;
+    sourceAccount: Horizon.AccountResponse;
+    toAddress: string;
+}) => Transaction;

package/src/utils/buildPaymentTransaction.js

@@ -0,0 +1,33 @@
+'use client'
+import { TransactionBuilder, BASE_FEE, Operation } from '@stellar/stellar-sdk';
+
+const DEFAULT_TIMEOUT = 180;
+/**
+ * Builds a Stellar payment transaction.
+ *
+ * @param params - Transaction parameters
+ * @param params.sourceAccount - The source account
+ * @param params.networkPassphrase - The network passphrase
+ * @param params.toAddress - Recipient address
+ * @param params.amount - Amount to send
+ * @param params.asset - Asset to send
+ * @param params.memo - Optional transaction memo
+ * @returns A built Stellar transaction
+ */
+const buildPaymentTransaction = (params) => {
+    const { sourceAccount, networkPassphrase, toAddress, amount, asset, memo } = params;
+    const transactionBuilder = new TransactionBuilder(sourceAccount, {
+        fee: BASE_FEE,
+        networkPassphrase,
+    }).addOperation(Operation.payment({
+        amount,
+        asset,
+        destination: toAddress,
+    }));
+    if (memo) {
+        transactionBuilder.addMemo(memo);
+    }
+    return transactionBuilder.setTimeout(DEFAULT_TIMEOUT).build();
+};
+
+export { buildPaymentTransaction };

package/src/utils/checkTrustline.cjs

@@ -0,0 +1,33 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Checks if an account has a trustline for a specific asset.
+ *
+ * @param account - The Horizon account response
+ * @param asset - The asset to check for trustline
+ * @returns True if the account has a trustline for the asset, false otherwise
+ */
+const checkTrustline = (account, asset) => {
+    // Native asset (XLM) doesn't require a trustline
+    if (asset.isNative()) {
+        return true;
+    }
+    // Check if the account has a balance for this asset
+    const assetCode = asset.getCode();
+    const assetIssuer = asset.getIssuer();
+    return account.balances.some((balance) => {
+        if (balance.asset_type === 'native') {
+            return false;
+        }
+        if (balance.asset_type === 'credit_alphanum4' ||
+            balance.asset_type === 'credit_alphanum12') {
+            return (balance.asset_code === assetCode && balance.asset_issuer === assetIssuer);
+        }
+        return false;
+    });
+};
+
+exports.checkTrustline = checkTrustline;

package/src/utils/checkTrustline.d.ts

@@ -0,0 +1,9 @@
+import type { Asset, Horizon } from '@stellar/stellar-sdk';
+/**
+ * Checks if an account has a trustline for a specific asset.
+ *
+ * @param account - The Horizon account response
+ * @param asset - The asset to check for trustline
+ * @returns True if the account has a trustline for the asset, false otherwise
+ */
+export declare const checkTrustline: (account: Horizon.AccountResponse, asset: Asset) => boolean;

package/src/utils/checkTrustline.js

@@ -0,0 +1,29 @@
+'use client'
+/**
+ * Checks if an account has a trustline for a specific asset.
+ *
+ * @param account - The Horizon account response
+ * @param asset - The asset to check for trustline
+ * @returns True if the account has a trustline for the asset, false otherwise
+ */
+const checkTrustline = (account, asset) => {
+    // Native asset (XLM) doesn't require a trustline
+    if (asset.isNative()) {
+        return true;
+    }
+    // Check if the account has a balance for this asset
+    const assetCode = asset.getCode();
+    const assetIssuer = asset.getIssuer();
+    return account.balances.some((balance) => {
+        if (balance.asset_type === 'native') {
+            return false;
+        }
+        if (balance.asset_type === 'credit_alphanum4' ||
+            balance.asset_type === 'credit_alphanum12') {
+            return (balance.asset_code === assetCode && balance.asset_issuer === assetIssuer);
+        }
+        return false;
+    });
+};
+
+export { checkTrustline };

package/src/utils/createPaymentAsset.cjs

@@ -0,0 +1,23 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var stellarSdk = require('@stellar/stellar-sdk');
+
+/**
+ * Creates a Stellar Asset object for payment operations.
+ *
+ * @param asset - Optional asset information
+ * @param asset.code - Asset code
+ * @param asset.issuer - Asset issuer public key
+ * @returns A Stellar Asset object (native XLM or custom asset)
+ */
+const createPaymentAsset = (asset) => {
+    if (asset) {
+        return new stellarSdk.Asset(asset.code, asset.issuer);
+    }
+    return stellarSdk.Asset.native();
+};
+
+exports.createPaymentAsset = createPaymentAsset;

package/src/utils/createPaymentAsset.d.ts

@@ -0,0 +1,13 @@
+import { Asset } from '@stellar/stellar-sdk';
+/**
+ * Creates a Stellar Asset object for payment operations.
+ *
+ * @param asset - Optional asset information
+ * @param asset.code - Asset code
+ * @param asset.issuer - Asset issuer public key
+ * @returns A Stellar Asset object (native XLM or custom asset)
+ */
+export declare const createPaymentAsset: (asset?: {
+    code: string;
+    issuer: string;
+}) => Asset;

package/src/utils/createPaymentAsset.js

@@ -0,0 +1,19 @@
+'use client'
+import { Asset } from '@stellar/stellar-sdk';
+
+/**
+ * Creates a Stellar Asset object for payment operations.
+ *
+ * @param asset - Optional asset information
+ * @param asset.code - Asset code
+ * @param asset.issuer - Asset issuer public key
+ * @returns A Stellar Asset object (native XLM or custom asset)
+ */
+const createPaymentAsset = (asset) => {
+    if (asset) {
+        return new Asset(asset.code, asset.issuer);
+    }
+    return Asset.native();
+};
+
+export { createPaymentAsset };

package/src/utils/createTransactionMemo.d.ts

@@ -0,0 +1,13 @@
+import { Memo } from '@stellar/stellar-sdk';
+/**
+ * Creates a Stellar transaction memo from memo parameters.
+ *
+ * @param memo - Optional memo information
+ * @param memo.type - Memo type ('text', 'id', 'hash', or 'return')
+ * @param memo.value - Memo value
+ * @returns A Stellar Memo object or undefined if no memo provided
+ */
+export declare const createTransactionMemo: (memo?: {
+    type: 'hash' | 'id' | 'return' | 'text';
+    value: string;
+}) => Memo | undefined;

package/src/utils/getAccountBalance.cjs

@@ -0,0 +1,33 @@
+'use client'
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Gets the balance for a specific asset from a Stellar account.
+ *
+ * @param account - The Horizon account object
+ * @param assetCode - Optional asset code. If not provided, returns native XLM balance
+ * @param assetIssuer - Optional asset issuer. Required if assetCode is provided
+ * @returns The balance as a string
+ * @throws Error if assetCode is provided without assetIssuer
+ */
+const getAccountBalance = (account, assetCode, assetIssuer) => {
+    if (!assetCode) {
+        const nativeBalance = account.balances.find((balance) => balance.asset_type === 'native');
+        return nativeBalance && 'balance' in nativeBalance
+            ? nativeBalance.balance
+            : '0';
+    }
+    if (!assetIssuer) {
+        throw new Error('Asset issuer is required when asset code is provided');
+    }
+    const assetBalance = account.balances.find((balance) => balance.asset_type !== 'native' &&
+        'asset_code' in balance &&
+        'asset_issuer' in balance &&
+        balance.asset_code === assetCode &&
+        balance.asset_issuer === assetIssuer);
+    return assetBalance && 'balance' in assetBalance ? assetBalance.balance : '0';
+};
+
+exports.getAccountBalance = getAccountBalance;

package/src/utils/getAccountBalance.d.ts

@@ -0,0 +1,11 @@
+import type { Horizon } from '@stellar/stellar-sdk';
+/**
+ * Gets the balance for a specific asset from a Stellar account.
+ *
+ * @param account - The Horizon account object
+ * @param assetCode - Optional asset code. If not provided, returns native XLM balance
+ * @param assetIssuer - Optional asset issuer. Required if assetCode is provided
+ * @returns The balance as a string
+ * @throws Error if assetCode is provided without assetIssuer
+ */
+export declare const getAccountBalance: (account: Horizon.AccountResponse, assetCode?: string, assetIssuer?: string) => string;

package/src/utils/getAccountBalance.js

@@ -0,0 +1,29 @@
+'use client'
+/**
+ * Gets the balance for a specific asset from a Stellar account.
+ *
+ * @param account - The Horizon account object
+ * @param assetCode - Optional asset code. If not provided, returns native XLM balance
+ * @param assetIssuer - Optional asset issuer. Required if assetCode is provided
+ * @returns The balance as a string
+ * @throws Error if assetCode is provided without assetIssuer
+ */
+const getAccountBalance = (account, assetCode, assetIssuer) => {
+    if (!assetCode) {
+        const nativeBalance = account.balances.find((balance) => balance.asset_type === 'native');
+        return nativeBalance && 'balance' in nativeBalance
+            ? nativeBalance.balance
+            : '0';
+    }
+    if (!assetIssuer) {
+        throw new Error('Asset issuer is required when asset code is provided');
+    }
+    const assetBalance = account.balances.find((balance) => balance.asset_type !== 'native' &&
+        'asset_code' in balance &&
+        'asset_issuer' in balance &&
+        balance.asset_code === assetCode &&
+        balance.asset_issuer === assetIssuer);
+    return assetBalance && 'balance' in assetBalance ? assetBalance.balance : '0';
+};
+
+export { getAccountBalance };

package/src/utils/getNetworkPassphrase.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Gets the network passphrase for a given network name.
+ *
+ * @param network - The network name ('PUBLIC', 'TESTNET', or 'FUTURENET')
+ * @returns The network passphrase
+ */
+export declare const getNetworkPassphrase: (network: string | undefined) => string;

package/src/utils/index.d.ts

@@ -1 +1,8 @@
+export { buildPaymentTransaction } from './buildPaymentTransaction';
+export { checkTrustline } from './checkTrustline';
+export { createPaymentAsset } from './createPaymentAsset';
+export { createTransactionMemo } from './createTransactionMemo';
+export { getAccountBalance } from './getAccountBalance';
 export { getNetworkFromAddress } from './getNetworkFromAddress';
+export { getNetworkPassphrase } from './getNetworkPassphrase';
+export { normalizeNetworkName } from './normalizeNetworkName';

package/src/utils/normalizeNetworkName.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize network name to standard format
+ *
+ * @param network - Raw network name from wallet
+ * @returns Normalized network name (PUBLIC, TESTNET, or FUTURENET)
+ *
+ * @example
+ * ```typescript
+ * normalizeNetworkName('mainnet') // 'PUBLIC'
+ * normalizeNetworkName('testnet') // 'TESTNET'
+ * normalizeNetworkName('Test SDF Network ; September 2015') // 'TESTNET'
+ * ```
+ */
+export declare const normalizeNetworkName: (network: string) => string;

package/src/wallet/StellarWallet.cjs

@@ -4,7 +4,12 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var _tslib = require('../../_virtual/_tslib.cjs');
+var stellarSdk = require('@stellar/stellar-sdk');
 var walletConnectorCore = require('@dynamic-labs/wallet-connector-core');
+var buildPaymentTransaction = require('../utils/buildPaymentTransaction.cjs');
+var checkTrustline = require('../utils/checkTrustline.cjs');
+var createPaymentAsset = require('../utils/createPaymentAsset.cjs');
+var getAccountBalance = require('../utils/getAccountBalance.cjs');
 
 /**
  * Stellar wallet implementation that provides chain-specific functionality
@@ -16,26 +21,76 @@ var walletConnectorCore = require('@dynamic-labs/wallet-connector-core');
 class StellarWallet extends walletConnectorCore.Wallet {
     /**
      * Get balance of the wallet.
-     * @returns Balance of the wallet in XLM
+     * @param assetCode - Optional asset code. If not provided, returns native XLM balance
+     * @param assetIssuer - Optional asset issuer. Required if assetCode is provided
+     * @returns Balance of the wallet
      */
-    getBalance() {
+    getBalance(assetCode, assetIssuer) {
         return _tslib.__awaiter(this, void 0, void 0, function* () {
             yield this._connector.connect();
-            // Balance fetching will be implemented when full SDK support is added
-            return '0';
+            const horizonServer = yield this.getHorizonServer();
+            const account = yield horizonServer.loadAccount(this.address);
+            return getAccountBalance.getAccountBalance(account, assetCode, assetIssuer);
         });
     }
     /**
      * Sends balance to another address.
-     * @param amount - Amount to send (in XLM for native transfers)
-     * @param toAddress - Recipient address
+     * Supports both native XLM and custom Stellar assets.
+     *
+     * @param params - Send balance parameters
+     * @param params.amount - Amount to send
+     * @param params.toAddress - Recipient address (Stellar public key)
+     * @param params.token - Optional token information for non-XLM transfers
+     * @param params.token.address - Token address in format "CODE:ISSUER"
+     * @param params.token.decimals - Token decimals (optional, Stellar uses 7 decimals by default)
      * @returns Transaction hash
      */
-    sendBalance(_a) {
-        return _tslib.__awaiter(this, arguments, void 0, function* ({ amount, toAddress, }) {
+    sendBalance(params) {
+        return _tslib.__awaiter(this, void 0, void 0, function* () {
+            const { amount, toAddress, token } = params;
             yield this._connector.connect();
-            // Transaction sending will be implemented when full SDK support is added
-            throw new Error(`sendBalance not yet implemented. Amount: ${amount}, To: ${toAddress}`);
+            const horizonServer = yield this.getHorizonServer();
+            const sourceAccount = yield horizonServer.loadAccount(this.address);
+            const networkPassphrase = yield this._connector.getNetworkPassphrase();
+            let asset;
+            if (token === null || token === void 0 ? void 0 : token.address) {
+                const [code, issuer] = token.address.split(':');
+                if (!code || !issuer) {
+                    throw new Error('Invalid token address format. Expected "CODE:ISSUER" (e.g., "USDC:GXXXXXXX...")');
+                }
+                asset = { code, issuer };
+            }
+            const paymentAsset = createPaymentAsset.createPaymentAsset(asset);
+            let destinationAccount;
+            try {
+                destinationAccount = yield horizonServer.loadAccount(toAddress);
+            }
+            catch (error) {
+                throw new Error(`Failed to load destination account ${toAddress}. The account may not exist or be funded.`);
+            }
+            // Check if destination account has trustline for non-native assets
+            if (!paymentAsset.isNative()) {
+                const hasTrustline = checkTrustline.checkTrustline(destinationAccount, paymentAsset);
+                if (!hasTrustline) {
+                    const assetCode = paymentAsset.getCode();
+                    const assetIssuer = paymentAsset.getIssuer();
+                    throw new Error(`Destination account ${toAddress} does not have a trustline for asset ${assetCode}:${assetIssuer}. ` +
+                        'The recipient must establish a trustline before receiving this asset.');
+                }
+            }
+            const transaction = buildPaymentTransaction.buildPaymentTransaction({
+                amount,
+                asset: paymentAsset,
+                memo: undefined,
+                networkPassphrase,
+                sourceAccount,
+                toAddress,
+            });
+            const transactionXdr = transaction.toXDR();
+            const signedXdr = yield this.signTransaction(transactionXdr);
+            const transactionToSubmit = stellarSdk.TransactionBuilder.fromXDR(signedXdr, networkPassphrase);
+            const response = yield horizonServer.submitTransaction(transactionToSubmit);
+            return response.hash;
         });
     }
     /**