@openzeppelin/adapter-stellar 1.0.0

package/src/mapping/type-coverage-validator.ts

@@ -0,0 +1,151 @@
+import type { FieldType } from '@openzeppelin/ui-types';
+import { logger } from '@openzeppelin/ui-utils';
+
+import { STELLAR_TYPE_TO_FIELD_TYPE } from './constants';
+import { mapStellarParameterTypeToFieldType } from './type-mapper';
+
+/**
+ * Known Stellar/Soroban types that should have explicit mappings
+ * This list should be updated when new types are added to the Stellar SDK
+ */
+export const KNOWN_STELLAR_TYPES = [
+  // Primitives
+  'Val',
+  'Bool',
+  'Void',
+  'Error',
+  'U32',
+  'I32',
+  'U64',
+  'I64',
+  'U128',
+  'I128',
+  'U256',
+  'I256',
+  'Timepoint',
+  'Duration',
+
+  // Strings & Bytes
+  'ScString',
+  'ScSymbol',
+  'Bytes',
+
+  // Addresses
+  'Address',
+  'MuxedAddress',
+
+  // Note: Vec, Map, Tuple, Option, Result, BytesN are handled dynamically
+] as const;
+
+/**
+ * Validate that all known Stellar types have appropriate field type mappings
+ */
+export function validateTypeMappingCompleteness(): {
+  success: boolean;
+  missing: string[];
+  warnings: string[];
+} {
+  const missing: string[] = [];
+  const warnings: string[] = [];
+
+  // Check explicit mappings
+  for (const stellarType of KNOWN_STELLAR_TYPES) {
+    if (!STELLAR_TYPE_TO_FIELD_TYPE[stellarType]) {
+      // Try the dynamic mapper
+      try {
+        const fieldType = mapStellarParameterTypeToFieldType(stellarType);
+        if (
+          fieldType === 'text' &&
+          !stellarType.includes('String') &&
+          !stellarType.includes('Symbol')
+        ) {
+          warnings.push(
+            `Type "${stellarType}" defaults to 'text' - consider adding explicit mapping`
+          );
+        }
+      } catch {
+        missing.push(stellarType);
+        logger.warn('validateTypeMappingCompleteness', `No mapping for type: ${stellarType}`);
+      }
+    }
+  }
+
+  // Validate field type consistency
+  const fieldTypes = Object.values(STELLAR_TYPE_TO_FIELD_TYPE) as FieldType[];
+  const validFieldTypes: FieldType[] = [
+    'text',
+    'number',
+    'textarea',
+    'checkbox',
+    'select',
+    'radio',
+    'blockchain-address',
+    'object',
+    'array',
+    'array-object',
+  ];
+
+  for (const fieldType of fieldTypes) {
+    if (!validFieldTypes.includes(fieldType)) {
+      warnings.push(`Unknown field type used: ${fieldType}`);
+    }
+  }
+
+  const success = missing.length === 0;
+
+  if (!success) {
+    logger.error('validateTypeMappingCompleteness', 'Missing type mappings found!', {
+      missing,
+      warnings,
+      knownTypesCount: KNOWN_STELLAR_TYPES.length,
+      explicitMappingsCount: Object.keys(STELLAR_TYPE_TO_FIELD_TYPE).length,
+    });
+  }
+
+  return { success, missing, warnings };
+}
+
+/**
+ * Runtime type discovery - tracks types encountered during contract loading
+ */
+class TypeTracker {
+  private encounteredTypes = new Set<string>();
+  private missedTypes = new Set<string>();
+
+  trackType(type: string, wasHandled: boolean) {
+    this.encounteredTypes.add(type);
+    if (!wasHandled) {
+      this.missedTypes.add(type);
+    }
+  }
+
+  getReport() {
+    return {
+      totalTypes: this.encounteredTypes.size,
+      encounteredTypes: Array.from(this.encounteredTypes).sort(),
+      missedTypes: Array.from(this.missedTypes).sort(),
+      coveragePercentage:
+        ((this.encounteredTypes.size - this.missedTypes.size) / this.encounteredTypes.size) * 100,
+    };
+  }
+
+  reset() {
+    this.encounteredTypes.clear();
+    this.missedTypes.clear();
+  }
+}
+
+export const globalTypeTracker = new TypeTracker();
+
+// Auto-validate on module load in development
+if (process.env.NODE_ENV === 'development') {
+  const validation = validateTypeMappingCompleteness();
+  if (validation.warnings.length > 0) {
+    console.warn('🟡 Stellar Type Mapping Warnings:', validation.warnings);
+  }
+  if (!validation.success) {
+    console.error('🔴 Stellar Type Mapping Validation Failed:', validation);
+  } else {
+    console.log('✅ Stellar Type Mapping Validation Passed');
+  }
+}

package/src/mapping/type-mapper.ts

