kokio-sdk 1.0.0 → 2.0.0

package/dist/types/logic/deviceWalletFactory.d.ts

@@ -1,6 +1,35 @@
 import { Address, WalletClient } from "viem";
-import { SmartAccountClient } from "@aa-sdk/core";
+import { KokioSmartAccountClient } from "../types.js";
 import { P256Key } from "../types.js";
 export declare const _createAccountWithEOA: (client: WalletClient, deviceUniqueIdentifier: string, deviceWalletOwnerKey: P256Key, salt: bigint, depositAmount: bigint) => Promise<`0x${string}`>;
-export declare const _getAddress: (client: SmartAccountClient, deviceUniqueIdentifier: string, deviceWalletOwnerKey: P256Key, salt: bigint) => Promise<Address>;
-export declare const _getCurrentDeviceWalletImplementation: (client: SmartAccountClient) => Promise<Address>;
+export declare const _getAddress: (client: KokioSmartAccountClient, deviceUniqueIdentifier: string, deviceWalletOwnerKey: P256Key, salt: bigint) => Promise<Address>;
+export declare const _getCurrentDeviceWalletImplementation: (client: KokioSmartAccountClient) => Promise<Address>;
+/**
+ * Check an identifier and owner key before deploying. Answers the zero address
+ * when both are free, or the wallet already holding one of them.
+ *
+ * Call this first. `createAccount` runs inside EntryPoint validation, where the
+ * 4337 rules bar it from reading the registry, so it cannot see that an
+ * identifier or a key is taken: it deploys a second wallet at a fresh address
+ * and the `postCreateAccount` that would register it fails afterwards.
+ *
+ * Reverts on an empty identifier or a key that is not a point on the P256 curve.
+ */
+export declare const _preCreateAccountValidation: (client: KokioSmartAccountClient, deviceUniqueIdentifier: string, deviceWalletOwnerKey: P256Key) => Promise<Address>;
+/**
+ * Whether the factory has recorded this wallet. Set by `postCreateAccount`, not
+ * by the deploy, so a wallet the app just created reads false until the backend
+ * registers it.
+ */
+export declare const _deviceWalletInfoAdded: (client: KokioSmartAccountClient, deviceWallet: Address) => Promise<boolean>;
+/**
+ * The beacon every device wallet reads its implementation from. One update moves
+ * all of them and no wallet can decline it.
+ */
+export declare const _beacon: (client: KokioSmartAccountClient) => Promise<Address>;
+/** The registry the factory writes new wallets into. */
+export declare const _registry: (client: KokioSmartAccountClient) => Promise<Address>;
+/** The EntryPoint baked into every device wallet this factory deploys. */
+export declare const _entryPoint: (client: KokioSmartAccountClient) => Promise<Address>;
+/** The contract new device wallets verify WebAuthn assertions through. */
+export declare const _verifier: (client: KokioSmartAccountClient) => Promise<Address>;

package/dist/types/logic/eSIMWallet.d.ts

@@ -1,9 +1,50 @@
 import { Address } from "viem";
 import { DataBundleDetails } from "../types.js";
