ObsidianDragon/docs/lite-wallet-backend-artifact-link-contract-2026-05-18.md

Lite Wallet Backend Artifact Link Contract - 2026-05-18

Phase 1 Decision

The first production backend path is an explicitly configured imported CMake library. Runtime dynamic loading remains a Phase 2 bridge-runtime-owner task. External executable bridge mode is not part of the Phase 1 production contract.

The default build remains unchanged: DRAGONX_ENABLE_LITE_BACKEND=OFF. Full-node builds do not require Rust, SDXL, or lite backend artifacts.

CMake Gate

The enabled lite backend path requires:

• DRAGONX_BUILD_LITE=ON
• DRAGONX_ENABLE_LITE_BACKEND=ON
• DRAGONX_LITE_BACKEND_LIBRARY=<path to static or shared library>
• DRAGONX_LITE_BACKEND_SYMBOLS_FILE=<path to generated symbol inventory>
• DRAGONX_LITE_BACKEND_LINK_MODE=imported
• DRAGONX_LITE_BACKEND_ABI=sdxl-c-v1
• DRAGONX_LITE_BACKEND_REQUIRE_SIGNATURE=ON only when a release builder wants CMake to require verified signature metadata in the manifest
• DRAGONX_LITE_BACKEND_EXTRA_LIBS=<verified platform extras> only when a platform linker proves additional backend-native dependencies are required

When those values are accepted, CMake imports the library as dragonx_lite_backend and links it into ObsidianDragonLite. No runtime dynamic loading is attempted by this Phase 1 contract.

DRAGONX_LITE_BACKEND_MANIFEST=<path to generated artifact manifest> is optional, but if supplied it must exist. The symbol inventory is mandatory so enabled backend builds fail closed before link-time or runtime when the artifact does not expose the expected C ABI. If DRAGONX_LITE_BACKEND_REQUIRE_SIGNATURE=ON, the manifest becomes mandatory and CMake rejects it unless the read-only signature metadata is verified and matches the artifact SHA-256.

DRAGONX_LITE_BACKEND_EXTRA_LIBS is intentionally a cache string instead of hardcoded platform guesses. Release builders should keep it empty for platforms that link successfully with the imported artifact and existing app/system libraries, and should document any non-empty value next to the platform artifact manifest that required it.

Artifact Production

scripts/build-lite-backend-artifact.sh builds or inventories the SDXL-compatible backend artifact and writes:

• the copied backend library artifact,
• lite-backend-symbols.txt, one exported symbol per line,
• lite-backend-artifact-manifest.json, including SHA-256, byte size, source revisions, builder label, ABI, platform, and provenance facts.

See docs/lite-wallet-backend-artifact-production-2026-05-18.md for platform commands and the no-build inventory mode.

The relative backend source layout and signature metadata boundary are recorded in docs/lite-wallet-backend-source-signature-plan-2026-05-20.md. The maintained dependency source is now vendored under external/SilentDragonXLite/silentdragonxlite-cli, and the wrapper uses silentdragonxlitelib = { path = "../silentdragonxlite-cli/lib" }. The portable override remains available for comparison against an external checkout, but release verification should move to the relative source layout. Signature metadata is read-only verification inventory under docs/lite-wallet-backend-signing-policy-2026-05-22.md; signing itself stays outside CMake, runtime code, and Phase 1 artifact production.

Platform Artifact Status

As of 2026-05-22, artifact production has moved past local Linux proof into clean-builder reproducibility and imported-link checks:

• Linux static artifact production is reproducible when built with --reproducible, an isolated --cargo-target-dir, and a remap for the current external silentdragonxlitelib path. Two clean Linux builds produced byte-identical archives with SHA-256 12228f5b895db6cdafb0f643ecb5fbad1a3760b57b7fe98d7084a34644f34622.
• Windows GNU static artifact production is reproducible on this host with x86_64-pc-windows-gnu and MinGW tools. Two clean Windows builds produced byte-identical archives with SHA-256 bdf1e0175a89560d15232f6430d162c6c009806e048062c124ec40c0744e49be.
• The artifact script now has a portable dependency override through --silentdragonxlitelib-dir, which prepares a generated backend wrapper under the output directory and records the override in artifact provenance instead of relying on the local absolute dependency path in the checked-in wrapper manifest.
• Clean Linux and Windows GNU builds using --silentdragonxlitelib-dir /home/d/external/silentdragonxlite-cli/lib are reproducible. The portable Linux archive SHA-256 is aaef46b99fdc304be88427852797d6674ac330209b377be5447c1b0805635ea2; the portable Windows GNU archive SHA-256 is 635a9e9bf3254955e63d1e9032e714488fa433cc249c8aabe636b5f18d2d1e3b.
• The checked-in backend source now carries the relative silentdragonxlitelib layout. A Linux build without --silentdragonxlitelib-dir produced build/lite-backend-relative-linux-b/linux/libsilentdragonxlite.a with SHA-256 8fd6c66ff661e13f768754de69d39e1a15ee55b6fdd530625a6018c867edde10; its manifest records portable_dependency_override: false, silentdragonxlitelib_revision: 6a178c8d08d9c1c153fb22759a68177cdb787be7, reproducible: true, and signing_requested: false.
• Windows GNU clean builds from the checked-in relative source layout are reproducible. Two clean builds produced byte-identical build/lite-backend-relative-windows-gnu-a/windows/libsilentdragonxlite.a and build/lite-backend-relative-windows-gnu-b/windows/libsilentdragonxlite.a archives with SHA-256 ca7677af58f61de4bd56311e76e32961d977da8fac2a3c5d158c1702f8807439; both manifests record portable_dependency_override: false, silentdragonxlitelib_revision: 6a178c8d08d9c1c153fb22759a68177cdb787be7, rust_target: x86_64-pc-windows-gnu, reproducible: true, and signing_requested: false.
• The portable Linux artifact was accepted by CMake in build/lite-backend-portable-verify, linked into ObsidianDragonTests, and the focused suite printed Focused service tests passed. The same artifact also linked into the ObsidianDragon app target with DRAGONX_LITE_BACKEND_EXTRA_LIBS empty, producing build/lite-backend-portable-verify/bin/ObsidianDragonLite for inspection without launch.
• Windows GNU imported app linking is verified for the portable artifact from /tmp/od-win-lite-link. The first no-extra link proved missing AcquireCredentialsHandleA, FreeCredentialsHandle, FreeContextBuffer, and GetUserProfileDirectoryW; the successful builder value is DRAGONX_LITE_BACKEND_EXTRA_LIBS=secur32;userenv, producing /tmp/od-win-lite-link/bin/ObsidianDragonLite.exe as a PE32+ GUI x86-64 Windows executable. The executable was inspected but not run.
• Windows GNU imported app linking is also verified for the relative-source artifact from /tmp/od-win-relative-link with the same DRAGONX_LITE_BACKEND_EXTRA_LIBS=secur32;userenv value, producing /tmp/od-win-relative-link/bin/ObsidianDragonLite.exe as a PE32+ GUI x86-64 Windows executable. The import table includes Secur32.dll and USERENV.dll; the executable was inspected but not run.
• The Windows GNU link run also proved the need for a Windows-only short CMake wrapper for the overlong Batch 90 generated source basename, because MinGW dependency files append .obj.d and exceed the filename component limit otherwise.
• macOS artifact production is blocked on this Linux workspace until an Apple Rust target and Apple/osxcross linker toolchain are available, and is deferred for now by operator request. The blocker was rechecked twice on 2026-05-20 and again on 2026-05-22; the host still has no installed Apple Rust targets, no Xcode, no /opt/osxcross, no Apple/osxcross compiler wrappers, and no Apple linker environment variables. The 2026-05-22 checked-in relative-source attempt with --rust-target x86_64-apple-darwin reached Cargo and failed with missing compiler_builtins, core, alloc, and std for that target. No macOS archive, symbol inventory, manifest, imported-link result, or extra-link-library value has been produced yet. The macOS builder prerequisites, command shape, acceptance criteria, and platform link-library planning notes remain recorded in the artifact production guide for a future continuation.
• Platform native link libraries are not being guessed in CMake. Linux test/app linking currently succeeds with DRAGONX_LITE_BACKEND_EXTRA_LIBS empty, Windows GNU app linking succeeds with secur32;userenv, and macOS imported-link verification must record any actual extra backend-specific libraries after Darwin linker proof.

Both verified platform artifacts expose blake3_PW plus all eight required litelib_* symbols. These checks still do not load, resolve, or call the backend at runtime.

Required C ABI

The artifact must export these C symbols, matching LiteClientBridgeApi:

Symbol	Purpose	Return ownership
litelib_wallet_exists	Check wallet existence for a chain	caller does not free
litelib_initialize_new	Create a new wallet	returned string must be freed
litelib_initialize_new_from_phrase	Restore wallet from seed phrase	returned string must be freed
litelib_initialize_existing	Open an existing wallet	returned string must be freed
litelib_execute	Execute SDXL command strings such as sync, syncstatus, balance, list, send, import, export, save, shield, and encryption commands	returned string must be freed
litelib_rust_free_string	Free strings returned by the Rust backend	cleanup function
litelib_check_server_online	Check lite server availability	caller does not free
litelib_shutdown	Shut down backend resources	no returned value

The supported ABI version label is sdxl-c-v1.

Contract Helper

src/wallet/lite_backend_artifact_contract.h/.cpp adds LiteBackendArtifactContract. It validates caller-supplied artifact metadata and exported-symbol inventory, then produces a LiteBackendArtifactResolverInput for the existing read-only resolver.

The helper verifies:

• contract owner and read-only gate are ready,
• link mode is the Phase 1 imported-library path,
• artifact path is configured,
• artifact kind is static or shared library,
• ABI version is sdxl-c-v1,
• required signature metadata is complete and verified when release policy requires it,
• symbol inventory owner is ready,
• all required C ABI symbols are present,
• no artifact mutation, dynamic library load/unload, symbol resolution, SDXL call, bridge call, server check, lifecycle, sync, worker, WalletState, persistence, upload, signing, or publication action is requested.

The helper never loads the artifact, resolves symbols, calls the bridge, calls SDXL, or enables runtime activation.

Remaining Phase 1 Work

• macOS artifact and imported-link verification is deferred for now by operator request; when resumed on a macOS host or configured osxcross builder, record any proven DRAGONX_LITE_BACKEND_EXTRA_LIBS values next to the artifact manifests.
• Read-only signature metadata capture and the optional CMake signature gate are implemented; signing itself remains outside wallet runtime code. Capture real signed-artifact evidence only when a release builder provides sidecar signatures.