kokio-sdk 0.1.4 → 1.1.0

package/README.md

@@ -1,3 +1,187 @@
 # Kokio SDK
 
-This is an internal SDK that allows Koki'o mobile app to interact with the Smart contracts.  
+A TypeScript SDK for interacting with the Koki'o eSIM smart contracts. It wraps
+[viem](https://viem.sh) and [`@aa-sdk/core`](https://www.npmjs.com/package/@aa-sdk/core)
+so that two very different callers can use the same contracts:
+
+- the **mobile app** (Expo / React Native), which acts on behalf of a user through
+  an ERC-4337 device-wallet smart account signed by an on-device passkey, and
+- the **backend server**, which acts as the platform admin through a plain EOA.
+
+Each caller has its own entry point so it only deals with the parameters it
+actually needs.
+
+| Entry point | Import | Signer | For |
+| --- | --- | --- | --- |
+| `Kokio` | `kokio-sdk` | Passkey (WebAuthn P-256) via user operations | Mobile app |
+| `KokioAdmin` | `kokio-sdk/admin` | Admin / owner EOA via direct transactions | Backend server |
+
+## Installation
+
+```sh
+npm install kokio-sdk
+```
+
+The package ships as ES modules and requires Node 18 or newer (or a React Native
+runtime). `viem` and `@aa-sdk/core` are bundled as dependencies, so you do not
+need to install them separately.
+
+## Mobile client (Expo / React Native)
+
+The mobile surface represents a user's **device wallet**, an ERC-4337 smart
+account whose owner is a P-256 passkey stored on the device. Actions are sent as
+user operations through a bundler and signed with the passkey, so no private key
+is ever held in the app.
+
+You will need:
+
+- a viem `WalletClient` connected to the target chain,
+- the passkey `credentialId` and `rpId` registered for the device,
+- your `organizationId`, a Pimlico API key, and a gas policy id (used by the
+  bundler and paymaster).
+
+```ts
+import { Kokio } from "kokio-sdk";
+import { createWalletClient, http } from "viem";
+import { baseSepolia } from "viem/chains";
+
+const walletClient = createWalletClient({ chain: baseSepolia, transport: http() });
+
+const kokio = new Kokio(
+  walletClient,
+  credentialId,        // passkey credential id on the device
+  rpId,                // relying party id (your app domain)
+  organizationId,
+  pimlicoAPIKey,
+  gasPolicyId,
+);
+
+// 1. Resolve the smart account for this device passkey. `ownerKey` is the
+//    passkey's P-256 public key as [x, y] hex coordinates; `salt` makes the
+//    counterfactual address unique per user.
+const account = await kokio.smartAccount.getSmartWallet(deviceUniqueIdentifier, ownerKey, salt);
+
+// 2. Build a bundler-backed client for that account.
+const smartAccountClient = await kokio.smartAccount.getSmartWalletClient(account);
+
+// 3. Re-create Kokio with the smart account client (and any known instance
+//    addresses) so the contract surfaces become available.
+const session = new Kokio(
+  walletClient,
+  credentialId,
+  rpId,
+  organizationId,
+  pimlicoAPIKey,
+  gasPolicyId,
+  smartAccountClient,
+  deviceWalletAddress,
+  eSIMWalletAddress,
+);
+
+// 4. Send a user operation. The passkey signs it on the device.
+const { hash } = await session.deviceWallet!.toggleAccessToETH(eSIMWalletAddress, true);
+await smartAccountClient.waitForUserOperationTransaction({ hash });
+```
+
+The contract surfaces (`deviceWallet`, `eSIMWallet`, `deviceWalletFactory`,
+`eSIMWalletFactory`, `lazyWalletRegistry`, `P256Verifier`) are only present once a
+`smartAccountClient` is supplied, which is why the example constructs `Kokio`
+twice. Instance surfaces (`deviceWallet`, `eSIMWallet`) also need their contract
+address. They stay `undefined` until you pass it.
+
+The passkey signing path depends on
+[`react-native-passkey`](https://github.com/f-23/react-native-passkey) and runs
+only on a device or simulator that supports WebAuthn. It is not available in a
+plain Node process.
+
+## Backend server (admin)
+
+The backend surface, `KokioAdmin`, exposes exactly the contract functions that are
+restricted on chain to the admin or owner EOA (`onlyAdmin`, `onlyOwner`,
+`onlyESIMWalletAdmin`). These can never be called through a device-wallet user
+operation, so they live here instead. No bundler, paymaster, or passkey is
+involved. A viem `WalletClient` carrying the admin account is all that is needed.
+
+```ts
+import { KokioAdmin } from "kokio-sdk/admin";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+
+const account = privateKeyToAccount(process.env.ADMIN_PRIVATE_KEY as `0x${string}`);
+const walletClient = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(process.env.RPC_URL),
+});
+
+const admin = new KokioAdmin(walletClient);
+
+// Deploy a device wallet for a user.
+const deployHash = await admin.deviceWalletFactory.createAccount(
+  deviceUniqueIdentifier,
+  ownerKey,
+  salt,
+  depositAmount,
+);
+```
+
+The backend often does not know a contract instance address at construction time.
+It deploys a device wallet, then needs to act on it. Bind the address afterwards
+with a setter and keep using the same `KokioAdmin` reference:
+
+```ts
+admin.setDeviceWalletAddress(deviceWalletAddress);
+await admin.deviceWallet!.deployESIMWallet(true, salt);
+
+admin.setESIMWalletAddress(eSIMWalletAddress);
+await admin.eSIMWallet!.buyDataBundle({ dataBundleID, dataBundlePrice });
+```
+
+`setDeviceWalletAddress`, `setESIMWalletAddress`, and `setWalletClient` each mutate
+the instance and return `this`, so they can be chained. Admin methods send ordinary
+transactions and resolve to a transaction hash.
+
+The chain-wide surfaces (`deviceWalletFactory`, `eSIMWalletFactory`, `registry`,
+`lazyWalletRegistry`) are available as soon as the instance exists. The
+instance-scoped surfaces (`deviceWallet`, `eSIMWallet`) become available once their
+address is set.
+
+## Errors
+
+Both entry points re-export a typed error surface, so you can catch and decode
+on-chain reverts without reaching into internal module paths:
+
+```ts
+import { KokioError, ContractRevertError } from "kokio-sdk";        // or "kokio-sdk/admin"
+
+try {
+  await admin.deviceWalletFactory.requestAdminUpdate(newAdmin);
+} catch (err) {
+  if (err instanceof ContractRevertError) {
+    console.error("reverted:", err.message);
+  }
+}
+```
+
+`KokioError` is the base class. Subclasses include `MissingSmartWalletError`,
+`MissingEOAWalletError`, `InvalidClientError`, `UnsupportedChainError`,
+`CounterfactualMismatchError`, and `ContractRevertError`. `decodeContractRevert`
+turns raw revert data into a readable reason.
+
+## Supported chains
+
+The SDK resolves the contract addresses from the wallet client's connected chain
+id, so you do not pass them yourself. Base Sepolia (chain id `84532`) is the
+deployment used in development. Sepolia and other testnets are also configured.
+
+## Testing
+
+`npm test` runs the offline unit suite with no network access. Two opt-in
+integration tiers (a read-only parity check against a live RPC, and a local
+`anvil` fork that exercises real write and user-operation flows) are documented in
+[tests/README.md](tests/README.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/esm/admin/config-admin.js

@@ -0,0 +1,102 @@
+import { ConstantsSubPackage } from "../interface/constantsClass.js";
+import { AdminDeviceWalletFactorySubPackage } from "./interface/deviceWalletFactoryClass.js";
+import { AdminESIMWalletFactorySubPackage } from "./interface/eSIMWalletFactoryClass.js";
+import { AdminRegistrySubPackage } from "./interface/registryClass.js";
+import { AdminLazyWalletRegistrySubPackage } from "./interface/lazyWalletRegistryClass.js";
+import { AdminDeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
+import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
+// Re-export the typed error surface so backend consumers can `instanceof
+// KokioError` (or a subclass) and decode reverts without reaching into internal
+// module paths - mirroring `config.ts`.
+export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, ContractRevertError, decodeContractRevert, } from "../logic/errors.js";
+/**
+ * EOA-only entry point for the NodeJS backend.
+ *
+ * Unlike {@link Kokio} (the mobile/passkey surface), `KokioAdmin` needs no
+ * bundler, paymaster, or WebAuthn params - only a viem `WalletClient` carrying
+ * the admin/owner EOA. It exposes exactly the contract functions that are
+ * `onlyAdmin`/`onlyOwner`/`onlyESIMWalletAdmin(OrRegistry)` on chain and thus
+ * callable directly by an EOA (never via a device-wallet userOp).
+ *
+ * Contract-instance surfaces (`deviceWallet`, `eSIMWallet`) target a specific
+ * deployed address. The backend often does not know that address at construction
+ * time - e.g. it deploys a device wallet, then acts on it - so those addresses
+ * can be supplied later via {@link setDeviceWalletAddress}/{@link setESIMWalletAddress}
+ * on the *same* instance, without re-constructing. The accessors stay `undefined`
+ * until their address is set.
+ */
+export class KokioAdmin {
+    walletClient;
+    deviceWalletAddress;
+    eSIMWalletAddress;
+    _constants;
+    // Chain-wide surfaces - available as soon as a wallet client exists.
+    deviceWalletFactory;
+    eSIMWalletFactory;
+    registry;
+    lazyWalletRegistry;
+    // Instance-scoped surfaces - undefined until their address is known.
+    deviceWallet;
+    eSIMWallet;
+    constructor(walletClient, deviceWalletAddress, eSIMWalletAddress) {
+        this.walletClient = walletClient;
+        this.deviceWalletAddress = deviceWalletAddress;
+        this.eSIMWalletAddress = eSIMWalletAddress;
+        this._constants = new ConstantsSubPackage(walletClient);
+        this.deviceWalletFactory = new AdminDeviceWalletFactorySubPackage(walletClient);
+        this.eSIMWalletFactory = new AdminESIMWalletFactorySubPackage(walletClient);
+        this.registry = new AdminRegistrySubPackage(walletClient);
+        this.lazyWalletRegistry = new AdminLazyWalletRegistrySubPackage(walletClient);
+        this.deviceWallet = deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, deviceWalletAddress) : undefined;
+        this.eSIMWallet = eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, eSIMWalletAddress) : undefined;
+    }
+    /**
+     * Chain-specific constants (factory addresses, chain, RPC URLs, custom errors)
+     * for the wallet client's connected chain. Resolution is asynchronous because
+     * the chain id is read from the client, so this getter returns a promise:
+     *
+     *   const { factoryAddresses } = await admin.constants;
+     *
+     * The underlying value is memoized, so repeated awaits do not re-fetch.
+     * There is no Pimlico key on this surface, so `pimlicoRpcURL` is always `""`.
+     */
+    get constants() {
+        return this._constants.load();
+    }
+    /**
+     * Bind a `DeviceWallet` instance address after construction and (re)wire the
+     * `deviceWallet` surface to it. Returns `this` for chaining. This is the
+     * backend's primary flow: deploy a wallet, resolve its address, then keep
+     * using the same `KokioAdmin` reference.
+     */
+    setDeviceWalletAddress(deviceWalletAddress) {
+        this.deviceWalletAddress = deviceWalletAddress;
+        this.deviceWallet = new AdminDeviceWalletSubPackage(this.walletClient, deviceWalletAddress);
+        return this;
+    }
+    /**
+     * Bind an `ESIMWallet` instance address after construction and (re)wire the
+     * `eSIMWallet` surface to it. Returns `this` for chaining.
+     */
+    setESIMWalletAddress(eSIMWalletAddress) {
+        this.eSIMWalletAddress = eSIMWalletAddress;
+        this.eSIMWallet = new AdminESIMWalletSubPackage(this.walletClient, eSIMWalletAddress);
+        return this;
+    }
+    /**
+     * Swap the underlying wallet client (e.g. to change the acting EOA) and
+     * re-instantiate every surface against it, preserving any bound instance
+     * addresses. Returns `this` for chaining.
+     */
+    setWalletClient(walletClient) {
+        this.walletClient = walletClient;
+        this._constants = new ConstantsSubPackage(walletClient);
+        this.deviceWalletFactory = new AdminDeviceWalletFactorySubPackage(walletClient);
+        this.eSIMWalletFactory = new AdminESIMWalletFactorySubPackage(walletClient);
+        this.registry = new AdminRegistrySubPackage(walletClient);
+        this.lazyWalletRegistry = new AdminLazyWalletRegistrySubPackage(walletClient);
+        this.deviceWallet = this.deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, this.deviceWalletAddress) : undefined;
+        this.eSIMWallet = this.eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, this.eSIMWalletAddress) : undefined;
+        return this;
+    }
+}

