Cardano Swift (Universal)

A high-performance Cardano SDK for Swift that works natively on iOS, macOS, tvOS, watchOS, and Linux. It bridges the industry-standard Cardano Serialization Lib (CSL) via a thin Rust-C-Swift bridge.

🚀 Features

• Pure Swift API: High-level abstractions for Wallets, Addresses, and Transactions.
• ✅ Async/Await Support: Full async/await API with Swift Concurrency for multi-core performance (up to 7.5x speedup).
• Complete Documentation: 200+ documented methods with parameters, returns, and error handling.
• Native Performance: No JavaScript or Node.js required. Runs at Rust speed.
• Universal Support: One codebase for mobile (iOS/watchOS), desktop (macOS), entertainment (tvOS), and server-side Swift (Linux).
• Zero Configuration: Automated build system for the native bridge.

🛠 Installation

Swift Package Manager (Recommended)

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/kxpone/cardano-swift.git", from: "0.2.4")
]

Note: The first build may take some time as SPM will automatically download and compile the native Rust bridge for your host architecture. No manual action is required.

CocoaPods

Add the following to your Podfile:

pod 'Cardano', :git => 'https://github.com/kxpone/cardano-swift.git'

Running pod install will automatically trigger the native build process via prepare_command.

Carthage

Add the following to your Cartfile:

github "kxpone/cardano-swift" "main"

Because this SDK relies on a native Rust bridge, you must run the bootstrap script after updating your dependencies:

carthage update
./Carthage/Checkouts/cardano-swift/scripts/init.sh

⚙️ How it works

The SDK features an Auto-Bootstrap system:

1. Zero Configuration: When you add the package, it detects your OS (Linux/macOS/iOS) and architecture.
2. Pinned Core: It compiles the CSL Rust Bridge (fixed at version 9.0.1) specifically for your machine. This ensures compatibility with Cardano Serialization Lib 15.0.3.
3. No External Dependencies: You don't need to manually install any pre-compiled binaries or manage system libraries.

🍎 Apple Platform Support (tvOS & watchOS)

While iOS and macOS are supported on the stable Rust toolchain, tvOS and watchOS targets are currently Tier 2/3 and require the nightly toolchain.

📚 Documentation (Swift-DocC)

Detailed documentation for cardano-swift is bundled directly with the package and integrated into Xcode.

Web version could be found here

Extra Documentation

The documentation is organized into three main areas:

Section	Description	Path
API Reference	Full documentation of all public classes, structs, and methods with code examples.	Sources/Cardano/
Technical Guides	Depth articles on Cardano-specific concepts (Plutus, HD Wallets, Concurrency).	Articles
Educational Tests	Every unit test includes "Cardano Usage Context" explaining the why behind the test.	Tests/CardanoTests/

Key Articles

• Plutus Smart Contracts: A guide to datums, redeemers, and Plutus V3 (CIP-112/CIP-085) integration.
• High-Performance Concurrency: How to leverage the 7.5x performance boost via Swift Async/Await.
• Test Coverage Analysis: Detailed breakdown of the 93.31% test coverage state.

Generating Documentation

To preview the full documentation in your browser or Xcode:

Using Xcode:

1. Open the project in Xcode.
2. Select Product > Build Documentation.

Using Swift CLI:

swift package generate-documentation --target Cardano

To enable support for these platforms, ensure you have the nightly toolchain and relevant targets installed:

rustup toolchain install nightly
rustup target add aarch64-apple-tvos aarch64-apple-tvos-sim --toolchain nightly
rustup target add aarch64-apple-watchos aarch64-apple-watchos-sim --toolchain nightly

During build, the init.sh script will automatically:

1. Patch the underlying rand_os dependency to enable tvOS/watchOS support (these platforms were missing from the crate's platform checks)
2. Use -Z build-std=core,alloc,std to compile the Rust standard library from source for unsupported targets
3. Link with the Apple Security framework which is universally available on all Apple platforms

Technical Details: The build patches rand_os v0.1.2 to recognize tvOS and watchOS as valid targets, allowing it to use the existing macOS/iOS implementation which leverages SecRandomCopyBytes from the Security framework.

🧪 Testing

Verify the installation by running tests:

swift test --enable-test-discovery

📦 Usage

Derive Address from Mnemonic

// Valid 15-word mnemonic or longer
let words = "art forum devote street sure rather head chuckle guard poverty release quote oak craft enemy"
let wallet = try Wallet(mnemonic: Mnemonic(phrase: words), networkId: 0) // 0 for testnet, 1 for mainnet

let address = try wallet.getAddress(account: 0, index: 0)
print("Bech32 Address: \(address.toBech32())")

Build and Sign Transaction

// 1. Prepare Wallet and Keychain
let words = "art forum devote street sure rather head chuckle guard poverty release quote oak craft enemy"
let mnemonic = Mnemonic(phrase: words)
let wallet = try Wallet(mnemonic: mnemonic, networkId: 0)
let keychain = try Keychain(mnemonic: mnemonic)

let myAddress = try wallet.getAddress(account: 0, index: 0)
let destination = try Address(bech32: "addr_test1qpu5sh7exv8v878q0p90v49f872kyv6968m6w86k4f8thqskkd69w2y3c848sh6lsh33u5m96v7a8tyd5whk60zay6xqlx0v9s")

// 2. Define UTXOs
let utxo = UTXO(
    txHash: "fd656fb1f4cf6fbbc36f2705568a4d3b7a970ec0b39f80cc81e1293626b77316",
    index: 0,
    value: Value(coin: 20_000_000),
    address: myAddress
)

// 3. Build Transaction
let builder = try TransactionBuilder()
try builder.addInputs(from: [utxo])
try builder.addOutput(address: destination, value: Value(coin: 10_000_000))
try builder.setTTL(ttl: 500000)

let body = try builder.build(changeAddress: myAddress)

// 4. Sign and get Hex
let transaction = try wallet.sign(transactionBody: body, keychain: keychain)
let hex = try transaction.toHex()
print("Signed Transaction Hex: \(hex)")

Multi-Asset Transaction

let assets = try Assets()
try assets.add(assetName: "KXP", amount: 500)

let multiAsset = try MultiAsset()
try multiAsset.insert(policyId: "6b8d3c96102aa674a26fed7c394c8b8dc0778c1c5e4f2f45ccf411e3", assets: assets)

let value = try Value(coin: 2_000_000, multiAsset: multiAsset)
try builder.addOutput(address: destination, value: value)

Transaction with Metadata

// Create Metadata
let metadata = try Metadata()
try metadata.insert(label: 674, value: Metadata.fromJSON(json: "{\"msg\": [\"Cardano Swift SDK\", \"Native Metadata\"]}"))

// Attach to Builder
let builder = try TransactionBuilder()
// ... add inputs/outputs ...
try builder.setAuxiliaryData(auxiliaryData: try AuxiliaryData(metadata: metadata))

let body = try builder.build(changeAddress: myAddress)

Async/Await: Batch Address Generation

// Generate 100 addresses in parallel (up to 7.5x faster than sequential)
let wallet = try Wallet(mnemonic: Mnemonic(phrase: words), networkId: 0)

let addresses = try await wallet.getAddress(account: 0, startIndex: 0, count: 100)
print("Generated \(addresses.count) addresses concurrently")

Async/Await: Batch Transaction Serialization

// Serialize multiple transactions in parallel (1.5x speedup for 50+ transactions)
let transactions: [Transaction] = /* ... */
let hexStrings = try await Transaction.toHex(transactions: transactions)

for (index, hex) in hexStrings.enumerated() {
    print("TX \(index): \(hex.prefix(32))...")
}

Async/Await: Parallel Mnemonic Validation

// Validate 1000 mnemonics in parallel (non-blocking)
let phrases = [/* ... 1000 phrases ... */]
let validationResults = try await Mnemonic.validate(phrases: phrases)

let validCount = validationResults.filter { $0 }.count
print("\(validCount)/\(phrases.count) mnemonics are valid")

Async/Await: Data Signing

// Sign data with non-blocking UI updates
let data = "message to sign".data(using: .utf8)!
let signature = try await wallet.signData(
    data: data,
    withAddress: address.toBech32()
)
print("Signature: \(signature.signature)")
print("Public Key: \(signature.key)")

📱 Mobile Support (iOS)

The SDK is fully compatible with iOS. For the best experience, ensure your environment has the necessary Rust targets:

rustup target add aarch64-apple-ios x86_64-apple-ios

The build system will automatically bundle these into the framework during the installation phase.

📚 Documentation

API Reference (DocC)

This project uses Apple DocC for unified documentation. You can browse the full API reference directly in Xcode (Product > Build Documentation) or generate it locally:

swift package generate-documentation --target Cardano

Quick Links

• Cardano Docs - Official Cardano documentation
• Plutus Docs - Plutus smart contract reference
• CIP-31 (V2) - Plutus V2 specification
• CIP-112 (V3) - Plutus V3 specification

---

📊 Comparison

Feature	cardano-swift	CardanoKit	Cardano.swift	swift-cardano-core	CSL Bridge
macOS Support	✅ (10.15+)	✅ (15.0+)	✅ (10.15+)	✅ (14.0+)	✅*
iOS Support	✅ (13.0+)	✅ (17.0+)	✅ (13.0+)	✅ (14.0+)	✅
tvOS Support	✅ (13.0+)	❌	❌	✅ (14.0+)	✅*
watchOS Support	✅ (6.0+)	❌	❌	✅ (7.0+)	✅*
Linux Support	✅ (Universal)	❌	⚠️ (Manual)	✅	✅*
Async/Await Support	✅ (Parallelized)	✅ (Standard)	❌	⚠️ (Basic)	❌
BIP39 Mnemonics	✅	✅	✅	✅	✅
Transaction Builder	✅	✅	✅	✅	✅
Plutus V1/V2 Support	✅	⚠️ (Partial)	❌ (Alonzo)	✅	✅
Plutus V3 Support	✅	❌	❌	⚠️ (In-progress)	✅
CIP-30 Data Signing	✅	✅	❌	❌	✅
Native Script Support	✅	✅	✅	✅	✅
Pure Swift (No Rust)	❌	❌	❌	✅	❌
Pinned Core Stability	✅ (v9.0.1)	❌ (Alpha)	❌ (Legacy)	✅ (N/A)	❌
Latest Era (Conway)	✅	✅	❌	✅	✅

* Supports any platform where Rust can be compiled (requires manual compilation for non-mobile targets).

---

🏁 Roadmap

🏁 Done (v0.2.4)

• Universal Apple Support: Native support for tvOS and watchOS platforms.
• Pinned Core Stability: Native bridge core pinned to v9.0.1 (CSL 15.0.3).
• Async/Await API: Complete Swift Concurrency support (7.5x speedup for batch operations).
• Unified Documentation: Full API reference via DocC with detailed code examples.
• Complete Documentation: 200+ documented methods with parameters, returns, and errors.
• Universal Linux/macOS/iOS support via unified Rust bridge.
• Auto-Bootstrap system for SPM and CocoaPods.
• Address Management: Shelley (Bech32), Byron (Base58), Pointer addresses.
• Transaction Builder: Support for simple and complex transactions with automated change calculation.
• Multi-Asset Support: Minting and transferring native tokens.
• Metadata Support: Attaching JSON/CBOR metadata (labels).
• Staking Support: Withdrawals and reward address derivation.
• Memory Safety: Automated RPtr management and error handling from Rust core.
• CIP-30 Compatibility: Data signing and verification.
• Plutus V1/V2/V3: Full support for scripts, datums, and redeemers.
• Min-ADA Logic: Automated calculation of minimum required ADA for multi-asset outputs.

📅 To Do

• Governance (CIP-1694): Support for DRep registration, voting, and delegation (Conway era).
• Native Scripts: Multi-signature support (ALL, ANY, N-of-M) and time-locks.
• Pluggable Providers: Protocol-based interface for easy integration with Blockfrost, Koios, or Ogmios.
• Collateral & Change: Automated collateral selection for smart contract interactions.

📜 License

MIT - See LICENSE for details. Copyright © 2020-2026 KXP. All rights reserved.