kokio-sdk 0.1.3 → 1.0.0

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);
-    }
 }

package/dist/esm/logic/P256Verifier.js

@@ -1,22 +1,15 @@
-import { encodeFunctionData } from "viem";
-import { _getChainSpecificConstants, customErrors } from "./constants.js";
+import { _getChainSpecificConstants } from "./constants.js";
 import { P256Verifier } from "../abis/index.js";
+// `verifySignature` is a `view` - read it directly instead of spending a userOp
+// (the previous userOp form returned a userOp hash, never the boolean result).
 export const _verifySignature = async (client, message, requireMessageVerification, webAuthnSignature, x, y) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.P256VERIFIER,
-            data: encodeFunctionData({
-                abi: P256Verifier,
-                functionName: "verifySignature",
-                args: [message, requireMessageVerification, webAuthnSignature, x, y]
-            })
-        }
+    return client.readContract({
+        address: values.factoryAddresses.P256VERIFIER,
+        abi: P256Verifier,
+        functionName: "verifySignature",
+        args: [message, requireMessageVerification, webAuthnSignature, x, y]
     });
 };

package/dist/esm/logic/account-kit/createSmartAccount.js

@@ -1,9 +1,9 @@
-import { createSmartAccountClient, getEntryPoint, toSmartContractAccount, split } from "@aa-sdk/core";
-import { http, encodeFunctionData, encodePacked, encodeAbiParameters, parseAbiParameters, getContract, concat, keccak256, getContractAddress, getAddress, hashMessage, stringToBytes, toHex, hexToBytes, bytesToHex } from "viem";
+import { createSmartAccountClient, getEntryPoint, toSmartContractAccount, split, erc7677Middleware } from "@aa-sdk/core";
+import { http, encodeFunctionData, encodePacked, encodeAbiParameters, parseAbiParameters, getContract, concat, keccak256, getContractAddress, getAddress, hashMessage, toHex, hashTypedData, hexToBytes, bytesToHex } from "viem";
 import { _getChainSpecificConstants, ZERO, SIGNATURE_VALIDITY_SECONDS } from "../constants.js";
+import { CounterfactualMismatchError } from "../errors.js";
 import { _remove0x } from "../utils.js";
 import { DeviceWallet, DeviceWalletFactory } from "../../abis/index.js";
-import { alchemyGasManagerMiddleware } from "@account-kit/infra";
 import { isoBase64URL } from "@simplewebauthn/server/helpers";
 import { Passkey } from "react-native-passkey";
 import { p256 } from "@noble/curves/nist.js";
@@ -16,6 +16,22 @@ var AuthenticatorTransport;
     AuthenticatorTransport["hybrid"] = "hybrid";
     AuthenticatorTransport["internal"] = "internal";
 })(AuthenticatorTransport || (AuthenticatorTransport = {}));
