> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate the TypeScript SDK from 0.3 to 0.4

> Update an application from @polygonlabs/oms-wallet 0.3 to 0.4.

Version 0.4.0 of `@polygonlabs/oms-wallet` changes how the active wallet and session are read, replaces the expiry callback with a session change callback, and renames several parameters and types. This page covers the changes most applications need. The [full migration guide](https://github.com/0xPolygon/oms-wallet-typescript-sdk/blob/master/packages/oms-wallet/MIGRATION.md) lists every change.

If you use the wagmi connector, upgrade `@polygonlabs/oms-wallet-wagmi-connector` to the same version. Both packages are released together. The connector now follows the session: it disconnects when the session ends or a non-Ethereum wallet becomes active.

## Users sign in once after upgrading

Version 0.4.0 stores sessions in a new format, per project and environment, and does not restore sessions saved by 0.3. Each user signs in once after the upgrade. The 0.3 records are left in storage unread.

## Read the active wallet

`omsWallet.wallet.walletAddress` was removed. Read `omsWallet.wallet.activeWallet`, a `WalletAccount` or `undefined` when signed out. Narrowing on `type` gives an Ethereum wallet a viem `Address`.

```typescript theme={null}
import { WalletType } from '@polygonlabs/oms-wallet'

// 0.3
const address = omsWallet.wallet.walletAddress

// 0.4
const activeWallet = omsWallet.wallet.activeWallet
if (activeWallet?.type === WalletType.Ethereum) {
  const address = activeWallet.address
}
```

Auth results and `WalletActivationResult` no longer have `walletAddress`. Use `result.wallet.address`.

## Check `session` for `undefined`

`omsWallet.wallet.session` is now `OMSWalletSession | undefined` (renamed from `OMSWalletSessionState`). In 0.3 it was an object whose fields were `undefined` when signed out. `session` is defined exactly when `activeWallet` is, and its `expiresAt` and `auth` are always set.

```typescript theme={null}
// 0.3
const email = omsWallet.wallet.session.auth?.email

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

Both values are frozen. Copy them before changing them.

## 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`.

```typescript theme={null}
// 0.3
omsWallet.wallet.onSessionExpired(({ session }) => showSignIn(session.auth))

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

Listeners run shortly after the change, not during the call that made it. With the default browser storage, changes made in other tabs of the same origin are reported too. See [Sessions and access](https://docs.polygon.technology/wallets/sdk/typescript/sessions-and-access.md).

## Renamed parameters and types

| 0.3 | 0.4 |
| - | - |
| `createWallet({ type })` | `createWallet({ walletType })` |
| `importEncryptedWallet({ type, keyMaterial })` | `importEncryptedWallet({ walletType, keyMaterial })` |
| `isValid…Signature({ walletId, … })` | `isValid…Signature({ walletAddress, … })`, or omit `walletAddress` for the active wallet |
| `feeOption.token.logoURL`, `tokenID` | `feeOption.token.logoUrl`, `tokenId` |
| `OMSWalletClient`, `OMSWalletIndexerClient` | `WalletClient`, `IndexerClient` |
| `OMSWalletSessionState` | `OMSWalletSession` |
| `OMSWalletSessionExpiredListener` | `OMSWalletSessionChangeListener` |
| `AuthMode.OTP`, `AuthMode.IDToken` | Removed. `AuthMode` lists only the OIDC redirect modes. |

TypeScript reports each of these. In untyped JavaScript, `createWallet({ type })` silently creates an Ethereum wallet, so search for these calls.

`upstreamError.code` is now a string: compare with `'7313'`, not `7313`. TypeScript flags comparisons and `switch` cases against numbers, but untyped JavaScript, values typed `any`, and logs that record the code now see a string.

`WalletType` gained `Tron`. Exhaustive `switch` statements over `WalletType` or `WalletAccount` need a `tron` case.

## 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. The default lifetime is now 180 days instead of one week; pass `sessionLifetimeSeconds` for a hard limit. Listen for `expiryUpdated` instead of treating `expiresAt` as final.
* **The expiry is checked when it passes.** When `expiresAt` passes, a session past its requested lifetime ends at once. Otherwise the SDK asks the wallet API, once the page is shown, and reports `expired` only if the session ended.
* **Signed requests time out after 30 seconds** with `OMS_REQUEST_FAILED` (`retryable: true`), 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, so there is nothing to check.
* **`callContract` takes a bare method name.** Pass `'transfer'`, not `'transfer(address,uint256)'`. A full signature now throws `OMS_VALIDATION_ERROR` 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.
* **Instances of one project share one wallet.** Creating `OMSWallet` again for the same project and environment, with the same storage, returns the same wallet, so signing out or switching wallets applies to both. Passing one `storage` object with a different `credentialSigner` or `redirectAuthStorage` throws `OMSWalletValidationError`, so outside a browser, instances that share a `storage` must also share a `credentialSigner`.