kokio-sdk 1.0.0 → 2.0.0

package/dist/esm/logic/eSIMWallet.js

@@ -1,27 +1,39 @@
-import { encodeFunctionData } from "viem";
+import { encodeFunctionData, maxUint256 } from "viem";
 import { MissingSmartWalletError } from "./errors.js";
 import { ESIMWallet } from "../abis/index.js";
+import { _defaultDataBundlePriceCap } from "./registry.js";
 // Not exposed on this surface:
-//   - populateHistory is `onlyRegistry` - callable only by the registry contract.
+//   - populateHistory and setESIMUniqueIdentifier are `onlyRegistry` - callable
+//     only by the registry contract. Naming an eSIM goes through
+//     `admin.registry.assignESIMIdentifier` instead.
 //   - transferOwnership is a `pure` override that always reverts
 //     ("Use acceptOwnershipTransfer instead."); use requestTransferOwnership /
 //     acceptOwnershipTransfer instead.
 // The functions below are `onlyDeviceWallet` (the eSIM wallet's owner IS the device
 // wallet) or otherwise satisfiable by the device-wallet userOp sender, so they succeed.
-export const _setESIMUniqueIdentifier = async (client, address, eSIMUniqueIdentifier) => {
+/**
+ * Cap what this eSIM wallet may be charged for one data bundle. Zero hands it
+ * back to the registry's ceiling.
+ *
+ * `onlyDeviceWallet`, so it needs the user's own signature. That is the point:
+ * the admin names the price on `buyDataBundle`, so it must not be able to raise
+ * the ceiling on that price too. A handover clears the cap, and the new owner has
+ * to set it again.
+ */
+export const _setDataBundlePriceCap = async (client, address, cap) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlyDeviceWallet`.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "setESIMUniqueIdentifier",
-                args: [eSIMUniqueIdentifier]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "setDataBundlePriceCap",
+                    args: [cap]
+                })
+            }]
     });
 };
 export const _buyDataBundle = async (client, address, dataBundleDetails) => {
@@ -30,14 +42,14 @@ export const _buyDataBundle = async (client, address, dataBundleDetails) => {
     // UserOp - `onlyDeviceWalletOrESIMWalletAdmin`; the owning device wallet may buy.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "buyDataBundle",
-                args: [dataBundleDetails]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "buyDataBundle",
+                    args: [dataBundleDetails]
+                })
+            }]
     });
 };
 // `owner()` is a `view` - read it directly instead of spending a userOp.
@@ -49,20 +61,78 @@ export const _owner = async (client, address) => {
         args: []
     });
 };
+/**
+ * The ceiling that actually applies to this wallet's next purchase, in wei.
+ * Read it before naming a price on `buyDataBundle`, since a price above the
+ * ceiling reverts.
+ *
+ * Resolved the way the contract resolves it. The wallet's own cap wins when it
+ * has one. Zero there means "follow the registry", which is where a fresh wallet
+ * and a newly handed-over wallet both start. A zero on both means no ceiling at
+ * all, so this returns `maxUint256` rather than a zero that reads as "you may
+ * not spend anything".
+ *
+ * That last case cannot happen on a live deployment: the registry refuses a zero
+ * cap in both `initialize` and `setDefaultDataBundlePriceCap`. It is handled
+ * because the contract's own check treats zero as unlimited, not because the
+ * state is reachable.
+ */
+export const _dataBundlePriceCap = async (client, address) => {
+    const walletCap = await client.readContract({
+        address,
+        abi: ESIMWallet,
+        functionName: "dataBundlePriceCap",
+        args: []
+    });
+    if (walletCap !== 0n)
+        return walletCap;
+    const registryCap = await _defaultDataBundlePriceCap(client);
+    return registryCap === 0n ? maxUint256 : registryCap;
+};
+/**
+ * The device wallet this eSIM wallet belongs to. Tracks `owner`, but it is its
+ * own storage slot with its own getter, so read whichever one you mean.
+ */
+export const _deviceWallet = async (client, address) => {
+    return client.readContract({
+        address,
+        abi: ESIMWallet,
+        functionName: "deviceWallet",
+        args: []
+    });
+};
+/**
+ * One data bundle purchase, by position. Holds every purchase this wallet has
+ * made, and for a wallet that came off the fiat path it also holds the
+ * pre-deployment purchases the lazy registry copies in.
+ *
+ * There is no length getter on the contract. Read upwards from zero until a call
+ * reverts, or track the count from the `DataBundleBought` and
+ * `TransactionHistoryPopulated` events.
+ */
+export const _transactionHistory = async (client, address, index) => {
+    const [dataBundleID, dataBundlePrice] = await client.readContract({
+        address,
+        abi: ESIMWallet,
+        functionName: "transactionHistory",
+        args: [index]
+    });
+    return { dataBundleID, dataBundlePrice };
+};
 export const _requestTransferOwnership = async (client, address, newOwner) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlyDeviceWallet`; the owning device wallet requests the transfer.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "requestTransferOwnership",
-                args: [newOwner]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "requestTransferOwnership",
+                    args: [newOwner]
+                })
+            }]
     });
 };
 export const _acceptOwnershipTransfer = async (client, address) => {
@@ -71,14 +141,14 @@ export const _acceptOwnershipTransfer = async (client, address) => {
     // UserOp - the caller must be the pending `newRequestedOwner` (the new device wallet).
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "acceptOwnershipTransfer",
-                args: []
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "acceptOwnershipTransfer",
+                    args: []
+                })
+            }]
     });
 };
 export const _sendETHToDeviceWallet = async (client, address, amount) => {
@@ -87,13 +157,13 @@ export const _sendETHToDeviceWallet = async (client, address, amount) => {
     // UserOp - `onlyDeviceWallet`.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "sendETHToDeviceWallet",
-                args: [amount]
-            })
-        }
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "sendETHToDeviceWallet",
+                    args: [amount]
+                })
+            }]
     });
 };