package/dist/esm/admin/interface/deviceWalletClass.js

@@ -0,0 +1,34 @@
+import { _deployESIMWallet, _setESIMUniqueIdentifierForAnESIMWallet, } from "../../logic/admin/deviceWallet.eoa.js";
+import { _deviceUniqueIdentifier, _isValidESIMWallet, _canPullETH, _getVaultAddress, } from "../../logic/admin/reads/deviceWallet.reads.js";
+/**
+ * Thin EOA wrapper around a specific `DeviceWallet` instance. The instance
+ * address is bound at construction; `KokioAdmin.setDeviceWalletAddress` swaps it
+ * by re-instantiating this SubPackage.
+ */
+export class AdminDeviceWalletSubPackage {
+    walletClient;
+    deviceWalletAddress;
+    constructor(walletClient, deviceWalletAddress) {
+        this.walletClient = walletClient;
+        this.deviceWalletAddress = deviceWalletAddress;
+    }
+    deployESIMWallet(hasAccessToETH, salt) {
+        return _deployESIMWallet(this.walletClient, this.deviceWalletAddress, hasAccessToETH, salt);
+    }
+    setESIMUniqueIdentifierForAnESIMWallet(eSIMWalletAddress, eSIMUniqueIdentifier) {
+        return _setESIMUniqueIdentifierForAnESIMWallet(this.walletClient, this.deviceWalletAddress, eSIMWalletAddress, eSIMUniqueIdentifier);
+    }
+    // Reads: public storage getters and views
+    deviceUniqueIdentifier() {
+        return _deviceUniqueIdentifier(this.walletClient, this.deviceWalletAddress);
+    }
+    isValidESIMWallet(eSIMWallet) {
+        return _isValidESIMWallet(this.walletClient, this.deviceWalletAddress, eSIMWallet);
+    }
+    canPullETH(eSIMWallet) {
+        return _canPullETH(this.walletClient, this.deviceWalletAddress, eSIMWallet);
+    }
+    getVaultAddress() {
+        return _getVaultAddress(this.walletClient, this.deviceWalletAddress);
+    }
+}

