LazorKit LogoLazorKit
React Native SDK

Upgrading to 2.x

What changes when you move @lazorkit/wallet-mobile-adapter from 1.x or the 2.0.0 betas to 2.x, release by release.

@lazorkit/wallet-mobile-adapter 2.0.0 is the release that speaks protocol v2. 2.4.0 is the current release. Full notes: the package CHANGELOG and the Changelog here.

npm install @lazorkit/wallet-mobile-adapter@^2.4.0

Do not install @beta

The npm beta tag still points at 2.0.0-beta.4, a pre-v2 build from April 2026. Use latest (2.4.0).

The adapter depends on expo-web-browser ^14.2.0 || ^15.0.0 (Expo SDK 53 / 54) and expo-crypto ^15.0.8 (Expo SDK 54); it is built and tested against Expo SDK 54. Older Expo SDKs have not been tested.

Checklist

  1. smartWalletPubkey is the vault (since the April 2026 betas; 1.x stored the wallet PDA there). Persisted wallets are migrated on load. Use smartWalletPubkey (alias vaultPubkey) as the user's address; walletPdaPubkey is the internal wallet PDA. Do not derive addresses with findVaultPda: the PDA helpers derive v2 addresses at the mainnet id.
  2. Sessions need limits. createSession without actions throws unless you pass unrestricted: true.
  3. Authorities need a role, and Delegates a policy. addAuthorityEd25519 has no default role (since 2.3.0: see below). role: ROLE_SPENDER (Delegate) on a v2 wallet throws without policy: serializeActions([...]). On a v1 wallet it requires unrestricted: true and refuses a policy.
  4. v1 users need their relayer: set v1ConfigPaymaster when configPaymaster points at a v2 relayer. See Migrating from v1.
  5. RPC URLs that do not name a cluster need the cluster prop.
  6. connect may ask the user, with a chooser drawn as a React Native Modal. On iOS it cannot appear over another modal: see Wallet Confirmation › iOS. While a wallet is connected, connect returns it without opening the portal; disconnect first to connect another passkey.
  7. Sends resolve later and can reject in new ways (2.1.0). See Sending transactions.
  8. Callbacks run after isSigning clears (2.2.0; connect and disconnect too since 2.3.0), and the store's signAndExecuteTransaction, signMessage and transferSol resolve with their results.
  9. Removed or changed exports: the low-level create*Ix builders are gone (use LazorKitClient methods). readAuthorityState is still exported for compatibility; new code should prepare passkey challenges with @lazorkit/sdk-legacy's prepare* methods and their minContextSlot / commitment options (Passkey signing).
  10. Android redirects. More than one app can claim a custom URL scheme on Android. Prefer a redirect only your app can receive, such as a verified App Link; see Wallet Confirmation.
  11. Check message signatures with verifyWalletMessage (2.3.1), which reads the passkey's key from chain. See below.
  12. Name every mint a session or Delegate spends (2.4.0), with an Actions.token* action. From the v2 program release that adds errors 3037 and 3038, an asset the actions do not name cannot leave the wallet. See below.

Release by release

ReleaseWhat changes for you
2.0.0 (2026-09-29)Protocol v2 beside v1, routed per wallet: protocolVersion, v1ConfigPaymaster, cluster, V1WalletRetiredError, V1WalletMigratedError. Wallet confirmation: onConfirmWallet, confirmWallet, trustedAuthorities, watchMints, <WalletChooser />, WalletChooserNotShownError, PortalCancelledError. A signing action always rejects on failure (it could resolve undefined). The breaking items above.
2.1.0 (2026-09-30)Sends resolve once confirmed (polling, no websocket); new errors TransactionFailedError, TransactionExpiredError, TransactionOutcomeUnknownError, ConfirmationTimeoutError, PreviousTransactionPendingError, SignatureReusedError, PaymasterError. Passkey transactions are sequenced. A passkey with no wallet can connect (key recovered from two signatures, one extra prompt). Large previews use the lookup tables instead of failing before the portal. expo-web-browser 15 accepted.
2.2.0 (2026-09-30)Callbacks run after isSigning clears; a send from onSuccess runs. Deferred window: expiryOffset 10–9000, default 1500 (was 300). DeferredExpiredError and its helpers.
2.2.1 (2026-10-01)An inner program's 3014 is no longer reported as DeferredExpiredError; isDeferredExpiredError is true for every DeferredExpiredError; DeferredFailureContext.
2.3.0 (2026-10-02)Breaking: addAuthorityEd25519 needs a role. connect and disconnect follow the callback contract, on the hook and the store; transferSol with no wallet calls onFail. The is*Error predicates recognise the adapter's own errors through wrappers. See below.
2.3.1 (2026-10-02)Security: message signatures are domain-separated, so they can no longer be confused with transaction approvals; signMessage resolves with a SignMessageResult (two new fields); new verifyWalletMessage and verifySignedMessage. Ownership-proof challenges are domain-separated too. See below.
2.4.0 (2026-10-03)UnlistedSolOutflowError / UnlistedTokenOutflowError for the program's 3037 / 3038 (a session moving SOL, or a token, its actions do not name), with predicates and codes. ERROR_NAMES names 3036–3038 and 4018. Docs: name each mint, keep actions within 244 bytes. No disconnect change: the adapter keeps no session key. See below.

