OZSmartAccountConfig

public struct OZSmartAccountConfig : @unchecked Sendable
extension OZSmartAccountConfig: Equatable
extension OZSmartAccountConfig: Hashable

Configuration for OpenZeppelin Smart Account operations.

Defines all parameters required to interact with OpenZeppelin smart accounts on Stellar/Soroban: network connectivity, contract addresses, and operational defaults.

Example:

let config = try OZSmartAccountConfig(
    rpcUrl: "https://soroban-testnet.stellar.org",
    networkPassphrase: "Test SDF Network ; September 2015",
    accountWasmHash: "abc123...",
    webauthnVerifierAddress: "CBCD1234..."
)

let custom = try OZSmartAccountConfig.builder(
    rpcUrl: "https://soroban-testnet.stellar.org",
    networkPassphrase: "Test SDF Network ; September 2015",
    accountWasmHash: "abc123...",
    webauthnVerifierAddress: "CBCD1234..."
)
    .sessionExpiryMs(86_400_000)
    .relayerUrl("https://relayer.example.com")
    .storage(myPersistentStorage)
    .externalWallet(freighterAdapter)
    .build()

Throws SmartAccountConfigurationException if required parameters are blank or invalid (for example, accountWasmHash is not a 64-character hex string, or webauthnVerifierAddress is not a valid C-address).

Show on GitHub

Required Configuration

  • The Soroban RPC endpoint URL.

    Example: https://soroban-testnet.stellar.org.

    Declaration

    Swift

    public let rpcUrl: String
    Show on GitHub

  • The Stellar network passphrase.

    Examples:

    • Testnet: "Test SDF Network ; September 2015"
    • Mainnet: "Public Global Stellar Network ; September 2015"

    Declaration

    Swift

    public let networkPassphrase: String
    Show on GitHub

  • The WASM hash of the smart account contract (64-character hex string).

    SHA-256 of the smart account contract WASM code, used for deploying new smart account instances.

    Declaration

    Swift

    public let accountWasmHash: String
    Show on GitHub

  • The contract address of the WebAuthn signature verifier (C… strkey).

    Validates secp256r1 signatures from WebAuthn / passkeys.

    Declaration

    Swift

    public let webauthnVerifierAddress: String
    Show on GitHub

Optional Configuration

  • The keypair used for deploying smart account contracts.

    When nil, a deterministic deployer is derived from SHA-256("openzeppelin-smart-account-kit"). Production apps typically supply a custom deployer for attribution and traceability. The deployer only pays for deployment transactions; it does not control user wallets.

    Declaration

    Swift

    public let deployerKeypair: KeyPair?
    Show on GitHub

  • Session expiry time in milliseconds.

    Sessions enable silent reconnection without re-authentication.

    Declaration

    Swift

    public let sessionExpiryMs: Int64
    Show on GitHub

  • Signature expiration in ledgers for auth entries.

    Auth entries expire after this many ledgers to prevent replay attacks. Default approximates one hour at five seconds per ledger. Must be >= 1. There is no client-side upper bound; the network’s maxEntryTTL (CAP-0046-11) governs the maximum and is enforced by the host at submission.

    Declaration

    Swift

    public let signatureExpirationLedgers: Int
    Show on GitHub

  • Transaction validity window in seconds.

    Sets each transaction’s TimeBounds max_time to now + timeoutInSeconds, bounding how long a signed transaction stays valid for submission. A value of 0 means no expiry (infinite): max_time is set to 0, the Stellar sentinel for “no upper bound”. Must be >= 0. Default is 30.

    Declaration

    Swift

    public let timeoutInSeconds: Int
    Show on GitHub

  • Optional relayer endpoint URL for fee sponsoring.

    When set, enables gasless transactions by submitting through a fee-bump relayer. Allows users with empty wallets to transact.

    Declaration

    Swift

    public let relayerUrl: String?
    Show on GitHub

  • Optional indexer endpoint URL for credential-to-contract mapping.

    The indexer maps WebAuthn credential IDs to deployed smart account contract addresses, enabling “Connect Wallet” functionality where users can discover previously-created wallets.

    Declaration

    Swift

    public let indexerUrl: String?
    Show on GitHub

  • Optional WebAuthn provider for passkey authentication.

    Platform-specific implementation that handles WebAuthn registration and authentication. Required for signing transactions with passkeys.

    Declaration

    Swift

    public let webauthnProvider: WebAuthnProvider?
    Show on GitHub

  • Storage adapter for persisting credentials and session data.

    Defaults to OZInMemoryStorageAdapter (non-persistent, suitable for testing).

    Declaration

    Swift

    public let storage: OZStorageAdapter
    Show on GitHub

  • When set, delegates transaction signing to this adapter instead of using WebAuthn credentials.

    Declaration

    Swift

    public let externalWallet: OZExternalWalletAdapter?
    Show on GitHub

  • Optional adapter for out-of-process Ed25519 signing in multi-signer ceremonies.

    When non-nil, the adapter is injected into the kit’s OZExternalSignerManager at construction time and consulted (with adapter-first precedence) before the in-memory Ed25519 keypair registry for every ed25519(verifierAddress:publicKey:) entry. In-memory keypairs can still be registered at runtime via externalSigners addEd25519FromRawKey(secretKeyBytes:verifierAddress:).

    Declaration

    Swift

    public let externalEd25519Adapter: OZExternalEd25519SignerAdapter?
    Show on GitHub

  • Maximum rule ID to scan when iterating context rules.

    The contract assigns monotonically increasing IDs to context rules. When rules are removed, their IDs leave gaps. Iterating from ID 0 up to this value finds all active rules. Increase if the account has had many add / remove cycles.

    Declaration

    Swift

    public let maxContextRuleScanId: UInt32
    Show on GitHub

