GLEECBTC · CharlVS · Apr 2, 2026
diff --git a/packages/komodo_defi_framework/README.md b/packages/komodo_defi_framework/README.md
@@ -103,6 +103,11 @@ flutter:
 
 You can customize sources and checksums via `app_build/build_config.json` in this package. See `packages/komodo_wallet_build_transformer/README.md` for CLI flags, environment variables, and troubleshooting.
 
+On macOS, the build pipeline accepts both release-style static archives
+(`libkdf-macos-universal2-<hash>.zip`) and CI-style executable archives
+(`kdf-macos-universal2-<hash>.zip`). The transformer normalizes them into the
+package layout consumed by the plugin podspec before Xcode builds.
+
 ## Web (WASM)
 
 On Web, the plugin registers a WASM implementation automatically (see `lib/web/kdf_plugin_web.dart`). The WASM bundle and bootstrap scripts are provided via the build transformer.

diff --git a/packages/komodo_defi_framework/app_build/BUILD_CONFIG_README.md b/packages/komodo_defi_framework/app_build/BUILD_CONFIG_README.md
@@ -12,6 +12,7 @@ This directory contains the artifact configuration used by `komodo_wallet_build_
 - `api.api_commit_hash` – commit hash of the KDF artifacts to fetch
 - `api.source_urls` – list of base URLs to download from (GitHub API, CDN)
 - `api.platforms.*.matching_pattern` – regex to match artifact names per platform
+- `api.platforms.*.matching_preference` – preferred filename substrings when multiple artifacts match
 - `api.platforms.*.valid_zip_sha256_checksums` – allow-list of artifact checksums
 - `api.platforms.*.path` – destination relative to artifact output package
 - `coins.bundled_coins_repo_commit` – commit of Komodo coins registry
@@ -28,6 +29,18 @@ Artifacts are downloaded into the package specified by the transformer flag:
 
 Paths in the config are relative to that package directory.
 
+### macOS canonical layout
+
+The transformer normalizes any compatible macOS archive into a single package
+layout before marking it current:
+
+- executable builds: `macos/bin/kdf`
+- dynamic library builds: `macos/lib/libkdflib.dylib`
+- static library builds: `macos/Frameworks/libkdflib.a`
+
+GitHub release artifacts are tried first. Mirror artifacts are only accepted
+after checksum validation and canonical-layout normalization succeed.
+
 ## Updating artifacts
 
 1. Update `api_commit_hash` and (optionally) checksums
@@ -53,6 +66,9 @@ Paths in the config are relative to that package directory.
 ```
 
 - The downloader expects branch-scoped directory listings (e.g., `.../dev/`) on both devbuilds and Nebula mirrors and will fallback to the base listing when available. It searches for artifacts that match the platform patterns and contain either the full commit hash or a 7-char short hash.