-import { SmartAccountClient } from "@aa-sdk/core";
-export declare const _setESIMUniqueIdentifier: (client: SmartAccountClient, address: Address, eSIMUniqueIdentifier: string) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
-export declare const _buyDataBundle: (client: SmartAccountClient, address: Address, dataBundleDetails: DataBundleDetails) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
-export declare const _owner: (client: SmartAccountClient, address: Address) => Promise<Address>;
-export declare const _requestTransferOwnership: (client: SmartAccountClient, address: Address, newOwner: Address) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
-export declare const _acceptOwnershipTransfer: (client: SmartAccountClient, address: Address) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
-export declare const _sendETHToDeviceWallet: (client: SmartAccountClient, address: Address, amount: bigint) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
+import { KokioSmartAccountClient } from "../types.js";
+/**
+ * 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 declare const _setDataBundlePriceCap: (client: KokioSmartAccountClient, address: Address, cap: bigint) => Promise<`0x${string}`>;
+export declare const _buyDataBundle: (client: KokioSmartAccountClient, address: Address, dataBundleDetails: DataBundleDetails) => Promise<`0x${string}`>;
+export declare const _owner: (client: KokioSmartAccountClient, address: Address) => Promise<Address>;
+/**
+ * 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 declare const _dataBundlePriceCap: (client: KokioSmartAccountClient, address: Address) => Promise<bigint>;
+/**
+ * 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 declare const _deviceWallet: (client: KokioSmartAccountClient, address: Address) => Promise<Address>;
+/**
+ * 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 declare const _transactionHistory: (client: KokioSmartAccountClient, address: Address, index: bigint) => Promise<DataBundleDetails>;
+export declare const _requestTransferOwnership: (client: KokioSmartAccountClient, address: Address, newOwner: Address) => Promise<`0x${string}`>;
+export declare const _acceptOwnershipTransfer: (client: KokioSmartAccountClient, address: Address) => Promise<`0x${string}`>;
+export declare const _sendETHToDeviceWallet: (client: KokioSmartAccountClient, address: Address, amount: bigint) => Promise<`0x${string}`>;

package/dist/types/logic/eSIMWalletFactory.d.ts

@@ -1,4 +1,4 @@
 import { Address } from "viem";
-import { SmartAccountClient } from "@aa-sdk/core";
-export declare const _deployESIMWalletWithUserOp: (client: SmartAccountClient, deviceWalletAddress: Address, salt: bigint) => Promise<import("@aa-sdk/core").SendUserOperationResult<keyof import("@aa-sdk/core").EntryPointRegistryBase<unknown>>>;
-export declare const _getCurrentESIMWalletImplementation: (client: SmartAccountClient) => Promise<Address>;
+import { KokioSmartAccountClient } from "../types.js";
+export declare const _deployESIMWalletWithUserOp: (client: KokioSmartAccountClient, deviceWalletAddress: Address, salt: bigint) => Promise<`0x${string}`>;
+export declare const _getCurrentESIMWalletImplementation: (client: KokioSmartAccountClient) => Promise<Address>;

package/dist/types/logic/errors.d.ts

@@ -42,6 +42,51 @@ export declare class CounterfactualMismatchError extends KokioError {
     readonly onChain: Hex;
     constructor(offChain: Hex, onChain: Hex);
 }
+/**
+ * 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 declare class BatchSizeOutOfRangeError extends KokioError {
+    readonly requested: bigint;
+    readonly max: bigint;
+    constructor(what: string, requested: bigint, max: bigint);
+}
+/**
+ * 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 declare class DepositOnResumeError extends KokioError {
+    readonly deviceUniqueIdentifier: string;
+    readonly depositAmount: bigint;
+    constructor(deviceUniqueIdentifier: string, depositAmount: bigint);
+}
+/**
+ * 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 declare class ESIMWalletNotLazyDeployedError extends KokioError {
+    readonly eSIMIdentifier: string;
+    constructor(eSIMIdentifier: string);
+}
+/**
+ * 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 declare class MissingBatchEventError extends KokioError {
+    readonly hash: Hex;
+    constructor(eventName: string, hash: Hex);
+}
+/**
+ * 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 declare class StalledBatchError extends KokioError {
+    readonly hash: Hex;
+    readonly remaining: bigint;
+    constructor(hash: Hex, remaining: bigint);
+}
 export interface DecodedRevert {
     errorName: string;
     args: readonly unknown[];

package/dist/types/logic/registry.d.ts

@@ -0,0 +1,78 @@
+import { Address } from "viem";
+import { KokioSmartAccountClient } from "../types.js";
+/**
+ * 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 declare const _bindESIMWallet: (client: KokioSmartAccountClient, eSIMWalletAddress: Address) => Promise<`0x${string}`>;
+/**
+ * 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 declare const _toggleESIMWalletStandbyStatus: (client: KokioSmartAccountClient, eSIMWalletAddress: Address, isOnStandby: boolean) => Promise<`0x${string}`>;
+/**
+ * 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 declare const _isDeviceIdentifierAlreadyUsed: (client: KokioSmartAccountClient, deviceUniqueIdentifier: string) => Promise<boolean>;
+/**
+ * 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 declare const _paused: (client: KokioSmartAccountClient) => Promise<boolean>;
+/**
+ * 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 declare const _requireNotPaused: (client: KokioSmartAccountClient) => Promise<void>;
+/**
+ * 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 declare const _isESIMWalletValid: (client: KokioSmartAccountClient, eSIMWalletAddress: Address) => Promise<Address>;
+/**
+ * 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 declare const _isESIMWalletOnStandby: (client: KokioSmartAccountClient, eSIMWalletAddress: Address) => Promise<boolean>;
+/** Whether a device wallet is registered with the protocol. */
+export declare const _isDeviceWalletValid: (client: KokioSmartAccountClient, deviceWalletAddress: Address) => Promise<boolean>;
+/** The device wallet registered for a device identifier, zero if none. */
+export declare const _uniqueIdentifierToDeviceWallet: (client: KokioSmartAccountClient, deviceUniqueIdentifier: string) => Promise<Address>;
+/** Whether an eSIM identifier is already held by a wallet. */
+export declare const _isESIMIdentifierClaimed: (client: KokioSmartAccountClient, eSIMUniqueIdentifier: string) => Promise<boolean>;
+/**
+ * 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 declare const _eSIMWalletForIdentifier: (client: KokioSmartAccountClient, eSIMUniqueIdentifier: string) => Promise<Address>;
+/** The fallback price ceiling in wei for a wallet holding no cap of its own. */
+export declare const _defaultDataBundlePriceCap: (client: KokioSmartAccountClient) => Promise<bigint>;
+/**
+ * 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 declare const _requireDeviceIdentifierNotReserved: (client: KokioSmartAccountClient, deviceUniqueIdentifier: string) => Promise<void>;

package/dist/types/types-export.d.ts

@@ -1 +1 @@
-export type { P256Key, WebAuthnSignature, P256Credential, DataBundleDetails, SignedRequest } from './types';
+export type { P256Key, Call, WebAuthnSignature, P256Credential, DataBundleDetails, SignedRequest, KokioSmartAccount, KokioSmartAccountClient, OwnerCall, OperationOptions, ScheduledOperation, ScheduledBatchOperation } from './types';

package/dist/types/types.d.ts

@@ -1,5 +1,77 @@
-import { Hex } from "viem";
+import { Abi, Address, Chain, Hex, PublicActions, Transport } from "viem";
+import type { BundlerClient, SmartAccount } from "viem/account-abstraction";
 export type P256Key = [Hex, Hex];
+/**
+ * One call inside a user operation: target, optional ETH value, optional
+ * calldata. A single `Call` encodes to the account's `execute`, several
+ * batch atomically through `executeBatch`.
+ */
+export type Call = {
+    to: Address;
+    value?: bigint;
+    data?: Hex;
+};
+/**
+ * A call the `ProtocolAdmin` timelock makes on a contract it owns. Same shape as
+ * a viem `writeContract`, because that is what it becomes once the delay is served.
+ */
+export type OwnerCall = {
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args?: readonly unknown[];
+    /** ETH sent with the call. The timelock has to be holding it. */
+    value?: bigint;
+};
+/**
+ * Optional operation fields. Both default to zero, which makes the operation id a
+ * function of the call alone, so it can be recomputed later from the same
+ * arguments. Pass a `salt` to schedule a call the timelock has already run once.
+ */
+export type OperationOptions = {
+    salt?: Hex;
+    /** Operation that has to be done before this one can execute. */
+    predecessor?: Hex;
+};
+/**
+ * What `schedule` returns. Hand the whole object to `execute`: the timelock
+ * recomputes the id from these fields, so anything altered makes it look up an
+ * operation that was never scheduled.
+ */
+export type ScheduledOperation = {
+    /** Transaction hash of the `schedule` call, not the operation id. */
+    hash: Hex;
+    id: Hex;
+    target: Address;
+    value: bigint;
+    payload: Hex;
+    predecessor: Hex;
+    salt: Hex;
+    /** Delay requested. `getTimestamp(id)` is when it can actually run. */
+    delay: bigint;
+};
+/**
+ * What `scheduleBatch` returns. A batch hashes differently from a single call, so
+ * this stays a separate type: a one-call batch is not the same operation as the
+ * same call scheduled on its own, and only `executeBatch` can run it.
+ */
+export type ScheduledBatchOperation = {
+    hash: Hex;
+    id: Hex;
+    targets: readonly Address[];
+    values: readonly bigint[];
+    payloads: readonly Hex[];
+    predecessor: Hex;
+    salt: Hex;
+    delay: bigint;
+};
+/** The device wallet, as an ERC-4337 account on EntryPoint v0.8. */
+export type KokioSmartAccount = SmartAccount;
+/**
+ * Sends user operations and reads contracts through one client. viem's bundler
+ * client carries no public actions, so the SDK adds them.
+ */
+export type KokioSmartAccountClient = BundlerClient<Transport, Chain, SmartAccount> & PublicActions<Transport, Chain>;
 export type WebAuthnSignature = {
     authenticatorData: Hex;
     clientDataJSON: string;
@@ -26,6 +98,44 @@ export type DataBundleDetails = {
     dataBundleID: string;
     dataBundlePrice: bigint;
 };
+/** One `deployMoreESIMWalletsForLazyDevice` (or first) transaction, read back from its receipt. */
+export type LazyDeploymentBatch = {
+    hash: Hex;
+    /** Wallets this batch deployed, in the order of the device's identifier list. */
+    eSIMWallets: readonly Address[];
+    eSIMIdentifiers: readonly string[];
+    /** eSIM wallets still waiting after this batch. Zero means the device is done. */
+    remaining: bigint;
+};
+/**
+ * What a fully paginated lazy deployment did. `eSIMWallets` and `eSIMIdentifiers`
+ * cover only the batches this call ran, so a resume reports what it finished
+ * rather than the device's whole set.
+ */
+export type LazyDeployment = {
+    deviceWallet: Address;
+    eSIMWallets: readonly Address[];
+    eSIMIdentifiers: readonly string[];
+    batches: readonly LazyDeploymentBatch[];
+    /** Every eSIM wallet already existed, so nothing was sent. */
+    alreadyComplete: boolean;
+};
+/** One `setHistoryForLazyWallet` transaction, read back from its receipt. */
+export type LazyHistoryBatch = {
+    hash: Hex;
+    copied: bigint;
+    /** Entries still waiting after this batch. Zero means the copy is done. */
+    remaining: bigint;
+};
+/** What a fully paginated history copy did, for one eSIM. */
+export type LazyHistoryCopy = {
+    eSIMWallet: Address;
+    /** Entries written by this call, across every batch it ran. */
+    copied: bigint;
+    batches: readonly LazyHistoryBatch[];
+    /** The history was already fully copied, so nothing was sent. */
+    alreadyComplete: boolean;
+};
 export type SignedRequest = {
     body: string;
     stamp: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokio-sdk",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "",
   "type": "module",
   "main": "./dist/esm/config.js",
@@ -48,22 +48,20 @@
   },
   "homepage": "https://github.com/Blockchain-Powered-eSIM/kokio-sdk#readme",
   "devDependencies": {
-    "dotenv": "^16.5.0",
-    "typescript": "^5.7.3",
-    "vitest": "4.1.10"
+    "@types/node": "22.20.1",
+    "dotenv": "17.4.2",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
   },
   "dependencies": {
-    "@aa-sdk/core": "4.88.4",
-    "@noble/curves": "2.2.0",
-    "@peculiar/asn1-ecc": "2.8.0",
-    "@peculiar/asn1-schema": "2.8.0",
+    "@noble/curves": "2.3.0",
+    "@peculiar/asn1-ecc": "2.9.3",
+    "@peculiar/asn1-schema": "2.9.3",
     "@simplewebauthn/server": "13.3.2",
-    "react-native-passkey": "3.5.0",
-    "viem": "2.53.1"
+    "react-native-passkey": "3.6.1",
+    "viem": "2.55.19"
   },
   "overrides": {
-    "ws": "8.21.0",
-    "uuid": "14.0.0",
-    "js-cookie": "3.0.8"
+    "ws": "8.21.0"
   }
 }

