kokio-sdk 3.1.0 → 3.2.0

package/dist/esm/admin/config-admin.js

@@ -7,6 +7,7 @@ import { AdminProtocolAdminSubPackage } from "./interface/protocolAdminClass.js"
 import { AdminDeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
 import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { AdminPaymentAdapterSubPackage } from "./interface/paymentAdapterClass.js";
+import { AdminCallsSubPackage } from "./interface/callsClass.js";
 // Re-export the typed error surface so backend consumers can `instanceof
 // KokioError` (or a subclass) and decode reverts without reaching into internal
 // module paths - mirroring `config.ts`.
@@ -42,6 +43,8 @@ export class KokioAdmin {
     lazyWalletRegistry;
     protocolAdmin;
     paymentAdapter;
+    /** Calls for the app to sign as a user operation, built here so the backend holds the purchase logic. */
+    calls;
     // Instance-scoped surfaces - undefined until their address is known.
     deviceWallet;
     eSIMWallet;
@@ -56,6 +59,7 @@ export class KokioAdmin {
         this.lazyWalletRegistry = new AdminLazyWalletRegistrySubPackage(walletClient);
         this.protocolAdmin = new AdminProtocolAdminSubPackage(walletClient);
         this.paymentAdapter = new AdminPaymentAdapterSubPackage(walletClient);
+        this.calls = new AdminCallsSubPackage(walletClient);
         this.deviceWallet = deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, deviceWalletAddress) : undefined;
         this.eSIMWallet = eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, eSIMWalletAddress) : undefined;
     }
@@ -106,6 +110,7 @@ export class KokioAdmin {
         this.lazyWalletRegistry = new AdminLazyWalletRegistrySubPackage(walletClient);
         this.protocolAdmin = new AdminProtocolAdminSubPackage(walletClient);
         this.paymentAdapter = new AdminPaymentAdapterSubPackage(walletClient);
+        this.calls = new AdminCallsSubPackage(walletClient);
         this.deviceWallet = this.deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, this.deviceWalletAddress) : undefined;
         this.eSIMWallet = this.eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, this.eSIMWalletAddress) : undefined;
         return this;

package/dist/esm/admin/interface/callsClass.js

@@ -0,0 +1,30 @@
+import { publicActions } from "viem";
+import { _acceptAndBindESIMWalletCalls, _buyDataBundleWithTransferCalls } from "../../logic/calls/eSIMWallet.calls.js";
+/**
+ * Builds the calls a user's device wallet signs as one user operation. Nothing
+ * is signed or sent here: hand the result to the app, which passes it to
+ * `deviceWallet.sendUserOperation`. Addresses are passed per call, since one
+ * backend builds calls for many users.
+ */
+export class AdminCallsSubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    /**
+     * The calls `kokio.eSIMWallet.buyDataBundleWithTransfer` sends: a token
+     * transfer from the device wallet for whatever the eSIM wallet is short of,
+     * then the purchase. The purchase emits `DataBundleBoughtWithToken` as usual.
+     */
+    buyDataBundleWithTransfer(eSIMWalletAddress, dataBundleDetails, asset, maxAmountIn, paymentReference) {
+        return _buyDataBundleWithTransferCalls(this.walletClient.extend(publicActions), eSIMWalletAddress, dataBundleDetails, asset, maxAmountIn, paymentReference);
+    }
+    /**
+     * The calls `kokio.eSIMWallet.acceptAndBindESIMWallet` sends, for the device
+     * wallet named in `requestTransferOwnership` to sign. Build them once the
+     * `OwnershipTransferRequested` event names that device wallet as `_newOwner`.
+     */
+    acceptAndBindESIMWallet(eSIMWalletAddress, newDeviceWalletAddress, options = {}) {
+        return _acceptAndBindESIMWalletCalls(eSIMWalletAddress, newDeviceWalletAddress, options.grantAccessToFunds ?? false);
+    }
+}

package/dist/esm/interface/eSIMWalletClass.js