@@ -0,0 +1,203 @@
+import type { FieldType } from '@openzeppelin/ui-types';
+
+import { isBytesNType, isLikelyEnumType } from '../utils/type-detection';
+import { STELLAR_TYPE_TO_FIELD_TYPE } from './constants';
+
+/**
+ * Map a Stellar-specific parameter type to a default form field type.
+ * @param parameterType The Stellar parameter type (e.g., 'U128', 'Address', 'Vec<U32>')
+ * @returns The appropriate default form field type (e.g., 'number', 'blockchain-address', 'array')
+ */
+export function mapStellarParameterTypeToFieldType(parameterType: string): FieldType {
+  // Check if this is a Vec of custom/complex types (e.g., Vec<CustomStruct>)
+  const vecComplexMatch = parameterType.match(/^Vec<([^>]+)>$/);
+  if (vecComplexMatch) {
+    const innerType = vecComplexMatch[1];
+    // If inner type is not a primitive, treat as array of objects
+    if (!STELLAR_TYPE_TO_FIELD_TYPE[innerType]) {
+      return 'array-object';
+    }
+    return 'array';
+  }
+
+  // Check if this is a simple Vec type
+  if (parameterType === 'Vec' || parameterType.startsWith('Vec<')) {
+    return 'array';
+  }
+
+  // Check if this is a Map type
+  if (parameterType === 'Map' || parameterType.startsWith('Map<')) {
+    return 'map' as FieldType;
+  }
+
+  // Extract base type for generic types (e.g., Option<U32> -> U32)
+  const genericMatch = parameterType.match(/^(\w+)<(.+)>$/);
+  if (genericMatch) {
+    const baseType = genericMatch[1];
+    // For Option and Result types, use the inner type
+    if (baseType === 'Option' || baseType === 'Result') {
+      const innerType = genericMatch[2];
+      return mapStellarParameterTypeToFieldType(innerType);
+    }
+  }
+
+  // Map known Stellar/Soroban types to appropriate field types
+  const mappedType = STELLAR_TYPE_TO_FIELD_TYPE[parameterType];
+  if (mappedType) {
+    return mappedType;
+  }
+
+  // Handle BytesN types (fixed-size byte arrays like BytesN<32> for hashes)
+  if (isBytesNType(parameterType)) {
+    return 'bytes';
+  }
+
+  // Handle custom types (structs, enums) - default to object unless it's clearly an enum
+  if (isLikelyEnumType(parameterType)) {
+    return 'select';
+  }
+
+  // Check if this looks like a custom struct (capitalized name and not a known primitive)
+  if (parameterType[0] && parameterType[0] === parameterType[0].toUpperCase()) {
+    // Check if it's not a known Stellar primitive type that starts with uppercase
+    const knownUppercaseTypes = [
+      'U32',
+      'U64',
+      'U128',
+      'U256',
+      'I32',
+      'I64',
+      'I128',
+      'I256',
+      'Bool',
+      'Bytes',
+    ];
+    if (
+      !knownUppercaseTypes.includes(parameterType) &&
+      !parameterType.startsWith('Vec') &&
+      !parameterType.startsWith('Map') &&
+      !parameterType.includes('Unknown')
+    ) {
+      // Don't treat Unknown* as structs
+      return 'object';
+    }
+  }
+
+  // Final fallback to text for truly unknown types
+  return 'text';
+}
+
+/**
+ * Get field types compatible with a specific parameter type.
+ * @param parameterType The Stellar parameter type.
+ * @returns Array of compatible form field types.
+ */
+export function getStellarCompatibleFieldTypes(parameterType: string): FieldType[] {
+  // Handle Vec of complex types
+  const vecComplexMatch = parameterType.match(/^Vec<([^>]+)>$/);
+  if (vecComplexMatch) {
+    const innerType = vecComplexMatch[1];
+    if (!STELLAR_TYPE_TO_FIELD_TYPE[innerType]) {
+      return ['array-object', 'textarea', 'text'];
+    }
+    return ['array', 'textarea', 'text'];
+  }
+
+  if (isBytesNType(parameterType)) {
+    return ['bytes', 'textarea', 'text'];
+  }
+
+  // Handle Vec types - allow array field or fallback to textarea/text
+  if (parameterType === 'Vec' || parameterType.startsWith('Vec<')) {
+    return ['array', 'textarea', 'text'];
+  }
+
+  // Handle Map types
+  if (parameterType === 'Map' || parameterType.startsWith('Map<')) {
+    return ['map' as FieldType, 'textarea', 'text'];
+  }
+
+  // Handle generic types
+  const genericMatch = parameterType.match(/^(\w+)<(.+)>$/);
+  if (genericMatch) {
+    const baseType = genericMatch[1];
+    if (baseType === 'Option' || baseType === 'Result') {
+      const innerType = genericMatch[2];
+      return getStellarCompatibleFieldTypes(innerType);
+    }
+  }
+
+  // Define compatibility map for known types
+  const compatibilityMap: Record<string, FieldType[]> = {
+    Address: ['blockchain-address', 'text'],
+
+    // Unsigned integers
+    U32: ['number', 'amount', 'text'],
+    U64: ['bigint', 'number', 'amount', 'text'],
+    U128: ['bigint', 'number', 'amount', 'text'],
+    U256: ['bigint', 'number', 'amount', 'text'],
+
+    // Signed integers
+    I32: ['number', 'amount', 'text'],
+    I64: ['bigint', 'number', 'text'],
+    I128: ['bigint', 'number', 'text'],
+    I256: ['bigint', 'number', 'text'],
+
+    // Boolean
+    Bool: ['checkbox', 'select', 'radio', 'text'],
+
+    // String types
+    ScString: ['text', 'textarea', 'email', 'password'],
+    ScSymbol: ['text', 'textarea'],
+
+    // Byte types
+    Bytes: ['bytes', 'textarea', 'text'],
+    DataUrl: ['bytes', 'textarea', 'text'],
+    // BytesN types like BytesN<32> for hashes
+    'BytesN<32>': ['bytes', 'textarea', 'text'],
+
+    // Complex types
+    Tuple: ['object', 'textarea', 'text'],
+    Instance: ['object', 'textarea', 'text'],
+  };
+
+  // Check if we have a specific compatibility mapping
+  const compatibleTypes = compatibilityMap[parameterType];
+  if (compatibleTypes) {
+    return compatibleTypes;
+  }
+
+  // Handle enums
+  if (isLikelyEnumType(parameterType)) {
+    return ['enum', 'select', 'radio', 'text'];
+  }
+
+  // Handle custom types (assumed to be structs)
+  if (parameterType[0] && parameterType[0] === parameterType[0].toUpperCase()) {
+    // Check if it's not a known Stellar primitive type that starts with uppercase
+    const knownUppercaseTypes = [
+      'U32',
+      'U64',
+      'U128',
+      'U256',
+      'I32',
+      'I64',
+      'I128',
+      'I256',
+      'Bool',
+      'Bytes',
+    ];
+    if (
+      !knownUppercaseTypes.includes(parameterType) &&
+      !parameterType.startsWith('Vec') &&
+      !parameterType.startsWith('Map') &&
+      !parameterType.includes('Unknown')
+    ) {
+      // Don't treat Unknown* as structs
+      return ['object', 'textarea', 'text'];
+    }
+  }
+
+  // Default fallback for truly unknown types
+  return ['text'];
+}