package/dist/esm/admin/interface/deviceWalletFactoryClass.js

@@ -0,0 +1,57 @@
+import { _createAccountWithEOA } from "../../logic/deviceWalletFactory.js";
+import { _deployDeviceWalletForUsers, _postCreateAccount, _addRegistryAddress, _updateVaultAddress, _requestAdminUpdate, _acceptAdminUpdate, _updateDeviceWalletImplementation, } from "../../logic/admin/deviceWalletFactory.eoa.js";
+import { _eSIMWalletAdmin, _vault, _newRequestedAdmin, _deviceWalletInfoAdded, _getCurrentDeviceWalletImplementation, _getCounterFactualAddress, } from "../../logic/admin/reads/deviceWalletFactory.reads.js";
+/**
+ * Thin EOA wrapper around `DeviceWalletFactory`. Holds only the wallet client;
+ * every method forwards to a logic function. `createAccountWithEOA` reuses the
+ * existing shared logic (the same call the mobile surface exposes).
+ */
+export class AdminDeviceWalletFactorySubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    createAccount(deviceUniqueIdentifier, deviceWalletOwnerKey, salt, depositAmount) {
+        return _createAccountWithEOA(this.walletClient, deviceUniqueIdentifier, deviceWalletOwnerKey, salt, depositAmount);
+    }
+    deployDeviceWalletForUsers(deviceUniqueIdentifiers, deviceWalletOwnersKey, salts, depositAmounts, value) {
+        return _deployDeviceWalletForUsers(this.walletClient, deviceUniqueIdentifiers, deviceWalletOwnersKey, salts, depositAmounts, value);
+    }
+    postCreateAccount(deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey) {
+        return _postCreateAccount(this.walletClient, deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey);
+    }
+    addRegistryAddress(registryContractAddress) {
+        return _addRegistryAddress(this.walletClient, registryContractAddress);
+    }
+    updateVaultAddress(newVaultAddress) {
+        return _updateVaultAddress(this.walletClient, newVaultAddress);
+    }
+    requestAdminUpdate(newAdmin) {
+        return _requestAdminUpdate(this.walletClient, newAdmin);
+    }
+    acceptAdminUpdate() {
+        return _acceptAdminUpdate(this.walletClient);
+    }
+    updateDeviceWalletImplementation(newDeviceImpl) {
+        return _updateDeviceWalletImplementation(this.walletClient, newDeviceImpl);
+    }
+    // Reads: public storage getters and views
+    eSIMWalletAdmin() {
+        return _eSIMWalletAdmin(this.walletClient);
+    }
+    vault() {
+        return _vault(this.walletClient);
+    }
+    newRequestedAdmin() {
+        return _newRequestedAdmin(this.walletClient);
+    }
+    deviceWalletInfoAdded(deviceWallet) {
+        return _deviceWalletInfoAdded(this.walletClient, deviceWallet);
+    }
+    getCurrentDeviceWalletImplementation() {
+        return _getCurrentDeviceWalletImplementation(this.walletClient);
+    }
+    getCounterFactualAddress(deviceWalletOwnerKey, deviceUniqueIdentifier, salt) {
+        return _getCounterFactualAddress(this.walletClient, deviceWalletOwnerKey, deviceUniqueIdentifier, salt);
+    }
+}