+/**
+ * BeaconProxy creation bytecode, used to compute the CREATE2 counterfactual
+ * DeviceWallet address off-chain (initCode = creationCode ++ abi.encode(beacon, initData)).
+ *
+ * PINNED - this MUST byte-for-byte match the BeaconProxy the on-chain
+ * DeviceWalletFactory deploys, or the computed address will diverge from the
+ * deployed one. Source of truth:
+ *   OpenZeppelin Contracts v5.0.0 - proxy/beacon/BeaconProxy.sol
+ *   compiled by Hardhat (smart-contract-suite `artifacts/@openzeppelin/contracts/
+ *   proxy/beacon/BeaconProxy.sol/BeaconProxy.json`), solc 0.8.25+commit.b61c2a91,
+ *   optimizer { enabled: true, runs: 200 }, viaIR: true.
+ * NOTE: the Foundry `out/` artifact (different optimizer settings) produces a
+ * DIFFERENT bytecode - do not swap it in without re-verifying the counterfactual.
+ * `_assertCounterfactualMatchesOnChain` guards against drift at runtime.
+ */
+export const BEACON_PROXY_CREATION_CODE = "0x60a06040908082526104a8803803809161001982856102ae565b8339810182828203126101e95761002f826102e7565b60208084015191939091906001600160401b0382116101e9570182601f820112156101e957805190610060826102fb565b9361006d875195866102ae565b8285528383830101116101e957829060005b83811061029a57505060009184010152823b1561027a577fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d5080546001600160a01b0319166001600160a01b038581169182179092558551635c60da1b60e01b8082529194928482600481895afa91821561026f57600092610238575b50813b1561021f5750508551847f1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e600080a282511561020057508290600487518096819382525afa9283156101f5576000936101b3575b5091600080848461019096519101845af4903d156101aa573d610174816102fb565b90610181885192836102ae565b8152600081943d92013e610316565b505b6080525161012e908161037a82396080518160180152f35b60609250610316565b92508183813d83116101ee575b6101ca81836102ae565b810103126101e9576000806101e1610190956102e7565b945050610152565b600080fd5b503d6101c0565b85513d6000823e3d90fd5b9350505050346102105750610192565b63b398979f60e01b8152600490fd5b8751634c9c8ce360e01b81529116600482015260249150fd5b9091508481813d8311610268575b61025081836102ae565b810103126101e957610261906102e7565b90386100fb565b503d610246565b88513d6000823e3d90fd5b8351631933b43b60e21b81526001600160a01b0384166004820152602490fd5b81810183015186820184015284920161007f565b601f909101601f19168101906001600160401b038211908210176102d157604052565b634e487b7160e01b600052604160045260246000fd5b51906001600160a01b03821682036101e957565b6001600160401b0381116102d157601f01601f191660200190565b9061033d575080511561032b57805190602001fd5b604051630a12f52160e11b8152600490fd5b81511580610370575b61034e575090565b604051639996b31560e01b81526001600160a01b039091166004820152602490fd5b50803b1561034656fe60806040819052635c60da1b60e01b81526020816004817f00000000000000000000000000000000000000000000000000000000000000006001600160a01b03165afa90811560a9576000916054575b5060da565b905060203d60201160a3575b601f8101601f191682019167ffffffffffffffff831181841017608d576088926040520160b5565b38604f565b634e487b7160e01b600052604160045260246000fd5b503d6060565b6040513d6000823e3d90fd5b602090607f19011260d5576080516001600160a01b038116810360d55790565b600080fd5b6000808092368280378136915af43d82803e1560f4573d90f35b3d90fdfea264697066735822122099ba460fd62b3e22c737d15959887e6cae3498f3495d31e43e2bcf1283aec7d264736f6c63430008190033";
 /*
 ** Stamp is client-side authentication. Since the passkeys are one the user's mobile device
 ** react-native-passkey helps fetch passkey for the user (provided credentialId, rpId).
@@ -23,7 +39,10 @@ var AuthenticatorTransport;
 */
 export const _stamp = async (credentialId, rpId, payload) => {
     const signingOptions = {
-        challenge: isoBase64URL.fromBuffer(hexToBytes(payload)),
+        // `Uint8Array.from` gives a fresh ArrayBuffer-backed view, matching the
+        // `Uint8Array<ArrayBuffer>` that `fromBuffer` expects (viem's `hexToBytes`
+        // is typed over the wider `ArrayBufferLike`).
+        challenge: isoBase64URL.fromBuffer(Uint8Array.from(hexToBytes(payload))),
         allowCredentials: [{
                 id: credentialId,
                 type: "public-key",
@@ -120,7 +139,7 @@ const _encodeBatchExecute = async (txs) => {
         args: [new_txs]
     });
 };
-const _getAccountInitCode = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
+export const _getAccountInitCode = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
     // To send with user operations
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
@@ -132,7 +151,7 @@ const _getAccountInitCode = async (client, deviceUniqueIdentifier, deviceWalletO
     });
     return values.factoryAddresses.DEVICE_WALLET_FACTORY.concat(_remove0x(callData));
 };