Keys

The adapter never stores session or authority keys: createSession and addAuthorityEd25519 take a public key, and you keep the secret key. Store it in the platform's secure storage (for example expo-secure-store), not in AsyncStorage. What the adapter keeps in AsyncStorage: the wallet record and config (lazor-wallet-store), and per passkey the slot of its last transaction and any send whose outcome is unknown (lazorkit:passkey-lane:…, the slot for ten minutes).

Keep the wallet a session key belongs to with the key, use the key only while that wallet is connected, and delete it at disconnect and once its session is revoked or expired. The package README's Session keys section (2.3.0) shows this with expo-secure-store.

Upgrading to 2.4.0

From 2.3.1. Nothing was removed, and no call changes shape. Full notes: the package CHANGELOG.

  1. Name every mint a session spends. From the v2 program release that adds errors 3037 and 3038, a session's actions (and a Delegate's policy) name what may leave the wallet, and nothing else may: SOL leaves only with an Actions.sol* action, rent the vault pays for a new account included, and a token only with an Actions.token* action for its mint. wSOL is a mint of its own. That release is not deployed yet; until it is, an asset the actions do not name is not bounded at all, so a session with token actions only can spend all the wallet's SOL. See Session Keys › What a policy bounds.
  2. Sessions and Delegates that name SOL only move no token once that release is deployed. Revoke them (revokeSession, or removeAuthority for a Delegate) and register ones whose actions name the mints they spend. The program does not create a second session for a key while the first exists: revoke first, or use a new key.
  3. Keep actions within 244 bytes. A session's actions, and a Delegate's policy, must fit in the transaction that registers them, beside the passkey's response. An Actions.sol* action takes 19 bytes (solRecurringLimit 43), tokenMaxPerTx and tokenLimit 51, tokenRecurringLimit 75: solMaxPerTx with tokenMaxPerTx and tokenLimit for 2 mints, or with tokenMaxPerTx for 4. The adapter does not check this before the portal opens: actions that do not fit fail after the user approved.
  4. New errors. signAndSendWithSession rejects with UnlistedSolOutflowError ("This session is not allowed to spend SOL") for a 3037 and UnlistedTokenOutflowError ("This session is not allowed to spend this token") for a 3038, with the original error as cause. A send whose outcome is unknown stays TransactionOutcomeUnknownError. Match them with isUnlistedSolOutflowError / isUnlistedTokenOutflowError, which also recognise a raw 3037 / 3038 through wrappers; codes UNLISTED_SOL_OUTFLOW_CODE, UNLISTED_TOKEN_OUTFLOW_CODE. See Errors › Assets a policy does not name.
  5. ERROR_NAMES / errorFromCode name 3036 (SessionNotExpired), 3037, 3038 and 4018 (RetiredDeployment).

Upgrading to 2.3.1

From 2.3.0. Nothing was removed, and no call changes shape; what changes is what your server checks. Full notes: the package CHANGELOG.

  1. Verify message signatures with verifyWalletMessage. signMessage signs signedMessageChallenge(message), a 58-byte challenge tagged LazorKit signed message v1, never the message's bytes, so a message signature can no longer be confused with a transaction approval. It resolves with a SignMessageResult: signature and signedPayload as before, plus clientDataJsonBase64 and authenticatorDataBase64. Send all four to your server with the wallet and its credentialId, and check them with verifyWalletMessage, which reads the passkey's key from chain. A signature made by 2.3.0 or earlier does not verify: ask the user to sign again. See useWallet › Verifying a message signature.
  2. Do not check a message signature against a key the client sends (such as passkeyPubkey): use verifyWalletMessage, or verifySignedMessage with a key you read from the wallet's authority on chain.
  3. Ownership proofs. connect signs LazorKit ownership proof v1 followed by 32 random bytes (59 bytes), from createOwnershipChallenge(). verifyOwnershipProof accepts it unchanged.
  4. New dependency: @noble/curves, already a dependency of @solana/web3.js.

Upgrading to 2.3.0

From 2.2.x. Full notes: the package CHANGELOG.

  1. addAuthorityEd25519 needs a role (breaking). There is no default any more. A call without role does not compile, and at runtime a missing role, or one that is not ROLE_OWNER, ROLE_ADMIN or ROLE_SPENDER, throws before the portal opens. So does ROLE_OWNER on a v2 wallet, where the adapter never adds an Owner. Migration: addAuthorityEd25519({ newEd25519Pubkey, role: ROLE_SPENDER, policy }, options) keeps 2.2.1's behaviour. Ranks: useWallet › addAuthorityEd25519.
  2. connect and disconnect callbacks follow the sign actions' contract: they run once the call is over, and a throwing onSuccess is logged and changes nothing (in 2.2.1 it made the call reject). The store's connect calls onSuccess / onFail (2.2.1 ignored them), and its disconnect takes them. A second connect while one runs calls onFail at once.
  3. transferSol with no wallet connected calls onFail and sets error, as every other action does (2.2.1 rejected without either).
  4. Predicates. isSignatureReusedError, isRetiredDeploymentError and isDeferredExpiredError recognise the adapter's own errors, through cause and a wallet-adapter WalletError, so they work where instanceof does not.