@@ -1,4 +1,4 @@
-import { _acceptOwnershipTransfer, _buyDataBundleWithToken, _buyDataBundleWithTransfer, _priceCapUSDCents, _deviceWallet, _owner, _requestTransferOwnership, _sendETHToDeviceWallet, _sendTokenToDeviceWallet, _setPriceCapUSDCents, _transactionHistory } from "../logic/eSIMWallet.js";
+import { _acceptAndBindESIMWallet, _acceptOwnershipTransfer, _buyDataBundleWithToken, _buyDataBundleWithTransfer, _priceCapUSDCents, _deviceWallet, _owner, _requestTransferOwnership, _sendETHToDeviceWallet, _sendTokenToDeviceWallet, _setPriceCapUSDCents, _transactionHistory } from "../logic/eSIMWallet.js";
 export class ESIMWalletSubPackage {
     client;
     address;
@@ -9,6 +9,14 @@ export class ESIMWalletSubPackage {
     acceptOwnershipTransfer() {
         return _acceptOwnershipTransfer(this.client, this.address);
     }
+    /**
+     * Accept this eSIM wallet's transfer and bind it to the signing device
+     * wallet in one user operation, optionally granting it access to that
+     * wallet's tokens too.
+     */
+    acceptAndBindESIMWallet(options = {}) {
+        return _acceptAndBindESIMWallet(this.client, this.address, options.grantAccessToFunds ?? false);
+    }
     buyDataBundleWithToken(dataBundleDetails, asset, maxAmountIn, paymentReference) {
         return _buyDataBundleWithToken(this.client, this.address, dataBundleDetails, asset, maxAmountIn, paymentReference);
     }

package/dist/esm/logic/calls/eSIMWallet.calls.js

@@ -0,0 +1,72 @@
+import { encodeFunctionData, erc20Abi } from "viem";
+import { DeviceWallet, ESIMWallet, PaymentAdapter, Registry } from "../../abis/index.js";
+import { _chainId, _getChainSpecificConstants } from "../constants.js";
+/**
+ * The calls for buying a data bundle with tokens the device wallet sends over
+ * in the same user operation, so the eSIM wallet needs no access to the device
+ * wallet's funds.
+ *
+ * Only the shortfall is sent: the quote for the bundle minus what the eSIM
+ * wallet already holds of `asset`, worked out when this runs. If that balance
+ * or the quote changes before the operation lands, it reverts, so build the
+ * calls again rather than resending old ones.
+ */
+export const _buyDataBundleWithTransferCalls = async (client, eSIMWalletAddress, dataBundleDetails, asset, maxAmountIn, paymentReference) => {
+    const chainID = await _chainId(client);
+    const values = _getChainSpecificConstants(chainID, client.transport.url);
+    // The eSIM wallet pays through whichever adapter the registry names, so read it there.
+    const adapter = await client.readContract({
+        address: values.factoryAddresses.REGISTRY, abi: Registry, functionName: "paymentAdapter"
+    });
+    const [{ token }, amountIn] = await Promise.all([
+        client.readContract({
+            address: adapter, abi: PaymentAdapter, functionName: "resolveAsset", args: [asset]
+        }),
+        client.readContract({
+            address: adapter, abi: PaymentAdapter, functionName: "quote", args: [asset, dataBundleDetails.priceUSDCents]
+        }),
+    ]);
+    const held = await client.readContract({
+        address: token, abi: erc20Abi, functionName: "balanceOf", args: [eSIMWalletAddress]
+    });
+    const buy = {
+        to: eSIMWalletAddress,
+        data: encodeFunctionData({
+            abi: ESIMWallet,
+            functionName: "buyDataBundleWithToken",
+            args: [dataBundleDetails, asset, maxAmountIn, paymentReference]
+        })
+    };
+    if (held >= amountIn)
+        return [buy];
+    return [
+        {
+            to: token,
+            data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [eSIMWalletAddress, amountIn - held] })
+        },
+        buy
+    ];
+};
+/**
+ * The calls for the new device wallet to take over an eSIM wallet another
+ * device wallet asked to hand it: accept the transfer, then bind it, which also
+ * tells the registry and clears the standby flag.
+ *
+ * Accepting first is what lets the bind through: it makes this device wallet
+ * the owner and clears the pending transfer. Fund access cannot be granted at
+ * bind time, so `grantAccessToFunds` adds a `toggleAccessToFunds` after it.
+ */
+export const _acceptAndBindESIMWalletCalls = (eSIMWalletAddress, deviceWalletAddress, grantAccessToFunds) => {
+    const self = (functionName, hasAccessToFunds) => ({
+        to: deviceWalletAddress,
+        data: encodeFunctionData({ abi: DeviceWallet, functionName, args: [eSIMWalletAddress, hasAccessToFunds] })
+    });
+    return [
+        {
+            to: eSIMWalletAddress,
+            data: encodeFunctionData({ abi: ESIMWallet, functionName: "acceptOwnershipTransfer", args: [] })
+        },
+        self("addESIMWallet", false),
+        ...(grantAccessToFunds ? [self("toggleAccessToFunds", true)] : [])
+    ];
+};

