stellar-sdk/com.soneso.stellar.sdk.smartaccount.oz/OZWalletOperations/ConnectWalletOptions

ConnectWalletOptions

data class ConnectWalletOptions(val credentialId: String? = null, val contractId: String? = null, val fresh: Boolean = false, val prompt: Boolean = false)

Options for connecting to a wallet.

These options control how wallet connection is performed, allowing for different connection flows based on your application's needs.

Decision Matrix

Options	Behavior
(default)	Session restore, return null if no session
credentialId and/or contractId	Direct connect, skip session check
fresh = true	Skip session, always WebAuthn
prompt = true	Session restore, WebAuthn if no session
fresh = true, prompt = true	fresh takes priority, always WebAuthn

Option Patterns

Silent Session Check (default)

// Returns saved session if valid, null if no session
val result = connectWallet()
if (result == null) {
    // Show login UI
}

Session Check with WebAuthn Fallback

// Uses saved session if valid, prompts WebAuthn if no session
connectWallet(ConnectWalletOptions(prompt = true))

Direct Connection with Known Credentials

// Connect to specific contract using known credential ID
connectWallet(ConnectWalletOptions(
    credentialId = "abc123...",
    contractId = "CABC..."
))

Force Fresh Authentication

// Require WebAuthn authentication even if session exists
connectWallet(ConnectWalletOptions(fresh = true))

Credential-Only Connection

// Provide credential ID, look up contract from storage/indexer
connectWallet(ConnectWalletOptions(credentialId = "abc123..."))

Constructors

ConnectWalletOptions

constructor(credentialId: String? = null, contractId: String? = null, fresh: Boolean = false, prompt: Boolean = false)

Properties

contractId

val contractId: String?

Connect directly to this contract address (C-address). Must be used with credentialId. Cannot be used alone. Useful when you already know both the credential and contract.

credentialId

val credentialId: String?

Connect directly using this credential ID (Base64URL-encoded). When provided alone, contract address is looked up from storage, indexer, or derived from deployer. Skips WebAuthn authentication.

fresh

val fresh: Boolean

Force fresh WebAuthn authentication, skipping session restore. Use this to require re-authentication even if a valid session exists. Useful for sensitive operations or after session timeout warnings.

prompt

val prompt: Boolean

When true, triggers WebAuthn authentication if no valid session exists. When false (default), returns null if no session is found. Has no effect when fresh is true (WebAuthn is always triggered). Has no effect when credentialId is provided (direct connect path).