kokio-sdk 2.0.0 → 3.0.0

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

@@ -1,4 +1,4 @@
-import { Address } from "viem";
+import { Address, Hex } from "viem";
 import { DataBundleDetails } from "../types";
 import { KokioSmartAccountClient } from "../types.js";
 export declare class ESIMWalletSubPackage {
@@ -6,12 +6,13 @@ export declare class ESIMWalletSubPackage {
     address: `0x${string}`;
     constructor(client: KokioSmartAccountClient, address: Address);
     acceptOwnershipTransfer(): Promise<`0x${string}`>;
-    buyDataBundle(dataBundleDetails: DataBundleDetails): Promise<`0x${string}`>;
-    dataBundlePriceCap(): Promise<bigint>;
+    buyDataBundleWithToken(dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex): Promise<`0x${string}`>;
+    priceCapUSDCents(): Promise<bigint>;
     deviceWallet(): Promise<`0x${string}`>;
     owner(): Promise<`0x${string}`>;
     requestTransferOwnership(newOwner: Address): Promise<`0x${string}`>;
     sendETHToDeviceWallet(amount: bigint): Promise<`0x${string}`>;
-    setDataBundlePriceCap(cap: bigint): Promise<`0x${string}`>;
+    sendTokenToDeviceWallet(token: Address, amount: bigint): Promise<`0x${string}`>;
+    setPriceCapUSDCents(cap: bigint): Promise<`0x${string}`>;
     transactionHistory(index: bigint): Promise<DataBundleDetails>;
 }

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

@@ -0,0 +1,13 @@
+import { Hex } from "viem";
+import { KokioSmartAccountClient } from "../types.js";
+export declare class PaymentAdapterSubPackage {
+    client: KokioSmartAccountClient;
+    constructor(client: KokioSmartAccountClient);
+    registry(): Promise<`0x${string}`>;
+    settlementToken(): Promise<`0x${string}`>;
+    assets(symbol: Hex): Promise<import("../types.js").Asset>;
+    resolveAsset(symbol: Hex): Promise<import("../types.js").Asset>;
+    quote(symbol: Hex, priceUSDCents: bigint): Promise<bigint>;
+    usedReferences(paymentReference: Hex): Promise<boolean>;
+    upgradeManager(): Promise<`0x${string}`>;
+}

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

@@ -1,4 +1,4 @@
-import { Address } from "viem";
+import { Address, Hex } from "viem";
 import { KokioSmartAccountClient } from "../types.js";
 export declare class RegistrySubPackage {
     client: KokioSmartAccountClient;
@@ -14,6 +14,9 @@ export declare class RegistrySubPackage {
     uniqueIdentifierToDeviceWallet(deviceUniqueIdentifier: string): Promise<`0x${string}`>;
     isESIMIdentifierClaimed(eSIMUniqueIdentifier: string): Promise<boolean>;
     eSIMWalletForIdentifier(eSIMUniqueIdentifier: string): Promise<`0x${string}`>;
-    defaultDataBundlePriceCap(): Promise<bigint>;
+    defaultPriceCapUSDCents(): Promise<bigint>;
+    paymentAdapter(): Promise<`0x${string}`>;
+    usedPaymentReferences(scopedReference: Hex): Promise<boolean>;
+    requireLazyHistoryCopied(eSIMWallet: Address): Promise<void>;
     requireDeviceIdentifierNotReserved(deviceUniqueIdentifier: string): Promise<void>;
 }

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

@@ -1,9 +1,12 @@
-import { Address, WalletClient } from "viem";
+import { Address, Hex, WalletClient } from "viem";
 import { DataBundleDetails } from "../../types.js";
 /**
- * Buy a data bundle for an eSIM wallet. `onlyDeviceWalletOrESIMWalletAdmin`,
- * `payable`. `value` is optional: the contract pulls any shortfall from the
- * device wallet's balance, so an admin can pass `0n` when the wallet is funded,
- * or forward `dataBundlePrice` to pay directly.
+ * Buy a data bundle in `asset`, an ERC-20 the payment adapter accepts.
+ * `onlyDeviceWalletOrESIMWalletAdmin`.
+ *
+ * `maxAmountIn` is the most of `asset` the buyer will spend, in its smallest
+ * unit - read it from `paymentAdapter.quote(asset, dataBundleDetails.priceUSDCents)`
+ * first. `paymentReference` ties this purchase to its offchain order and is
+ * spendable once per eSIM wallet.
  */
-export declare const _buyDataBundle: (client: WalletClient, eSIMWalletAddress: Address, dataBundleDetails: DataBundleDetails, value?: bigint) => Promise<`0x${string}`>;
+export declare const _buyDataBundleWithToken: (client: WalletClient, eSIMWalletAddress: Address, dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex) => Promise<`0x${string}`>;

package/dist/types/logic/admin/paymentAdapter.eoa.d.ts

@@ -0,0 +1,28 @@
+import { Address, Hex, WalletClient } from "viem";
+import type { Asset, OwnerCall } from "../../types.js";
+/** Add a currency the adapter has never seen. Reverts if `_symbol` is already registered. Owner only. */
+export declare const _registerAsset: (client: WalletClient, symbol: Hex, asset: Asset) => Promise<`0x${string}`>;
+/** Change a currency already in the table (its decimals, token, or allowed flag). Owner only. */
+export declare const _updateAsset: (client: WalletClient, symbol: Hex, asset: Asset) => Promise<`0x${string}`>;
+/** Add or change a currency, scheduled through the timelock. Pass the result to `schedule`. */
+export declare const _registerAssetCall: (client: WalletClient, symbol: Hex, asset: Asset) => Promise<OwnerCall>;
+/** Change a currency already in the table, scheduled through the timelock. Pass the result to `schedule`. */
+export declare const _updateAssetCall: (client: WalletClient, symbol: Hex, asset: Asset) => Promise<OwnerCall>;
+/**
+ * Offer ownership to a new address. Pass the result to `schedule`.
+ *
+ * Ownable2Step, so the offer changes nothing until the named address calls
+ * `acceptOwnership`.
+ */
+export declare const _transferOwnershipCall: (client: WalletClient, newOwner: Address) => Promise<OwnerCall>;
+/** Point the adapter's proxy at a new implementation. Builds `upgradeToAndCall`. Pass the result to `schedule`. */
+export declare const _upgradeCall: (client: WalletClient, newImplementation: Address, data?: Hex) => Promise<OwnerCall>;
+/**
+ * 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 declare const _acceptOwnership: (client: WalletClient) => Promise<`0x${string}`>;

package/dist/types/logic/admin/protocolAdmin.eoa.d.ts

@@ -130,14 +130,24 @@ export declare const _disableAndNominateCall: (client: WalletClient, target: Add
  */
 export declare const _unpauseCall: (client: WalletClient, target?: Address) => Promise<OwnerCall>;
 /**
- * Set the fallback data bundle price ceiling. Pass the result to `schedule`.
+ * Set the fallback price ceiling, in USD cents. Pass the result to `schedule`.
  *
  * Zero reverts on execution, not on scheduling, so a zero here costs the whole
  * delay before it fails.
  *
  * `target` defaults to the registry.
  */
-export declare const _setDefaultDataBundlePriceCapCall: (client: WalletClient, cap: bigint, target?: Address) => Promise<OwnerCall>;
+export declare const _setDefaultPriceCapUSDCentsCall: (client: WalletClient, cap: bigint, target?: Address) => Promise<OwnerCall>;
+/**
+ * Point the registry at a new payment adapter. Pass the result to `schedule`.
+ *
+ * Owner only, deliberately not the admin: the adapter holds the spent payment
+ * references, so an admin that could swap it would get an empty set back and
+ * could record every purchase a second time.
+ *
+ * `target` defaults to the registry.
+ */
+export declare const _setPaymentAdapterCall: (client: WalletClient, paymentAdapter: Address, target?: Address) => Promise<OwnerCall>;
 /**
  * Suspend a contract's admin key on the owner's route. Pass the result to
  * `schedule`.

package/dist/types/logic/admin/reads/deviceWallet.reads.d.ts

@@ -5,7 +5,7 @@ export declare const _deviceUniqueIdentifier: (client: WalletClient, deviceWalle
 /** Whether an eSIM wallet is a valid child of this device wallet. */
 export declare const _isValidESIMWallet: (client: WalletClient, deviceWalletAddress: Address, eSIMWallet: Address) => Promise<boolean>;
 /** Whether an eSIM wallet is allowed to pull ETH from this device wallet. */
-export declare const _canPullETH: (client: WalletClient, deviceWalletAddress: Address, eSIMWallet: Address) => Promise<boolean>;
+export declare const _canPullFunds: (client: WalletClient, deviceWalletAddress: Address, eSIMWallet: Address) => Promise<boolean>;
 /** The vault address this device wallet pays eSIM purchases to. */
 export declare const _getVaultAddress: (client: WalletClient, deviceWalletAddress: Address) => Promise<Address>;
 /**

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

@@ -8,9 +8,9 @@ export declare const _eSIMUniqueIdentifier: (client: WalletClient, eSIMWalletAdd
  * This wallet's own price ceiling in wei. Zero means it follows the registry's
  * `defaultDataBundlePriceCap` instead, which is the state a fresh wallet and a
  * newly handed-over wallet both start in. Worth reading before naming a price on
- * `buyDataBundle`, since a price over the ceiling reverts.
+ * `buyDataBundleWithToken`, since a price over the ceiling reverts.
  */
-export declare const _dataBundlePriceCap: (client: WalletClient, eSIMWalletAddress: Address) => Promise<bigint>;
+export declare const _priceCapUSDCents: (client: WalletClient, eSIMWalletAddress: Address) => Promise<bigint>;
 /** The pending owner proposed via `requestTransferOwnership` (zero if none). */
 export declare const _newRequestedOwner: (client: WalletClient, eSIMWalletAddress: Address) => Promise<Address>;
 /** The current owner (device wallet) of this eSIM wallet. */
@@ -28,7 +28,8 @@ export declare const _deviceWallet: (client: WalletClient, eSIMWalletAddress: Ad
  *
  * The contract publishes no length getter, so there is no way to ask how many
  * entries exist. Read upwards from zero until a call reverts, or track the count
- * from the `DataBundleBought` and `TransactionHistoryPopulated` events, whose
- * `_totalEntries` is the length after the batch landed.
+ * from the `DataBundleBoughtWithToken`, `DataBundleSettlementRecorded` and
+ * `TransactionHistoryPopulated` events, whose `_totalEntries` is the length
+ * after the batch landed.
  */
 export declare const _transactionHistory: (client: WalletClient, eSIMWalletAddress: Address, index: bigint) => Promise<DataBundleDetails>;

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

@@ -25,6 +25,13 @@ export declare const _lazyDeploymentSalt: (client: WalletClient, deviceIdentifie
 export declare const _lazyDeployedESIMWallet: (client: WalletClient, eSIMIdentifier: string) => Promise<`0x${string}`>;
 /** How many of an eSIM's stored purchase entries have already reached its wallet. */
 export declare const _historyEntriesCopied: (client: WalletClient, eSIMIdentifier: string) => Promise<bigint>;
+/**
+ * History entries still waiting to be copied in for this eSIM. A wallet's own
+ * purchase paths (`buyDataBundleWithToken`, `recordSettledPurchase`) refuse a
+ * new entry while this is non-zero, since it would land ahead of history that
+ * has not arrived yet.
+ */
+export declare const _outstandingHistoryEntries: (client: WalletClient, eSIMIdentifier: string) => Promise<bigint>;
 /** Whether a device identifier has purchases recorded against it here. */
 export declare const _isDeviceIdentifierReserved: (client: WalletClient, deviceIdentifier: string) => Promise<boolean>;
 /** Whether an eSIM identifier is bound to a device here. */

package/dist/types/logic/admin/reads/paymentAdapter.reads.d.ts

@@ -0,0 +1,30 @@
+import { Address, Hex, WalletClient } from "viem";
+import { Asset } from "../../../types.js";
+/** The registry this adapter reads `vault()` and `isESIMWalletValid()` from. */
+export declare const _registry: (client: WalletClient) => Promise<Address>;
+/** The ERC-20 registered under the `USDC` symbol at configure time. */
+export declare const _settlementToken: (client: WalletClient) => Promise<Address>;
+/**
+ * The raw currency table entry for a symbol. `decimals` reads zero for a symbol
+ * never registered, which is how `resolveAsset` tells "not registered" apart
+ * from "registered but withdrawn" (`allowed: false`).
+ */
+export declare const _assets: (client: WalletClient, symbol: Hex) => Promise<Asset>;
+/** A currency's full entry, reverting if the symbol was never registered. */
+export declare const _resolveAsset: (client: WalletClient, symbol: Hex) => Promise<Asset>;
+/**
+ * The amount of `symbol`, in its smallest unit, that a `priceUSDCents` charge
+ * currently costs. Worth reading before `recordSettledPurchase`, to size
+ * `_tokenAmount` for the backend's own settlement record.
+ */
+export declare const _quote: (client: WalletClient, symbol: Hex, priceUSDCents: bigint) => Promise<bigint>;
+/**
+ * Whether a payment reference has already been spent here. Retired from the
+ * registry's live purchase paths (`PaymentAdapter.consumePaymentReference` is
+ * `onlyRegistry` but nothing calls it any more): replay protection now lives on
+ * `Registry.usedPaymentReferences`, scoped per eSIM wallet. Kept for whatever
+ * still reads the adapter's own record from before that move.
+ */
+export declare const _usedReferences: (client: WalletClient, paymentReference: Hex) => Promise<boolean>;
+/** The address holding upgrade authority over this adapter (its owner). */
+export declare const _upgradeManager: (client: WalletClient) => Promise<Address>;

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

@@ -18,15 +18,15 @@ export declare const _adminOfRecord: (client: WalletClient) => Promise<Address>;
  */
 export declare const _adminDisabled: (client: WalletClient) => Promise<boolean>;
 /**
- * Whether the protocol is paused. While true, every ETH-moving path on the
- * device wallets and eSIM wallets reverts `ProtocolPaused`.
+ * Whether the protocol is paused. While true, the purchase and token-pull
+ * paths on the device wallets and eSIM wallets revert `ProtocolPaused`.
  */
 export declare const _paused: (client: WalletClient) => Promise<boolean>;
 /**
- * The fallback price ceiling in wei, applied to any eSIM wallet holding no cap of
- * its own. Never zero.
+ * The fallback price ceiling in USD cents, applied to any eSIM wallet holding no
+ * cap of its own. Never zero.
  */
-export declare const _defaultDataBundlePriceCap: (client: WalletClient) => Promise<bigint>;
+export declare const _defaultPriceCapUSDCents: (client: WalletClient) => Promise<bigint>;
 /** The vault EOA recorded in the registry. */
 export declare const _vault: (client: WalletClient) => Promise<Address>;
 /** The pending admin nominated via `requestAdminUpdate` (zero address if none). */
@@ -128,3 +128,11 @@ export declare const _requireDeviceIdentifierNotReserved: (client: WalletClient,
 export declare const _proxiableUUID: (client: WalletClient) => Promise<Hex>;
 /** The OpenZeppelin upgrade interface this proxy speaks, currently `"5.0.0"`. */
 export declare const _upgradeInterfaceVersion: (client: WalletClient) => Promise<string>;
+/** The payment adapter this registry currently points at. */
+export declare const _paymentAdapter: (client: WalletClient) => Promise<Address>;
+/**
+ * Whether a payment reference has already been spent for an eSIM wallet.
+ * Scoped per wallet: pass the same `keccak256(abi.encode(eSIMWallet, paymentReference))`
+ * the contract keys `usedPaymentReferences` by, not the bare reference.
+ */
+export declare const _usedPaymentReferences: (client: WalletClient, scopedReference: Hex) => Promise<boolean>;

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

@@ -1,5 +1,5 @@
 import { Address, Hex, WalletClient } from "viem";
-import type { OwnerCall } from "../../types.js";
+import type { DataBundleDetails, OwnerCall } from "../../types.js";
 /** Wire (or rewire) the LazyWalletRegistry into the Registry. `onlyOwner`. */
 export declare const _addOrUpdateLazyWalletRegistryAddress: (client: WalletClient, lazyWalletRegistry: Address) => Promise<`0x${string}`>;
 /** Update the vault that receives eSIM payments. `onlyOwner`. */
@@ -31,13 +31,13 @@ export declare const _disableAdmin: (client: WalletClient) => Promise<`0x${strin
  */
 export declare const _enableAdmin: (client: WalletClient) => Promise<`0x${string}`>;
 /**
- * Stop the ETH-moving paths on every device wallet and eSIM wallet.
- * `onlyESIMWalletAdmin`, so this is the one emergency lever the backend key can
- * pull on its own.
+ * Stop the purchase and token-pull paths on every device wallet and eSIM
+ * wallet. `onlyESIMWalletAdmin`, so this is the one emergency lever the backend
+ * key can pull on its own.
  *
  * It cannot release it again: `_unpause` is `onlyOwner`. That split is what stops
- * a compromised backend key holding user funds. Owners can still spend their own
- * ETH through their device wallet's `execute`, which a pause never reaches.
+ * a compromised backend key holding user funds. Owners can still move their own
+ * funds through their device wallet's `execute`, which a pause never reaches.
  */
 export declare const _pause: (client: WalletClient) => Promise<`0x${string}`>;
 /**
@@ -51,12 +51,12 @@ export declare const _unpause: (client: WalletClient) => Promise<`0x${string}`>;
 /**
  * Set the price ceiling every eSIM wallet falls back to when it holds none of its
  * own. `onlyOwner`, deliberately not the admin: the admin names the price on
- * `buyDataBundle`, so it must not also be able to raise its own limit.
+ * `buyDataBundleWithToken`, so it must not also be able to raise its own limit.
  *
  * Zero reverts `ZeroDataBundlePriceCap`, since a zero would read as "no ceiling"
  * for every wallet without one of its own.
  */
-export declare const _setDefaultDataBundlePriceCap: (client: WalletClient, cap: bigint) => Promise<`0x${string}`>;
+export declare const _setDefaultPriceCapUSDCents: (client: WalletClient, cap: bigint) => Promise<`0x${string}`>;
 /**
  * Bind an eSIM's unique identifier to its wallet. `onlyESIMWalletAdmin`.
  *
@@ -64,6 +64,16 @@ export declare const _setDefaultDataBundlePriceCap: (client: WalletClient, cap:
  * wallet reverts rather than moving.
  */
 export declare const _assignESIMIdentifier: (client: WalletClient, eSIMWalletAddress: Address, eSIMUniqueIdentifier: string) => Promise<`0x${string}`>;
+/**
+ * Record a data bundle paid for outside the protocol - a card or an external
+ * wallet, never the device wallet. `onlyESIMWalletAdmin`. No money moves here:
+ * `_dataBundleDetail.settlement` must be `ExternalWallet` or `Fiat` (the
+ * contract reverts `SettlementNotAsserted` on `DeviceWallet`, since this call
+ * never sees a transfer to prove it), and `_tokenAmount` is recorded for
+ * offchain matching but never checked against `_dataBundleDetail.priceUSDCents`.
+ * `_paymentReference` is spendable once per eSIM wallet.
+ */
+export declare const _recordSettledPurchase: (client: WalletClient, eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReference: Hex) => Promise<`0x${string}`>;
 /**
  * Step 2 of the 2-step admin handover: the nominee accepts. The chain requires
  * `msg.sender` to equal the pending admin, so the `client` here must be the

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

@@ -1,34 +1,22 @@
 import { WalletClient, Address } from 'viem';
-import { mainnet, sepolia, optimism, optimismSepolia, arbitrum, arbitrumSepolia, base, baseSepolia } from "viem/chains";
+import { base, baseSepolia } from "viem/chains";
 export declare const ZERO: bigint;
 export declare const SIGNATURE_VALIDITY_SECONDS = 180;
 export declare const STUB_VERIFICATION_GAS_PAD: bigint;
 export declare const STUB_PRE_VERIFICATION_GAS_PAD: bigint;
 export declare enum CHAIN_ID {
-    MAINNET = 1,
-    SEPOLIA = 11155111,
-    OPTIMISM_MAINNET = 10,
-    OPTIMISM_SEPOLIA = 11155420,
     BASE_MAINNET = 8453,
-    BASE_SEPOLIA = 84532,
-    ARBITRUM_ONE = 42161,
-    ARBITRUM_SEPOLIA = 421614
+    BASE_SEPOLIA = 84532
 }
 export interface chainSpecifcConstants {
-    factoryAddresses: typeof sepoliaFactoryAddresses | typeof mainnetFactoryAddresses | typeof optimismMainnetFactoryAddresses | typeof optimismSepoliaFactoryAddresses | typeof baseMainnetFactoryAddresses | typeof baseSepoliaFactoryAddresses | typeof arbitrumOneFactoryAddresses | typeof arbitrumSepoliaFactoryAddresses;
-    chain: typeof mainnet | typeof sepolia | typeof optimism | typeof optimismSepolia | typeof base | typeof baseSepolia | typeof arbitrum | typeof arbitrumSepolia;
+    factoryAddresses: typeof baseMainnetFactoryAddresses | typeof baseSepoliaFactoryAddresses;
+    chain: typeof base | typeof baseSepolia;
     rpcURL: string;
     pimlicoRpcURL: string;
     customErrors: typeof customErrors;
 }
-export declare const sepoliaFactoryAddresses: Record<string, Address>;
-export declare const mainnetFactoryAddresses: Record<string, Address>;
-export declare const optimismMainnetFactoryAddresses: Record<string, Address>;
-export declare const optimismSepoliaFactoryAddresses: Record<string, Address>;
 export declare const baseMainnetFactoryAddresses: Record<string, Address>;
 export declare const baseSepoliaFactoryAddresses: Record<string, Address>;
-export declare const arbitrumOneFactoryAddresses: Record<string, Address>;
-export declare const arbitrumSepoliaFactoryAddresses: Record<string, Address>;
 export declare const customErrors: Record<string, string>;
 export declare const _extractChainID: (client: WalletClient) => Promise<number>;
-export declare const _getChainSpecificConstants: (chainID: CHAIN_ID.SEPOLIA | CHAIN_ID.MAINNET | CHAIN_ID.OPTIMISM_MAINNET | CHAIN_ID.OPTIMISM_SEPOLIA | CHAIN_ID.BASE_MAINNET | CHAIN_ID.BASE_SEPOLIA | CHAIN_ID.ARBITRUM_ONE | CHAIN_ID.ARBITRUM_SEPOLIA, rpcURL: string, pimlicoAPIKey?: string) => chainSpecifcConstants;
+export declare const _getChainSpecificConstants: (chainID: CHAIN_ID.BASE_MAINNET | CHAIN_ID.BASE_SEPOLIA, rpcURL: string, pimlicoAPIKey?: string) => chainSpecifcConstants;

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

@@ -9,14 +9,14 @@ import { P256Key } from "../types.js";
  * atomically through `executeBatch`.
  */
 export declare const _sendUserOperation: (client: KokioSmartAccountClient, calls: Call[]) => Promise<`0x${string}`>;
-export declare const _toggleAccessToETH: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address, hasAccessToETH: boolean) => Promise<`0x${string}`>;
+export declare const _toggleAccessToFunds: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address, hasAccessToFunds: boolean) => Promise<`0x${string}`>;
 /**
  * Bind an eSIM wallet this device wallet already owns.
  *
- * A bind never carries ETH access: the contract reverts on a `true` rather than
+ * A bind never carries fund access: the contract reverts on a `true` rather than
  * downgrading it quietly, so the SDK passes `false` and there is nothing to
- * choose. `toggleAccessToETH` is the only way to grant it, which is what stops a
- * bind from undoing the owner's revocation.
+ * choose. `toggleAccessToFunds` is the only way to grant it, which is what stops
+ * a bind from undoing the owner's revocation.
  */
 export declare const _addESIMWallet: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address) => Promise<`0x${string}`>;
 /**
@@ -54,10 +54,10 @@ export declare const _deviceUniqueIdentifier: (client: KokioSmartAccountClient,
 /** Whether this wallet currently holds the given eSIM wallet. */
 export declare const _isValidESIMWallet: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address) => Promise<boolean>;
 /**
- * Whether an eSIM wallet may pull ETH from this one. Binding a wallet never
- * grants it, so this stays false until `toggleAccessToETH` says otherwise.
+ * Whether an eSIM wallet may pull funds from this one. Binding a wallet never
+ * grants it, so this stays false until `toggleAccessToFunds` says otherwise.
  */
-export declare const _canPullETH: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address) => Promise<boolean>;
+export declare const _canPullFunds: (client: KokioSmartAccountClient, address: Address, eSIMWalletAddress: Address) => Promise<boolean>;
 /**
  * Check a signature over an arbitrary message, per ERC-1271. Returns
  * `0x1626ba7e` when the signature is valid and unexpired, `0xffffffff` otherwise.

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

@@ -1,22 +1,36 @@
-import { Address } from "viem";
+import { Address, Hex } from "viem";
 import { DataBundleDetails } from "../types.js";
 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.
+ * Cap what this eSIM wallet may be charged for one data bundle, in USD cents.
+ * 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.
+ * the admin names the price on `buyDataBundleWithToken`, 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 _setPriceCapUSDCents: (client: KokioSmartAccountClient, address: Address, cap: bigint) => Promise<`0x${string}`>;
+/**
+ * Buy a data bundle in `asset`, an ERC-20 the payment adapter accepts.
+ *
+ * `_maxAmountIn` is the most of `asset` the buyer will spend, in its smallest
+ * unit - read it from `paymentAdapter.quote(asset, dataBundleDetails.priceUSDCents)`
+ * first. `_paymentReference` ties this purchase to its offchain order and is
+ * spendable once per eSIM wallet; the caller supplies it rather than the SDK
+ * inventing one.
+ */
+export declare const _buyDataBundleWithToken: (client: KokioSmartAccountClient, address: Address, dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex) => Promise<`0x${string}`>;
+/**
+ * Send an ERC-20 held by this eSIM wallet back to its owning device wallet.
+ * `onlyDeviceWallet`.
+ */
+export declare const _sendTokenToDeviceWallet: (client: KokioSmartAccountClient, address: Address, token: Address, amount: bigint) => 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.
+ * The ceiling that actually applies to this wallet's next purchase, in USD
+ * cents. Read it before naming a price on `buyDataBundleWithToken`, 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
@@ -25,11 +39,11 @@ export declare const _owner: (client: KokioSmartAccountClient, address: Address)
  * 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
+ * cap in both `initialize` and `setDefaultPriceCapUSDCents`. 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>;
+export declare const _priceCapUSDCents: (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.
@@ -41,8 +55,8 @@ export declare const _deviceWallet: (client: KokioSmartAccountClient, address: A
  * 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.
+ * reverts, or track the count from the `DataBundleBoughtWithToken`,
+ * `DataBundleSettlementRecorded` 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}`>;

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

@@ -1,4 +1,4 @@
-import { Hex } from "viem";
+import { Abi, Account, Chain, ContractFunctionArgs, ContractFunctionName, Hex, WalletClient, WriteContractParameters, WriteContractReturnType } from "viem";
 /**
  * Base class for every error the Kokio SDK throws deliberately. Consumers can
  * `instanceof KokioError` to distinguish SDK-originated failures from viem /
@@ -106,3 +106,18 @@ export declare class ContractRevertError extends KokioError {
     readonly decoded: DecodedRevert | null;
     constructor(data: Hex);
 }
+/**
+ * Pulls a ContractRevertError out of an error thrown by viem, or `null` if it
+ * isn't a revert viem could decode a selector for.
+ */
+export declare const toContractRevertError: (err: unknown) => ContractRevertError | null;
+/**
+ * `client.writeContract`, but a recognised on-chain revert comes back as a
+ * ContractRevertError instead of viem's raw error chain. Anything else -
+ * network failures, an unrecognised revert selector - is rethrown as-is.
+ *
+ * Mirrors `WalletClient["writeContract"]`'s own generics rather than reading
+ * them off `Parameters<...>`, since that would collapse the per-call overload
+ * (e.g. a payable function's `value` field) to a single, wrong shape.
+ */
+export declare const writeContractOrThrow: <const abi extends Abi | readonly unknown[], functionName extends ContractFunctionName<abi, "payable" | "nonpayable">, args extends ContractFunctionArgs<abi, "payable" | "nonpayable", functionName>, chainOverride extends Chain | undefined = undefined>(client: WalletClient, request: WriteContractParameters<abi, functionName, args, Chain | undefined, Account | undefined, chainOverride>) => Promise<WriteContractReturnType>;

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

@@ -0,0 +1,40 @@
+import { Address, Hex } from "viem";
+import { KokioSmartAccountClient } from "../types.js";
+import { Asset } from "../types.js";
+/**
+ * The registry this adapter reads `vault()` and `isESIMWalletValid()` from.
+ */
+export declare const _registry: (client: KokioSmartAccountClient) => Promise<Address>;
+/** The ERC-20 registered under the `USDC` symbol at configure time. */
+export declare const _settlementToken: (client: KokioSmartAccountClient) => Promise<Address>;
+/**
+ * The raw currency table entry for a symbol. `decimals` reads zero for a symbol
+ * never registered, which is how `resolveAsset` tells "not registered" apart
+ * from "registered but withdrawn" (`allowed: false`).
+ */
+export declare const _assets: (client: KokioSmartAccountClient, symbol: Hex) => Promise<Asset>;
+/**
+ * A currency's full entry, reverting if the symbol was never registered.
+ * `_asset` is not required for `buyDataBundleWithToken`, but is worth reading
+ * first: `token` being the zero address means the currency is fiat-only and the
+ * purchase will revert with `AssetNotTransferable`.
+ */
+export declare const _resolveAsset: (client: KokioSmartAccountClient, symbol: Hex) => Promise<Asset>;
+/**
+ * The amount of `symbol`, in its smallest unit, that a `priceUSDCents` charge
+ * currently costs. Read this before calling `buyDataBundleWithToken`, and pass
+ * the result (or a value at least this large) as `_maxAmountIn`: nothing today
+ * moves the price between the quote and the purchase, so the two always agree,
+ * but the contract will not assume that on the caller's behalf.
+ */
+export declare const _quote: (client: KokioSmartAccountClient, symbol: Hex, priceUSDCents: bigint) => Promise<bigint>;
+/**
+ * Whether a payment reference has already been spent here. Retired from the
+ * registry's live purchase paths (`PaymentAdapter.consumePaymentReference` is
+ * `onlyRegistry` but nothing calls it any more): replay protection now lives on
+ * `Registry.usedPaymentReferences`, scoped per eSIM wallet. Kept for whatever
+ * still reads the adapter's own record from before that move.
+ */
+export declare const _usedReferences: (client: KokioSmartAccountClient, paymentReference: Hex) => Promise<boolean>;
+/** The address holding upgrade authority over this adapter (its owner). */
+export declare const _upgradeManager: (client: KokioSmartAccountClient) => Promise<Address>;

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

@@ -1,4 +1,4 @@
-import { Address } from "viem";
+import { Address, Hex } from "viem";
 import { KokioSmartAccountClient } from "../types.js";
 /**
  * Take on an eSIM wallet and clear any standby flag left by a transfer.
@@ -29,8 +29,9 @@ export declare const _toggleESIMWalletStandbyStatus: (client: KokioSmartAccountC
  */
 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.
+ * Whether the protocol is paused. While true, the purchase and token-pull paths
+ * on the device wallets and eSIM wallets revert, so check this before offering a
+ * purchase.
  */
 export declare const _paused: (client: KokioSmartAccountClient) => Promise<boolean>;
 /**
@@ -67,8 +68,22 @@ export declare const _isESIMIdentifierClaimed: (client: KokioSmartAccountClient,
  * 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>;
+/** The fallback price ceiling in USD cents for a wallet holding no cap of its own. */
+export declare const _defaultPriceCapUSDCents: (client: KokioSmartAccountClient) => Promise<bigint>;
+/** The payment adapter this registry currently points at. */
+export declare const _paymentAdapter: (client: KokioSmartAccountClient) => Promise<Address>;
+/**
+ * Whether a payment reference has already been spent for an eSIM wallet.
+ * Scoped per wallet: pass the same `keccak256(abi.encode(eSIMWallet, paymentReference))`
+ * the contract keys `usedPaymentReferences` by, not the bare reference.
+ */
+export declare const _usedPaymentReferences: (client: KokioSmartAccountClient, scopedReference: Hex) => Promise<boolean>;
+/**
+ * Throws if `eSIMWallet` still has lazy-deployment history waiting to be copied
+ * in. `buyDataBundleWithToken` checks this itself before writing a new entry, so
+ * calling it first only turns that revert into a typed error ahead of a userOp.
+ */
+export declare const _requireLazyHistoryCopied: (client: KokioSmartAccountClient, eSIMWallet: Address) => Promise<void>;
 /**
  * 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

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

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

package/dist/types/types.d.ts

@@ -94,9 +94,27 @@ export type P256Credential = {
         s: Hex;
     };
 };
+/**
+ * Which contract, if any, saw the money for a data bundle move. Mirrors the
+ * on-chain `Settlement` enum (CustomStructs.sol) - viem decodes a Solidity enum
+ * as its `uint8` position, so the member order here must match exactly.
+ */
+export declare enum Settlement {
+    DeviceWallet = 0,
+    ExternalWallet = 1,
+    Fiat = 2
+}
 export type DataBundleDetails = {
-    dataBundleID: string;
-    dataBundlePrice: bigint;
+    id: Hex;
+    priceUSDCents: bigint;
+    settlement: Settlement;
+};
+/** One currency the payment adapter accepts. Mirrors the on-chain `Asset` struct (PaymentAdapter.sol). */
+export type Asset = {
+    allowed: boolean;
+    isDollarUnit: boolean;
+    decimals: number;
+    token: Address;
 };
 /** One `deployMoreESIMWalletsForLazyDevice` (or first) transaction, read back from its receipt. */
 export type LazyDeploymentBatch = {

package/package.json

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