Migrate the React Native SDK from 0.3 to 0.4

Version 0.4.0 of the React Native SDK uses version 0.4.0 of the Swift and Kotlin SDKs. It replaces the wallet address and expiry APIs with the active wallet and session change APIs, and adds Tron wallets and claimable wallets. This page covers the changes most applications need. The full migration guide lists every change.

Run `pod install` after upgrading

On iOS, the module now pulls the Swift SDK with Swift Package Manager instead of the oms-wallet-swift-sdk pod, which is no longer published to CocoaPods. Run pod install after upgrading, and keep the react_native_post_install call in your Podfile’s post_install hook, as in the React Native template; Expo adds it for you. Remove any pod 'oms-wallet-swift-sdk' line you added yourself. The native SDKs store sessions in a new format and do not restore sessions saved by 0.3, so each user signs in once after the upgrade.

Read the active wallet

getWalletAddress() was removed. Read the active WalletAccount from the synchronous activeWallet property; it is undefined when signed out. Check its type before passing the address to chain-specific code.

// 0.3
const address = await omsWallet.wallet.getWalletAddress()

// 0.4
const activeWallet = omsWallet.wallet.activeWallet
if (activeWallet?.type === 'ethereum') {
  const address = activeWallet.address
}

WalletActivationResult and CompleteAuthResult no longer have walletAddress; use result.wallet.address.

Read `session` instead of `getSession()`

getSession() was removed. Read the synchronous session property, an OMSWalletSession (renamed from OMSWalletSessionState) or undefined when signed out. In 0.3, getSession() resolved to an object whose fields were undefined when signed out. The session has no walletAddress; its expiresAt and auth are always set, and it is defined exactly when activeWallet is.

// 0.3
const email = (await omsWallet.wallet.getSession()).auth?.email

// 0.4
const email = omsWallet.wallet.session?.auth.email

activeWallet and session are current as soon as a sign-in or wallet change returns, and they return the same frozen objects until the state changes, so React components can read them with useSyncExternalStore.

`new OMSWallet()` throws when the client cannot be created

The constructor now creates the native client synchronously. When that fails, for example for an invalid publishable key, new OMSWallet() throws OMSWalletError instead of the first call rejecting.

Replace `onSessionExpired` with `onSessionChange`

onSessionChange reports every change of the active wallet or session with a reason: signedIn, walletChanged, expiryUpdated, signedOut, or expired. An expired change carries the ended session as expiredSession, which replaces OMSWalletSessionExpiredEvent.

// 0.3
omsWallet.wallet.onSessionExpired(({ session }) => showSignIn(session.auth))

// 0.4
const unsubscribe = omsWallet.wallet.onSessionChange((event) => {
  if (event.reason === 'expired') showSignIn(event.expiredSession.session.auth)
})

onSessionChange returns a function that removes the listener, instead of an EventSubscription: call unsubscribe() instead of subscription.remove(). As before, a listener added while signed out first receives the last expired change. See sessions and access.

Renamed parameters and new cases

importEncryptedWallet takes walletType instead of type, matching createWallet:

// 0.3
await omsWallet.wallet.importEncryptedWallet({ type: 'solana', keyMaterial })

// 0.4
await omsWallet.wallet.importEncryptedWallet({ walletType: 'solana', keyMaterial })

WalletType and ImportWalletParams gained tron, and OMSWalletErrorCode gained OMS_WALLET_ADDRESS_ALREADY_IMPORTED, which importing an already imported address now throws instead of OMS_REQUEST_FAILED. Update exhaustive switch statements over them. The isValid…Signature methods accept an optional walletAddress to verify any wallet, even while signed out. Existing calls are unchanged and still verify against the active wallet.

Behavior changes

These need no code change to compile, but can change what your application sees:

Session expiry extends with use. session.expiresAt is the current expiry, not a fixed end time. An idle session ends about 10 days after its last use, and never after the requested lifetime. Sign-in now requests 180 days instead of 7 when sessionLifetimeSeconds is omitted; pass a shorter value for a hard limit. Listen for expiryUpdated instead of treating expiresAt as final.
Rejected credentials end the session. A wallet call whose credential the wallet API rejects as not found or expired fails with OMS_SESSION_EXPIRED instead of OMS_REQUEST_FAILED, and the session ends with an expired change. When the wallet API cannot be reached, the session is kept and calls fail with OMS_REQUEST_FAILED.
Signed requests time out after 30 seconds with OMS_REQUEST_FAILED, counting the time spent waiting behind other signed requests, which are now sent one at a time. A transaction that times out after it was sent still fails with OMS_TRANSACTION_EXECUTION_UNCONFIRMED: check its status before sending it again.
Refused transactions fail as request errors. A transaction the wallet API refuses before submitting it, for example because simulation shows it would revert, fails with OMS_REQUEST_FAILED (or OMS_SESSION_EXPIRED when the session has ended) instead of OMS_TRANSACTION_EXECUTION_UNCONFIRMED. It was never submitted.
callContract takes a bare method name. Pass 'transfer', not 'transfer(address,uint256)'. A full signature now fails with OMS_VALIDATION_ERROR before any request.
Invalid lifetimes fail early. A sessionLifetimeSeconds that is not an integer from 1 to MAX_SESSION_LIFETIME_SECONDS fails with OMS_VALIDATION_ERROR on both platforms before any request.
Sign-in claims a claimable wallet. With automatic selection, a user with no wallet of the requested type but a claimable one gets that wallet instead of a new one.
iOS keys stay on the device. On an iOS device, the session signing key is generated in the Secure Enclave, and keychain items are readable only while the device is unlocked and are never restored to another device from a backup.

​Run pod install after upgrading

​Users sign in once after upgrading

​Read the active wallet

​Read session instead of getSession()

​new OMSWallet() throws when the client cannot be created

​Replace onSessionExpired with onSessionChange

​Renamed parameters and new cases

​Behavior changes