package/dist/esm/logic/eSIMWalletFactory.js

@@ -18,14 +18,14 @@ export const _deployESIMWalletWithUserOp = async (client, deviceWalletAddress, s
     // UserOp - the device-wallet sender is a valid device wallet per the registry.
     return client.sendUserOperation({
         account: client.account,
-        uo: {
-            target: values.factoryAddresses.ESIM_WALLET_FACTORY,
-            data: encodeFunctionData({
-                abi: ESIMWalletFactory,
-                functionName: "deployESIMWallet",
-                args: [deviceWalletAddress, salt]
-            })
-        }
+        calls: [{
+                to: values.factoryAddresses.ESIM_WALLET_FACTORY,
+                data: encodeFunctionData({
+                    abi: ESIMWalletFactory,
+                    functionName: "deployESIMWallet",
+                    args: [deviceWalletAddress, salt]
+                })
+            }]
     });
 };
 export const _getCurrentESIMWalletImplementation = async (client) => {

package/dist/esm/logic/errors.js

@@ -68,6 +68,70 @@ export class CounterfactualMismatchError extends KokioError {
         this.onChain = onChain;
     }
 }
+/**
+ * A batch size outside what the contract accepts. Both paginated calls refuse a
+ * request above their cap rather than clamping it, so this is caught locally to
+ * save the caller a reverted transaction.
+ */
+export class BatchSizeOutOfRangeError extends KokioError {
+    requested;
+    max;
+    constructor(what, requested, max) {
+        super("BATCH_SIZE_OUT_OF_RANGE", `${what} must be between 1 and ${max}, got ${requested}.`);
+        this.requested = requested;
+        this.max = max;
+    }
+}
+/**
+ * A deposit was passed to a lazy deployment that turned out to be a resume. Only
+ * the first batch is payable and it already took the deposit, so carrying on
+ * would fund the device with less than the caller asked for.
+ */
+export class DepositOnResumeError extends KokioError {
+    deviceUniqueIdentifier;
+    depositAmount;
+    constructor(deviceUniqueIdentifier, depositAmount) {
+        super("DEPOSIT_ON_RESUME", `Device ${deviceUniqueIdentifier} is already part-deployed, so its deposit was taken by ` +
+            `the first batch. Retry with a deposit of 0 rather than ${depositAmount}.`);
+        this.deviceUniqueIdentifier = deviceUniqueIdentifier;
+        this.depositAmount = depositAmount;
+    }
+}
+/**
+ * History was aimed at an eSIM this registry never deployed a wallet for. That
+ * lookup is the whole authorisation on chain, so it cannot be worked around.
+ */
+export class ESIMWalletNotLazyDeployedError extends KokioError {
+    eSIMIdentifier;
+    constructor(eSIMIdentifier) {
+        super("ESIM_WALLET_NOT_LAZY_DEPLOYED", `No lazily deployed eSIM wallet for identifier ${eSIMIdentifier}.`);
+        this.eSIMIdentifier = eSIMIdentifier;
+    }
+}
+/**
+ * A batch landed but its receipt carried no event from the lazy registry. The
+ * loop reads its position from that event, so it cannot continue without one.
+ */
+export class MissingBatchEventError extends KokioError {
+    hash;
+    constructor(eventName, hash) {
+        super("MISSING_BATCH_EVENT", `Transaction ${hash} emitted no ${eventName} event from the lazy registry.`);
+        this.hash = hash;
+    }
+}
+/**
+ * A batch reported work outstanding but did none of it. Nothing on chain should
+ * produce this; it stops the loop rather than letting it spin.
+ */
+export class StalledBatchError extends KokioError {
+    hash;
+    remaining;
+    constructor(hash, remaining) {
+        super("STALLED_BATCH", `Transaction ${hash} made no progress with ${remaining} still outstanding.`);
+        this.hash = hash;
+        this.remaining = remaining;
+    }
+}
 // Every ABI that can surface a custom error from an on-chain revert. viem's
 // `decodeErrorResult` walks each ABI's `error` fragments to match the 4-byte
 // selector in the revert data.

