OZExternalWalletAdapter

public protocol OZExternalWalletAdapter : AnyObject, Sendable

Protocol for integrating external wallet adapters for multi-signer support.

External wallet adapters enable signing with external wallets like Freighter or Albedo for multi-signature smart accounts. They handle wallet connection and signature collection.

Example implementation:

final class FreighterAdapter: OZExternalWalletAdapter {
    func connect() async throws -> OZConnectedWallet? {
        return OZConnectedWallet(address: "G...", walletId: "freighter", walletName: "Freighter")
    }
    func signAuthEntry(
        preimageXdr: String,
        options: OZSignAuthEntryOptions?
    ) async throws -> OZSignAuthEntryResult {
        // Decode preimage, hash with SHA-256, sign with Ed25519, return result.
    }
    // ... remaining members ...
}
Show on GitHub
  • connect() Asynchronous

    Connects to the external wallet, prompting the user to authorize via the wallet’s UI (for example a wallet selection modal).

    Throws

    SmartAccountWalletException if connection fails.

    Declaration

    Swift

    func connect() async throws -> OZConnectedWallet?

    Return Value

    The connected wallet info, or nil if the user cancelled.

    Show on GitHub
  • disconnect() Asynchronous

    Disconnects all external wallets.

    Throws

    SmartAccountWalletException if disconnection fails.

    Declaration

    Swift

    func disconnect() async throws
    Show on GitHub
  • disconnectByAddress(address:) Default implementation, asynchronous

    Disconnects a specific wallet by address. The default implementation is a no-op suitable for adapters that do not need per-address cleanup.

    Default Implementation

    Declaration

    Swift

    func disconnectByAddress(address: String) async throws

    Parameters

    address

    The Stellar G-address of the wallet to disconnect.
    Show on GitHub

  • Signs an authorization preimage with the external wallet.

    The SDK passes a base64-encoded HashIDPreimage XDR. The wallet must:

    1. Base64-decode the preimage bytes.
    2. SHA-256 hash the preimage bytes.
    3. Ed25519-sign the 32-byte hash.
    4. Return the 64-byte raw signature as base64.

    The SDK handles auth-entry construction and signature format; the wallet only needs to produce the raw Ed25519 signature.

    Throws

    SmartAccountTransactionException.SigningFailed if signing fails or is rejected.

    Declaration

    Swift

    func signAuthEntry(
    preimageXdr: String,
    options: OZSignAuthEntryOptions?
) async throws -> OZSignAuthEntryResult

    Parameters

    preimageXdr

    The base64-encoded HashIDPreimage XDR to sign.
    options

    Optional signing options (network passphrase, specific address).

    Return Value

    The signing result with base64-encoded raw Ed25519 signature (64 bytes).

    Show on GitHub

  • Returns all currently connected wallets with their addresses and identifiers.

    Declaration

    Swift

    func getConnectedWallets() -> [OZConnectedWallet]
    Show on GitHub

  • Returns whether a specific address has a connected wallet that can sign for it.

    Declaration

    Swift

    func canSignFor(address: String) -> Bool
    Show on GitHub
  • getWalletForAddress(address:) Default implementation

    Returns wallet info for a specific address, or nil when not found.

    The default implementation returns nil.

    Default Implementation

    Declaration

    Swift

    func getWalletForAddress(address: String) -> OZConnectedWallet?
    Show on GitHub