kokio-sdk 0.1.4 → 1.0.0

package/dist/esm/logic/eSIMWallet.js

@@ -1,10 +1,17 @@
 import { encodeFunctionData } from "viem";
-import { customErrors } from "./constants.js";
+import { MissingSmartWalletError } from "./errors.js";
 import { ESIMWallet } from "../abis/index.js";
+// Not exposed on this surface:
+//   - populateHistory is `onlyRegistry` - callable only by the registry contract.
+//   - 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) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyDeviceWallet`.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -19,56 +26,33 @@ export const _setESIMUniqueIdentifier = async (client, address, eSIMUniqueIdenti
 };
 export const _buyDataBundle = async (client, address, dataBundleDetails) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyDeviceWalletOrESIMWalletAdmin`; the owning device wallet may buy.
     return client.sendUserOperation({
         account: client.account,
         uo: {
             target: address,
             data: encodeFunctionData({
                 abi: ESIMWallet,
-                functionName: "payETHForDataBundles",
-                args: [dataBundleDetails]
-            })
-        }
-    });
-};
-export const _populateHistory = async (client, address, dataBundleDetails) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "populateHistory",
+                functionName: "buyDataBundle",
                 args: [dataBundleDetails]
             })
         }
     });
 };
+// `owner()` is a `view` - read it directly instead of spending a userOp.
 export const _owner = async (client, address) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "owner",
-                args: []
-            })
-        }
+    return client.readContract({
+        address,
+        abi: ESIMWallet,
+        functionName: "owner",
+        args: []
     });
 };
 export const _requestTransferOwnership = async (client, address, newOwner) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyDeviceWallet`; the owning device wallet requests the transfer.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -83,8 +67,8 @@ export const _requestTransferOwnership = async (client, address, newOwner) => {
 };
 export const _acceptOwnershipTransfer = async (client, address) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - the caller must be the pending `newRequestedOwner` (the new device wallet).
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -99,8 +83,8 @@ export const _acceptOwnershipTransfer = async (client, address) => {
 };
 export const _sendETHToDeviceWallet = async (client, address, amount) => {
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyDeviceWallet`.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -113,19 +97,3 @@ export const _sendETHToDeviceWallet = async (client, address, amount) => {
         }
     });
 };
-export const _transferOwnership = async (client, address, amount) => {
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: address,
-            data: encodeFunctionData({
-                abi: ESIMWallet,
-                functionName: "transferOwnership",
-                args: [amount]
-            })
-        }
-    });
-};

package/dist/esm/logic/eSIMWalletFactory.js

@@ -1,47 +1,21 @@
 import { encodeFunctionData } from "viem";
-import { _getChainSpecificConstants, customErrors } from "./constants.js";
+import { _getChainSpecificConstants } from "./constants.js";
+import { MissingSmartWalletError } from "./errors.js";
 import { ESIMWalletFactory } from "../abis/index.js";
-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 Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.ESIM_WALLET_FACTORY,
-            data: encodeFunctionData({
-                abi: ESIMWalletFactory,
-                functionName: "addRegistryAddress",
-                args: [registryContractAddress]
-            })
-        }
-    });
-};
-export const _deployESIMWalletWithEOA = async (client, deviceWalletAddress, salt) => {
-    const chainID = await client.getChainId();
-    const rpcURL = client.transport.url;
-    const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new Error(customErrors.MISSING_EOA_WALLET);
-    return client.writeContract({
-        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
-        chain: values.chain,
-        account: client.account.address,
-        abi: ESIMWalletFactory,
-        functionName: 'deployESIMWallet',
-        args: [deviceWalletAddress, salt]
-    });
-};
+// Not exposed on this surface:
+//   - addRegistryAddress is `onlyOwner` (the upgradeManager EOA); exposed on
+//     `KokioAdmin.eSIMWalletFactory` instead.
+//   - a direct EOA call to `deployESIMWallet` always reverts: the modifier is
+//     `onlyRegistryOrDeviceWalletFactoryOrDeviceWallet`, and a bare EOA is none of those.
+// `deployESIMWalletWithUserOp` works because a registered device wallet passes
+// `registry.isDeviceWalletValid(msg.sender)`, so the userOp sender satisfies the modifier.
 export const _deployESIMWalletWithUserOp = async (client, deviceWalletAddress, salt) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
+        throw new MissingSmartWalletError();
+    // UserOp - the device-wallet sender is a valid device wallet per the registry.
     return client.sendUserOperation({
         account: client.account,
         uo: {
@@ -58,18 +32,11 @@ export const _getCurrentESIMWalletImplementation = async (client) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.ESIM_WALLET_FACTORY,
-            data: encodeFunctionData({
-                abi: ESIMWalletFactory,
-                functionName: "getCurrentESIMWalletImplementation",
-                args: []
-            })
-        }
+    // `getCurrentESIMWalletImplementation` is a `view` - read it directly instead of a userOp.
+    return client.readContract({
+        address: values.factoryAddresses.ESIM_WALLET_FACTORY,
+        abi: ESIMWalletFactory,
+        functionName: "getCurrentESIMWalletImplementation",
+        args: []
     });
 };

package/dist/esm/logic/errors.js

@@ -0,0 +1,118 @@
+import { decodeErrorResult, isHex } from "viem";
+import { DeviceWallet, DeviceWalletFactory, ESIMWallet, ESIMWalletFactory, LazyWalletRegistry, P256Verifier, Registry, RegistryHelper, } from "../abis/index.js";
+/**
+ * Base class for every error the Kokio SDK throws deliberately. Consumers can
+ * `instanceof KokioError` to distinguish SDK-originated failures from viem /
+ * bundler / network errors, and switch on `code` for programmatic handling.
+ */
+export class KokioError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        // Restore the prototype chain when compiling down to ES5 targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** A required value was null, undefined, or empty. */
+export class NullOrUndefinedValueError extends KokioError {
+    constructor(message = "Null or undefined value provided") {
+        super("NULL_OR_UNDEFINED_VALUE", message);
+    }
+}
+/** The client has no smart-wallet (ERC-4337) account associated. */
+export class MissingSmartWalletError extends KokioError {
+    constructor(message = "Client does not have a smart wallet account associated") {
+        super("MISSING_SMART_WALLET", message);
+    }
+}
+/** The client has no EOA account associated. */
+export class MissingEOAWalletError extends KokioError {
+    constructor(message = "Client does not have an EOA wallet associated") {
+        super("MISSING_EOA_WALLET", message);
+    }
+}
+/** No client/signer instance was supplied where one was required. */
+export class InvalidClientError extends KokioError {
+    constructor(message = "Invalid Signer or Provider instance") {
+        super("INVALID_CLIENT", message);
+    }
+}
+/** The requested chain id is not known to the SDK at all. */
+export class UnsupportedChainError extends KokioError {
+    constructor(chainID) {
+        super("UNSUPPORTED_CHAIN", `Unsupported chain id ${chainID}. Kokio SDK has no configuration for this chain.`);
+    }
+}
+/** The chain is known but its factory address book is still '0x' placeholders. */
+export class UnconfiguredChainError extends KokioError {
+    constructor(chainID) {
+        super("UNCONFIGURED_CHAIN", `Chain id ${chainID} is not yet configured (factory addresses are '0x' placeholders). ` +
+            `Deploy the contracts and populate its address book before using this chain.`);
+    }
+}
+/**
+ * The off-chain counterfactual address diverged from the factory's on-chain
+ * `getCounterFactualAddress` view - a signal that the pinned BeaconProxy
+ * bytecode or CREATE2 encoding has drifted from the deployed contracts.
+ */
+export class CounterfactualMismatchError extends KokioError {
+    offChain;
+    onChain;
+    constructor(offChain, onChain) {
+        super("COUNTERFACTUAL_MISMATCH", `Counterfactual address mismatch: SDK computed ${offChain} but the factory ` +
+            `returned ${onChain}. The pinned BeaconProxy bytecode or CREATE2 encoding ` +
+            `is out of sync with the deployed contracts.`);
+        this.offChain = offChain;
+        this.onChain = onChain;
+    }
+}
+// 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.
+const REVERTABLE_ABIS = [
+    DeviceWallet,
+    DeviceWalletFactory,
+    ESIMWallet,
+    ESIMWalletFactory,
+    LazyWalletRegistry,
+    P256Verifier,
+    Registry,
+    RegistryHelper,
+];
+/**
+ * Best-effort decode of raw revert data (the ABI-encoded `Error(string)`,
+ * `Panic(uint256)`, or a contract custom error) against the known Kokio ABIs.
+ * Returns `null` when the selector matches none of them.
+ */
+export const decodeContractRevert = (data) => {
+    if (!isHex(data) || data.length < 10)
+        return null;
+    for (const abi of REVERTABLE_ABIS) {
+        try {
+            const decoded = decodeErrorResult({ abi, data });
+            return { errorName: decoded.errorName, args: (decoded.args ?? []) };
+        }
+        catch {
+            // Selector not present in this ABI - try the next one.
+        }
+    }
+    return null;
+};
+/**
+ * A decoded on-chain revert. Carries the raw revert data plus, when the
+ * selector was recognised, the decoded custom-error name and args.
+ */
+export class ContractRevertError extends KokioError {
+    data;
+    decoded;
+    constructor(data) {
+        const decoded = decodeContractRevert(data);
+        super("CONTRACT_REVERT", decoded
+            ? `Contract reverted with ${decoded.errorName}(${decoded.args.map(String).join(", ")})`
+            : `Contract reverted with unrecognised data ${data}`);
+        this.data = data;
+        this.decoded = decoded;
+    }
+}

package/dist/esm/logic/lazyWalletRegistry.js

@@ -1,79 +1,19 @@
-import { encodeFunctionData } from "viem";
-import { _getChainSpecificConstants, customErrors } from "./constants.js";
+import { _getChainSpecificConstants } from "./constants.js";
 import { LazyWalletRegistry } from "../abis/index.js";
+// batchPopulateHistory, deployLazyWalletAndSetESIMIdentifier and
+// switchESIMIdentifierToNewDeviceIdentifier are all `onlyESIMWalletAdmin`, so a
+// device-wallet userOp (msg.sender = the device wallet account) always reverts. They
+// are exposed on `KokioAdmin.lazyWalletRegistry` instead. Only the `view` lookup
+// belongs on this surface, exposed as a direct read.
 export const _isLazyWalletDeployed = async (client, deviceUniqueIdentifier) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    if (!client.account)
-        throw new Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.LAZY_WALLET_REGISTRY,
-            data: encodeFunctionData({
-                abi: LazyWalletRegistry,
-                functionName: "isLazyWalletDeployed",
-                args: [deviceUniqueIdentifier]
-            })
-        }
-    });
-};
-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 Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.LAZY_WALLET_REGISTRY,
-            data: encodeFunctionData({
-                abi: LazyWalletRegistry,
-                functionName: "batchPopulateHistory",
-                args: [deviceUniqueIdentifiers, eSIMUniqueIdentifiers, dataBundleDetails]
-            })
-        }
-    });
-};
-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 Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.LAZY_WALLET_REGISTRY,
-            data: encodeFunctionData({
-                abi: LazyWalletRegistry,
-                functionName: "deployLazyWalletAndSetESIMIdentifier",
-                args: [deviceOwnerPublicKey, deviceUniqueIdentifier, salt, depositAmount]
-            })
-        }
-    });
-};
-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 Error(customErrors.MISSING_SMART_WALLET);
-    // UserOp
-    return client.sendUserOperation({
-        account: client.account,
-        uo: {
-            target: values.factoryAddresses.LAZY_WALLET_REGISTRY,
-            data: encodeFunctionData({
-                abi: LazyWalletRegistry,
-                functionName: "switchESIMIdentifierToNewDeviceIdentifier",
-                args: [eSIMIdentifier, oldDeviceIdentifier, newDeviceIdentifier]
-            })
-        }
+    // `isLazyWalletDeployed` is a `view` - read it directly instead of spending a userOp.
+    return client.readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "isLazyWalletDeployed",
+        args: [deviceUniqueIdentifier]
     });
 };

package/dist/esm/logic/utils.js

@@ -1,16 +1,16 @@
 import { isHex, toHex } from "viem";
 import { AsnParser } from "@peculiar/asn1-schema";
 import { ECDSASigValue } from "@peculiar/asn1-ecc";
-import { customErrors } from "./constants.js";
+import { NullOrUndefinedValueError } from "./errors.js";
 export const _add0x = (data) => {
     if (!data) {
-        throw customErrors.NULL_OR_UNDEFINED_VALUE;
+        throw new NullOrUndefinedValueError();
     }
     return (data.indexOf('0x') !== -1) ? isHex(data) ? data : `0x${data}` : `0x${data}`;
 };
 export const _remove0x = (data) => {
     if (!data) {
-        throw customErrors.NULL_OR_UNDEFINED_VALUE;
+        throw new NullOrUndefinedValueError();
     }
     return (data.indexOf('0x') !== -1) ? data.slice(2) : data;
 };

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

@@ -1,3 +1,59 @@
-import type { Abi } from "viem";
-declare const BeaconProxy: Abi;
+declare const BeaconProxy: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "beacon";
+        readonly type: "address";
+    }, {
+        readonly internalType: "bytes";
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly stateMutability: "payable";
+    readonly type: "constructor";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "target";
+        readonly type: "address";
+    }];
+    readonly name: "AddressEmptyCode";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "beacon";
+        readonly type: "address";
+    }];
+    readonly name: "ERC1967InvalidBeacon";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "implementation";
+        readonly type: "address";
+    }];
+    readonly name: "ERC1967InvalidImplementation";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "ERC1967NonPayable";
+    readonly type: "error";
+}, {
+    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";
+}];
 export default BeaconProxy;