Initialization

Static factories

  • Creates a deterministic deployer keypair for smart account deployment.

    Derives a keypair from SHA-256("openzeppelin-smart-account-kit"). The derivation is deterministic, so the same deployer is produced on every invocation unless overridden. This keypair only pays deployment fees and does not control user wallets. Production apps typically supply a custom deployer for attribution and traceability.

    Throws

    SmartAccountConfigurationException.InvalidConfig if seed generation fails.

    Declaration

    Swift

    public static func createDefaultDeployer() async throws -> KeyPair

    Return Value

    A deterministic KeyPair for contract deployment.

    Show on GitHub

  • Creates a builder for constructing OZSmartAccountConfig with a fluent API.

    Declaration

    Swift

    public static func builder(
    rpcUrl: String,
    networkPassphrase: String,
    accountWasmHash: String,
    webauthnVerifierAddress: String
) -> Builder

    Parameters

    rpcUrl

    The Soroban RPC endpoint URL.
    networkPassphrase

    The Stellar network passphrase.
    accountWasmHash

    The smart account contract WASM hash (64-char hex).
    webauthnVerifierAddress

    The WebAuthn verifier contract address (C… strkey).

    Return Value

    A new Builder with the four required fields set and defaults applied to every optional field.

    Show on GitHub

Instance methods

  • effectiveDeployer() Asynchronous

    Returns the deployer keypair, creating the default if needed.

    Async because creating the default deployer involves cryptographic operations (SHA-256 hashing and Ed25519 seed derivation).

    Throws

    SmartAccountConfigurationException.InvalidConfig if default deployer creation fails.

    Declaration

    Swift

    public func effectiveDeployer() async throws -> KeyPair

    Return Value

    The configured deployer or the default deterministic deployer.

    Show on GitHub

  • Returns the indexer URL that will be used after applying fallback logic.

    If an indexer URL is explicitly configured, it is returned. Otherwise the built-in default for the configured network passphrase is returned, sourced from OZIndexerClient.getDefaultUrl(networkPassphrase:). Returns nil when no URL is configured and no default exists for the network.

    Declaration

    Swift

    public func effectiveIndexerUrl() -> String?

    Return Value

    The resolved indexer URL, or nil.

    Show on GitHub

Builder

  • Builder for creating OZSmartAccountConfig with a fluent API.

    Example:

    let config = try OZSmartAccountConfig.builder(
    rpcUrl: "https://soroban-testnet.stellar.org",
    networkPassphrase: "Test SDF Network ; September 2015",
    accountWasmHash: "abc123...",
    webauthnVerifierAddress: "CBCD1234..."
)
    .sessionExpiryMs(86_400_000)
    .relayerUrl("https://relayer.example.com")
    .storage(myPersistentStorage)
    .externalWallet(freighterAdapter)
    .build()
    See more

    Declaration

    Swift

    public final class Builder : @unchecked Sendable
    Show on GitHub

Equatable

  • Two configurations are equal when every field compares equal.

    KeyPair and the protocol-typed storage, webauthnProvider, and externalWallet fields use reference / instance equality where applicable. OZInMemoryStorageAdapter overrides equality so all instances of that class compare equal, which lets two default-constructed configs round-trip through equality without surprises.

    Declaration

    Swift

    public static func == (lhs: OZSmartAccountConfig, rhs: OZSmartAccountConfig) -> Bool
    Show on GitHub

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)
    Show on GitHub