package/src/metadata.ts

@@ -0,0 +1,16 @@
+import { NetworkStellar } from '@web3icons/react';
+
+import type { EcosystemMetadata } from '@openzeppelin/ui-types';
+
+export const ecosystemMetadata: EcosystemMetadata = {
+  id: 'stellar',
+  name: 'Stellar',
+  description:
+    'Stellar is a fast, energy-efficient blockchain network designed for real-world financial applications. It enables near-instant global payments at low cost, connects digital assets to traditional finance, and supports smart contracts through Soroban.',
+  explorerGuidance: 'contract IDs on Stellar Expert',
+  addressExample: 'GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG',
+  iconComponent: NetworkStellar,
+  bgColorClass: 'bg-sky-100',
+  textColorClass: 'text-sky-900',
+  defaultFeatureConfig: { enabled: true, showInUI: true },
+};

package/src/networks/README.md

@@ -0,0 +1,84 @@
+# Stellar Adapter Networks
+
+This directory defines the Stellar network configurations exported by the adapter.
+
+## Available Networks
+
+Exports from `index.ts`:
+
+- `stellarPublic` (mainnet)
+- `stellarTestnet` (testnet)
+- `stellarMainnetNetworks`: `StellarNetworkConfig[]` containing all mainnet networks
+- `stellarTestnetNetworks`: `StellarNetworkConfig[]` containing all testnet networks
+- `stellarNetworks`: union of all supported networks
+
+Each `StellarNetworkConfig` includes:
+
+- `id`: Unique identifier (e.g., `"stellar-public"`, `"stellar-testnet"`)
+- `name`: Display name
+- `ecosystem`: `"stellar"`
+- `network`: `"stellar"`
+- `type`: `"mainnet" | "testnet"`
+- `isTestnet`: boolean
+- `horizonUrl`: Horizon REST URL
+- `sorobanRpcUrl`: Soroban JSON-RPC URL
+- `networkPassphrase`: Network passphrase
+- `explorerUrl`: Base explorer URL (for display links)
+- `icon`: Icon identifier
+
+## Soroban RPC URL Overrides
+
+You can override the default `sorobanRpcUrl` at runtime through `AppConfigService`.
+
+In `.env` (Builder app):
+`VITE_APP_CFG_RPC_ENDPOINT_STELLAR_TESTNET="https://your-custom-soroban-rpc.testnet.example"`
+
+In `public/app.config.json` (exported apps):
+
+```json
+{
+  "rpcEndpoints": {
+    "stellar-testnet": "https://your-custom-soroban-rpc.testnet.example",
+    "stellar-public": "https://your-custom-soroban-rpc.public.example"
+  }
+}
+```
+
+Resolution order used by the adapter:
+
+1. User RPC from `UserRpcConfigService`
+2. `AppConfigService.getRpcEndpointOverride(networkId)`
+3. Default `sorobanRpcUrl` from the network config
+
+## Adding a New Stellar Network
+
+1. Add the network to `mainnet.ts` or `testnet.ts`:
+
+```typescript
+export const stellarCustom: StellarNetworkConfig = {
+  id: 'stellar-custom',
+  exportConstName: 'stellarCustom',
+  name: 'Stellar Custom',
+  ecosystem: 'stellar',
+  network: 'stellar',
+  type: 'testnet',
+  isTestnet: true,
+  horizonUrl: 'https://horizon.custom.example',
+  sorobanRpcUrl: 'https://soroban.custom.example',
+  networkPassphrase: 'Custom Network Passphrase',
+  explorerUrl: 'https://stellar.expert/explorer/custom',
+  iconComponent: NetworkStellarCustom,
+};
+```
+
+1. Include it in the appropriate array and export it from `index.ts`.
+2. Re-export from the package root in `src/index.ts` if you want it available to consumers.
+
+## Explorer URLs
+
+Explorers are used for display only. The adapter builds links using `explorerUrl`:
+
+- Address or contract: `.../account/{address}` or `.../contract/{id}`
+- Transaction: `.../tx/{hash}`
+
+No explorer API keys are required for Stellar adapter functionality.