package/dist/esm/admin/interface/eSIMWalletClass.js

@@ -0,0 +1,31 @@
+import { _buyDataBundle } from "../../logic/admin/eSIMWallet.eoa.js";
+import { _eSIMWalletFactory, _eSIMUniqueIdentifier, _newRequestedOwner, _owner, } from "../../logic/admin/reads/eSIMWallet.reads.js";
+/**
+ * Thin EOA wrapper around a specific `ESIMWallet` instance. The instance address
+ * is bound at construction; `KokioAdmin.setESIMWalletAddress` swaps it by
+ * re-instantiating this SubPackage.
+ */
+export class AdminESIMWalletSubPackage {
+    walletClient;
+    eSIMWalletAddress;
+    constructor(walletClient, eSIMWalletAddress) {
+        this.walletClient = walletClient;
+        this.eSIMWalletAddress = eSIMWalletAddress;
+    }
+    buyDataBundle(dataBundleDetails, value = 0n) {
+        return _buyDataBundle(this.walletClient, this.eSIMWalletAddress, dataBundleDetails, value);
+    }
+    // Reads: public storage getters and views
+    eSIMWalletFactory() {
+        return _eSIMWalletFactory(this.walletClient, this.eSIMWalletAddress);
+    }
+    eSIMUniqueIdentifier() {
+        return _eSIMUniqueIdentifier(this.walletClient, this.eSIMWalletAddress);
+    }
+    newRequestedOwner() {
+        return _newRequestedOwner(this.walletClient, this.eSIMWalletAddress);
+    }
+    owner() {
+        return _owner(this.walletClient, this.eSIMWalletAddress);
+    }
+}

