Upgrading

Upgrade the package, then refresh the agent kit so your coding agent keeps targeting the current API. If you are coming from 2.6.2 or earlier, read From 2.6.2 or earlier before you upgrade.

Upgrade the package

pnpm add wative-core@latest
pnpm exec wative-core init-agent          # refresh the kit after an upgrade
pnpm exec wative-core init-agent --check  # in CI: fail if the kit is stale

npm i wative-core@latest
npx wative-core init-agent          # refresh the kit after an upgrade
npx wative-core init-agent --check  # in CI: fail if the kit is stale

init-agent rewrites the kit for the installed version, keeping an existing AGENTS.md unless you pass --force. --check exits non-zero when the kit was generated from a different wative-core version than the one installed. See Agent quick-start.

From 2.6.2 or earlier

Which workspaces are affected

Anything IdbProvider or HybridProvider wrote before 2.6.3 is in the older format:

• every browser workspace on the default provider — IdbProvider, including the one Workspace.open(...) uses when you pass no provider;
• a Node workspace created before 2.4.1, even if a later version has opened it since;
• a Node workspace written through an explicit new HybridProvider(...), or through the Node default on a machine where @node-rs/argon2 was not installed.

A workspace that only IdbProviderV3 or HybridProviderV3 ever wrote opens unchanged.

What you see

Workspace.open, ws.unlock(), Workspace.openWithSessionKey() and a provider's unlockContainer / unlockContainerWithKey throw a WativeError with code DECRYPT_FAILED. The message names the older v2 storage format and says to convert with wative-core 2.6.2 first. A wrong password gives the same error.

Nothing on disk or in IndexedDB is changed, so going back to 2.6.2 opens the workspace as before. importContainer also refuses a dump that holds older-format records, before writing anything.

Convert with 2.6.2

With 2.6.2 still installed:

1. Open the old workspace as usual.
2. Create a new, empty workspace at a new location, under the password you want to keep: with new HybridProviderV3(path) in Node, or with IdbProviderV3.create(name) and a new database name in the browser.
3. For each account, unlock it with account.tryUnlock(password) (the account's own password, or the workspace password for a shared-password account) and re-create it in the new workspace with ws.accounts.create(displayName, password, secret, defaultNetwork?, { kind, hasOwnPassword }), keeping the same display name, password, kind (account.organizationType) and hasOwnPassword setting:
   • HD account — the secret is account.dumpMnemonic(). The new account starts with one wallet; call deriveWallets(n) until it has as many wallets as the old one.
   • PK account — the secret is the first wallet's key, wallet.dumpPrivateKey(vm). Add each further wallet with account.importPrivateKey(wallet.dumpPrivateKey(vm), vm). For vm, use the chain the key was imported for: the first entry of wallet.addresses.
4. Re-add any networks and tokens you added, then re-apply each account's default network (setDefaultNetwork), wallet tags (addTag) and disabled slots (getDisabledSlots() on the old account, disableSlots(...) on the new one).
5. Check that the new workspace lists the same addresses, then upgrade and open the new workspace.

Opening an old workspace with HybridProviderV3 or IdbProviderV3 in 2.6.2 is not a conversion: it leaves most records in the older format, and 2.6.3 still refuses the workspace.

Mnemonic backups made with sealMnemonic() before 2.6.3 still open with openMnemonic(). See Mnemonic Backup.

Node: @node-rs/argon2 is required

In Node, @node-rs/argon2 is now a required dependency, installed with the package — you no longer add it yourself. HybridProvider and HybridProviderV3 both derive with it, and there is no fallback. It ships prebuilt binaries for macOS (x64, arm64), Windows (x64, ia32, arm64), Linux glibc and musl (x64, arm64), Linux armv7, FreeBSD x64 and Android. The binary for your platform installs as an optional dependency of @node-rs/argon2, so an install that omits optional dependencies leaves it out.

Without a loadable binary, constructing either provider — and so Node's default Workspace.open({ path }) or Workspace.open({ password }) — throws UNSUPPORTED_OP with a message naming the package. See Node providers. In the browser nothing changes: keys are derived with the bundled WebAssembly build.

Also in 2.6.3

• IdbProvider and IdbProviderV3 are interchangeable, and so are HybridProvider and HybridProviderV3. All four write the same format, and unlocking costs one key derivation per distinct password, however many accounts and addresses a workspace holds. The V3 names remain and behave identically.
• ws.exportSessionKey(), Workspace.openWithSessionKey() and ws.unlockWithSessionKey() work on all four providers and on any ContainerProvider subclass. See Session keys.
• In browser storage that is not persistent, IdbProvider refuses only to create a new workspace without { acknowledgeEvictionRisk: true }; opening or unlocking an existing one no longer needs it. See the eviction-risk guard.