+- For macOS, keep all accepted archive checksums for a commit in the
+  checksum allow-list when both release (`libkdf-*`) and mirror/CI
+  (`kdf-*`) archives should be usable.
 - To pin a specific commit (e.g., `4025b8c`) without changing branches, update `api.api_commit_hash` or use the CLI with `--commit`:
 
 ```bash

diff --git a/packages/komodo_defi_framework/app_build/build_config.json b/packages/komodo_defi_framework/app_build/build_config.json
@@ -26,9 +26,16 @@
       },
       "macos": {
         "matching_pattern": "^(?:kdf-macos-universal2-[a-f0-9]{7,40}|kdf_[a-f0-9]{7,40}-mac-universal|libkdf-macos-universal2-[a-f0-9]{7,40})\\.zip$",
-        "matching_preference": ["universal2", "mac-arm64"],
+        "matching_preference": [
+          "libkdf-macos-universal2",
+          "kdf-macos-universal2",
+          "kdf_",
+          "universal2",
+          "mac-arm64"
+        ],
         "valid_zip_sha256_checksums": [
-          "14a1473d46706fdfbd04d18939994b686016a126e4dc2cb8937d00f5645b8773"
+          "14a1473d46706fdfbd04d18939994b686016a126e4dc2cb8937d00f5645b8773",
+          "61ed5295dfc7acfb962a976e915c0909a300f15552a3d1ae64b737f3add8a39d"
         ],
         "path": "macos/bin"
       },

diff --git a/packages/komodo_defi_framework/lib/src/native/kdf_executable_finder.dart b/packages/komodo_defi_framework/lib/src/native/kdf_executable_finder.dart
@@ -34,6 +34,9 @@ class KdfExecutableFinder {
   /// Attempts to find the KDF executable in standard and platform-specific
   /// locations
   Future<File?> findExecutable({String executableName = 'kdf'}) async {
+    // Executable-based macOS builds copy kdf into the framework Helpers
+    // directory. Static-library builds do not populate this path and instead
+    // rely on DynamicLibrary.process()/executable() resolution.
     final macosHelpersInFrameworkPath = p.joinAll([
       p.dirname(p.dirname(Platform.resolvedExecutable)),
       'Frameworks',
@@ -73,8 +76,9 @@ class KdfExecutableFinder {
       }
     }
 
+    final searchedPaths = files.map((e) => e.absolute.path).join('\n');
     logCallback(
-      'Executable not found in paths: ${files.map((e) => e.absolute.path).join('\n')}. '
+      'Executable not found in paths: $searchedPaths. '
       'If you are using the KDF Flutter SDK, open an issue on GitHub.',
     );
 

diff --git a/packages/komodo_defi_framework/lib/src/operations/kdf_operations_native.dart b/packages/komodo_defi_framework/lib/src/operations/kdf_operations_native.dart
@@ -365,6 +365,10 @@ ffi.DynamicLibrary _loadLibrary() {
 
 List<String> _getLibraryPaths() {
   if (Platform.isMacOS) {
+    // macOS supports three packaging modes:
+    // - a bundled kdf executable copied into the framework Helpers directory
+    // - a bundled libkdflib.dylib
+    // - a force-loaded libkdflib.a, resolved via PROCESS/EXECUTABLE symbols
     return ['kdf', 'mm2', 'libkdflib.dylib', 'PROCESS', 'EXECUTABLE'];
   } else if (Platform.isIOS) {
     return ['libkdflib.dylib', 'PROCESS', 'EXECUTABLE'];

diff --git a/packages/komodo_defi_framework/macos/komodo_defi_framework.podspec b/packages/komodo_defi_framework/macos/komodo_defi_framework.podspec
@@ -1,3 +1,6 @@
+has_static_library = File.exist?('Frameworks/libkdflib.a')
+has_dynamic_library = File.exist?('lib/libkdflib.dylib')
+
 Pod::Spec.new do |s|
   s.name             = 'komodo_defi_framework'
   s.version          = '0.0.1'
@@ -15,11 +18,17 @@ A new Flutter FFI plugin project.
   s.source_files = 'Classes/**/*'
   s.dependency 'FlutterMacOS'
 
-  s.resource_bundles = {
-    'kdf_resources' => ['lib/*.dylib'].select { |f| Dir.exist?(File.dirname(f)) }
-  }
+  if has_dynamic_library
+    s.resource_bundles = {
+      'kdf_resources' => ['lib/*.dylib']
+    }
+  end
 
-  # s.preserve_paths = ['bin/kdf']
+  if has_static_library
+    s.vendored_libraries = ['Frameworks/libkdflib.a']
+  end
+
+  s.preserve_paths = ['bin/kdf', 'lib/libkdflib.dylib', 'Frameworks/libkdflib.a']
 
   s.script_phase = {
     :name => 'Install kdf executable and/or dylib',
@@ -55,6 +64,13 @@ A new Flutter FFI plugin project.
       else
         echo "Warning: libkdflib.dylib not found in lib/libkdflib.dylib"
       fi
+
+      if [ -f "${PODS_TARGET_SRCROOT}/Frameworks/libkdflib.a" ]; then
+        echo "Static libkdflib.a found, linking through CocoaPods vendored_libraries"
+        FOUND_REQUIRED_FILE=1
+      else
+        echo "Warning: libkdflib.a not found in Frameworks/libkdflib.a"
+      fi
 
       # Prune binary slices to match $ARCHS (preserve universals) in Release builds only
       case "$CONFIGURATION" in
@@ -125,20 +141,31 @@ A new Flutter FFI plugin project.
       if [ -f "$APP_SUPPORT_DIR/kdf" ]; then cp "$APP_SUPPORT_DIR/kdf" "$HELPERS_DIR/kdf"; fi
       code_sign_if_enabled "$FRAMEWORKS_DIR/libkdflib.dylib" || true
 
-      # Fail if neither file was found
+      # Static-library builds rely on vendored_libraries/force_load and
+      # DynamicLibrary.process() at runtime, so there is nothing to copy/sign.
       if [ $FOUND_REQUIRED_FILE -eq 0 ]; then
-        echo "Error: Neither kdf executable nor libkdflib.dylib was found. At least one is required."
+        echo "Error: No compatible macOS KDF artefact was found."
+        echo "Expected one of:"
+        echo "  - bin/kdf"
+        echo "  - lib/libkdflib.dylib"
+        echo "  - Frameworks/libkdflib.a"
         exit 1
       fi
     SCRIPT
   }
 
   # Configuration for macOS build
+  other_ldflags = if has_static_library
+                    '-force_load $(PODS_TARGET_SRCROOT)/Frameworks/libkdflib.a -lstdc++ -framework SystemConfiguration'
+                  else
+                    '-framework SystemConfiguration'
+                  end
+
   s.pod_target_xcconfig = {
     'DEFINES_MODULE' => 'YES',
     # Allow building universal macOS apps (arm64 + x86_64). i386 remains excluded by default Xcode settings.
-    'OTHER_LDFLAGS' => '-framework SystemConfiguration',
-    # Add rpath to ensure dylib can be found at runtime
+    'OTHER_LDFLAGS' => other_ldflags,
+    # Add rpath to ensure dylib can be found at runtime when the dynamic artefact is used.
     'LD_RUNPATH_SEARCH_PATHS' => [
       '$(inherited)',
       '@executable_path/../Frameworks',

diff --git a/packages/komodo_defi_framework/macos/komodo_defi_framework.podspec.staticlib b/packages/komodo_defi_framework/macos/komodo_defi_framework.podspec.staticlib
diff --git a/packages/komodo_wallet_build_transformer/README.md b/packages/komodo_wallet_build_transformer/README.md
@@ -37,6 +37,17 @@ flutter:
 
 Artifacts and checksums are configured in `packages/komodo_defi_framework/app_build/build_config.json`.
 
+For macOS, the transformer normalizes compatible archives into a canonical
+layout before they are marked current:
+
+- `bin/kdf` for executable builds
+- `lib/libkdflib.dylib` for dynamic-library builds
+- `Frameworks/libkdflib.a` for static-library builds
+
+GitHub release assets remain the primary source. Mirror/CI assets are accepted
+only when they match the requested commit, pass checksum validation, and
+normalize into one of the supported macOS layouts.
+
 ## CLI
 
 You can run the transformer directly for local testing: