Clear Signing SDK

Rust ERC-7730 v2 clear-signing library with SDK surfaces for Swift and Kotlin.

The repository contains:

• A Rust engine that resolves descriptors and formats contract calldata and EIP-712 typed data into a display model.
• A Swift package surface built on UniFFI bindings plus a handwritten ClearSigningClient.
• An Android/Kotlin SDK module built on UniFFI bindings plus a handwritten ClearSigningClient.
• Local demo and smoke-test consumers for validating the SDK integrations.

What The SDK Does

• Formats calldata and EIP-712 typed data into an explicit FormatOutcome:
  • clearSigned: descriptor-backed clear signing succeeded
  • fallback: renderable but degraded / unverified output
  • failure: invalid input, invalid descriptor, resolution outage, or internal failure
• Returns typed FormatDiagnostic entries for non-fatal degradation instead of string warnings. FormatDiagnostic.code is the machine-readable contract for wallet policy and telemetry. FormatDiagnostic.message is human-readable text and may evolve independently.
• Resolves descriptors for direct calls and nested calldata flows via DescriptorResolutionOutcome.
• Supports proxy-aware descriptor resolution through wallet-provided DataProviderFfi.
• Delegates token, name, NFT, and block metadata lookups to the host wallet.

Provider callbacks are still best-effort in this phase:

• missing token or name metadata can produce diagnostics
• they do not automatically become hard failures

Wallet policy should branch on diagnostic code, not parse diagnostic message. Example:

• token_metadata_not_found: show degraded token presentation
• nested_descriptor_not_found: show generic nested-call UI

SDK Surfaces

Swift

• Package product: ClearSigning
• Integration style: Swift Package Manager
• Main API: ClearSigningClient
• main resolves the local XCFramework at target/ios/libclear_signing.xcframework
• Tagged releases resolve the remote GitHub Release XCFramework zip

See docs/swift-integration.md.

Kotlin

• Android library module: android/clear-signing
• Published consumption: JitPack-backed Maven dependency
• Main API: com.clearsigning.ClearSigningClient
• Local development packaging: generated Kotlin bindings plus Android jniLibs

See docs/kotlin-integration.md.

React Native

• npm package: react-native-clear-signing
• Integration style: JSI / TurboModule via uniffi-bindgen-react-native; iOS Podfile peer-pod entry, Android autolinking
• Main API: bare clearSigning* async functions (no handwritten client wrapper); DataProviderFfi callbacks are synchronous across the FFI boundary
• Local-dev consumer: bindings/react-native/example/ (file:.. link, mirrors the iOS Wallet Debug tab)

See docs/react-native-integration.md.

Release Docs

• One-click SDK-bindings release: trigger Release All Platforms (workflow_dispatch) — fans out to Swift + Kotlin + React Native in dependency order.
• Cargo crate releases stay standalone via release-crate.yml — manifest bump on main is required first, so it doesn't fit the orchestrator's tag-driven model.
• Per-platform standalone workflows stay individually triggerable for hotfixes.
• Full procedure + recovery notes: docs/release-guide.md

Local Development

Build and test the Rust crate from repo root:

cargo build
cargo test
cargo check -p clear-signing --features uniffi,github-registry
cargo test -p clear-signing --features uniffi,github-registry
cargo clippy -p clear-signing --all-targets --features uniffi,github-registry -- -D warnings

Swift local packaging:

./scripts/generate_uniffi_bindings.sh
./scripts/build-xcframework.sh
swift package describe
xcodebuild -project wallet/Wallet.xcodeproj -scheme Wallet -destination 'generic/platform=iOS Simulator' build

Android local packaging follows the same steps used in CI: build native libraries, generate Kotlin bindings, then assemble/publish the Android artifact. See the Kotlin integration guide for the exact local flow.

Repo Notes

• The checked-in Package.swift on main defaults to the local XCFramework and currently declares .iOS(.v14).
• The Swift release workflow rewrites Package.swift on the tagged release commit to point at the published artifact URL and checksum.
• main remains the local-development manifest after release tagging.
• The Android SDK consumes generated bindings and native libraries from android/build/generated/clear-signing/.