package/dist/esm/logic/registry.js

@@ -0,0 +1,236 @@
+import { encodeFunctionData } from "viem";
+import { _getChainSpecificConstants } from "./constants.js";
+import { Registry } from "../abis/index.js";
+import { MissingSmartWalletError } from "./errors.js";
+// A userOp from a device wallet arrives at the registry with msg.sender set to the
+// device wallet, which is what `onlyDeviceWallet` wants. Those three functions are
+// the only writes this surface can reach; everything else is `onlyOwner`,
+// `onlyESIMWalletAdmin`, `onlyDeviceWalletFactory` or `onlyLazyWalletRegistry` and
+// lives on `KokioAdmin.registry` or behind the lazy registry wrappers.
+//
+// updateDeviceWalletOwnerKey is the exception among the three. It is
+// `onlyDeviceWallet`, so a userOp reaches it, but calling it on its own writes a
+// key into the registry that the wallet is not actually using.
+// `deviceWallet.transferOwnership` rotates the key and updates the registry in one
+// call, so that is the only way this surface offers to move it.
+/**
+ * Take on an eSIM wallet and clear any standby flag left by a transfer.
+ *
+ * The registry only accepts the calling device wallet as the new holder, so the
+ * SDK fills that in and there is nothing to pass. The eSIM wallet's `owner()`
+ * has to already be this device wallet: accept the ownership transfer first,
+ * then bind.
+ *
+ * Reverts while a transfer is still pending on the eSIM wallet, and for any
+ * address the eSIM wallet factory did not deploy.
+ */
+export const _bindESIMWallet = async (client, eSIMWalletAddress) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: values.factoryAddresses.REGISTRY,
+                data: encodeFunctionData({
+                    abi: Registry,
+                    functionName: "bindESIMWallet",
+                    args: [eSIMWalletAddress, client.account.address]
+                })
+            }]
+    });
+};
+/**
+ * Flag an eSIM wallet as mid-transfer, or clear the flag when the move settles or
+ * is called off.
+ *
+ * Only the flag moves. The registry keeps naming this device wallet as the eSIM
+ * wallet's holder either way, so raising standby on a wallet still held here is
+ * the ordinary case rather than a contradiction.
+ */
+export const _toggleESIMWalletStandbyStatus = async (client, eSIMWalletAddress, isOnStandby) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: values.factoryAddresses.REGISTRY,
+                data: encodeFunctionData({
+                    abi: Registry,
+                    functionName: "toggleESIMWalletStandbyStatus",
+                    args: [eSIMWalletAddress, isOnStandby]
+                })
+            }]
+    });
+};
+/**
+ * True once the device has a wallet on chain. Note this is not the same question
+ * as `LazyWalletRegistry.isDeviceIdentifierReserved`, which only says whether
+ * history has been recorded for the device, and is true well before anything is
+ * deployed.
+ */
+export const _isDeviceIdentifierAlreadyUsed = async (client, deviceUniqueIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    // A `view` - read it directly instead of spending a userOp.
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isDeviceIdentifierAlreadyUsed",
+        args: [deviceUniqueIdentifier]
+    });
+};
+/**
+ * Whether the protocol is paused. While true, every ETH-moving path on the device
+ * wallets and eSIM wallets reverts, so check this before offering a purchase.
+ */
+export const _paused = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "paused",
+        args: []
+    });
+};
+/**
+ * The same pause check the wallets themselves run, which throws rather than
+ * returning false. Use `_paused` to branch on it; use this when you want the
+ * failure to carry the protocol's own revert reason.
+ */
+export const _requireNotPaused = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    await client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "requireNotPaused",
+        args: []
+    });
+};
+/**
+ * The device wallet holding an eSIM wallet, zero if it was never registered.
+ * Despite the name this returns an address, not a boolean, and it keeps naming
+ * the last holder after a release, so a non-zero answer is not proof anyone
+ * holds it now. Ask `deviceWallet.isValidESIMWallet` for that.
+ */
+export const _isESIMWalletValid = async (client, eSIMWalletAddress) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isESIMWalletValid",
+        args: [eSIMWalletAddress]
+    });
+};
+/**
+ * Whether a transfer is outstanding on an eSIM wallet. `bindESIMWallet` clears
+ * it once the new device wallet takes the eSIM wallet on.
+ *
+ * Independent of `isESIMWalletValid`, and neither implies the other. A `true`
+ * here is not a claim the wallet left the protocol, and it is normal for the
+ * association to still name the device wallet that raised the flag.
+ */
+export const _isESIMWalletOnStandby = async (client, eSIMWalletAddress) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isESIMWalletOnStandby",
+        args: [eSIMWalletAddress]
+    });
+};
+/** Whether a device wallet is registered with the protocol. */
+export const _isDeviceWalletValid = async (client, deviceWalletAddress) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isDeviceWalletValid",
+        args: [deviceWalletAddress]
+    });
+};
+/** The device wallet registered for a device identifier, zero if none. */
+export const _uniqueIdentifierToDeviceWallet = async (client, deviceUniqueIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "uniqueIdentifierToDeviceWallet",
+        args: [deviceUniqueIdentifier]
+    });
+};
+/** Whether an eSIM identifier is already held by a wallet. */
+export const _isESIMIdentifierClaimed = async (client, eSIMUniqueIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "isESIMIdentifierClaimed",
+        args: [eSIMUniqueIdentifier]
+    });
+};
+/**
+ * The one eSIM wallet holding an eSIM identifier, zero if nobody holds it. Set
+ * once and never cleared, an ownership transfer included, because the eSIM
+ * belongs to the wallet rather than to whichever device is holding it.
+ */
+export const _eSIMWalletForIdentifier = async (client, eSIMUniqueIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "eSIMWalletForIdentifier",
+        args: [eSIMUniqueIdentifier]
+    });
+};
+/** The fallback price ceiling in wei for a wallet holding no cap of its own. */
+export const _defaultDataBundlePriceCap = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "defaultDataBundlePriceCap",
+        args: []
+    });
+};
+/**
+ * Throws if a fiat user's eSIMs are already waiting on this device identifier.
+ * Worth calling before a deployment: taking a reserved identifier strands the
+ * lazy user, since the history copy, the wallet deployment and the device switch
+ * all then refuse it.
+ */
+export const _requireDeviceIdentifierNotReserved = async (client, deviceUniqueIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    await client.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "requireDeviceIdentifierNotReserved",
+        args: [deviceUniqueIdentifier]
+    });
+};

