kokio-sdk 1.1.0 → 2.0.0

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

@@ -1,15 +1,18 @@
 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`).
- */
+// 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`).
+//
+// On the live deployment the owner is the `ProtocolAdmin` timelock, not an EOA,
+// so an `onlyOwner` call sent directly reverts. Route those through
+// `protocolAdmin.proposer.schedule` instead. The direct path stays for
+// deployments whose owner is a plain EOA or multisig.
 /**
  * Batch-deploy device wallets for lazy/fiat users. `onlyAdminOrRegistry`,
  * `payable`: `value` is the total ETH pot from which each `depositAmounts[i]`
@@ -31,8 +34,12 @@ export const _deployDeviceWalletForUsers = async (client, deviceUniqueIdentifier
         value
     });
 };
-/** Register a freshly created device wallet with the factory. `onlyAdminOrRegistry`. */
-export const _postCreateAccount = async (client, deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey) => {
+/**
+ * Register a freshly created device wallet with the factory. `onlyAdminOrRegistry`.
+ * The salt has to be the one the deploying `createAccount` used, since the
+ * factory rederives the counterfactual address from it to check the wallet.
+ */
+export const _postCreateAccount = async (client, deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey, salt) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -44,7 +51,7 @@ export const _postCreateAccount = async (client, deviceWallet, deviceUniqueIdent
         account: client.account.address,
         abi: DeviceWalletFactory,
         functionName: 'postCreateAccount',
-        args: [deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey]
+        args: [deviceWallet, deviceUniqueIdentifier, deviceWalletOwnerKey, salt]
     });
 };
 /** One-time wiring of the registry into the factory. `onlyAdmin`. */
@@ -63,8 +70,8 @@ export const _addRegistryAddress = async (client, registryContractAddress) => {
         args: [registryContractAddress]
     });
 };
-/** Update the vault that receives eSIM payments. `onlyAdmin`. */
-export const _updateVaultAddress = async (client, newVaultAddress) => {
+/** 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);
@@ -75,48 +82,62 @@ export const _updateVaultAddress = async (client, newVaultAddress) => {
         chain: values.chain,
         account: client.account.address,
         abi: DeviceWalletFactory,
-        functionName: 'updateVaultAddress',
-        args: [newVaultAddress]
+        functionName: 'updateDeviceWalletImplementation',
+        args: [newDeviceImpl]
     });
 };
-/** Step 1 of the 2-step admin handover: propose a new admin. `onlyAdmin`. */
-export const _requestAdminUpdate = async (client, newAdmin) => {
+// ---------------------------------------------------------------------------
+// Owner payloads - only reachable through schedule
+// ---------------------------------------------------------------------------
+// Both are `onlyOwner`, and on the live deployment the owner is the timelock, so
+// they exist as something to schedule rather than to send. Each returns the
+// `OwnerCall` to hand to `protocolAdmin.schedule`.
+/**
+ * Offer ownership to a new address. Pass the result to `schedule`.
+ *
+ * Ownable2Step, so the offer changes nothing until the named address calls
+ * `acceptOwnership`. Note this hands over the beacon too, since the factory owns
+ * it, so the new owner can move every deployed device wallet at once.
+ */
+export const _transferOwnershipCall = async (client, newOwner) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new MissingEOAWalletError();
-    return client.writeContract({
+    return {
         address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
-        chain: values.chain,
-        account: client.account.address,
         abi: DeviceWalletFactory,
-        functionName: 'requestAdminUpdate',
-        args: [newAdmin]
-    });
+        functionName: 'transferOwnership',
+        args: [newOwner],
+    };
 };
 /**
- * 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.
+ * Point the factory's own proxy at a new implementation. Builds
+ * `upgradeToAndCall`. Pass the result to `schedule`.
+ *
+ * This does not touch deployed device wallets. They read their implementation
+ * from the beacon, which moves through `updateDeviceWalletImplementation`
+ * instead. Changing what the factory deploys next is a beacon update, not this.
  */
-export const _acceptAdminUpdate = async (client) => {
+export const _upgradeCall = async (client, newImplementation, data = '0x') => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new MissingEOAWalletError();
-    return client.writeContract({
+    return {
         address: values.factoryAddresses.DEVICE_WALLET_FACTORY,
-        chain: values.chain,
-        account: client.account.address,
         abi: DeviceWalletFactory,
-        functionName: 'acceptAdminUpdate',
-        args: []
-    });
+        functionName: 'upgradeToAndCall',
+        args: [newImplementation, data],
+    };
 };
-/** Point the device-wallet beacon at a new implementation. `onlyOwner` (upgradeManager). */
-export const _updateDeviceWalletImplementation = async (client, newDeviceImpl) => {
+/**
+ * Take ownership after a `transferOwnership` named this client. `msg.sender`
+ * must equal `pendingOwner`, so the `client` is the incoming owner.
+ *
+ * Where the incoming owner is the timelock, use
+ * `protocolAdmin.acceptOwnershipBatch` instead, which accepts for every contract
+ * at once.
+ */
+export const _acceptOwnership = async (client) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -127,7 +148,7 @@ export const _updateDeviceWalletImplementation = async (client, newDeviceImpl) =
         chain: values.chain,
         account: client.account.address,
         abi: DeviceWalletFactory,
-        functionName: 'updateDeviceWalletImplementation',
-        args: [newDeviceImpl]
+        functionName: 'acceptOwnership',
+        args: []
     });
 };

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