-const getInitCodeHash = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey) => {
+export const getInitCodeHash = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -145,7 +164,7 @@ const getInitCodeHash = async (client, deviceUniqueIdentifier, deviceWalletOwner
         address: deviceWalletFactoryAddress,
         client
     });
-    const beacon = await deviceWalletFactory.read.beacon([]);
+    const beacon = await deviceWalletFactory.read.beacon();
     // Encode the DeviceWallet.init with the init params
     const deviceWalletInitData = encodeFunctionData({
         abi: DeviceWallet,
@@ -157,14 +176,13 @@ const getInitCodeHash = async (client, deviceUniqueIdentifier, deviceWalletOwner
             eSIMWalletFactoryAddress
         ]
     });
-    const beaconProxyBytecode = "0x60a06040908082526104a8803803809161001982856102ae565b8339810182828203126101e95761002f826102e7565b60208084015191939091906001600160401b0382116101e9570182601f820112156101e957805190610060826102fb565b9361006d875195866102ae565b8285528383830101116101e957829060005b83811061029a57505060009184010152823b1561027a577fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d5080546001600160a01b0319166001600160a01b038581169182179092558551635c60da1b60e01b8082529194928482600481895afa91821561026f57600092610238575b50813b1561021f5750508551847f1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e600080a282511561020057508290600487518096819382525afa9283156101f5576000936101b3575b5091600080848461019096519101845af4903d156101aa573d610174816102fb565b90610181885192836102ae565b8152600081943d92013e610316565b505b6080525161012e908161037a82396080518160180152f35b60609250610316565b92508183813d83116101ee575b6101ca81836102ae565b810103126101e9576000806101e1610190956102e7565b945050610152565b600080fd5b503d6101c0565b85513d6000823e3d90fd5b9350505050346102105750610192565b63b398979f60e01b8152600490fd5b8751634c9c8ce360e01b81529116600482015260249150fd5b9091508481813d8311610268575b61025081836102ae565b810103126101e957610261906102e7565b90386100fb565b503d610246565b88513d6000823e3d90fd5b8351631933b43b60e21b81526001600160a01b0384166004820152602490fd5b81810183015186820184015284920161007f565b601f909101601f19168101906001600160401b038211908210176102d157604052565b634e487b7160e01b600052604160045260246000fd5b51906001600160a01b03821682036101e957565b6001600160401b0381116102d157601f01601f191660200190565b9061033d575080511561032b57805190602001fd5b604051630a12f52160e11b8152600490fd5b81511580610370575b61034e575090565b604051639996b31560e01b81526001600160a01b039091166004820152602490fd5b50803b1561034656fe60806040819052635c60da1b60e01b81526020816004817f00000000000000000000000000000000000000000000000000000000000000006001600160a01b03165afa90811560a9576000916054575b5060da565b905060203d60201160a3575b601f8101601f191682019167ffffffffffffffff831181841017608d576088926040520160b5565b38604f565b634e487b7160e01b600052604160045260246000fd5b503d6060565b6040513d6000823e3d90fd5b602090607f19011260d5576080516001600160a01b038116810360d55790565b600080fd5b6000808092368280378136915af43d82803e1560f4573d90f35b3d90fdfea264697066735822122099ba460fd62b3e22c737d15959887e6cae3498f3495d31e43e2bcf1283aec7d264736f6c63430008190033";
     // Encode BeaconProxy constructor args
     const beaconProxyConstructorArgs = encodeAbiParameters(parseAbiParameters("address, bytes"), [beacon, deviceWalletInitData]);
     // Compute initCode
-    const initCode = concat([beaconProxyBytecode, beaconProxyConstructorArgs]);
+    const initCode = concat([BEACON_PROXY_CREATION_CODE, beaconProxyConstructorArgs]);
     return keccak256(initCode);
 };
-const getCounterFactualAddress = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
+export const getCounterFactualAddress = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -180,7 +198,41 @@ const getCounterFactualAddress = async (client, deviceUniqueIdentifier, deviceWa
     });
     return getAddress(create2Address);
 };
-const _encodeSignature = async (webAuthnSignature, validUntil) => {
+/**
+ * Optional drift guard. Recomputes the counterfactual address off-chain (using
+ * the pinned {@link BEACON_PROXY_CREATION_CODE}) and compares it against the
+ * on-chain `DeviceWalletFactory.getCounterFactualAddress` view - which derives
+ * the address from the BeaconProxy the factory ACTUALLY deploys. A mismatch
+ * means the pinned proxy bytecode (or init encoding) has drifted from the
+ * deployed contract, so this throws early instead of letting a UserOp deploy to,
+ * or fund, the wrong address.
+ *
+ * Not wired into the default account-creation path (it costs one extra RPC);
+ * call it explicitly in environments where you want the extra safety, e.g.
+ * after a contract redeploy or on first use against a new chain.
+ */
+export const _assertCounterfactualMatchesOnChain = async (client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    const offChain = await getCounterFactualAddress(client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt);
+    const deviceWalletFactory = getContract({
+        abi: DeviceWalletFactory,
+        address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
+        client,
+    });
+    // on-chain view arg order is (ownerKey, uid, salt) - differs from createAccount
+    const onChain = await deviceWalletFactory.read.getCounterFactualAddress([
+        deviceWalletOwnerKey,
+        deviceUniqueIdentifier,
+        salt,
+    ]);
+    if (getAddress(offChain) !== getAddress(onChain)) {
+        throw new CounterfactualMismatchError(getAddress(offChain), getAddress(onChain));
+    }
+    return offChain;
+};
+export const _encodeSignature = async (webAuthnSignature, validUntil) => {
     const encodedWebAuthnSignatureBytes = encodeAbiParameters([
         {
             type: "tuple",
@@ -201,30 +253,30 @@ const _encodeSignature = async (webAuthnSignature, validUntil) => {
     return signature;
 };
 // message here is the original message data (string or Uint8Array) directly from the app
-const _signMessage = async (message, credentialId, rpId) => {
+export const _signMessage = async (message, credentialId, rpId) => {
     const validUntil = Math.floor(Date.now() / 1000) + SIGNATURE_VALIDITY_SECONDS;
-    const payload = hashMessage({ raw: stringToBytes(message) });
+    // viem's SignableMessage is `string | { raw: Hex | ByteArray }`. A plain
+    // string is a UTF-8 message; the `{ raw }` form is already-serialized bytes
+    // (possibly a pre-computed digest). hashMessage handles both natively, so
+    // forward the message as-is rather than force-casting it to a string.
+    const payload = hashMessage(message);
     // The original message is passed to the stamp and sign function.
     // The stamp and sign function creates the EIP-191 digest hash using its hashMessage function
     // The result of the hashMessage(message) will be the `payload` used as a challenge
     const webAuthnSignature = await _stamp(credentialId, rpId, payload);
     return _encodeSignature(webAuthnSignature, validUntil);
 };
-const _signTypedData = async (typedData, organiationId, signWith) => {
+export const _signTypedData = async (typedData, credentialId, rpId) => {
     // signature valid until, UNIX timestamp in seconds
     const validUntil = Math.floor(Date.now() / 1000) + SIGNATURE_VALIDITY_SECONDS;
-    // TODO: Implement stamping for Typed Data
-    let webAuthnSignature = {
-        authenticatorData: `0x`,
-        clientDataJSON: "",
-        challengeIndex: BigInt(0),
-        typeIndex: BigInt(0),
-        r: BigInt(0),
-        s: BigInt(0)
-    };
+    // EIP-712 digest is the WebAuthn challenge, mirroring _signMessage's use of
+    // the EIP-191 digest. The contract's isValidSignature receives this same
+    // hashTypedData result and verifies the passkey signature against it.
+    const payload = hashTypedData(typedData);
+    const webAuthnSignature = await _stamp(credentialId, rpId, payload);
     return _encodeSignature(webAuthnSignature, validUntil);
 };
-const _signUserOperationHash = async (credentialId, rpId, userOpHash) => {
+export const _signUserOperationHash = async (credentialId, rpId, userOpHash) => {
     const validUntil = Math.floor(Date.now() / 1000) + SIGNATURE_VALIDITY_SECONDS;
     const messagePrecursor = encodePacked(["uint8", "uint48", "bytes32"], [
         1,
@@ -241,7 +293,6 @@ export const _getSmartWallet = async (client, credentialId, rpId, organiationId,
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new Error('Error: No signer account found with WalletClient');
-    const signWith = client.account.address;
     return toSmartContractAccount({
         /// REQUIRED PARAMS ///
         source: "MyAccount",
@@ -256,7 +307,7 @@ export const _getSmartWallet = async (client, credentialId, rpId, organiationId,
         // given a UO in the form of {target, data, value} should output the calldata for calling your contract's execution method
         encodeExecute: async (uo) => _encodeExecute(uo),
         signMessage: async ({ message }) => _signMessage(message, credentialId, rpId),
-        signTypedData: async (typedData) => _signTypedData(typedData, organiationId, signWith),
+        signTypedData: async (typedData) => _signTypedData(typedData, credentialId, rpId),
         /// OPTIONAL PARAMS ///
         // if you already know your account's address, pass that in here to avoid generating a new counterfactual
         accountAddress: await getCounterFactualAddress(client, deviceUniqueIdentifier, deviceWalletOwnerKey, salt),
@@ -294,6 +345,6 @@ export const _getSmartWalletClient = async (client, pimlicoAPIKey, gasPolicyId,
             fallback: http(values.rpcURL),
         }),
         // transport: http(values.rpcURL),
-        ...alchemyGasManagerMiddleware(gasPolicyId)
+        ...erc7677Middleware({ context: { policyId: gasPolicyId } })
     });
 };

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

@@ -0,0 +1,42 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { DeviceWallet } from "../../abis/index.js";
+/**
+ * Admin-EOA logic targeting a specific `DeviceWallet` instance (its address is
+ * passed in - there is no single factory address). Both functions are admin
+ * gated on chain (`deployESIMWallet` is `onlyESIMWalletAdmin`,
+ * `setESIMUniqueIdentifierForAnESIMWallet` is `onlyESIMWalletAdminOrRegistry`),
+ * so they cannot be driven from a device-wallet userOp and live on the EOA surface.
+ */
+/** Deploy a new eSIM wallet under a device wallet. `onlyESIMWalletAdmin`. */
+export const _deployESIMWallet = async (client, deviceWalletAddress, hasAccessToETH, salt) => {
+    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: deviceWalletAddress,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWallet,
+        functionName: 'deployESIMWallet',
+        args: [hasAccessToETH, salt]
+    });
+};
+/** Bind an eSIM's unique identifier to its wallet. `onlyESIMWalletAdminOrRegistry`. */
+export const _setESIMUniqueIdentifierForAnESIMWallet = async (client, deviceWalletAddress, eSIMWalletAddress, eSIMUniqueIdentifier) => {
+    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: deviceWalletAddress,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWallet,
+        functionName: 'setESIMUniqueIdentifierForAnESIMWallet',
+        args: [eSIMWalletAddress, eSIMUniqueIdentifier]
+    });
+};

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

@@ -0,0 +1,133 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { DeviceWalletFactory } from "../../abis/index.js";
+/**
+ * Admin-EOA logic for `DeviceWalletFactory`.
+ *
+ * Every function here is `onlyAdmin` / `onlyAdminOrRegistry` / `onlyOwner` on
+ * chain, i.e. the caller must be the `eSIMWalletAdmin` (or `upgradeManager`)
+ * EOA - never a device-wallet userOp. They therefore live on the EOA surface
+ * (`KokioAdmin`) and use `writeContract`, mirroring `_createAccountWithEOA`
+ * (which is reused as-is from `../deviceWalletFactory.js`).
+ */
+/**
+ * Batch-deploy device wallets for lazy/fiat users. `onlyAdminOrRegistry`,
+ * `payable`: `value` is the total ETH pot from which each `depositAmounts[i]`
+ * is drawn; any surplus is refunded to the caller on chain.
+ */
+export const _deployDeviceWalletForUsers = async (client, deviceUniqueIdentifiers, deviceWalletOwnersKey, salts, depositAmounts, value) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'deployDeviceWalletForUsers',
+        args: [deviceUniqueIdentifiers, deviceWalletOwnersKey, salts, depositAmounts],
+        value
+    });
+};
+/** Register a freshly created device wallet with the factory. `onlyAdminOrRegistry`. */
+export const _postCreateAccount = async (client, deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'postCreateAccount',
+        args: [deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey]
+    });
+};
+/** One-time wiring of the registry into the factory. `onlyAdmin`. */
+export const _addRegistryAddress = async (client, registryContractAddress) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'addRegistryAddress',
+        args: [registryContractAddress]
+    });
+};
+/** Update the vault that receives eSIM payments. `onlyAdmin`. */
+export const _updateVaultAddress = async (client, newVaultAddress) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'updateVaultAddress',
+        args: [newVaultAddress]
+    });
+};
+/** Step 1 of the 2-step admin handover: propose a new admin. `onlyAdmin`. */
+export const _requestAdminUpdate = async (client, newAdmin) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'requestAdminUpdate',
+        args: [newAdmin]
+    });
+};
+/**
+ * Step 2 of the 2-step admin handover: the proposed admin accepts. The chain
+ * requires `msg.sender` to equal the pending admin, so the `client` here must
+ * be the newly proposed admin EOA.
+ */
+export const _acceptAdminUpdate = async (client) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'acceptAdminUpdate',
+        args: []
+    });
+};
+/** Point the device-wallet beacon at a new implementation. `onlyOwner` (upgradeManager). */
+export const _updateDeviceWalletImplementation = async (client, newDeviceImpl) => {
+    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.DEVICE_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: DeviceWalletFactory,
+        functionName: 'updateDeviceWalletImplementation',
+        args: [newDeviceImpl]
+    });
+};

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