package/dist/esm/logic/utils.js

@@ -54,7 +54,8 @@ export function parseDEREncodedSignature(signature) {
     let offset = 0;
     if (signature[offset++] !== 0x30)
         throw new Error("Invalid DER sequence");
-    const length = signature[offset++];
+    // Sequence length byte. Skipped, because r and s each carry their own length.
+    offset++;
     if (signature[offset++] !== 0x02)
         throw new Error("Expected integer for r");
     const rLen = signature[offset++];

package/dist/types/abis/BeaconProxy.d.ts

@@ -1,59 +1,47 @@
 declare const BeaconProxy: readonly [{
+    readonly type: "fallback";
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "event";
+    readonly name: "BeaconUpgraded";
     readonly inputs: readonly [{
-        readonly internalType: "address";
         readonly name: "beacon";
         readonly type: "address";
-    }, {
-        readonly internalType: "bytes";
-        readonly name: "data";
-        readonly type: "bytes";
+        readonly indexed: true;
+        readonly internalType: "address";
     }];
-    readonly stateMutability: "payable";
-    readonly type: "constructor";
+    readonly anonymous: false;
 }, {
+    readonly type: "error";
+    readonly name: "AddressEmptyCode";
     readonly inputs: readonly [{
-        readonly internalType: "address";
         readonly name: "target";
         readonly type: "address";
+        readonly internalType: "address";
     }];
-    readonly name: "AddressEmptyCode";
-    readonly type: "error";
 }, {
+    readonly type: "error";
+    readonly name: "ERC1967InvalidBeacon";
     readonly inputs: readonly [{
-        readonly internalType: "address";
         readonly name: "beacon";
         readonly type: "address";
+        readonly internalType: "address";
     }];
-    readonly name: "ERC1967InvalidBeacon";
-    readonly type: "error";
 }, {
+    readonly type: "error";
+    readonly name: "ERC1967InvalidImplementation";
     readonly inputs: readonly [{
-        readonly internalType: "address";
         readonly name: "implementation";
         readonly type: "address";
+        readonly internalType: "address";
     }];
-    readonly name: "ERC1967InvalidImplementation";
-    readonly type: "error";
 }, {
-    readonly inputs: readonly [];
-    readonly name: "ERC1967NonPayable";
     readonly type: "error";
-}, {
+    readonly name: "ERC1967NonPayable";
     readonly inputs: readonly [];
-    readonly name: "FailedInnerCall";
-    readonly type: "error";
 }, {
-    readonly anonymous: false;
-    readonly inputs: readonly [{
-        readonly indexed: true;
-        readonly internalType: "address";
-        readonly name: "beacon";
-        readonly type: "address";
-    }];
-    readonly name: "BeaconUpgraded";
-    readonly type: "event";
-}, {
-    readonly stateMutability: "payable";
-    readonly type: "fallback";
+    readonly type: "error";
+    readonly name: "FailedCall";
+    readonly inputs: readonly [];
 }];
 export default BeaconProxy;