connectWallet

Connects to an existing smart account wallet.

Returns a ConnectWalletResult on successful connection, or null if no valid session exists and neither ConnectWalletOptions.prompt nor ConnectWalletOptions.fresh is set.

The non-null result is one of two sealed arms:

• ConnectWalletResult.Connected: a single contract was resolved, the kit's connected state has been set, and a session has been saved.

• ConnectWalletResult.Ambiguous: the indexer reported multiple contracts where the passkey is registered as a signer. The connected state has NOT been set; the caller must let the user pick a contract and re-call connectWallet(ConnectWalletOptions(credentialId, contractId = chosen)) to finalize.

Connection flow:

1. If credentialId/contractId provided: direct connect via connectWithCredentials.

2. If fresh = true: skip session, trigger WebAuthn authentication.

3. Otherwise, check storage for a valid (non-expired) session. If a valid session is found, verify the contract on-chain and reconnect. If verification returns NotFound (contract is not on-chain), clear the stale session and continue. Other exceptions during session verification propagate (the saved session is preserved so the user can retry once their network is healthy).

4. If no valid session and prompt = false: return null.

5. If no valid session and prompt = true: trigger WebAuthn authentication.

6. Resolve the contract via the cascade: storage → derivation → indexer. Storage with FAILED deployment status throws with a recovery hint. Derivation under the configured deployer is checked on-chain; if the address has no contract, falls through to the indexer. Indexer returns 0 / 1 / N>1 contracts mapping to NotFound / Connected / Ambiguous respectively.

7. On Connected: save session, set kit connected state, return. On Ambiguous: return early without saving a session.

Connection Options

Silent Session Check (default)

val result = walletOps.connectWallet()
when (result) {
    null -> println("No active session - show login UI")
    is ConnectWalletResult.Connected -> println("Connected: ${result.contractId}")
    is ConnectWalletResult.Ambiguous -> { /* unreachable for the silent path */}
}

Session Check with WebAuthn Fallback

val result = walletOps.connectWallet(
    ConnectWalletOptions(prompt = true)
)
when (result) {
    null -> { /* unreachable when prompt = true */}
    is ConnectWalletResult.Connected -> println("Connected: ${result.contractId}")
    is ConnectWalletResult.Ambiguous -> showPicker(result.candidates)
}

Direct Connection

val result = walletOps.connectWallet(
    ConnectWalletOptions(
        credentialId = "abc123...",
        contractId = "CABC..."
    )
)
// Explicit contractId bypasses the cascade. The non-null result is
// always Connected; Ambiguous is by-construction unreachable.

Force Fresh Authentication

val result = walletOps.connectWallet(
    ConnectWalletOptions(fresh = true)
)
// Always prompts WebAuthn, ignoring any saved session.

IMPORTANT: Requires a WebAuthnProvider to be configured in the kit config when WebAuthn authentication is needed (prompt = true or fresh = true).

Parameters

See also

Throws