@@ -0,0 +1,30 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { ESIMWallet } from "../../abis/index.js";
+/**
+ * Admin-EOA logic targeting a specific `ESIMWallet` instance (address passed in).
+ * `buyDataBundle` is `onlyDeviceWalletOrESIMWalletAdmin`, so the admin EOA can
+ * call it directly.
+ */
+/**
+ * Buy a data bundle for an eSIM wallet. `onlyDeviceWalletOrESIMWalletAdmin`,
+ * `payable`. `value` is optional: the contract pulls any shortfall from the
+ * device wallet's balance, so an admin can pass `0n` when the wallet is funded,
+ * or forward `dataBundlePrice` to pay directly.
+ */
+export const _buyDataBundle = async (client, eSIMWalletAddress, dataBundleDetails, value = 0n) => {
+    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: eSIMWalletAddress,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ESIMWallet,
+        functionName: 'buyDataBundle',
+        args: [dataBundleDetails],
+        value
+    });
+};

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

@@ -0,0 +1,43 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { ESIMWalletFactory } from "../../abis/index.js";
+/**
+ * Admin-EOA logic for `ESIMWalletFactory`. Both functions are owner-gated
+ * (`addRegistryAddress` requires `msg.sender == owner()`, `updateESIMWalletImplementation`
+ * is `onlyOwner`), so the `client` must carry the `upgradeManager` EOA.
+ *
+ * Note: `ESIMWalletFactory.deployESIMWallet` is intentionally NOT exposed - it is
+ * `onlyRegistryOrDeviceWalletFactoryOrDeviceWallet`, so a bare EOA always reverts.
+ */
+/** One-time wiring of the registry into the eSIM factory. Owner only. */
+export const _addRegistryAddress = async (client, registryContractAddress) => {
+    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.ESIM_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ESIMWalletFactory,
+        functionName: 'addRegistryAddress',
+        args: [registryContractAddress]
+    });
+};
+/** Point the eSIM-wallet beacon at a new implementation. `onlyOwner`. */
+export const _updateESIMWalletImplementation = async (client, eSIMWalletImpl) => {
+    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.ESIM_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ESIMWalletFactory,
+        functionName: 'updateESIMWalletImplementation',
+        args: [eSIMWalletImpl]
+    });
+};

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

