kokio-sdk 0.1.3 → 1.0.0

package/dist/esm/logic/admin/reads/deviceWalletFactory.reads.js

@@ -0,0 +1,87 @@
+import { publicActions } from "viem";
+import { _getChainSpecificConstants } from "../../constants.js";
+import { DeviceWalletFactory } from "../../../abis/index.js";
+/**
+ * Read-only admin logic for `DeviceWalletFactory` - the contract's public
+ * storage getters and `view` functions, surfaced for the backend.
+ *
+ * A viem `WalletClient` carries no public actions, so each read extends it with
+ * `publicActions` (reusing the same transport, so it also works under an anvil
+ * fork) before calling `readContract`. Reads need no EOA account, so there is no
+ * `MissingEOAWalletError` guard.
+ */
+/** The admin EOA (`eSIMWalletAdmin`) currently set on the factory. */
+export const _eSIMWalletAdmin = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "eSIMWalletAdmin",
+        args: []
+    });
+};
+/** The vault EOA that receives eSIM payments. */
+export const _vault = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "vault",
+        args: []
+    });
+};
+/** The pending admin proposed via `requestAdminUpdate` (zero address if none). */
+export const _newRequestedAdmin = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "newRequestedAdmin",
+        args: []
+    });
+};
+/** Whether a device wallet has been registered with the factory. */
+export const _deviceWalletInfoAdded = async (client, deviceWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "deviceWalletInfoAdded",
+        args: [deviceWallet]
+    });
+};
+/** The current device-wallet beacon implementation. */
+export const _getCurrentDeviceWalletImplementation = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "getCurrentDeviceWalletImplementation",
+        args: []
+    });
+};
+/**
+ * The counterfactual (CREATE2) device-wallet address for an owner key. On-chain
+ * arg order is `(ownerKey, uid, salt)` - note this differs from `createAccount`.
+ */
+export const _getCounterFactualAddress = async (client, deviceWalletOwnerKey, deviceUniqueIdentifier, salt) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        abi: DeviceWalletFactory,
+        functionName: "getCounterFactualAddress",
+        args: [deviceWalletOwnerKey, deviceUniqueIdentifier, salt]
+    });
+};

package/dist/esm/logic/admin/reads/eSIMWallet.reads.js

@@ -0,0 +1,44 @@
+import { publicActions } from "viem";
+import { ESIMWallet } from "../../../abis/index.js";
+/**
+ * Read-only admin logic targeting a specific `ESIMWallet` instance (its address
+ * is passed in). Surfaces the instance's public storage getters + `owner` view
+ * for the backend. Each read extends the `WalletClient` with `publicActions`; no
+ * EOA account is required.
+ */
+/** The `ESIMWalletFactory` that deployed this eSIM wallet. */
+export const _eSIMWalletFactory = async (client, eSIMWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: eSIMWalletAddress,
+        abi: ESIMWallet,
+        functionName: "eSIMWalletFactory",
+        args: []
+    });
+};
+/** The eSIM's unique identifier string (empty until set by the admin). */
+export const _eSIMUniqueIdentifier = async (client, eSIMWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: eSIMWalletAddress,
+        abi: ESIMWallet,
+        functionName: "eSIMUniqueIdentifier",
+        args: []
+    });
+};
+/** The pending owner proposed via `requestTransferOwnership` (zero if none). */
+export const _newRequestedOwner = async (client, eSIMWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: eSIMWalletAddress,
+        abi: ESIMWallet,
+        functionName: "newRequestedOwner",
+        args: []
+    });
+};
+/** The current owner (device wallet) of this eSIM wallet. */
+export const _owner = async (client, eSIMWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: eSIMWalletAddress,
+        abi: ESIMWallet,
+        functionName: "owner",
+        args: []
+    });
+};

package/dist/esm/logic/admin/reads/eSIMWalletFactory.reads.js

@@ -0,0 +1,32 @@
+import { publicActions } from "viem";
+import { _getChainSpecificConstants } from "../../constants.js";
+import { ESIMWalletFactory } from "../../../abis/index.js";
+/**
+ * Read-only admin logic for `ESIMWalletFactory` - its public storage getter and
+ * `view` function, surfaced for the backend. Each read extends the `WalletClient`
+ * with `publicActions` (no EOA account required).
+ */
+/** Whether an eSIM wallet was deployed by this factory. */
+export const _isESIMWalletDeployed = async (client, eSIMWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
+        abi: ESIMWalletFactory,
+        functionName: "isESIMWalletDeployed",
+        args: [eSIMWallet]
+    });
+};
+/** The current eSIM-wallet beacon implementation. */
+export const _getCurrentESIMWalletImplementation = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
+        abi: ESIMWalletFactory,
+        functionName: "getCurrentESIMWalletImplementation",
+        args: []
+    });
+};

