@openzeppelin/adapter-stellar 1.0.0

package/src/query/handler.ts

@@ -0,0 +1,411 @@
+import {
+  Account,
+  Address,
+  BASE_FEE,
+  Contract,
+  nativeToScVal,
+  rpc as StellarRpc,
+  TransactionBuilder,
+  xdr,
+} from '@stellar/stellar-sdk';
+
+import type {
+  ContractSchema,
+  FunctionParameter,
+  NetworkConfig,
+  StellarNetworkConfig,
+} from '@openzeppelin/ui-types';
+import { logger, userRpcConfigService } from '@openzeppelin/ui-utils';
+
+import { parseStellarInput } from '../transform';
+import { formatStellarFunctionResult } from '../transform/output-formatter';
+import { convertStellarTypeToScValType } from '../utils';
+import { isStellarViewFunction } from './view-checker';
+
+/**
+ * Private helper to get a Soroban RPC Server instance for view queries.
+ * Prioritizes custom RPC configuration, then falls back to network default.
+ */
+function getSorobanRpcServer(networkConfig: StellarNetworkConfig): StellarRpc.Server {
+  // Check if there's a custom RPC configuration
+  const customRpcConfig = userRpcConfigService.getUserRpcConfig(networkConfig.id);
+  const rpcUrl = customRpcConfig?.url || networkConfig.sorobanRpcUrl;
+
+  if (!rpcUrl) {
+    throw new Error(`No Soroban RPC URL available for network ${networkConfig.name}`);
+  }
+
+  logger.info(
+    'getSorobanRpcServer',
+    `Creating Soroban RPC server for ${networkConfig.name} using RPC: ${rpcUrl}`
+  );
+
+  // Allow HTTP for localhost development
+  const allowHttp = new URL(rpcUrl).hostname === 'localhost';
+
+  return new StellarRpc.Server(rpcUrl, {
+    allowHttp,
+  });
+}
+
+/**
+ * Creates a dummy transaction to simulate a contract function call.
+ * This is used for view functions that don't modify state.
+ */
+async function createSimulationTransaction(
+  contractAddress: string,
+  functionName: string,
+  args: unknown[],
+  paramTypes: string[],
+  networkConfig: StellarNetworkConfig
+): Promise<TransactionBuilder> {
+  try {
+    // Create a dummy source account for simulation
+    // For simulations, we only need a valid public key - no private key required.
+    // Using a hardcoded test public key avoids Keypair.random() issues in test environments
+    // where @noble/curves crypto may not work correctly.
+    // This is a valid Stellar public key (the "zero" key derived from 32 zero bytes).
+    const SIMULATION_PUBLIC_KEY = 'GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF';
+    const sourceAccount = new Account(SIMULATION_PUBLIC_KEY, '0');
+
+    // Create contract instance
+    const contract = new Contract(contractAddress);
+
+    // Convert args to ScVal with proper type hints
+    const scValArgs = args.map((arg, index) => {
+      const paramType = paramTypes[index];
+      if (!paramType) {
+        // Fallback to direct conversion if type info missing
+        return nativeToScVal(arg);
+      }
+
+      // Special cases that don't need type hints
+      if (paramType === 'Bool' || paramType === 'Bytes' || paramType.match(/^BytesN<\d+>$/)) {
+        return nativeToScVal(arg);
+      }
+
+      // Use common utility for type conversion with hints
+      const typeHint = convertStellarTypeToScValType(paramType);
+      return nativeToScVal(arg, { type: typeHint });
+    });
+
+    // Build the transaction for simulation
+    const transaction = new TransactionBuilder(sourceAccount, {
+      fee: BASE_FEE,
+      networkPassphrase: networkConfig.networkPassphrase,
+    })
+      .addOperation(contract.call(functionName, ...scValArgs))
+      .setTimeout(30);
+
+    return transaction;
+  } catch (error) {
+    logger.error('createSimulationTransaction', 'Failed to create simulation transaction:', error);
+    throw new Error(`Failed to create simulation transaction: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Determines if a Stellar contract function modifies state by simulating it
+ * and checking for state changes.
+ *
+ * @param contractAddress Address of the contract.
+ * @param functionName Name of the function to check.
+ * @param networkConfig The specific network configuration.
+ * @param inputTypes Parameter types for the function (empty array for parameterless functions).
+ * @returns True if the function modifies state, false if it's read-only.
+ */
+export async function checkStellarFunctionStateMutability(
+  contractAddress: string,
+  functionName: string,
+  networkConfig: StellarNetworkConfig,
+  inputTypes: string[] = []
+): Promise<boolean> {
+  logger.info(
+    'checkStellarFunctionStateMutability',
+    `Checking state mutability for function: ${functionName} on ${contractAddress}`
+  );
+
+  try {
+    // --- Validate Contract Address --- //
+    try {
+      Address.fromString(contractAddress);
+    } catch {
+      throw new Error(`Invalid Stellar contract address provided: ${contractAddress}`);
+    }
+
+    // --- Get Soroban RPC Server --- //
+    const rpcServer = getSorobanRpcServer(networkConfig);
+
+    // --- Create dummy parameters for simulation --- //
+    // For state mutability detection, we can use dummy values since we only care about state changes
+    const dummyArgs = inputTypes.map((paramType) => {
+      // Create minimal dummy values for different types
+      switch (paramType) {
+        case 'Bool':
+          return false;
+        case 'I32':
+        case 'U32':
+        case 'I64':
+        case 'U64':
+        case 'I128':
+        case 'U128':
+        case 'I256':
+        case 'U256':
+          return 0;
+        case 'String':
+          return '';
+        case 'Bytes':
+          return Buffer.alloc(0);
+        case 'Address':
+          // Use the contract address as a dummy address
+          return contractAddress;
+        default:
+          // For complex types, use null which often gets converted to appropriate defaults
+          return null;
+      }
+    });
+
+    // --- Create Simulation Transaction --- //
+    const transactionBuilder = await createSimulationTransaction(
+      contractAddress,
+      functionName,
+      dummyArgs,
+      inputTypes,
+      networkConfig
+    );
+
+    const transaction = transactionBuilder.build();
+
+    logger.debug(
+      'checkStellarFunctionStateMutability',
+      `[Check ${functionName}] Simulating transaction for state mutability check`
+    );
+
+    // --- Simulate Transaction --- //
+    let simulationResult: StellarRpc.Api.SimulateTransactionResponse;
+    try {
+      simulationResult = await rpcServer.simulateTransaction(transaction);
+    } catch (simulationError) {
+      logger.warn(
+        'checkStellarFunctionStateMutability',
+        `[Check ${functionName}] Simulation failed, assuming function modifies state:`,
+        simulationError
+      );
+      // If simulation fails, err on the side of caution and assume it modifies state
+      return true;
+    }
+
+    // --- Process Simulation Result --- //
+    if (StellarRpc.Api.isSimulationError(simulationResult)) {
+      logger.warn(
+        'checkStellarFunctionStateMutability',
+        `[Check ${functionName}] Simulation error, assuming function modifies state:`,
+        simulationResult.error
+      );
+      // If there's a simulation error, assume it modifies state for safety
+      return true;
+    }
+
+    // --- Check State Changes --- //
+    // Filter out infrastructure state changes that occur for every invocation:
+    // 1. CONTRACT_CODE entries (WASM code TTL bumps)
+    // 2. CONTRACT_DATA entries with scvLedgerKeyContractInstance key (instance TTL bumps)
+    // Only remaining entries represent actual contract storage modifications.
+    const storageChanges = (simulationResult.stateChanges ?? []).filter((change) => {
+      try {
+        const keyType = change.key.switch();
+
+        if (keyType === xdr.LedgerEntryType.contractCode()) {
+          return false;
+        }
+
+        if (keyType === xdr.LedgerEntryType.contractData()) {
+          const dataKey = change.key.contractData().key();
+          if (dataKey.switch() === xdr.ScValType.scvLedgerKeyContractInstance()) {
+            return false;
+          }
+        }
+
+        return true;
+      } catch {
+        return true;
+      }
+    });
+
+    const hasStorageChanges = storageChanges.length > 0;
+
+    logger.info(
+      'checkStellarFunctionStateMutability',
+      `[Check ${functionName}] State mutability check complete:`,
+      {
+        totalStateChanges: simulationResult.stateChanges?.length || 0,
+        storageChangesCount: storageChanges.length,
+        modifiesState: hasStorageChanges,
+      }
+    );
+
+    return hasStorageChanges;
+  } catch (error) {
+    logger.warn(
+      'checkStellarFunctionStateMutability',
+      `Failed to check state mutability for ${functionName}, assuming it modifies state:`,
+      error
+    );
+    // If anything goes wrong, assume the function modifies state as a safe default
+    return true;
+  }
+}
+
+/**
+ * Core logic for querying a Stellar view function.
+ *
+ * @param contractAddress Address of the contract.
+ * @param functionId ID of the function to query.
+ * @param networkConfig The specific network configuration.
+ * @param params Raw parameters for the function call.
+ * @param contractSchema Optional pre-loaded contract schema.
+ * @param loadContractFn Function reference to load contract schema if not provided.
+ * @returns The decoded result of the view function call.
+ */
+export async function queryStellarViewFunction(
+  contractAddress: string,
+  functionId: string,
+  networkConfig: NetworkConfig,
+  params: unknown[] = [],
+  contractSchema?: ContractSchema,
+  loadContractFn?: (source: string) => Promise<ContractSchema>
+): Promise<unknown> {
+  logger.info(
+    'queryStellarViewFunction',
+    `Querying Stellar view function: ${functionId} on ${contractAddress} (${networkConfig.name})`,
+    { params }
+  );
+
+  if (networkConfig.ecosystem !== 'stellar') {
+    throw new Error('Invalid network configuration for Stellar query.');
+  }
+
+  const stellarConfig = networkConfig as StellarNetworkConfig;
+
+  try {
+    // --- Validate Contract Address --- //
+    try {
+      Address.fromString(contractAddress);
+    } catch {
+      throw new Error(`Invalid Stellar contract address provided: ${contractAddress}`);
+    }
+
+    // --- Get Soroban RPC Server --- //
+    const rpcServer = getSorobanRpcServer(stellarConfig);
+
+    // --- Get Schema & Function Details --- //
+    let schema = contractSchema;
+    if (!schema && loadContractFn) {
+      schema = await loadContractFn(contractAddress);
+    }
+    if (!schema) {
+      throw new Error(
+        `Contract schema not provided and loadContractFn not available for ${contractAddress}`
+      );
+    }
+
+    const functionDetails = schema.functions.find((fn) => fn.id === functionId);
+    if (!functionDetails) {
+      throw new Error(`Function with ID ${functionId} not found in contract schema.`);
+    }
+
+    if (!isStellarViewFunction(functionDetails)) {
+      throw new Error(`Function ${functionDetails.name} is not a view function.`);
+    }
+
+    // --- Parse Input Parameters --- //
+    const expectedInputs: readonly FunctionParameter[] = functionDetails.inputs;
+    if (params.length !== expectedInputs.length) {
+      throw new Error(
+        `Incorrect number of parameters provided for ${functionDetails.name}. Expected ${expectedInputs.length}, got ${params.length}.`
+      );
+    }
+
+    const args = expectedInputs.map((inputParam: FunctionParameter, index: number) => {
+      const rawValue = params[index];
+      return parseStellarInput(rawValue, inputParam.type);
+    });
+
+    logger.debug('queryStellarViewFunction', 'Parsed Args for contract call:', args);
+
+    // --- Create Simulation Transaction --- //
+    const paramTypes = expectedInputs.map((input) => input.type);
+    const transactionBuilder = await createSimulationTransaction(
+      contractAddress,
+      functionDetails.name,
+      args,
+      paramTypes,
+      stellarConfig
+    );
+
+    const transaction = transactionBuilder.build();
+
+    logger.debug(
+      'queryStellarViewFunction',
+      `[Query ${functionDetails.name}] Simulating transaction:`,
+      transaction.toXDR()
+    );
+
+    // --- Simulate Transaction --- //
+    let simulationResult: StellarRpc.Api.SimulateTransactionResponse;
+    try {
+      simulationResult = await rpcServer.simulateTransaction(transaction);
+    } catch (simulationError) {
+      logger.error(
+        'queryStellarViewFunction',
+        `[Query ${functionDetails.name}] Simulation failed:`,
+        simulationError
+      );
+      throw new Error(
+        `Soroban RPC simulation failed for ${functionDetails.name}: ${(simulationError as Error).message}`
+      );
+    }
+
+    // --- Process Simulation Result --- //
+    if (StellarRpc.Api.isSimulationError(simulationResult)) {
+      logger.error(
+        'queryStellarViewFunction',
+        `[Query ${functionDetails.name}] Simulation error:`,
+        simulationResult.error
+      );
+      throw new Error(`Contract simulation failed: ${simulationResult.error}`);
+    }
+
+    if (!simulationResult.result) {
+      throw new Error(`No result returned from contract simulation for ${functionDetails.name}`);
+    }
+
+    const rawResult = simulationResult.result.retval;
+    logger.debug(
+      'queryStellarViewFunction',
+      `[Query ${functionDetails.name}] Raw simulation result:`,
+      rawResult
+    );
+
+    // --- Format Result --- //
+    const formattedResult = formatStellarFunctionResult(rawResult, functionDetails);
+
+    logger.info(
+      'queryStellarViewFunction',
+      `[Query ${functionDetails.name}] Formatted result:`,
+      formattedResult
+    );
+
+    return formattedResult;
+  } catch (error) {
+    const errorMessage = `Failed to query Stellar view function ${functionId} on network ${networkConfig.name}: ${(error as Error).message}`;
+    logger.error('queryStellarViewFunction', errorMessage, {
+      contractAddress,
+      functionId,
+      params,
+      networkConfig,
+      error,
+    });
+    throw new Error(errorMessage);
+  }
+}

package/src/query/index.ts

@@ -0,0 +1,4 @@
+// Barrel file
+
+export * from './handler';
+export * from './view-checker';

package/src/query/view-checker.ts

@@ -0,0 +1,32 @@
+import type { ContractFunction, ContractSchema } from '@openzeppelin/ui-types';
+
+/**
+ * Determines if a function is a view/pure function (read-only) for Stellar contracts.
+ * This function works with simulation-based state mutability detection results
+ * from the contract loader, following the same approach as the official Stellar Laboratory.
+ *
+ * @param functionDetails The function details from the contract schema (with simulation-based mutability info).
+ * @returns True if the function is read-only, false otherwise.
+ */
+export function isStellarViewFunction(functionDetails: ContractFunction): boolean {
+  // First check stateMutability if available (set by simulation-based detection)
+  if (functionDetails.stateMutability) {
+    return functionDetails.stateMutability === 'view' || functionDetails.stateMutability === 'pure';
+  }
+
+  // Fallback to modifiesState if stateMutability is not available
+  // (also set by simulation-based detection in the loader)
+  return !functionDetails.modifiesState;
+}
+
+/**
+ * Get only the functions that modify state (writable functions) for Stellar contracts.
+ * Uses simulation-based state mutability detection results to accurately filter functions.
+ * @param contractSchema The contract schema to filter (with simulation-based mutability info).
+ * @returns Array of writable functions
+ */
+export function getStellarWritableFunctions(
+  contractSchema: ContractSchema
+): ContractSchema['functions'] {
+  return contractSchema.functions.filter((func) => !isStellarViewFunction(func));
+}

package/src/sac/spec-cache.ts

@@ -0,0 +1,68 @@
+import type { xdr } from '@stellar/stellar-sdk';
+
+import { logger } from '@openzeppelin/ui-utils';
+
+import type { SacSpecSourceConfig } from './spec-source';
+import { fetchSacSpecJson, getSacSpecUrl } from './spec-source';
+import { encodeSacSpecEntries, toScSpecEntries } from './xdr';
+
+interface SacSpecCacheEntry {
+  base64Entries: string[];
+  specEntries: xdr.ScSpecEntry[];
+}
+
+const sacSpecCache = new Map<string, SacSpecCacheEntry>();
+const sacSpecInflight = new Map<string, Promise<SacSpecCacheEntry>>();
+
+/**
+ * Returns cached SAC spec artifacts (base64 and decoded entries) for the given source config.
+ * Ensures fetch/encode work is performed at most once per config.
+ */
+export async function getSacSpecArtifacts(
+  cfg: SacSpecSourceConfig = {}
+): Promise<SacSpecCacheEntry> {
+  const cacheKey = getSacSpecUrl(cfg);
+
+  const cached = sacSpecCache.get(cacheKey);
+  if (cached) {
+    logger.debug('stellar:sac:spec-cache', 'Returning cached SAC spec artifacts');
+    return cached;
+  }
+
+  const inflight = sacSpecInflight.get(cacheKey);
+  if (inflight) {
+    return inflight;
+  }
+
+  const promise = (async () => {
+    const json = await fetchSacSpecJson(cfg);
+    const base64Entries = await encodeSacSpecEntries(json);
+    const specEntries = toScSpecEntries(base64Entries);
+
+    const entry: SacSpecCacheEntry = {
+      base64Entries,
+      specEntries,
+    };
+
+    sacSpecCache.set(cacheKey, entry);
+    sacSpecInflight.delete(cacheKey);
+
+    logger.debug('stellar:sac:spec-cache', 'Cached SAC spec artifacts for future re-use');
+
+    return entry;
+  })().catch((error) => {
+    sacSpecInflight.delete(cacheKey);
+    throw error;
+  });
+
+  sacSpecInflight.set(cacheKey, promise);
+  return promise;
+}
+
+/**
+ * Clears cached SAC spec artifacts. Intended for test environments.
+ */
+export function clearSacSpecArtifactsCache(): void {
+  sacSpecCache.clear();
+  sacSpecInflight.clear();
+}

package/src/sac/spec-source.ts

@@ -0,0 +1,35 @@
+import { logger } from '@openzeppelin/ui-utils';
+
+export const DEFAULT_SPEC = {
+  repo: 'stellar/stellar-asset-contract-spec',
+  path: 'refs/heads/main',
+  file: 'stellar-asset-spec.json',
+};
+
+export interface SacSpecSourceConfig {
+  repo?: string;
+  path?: string;
+  file?: string;
+}
+
+export function getSacSpecUrl(cfg: SacSpecSourceConfig = {}): string {
+  const repo = cfg.repo || DEFAULT_SPEC.repo;
+  const path = cfg.path || DEFAULT_SPEC.path;
+  const file = cfg.file || DEFAULT_SPEC.file;
+  return `https://raw.githubusercontent.com/${repo}/${path}/${file}`;
+}
+
+/** Fetches the SAC JSON spec from GitHub raw. */
+export async function fetchSacSpecJson(cfg: SacSpecSourceConfig = {}): Promise<string> {
+  const url = getSacSpecUrl(cfg);
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    return await res.text();
+  } catch (error) {
+    logger.error('stellar:sac:spec-source', 'Failed to fetch SAC spec:', url, error);
+    throw new Error('Failed to load Stellar Asset Contract spec. Please try again later.');
+  }
+}

package/src/sac/xdr.ts

@@ -0,0 +1,101 @@
+import { xdr } from '@stellar/stellar-sdk';
+import stellarXdrJsonPackage from '@stellar/stellar-xdr-json/package.json' with { type: 'json' };
+import { parse, stringify } from 'lossless-json';
+
+import { logger } from '@openzeppelin/ui-utils';
+
+/**
+ * CDN URL for the stellar-xdr-json WASM module.
+ *
+ * Why CDN instead of bundling?
+ * 1. Vite bundling issues: The WASM file requires special handling in Vite. We tried multiple
+ *    approaches including vite-plugin-wasm, vite-plugin-top-level-await, ?url imports, and
+ *    various configurations, but consistently hit WebAssembly.instantiate errors where the
+ *    browser received HTML instead of the WASM binary (magic word 00 61 73 6d expected,
+ *    but got 3c 21 64 6f which is "<!do" in HTML).
+ * 2. Bundle size: The WASM file is ~3MB, which would significantly increase bundle size
+ *    for all users, even those who never use SAC contracts.
+ * 3. Dynamic loading: With CDN + dynamic imports, the WASM only loads when actually needed
+ *    (when a SAC contract is detected), keeping the initial bundle lean.
+ * 4. Simplicity: After trying complex Vite configurations and WASM plugins without success,
+ *    the CDN approach is simpler and more reliable.
+ *
+ * Trade-off: Requires internet connection for SAC contracts, but this is acceptable since
+ * SAC specs are already fetched from GitHub anyway.
+ */
+type PackageJson = { version?: string };
+
+const stellarXdrJsonVersion = (stellarXdrJsonPackage as PackageJson).version ?? '23.0.0';
+
+const CDN_WASM_URL = `https://unpkg.com/@stellar/stellar-xdr-json@${stellarXdrJsonVersion}/stellar_xdr_json_bg.wasm`;
+
+// Dynamically import the WASM module only when needed
+let initialized = false;
+let encode: ((type: string, value: string) => string) | null = null;
+
+/**
+ * Initializes the stellar-xdr-json WASM module for XDR encoding.
+ *
+ * This uses dynamic imports to only load the WASM when SAC contracts are actually used,
+ * avoiding the 3MB overhead for users who don't need SAC support.
+ *
+ * The WASM is loaded from CDN to keep bundle size minimal.
+ */
+export async function ensureXdrJsonInitialized(): Promise<void> {
+  if (initialized) return;
+
+  try {
+    // Dynamic import - only loads when SAC is actually used
+    const stellarXdrJson = await import('@stellar/stellar-xdr-json');
+    const init = stellarXdrJson.default;
+
+    // Load WASM from CDN
+    await init(CDN_WASM_URL);
+    encode = stellarXdrJson.encode;
+    initialized = true;
+  } catch (error) {
+    logger.error('stellar:sac:xdr', 'Failed to initialize WASM module:', error);
+    throw error;
+  }
+}
+
+/**
+ * Converts the SAC JSON spec content into Base64 XDR entries for ScSpecEntry[]
+ */
+export async function encodeSacSpecEntries(jsonString: string): Promise<string[]> {
+  await ensureXdrJsonInitialized();
+
+  if (!encode) {
+    throw new Error('WASM module not properly initialized');
+  }
+
+  try {
+    const jsonData = parse(jsonString) as unknown[];
+    const result: string[] = [];
+    for (const entry of jsonData) {
+      const stringified = stringify(entry);
+      if (!stringified) {
+        throw new Error('Failed to stringify SAC spec entry before XDR encoding.');
+      }
+      const encoded = encode('ScSpecEntry', stringified);
+      result.push(encoded);
+    }
+    return result;
+  } catch (error) {
+    logger.error('stellar:sac:xdr', 'Failed to encode SAC spec to XDR', error);
+    throw new Error('Failed to process SAC spec.');
+  }
+}
+
+/** Utility to convert base64 strings to xdr.ScSpecEntry[] */
+export function toScSpecEntries(base64Entries: string[]): xdr.ScSpecEntry[] {
+  return base64Entries.map((b64) => xdr.ScSpecEntry.fromXDR(b64, 'base64'));
+}
+
+/**
+ * Reset the initialization state (mainly for testing)
+ */
+export function resetXdrInitialization(): void {
+  initialized = false;
+  encode = null;
+}

package/src/transaction/components/AdvancedInfo.tsx

@@ -0,0 +1,34 @@
+import { Info } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@openzeppelin/ui-components';
+
+interface AdvancedInfoProps {
+  showAdvancedInfo: boolean;
+  onToggle: () => void;
+}
+
+export const AdvancedInfo: React.FC<AdvancedInfoProps> = ({ showAdvancedInfo, onToggle }) => {
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between">
+        <label className="text-base font-medium">Stellar Transaction Configuration</label>
+        <Button variant="ghost" size="sm" onClick={onToggle} className="text-xs" type="button">
+          <Info className="h-3 w-3 mr-1" />
+          Stellar Options
+        </Button>
+      </div>
+
+      {showAdvancedInfo && (
+        <div className="mt-3 rounded-lg bg-muted/30 p-4">
+          <p className="text-sm text-muted-foreground leading-relaxed">
+            Configure Stellar-specific transaction parameters: <strong>maxFee</strong> sets the
+            maximum fee in stroops you&apos;re willing to pay, <strong>validUntil</strong> sets
+            transaction expiration, and <strong>feeBump</strong> enables automatic fee increases for
+            stuck transactions.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+};