CashuKit

PRE-1.0 / BETA — tracks CoreCashu's API freeze.

CashuKit is the Apple-platform layer over CoreCashu. It builds clean on macOS and iOS Simulator with strict Swift 6 concurrency and 69 Swift Testing tests green. After CoreCashu's Phase 7.1 (@_exported removal), consumers that use P256K, CryptoSwift, or BigInt types directly must add those packages as their own dependencies — they are no longer transitively re-exported.

Pending external security audit before production use with significant funds. See ../CoreCashu/Docs/NUT_STATUS.md for which NUTs are safe to advertise and which are still gated off.

Native Apple platform SDK for the Cashu ecash protocol. CashuKit provides deep integration with iOS, macOS, and other Apple platforms, leveraging system frameworks for security, performance, and reliability.

Overview

CashuKit is a headless SDK built on top of CoreCashu. It provides Apple-platform-specific implementations but does not include any UI components. Apps are expected to build their own user interfaces using the CashuKit APIs.

What CashuKit provides:

• Keychain-based secure storage
• Face ID / Touch ID / Optic ID authentication
• iCloud Keychain sync support
• Background task processing
• Network monitoring with offline queueing
• Privacy-preserving structured logging

What CashuKit does NOT provide:

• SwiftUI views or UI components
• Pre-built wallet screens
• Transaction list views

For UI implementation, refer to the example app or build your own using the AppleCashuWallet class.

Architecture

┌─────────────────────────────────────────┐
│           Your iOS/macOS App            │
│         (Your UI goes here)             │
├─────────────────────────────────────────┤
│              CashuKit                   │  ← You are here
│  (Apple Platform Integration - No UI)  │
├─────────────────────────────────────────┤
│              CoreCashu                  │
│    (Platform-Agnostic Protocol)         │
└─────────────────────────────────────────┘

Key Features

Apple Platform Integration

• Keychain & Secure Enclave: Hardware-backed key storage with biometric protection
• Face ID / Touch ID / Optic ID: Seamless biometric authentication
• iCloud Keychain Sync: Optional cross-device wallet synchronization
• Background Execution: Continue operations when app is backgrounded
• Network Monitoring: Intelligent offline queueing and retry logic
• Structured Logging: Privacy-preserving os.log integration

Protocol Features (via CoreCashu)

• Spec-correct NUTs — see CoreCashu's NUT_STATUS
• Lightning Network mint & melt (BOLT11)
• Deterministic secrets with BIP39/BIP32 (PBKDF2-HMAC-SHA-512, 2048 iterations)
• Advanced spending conditions: P2PK (NUT-11) and HTLC (NUT-14) end-to-end
• Token state management (NUT-07)
• Capability-gated optional NUTs — operations refuse to execute when the mint doesn't advertise support

Not yet supported / gated off

• NUT-15 multi-path payments (type definitions only)
• NUT-17 WebSocket reconnect-and-resume integration test (HTTP-only MockMint)
• NUT-21 Clear auth / JWT (signature verification is a stub)
• NUT-22 Blind auth / BAT (endpoint and header shape don't match spec)
• NUT-23, NUT-25 through NUT-29

Installation

Requirements

• iOS 17.0+ / macOS 15.0+ / tvOS 17.0+ / watchOS 10.0+ / visionOS 2.0+
• Xcode 16.0+
• Swift 6.0+

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/SparrowTek/CashuKit", from: "0.1.0")
]

Or in Xcode:

1. File -> Add Package Dependencies
2. Enter the repository URL
3. Select CashuKit product

Configuration

Add to your app's Info.plist:

<!-- Required for biometric authentication -->
<key>NSFaceIDUsageDescription</key>
<string>Authenticate to access your Cashu wallet</string>

<!-- Optional: For background tasks -->
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>

<!-- Optional: Register background task identifiers -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.cashukit.balance.refresh</string>
    <string>com.cashukit.proof.validation</string>
    <string>com.cashukit.token.sync</string>
    <string>com.cashukit.mint.health</string>
</array>

Quick Start

Basic Wallet Setup

import CashuKit
import CoreCashu

// Create wallet with Apple platform defaults
let wallet = await AppleCashuWallet()

// Connect to a mint
try await wallet.connect(to: URL(string: "https://testnut.cashu.space")!)

// Check balance
let balance = await wallet.balance
print("Balance: \(balance) sats")

// Send ecash
let token = try await wallet.send(amount: 100, memo: "Coffee payment")
print("Token: \(try wallet.encodeToken(token))")

// Receive ecash
let proofs = try await wallet.receive(token: receivedTokenString)
print("Received \(proofs.count) proofs")

SwiftUI Integration

Since CashuKit is a headless SDK, you build your own UI:

import SwiftUI
import CashuKit

@main
struct MyWalletApp: App {
    @StateObject private var wallet = AppleCashuWallet()
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(wallet)
        }
    }
}