package/dist/esm/logic/admin/reads/lazyWalletRegistry.reads.js

@@ -0,0 +1,62 @@
+import { publicActions } from "viem";
+import { _getChainSpecificConstants } from "../../constants.js";
+import { LazyWalletRegistry } from "../../../abis/index.js";
+/**
+ * Read-only admin logic for `LazyWalletRegistry` - its public storage getters,
+ * surfaced for the backend's fiat/lazy provisioning flows. Each read extends the
+ * `WalletClient` with `publicActions`; no EOA account is required.
+ *
+ * Note: `deviceIdentifierToESIMDetails` and
+ * `eSIMIdentifiersAssociatedWithDeviceIdentifier` back dynamic arrays on chain,
+ * so their auto-generated getters take an element `index` and return one entry -
+ * callers iterate indices to read the whole list (there is no full-array getter).
+ */
+/** The upgrade-manager (owner) EOA of the lazy registry. */
+export const _upgradeManager = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "upgradeManager",
+        args: []
+    });
+};
+/** The device identifier an eSIM identifier is currently associated with. */
+export const _eSIMIdentifierToDeviceIdentifier = async (client, eSIMIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "eSIMIdentifierToDeviceIdentifier",
+        args: [eSIMIdentifier]
+    });
+};
+/** One data-bundle history entry for a (device, eSIM) pair, by array index. */
+export const _deviceIdentifierToESIMDetails = async (client, deviceIdentifier, eSIMIdentifier, index) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    const [dataBundleID, dataBundlePrice] = await client.extend(publicActions).readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "deviceIdentifierToESIMDetails",
+        args: [deviceIdentifier, eSIMIdentifier, index]
+    });
+    return { dataBundleID, dataBundlePrice };
+};
+/** One eSIM identifier associated with a device identifier, by array index. */
+export const _eSIMIdentifiersAssociatedWithDeviceIdentifier = async (client, deviceIdentifier, index) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "eSIMIdentifiersAssociatedWithDeviceIdentifier",
+        args: [deviceIdentifier, index]
+    });
+};

package/dist/esm/logic/admin/reads/registry.reads.js

@@ -0,0 +1,136 @@
+import { publicActions } from "viem";
+import { _getChainSpecificConstants } from "../../constants.js";
+import { Registry } from "../../../abis/index.js";
+/**
+ * Read-only admin logic for `Registry` (which inherits `RegistryHelper`, so its
+ * ABI carries the helper mappings too). Surfaces the public storage getters for
+ * the backend. Each read extends the `WalletClient` with `publicActions`; no EOA
+ * account is required.
+ */
+/** The admin EOA (`eSIMWalletAdmin`) recorded in the registry. */
+export const _eSIMWalletAdmin = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "eSIMWalletAdmin",
+        args: []
+    });
+};
+/** The vault EOA recorded in the registry. */
+export const _vault = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "vault",
+        args: []
+    });
+};
+/** The upgrade-manager (owner) EOA recorded in the registry. */
+export const _upgradeManager = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "upgradeManager",
+        args: []
+    });
+};
+/** The `LazyWalletRegistry` address wired into the registry. */
+export const _lazyWalletRegistry = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "lazyWalletRegistry",
+        args: []
+    });
+};
+/** The device wallet registered for a device unique identifier (zero if none). */
+export const _uniqueIdentifierToDeviceWallet = async (client, deviceIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "uniqueIdentifierToDeviceWallet",
+        args: [deviceIdentifier]
+    });
+};
+/**
+ * One of a device wallet's two P-256 owner keys. The on-chain getter for the
+ * `bytes32[2]` array takes the element index (`0` or `1`) and returns one key.
+ */
+export const _deviceWalletToOwner = async (client, deviceWallet, index) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "deviceWalletToOwner",
+        args: [deviceWallet, index]
+    });
+};
+/** The device wallet registered for a hash of owner P-256 keys (zero if none). */
+export const _registeredP256Keys = async (client, hashOfOwnerP256Keys) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "registeredP256Keys",
+        args: [hashOfOwnerP256Keys]
+    });
+};
+/** Whether a device wallet is registered/valid. */
+export const _isDeviceWalletValid = async (client, deviceWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isDeviceWalletValid",
+        args: [deviceWallet]
+    });
+};
+/**
+ * The device wallet that owns an eSIM wallet (zero address if the eSIM is not
+ * valid). On-chain this getter is named `isESIMWalletValid` but returns the
+ * associated device-wallet address, not a boolean.
+ */
+export const _isESIMWalletValid = async (client, eSIMWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isESIMWalletValid",
+        args: [eSIMWallet]
+    });
+};
+/** Whether an eSIM wallet is currently on standby. */
+export const _isESIMWalletOnStandby = async (client, eSIMWallet) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isESIMWalletOnStandby",
+        args: [eSIMWallet]
+    });
+};

