Contents

kingpin-apps/swift-cardano-wallet

A high-level Swift wallet SDK for Cardano. Pure Swift —

Features

  • Six wallet types — mnemonic, TextEnvelope (cardano-cli .skey), watch-only,

passphrase-encrypted, native-script multisig, and hardware (Ledger / Trezor via cardano-hw-cli).

  • All major operations — send, stake (register / delegate / withdraw), mint

(both native-script and Plutus V1/V2/V3 policies, with CIP-25 v1 + v2 NFTs), Conway-era governance (DRep registration, vote delegation, voting). Auto coin selection, auto signing, auto submit, auto collateral selection for Plutus mints.

  • Five chain providers — Blockfrost, Koios, Ogmios, Kupo, Offline. Pluggable via

ProviderConfig.

  • CIP support — CIP-1852 (HD), CIP-8 (message signing), CIP-14 (asset

fingerprints), CIP-25 v1 + v2 (NFT metadata; v2 supports byte-keyed asset names for CIP-67/68 prefixed assets), CIP-30 (dApp connector via wallet.cip30Provider(info:policy:) — every signing op is gated on a required CIP30ApprovalPolicy), CIP-119 (DRep metadata).

  • ADA Handle resolution — wallet.sendTo(handle: "$alice", lovelace: 5_000_000)

via swift-handles-api with a TTL cache.

  • Two storage backends — FileKeyStore (default) and KeychainKeyStore

(Apple platforms). Optional SQLiteUTxOStore behind the SQLite package trait.

Install

In your Package.swift:

.package(url: "https://github.com/Kingpin-Apps/swift-cardano-wallet.git", from: "0.1.0"),

Then add "SwiftCardanoWallet" to your target's dependencies.

To enable the optional SQLite-backed UTxO cache:

.package(
    url: "https://github.com/Kingpin-Apps/swift-cardano-wallet.git",
    from: "0.1.0",
    traits: ["SQLite"]
),

Generating a new wallet

Every constructor on this page takes existing key material. To mint a fresh wallet, use the matching generate(...) factory:

// HD mnemonic — the default. Returns the freshly-minted phrase; persist or display
// it to the user before this tuple goes out of scope — once it's gone, the keys are
// unrecoverable.
let (wallet, phrase) = try await Wallet.generateMnemonic(
    network: .mainnet,
    provider: .blockfrost(projectId: "mainnet_…")
)

// Generate + encrypt in one round-trip. The blob is the at-rest form; persist it via
// any KeyStore.
let (wallet, phrase, blob) = try await Wallet.generateEncrypted(
    passphrase: userPassphrase,
    network: .mainnet,
    provider: .blockfrost(projectId: "mainnet_…")
)
try await keyStore.save(blob, id: "primary")

// TextEnvelope (`cardano-cli`-style `.skey` files on disk).
let (wallet, paymentSkeyURL, stakeSkeyURL) = try await Wallet.generateTextEnvelope(
    writeTo: keyDirectory,
    network: .preprod,
    provider: .blockfrost(projectId: "preprod_…")
)

watchOnly, multisig, and hardware wallets do not get generate factories by design — they wrap pre-existing key material (vkeys, key hashes, device-generated .hwsfiles) and there is no fresh-keypair operation to perform locally.

MnemonicWallet.generate accepts a wordCount: of 12 / 15 / 18 / 21 / 24 (default 24) and a language: parameter (default .english). All BIP-39 wordlists exposed by swift-cardano-core round-trip — English, Japanese, Spanish, French, Italian, Korean, Czech, Portuguese, and the two Chinese variants. Japanese phrases are joined with U+3000 IDEOGRAPHIC SPACE per BIP-39 and recover via NFKD normalization on the upstream side. TextEnvelopeWallet also exposes a generateInMemory(...) variant that hands back the raw 32-byte signing key payloads instead of writing them to disk, for callers that want to persist via a custom KeyStore.

Five lines to send ADA

import SwiftCardanoWallet

let wallet = try await Wallet.mnemonic(
    phrase: phrase,
    network: .mainnet,
    provider: .blockfrost(projectId: "mainnet…")
)
let txId = try await wallet.send(lovelace: 5_000_000, to: try Address.fromBech32("addr1…"))

For a step-by-step walkthrough — including how to inspect the unsigned transaction before signing — see the Quick Start article.

Wallet types

| Type | When to use | |---|---| | MnemonicWallet | BIP-39 phrase. The default; HD addresses + auto sign. | | Wallet.encrypted(blob:passphrase:...) | Recover a wallet from a persisted EncryptedBlob. PBKDF2-SHA512 → AES-256-GCM. Returns a .mnemonic(_:) case after decryption. | | TextEnvelopeWallet | Existing cardano-cli .skey files. Full send + sign. | | WatchOnlyWallet | Verification keys or just an address. prepareSend builds; sign() throws watchOnly — pair with offline signing. Stake addresses (stake1…) are also accepted for reward / delegation monitoring. | | MultisigWallet | Native-script multisig (N-of-M, all, any). Coordinator collects partial witnesses from cosigners and assembles. | | HardwareWallet | Ledger / Trezor via cardano-hw-cli. macOS + Linux only (iOS traps with unsupportedOperation). |

See the Wallet Types article for construction examples and trade-offs.

