Release v3.1.0: sponsored user flows, batched helpers, decoded errors, lighter install

[ManulParihar]

Summary

Adds helpers that batch common user actions into one passkey prompt, makes failed calls report the contract's error by name, fixes bugs found while testing the SDK the way an app would use it, and makes the install much smaller. Adds test tiers that run the full user journey through the published package, on a local Base Sepolia fork and on the live network with Pimlico.

Upgrade notes

• Mobile apps must now install react-native-passkey themselves: npm install kokio-sdk react-native-passkey. It is an optional peer dependency (^3.6.1). Expo only links native modules the app lists directly, so apps needed it anyway.
• Backends using only kokio-sdk/admin need nothing extra. That entry point never loads the passkey module.
• deployESIMWalletWithUserOp is deprecated in favour of deployAndBindESIMWallet. It still works.

New

• deviceWallet.deployAndBindESIMWallet(salt, { grantAccessToFunds? }) deploys an eSIM wallet, binds it to the device wallet and optionally grants it access to funds, in one sponsored user operation. Returns { userOpHash, eSIMWalletAddress }.
• eSIMWallet.buyDataBundleWithTransfer(details, asset, maxAmountIn, ref) sends any missing tokens and buys the bundle in one user operation, so it works without pull access.
• eSIMWalletFactory.getCounterFactualAddress(deviceWallet, salt) predicts an eSIM wallet address before it is deployed.
• getSmartWalletClient(account, { bundlerUrl }) accepts an optional bundler URL.

Changed

• getSmartWallet no longer needs the wallet client to carry an account.
• The gas policy goes to the paymaster as sponsorshipPolicyId, the key Pimlico reads. The policy is now optional.
• A reverting user operation throws ContractRevertError with the contract error name, instead of a raw bundler error.
• ProtocolAdmin and PaymentAdapter errors are decoded by name.
• The lazy deployment error classes are exported from both kokio-sdk and kokio-sdk/admin.

Fixed

• Admin writes from a wallet client with a local private key failed with "No Signer available". They now sign locally.
• The package imported @peculiar/asn1-* without declaring them. The unused code that did so is removed.

Performance

• The chain id is fetched once per client instead of on every call (155 call sites).
• Independent reads run in parallel. Setting up a smart wallet goes from about 6 sequential RPC round trips to 2 on first use and 1 after.

Dependencies

Package	Before	After
@simplewebauthn/server	runtime	dev only (tests). It pulled about 5 MB of certificate parsers into apps for one base64url helper
@scure/base	not listed	runtime. Replaces the above; viem already installs it, so it adds nothing
react-native-passkey	runtime	optional peer
@peculiar/asn1-*	runtime	removed

Runtime dependencies are now viem, @noble/curves and @scure/base. Dev only: @pimlico/alto, @pimlico/mock-paymaster and prool for the local bundler and paymaster; tar is overridden to 7.5.22 for a security advisory.

Docs

• README: install commands for app and backend, no account needed, optional policy, write results and ContractRevertError, the batched helpers.
• PROTOCOL_ADMIN.md: corrected ProtocolAdmin address, and clarified that the executor sends an operation's ETH.
• registry.bindESIMWallet: notes that it binds the registry side only.

Tests

Command	What it runs
npm test	Unit tests, offline (425)
npm run test:consumer:fork	Full user journey through the built package on a Base Sepolia fork, with a local bundler and paymaster. Every user operation must be sponsored (16)
npm run test:integration:fork	Lower-level fork suites, pinned to a block with isolated ports (23)
npm run test:consumer:live	The same journey on Base Sepolia with Pimlico. Needs BASE_SEPOLIA_RPC_URL, PIMLICO_API_SECRET, ESIM_WALLET_ADMIN_PK, and USDCt on the admin account

What the journeys cover:

• Deploy a device wallet, then register it through the backend
• Deploy, bind and grant access to an eSIM wallet in one user operation
• Grant and revoke fund access
• Buy with pull access and with a transfer, in both USDC and USDCt
• Refusals: reused payment reference, price above cap, quote above max, unknown asset, revoked access
• High-s passkey signatures
• ERC-1271 / ERC-6492 message and typed data signing, before and after deploy

Other test changes:

• Every unit-tested write must pass the client's account object, so the local-key bug above cannot return unnoticed.
• Test data is tagged kokio-sdk-test so it stands apart from other activity on Base Sepolia.
• Tests superseded by the public SDK journeys were removed, along with five unused internal helpers.