kokio-sdk 2.1.0 → 3.0.0

package/dist/esm/logic/admin/reads/paymentAdapter.reads.js

@@ -0,0 +1,106 @@
+import { publicActions } from "viem";
+import { _getChainSpecificConstants } from "../../constants.js";
+import { PaymentAdapter } from "../../../abis/index.js";
+// Read-only admin logic for `PaymentAdapter`. Every write on it
+// (registerAsset/updateAsset) is `onlyOwner`, i.e. only reachable through the
+// timelock, so those live as payload builders on `KokioAdmin.protocolAdmin`
+// rather than here.
+/** The registry this adapter reads `vault()` and `isESIMWalletValid()` from. */
+export const _registry = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "registry",
+        args: []
+    });
+};
+/** The ERC-20 registered under the `USDC` symbol at configure time. */
+export const _settlementToken = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "settlementToken",
+        args: []
+    });
+};
+/**
+ * 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 const _assets = async (client, symbol) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    const [allowed, isDollarUnit, decimals, token] = await client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "assets",
+        args: [symbol]
+    });
+    return { allowed, isDollarUnit, decimals, token };
+};
+/** A currency's full entry, reverting if the symbol was never registered. */
+export const _resolveAsset = async (client, symbol) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "resolveAsset",
+        args: [symbol]
+    });
+};
+/**
+ * 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 const _quote = async (client, symbol, priceUSDCents) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "quote",
+        args: [symbol, priceUSDCents]
+    });
+};
+/**
+ * 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 const _usedReferences = async (client, paymentReference) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "usedReferences",
+        args: [paymentReference]
+    });
+};
+/** The address holding upgrade authority over this adapter (its owner). */
+export const _upgradeManager = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: "upgradeManager",
+        args: []
+    });
+};

package/dist/esm/logic/admin/reads/registry.reads.js

