Upgrading to 3.x
What changes when you move @lazorkit/wallet from 2.x to 3.x, release by release, and what to change in your app.
@lazorkit/wallet 3.0.0 is the release that speaks protocol v2. 3.4.0 is the current
release. Full notes: the package
CHANGELOG
and the Changelog here.
npm install @lazorkit/wallet@^3.4.0 @solana/web3.js@^1.99.0@solana/web3.js must be 1.99 or later (3.0.1): @solana/wallet-adapter-base
0.9.28 requires it, and an app pinned to 1.98.x gets npm ERESOLVE. The package also
declares react, react-dom, zustand, @solana/wallet-adapter-base,
@solana/wallet-standard-features and @wallet-standard/* as peers. Since 3.3.1 it no
longer declares @solana/kit, @solana/kora or @solana-program/token, which it never
loaded: it installs next to @solana/kit 6, 7 or 8 without --legacy-peer-deps.
Checklist
- Show and fund
vaultPubkey.smartWalletPubkey/wallet.smartWalletis the wallet PDA, which nothing can spend from. UseuseWallet().vaultPubkey(orwallet.vaultPda) as the user's address and asfromPubkey. Do not derive it withfindVaultPda: the exported PDA helpers derive v2 addresses at the mainnet id, which is wrong for v1 wallets and for devnet. Wallets saved withoutvaultPdaget it on the nextconnect. - Sessions need limits.
createSession()withoutspendingLimitsthrows, unless you passunrestricted: true. A session without limits can spend the whole vault through any program until it expires. - Authorities need a role, and Delegates a policy.
addAuthorityhas no default role (since 3.3.0: see below).addAuthority({ role: ROLE_SPENDER })on a v2 wallet throws withoutpolicy: serializeActions([...]). On a v1 wallet,addAuthorityrequiresunrestricted: trueand refuses a policy. - v1 users need their relayer. If
paymasterConfigpoints at a v2 relayer (LazorKit's does not sponsor v1), setv1PaymasterConfigto the relayer you used before. See Migrating from v1. - RPC URLs that do not name a cluster need
cluster="devnet"orcluster="mainnet"; anything unrecognised is taken as mainnet. connectmay ask the user. With no stored wallet,connectuses a wallet on its own only when it is the one wallet the passkey has signed for and nothing else can spend from it; otherwise it shows the built-in chooser. See Wallet Confirmation.- Sends resolve later, and can reject in new ways (3.1.0). Every send resolves once
confirmed, and
isSigningstaystrueuntil then. Handle the new errors; see Sending transactions. - Wallet adapter / Wallet Standard:
publicKeyis now the vault (it used to be the wallet PDA). - No 2.1.0 export was removed. The package CHANGELOG lists the
create*Ixbuilders,appendProtocolFeeAccounts,readAuthorityState,findOwnedCandidates,provenCandidates,chooseOwnWalletandOwnedCandidateas removed, but no published 2.x exported them, so there is nothing to replace. Coming from 2.0.0 or 2.0.1: the contract helpers those exported (LazorkitClient,deriveSmartWalletPda, theassert*/validate*utilities and others) were already dropped in 2.1.0. PROGRAM_ID/PROGRAM_ADDRESSare the v2 mainnet id. Use thePROGRAM_ID_*constants (Networks & versions) when you need a specific one.- Check message signatures with
verifyWalletMessage(3.3.1), never with the deprecatedverifyMessage. See below. - Name every mint a session or Delegate spends (3.4.0):
spendingLimits.tokens, or aToken*action in a policy. From the v2 program release that adds errors 3037 and 3038, an asset the limits do not name cannot leave the wallet. See below.
Release by release
| Release | What changes for you |
|---|---|
| 3.0.0 (2026-09-29) | Protocol v2 support beside v1, routed per wallet: protocolVersion, v1PaymasterConfig, cluster, V1WalletRetiredError, V1WalletMigratedError. Wallet confirmation: onConfirmWallet, confirmWallet, trustedAuthorities, watchMints, the built-in chooser, PortalCancelledError (closing the portal now rejects at once). The breaking items in the checklist above. |
| 3.0.1 (2026-09-29) | Peer @solana/web3.js ^1.99.0. |
| 3.0.2 (2026-09-29) | No global Buffer polyfill needed. The wallet adapter reads at confirmed (it read at finalized, up to 15 s behind, and could fail a second send with 3006). |
| 3.1.0 (2026-09-30) | Sends resolve once confirmed; new errors TransactionFailedError, TransactionExpiredError, TransactionOutcomeUnknownError, ConfirmationTimeoutError, PreviousTransactionPendingError, SignatureReusedError, PaymasterError. Passkey transactions are sequenced (no more 3006 back to back). A passkey with no wallet can connect: its key is recovered from two signatures, at the cost of one extra prompt. dApp v0 transactions with lookup tables work through the adapter. |
| 3.2.0 (2026-09-30) | Deferred window: expiryOffset 10–9000 slots, default 1500 (was 300). DeferredExpiredError, isDeferredExpiredError, MIN_/MAX_DEFERRED_EXPIRY_SLOTS, DEFERRED_EXPIRED_CODE. |
| 3.2.1 (2026-10-01) | An inner program's 3014 is no longer reported as DeferredExpiredError; isDeferredExpiredError is true for every DeferredExpiredError; DeferredFailureContext on TX2 errors. |
| 3.3.0 (2026-10-02) | Breaking: addAuthority needs a role. Session and authority keys kept as non-extractable WebCrypto keys in IndexedDB, not plaintext localStorage: keyStorage, forgetStoredKeys(). A kept key signs only for its own wallet: KeyWalletMismatchError, isKeyWalletMismatchError. disconnect deletes the session key unless keepSessionKeys; expired session keys are deleted. Callbacks run once the action is over, one per call. The is*Error predicates recognise the SDK's own errors through wrappers. A 4018 is not resent. See below. |
| 3.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; verifyMessage and verifySignatureBrowser deprecated. Ownership-proof challenges are domain-separated too. LazorkitWalletAdapter.disconnect() and standard:disconnect delete the session key. The sign dialog sends the stored credentials to the portal's origin only. Peers @solana/kit, @solana/kora, @solana-program/token dropped. See below. |
| 3.4.0 (2026-10-03) | Security: a session or authority send running when the wallet is disconnected, whichever way, neither signs nor sends after it (KeyWalletMismatchReason 'disconnected'), and LazorkitWalletAdapter.disconnect() / standard:disconnect disconnect the store too. SpendingLimits.tokens, checked before the prompt (at most 244 bytes of actions); spendingLimitsToActions; UnlistedSolOutflowError / UnlistedTokenOutflowError for 3037 / 3038, not resent. Changed: createSession with a sessionKey that already has a session checks the limits first. Paymaster option beforeAttempt. See below. |
Keys the SDK keeps in the browser
createSession (without sessionKey) and addAuthority generate an Ed25519 key and keep
it, so that signAndSendWithSession / signAndSendWithAuthority sign without a prompt.
Since 3.3.0 each key is a non-extractable WebCrypto key in IndexedDB, signs only while the
wallet it was registered for is connected, and the session key is deleted at disconnect
(also through wallet-adapter and the Wallet Standard, since 3.3.1, which since 3.4.0
disconnect the store too). Since 3.4.0 a send that loaded its key before any disconnect
neither signs nor sends after it. See
What the SDK stores. A
sessionKey you pass is never stored.
3.2.1 and earlier kept the secret key in localStorage as plain text, under
lazorkit-session and lazorkit-authority, where any script on your origin could read
it, and disconnect did not remove it. 3.3.0 moves such a key to IndexedDB (item 5
below).
Upgrading to 3.4.0
From 3.3.1. Nothing was removed. Items 1 and 2 change what a disconnect stops; items 3 to
6 how a session or Delegate names what it may spend, and item 4 has a behaviour change for
a sessionKey of your own. Full notes: the package
CHANGELOG.
- A wallet-adapter or Wallet Standard sign-out disconnects the store.
LazorkitWalletAdapter.disconnect()andstandard:disconnectnow disconnect it asuseWallet().disconnect()does:useWallet()shows no wallet (also after a reload), aconnectthe store is running rejects withPortalCancelledError,erroris cleared, andisSigningis left to the action running. A kept key signs only once its wallet is connected again. In 3.3.1 they deleted the session key but left the store connected, so the authority key, and a session key kept withkeepSessionKeys, went on signing for the wallet with no reconnect. If your app readsuseWallet()next to a wallet-adapter UI, expect it to disconnect with the adapter.keepSessionKeysstill decides only whether the session key is deleted. - A send running at a disconnect is not finished. A
signAndSendWithSessionorsignAndSendWithAuthoritythat loaded its kept key before any disconnect (the store's, the adapter's, the Wallet Standard's) is refused right before the key signs, and again right before each attempt to send, retries included. It rejects withKeyWalletMismatchError:reason'no-wallet', or the new'disconnected'when the same wallet is connected again by then. Handle'disconnected'by sending again. A refusal after the key signed says "The transaction it had signed was not sent." If an earlier attempt got no answer from the paymaster, that attempt may still land: the send rejects withTransactionOutcomeUnknownError, as before, and is not sent again. AswitchonKeyWalletMismatchReasongains a case. - Name every mint a session spends.
SpendingLimitstakestokens: one entry per mint,{ mint, lifetimeCap?, perTxMax?, recurring?: { limit, windowSlots } }, amounts in the mint's base units. wSOL is a mint of its own. From the v2 program release that adds errors 3037 and 3038, a session moves SOL only with a SOL limit (rent the vault pays for a new account included) and a token only with atokensentry for its mint; that release is not deployed yet, and until it is an asset the limits do not name is not bounded at all. A session made with SOL limits only, as every session made withSpendingLimitsbefore 3.4.0, will move no token once the program release is deployed: create a new one that names the mints it spends. See Session Keys › What a policy bounds. createSessionchecks the limits before anything is read or the passkey is asked, and throws on atokensentry with no limit, a mint named twice, an amount outside a u64, a window of 0 slots (which the program refuses), more than 16 actions, or more than 244 bytes of actions: what fits in the transaction beside the passkey's response. A SOL limit takes 19 bytes (solRecurring43), a token'slifetimeCaporperTxMax51, itsrecurring75. Behaviour change for asessionKeyof your own that already has a session: the limits are checked before the SDK looks for that session, so a call with nospendingLimits(and notunrestricted), or invalid ones, now throws where 3.3.1 resolved with the existing session. With valid limits it still resolves with the session as it was made, whatever limits you pass: to change an external key's limits, revoke its session (revokeSession({ sessionPda })) or register a new key.- Delegate policies. A
policyforaddAuthoritynames what may leave the wallet in the same way: name SOL with aSol*action and each mint with aToken*action, or build it withserializeActions(spendingLimitsToActions(limits))(new). Keep it within 244 bytes:addAuthoritydoes not check its size, and a policy that does not fit fails after the user approved. - New errors for the program's refusals, which
signAndSendWithSessionandsignAndSendWithAuthorityreject with:UnlistedSolOutflowError(3037, "This session is not allowed to spend SOL") andUnlistedTokenOutflowError(3038, "This session is not allowed to spend this token"; "This key …" for a Delegate), withsignerand the original error ascause. Match them withisUnlistedSolOutflowError/isUnlistedTokenOutflowError, which also recognise a raw 3037 / 3038 through wrappers. A send whose outcome is unknown staysTransactionOutcomeUnknownError. The paymaster does not resend a 3037 or 3038, unless an earlier attempt's answer was lost. See Errors › Assets a policy does not name. ERROR_NAMES/errorFromCodename 3036 (SessionNotExpired), 3037, 3038 and 4018 (RetiredDeployment).- A
Paymasteryou construct takesbeforeAttemptin its options: it runs right before each attempt to send, retries included, and what it throws stops the send.
Upgrading to 3.3.1
From 3.3.0. Nothing was removed, and no call changes shape; items 1 to 3 change what your server checks, and item 4 what a sign-out deletes. Full notes: the package CHANGELOG.
- Verify message signatures with
verifyWalletMessage.signMessage(the hook, the store,LazorkitWalletAdapter.signMessageand the Wallet Standardsolana:signMessage) signssignedMessageChallenge(message), a 58-byte challenge taggedLazorKit signed message v1, never the message's bytes, so a message signature can no longer be confused with a transaction approval. It resolves with aSignMessageResult:signatureandsignedPayloadas before, plusclientDataJsonBase64andauthenticatorDataBase64. Send all four to your server with the wallet and itscredentialId, and check them withverifyWalletMessage, which reads the passkey's key from chain. A signature made by 3.3.0 or earlier does not verify: ask the user to sign again. See useWallet › Verifying a message signature. - Stop authenticating with
verifyMessageorverifySignatureBrowser. Both are deprecated. They check only thatsignatureis oversignedPayload, not which message was signed, so any assertion the passkey ever made passes. - Adapter and Wallet Standard signatures are still the UTF-8 bytes of a JSON object,
now with the four
SignMessageResultfields: passJSON.parse(new TextDecoder().decode(signature))toverifyWalletMessage. They are not a 64-byte Ed25519 signature: a LazorKit address is a program account, with no key to sign with. - A wallet-adapter or Wallet Standard sign-out deletes the session key.
LazorkitWalletAdapter.disconnect()(what a wallet-adapter UI's Disconnect calls) andstandard:disconnectdelete the session key the SDK keeps, asuseWallet().disconnect()has since 3.3.0. To keep it, calladapter.disconnect({ keepSessionKeys: true })(new typeLazorkitAdapterDisconnectOptions);standard:disconnecttakes no options, so it always deletes it. The authority key is kept on both paths;forgetStoredKeys()deletes it. - Ownership proofs.
createOwnershipChallenge()from@lazorkit/walletreturnsLazorKit ownership proof v1followed by 32 random bytes (59 bytes), andconnectsigns that.verifyOwnershipProofaccepts it unchanged. - Install. The unused peers
@solana/kit^5,@solana/koraand@solana-program/tokenare gone, so the wallet installs next to@solana/kit8. Drop--legacy-peer-depsif you added it for them. - The portal's origin. The sign dialog posts the stored credential id, passkey public
key and wallet address only to the origin of
portalUrl, never to whatever page its iframe shows. A portal that stays on its own origin sees no change. KeepportalUrlan absolute URL: with one that has no origin to address, nothing is posted.
Upgrading to 3.3.0
From 3.2.x. Full notes: the package CHANGELOG.
addAuthorityneeds arole(breaking). There is no default any more. A call withoutroledoes not compile, and at runtime a missing role, or one that is notROLE_OWNER,ROLE_ADMINorROLE_SPENDER, throws before anything is read or the passkey is prompted. So doesROLE_OWNERon a v2 wallet, whereaddAuthoritynever adds an Owner. Migration:addAuthority({ role: ROLE_ADMIN, ... })keeps 3.2.1's behaviour; for a key your app spends with, preferrole: ROLE_SPENDERwith apolicy. Ranks: useWallet › addAuthority.- Kept keys sign only for their own wallet.
signAndSendWithSession,signAndSendWithAuthorityandrevokeSession()(withoutsessionPda) need the key's wallet connected. Where you sent beforeconnectresolved (on page load, say), wait for the wallet. Otherwise they reject withKeyWalletMismatchError: handleisKeyWalletMismatchError(e)by creating a session (adding an authority) for the connected wallet, or by asking the user to connect the key's wallet. See Errors. disconnectdeletes the session key, whichever wallet it belongs to, and acreateSessionstill waiting for its transaction keeps no key once it lands. To keep a session across sign-out and sign-in, passdisconnect({ keepSessionKeys: true }); otherwise the user approves a new session after connecting again. The authority key is kept, and signs once the same wallet is connected again.disconnectacts in its own tab: another tab of the app stays connected.- Sign-out code. Removing
lazorkit-session/lazorkit-authorityfrom localStorage, orlocalStorage.clear(), no longer removes the keys: they are in IndexedDB, shared by every tab. CallforgetStoredKeys(), which deletes both (and keeps none for a session or authority still landing). - Keys from 3.2 and earlier move to IndexedDB when
LazorkitProvidermounts, or on first use. On first use each is bound to its wallet, when that can be confirmed from the session or authority PDA or from the account on chain. One whose wallet cannot be confirmed is never used (reason: 'unbound'): create the session (add the authority) again, which replaces it (forgetStoredKeys()would also delete the other kept key). The move is one-way: going back to 3.2.1 finds no key, and the user creates a new session. - Expired session keys are deleted when next read; the call rejects with "No session key found: … expired after slot …". Create a new session.
- Callbacks run once the action is over (
isSigningorisConnectingalreadyfalse), exactly one per call. A send started fromonSuccessruns, and a callback that throws is logged and changes nothing. Refusals ("Already signing", "No wallet connected", "Already connecting") callonFailtoo.disconnect,removeAuthorityandsignMessagetakeonSuccess/onFail, onuseWallet()and on the store. See Sending transactions › Callbacks. - Predicates.
isSignatureReusedError,isRetiredDeploymentErrorandisDeferredExpiredErrorrecognise the SDK's own errors, throughcauseand a wallet-adapterWalletError, so they work whereinstanceofdoes not. - A 4018 is not resent. The paymaster fails on the first answer, with
V1WalletRetiredErrorfor a retired v1 wallet, instead of after 3 attempts. - Optional:
keyStorage="memory"onLazorkitProviderkeeps no key at rest (What the SDK stores).