kokio-sdk 2.0.0 → 3.0.0

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

@@ -1,6 +1,6 @@
 import { encodeFunctionData, publicActions } from "viem";
 import { _getChainSpecificConstants } from "../constants.js";
-import { MissingEOAWalletError } from "../errors.js";
+import { MissingEOAWalletError, writeContractOrThrow } from "../errors.js";
 import { ProtocolAdmin, Registry } from "../../abis/index.js";
 // Admin-EOA logic for `ProtocolAdmin`, the timelock that owns `Registry`,
 // `LazyWalletRegistry`, `DeviceWalletFactory` and `ESIMWalletFactory`.
@@ -116,7 +116,7 @@ export const _schedule = async (client, call, opts = {}, delay) => {
         functionName: "hashOperation",
         args: [target, value, payload, predecessor, salt]
     });
-    const hash = await client.writeContract({
+    const hash = await writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -156,7 +156,7 @@ export const _scheduleBatch = async (client, calls, opts = {}, delay) => {
         functionName: "hashOperationBatch",
         args: [targets, callValues, payloads, predecessor, salt]
     });
-    const hash = await client.writeContract({
+    const hash = await writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -183,7 +183,7 @@ export const _scheduleRaw = async (client, target, value, payload, predecessor,
         functionName: "hashOperation",
         args: [target, value, payload, predecessor, salt]
     });
-    const hash = await client.writeContract({
+    const hash = await writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -208,7 +208,7 @@ export const _execute = async (client, operation) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -223,7 +223,7 @@ export const _executeBatch = async (client, operation) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -238,7 +238,7 @@ export const _executeRaw = async (client, target, value, payload, predecessor, s
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -259,7 +259,7 @@ export const _cancel = async (client, id) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -281,7 +281,7 @@ export const _unpauseInstantly = async (client, target) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -301,7 +301,7 @@ export const _revokeCancellersInstantly = async (client, accounts) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -324,7 +324,7 @@ export const _disableAdminInstantly = async (client, target) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -345,7 +345,7 @@ export const _acceptOwnershipBatch = async (client, targets) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -362,7 +362,7 @@ export const _renounceRole = async (client, role, account) => {
     const values = await _resolve(client);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.PROTOCOL_ADMIN,
         chain: values.chain,
         account: client.account.address,
@@ -456,22 +456,40 @@ export const _unpauseCall = async (client, target) => {
     };
 };
 /**
- * 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 const _setDefaultDataBundlePriceCapCall = async (client, cap, target) => {
+export const _setDefaultPriceCapUSDCentsCall = async (client, cap, target) => {
     const values = await _resolve(client);
     return {
         address: target ?? values.factoryAddresses.REGISTRY,
         abi: Registry,
-        functionName: 'setDefaultDataBundlePriceCap',
+        functionName: 'setDefaultPriceCapUSDCents',
         args: [cap],
     };
 };
+/**
+ * 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 const _setPaymentAdapterCall = async (client, paymentAdapter, target) => {
+    const values = await _resolve(client);
+    return {
+        address: target ?? values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: 'setPaymentAdapter',
+        args: [paymentAdapter],
+    };
+};
 // ---------------------------------------------------------------------------
 // Admin suspension payloads - the owner's route, aimed at the target contract
 // ---------------------------------------------------------------------------

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

@@ -24,11 +24,11 @@ export const _isValidESIMWallet = async (client, deviceWalletAddress, eSIMWallet
     });
 };
 /** Whether an eSIM wallet is allowed to pull ETH from this device wallet. */
-export const _canPullETH = async (client, deviceWalletAddress, eSIMWallet) => {
+export const _canPullFunds = async (client, deviceWalletAddress, eSIMWallet) => {
     return client.extend(publicActions).readContract({
         address: deviceWalletAddress,
         abi: DeviceWallet,
-        functionName: "canPullETH",
+        functionName: "canPullFunds",
         args: [eSIMWallet]
     });
 };

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

@@ -26,13 +26,13 @@ export const _eSIMUniqueIdentifier = async (client, eSIMWalletAddress) => {
  * 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 const _dataBundlePriceCap = async (client, eSIMWalletAddress) => {
+export const _priceCapUSDCents = async (client, eSIMWalletAddress) => {
     return client.extend(publicActions).readContract({
         address: eSIMWalletAddress,
         abi: ESIMWallet,
-        functionName: "dataBundlePriceCap",
+        functionName: "priceCapUSDCents",
         args: []
     });
 };
@@ -74,15 +74,16 @@ export const _deviceWallet = async (client, eSIMWalletAddress) => {
  *
  * 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 const _transactionHistory = async (client, eSIMWalletAddress, index) => {
-    const [dataBundleID, dataBundlePrice] = await client.extend(publicActions).readContract({
+    const [id, priceUSDCents, settlement] = await client.extend(publicActions).readContract({
         address: eSIMWalletAddress,
         abi: ESIMWallet,
         functionName: "transactionHistory",
         args: [index]
     });
-    return { dataBundleID, dataBundlePrice };
+    return { id, priceUSDCents, settlement };
 };

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

@@ -38,13 +38,13 @@ export const _deviceIdentifierToESIMDetails = async (client, deviceIdentifier, e
     const chainID = await client.getChainId();
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
-    const [dataBundleID, dataBundlePrice] = await client.extend(publicActions).readContract({
+    const [id, priceUSDCents, settlement] = await client.extend(publicActions).readContract({
         address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
         abi: LazyWalletRegistry,
         functionName: "deviceIdentifierToESIMDetails",
         args: [deviceIdentifier, eSIMIdentifier, index]
     });
-    return { dataBundleID, dataBundlePrice };
+    return { id, priceUSDCents, settlement };
 };
 /** Most eSIM wallets one `deployLazyWalletAndSetESIMIdentifier` call will deploy. */
 export const _maxESIMWalletsPerCall = async (client) => {
@@ -125,6 +125,23 @@ export const _historyEntriesCopied = async (client, eSIMIdentifier) => {
         args: [eSIMIdentifier]
     });
 };
+/**
+ * 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 const _outstandingHistoryEntries = async (client, eSIMIdentifier) => {
+    const chainID = await client.getChainId();
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return client.extend(publicActions).readContract({
+        address: values.factoryAddresses.LAZY_WALLET_REGISTRY,
+        abi: LazyWalletRegistry,
+        functionName: "outstandingHistoryEntries",
+        args: [eSIMIdentifier]
+    });
+};
 /** Whether a device identifier has purchases recorded against it here. */
 export const _isDeviceIdentifierReserved = async (client, deviceIdentifier) => {
     const chainID = await client.getChainId();

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

@@ -1,5 +1,5 @@
 import { _getChainSpecificConstants } from "../constants.js";
-import { MissingEOAWalletError } from "../errors.js";
+import { MissingEOAWalletError, writeContractOrThrow } from "../errors.js";
 import { Registry } from "../../abis/index.js";
 // Admin-EOA logic for `Registry`. Most of this is `onlyOwner`, so the `client`
 // must carry the owner EOA. `_acceptAdminUpdate` is the nominee's own call and
@@ -16,7 +16,7 @@ export const _addOrUpdateLazyWalletRegistryAddress = async (client, lazyWalletRe
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -32,7 +32,7 @@ export const _updateVaultAddress = async (client, newVaultAddress) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -56,7 +56,7 @@ export const _requestAdminUpdate = async (client, newAdmin) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -78,7 +78,7 @@ export const _disableAdmin = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -100,7 +100,7 @@ export const _enableAdmin = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -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();
@@ -124,7 +124,7 @@ export const _pause = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -146,7 +146,7 @@ export const _unpause = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -158,23 +158,23 @@ 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);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
         abi: Registry,
-        functionName: 'setDefaultDataBundlePriceCap',
+        functionName: 'setDefaultPriceCapUSDCents',
         args: [cap]
     });
 };
@@ -190,7 +190,7 @@ export const _assignESIMIdentifier = async (client, eSIMWalletAddress, eSIMUniqu
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -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
@@ -210,7 +234,7 @@ export const _acceptAdminUpdate = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,
@@ -234,7 +258,7 @@ export const _acceptOwnership = async (client) => {
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return client.writeContract({
+    return writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
         account: client.account.address,