@@ -1,11 +1,9 @@
 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.
- */
+// 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

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

@@ -1,14 +1,17 @@
 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.
- */
+// 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.
+//
+// On the live deployment the owner is the `ProtocolAdmin` timelock, not an EOA,
+// so either call sent directly reverts. Route them through
+// `protocolAdmin.proposer.schedule` instead. The direct path stays for
+// deployments whose owner is a plain EOA or multisig.
+//
+// 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();
@@ -41,3 +44,68 @@ export const _updateESIMWalletImplementation = async (client, eSIMWalletImpl) =>
         args: [eSIMWalletImpl]
     });
 };
+// ---------------------------------------------------------------------------
+// Owner payloads - only reachable through schedule
+// ---------------------------------------------------------------------------
+// Both are `onlyOwner`, and on the live deployment the owner is the timelock, so
+// they exist as something to schedule rather than to send. Each returns the
+// `OwnerCall` to hand to `protocolAdmin.schedule`.
+/**
+ * Offer ownership to a new address. Pass the result to `schedule`.
+ *
+ * Ownable2Step, so the offer changes nothing until the named address calls
+ * `acceptOwnership`. Note this hands over the beacon too, since the factory owns
+ * it, so the new owner can move every deployed eSIM wallet at once.
+ */
+export const _transferOwnershipCall = async (client, newOwner) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return {
+        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
+        abi: ESIMWalletFactory,
+        functionName: 'transferOwnership',
+        args: [newOwner],
+    };
+};
+/**
+ * Point the factory's own proxy at a new implementation. Builds
+ * `upgradeToAndCall`. Pass the result to `schedule`.
+ *
+ * This does not touch deployed eSIM wallets. They read their implementation from
+ * the beacon, which moves through `updateESIMWalletImplementation` instead.
+ */
+export const _upgradeCall = async (client, newImplementation, data = '0x') => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return {
+        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
+        abi: ESIMWalletFactory,
+        functionName: 'upgradeToAndCall',
+        args: [newImplementation, data],
+    };
+};
+/**
+ * Take ownership after a `transferOwnership` named this client. `msg.sender`
+ * must equal `pendingOwner`, so the `client` is the incoming owner.
+ *
+ * Where the incoming owner is the timelock, use
+ * `protocolAdmin.acceptOwnershipBatch` instead, which accepts for every contract
+ * at once.
+ */
+export const _acceptOwnership = 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.ESIM_WALLET_FACTORY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: ESIMWalletFactory,
+        functionName: 'acceptOwnership',
+        args: []
+    });
+};

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