@@ -0,0 +1,62 @@
+import { _getChainSpecificConstants } from "../constants.js";
+import { MissingEOAWalletError } from "../errors.js";
+import { LazyWalletRegistry } from "../../abis/index.js";
+/**
+ * Admin-EOA logic for `LazyWalletRegistry`. All three functions are
+ * `onlyESIMWalletAdmin` on chain, so they can only succeed from the admin EOA -
+ * a device-wallet userOp (whose sender is the smart account) always reverts.
+ * This is why they belong on the EOA surface rather than the mobile userOp one.
+ */
+/** Record fiat/lazy purchase history for a batch of devices. `onlyESIMWalletAdmin`. */
+export const _batchPopulateHistory = async (client, deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails) => {
+    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.LAZY_WALLET_REGISTRY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: LazyWalletRegistry,
+        functionName: 'batchPopulateHistory',
+        args: [deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails]
+    });
+};
+/**
+ * Materialise a lazily-provisioned device wallet and its eSIMs on chain.
+ * `onlyESIMWalletAdmin`, `payable`: the contract requires `depositAmount == msg.value`,
+ * so `value` is set to `depositAmount` here.
+ */
+export const _deployLazyWalletAndSetESIMIdentifier = async (client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount) => {
+    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.LAZY_WALLET_REGISTRY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: LazyWalletRegistry,
+        functionName: 'deployLazyWalletAndSetESIMIdentifier',
+        args: [deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount],
+        value: depositAmount
+    });
+};
+/** Re-point an eSIM identifier from an old device to a new one. `onlyESIMWalletAdmin`. */
+export const _switchESIMIdentifierToNewDeviceIdentifier = async (client, eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier) => {
+    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.LAZY_WALLET_REGISTRY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: LazyWalletRegistry,
+        functionName: 'switchESIMIdentifierToNewDeviceIdentifier',
+        args: [eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier]
+    });
+};

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