Operations cheat sheet

// --- Available on the `Wallet` enum directly ---

// Read
let balance  = try await wallet.balance()              // ADA + multi-asset + rewards
let address  = try await wallet.primaryAddress()       // receive (mnemonic) / script (multisig) / etc.
let utxos    = try await wallet.utxos()
let canSign  = wallet.canSign                          // false for .watchOnly

// Send
try await wallet.send(lovelace: 5_000_000, to: addr)
try await wallet.sendTo(handle: "$alice", lovelace: 5_000_000)

// --- Stake / mint / governance live on `MnemonicWallet` ---
// (Multisig / hardware have their own multi-step flows; drop down via the typed accessor.)

guard let m = wallet.mnemonicWallet else { return }

// Stake
try await m.registerStake()
try await m.delegate(toPool: poolId)
try await m.claimAllRewards()

// Mint — native script (one-shot NFT)
try await m.mintNFT(name: "MyNFT", metadata: cip25)         // CIP-25 v1 default
let v2 = metadata.encode(policyId: pid, assetName: "MyNFT", version: .v2)

// Mint — Plutus policy
try await m.mint(
    amount: 1,
    assetName: "MyToken",
    plutusPolicy: .plutusV2Script(PlutusV2Script(data: compiledScript))
    // `redeemer:` defaults to a Unit redeemer; `collateral:` auto-picked from UTxOs
)

// Governance
try await m.delegateVote(to: .alwaysAbstain)
try await m.vote(on: govActionId, vote: .yes)

For multi-action transactions, build with prepareSend(...) / prepareMint(...) / etc. on the concrete actor and chain the resulting PreparedTransactions manually.

Connecting a dApp (CIP-30)

import SwiftCardanoCIPs

let provider = try await wallet.mnemonicWallet!.cip30Provider(
    info: WalletInfo(name: "MyWallet", icon: "data:image/png;base64,…"),
    policy: CIP30ApprovalPolicy(
        approveSignTx:   { tx, _, ctx in await ui.confirmSignTx(tx, origin: ctx?.origin) },
        approveSignData: { addr, payload, ctx in await ui.confirmSignData(addr, payload, origin: ctx?.origin) },
        approveSubmitTx: { _, ctx in await ui.confirmSubmit(origin: ctx?.origin) }
    )
)

The returned KeyStoreCIP30Provider is the upstream reference implementation from swift-cardano-cips. Every signTx / signData / submitTx call invokes the matching approval closure first — there's no "always allow" backdoor. partialSign: false is real: the provider checks required-signer hashes against the wallet's keys and throws TxSignError.proofGeneration when any are missing. signData uses raw byte payloads (no UTF-8 transcoding), so signing arbitrary bytes is well-defined.

Use CIP30ApprovalPolicy.denyAll as a safe placeholder during development; never ship .allowAll — it's only for test harnesses.

Security defaults

  • Mnemonic encryption. EncryptedKeyManager → PBKDF2-HMAC-SHA512 (210,000 iters by

default; 100k floor enforced on decrypt to reject tampered blobs) → AES-256-GCM via CryptoKit. Passphrase is NFKC-normalized before key derivation so composed vs decomposed accented characters produce the same key across devices.

  • Blob format. v2 (current) uses a CBOR-map plaintext so future fields can be added

without ambiguity. v1 (\n-delimited) blobs still decrypt — re-saving migrates them to v2.

  • On-disk permissions. FileKeyStore chmods newly-created vault directories to

0o700 and every saved blob to 0o600 regardless of process umask.

  • Heap residue. PBKDF2-derived keys and decrypted plaintext are zeroed via

memset_s after use (best-effort defense-in-depth; see Data.zeroize() for the caveats).

  • dApp consent. CIP-30 surface is gated on a required CIP30ApprovalPolicy — see

the section above.

Documentation

DocC catalog ships in Sources/SwiftCardanoWallet/SwiftCardanoWallet.docc/. Open the package in Xcode and choose Product → Build Documentation (⌃⇧⌘D) — this is the canonical path; Xcode's symbol extractor handles the OpenSSL transitive dependency (via swift-cardano-chain → Blockfrost) without extra wiring.

For command-line generation, add the swift-docc-plugin to your own consumer package and run swift package generate-documentation. (Adding it here causes swift-symbolgraph-extract to fail on the OpenSSL XCFramework on macOS, so it isn't a direct dep.)

Status

Currently at parity with TokeoPay/CardanoKit plus the full swift-cardano-txbuilder shortcut surface, Plutus V1/V2/V3 minting, and CIP-25 v2 NFT metadata. 220 hermetic tests (227 with the SQLite trait) — all green.

See .agents/PLAN.md for the full build sequence, dependencies, and known follow-ups (Ogmios chain-sync, mixed software/hardware signing, verified Plutus script fixtures for end-to-end auto-estimate testing).

Requirements

  • Swift 6.3+
  • macOS 15+ / iOS 18+ / Linux (Swift 6 toolchain)
  • Hardware wallet support requires cardano-hw-cli installed locally (`scm install

cardano-hw-cli from swift-cardano-multitool`, or the upstream Vacuumlabs binary)

License

Apache 2.0 — see LICENSE.

Package Metadata

Repository: kingpin-apps/swift-cardano-wallet

Default branch: main

README: README.md