@@ -1,17 +1,48 @@
+import { BaseError, ContractFunctionRevertedError, isAddressEqual, parseEventLogs, publicActions, } from "viem";
 import { _getChainSpecificConstants } from "../constants.js";
-import { MissingEOAWalletError } from "../errors.js";
-import { LazyWalletRegistry } from "../../abis/index.js";
+import { BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, MissingEOAWalletError, StalledBatchError, } from "../errors.js";
+import { LazyWalletRegistry, Registry } from "../../abis/index.js";
+import { _eSIMWalletsDeployed, _lazyDeployedESIMWallet } from "./reads/lazyWalletRegistry.reads.js";
+// Admin-EOA logic for `LazyWalletRegistry`. Every function here is
+// `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.
+//
+// Deployment and the history copy are both paginated on chain. The thin wrappers
+// send one batch each; the two `AllBatches` functions below run a device or an
+// eSIM to completion and are what the backend should normally call.
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 /**
- * 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.
+ * The contract's own caps, mirrored here because they are `constant` on chain and
+ * reading them would cost a round trip on every call. The fork tier checks these
+ * against the live deployment, so an upgrade that moved one would fail there
+ * rather than turning every call into a reverted transaction.
  */
-/** Record fiat/lazy purchase history for a batch of devices. `onlyESIMWalletAdmin`. */
-export const _batchPopulateHistory = async (client, deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails) => {
+export const MAX_ESIM_WALLETS_PER_CALL = 20n;
+export const MAX_HISTORY_ENTRIES_PER_CALL = 50n;
+/**
+ * Default batch sizes, both below the caps above.
+ *
+ * A continuation call costs about 28,000 gas before it deploys anything, against
+ * roughly 556,000 per eSIM wallet, so a smaller batch buys headroom for almost
+ * nothing: running a 45 eSIM device at 10 rather than 20 costs about 0.4% more
+ * gas in total. That headroom matters because a full batch of 20 measures between
+ * 9.3M and 11.8M gas depending on identifier length and storage warmth, which is
+ * uncomfortably close to a per-transaction gas ceiling.
+ */
+export const DEFAULT_ESIM_WALLETS_PER_CALL = 10n;
+export const DEFAULT_HISTORY_ENTRIES_PER_CALL = 25n;
+const _resolve = async (client) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
-    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return _getChainSpecificConstants(chainID, rpcURL);
+};
+// ---------------------------------------------------------------------------
+// One transaction each, mirroring the contract
+// ---------------------------------------------------------------------------
+/** Record fiat/lazy purchase history for a batch of devices. `onlyESIMWalletAdmin`. */
+export const _batchPopulateHistory = async (client, deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails) => {
+    const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
     return client.writeContract({
@@ -24,14 +55,16 @@ export const _batchPopulateHistory = async (client, deviceUniqueIdentifiers, eSI
     });
 };
 /**
- * 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.
+ * Materialise a lazily-provisioned device wallet and the first batch of its eSIMs
+ * on chain. `onlyESIMWalletAdmin`, `payable`: the contract requires
+ * `depositAmount == msg.value`, so `value` is set to `depositAmount` here.
+ *
+ * One transaction. `maxWallets` caps how many eSIM wallets it deploys, and the
+ * contract refuses anything above `MAX_ESIM_WALLETS_PER_CALL` rather than
+ * clamping it. Prefer `_deployLazyWalletAllBatches`, which finishes the device.
  */
-export const _deployLazyWalletAndSetESIMIdentifier = async (client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount) => {
-    const chainID = await client.getChainId();
-    const rpcURL = client.transport.url;
-    const values = _getChainSpecificConstants(chainID, rpcURL);
+export const _deployLazyWalletAndSetESIMIdentifier = async (client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount, maxWallets) => {
+    const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
     return client.writeContract({
@@ -40,12 +73,290 @@ export const _deployLazyWalletAndSetESIMIdentifier = async (client, deviceOwnerP
         account: client.account.address,
         abi: LazyWalletRegistry,
         functionName: 'deployLazyWalletAndSetESIMIdentifier',
-        args: [deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount],
+        args: [deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount, maxWallets],
         value: depositAmount
     });
 };
+/**
+ * Deploy the next batch of eSIM wallets for a device the lazy route already
+ * started. `onlyESIMWalletAdmin`.
+ *
+ * One transaction. The contract reads its position from a cursor, so a dropped
+ * transaction is retried by repeating the identical call. It reverts
+ * `AllESIMWalletsDeployed` once nothing is left, which is the terminal condition
+ * rather than a failure.
+ */
+export const _deployMoreESIMWalletsForLazyDevice = async (client, deviceUniqueIdentifier, maxWallets) => {
+    const values = await _resolve(client);
+    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: 'deployMoreESIMWalletsForLazyDevice',
+        args: [deviceUniqueIdentifier, maxWallets]
+    });
+};
+/**
+ * Copy the next batch of an eSIM's stored purchase history onto its deployed
+ * wallet. `onlyESIMWalletAdmin`.
+ *
+ * One transaction, with its own cursor per eSIM. Reverts `HistoryAlreadyCopied`
+ * once nothing is left. Prefer `_setHistoryForLazyWalletAllBatches`.
+ */
+export const _setHistoryForLazyWallet = async (client, eSIMIdentifier, maxEntries) => {
+    const values = await _resolve(client);
+    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: 'setHistoryForLazyWallet',
+        args: [eSIMIdentifier, maxEntries]
+    });
+};
 /** Re-point an eSIM identifier from an old device to a new one. `onlyESIMWalletAdmin`. */
 export const _switchESIMIdentifierToNewDeviceIdentifier = async (client, eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier) => {
+    const values = await _resolve(client);
+    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]
+    });
+};
+// ---------------------------------------------------------------------------
+// Reading a batch back
+// ---------------------------------------------------------------------------
+// `writeContract` returns a hash, not the function's return values, so how much
+// is left comes from the event each batch emits rather than from the call.
+const _batchEvent = async (client, lazyRegistryAddress, hash, eventName) => {
+    const receipt = await client.waitForTransactionReceipt({ hash });
+    const logs = parseEventLogs({
+        abi: LazyWalletRegistry,
+        eventName,
+        logs: receipt.logs.filter((log) => isAddressEqual(log.address, lazyRegistryAddress)),
+    });
+    if (logs.length === 0)
+        throw new MissingBatchEventError(eventName, hash);
+    return logs[0].args;
+};
+/**
+ * Whether a call hit its terminal condition. Both paginated calls revert when
+ * there is nothing left rather than returning quietly, so a simulation is the
+ * only way to tell "already finished" from "more to do" without paying for a
+ * transaction that fails.
+ */
+const _isFinished = async (client, request, terminalError) => {
+    try {
+        await client.simulateContract(request);
+        return false;
+    }
+    catch (err) {
+        if (err instanceof BaseError) {
+            const revert = err.walk((e) => e instanceof ContractFunctionRevertedError);
+            if (revert instanceof ContractFunctionRevertedError && revert.data?.errorName === terminalError) {
+                return true;
+            }
+        }
+        throw err;
+    }
+};
+// ---------------------------------------------------------------------------
+// Run a device or an eSIM to completion
+// ---------------------------------------------------------------------------
+/**
+ * Deploy a lazy device and every one of its eSIM wallets, over as many
+ * transactions as that takes. `onlyESIMWalletAdmin`.
+ *
+ * Resumable. A device that is part-deployed, because a batch was dropped or an
+ * earlier call threw, is continued from its cursor instead of being restarted,
+ * so retrying is just calling this again with the same arguments. Pass a deposit
+ * of 0 on a retry: only the first batch is payable and it already took one.
+ *
+ * All of a device's purchase history has to be recorded before this runs. The
+ * first batch creates the device wallet, and `batchPopulateHistory` refuses any
+ * device that has one.
+ *
+ * @param maxWallets eSIM wallets per transaction, 1 to `MAX_ESIM_WALLETS_PER_CALL`.
+ */
+export const _deployLazyWalletAllBatches = async (client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount, maxWallets = DEFAULT_ESIM_WALLETS_PER_CALL) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    const publicClient = client.extend(publicActions);
+    const lazyRegistryAddress = values.factoryAddresses.LAZY_WALLET_REGISTRY;
+    if (maxWallets < 1n || maxWallets > MAX_ESIM_WALLETS_PER_CALL) {
+        throw new BatchSizeOutOfRangeError("maxWallets", maxWallets, MAX_ESIM_WALLETS_PER_CALL);
+    }
+    const alreadyDeployed = await _eSIMWalletsDeployed(client, deviceUniqueIdentifier);
+    const batches = [];
+    let deviceWallet;
+    let outstanding;
+    if (alreadyDeployed === 0n) {
+        const hash = await _deployLazyWalletAndSetESIMIdentifier(client, deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount, maxWallets);
+        const first = await _batchEvent(publicClient, lazyRegistryAddress, hash, "LazyESIMWalletsDeployed");
+        deviceWallet = first._deviceWallet;
+        outstanding = first._remaining > 0n;
+        batches.push({
+            hash,
+            eSIMWallets: first._eSIMWallets,
+            eSIMIdentifiers: first._eSIMUniqueIdentifiers,
+            remaining: first._remaining,
+        });
+    }
+    else {
+        if (depositAmount !== 0n)
+            throw new DepositOnResumeError(deviceUniqueIdentifier, depositAmount);
+        deviceWallet = await publicClient.readContract({
+            address: values.factoryAddresses.REGISTRY,
+            abi: Registry,
+            functionName: "uniqueIdentifierToDeviceWallet",
+            args: [deviceUniqueIdentifier]
+        });
+        const finished = await _isFinished(publicClient, {
+            address: lazyRegistryAddress,
+            abi: LazyWalletRegistry,
+            functionName: "deployMoreESIMWalletsForLazyDevice",
+            args: [deviceUniqueIdentifier, maxWallets],
+            account: client.account.address,
+        }, "AllESIMWalletsDeployed");
+        if (finished) {
+            return { deviceWallet, eSIMWallets: [], eSIMIdentifiers: [], batches: [], alreadyComplete: true };
+        }
+        outstanding = true;
+    }
+    while (outstanding) {
+        const hash = await _deployMoreESIMWalletsForLazyDevice(client, deviceUniqueIdentifier, maxWallets);
+        const next = await _batchEvent(publicClient, lazyRegistryAddress, hash, "LazyESIMWalletsDeployed");
+        if (next._eSIMWallets.length === 0)
+            throw new StalledBatchError(hash, next._remaining);
+        batches.push({
+            hash,
+            eSIMWallets: next._eSIMWallets,
+            eSIMIdentifiers: next._eSIMUniqueIdentifiers,
+            remaining: next._remaining,
+        });
+        outstanding = next._remaining > 0n;
+    }
+    return {
+        deviceWallet,
+        eSIMWallets: batches.flatMap((batch) => [...batch.eSIMWallets]),
+        eSIMIdentifiers: batches.flatMap((batch) => [...batch.eSIMIdentifiers]),
+        batches,
+        alreadyComplete: false,
+    };
+};
+/**
+ * Copy an eSIM's whole stored purchase history onto its wallet, over as many
+ * transactions as that takes. `onlyESIMWalletAdmin`.
+ *
+ * Resumable for the same reason as the deployment: the cursor lives on chain, so
+ * a partly copied eSIM is continued rather than restarted.
+ *
+ * The history cursor is per eSIM and the deploy cursor is per device, so this can
+ * run against an eSIM whose wallet has landed while its siblings are still
+ * undeployed.
+ *
+ * @param maxEntries entries per transaction, 1 to `MAX_HISTORY_ENTRIES_PER_CALL`.
+ */
+export const _setHistoryForLazyWalletAllBatches = async (client, eSIMIdentifier, maxEntries = DEFAULT_HISTORY_ENTRIES_PER_CALL) => {
+    const values = await _resolve(client);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    const publicClient = client.extend(publicActions);
+    const lazyRegistryAddress = values.factoryAddresses.LAZY_WALLET_REGISTRY;
+    if (maxEntries < 1n || maxEntries > MAX_HISTORY_ENTRIES_PER_CALL) {
+        throw new BatchSizeOutOfRangeError("maxEntries", maxEntries, MAX_HISTORY_ENTRIES_PER_CALL);
+    }
+    // The same lookup the contract authorises on. Checking it here turns a
+    // reverted transaction into a typed error.
+    const eSIMWallet = await _lazyDeployedESIMWallet(client, eSIMIdentifier);
+    if (eSIMWallet === ZERO_ADDRESS)
+        throw new ESIMWalletNotLazyDeployedError(eSIMIdentifier);
+    const finished = await _isFinished(publicClient, {
+        address: lazyRegistryAddress,
+        abi: LazyWalletRegistry,
+        functionName: "setHistoryForLazyWallet",
+        args: [eSIMIdentifier, maxEntries],
+        account: client.account.address,
+    }, "HistoryAlreadyCopied");
+    if (finished)
+        return { eSIMWallet, copied: 0n, batches: [], alreadyComplete: true };
+    const batches = [];
+    let copied = 0n;
+    let outstanding = true;
+    while (outstanding) {
+        const hash = await _setHistoryForLazyWallet(client, eSIMIdentifier, maxEntries);
+        const batch = await _batchEvent(publicClient, lazyRegistryAddress, hash, "LazyHistoryCopied");
+        if (batch._copied === 0n)
+            throw new StalledBatchError(hash, batch._remaining);
+        batches.push({ hash, copied: batch._copied, remaining: batch._remaining });
+        copied += batch._copied;
+        outstanding = batch._remaining > 0n;
+    }
+    return { eSIMWallet, copied, batches, alreadyComplete: false };
+};
+// ---------------------------------------------------------------------------
+// Owner payloads - only reachable through schedule
+// ---------------------------------------------------------------------------
+// Both are `onlyOwner`, and on the live deployment the owner is the timelock, so
+// they exist as something to schedule rather than to send. Each returns the
+// `OwnerCall` to hand to `protocolAdmin.schedule`.
+/**
+ * Offer ownership to a new address. Pass the result to `schedule`.
+ *
+ * Ownable2Step, so the offer changes nothing until the named address calls
+ * `acceptOwnership`. Until then the current owner keeps every power.
+ */
+export const _transferOwnershipCall = async (client, newOwner) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return {
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: 'transferOwnership',
+        args: [newOwner],
+    };
+};
+/**
+ * Point the proxy at a new implementation. Builds `upgradeToAndCall`. Pass the
+ * result to `schedule`.
+ *
+ * This contract holds every fiat user's unclaimed purchase history, so a layout
+ * change here strands data that has no other copy. Diff the storage layout
+ * before scheduling. `data` runs on the proxy straight after the swap and is
+ * where a `reinitializer` goes.
+ */
+export const _upgradeCall = async (client, newImplementation, data = '0x') => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return {
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: 'upgradeToAndCall',
+        args: [newImplementation, data],
+    };
+};
+/**
+ * Take ownership after a `transferOwnership` named this client. `msg.sender`
+ * must equal `pendingOwner`, so the `client` is the incoming owner.
+ *
+ * Where the incoming owner is the timelock, use
+ * `protocolAdmin.acceptOwnershipBatch` instead, which accepts for every contract
+ * at once.
+ */
+export const _acceptOwnership = async (client) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -56,7 +367,7 @@ export const _switchESIMIdentifierToNewDeviceIdentifier = async (client, eSIMIde
         chain: values.chain,
         account: client.account.address,
         abi: LazyWalletRegistry,
-        functionName: 'switchESIMIdentifierToNewDeviceIdentifier',
-        args: [eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier]
+        functionName: 'acceptOwnership',
+        args: []
     });
 };