package/src/networks/index.ts

@@ -0,0 +1,19 @@
+import { StellarNetworkConfig } from '@openzeppelin/ui-types';
+
+import { stellarPublic } from './mainnet';
+import { stellarTestnet } from './testnet';
+
+// All mainnet networks
+export const stellarMainnetNetworks: StellarNetworkConfig[] = [stellarPublic];
+
+// All testnet networks
+export const stellarTestnetNetworks: StellarNetworkConfig[] = [stellarTestnet];
+
+// All Stellar networks
+export const stellarNetworks: StellarNetworkConfig[] = [
+  ...stellarMainnetNetworks,
+  ...stellarTestnetNetworks,
+];
+
+// Export individual networks as well
+export { stellarPublic, stellarTestnet };

package/src/networks/mainnet.ts

@@ -0,0 +1,20 @@
+import { NetworkStellar } from '@web3icons/react';
+
+import { StellarNetworkConfig } from '@openzeppelin/ui-types';
+
+// Stellar Public Network (Mainnet)
+export const stellarPublic: StellarNetworkConfig = {
+  id: 'stellar-public',
+  exportConstName: 'stellarPublic',
+  name: 'Stellar',
+  ecosystem: 'stellar',
+  network: 'stellar',
+  type: 'mainnet',
+  isTestnet: false,
+  horizonUrl: 'https://horizon.stellar.org',
+  sorobanRpcUrl: 'https://mainnet.sorobanrpc.com',
+  networkPassphrase: 'Public Global Stellar Network ; September 2015',
+  explorerUrl: 'https://stellar.expert/explorer/public',
+  iconComponent: NetworkStellar,
+  accessControlIndexerUrl: 'https://openzeppelin-stellar-mainnet.graphql.subquery.network',
+};

package/src/networks/testnet.ts

@@ -0,0 +1,20 @@
+import { NetworkStellar } from '@web3icons/react';
+
+import { StellarNetworkConfig } from '@openzeppelin/ui-types';
+
+// Stellar Testnet
+export const stellarTestnet: StellarNetworkConfig = {
+  id: 'stellar-testnet',
+  exportConstName: 'stellarTestnet',
+  name: 'Stellar Testnet',
+  ecosystem: 'stellar',
+  network: 'stellar',
+  type: 'testnet',
+  isTestnet: true,
+  horizonUrl: 'https://horizon-testnet.stellar.org',
+  sorobanRpcUrl: 'https://soroban-testnet.stellar.org',
+  networkPassphrase: 'Test SDF Network ; September 2015',
+  explorerUrl: 'https://stellar.expert/explorer/testnet',
+  iconComponent: NetworkStellar,
+  accessControlIndexerUrl: 'https://openzeppelin-stellar-testnet.graphql.subquery.network',
+};

package/src/networks.ts

@@ -0,0 +1,2 @@
+export * from './networks/index';
+export { stellarNetworks as networks } from './networks/index';