package/dist/esm/logic/eSIMWallet.js

@@ -1,8 +1,8 @@
-import { encodeFunctionData, erc20Abi, maxUint256 } from "viem";
+import { encodeFunctionData, maxUint256 } from "viem";
 import { MissingSmartWalletError } from "./errors.js";
-import { ESIMWallet, PaymentAdapter, Registry } from "../abis/index.js";
-import { _chainId, _getChainSpecificConstants } from "./constants.js";
+import { ESIMWallet } from "../abis/index.js";
 import { _defaultPriceCapUSDCents } from "./registry.js";
+import { _acceptAndBindESIMWalletCalls, _buyDataBundleWithTransferCalls } from "./calls/eSIMWallet.calls.js";
 // Not exposed on this surface:
 //   - populateHistory and setESIMUniqueIdentifier are `onlyRegistry` - callable
 //     only by the registry contract. Naming an eSIM goes through
@@ -68,45 +68,14 @@ export const _buyDataBundleWithToken = async (client, address, dataBundleDetails
  *
  * Only the shortfall is sent: the quote for the bundle minus what this eSIM
  * wallet already holds of `asset`. Arguments are as for `buyDataBundleWithToken`.
+ * The backend builds the same calls with `admin.calls.buyDataBundleWithTransfer`.
  */
 export const _buyDataBundleWithTransfer = async (client, address, dataBundleDetails, asset, maxAmountIn, paymentReference) => {
-    const chainID = await _chainId(client);
-    const rpcURL = client.transport.url;
-    const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingSmartWalletError();
-    // The eSIM wallet pays through whichever adapter the registry names, so read it there.
-    const adapter = await client.readContract({
-        address: values.factoryAddresses.REGISTRY, abi: Registry, functionName: "paymentAdapter"
-    });
-    const [{ token }, amountIn] = await Promise.all([
-        client.readContract({
-            address: adapter, abi: PaymentAdapter, functionName: "resolveAsset", args: [asset]
-        }),
-        client.readContract({
-            address: adapter, abi: PaymentAdapter, functionName: "quote", args: [asset, dataBundleDetails.priceUSDCents]
-        }),
-    ]);
-    const held = await client.readContract({
-        address: token, abi: erc20Abi, functionName: "balanceOf", args: [address]
-    });
-    const buy = {
-        to: address,
-        data: encodeFunctionData({
-            abi: ESIMWallet,
-            functionName: "buyDataBundleWithToken",
-            args: [dataBundleDetails, asset, maxAmountIn, paymentReference]
-        })
-    };
     return client.sendUserOperation({
         account: client.account,
-        calls: held >= amountIn ? [buy] : [
-            {
-                to: token,
-                data: encodeFunctionData({ abi: erc20Abi, functionName: "transfer", args: [address, amountIn - held] })
-            },
-            buy
-        ]
+        calls: await _buyDataBundleWithTransferCalls(client, address, dataBundleDetails, asset, maxAmountIn, paymentReference)
     });
 };
 /**
@@ -228,6 +197,21 @@ export const _acceptOwnershipTransfer = async (client, address) => {
             }]
     });
 };
+/**
+ * Accept an eSIM wallet another device wallet asked to hand over, and bind it,
+ * in one user operation. `grantAccessToFunds` also lets it pull this device
+ * wallet's tokens. The backend builds the same calls with
+ * `admin.calls.acceptAndBindESIMWallet`.
+ */
+export const _acceptAndBindESIMWallet = async (client, address, grantAccessToFunds) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    // UserOp - the sender is the pending `newRequestedOwner`, and then the owner the bind needs.
+    return client.sendUserOperation({
+        account: client.account,
+        calls: _acceptAndBindESIMWalletCalls(address, client.account.address, grantAccessToFunds)
+    });
+};
 export const _sendETHToDeviceWallet = async (client, address, amount) => {
     if (!client.account)
         throw new MissingSmartWalletError();

package/dist/types/admin/config-admin.d.ts

@@ -8,6 +8,7 @@ import { AdminProtocolAdminSubPackage } from "./interface/protocolAdminClass.js"
 import { AdminDeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
 import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { AdminPaymentAdapterSubPackage } from "./interface/paymentAdapterClass.js";
+import { AdminCallsSubPackage } from "./interface/callsClass.js";
 export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, StalledBatchError, ContractRevertError, decodeContractRevert, } from "../logic/errors.js";
 export type { DecodedRevert } from "../logic/errors.js";
 export { OperationState } from "../logic/admin/reads/protocolAdmin.reads.js";
@@ -38,6 +39,8 @@ export declare class KokioAdmin {
     lazyWalletRegistry: AdminLazyWalletRegistrySubPackage;
     protocolAdmin: AdminProtocolAdminSubPackage;
     paymentAdapter: AdminPaymentAdapterSubPackage;
+    /** Calls for the app to sign as a user operation, built here so the backend holds the purchase logic. */
+    calls: AdminCallsSubPackage;
     deviceWallet?: AdminDeviceWalletSubPackage;
     eSIMWallet?: AdminESIMWalletSubPackage;
     constructor(walletClient: WalletClient, deviceWalletAddress?: Address, eSIMWalletAddress?: Address);

package/dist/types/admin/interface/callsClass.d.ts

@@ -0,0 +1,26 @@
+import { Address, Hex, WalletClient } from "viem";
+import { DataBundleDetails } from "../../types.js";
+/**
+ * Builds the calls a user's device wallet signs as one user operation. Nothing
+ * is signed or sent here: hand the result to the app, which passes it to
+ * `deviceWallet.sendUserOperation`. Addresses are passed per call, since one
+ * backend builds calls for many users.
+ */
+export declare class AdminCallsSubPackage {
+    walletClient: WalletClient;
+    constructor(walletClient: WalletClient);
+    /**
+     * The calls `kokio.eSIMWallet.buyDataBundleWithTransfer` sends: a token
+     * transfer from the device wallet for whatever the eSIM wallet is short of,
+     * then the purchase. The purchase emits `DataBundleBoughtWithToken` as usual.
+     */
+    buyDataBundleWithTransfer(eSIMWalletAddress: Address, dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex): Promise<import("../../types.js").Call[]>;
+    /**
+     * The calls `kokio.eSIMWallet.acceptAndBindESIMWallet` sends, for the device
+     * wallet named in `requestTransferOwnership` to sign. Build them once the
+     * `OwnershipTransferRequested` event names that device wallet as `_newOwner`.
+     */
+    acceptAndBindESIMWallet(eSIMWalletAddress: Address, newDeviceWalletAddress: Address, options?: {
+        grantAccessToFunds?: boolean;
+    }): import("../../types.js").Call[];
+}

package/dist/types/interface/eSIMWalletClass.d.ts

@@ -6,6 +6,14 @@ export declare class ESIMWalletSubPackage {
     address: `0x${string}`;
     constructor(client: KokioSmartAccountClient, address: Address);
     acceptOwnershipTransfer(): Promise<`0x${string}`>;
+    /**
+     * Accept this eSIM wallet's transfer and bind it to the signing device
+     * wallet in one user operation, optionally granting it access to that
+     * wallet's tokens too.
+     */
+    acceptAndBindESIMWallet(options?: {
+        grantAccessToFunds?: boolean;
+    }): Promise<`0x${string}`>;
     buyDataBundleWithToken(dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex): Promise<`0x${string}`>;
     /**
      * Same purchase as `buyDataBundleWithToken`, with the device wallet sending

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

@@ -0,0 +1,25 @@
+import { Address, Client, Hex, PublicActions } from "viem";
+import { Call, DataBundleDetails } from "../../types.js";
+/** Any client that can read contracts: the mobile smart account client, or a wallet client extended with `publicActions`. */
+export type CallBuilderClient = Pick<PublicActions, "readContract" | "getChainId"> & Pick<Client, "transport">;
+/**
+ * The calls for buying a data bundle with tokens the device wallet sends over
+ * in the same user operation, so the eSIM wallet needs no access to the device
+ * wallet's funds.
+ *
+ * Only the shortfall is sent: the quote for the bundle minus what the eSIM
+ * wallet already holds of `asset`, worked out when this runs. If that balance
+ * or the quote changes before the operation lands, it reverts, so build the
+ * calls again rather than resending old ones.
+ */
+export declare const _buyDataBundleWithTransferCalls: (client: CallBuilderClient, eSIMWalletAddress: Address, dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex) => Promise<Call[]>;
+/**
+ * The calls for the new device wallet to take over an eSIM wallet another
+ * device wallet asked to hand it: accept the transfer, then bind it, which also
+ * tells the registry and clears the standby flag.
+ *
+ * Accepting first is what lets the bind through: it makes this device wallet
+ * the owner and clears the pending transfer. Fund access cannot be granted at
+ * bind time, so `grantAccessToFunds` adds a `toggleAccessToFunds` after it.
+ */
+export declare const _acceptAndBindESIMWalletCalls: (eSIMWalletAddress: Address, deviceWalletAddress: Address, grantAccessToFunds: boolean) => Call[];

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

@@ -27,6 +27,7 @@ export declare const _buyDataBundleWithToken: (client: KokioSmartAccountClient,
  *
  * Only the shortfall is sent: the quote for the bundle minus what this eSIM
  * wallet already holds of `asset`. Arguments are as for `buyDataBundleWithToken`.
+ * The backend builds the same calls with `admin.calls.buyDataBundleWithTransfer`.
  */
 export declare const _buyDataBundleWithTransfer: (client: KokioSmartAccountClient, address: Address, dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex) => Promise<`0x${string}`>;
 /**
@@ -69,4 +70,11 @@ export declare const _deviceWallet: (client: KokioSmartAccountClient, address: A
 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}`>;
+/**
+ * Accept an eSIM wallet another device wallet asked to hand over, and bind it,
+ * in one user operation. `grantAccessToFunds` also lets it pull this device
+ * wallet's tokens. The backend builds the same calls with
+ * `admin.calls.acceptAndBindESIMWallet`.
+ */
+export declare const _acceptAndBindESIMWallet: (client: KokioSmartAccountClient, address: Address, grantAccessToFunds: boolean) => Promise<`0x${string}`>;
 export declare const _sendETHToDeviceWallet: (client: KokioSmartAccountClient, address: Address, amount: bigint) => Promise<`0x${string}`>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kokio-sdk",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "",
   "type": "module",
   "main": "./dist/esm/config.js",