package/dist/esm/logic/admin/registry.eoa.js

@@ -0,0 +1,23 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { Registry } from "../../abis/index.js";
+/**
+ * Admin-EOA logic for `Registry`. `addOrUpdateLazyWalletRegistryAddress` is
+ * `onlyOwner`, so the `client` must carry the `upgradeManager` EOA.
+ */
+/** Wire (or rewire) the LazyWalletRegistry into the Registry. `onlyOwner`. */
+export const _addOrUpdateLazyWalletRegistryAddress = async (client, lazyWalletRegistry) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return client.writeContract({
+        address: values.factoryAddresses.REGISTRY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: Registry,
+        functionName: 'addOrUpdateLazyWalletRegistryAddress',
+        args: [lazyWalletRegistry]
+    });
+};

package/dist/esm/logic/constants.js

@@ -1,3 +1,4 @@
+import { InvalidClientError, UnconfiguredChainError, UnsupportedChainError, } from './errors.js';
 import { mainnet, sepolia, optimism, optimismSepolia, arbitrum, arbitrumSepolia, base, baseSepolia } from "viem/chains";
 export const ZERO = BigInt('0');
 export const SIGNATURE_VALIDITY_SECONDS = 180; // 3 minutes validity
@@ -91,81 +92,40 @@ export const customErrors = {
 };
 export const _extractChainID = async (client) => {
     if (!client) {
-        throw "Invalid Signer or Provider instance";
+        throw new InvalidClientError();
     }
     return client.getChainId();
 };