struct ContentView: View {
    @EnvironmentObject var wallet: AppleCashuWallet
    
    var body: some View {
        NavigationStack {
            VStack(spacing: 20) {
                // Build your own balance display
                Text("\(wallet.balance) sats")
                    .font(.largeTitle)
                
                // Build your own send/receive UI
                Button("Send 100 sats") {
                    Task {
                        let token = try await wallet.send(amount: 100)
                        // Handle token...
                    }
                }
                
                // Build your own transaction list
                // ...
            }
            .navigationTitle("My Wallet")
        }
    }
}

Secure Storage Configuration

// Default configuration (recommended)
let wallet = await AppleCashuWallet()

// Custom configuration
let config = AppleCashuWallet.Configuration(
    keychainAccessGroup: "group.com.yourapp.cashu",
    enableBiometrics: true,
    enableiCloudSync: true
)
let customWallet = await AppleCashuWallet(configuration: config)

Background Task Management

// In your AppDelegate or App initialization
let networkMonitor = await NetworkMonitor()
let backgroundTaskManager = BackgroundTaskManager(networkMonitor: networkMonitor)

// Register background tasks
await backgroundTaskManager.registerBackgroundTasks()

// Queue operations for background execution
await backgroundTaskManager.addPendingOperation(
    type: "token_sync",
    data: syncData
)

Network Monitoring

let networkMonitor = await NetworkMonitor()

// Start monitoring
await networkMonitor.startMonitoring()

// Check status
let isConnected = await networkMonitor.isConnected

// Queue operations when offline
await networkMonitor.queueOperation(
    type: .sendToken,
    data: tokenData,
    priority: .high
)

Advanced Usage

Wallet Restoration

// Generate new mnemonic
let mnemonic = try await wallet.generateMnemonic()
print("Save these words: \(mnemonic)")

// Restore wallet from mnemonic
try await wallet.restore(mnemonic: savedMnemonic)

Biometric Authentication

let bioManager = BiometricAuthManager.shared

// Check availability
await bioManager.checkBiometricAvailability()

if await bioManager.isAvailable {
    // Authenticate user
    let authenticated = try await bioManager.authenticateUser(
        reason: "Access your Cashu wallet"
    )
    
    if authenticated {
        // Proceed with sensitive operation
    }
}

Custom Logging

// Configure logging
let logger = OSLogLogger(
    category: "CashuWallet",
    minimumLevel: .debug
)

// Sensitive data is automatically redacted
logger.info("Sending transaction", metadata: [
    "mint": mintURL,
    "amount": amount
])

WebSocket Subscriptions

// Create WebSocket client
let wsClient = AppleWebSocketClient(
    configuration: WebSocketConfiguration(
        connectionTimeout: 10,
        pingInterval: 30
    )
)

// Connect and subscribe
try await wsClient.connect(to: URL(string: "wss://mint.example.com/v1/ws")!)

connect(to:) validates the connection with a ping probe before isConnected is set to true. send, receive, and ping are bounded by connectionTimeout and throw WebSocketError.timeout on slow or unresponsive links.

Security

CashuKit provides Apple platform security integrations on top of CoreCashu's protocol security.

Platform Security Features

• Keychain Storage: Hardware-backed key storage with Secure Enclave support
• Biometric Authentication: Face ID, Touch ID, Optic ID for sensitive operations
• iCloud Keychain Sync: Optional cross-device synchronization (encrypted)
• Privacy-Preserving Logging: Automatic sensitive data redaction in os.log
• Secure Operation Queue: Offline operations stored in Keychain (not UserDefaults)

Inherited from CoreCashu

• Rate limiting and circuit breakers
• Constant-time cryptographic operations
• Memory zeroization for sensitive data
• BIP39/BIP32 deterministic key derivation

Audit Status

CashuKit is ready for external security audit alongside CoreCashu. See CoreCashu Security Documentation for the complete threat model.

Production use with significant funds should await completion of external audit.

Testing

# Run all tests
swift test

# Run specific test suite
swift test --filter CashuKitTests

# Run with coverage
swift test --enable-code-coverage

Contributing

We welcome contributions! Areas that need work:

1. Security: Hardening and audit preparation
2. Testing: Increase test coverage
3. Documentation: API documentation and guides
4. Performance: Optimization for large wallets

Please open an issue before starting major work.

Dependencies

• CoreCashu - Platform-agnostic Cashu protocol
• swift-secp256k1 - Elliptic curve cryptography
• BigInt - Arbitrary precision arithmetic
• BitcoinDevKit - Bitcoin functionality
• Vault - Keychain wrapper

License

CashuKit is released under the MIT License. See LICENSE for details.

Acknowledgments

• Cashu Protocol - The underlying ecash protocol
• cashubtc/nuts - Protocol specifications
• The Cashu community for protocol development and support

---

Status: Beta - Security audit preparation complete. External audit pending before production use with significant funds.