@@ -54,8 +54,8 @@ export const _adminDisabled = async (client) => {
     });
 };
 /**
- * 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 const _paused = async (client) => {
     const chainID = await client.getChainId();
@@ -69,17 +69,17 @@ export const _paused = async (client) => {
     });
 };
 /**
- * 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 const _defaultDataBundlePriceCap = async (client) => {
+export const _defaultPriceCapUSDCents = async (client) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
     return client.extend(publicActions).readContract({
         address: values.factoryAddresses.REGISTRY,
         abi: Registry,
-        functionName: "defaultDataBundlePriceCap",
+        functionName: "defaultPriceCapUSDCents",
         args: []
     });
 };
@@ -414,3 +414,31 @@ export const _upgradeInterfaceVersion = async (client) => {
         args: []
     });
 };
+/** The payment adapter this registry currently points at. */
+export const _paymentAdapter = async (client) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "paymentAdapter",
+        args: []
+    });
+};
+/**
+ * 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 const _usedPaymentReferences = async (client, scopedReference) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "usedPaymentReferences",
+        args: [scopedReference]
+    });
+};

package/dist/esm/logic/admin/registry.eoa.js

@@ -110,13 +110,13 @@ export const _enableAdmin = async (client) => {
     });
 };
 /**
- * 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 const _pause = async (client) => {
     const chainID = await client.getChainId();
@@ -158,12 +158,12 @@ export const _unpause = async (client) => {
 /**
  * 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 const _setDefaultDataBundlePriceCap = async (client, cap) => {
+export const _setDefaultPriceCapUSDCents = async (client, cap) => {
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
@@ -174,7 +174,7 @@ export const _setDefaultDataBundlePriceCap = async (client, cap) => {
         chain: values.chain,
         account: client.account.address,
         abi: Registry,
-        functionName: 'setDefaultDataBundlePriceCap',
+        functionName: 'setDefaultPriceCapUSDCents',
         args: [cap]
     });
 };
@@ -199,6 +199,30 @@ export const _assignESIMIdentifier = async (client, eSIMWalletAddress, eSIMUniqu
         args: [eSIMWalletAddress, eSIMUniqueIdentifier]
     });
 };
+/**
+ * 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 const _recordSettledPurchase = async (client, eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    if (!client.account)
+        throw new MissingEOAWalletError();
+    return writeContractOrThrow(client, {
+        address: values.factoryAddresses.REGISTRY,
+        chain: values.chain,
+        account: client.account.address,
+        abi: Registry,
+        functionName: 'recordSettledPurchase',
+        args: [eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference]
+    });
+};
 /**
  * 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/esm/logic/constants.js

@@ -1,5 +1,5 @@
 import { InvalidClientError, UnconfiguredChainError, UnsupportedChainError, } from './errors.js';
-import { mainnet, sepolia, optimism, optimismSepolia, arbitrum, arbitrumSepolia, base, baseSepolia } from "viem/chains";
+import { base, baseSepolia } from "viem/chains";
 export const ZERO = BigInt('0');
 export const SIGNATURE_VALIDITY_SECONDS = 180; // 3 minutes validity
 // Gas estimation runs before a passkey signature exists, so the account hands the
@@ -18,60 +18,15 @@ export const STUB_VERIFICATION_GAS_PAD = BigInt(60_000);
 // preVerificationGas is charged whether or not it is used, so this stays close to
 // the measured shortfall.
 export const STUB_PRE_VERIFICATION_GAS_PAD = BigInt(15_000);
+// Only the two chains the protocol actually targets. A chain gets an entry here
+// once a deployment exists for it, not before.
 export var CHAIN_ID;
 (function (CHAIN_ID) {
-    CHAIN_ID[CHAIN_ID["MAINNET"] = 1] = "MAINNET";
-    CHAIN_ID[CHAIN_ID["SEPOLIA"] = 11155111] = "SEPOLIA";
-    CHAIN_ID[CHAIN_ID["OPTIMISM_MAINNET"] = 10] = "OPTIMISM_MAINNET";
-    CHAIN_ID[CHAIN_ID["OPTIMISM_SEPOLIA"] = 11155420] = "OPTIMISM_SEPOLIA";
     CHAIN_ID[CHAIN_ID["BASE_MAINNET"] = 8453] = "BASE_MAINNET";
     CHAIN_ID[CHAIN_ID["BASE_SEPOLIA"] = 84532] = "BASE_SEPOLIA";
-    CHAIN_ID[CHAIN_ID["ARBITRUM_ONE"] = 42161] = "ARBITRUM_ONE";
-    CHAIN_ID[CHAIN_ID["ARBITRUM_SEPOLIA"] = 421614] = "ARBITRUM_SEPOLIA";
 })(CHAIN_ID || (CHAIN_ID = {}));
-// Cleared: the deployment here targets EntryPoint v0.7, which this SDK no longer
-// speaks. Refill only after a redeploy on v0.8.
-export const sepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
-};
-export const mainnetFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
-};
-export const optimismMainnetFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
-};
-// Cleared for the same reason as Sepolia: a v0.7 deployment this SDK cannot use.
-export const optimismSepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
-};
+// Not yet deployed. Kept as a placeholder so mainnet has a documented shape to
+// fill in once the protocol ships there, following Base Sepolia's soak.
 export const baseMainnetFactoryAddresses = {
     DEVICE_WALLET_FACTORY: '0x',
     ESIM_WALLET_FACTORY: '0x',
@@ -80,37 +35,19 @@ export const baseMainnetFactoryAddresses = {
     ENTRY_POINT: '0x',
     SENDER_CREATOR: '0x',
     P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
+    PROTOCOL_ADMIN: '0x',
+    PAYMENT_ADAPTER: '0x'
 };
 export const baseSepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0xB006c7066C89a5d7Bfc229e9fb0bADf96c8F979f',
-    ESIM_WALLET_FACTORY: '0x13998C0bb7433c51cE5101922B12EE69F459699A',
-    LAZY_WALLET_REGISTRY: '0x394177c5cc4762b897c37de1820259B75993e033',
-    REGISTRY: '0x89e386E3251692F21a2E9048A46518AdC2A5Cb4A',
+    DEVICE_WALLET_FACTORY: '0x0BB3BA8D9233514a4aA6D72c243a2473f9cFf0bb',
+    ESIM_WALLET_FACTORY: '0x57da54e07705de17c713ec311ac193e83470D5a5',
+    LAZY_WALLET_REGISTRY: '0x5bE46Cf216186Bc2E3C220729331D6bE7d186e84',
+    REGISTRY: '0x916b6b554119c789EF3026EDeB0E1Ba741b42A49',
     ENTRY_POINT: '0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108',
     SENDER_CREATOR: '0x449ED7C3e6Fee6a97311d4b55475DF59C44AdD33',
-    P256VERIFIER: '0x625561429bD99d647956ccBCA4eBf762aaA142c5',
-    PROTOCOL_ADMIN: '0x77A1D6f27462c34BF038832d9Cff6b3E94a9Fe6F'
-};
-export const arbitrumOneFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
-};
-export const arbitrumSepoliaFactoryAddresses = {
-    DEVICE_WALLET_FACTORY: '0x',
-    ESIM_WALLET_FACTORY: '0x',
-    LAZY_WALLET_REGISTRY: '0x',
-    REGISTRY: '0x',
-    ENTRY_POINT: '0x',
-    SENDER_CREATOR: '0x',
-    P256VERIFIER: '0x',
-    PROTOCOL_ADMIN: '0x'
+    P256VERIFIER: '0x6FA3E7E145476Dc4682734Fd845019A3872b4821',
+    PROTOCOL_ADMIN: '0xdDeCC2C1345BC966337B5f4Fe57EC2D5bfad751A',
+    PAYMENT_ADAPTER: '0xBFaA666a8074924588E96507c307b680ecCeB2c1'
 };
 export const customErrors = {
     NULL_OR_UNDEFINED_VALUE: "Error: Null or undefined value provided",
@@ -123,19 +60,12 @@ export const _extractChainID = async (client) => {
     }
     return client.getChainId();
 };
-// Maps each supported chain id to its factory-address book + viem chain. Chains
-// whose addresses are still '0x' placeholders are intentionally listed so the
-// guard below can reject them with a clear message rather than leaking '0x'
-// into viem calls.
+// Maps each supported chain id to its factory-address book + viem chain. Base
+// Mainnet is listed with '0x' placeholders so the guard below rejects it with a
+// clear message rather than leaking '0x' into viem calls.
 const CHAIN_CONFIG = {
-    [CHAIN_ID.SEPOLIA]: { factoryAddresses: sepoliaFactoryAddresses, chain: sepolia },
-    [CHAIN_ID.MAINNET]: { factoryAddresses: mainnetFactoryAddresses, chain: mainnet },
-    [CHAIN_ID.OPTIMISM_MAINNET]: { factoryAddresses: optimismMainnetFactoryAddresses, chain: optimism },
-    [CHAIN_ID.OPTIMISM_SEPOLIA]: { factoryAddresses: optimismSepoliaFactoryAddresses, chain: optimismSepolia },
     [CHAIN_ID.BASE_MAINNET]: { factoryAddresses: baseMainnetFactoryAddresses, chain: base },
     [CHAIN_ID.BASE_SEPOLIA]: { factoryAddresses: baseSepoliaFactoryAddresses, chain: baseSepolia },
-    [CHAIN_ID.ARBITRUM_ONE]: { factoryAddresses: arbitrumOneFactoryAddresses, chain: arbitrum },
-    [CHAIN_ID.ARBITRUM_SEPOLIA]: { factoryAddresses: arbitrumSepoliaFactoryAddresses, chain: arbitrumSepolia },
 };
 // A factory address book is only usable if every entry is a real 20-byte
 // address - an unconfigured chain leaves '0x' placeholders behind.

package/dist/esm/logic/deviceWallet.js

@@ -32,18 +32,18 @@ export const _sendUserOperation = async (client, calls) => {
         calls
     });
 };
-export const _toggleAccessToETH = async (client, address, eSIMWalletAddress, hasAccessToETH) => {
+export const _toggleAccessToFunds = async (client, address, eSIMWalletAddress, hasAccessToFunds) => {
     if (!client.account)
         throw new MissingSmartWalletError();
-    // UserOp - `onlySelf`; the device wallet toggles ETH access for an eSIM wallet it owns.
+    // UserOp - `onlySelf`; the device wallet toggles fund access for an eSIM wallet it owns.
     return client.sendUserOperation({
         account: client.account,
         calls: [{
                 to: address,
                 data: encodeFunctionData({
                     abi: DeviceWallet,
-                    functionName: "toggleAccessToETH",
-                    args: [eSIMWalletAddress, hasAccessToETH]
+                    functionName: "toggleAccessToFunds",
+                    args: [eSIMWalletAddress, hasAccessToFunds]
                 })
             }]
     });
@@ -51,10 +51,10 @@ export const _toggleAccessToETH = async (client, address, eSIMWalletAddress, has
 /**
  * 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 const _addESIMWallet = async (client, address, eSIMWalletAddress) => {
     if (!client.account)
@@ -196,14 +196,14 @@ export const _isValidESIMWallet = async (client, address, eSIMWalletAddress) =>
     });
 };
 /**
- * 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 const _canPullETH = async (client, address, eSIMWalletAddress) => {
+export const _canPullFunds = async (client, address, eSIMWalletAddress) => {
     return client.readContract({
         address,
         abi: DeviceWallet,
-        functionName: "canPullETH",
+        functionName: "canPullFunds",
         args: [eSIMWalletAddress]
     });
 };

package/dist/esm/logic/eSIMWallet.js

@@ -1,7 +1,7 @@
 import { encodeFunctionData, maxUint256 } from "viem";
 import { MissingSmartWalletError } from "./errors.js";
 import { ESIMWallet } from "../abis/index.js";
-import { _defaultDataBundlePriceCap } from "./registry.js";
+import { _defaultPriceCapUSDCents } from "./registry.js";
 // Not exposed on this surface:
 //   - populateHistory and setESIMUniqueIdentifier are `onlyRegistry` - callable
 //     only by the registry contract. Naming an eSIM goes through
@@ -12,15 +12,15 @@ import { _defaultDataBundlePriceCap } from "./registry.js";
 // 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.
 /**
- * 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 const _setDataBundlePriceCap = async (client, address, cap) => {
+export const _setPriceCapUSDCents = async (client, address, cap) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlyDeviceWallet`.
@@ -30,13 +30,22 @@ export const _setDataBundlePriceCap = async (client, address, cap) => {
                 to: address,
                 data: encodeFunctionData({
                     abi: ESIMWallet,
-                    functionName: "setDataBundlePriceCap",
+                    functionName: "setPriceCapUSDCents",
                     args: [cap]
                 })
             }]
     });
 };
-export const _buyDataBundle = async (client, address, dataBundleDetails) => {
+/**
+ * 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 const _buyDataBundleWithToken = async (client, address, dataBundleDetails, asset, maxAmountIn, paymentReference) => {
     if (!client.account)
         throw new MissingSmartWalletError();
     // UserOp - `onlyDeviceWalletOrESIMWalletAdmin`; the owning device wallet may buy.
@@ -46,8 +55,28 @@ export const _buyDataBundle = async (client, address, dataBundleDetails) => {
                 to: address,
                 data: encodeFunctionData({
                     abi: ESIMWallet,
-                    functionName: "buyDataBundle",
-                    args: [dataBundleDetails]
+                    functionName: "buyDataBundleWithToken",
+                    args: [dataBundleDetails, asset, maxAmountIn, paymentReference]
+                })
+            }]
+    });
+};
+/**
+ * Send an ERC-20 held by this eSIM wallet back to its owning device wallet.
+ * `onlyDeviceWallet`.
+ */
+export const _sendTokenToDeviceWallet = async (client, address, token, amount) => {
+    if (!client.account)
+        throw new MissingSmartWalletError();
+    // UserOp - `onlyDeviceWallet`.
+    return client.sendUserOperation({
+        account: client.account,
+        calls: [{
+                to: address,
+                data: encodeFunctionData({
+                    abi: ESIMWallet,
+                    functionName: "sendTokenToDeviceWallet",
+                    args: [token, amount]
                 })
             }]
     });
@@ -62,9 +91,9 @@ export const _owner = async (client, 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
@@ -73,20 +102,20 @@ export const _owner = async (client, 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 const _dataBundlePriceCap = async (client, address) => {
+export const _priceCapUSDCents = async (client, address) => {
     const walletCap = await client.readContract({
         address,
         abi: ESIMWallet,
-        functionName: "dataBundlePriceCap",
+        functionName: "priceCapUSDCents",
         args: []
     });
     if (walletCap !== 0n)
         return walletCap;
-    const registryCap = await _defaultDataBundlePriceCap(client);
+    const registryCap = await _defaultPriceCapUSDCents(client);
     return registryCap === 0n ? maxUint256 : registryCap;
 };
 /**
@@ -107,17 +136,17 @@ export const _deviceWallet = async (client, address) => {
  * 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 const _transactionHistory = async (client, address, index) => {
-    const [dataBundleID, dataBundlePrice] = await client.readContract({
+    const [id, priceUSDCents, settlement] = await client.readContract({
         address,
         abi: ESIMWallet,
         functionName: "transactionHistory",
         args: [index]
     });
-    return { dataBundleID, dataBundlePrice };
+    return { id, priceUSDCents, settlement };
 };
 export const _requestTransferOwnership = async (client, address, newOwner) => {
     if (!client.account)