package/dist/esm/admin/interface/eSIMWalletFactoryClass.js

@@ -0,0 +1,22 @@
+import { _addRegistryAddress, _updateESIMWalletImplementation, } from "../../logic/admin/eSIMWalletFactory.eoa.js";
+import { _isESIMWalletDeployed, _getCurrentESIMWalletImplementation, } from "../../logic/admin/reads/eSIMWalletFactory.reads.js";
+/** Thin EOA (owner) wrapper around `ESIMWalletFactory`. */
+export class AdminESIMWalletFactorySubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    addRegistryAddress(registryContractAddress) {
+        return _addRegistryAddress(this.walletClient, registryContractAddress);
+    }
+    updateESIMWalletImplementation(eSIMWalletImpl) {
+        return _updateESIMWalletImplementation(this.walletClient, eSIMWalletImpl);
+    }
+    // Reads: public storage getters and views
+    isESIMWalletDeployed(eSIMWallet) {
+        return _isESIMWalletDeployed(this.walletClient, eSIMWallet);
+    }
+    getCurrentESIMWalletImplementation() {
+        return _getCurrentESIMWalletImplementation(this.walletClient);
+    }
+}

package/dist/esm/admin/interface/lazyWalletRegistryClass.js

@@ -0,0 +1,33 @@
+import { _batchPopulateHistory, _deployLazyWalletAndSetESIMIdentifier, _switchESIMIdentifierToNewDeviceIdentifier, } from "../../logic/admin/lazyWalletRegistry.eoa.js";
+import { _upgradeManager, _eSIMIdentifierToDeviceIdentifier, _deviceIdentifierToESIMDetails, _eSIMIdentifiersAssociatedWithDeviceIdentifier, } from "../../logic/admin/reads/lazyWalletRegistry.reads.js";
+/** Thin EOA (eSIMWalletAdmin) wrapper around `LazyWalletRegistry`. */
+export class AdminLazyWalletRegistrySubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    batchPopulateHistory(deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails) {
+        return _batchPopulateHistory(this.walletClient, deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails);
+    }
+    deployLazyWalletAndSetESIMIdentifier(deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount) {
+        return _deployLazyWalletAndSetESIMIdentifier(this.walletClient, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount);
+    }
+    switchESIMIdentifierToNewDeviceIdentifier(eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier) {
+        return _switchESIMIdentifierToNewDeviceIdentifier(this.walletClient, eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier);
+    }
+    // Reads: public storage getters
+    upgradeManager() {
+        return _upgradeManager(this.walletClient);
+    }
+    eSIMIdentifierToDeviceIdentifier(eSIMIdentifier) {
+        return _eSIMIdentifierToDeviceIdentifier(this.walletClient, eSIMIdentifier);
+    }
+    // Array-backed getters take an element index and return one entry - iterate
+    // indices to read the full list (there is no on-chain full-array getter).
+    deviceIdentifierToESIMDetails(deviceIdentifier, eSIMIdentifier, index) {
+        return _deviceIdentifierToESIMDetails(this.walletClient, deviceIdentifier, eSIMIdentifier, index);
+    }
+    eSIMIdentifiersAssociatedWithDeviceIdentifier(deviceIdentifier, index) {
+        return _eSIMIdentifiersAssociatedWithDeviceIdentifier(this.walletClient, deviceIdentifier, index);
+    }
+}

