OZWalletOperations

public final class OZWalletOperations : OZManagerHelpers, @unchecked Sendable

Wallet-lifecycle operations for OpenZeppelin Smart Accounts.

Handles wallet creation (WebAuthn registration + deterministic contract derivation + deploy-transaction build and submission), wallet connection (session restore, storage → derivation → indexer cascade, ambiguous-multi- contract handling), standalone passkey authentication, and retry of a previously deferred or failed deployment.

Instances are constructed by OZSmartAccountKit and accessed through kit.walletOperations.

Show on GitHub

Initialization


                    
                    
                    createWallet(userName:autoSubmit:autoFund:nativeTokenContract:forceMethod:policies:)

Asynchronous

Creates a new smart-account wallet backed by a fresh WebAuthn credential.

Registers a passkey, derives the deterministic contract address, builds and signs the deploy transaction, and optionally submits it. The signed deploy XDR is always present in the result for deferred submission.

Throws

WebAuthnException, SmartAccountValidationException, SmartAccountTransactionException, SmartAccountCredentialException, SmartAccountStorageException.

Declaration

Swift

public func createWallet(
    userName: String = "Smart Account User",
    autoSubmit: Bool = false,
    autoFund: Bool = false,
    nativeTokenContract: String? = nil,
    forceMethod: OZSubmissionMethod? = nil,
    policies: [String: SCValXDR]? = nil
) async throws -> OZCreateWalletResult

Parameters

`userName`	Display name persisted with the credential.
`autoSubmit`	When `true`, submits the deploy transaction immediately (default `false`). The `signedTransactionXdr` field of the result carries the signed envelope for later external submission regardless.
`autoFund`	Fund the freshly deployed wallet via Friendbot (testnet only). Requires `autoSubmit = true` and `nativeTokenContract != nil`.
`nativeTokenContract`	Native token (XLM SAC) contract address used when `autoFund = true`.
`forceMethod`	Optional submission-method override.
`policies`	Policies to install on the new wallet’s default context rule at deploy time, keyed by policy contract address with the install-param ScVal as the value. `nil` (default) uses `defaultPolicies`; a non-`nil` map overrides it. Validated before the passkey ceremony. Maximum `maxPolicies`.

Return Value

OZCreateWalletResult describing the new wallet.

Show on GitHub


                    
                    
                    connectWallet(options:)

Asynchronous

Connects to an existing smart-account wallet.

Returns OZConnectWalletResult on success, or nil when no valid session exists and options.prompt == false. The non-nil result is either an connected(credentialId:contractId:restoredFromSession:) arm (single contract resolved, kit state set, session saved) or a ambiguous(credentialId:candidates:) arm (indexer reported multiple contracts — kit state NOT set, caller must let the user pick).

Throws

WebAuthnException (prompt path), SmartAccountWalletException (no contract resolved), SmartAccountValidationException (options validation), SmartAccountTransactionException (RPC failure), SmartAccountIndexerException (indexer transport failure).

Declaration

Swift

public func connectWallet(
    options: OZConnectWalletOptions = OZConnectWalletOptions()
) async throws -> OZConnectWalletResult?

Parameters


                                options

Connect-wallet options. Defaults to a silent session-only restore.

Return Value

OZConnectWalletResult or nil.

Show on GitHub


                    
                    
                    connectToContract(contractId:)

Asynchronous

Connects the kit to an already-deployed smart account by contract address, with no passkey credential.

Intended for headless callers — an autonomous signer (the reference agent) or a backend service — that operate the account through the multi-signer / external-signer pipeline (non-empty selectedSigners) and never present a passkey. Unlike connectWallet(options:), this does not run a WebAuthn ceremony, does not consult the credential manager, and does not persist a session; it also clears any previously saved session so a later silent reconnect cannot resurrect a stale passkey session.

After a headless connect the single-passkey paths (submit(hostFunction:auth:forceMethod:resolveContextRuleIds:), transfer(tokenContract:recipient:amount:decimals:forceMethod:), contractCall(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:), executeAndSubmit(target:targetFn:targetArgs:forceMethod:resolveContextRuleIds:), and any manager call left at the default empty selectedSigners) are NOT usable: they require a passkey credential and throw a clear error from the headless guard. Operate through kit.multiSignerManager or the sibling managers with an explicit non-empty selectedSigners list.

The contract address is validated and its on-chain existence is verified before the connected state is set.

Throws

InvalidAddress when contractId is not a valid contract address; NotFound when no contract instance exists at the address; SmartAccountTransactionException when the RPC existence check fails for transport reasons.

Declaration

Swift

public func connectToContract(contractId: String) async throws -> OZConnectToContractResult

Parameters


                                contractId

Smart account contract address (C… strkey).

Return Value

OZConnectToContractResult carrying the verified contractId.

Show on GitHub


                    
                    
                    authenticatePasskey(challenge:credentialIds:)

Asynchronous

Authenticates with a passkey without connecting to a wallet.

Used to authenticate the user before contract selection (for example to discover deployed contracts via the indexer) or for multi-signer operations that do not require a fully-connected kit state.

Throws

WebAuthnException (authentication failure / no provider), SmartAccountValidationException (signature normalisation failure).

Declaration

Swift

public func authenticatePasskey(
    challenge: Data? = nil,
    credentialIds: [String]? = nil
) async throws -> OZAuthenticatePasskeyResult

Parameters

`challenge`	Optional challenge bytes to sign. When `nil`, a fresh 32-byte random challenge is generated.
`credentialIds`	Optional list of allowed credential ids (Base64URL-encoded). When provided, only those credentials may be used by the authenticator.

Return Value

OZAuthenticatePasskeyResult carrying the credential id, normalised signature, and stored public key (when available).

Show on GitHub


                    
                    
                    deployPendingCredential(credentialId:autoSubmit:autoFund:nativeTokenContract:forceMethod:policies:)

Asynchronous

Deploys a wallet from a previously created pending credential.

Used to retry a failed deployment or to submit a wallet created with createWallet(autoSubmit: false). The credential must exist in storage with a valid publicKey and contractId.

Throws

SmartAccountCredentialException, SmartAccountValidationException, SmartAccountTransactionException.

Declaration

Swift

public func deployPendingCredential(
    credentialId: String,
    autoSubmit: Bool = true,
    autoFund: Bool = false,
    nativeTokenContract: String? = nil,
    forceMethod: OZSubmissionMethod? = nil,
    policies: [String: SCValXDR]? = nil
) async throws -> OZDeployPendingResult

Parameters

`credentialId`	Base64URL-encoded credential identifier of the credential to deploy.
`autoSubmit`	Whether to submit the deploy transaction. Defaults to `true` (this entry point is typically used to retry a failed deploy so callers usually want submission).
`autoFund`	Whether to fund the freshly deployed wallet using Friendbot (testnet only). Requires `autoSubmit = true`.
`nativeTokenContract`	Native token contract address used when `autoFund = true`.
`forceMethod`	Optional submission-method override.
`policies`	Policies to install on the default context rule at deploy time, keyed by policy contract address with the install-param ScVal as the value. `nil` (default) uses `defaultPolicies`; a non-`nil` map overrides it. Maximum `maxPolicies`.

Return Value

OZDeployPendingResult describing the deployment.

Show on GitHub