@@ -0,0 +1,45 @@
+import { publicActions } from "viem";
+import { DeviceWallet } from "../../../abis/index.js";
+/**
+ * Read-only admin logic targeting a specific `DeviceWallet` instance (its address
+ * is passed in). Surfaces the instance's public storage getters + `getVaultAddress`
+ * view for the backend. Each read extends the `WalletClient` with `publicActions`;
+ * no EOA account is required, and the target is the instance address (not a
+ * factory address, so no chain-constants lookup is needed).
+ */
+/** The device's unique identifier string. */
+export const _deviceUniqueIdentifier = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "deviceUniqueIdentifier",
+        args: []
+    });
+};
+/** Whether an eSIM wallet is a valid child of this device wallet. */
+export const _isValidESIMWallet = async (client, deviceWalletAddress, eSIMWallet) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "isValidESIMWallet",
+        args: [eSIMWallet]
+    });
+};
+/** Whether an eSIM wallet is allowed to pull ETH from this device wallet. */
+export const _canPullETH = async (client, deviceWalletAddress, eSIMWallet) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "canPullETH",
+        args: [eSIMWallet]
+    });
+};
+/** The vault address this device wallet pays eSIM purchases to. */
+export const _getVaultAddress = async (client, deviceWalletAddress) => {
+    return client.extend(publicActions).readContract({
+        address: deviceWalletAddress,
+        abi: DeviceWallet,
+        functionName: "getVaultAddress",
+        args: []
+    });
+};