package/dist/esm/admin/interface/registryClass.js

@@ -0,0 +1,43 @@
+import { _addOrUpdateLazyWalletRegistryAddress } from "../../logic/admin/registry.eoa.js";
+import { _eSIMWalletAdmin, _vault, _upgradeManager, _lazyWalletRegistry, _uniqueIdentifierToDeviceWallet, _deviceWalletToOwner, _registeredP256Keys, _isDeviceWalletValid, _isESIMWalletValid, _isESIMWalletOnStandby, } from "../../logic/admin/reads/registry.reads.js";
+/** Thin EOA (owner) wrapper around `Registry`. */
+export class AdminRegistrySubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    addOrUpdateLazyWalletRegistryAddress(lazyWalletRegistry) {
+        return _addOrUpdateLazyWalletRegistryAddress(this.walletClient, lazyWalletRegistry);
+    }
+    // Reads: public storage getters, including the inherited RegistryHelper mappings
+    eSIMWalletAdmin() {
+        return _eSIMWalletAdmin(this.walletClient);
+    }
+    vault() {
+        return _vault(this.walletClient);
+    }
+    upgradeManager() {
+        return _upgradeManager(this.walletClient);
+    }
+    lazyWalletRegistry() {
+        return _lazyWalletRegistry(this.walletClient);
+    }
+    uniqueIdentifierToDeviceWallet(deviceIdentifier) {
+        return _uniqueIdentifierToDeviceWallet(this.walletClient, deviceIdentifier);
+    }
+    deviceWalletToOwner(deviceWallet, index) {
+        return _deviceWalletToOwner(this.walletClient, deviceWallet, index);
+    }
+    registeredP256Keys(hashOfOwnerP256Keys) {
+        return _registeredP256Keys(this.walletClient, hashOfOwnerP256Keys);
+    }
+    isDeviceWalletValid(deviceWallet) {
+        return _isDeviceWalletValid(this.walletClient, deviceWallet);
+    }
+    isESIMWalletValid(eSIMWallet) {
+        return _isESIMWalletValid(this.walletClient, eSIMWallet);
+    }
+    isESIMWalletOnStandby(eSIMWallet) {
+        return _isESIMWalletOnStandby(this.walletClient, eSIMWallet);
+    }
+}

