kokio-sdk 0.1.4 → 1.0.0

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

@@ -1,6 +1,7 @@
 import { createSmartAccountClient, getEntryPoint, toSmartContractAccount, split, erc7677Middleware } from "@aa-sdk/core";
-import { http, encodeFunctionData, encodePacked, encodeAbiParameters, parseAbiParameters, getContract, concat, keccak256, getContractAddress, getAddress, hashMessage, stringToBytes, toHex, hexToBytes, bytesToHex } from "viem";
+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 { isoBase64URL } from "@simplewebauthn/server/helpers";
@@ -15,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).
@@ -22,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",
@@ -119,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;
@@ -131,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);
@@ -144,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,
@@ -156,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);
@@ -179,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",
@@ -200,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,
@@ -240,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",
@@ -255,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),

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: []
+    });
+};

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