+// Maps each supported chain id to its factory-address book + viem chain. Chains
+// whose addresses are still '0x' placeholders are intentionally listed so the
+// guard below can reject them with a clear message rather than leaking '0x'
+// into viem calls.
+const CHAIN_CONFIG = {
+    [CHAIN_ID.SEPOLIA]: { factoryAddresses: sepoliaFactoryAddresses, chain: sepolia },
+    [CHAIN_ID.MAINNET]: { factoryAddresses: mainnetFactoryAddresses, chain: mainnet },
+    [CHAIN_ID.OPTIMISM_MAINNET]: { factoryAddresses: optimismMainnetFactoryAddresses, chain: optimism },
+    [CHAIN_ID.OPTIMISM_SEPOLIA]: { factoryAddresses: optimismSepoliaFactoryAddresses, chain: optimismSepolia },
+    [CHAIN_ID.BASE_MAINNET]: { factoryAddresses: baseMainnetFactoryAddresses, chain: base },
+    [CHAIN_ID.BASE_SEPOLIA]: { factoryAddresses: baseSepoliaFactoryAddresses, chain: baseSepolia },
+    [CHAIN_ID.ARBITRUM_ONE]: { factoryAddresses: arbitrumOneFactoryAddresses, chain: arbitrum },
+    [CHAIN_ID.ARBITRUM_SEPOLIA]: { factoryAddresses: arbitrumSepoliaFactoryAddresses, chain: arbitrumSepolia },
+};
+// A factory address book is only usable if every entry is a real 20-byte
+// address - an unconfigured chain leaves '0x' placeholders behind.
+const _hasUnconfiguredAddresses = (addresses) => Object.values(addresses).some((a) => !a || a === '0x' || a.length !== 42);
 export const _getChainSpecificConstants = (chainID, rpcURL, pimlicoAPIKey) => {
-    if (chainID == CHAIN_ID.SEPOLIA) {
-        return {
-            factoryAddresses: sepoliaFactoryAddresses,
-            chain: sepolia,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.MAINNET) {
-        return {
-            factoryAddresses: mainnetFactoryAddresses,
-            chain: mainnet,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.OPTIMISM_MAINNET) {
-        return {
-            factoryAddresses: optimismMainnetFactoryAddresses,
-            chain: optimism,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.OPTIMISM_SEPOLIA) {
-        return {
-            factoryAddresses: optimismSepoliaFactoryAddresses,
-            chain: optimismSepolia,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.BASE_MAINNET) {
-        return {
-            factoryAddresses: baseMainnetFactoryAddresses,
-            chain: base,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.BASE_SEPOLIA) {
-        return {
-            factoryAddresses: baseSepoliaFactoryAddresses,
-            chain: baseSepolia,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
-    }
-    else if (chainID == CHAIN_ID.ARBITRUM_ONE) {
-        return {
-            factoryAddresses: arbitrumOneFactoryAddresses,
-            chain: arbitrum,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
+    const config = CHAIN_CONFIG[chainID];
+    if (!config) {
+        throw new UnsupportedChainError(chainID);
     }
-    else {
-        return {
-            factoryAddresses: arbitrumSepoliaFactoryAddresses,
-            chain: arbitrumSepolia,
-            rpcURL: rpcURL,
-            pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
-            customErrors: customErrors
-        };
+    if (_hasUnconfiguredAddresses(config.factoryAddresses)) {
+        throw new UnconfiguredChainError(chainID);
     }
+    return {
+        factoryAddresses: config.factoryAddresses,
+        chain: config.chain,
+        rpcURL: rpcURL,
+        pimlicoRpcURL: pimlicoAPIKey ? `https://api.pimlico.io/v2/${chainID}/rpc?apikey=${pimlicoAPIKey}` : "",
+        customErrors: customErrors,
+    };
 };

package/dist/esm/logic/deviceWallet.js

@@ -1,92 +1,20 @@
 import { encodeFunctionData, getContract } from "viem";
 import { DeviceWallet } from "../abis/index.js";
-import { customErrors } from "./constants.js";
-export const _deployESIMWallet = async (client, address, hasAccessToETH, salt) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "deployESIMWallet",
-                args: [hasAccessToETH, salt]
-            })
-        }
-    });
-};
-export const _setESIMUniqueIdentifierForAnESIMWallet = async (client, address, eSIMWalletAddress, eSIMUniqueIdentifier) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "setESIMUniqueIdentifierForAnESIMWallet",
-                args: [eSIMWalletAddress, eSIMUniqueIdentifier]
-            })
-        }
-    });
-    // const contract = (await getContractInstance(client)).deviceWallet(address);
-    // return contract.write.setESIMUniqueIdentifierForAnESIMWallet([eSIMWalletAddress, eSIMUniqueIdentifier]);
-};
-export const _payETHForDataBundles = async (client, address, amount) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "payETHForDataBundles",
-                args: [amount]
-            })
-        }
-    });
-};
-export const _pullETH = async (client, address, amount) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "pullETH",
-                args: [amount]
-            })
-        }
-    });
-};
-export const _getVaultAddress = async (client, address) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: DeviceWallet,
-                functionName: "getVaultAddress",
-                args: []
-            })
-        }
-    });
-};
+import { MissingSmartWalletError } from "./errors.js";
+// A userOp from a device wallet runs through `execute`, so at the target contract
+// msg.sender is the device-wallet account itself. That constrains which DeviceWallet
+// functions this surface can expose:
+//   - deployESIMWallet / setESIMUniqueIdentifierForAnESIMWallet are `onlyESIMWalletAdmin`
+//     / `onlyESIMWalletAdminOrRegistry` - only the admin EOA (or registry) may call, so a
+//     device-wallet userOp always reverts. They are exposed on `KokioAdmin.deviceWallet`.
+//   - payETHForDataBundles / pullETH are `onlyAssociatedESIMWallets` - callable only by an
+//     associated eSIM wallet contract, never by the device wallet or an EOA.
+// The functions below are self-callable (target = the device wallet's own address, so
+// msg.sender == self), so they succeed via a userOp.
 export const _toggleAccessToETH = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlySelf`; the device wallet toggles ETH access for an eSIM wallet it owns.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -101,8 +29,8 @@ export const _toggleAccessToETH = async (client, address, eSIMWalletAddress, has
 };
 export const _addESIMWallet = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyRegistryOrDeviceWalletFactoryOrOwner`; self is permitted.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -117,8 +45,8 @@ export const _addESIMWallet = async (client, address, eSIMWalletAddress, hasAcce
 };
 export const _removeESIMWallet = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlySelfOrAssociatedESIMWallet`; self is permitted.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -131,14 +59,23 @@ export const _removeESIMWallet = async (client, address, eSIMWalletAddress, hasA
         }
     });
 };
+// `getVaultAddress` is a `view` - read it directly instead of spending a userOp.
+export const _getVaultAddress = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: DeviceWallet,
+        functionName: "getVaultAddress",
+        args: []
+    });
+};
 export const _getOwner = async (client, address) => {
     const contract = getContract({
         abi: DeviceWallet,
         address: address,
         client
     });
-    const x = await contract.read.owner([0]);
-    const y = await contract.read.owner([1]);
+    const x = await contract.read.owner([0n]);
+    const y = await contract.read.owner([1n]);
     const owner = [x, y];
     return owner;
 };