package/dist/esm/interface/lazyWalletRegistryClass.js

@@ -1,10 +0,0 @@
-import { _isLazyWalletDeployed } from "../logic/lazyWalletRegistry.js";
-export class LazyWalletRegistrySubPackage {
-    client;
-    constructor(client) {
-        this.client = client;
-    }
-    isLazyWalletDeployed(deviceUniqueIdentifier) {
-        return _isLazyWalletDeployed(this.client, deviceUniqueIdentifier);
-    }
-}

package/dist/esm/logic/lazyWalletRegistry.js

@@ -1,19 +0,0 @@
-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);
-    // `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/types/interface/lazyWalletRegistryClass.d.ts

@@ -1,6 +0,0 @@
-import { SmartAccountClient } from "@aa-sdk/core";
-export declare class LazyWalletRegistrySubPackage {
-    client: SmartAccountClient;
-    constructor(client: SmartAccountClient);
-    isLazyWalletDeployed(deviceUniqueIdentifier: string): Promise<boolean>;
-}

package/dist/types/logic/lazyWalletRegistry.d.ts

@@ -1,2 +0,0 @@
-import { SmartAccountClient } from "@aa-sdk/core";
-export declare const _isLazyWalletDeployed: (client: SmartAccountClient, deviceUniqueIdentifier: string) => Promise<boolean>;