package/dist/esm/config.js

@@ -6,6 +6,10 @@ import { LazyWalletRegistrySubPackage } from "./interface/lazyWalletRegistryClas
 import { DeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
 import { ESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { ESIMWalletFactorySubPackage } from "./interface/eSIMWalletFactoryClass.js";
+// Re-export the typed error surface so consumers can `instanceof KokioError`
+// (or a specific subclass) and decode on-chain reverts without reaching into
+// internal module paths.
+export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, ContractRevertError, decodeContractRevert, } from "./logic/errors.js";
 export class Kokio {
     viemWalletClient;
     credentialId;

package/dist/esm/interface/deviceWalletClass.js

@@ -1,4 +1,4 @@
-import { _addESIMWallet, _deployESIMWallet, _getOwner, _getVaultAddress, _payETHForDataBundles, _pullETH, _removeESIMWallet, _setESIMUniqueIdentifierForAnESIMWallet, _toggleAccessToETH } from "../logic/deviceWallet.js";
+import { _addESIMWallet, _getOwner, _getVaultAddress, _removeESIMWallet, _toggleAccessToETH } from "../logic/deviceWallet.js";
 export class DeviceWalletSubPackage {
     smartAccountClient;
     walletClient;
@@ -11,24 +11,12 @@ export class DeviceWalletSubPackage {
     addESIMWallet(eSIMWalletAddress, hasAccessToETH) {
         return _addESIMWallet(this.smartAccountClient, this.address, eSIMWalletAddress, hasAccessToETH);
     }
-    deployESIMWallet(hasAccessToETH, salt) {
-        return _deployESIMWallet(this.smartAccountClient, this.address, hasAccessToETH, salt);
-    }
     getVaultAddress() {
         return _getVaultAddress(this.smartAccountClient, this.address);
     }
-    payETHForDataBundles(amount) {
-        return _payETHForDataBundles(this.smartAccountClient, this.address, amount);
-    }
-    pullETH(amount) {
-        return _pullETH(this.smartAccountClient, this.address, amount);
-    }
     removeESIMWallet(eSIMWalletAddress, hasAccessToETH) {
         return _removeESIMWallet(this.smartAccountClient, this.address, eSIMWalletAddress, hasAccessToETH);
     }
-    setESIMUniqueIdentifierForAnESIMWallet(eSIMWalletAddress, eSIMUniqueIdentifier) {
-        return _setESIMUniqueIdentifierForAnESIMWallet(this.smartAccountClient, this.address, eSIMWalletAddress, eSIMUniqueIdentifier);
-    }
     toggleAccessToETH(eSIMWalletAddress, hasAccessToETH) {
         return _toggleAccessToETH(this.smartAccountClient, this.address, eSIMWalletAddress, hasAccessToETH);
     }

package/dist/esm/interface/eSIMWalletClass.js

@@ -1,4 +1,4 @@
-import { _acceptOwnershipTransfer, _buyDataBundle, _owner, _populateHistory, _requestTransferOwnership, _sendETHToDeviceWallet, _setESIMUniqueIdentifier, _transferOwnership } from "../logic/eSIMWallet.js";
+import { _acceptOwnershipTransfer, _buyDataBundle, _owner, _requestTransferOwnership, _sendETHToDeviceWallet, _setESIMUniqueIdentifier } from "../logic/eSIMWallet.js";
 export class ESIMWalletSubPackage {
     client;
     address;
@@ -15,19 +15,13 @@ export class ESIMWalletSubPackage {
     owner() {
         return _owner(this.client, this.address);
     }
-    populateHistory(dataBundleDetails) {
-        return _populateHistory(this.client, this.address, dataBundleDetails);
-    }
     requestTransferOwnership(newOwner) {
         return _requestTransferOwnership(this.client, this.address, newOwner);
     }
     sendETHToDeviceWallet(amount) {
         return _sendETHToDeviceWallet(this.client, this.address, amount);
     }
-    _setESIMUniqueIdentifier(eSIMUniqueIdentifier) {
+    setESIMUniqueIdentifier(eSIMUniqueIdentifier) {
         return _setESIMUniqueIdentifier(this.client, this.address, eSIMUniqueIdentifier);
     }
-    _transferOwnership(amount) {
-        return _transferOwnership(this.client, this.address, amount);
-    }
 }

package/dist/esm/interface/eSIMWalletFactoryClass.js

@@ -1,4 +1,4 @@
-import { _addRegistryAddress, _deployESIMWalletWithEOA, _deployESIMWalletWithUserOp, _getCurrentESIMWalletImplementation } from "../logic/eSIMWalletFactory.js";
+import { _deployESIMWalletWithUserOp, _getCurrentESIMWalletImplementation } from "../logic/eSIMWalletFactory.js";
 export class ESIMWalletFactorySubPackage {
     smartAccountClient;
     walletClient;
@@ -6,16 +6,10 @@ export class ESIMWalletFactorySubPackage {
         this.smartAccountClient = smartAccountClient;
         this.walletClient = walletClient;
     }
-    deployESIMWalletWithEOA(deviceWalletAddress, salt) {
-        return _deployESIMWalletWithEOA(this.walletClient, deviceWalletAddress, salt);
-    }
     deployESIMWalletWithUserOp(deviceWalletAddress, salt) {
         return _deployESIMWalletWithUserOp(this.smartAccountClient, deviceWalletAddress, salt);
     }
-    addRegistryAddress(registryContractAddress) {
-        return _addRegistryAddress(this.smartAccountClient, registryContractAddress);
-    }
-    _getCurrentESIMWalletImplementation() {
+    getCurrentESIMWalletImplementation() {
         return _getCurrentESIMWalletImplementation(this.smartAccountClient);
     }
 }

package/dist/esm/interface/lazyWalletRegistryClass.js

@@ -1,19 +1,10 @@
-import { _batchPopulateHistory, _deployLazyWalletAndSetESIMIdentifier, _isLazyWalletDeployed, _switchESIMIdentifierToNewDeviceIdentifier } from "../logic/lazyWalletRegistry.js";
+import { _isLazyWalletDeployed } from "../logic/lazyWalletRegistry.js";
 export class LazyWalletRegistrySubPackage {
     client;
     constructor(client) {
         this.client = client;
     }
-    _batchPopulateHistory(deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails) {
-        return _batchPopulateHistory(this.client, deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails);
-    }
-    _deployLazyWalletAndSetESIMIdentifier(deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount) {
-        return _deployLazyWalletAndSetESIMIdentifier(this.client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount);
-    }
-    _isLazyWalletDeployed(deviceUniqueIdentifier) {
+    isLazyWalletDeployed(deviceUniqueIdentifier) {
         return _isLazyWalletDeployed(this.client, deviceUniqueIdentifier);
     }
-    _switchESIMIdentifierToNewDeviceIdentifier(eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier) {
-        return _switchESIMIdentifierToNewDeviceIdentifier(this.client, eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier);
-    }
 }