kokio-sdk 3.3.0 → 3.5.0

package/README.md

@@ -249,10 +249,14 @@ const { factoryAddresses, chain, rpcURL } = await kokio.constants;
 ```
 
 The SDK resolves these from the wallet client's connected chain id, so you do not
-pass addresses yourself. Base Sepolia (chain id `84532`) is the only chain with a
-live deployment today. Ethereum, Optimism, and Arbitrum (mainnet and their
-testnets) are wired into the chain-resolution logic but not yet deployed;
-connecting to one of them throws `UnconfiguredChainError` until it is.
+pass addresses yourself.
+
+| Chain | Chain id | EntryPoint |
+|---|---|---|
+| Base mainnet | `8453` | v0.8, `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` |
+| Base Sepolia | `84532` | v0.8, `0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108` |
+
+Any other chain id throws `UnsupportedChainError`. The contract addresses for each chain are in `src/logic/constants.ts`, taken from the deployment records in `smart-contract-suite/deployments/`.
 
 ## Testing
 

package/dist/esm/abis/DeviceWallet.js

@@ -453,6 +453,25 @@ const DeviceWallet = [
         "outputs": [],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "rotationChallenge",
+        "inputs": [
+            {
+                "name": "newOwner",
+                "type": "bytes32[2]",
+                "internalType": "bytes32[2]"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "",
+                "type": "bytes",
+                "internalType": "bytes"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "supportsInterface",
@@ -498,6 +517,11 @@ const DeviceWallet = [
                 "name": "newOwner",
                 "type": "bytes32[2]",
                 "internalType": "bytes32[2]"
+            },
+            {
+                "name": "newOwnerSignature",
+                "type": "bytes",
+                "internalType": "bytes"
             }
         ],
         "outputs": [
@@ -838,6 +862,11 @@ const DeviceWallet = [
         "name": "InvalidInitialization",
         "inputs": []
     },
+    {
+        "type": "error",
+        "name": "NewOwnerKeyCannotSign",
+        "inputs": []
+    },
     {
         "type": "error",
         "name": "NotInitializing",

package/dist/esm/abis/ESIMWallet.js

@@ -10,6 +10,19 @@ const ESIMWallet = [
         "outputs": [],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "adminAllowanceUSDCents",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint64",
+                "internalType": "uint64"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "buyDataBundleWithToken",
@@ -286,6 +299,19 @@ const ESIMWallet = [
         ],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "setAdminAllowanceUSDCents",
+        "inputs": [
+            {
+                "name": "_allowance",
+                "type": "uint64",
+                "internalType": "uint64"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
     {
         "type": "function",
         "name": "setESIMUniqueIdentifier",
@@ -354,6 +380,19 @@ const ESIMWallet = [
         "outputs": [],
         "stateMutability": "pure"
     },
+    {
+        "type": "event",
+        "name": "AdminAllowanceUSDCentsUpdated",
+        "inputs": [
+            {
+                "name": "_allowance",
+                "type": "uint64",
+                "indexed": false,
+                "internalType": "uint64"
+            }
+        ],
+        "anonymous": false
+    },
     {
         "type": "event",
         "name": "DataBundleBoughtWithToken",
@@ -623,6 +662,22 @@ const ESIMWallet = [
         ],
         "anonymous": false
     },
+    {
+        "type": "error",
+        "name": "AdminAllowanceExceeded",
+        "inputs": [
+            {
+                "name": "priceUSDCents",
+                "type": "uint64",
+                "internalType": "uint64"
+            },
+            {
+                "name": "remaining",
+                "type": "uint64",
+                "internalType": "uint64"
+            }
+        ]
+    },
     {
         "type": "error",
         "name": "AssetNotTransferable",

package/dist/esm/abis/PaymentAdapter.js

@@ -152,6 +152,29 @@ const PaymentAdapter = [
         ],
         "stateMutability": "view"
     },
+    {
+        "type": "function",
+        "name": "recoverTokens",
+        "inputs": [
+            {
+                "name": "_token",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "_to",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "_amount",
+                "type": "uint256",
+                "internalType": "uint256"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
     {
         "type": "function",
         "name": "registerAsset",
@@ -571,6 +594,31 @@ const PaymentAdapter = [
         ],
         "anonymous": false
     },
+    {
+        "type": "event",
+        "name": "TokensRecovered",
+        "inputs": [
+            {
+                "name": "_token",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            },
+            {
+                "name": "_to",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            },
+            {
+                "name": "_amount",
+                "type": "uint256",
+                "indexed": false,
+                "internalType": "uint256"
+            }
+        ],
+        "anonymous": false
+    },
     {
         "type": "event",
         "name": "Upgraded",
@@ -852,6 +900,11 @@ const PaymentAdapter = [
             }
         ]
     },
+    {
+        "type": "error",
+        "name": "ZeroAmount",
+        "inputs": []
+    },
     {
         "type": "error",
         "name": "ZeroDataBundlePrice",

package/dist/esm/abis/ProtocolAdmin.js

@@ -582,6 +582,19 @@ const ProtocolAdmin = [
         ],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "pauseInstantly",
+        "inputs": [
+            {
+                "name": "target",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
     {
         "type": "function",
         "name": "renounceRole",
@@ -959,6 +972,25 @@ const ProtocolAdmin = [
         ],
         "anonymous": false
     },
+    {
+        "type": "event",
+        "name": "PauseRaised",
+        "inputs": [
+            {
+                "name": "target",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            },
+            {
+                "name": "guardian",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            }
+        ],
+        "anonymous": false
+    },
     {
         "type": "event",
         "name": "PauseReleased",
@@ -1105,6 +1137,22 @@ const ProtocolAdmin = [
         "name": "NoProposers",
         "inputs": []
     },
+    {
+        "type": "error",
+        "name": "NomineeIsTheIncumbent",
+        "inputs": [
+            {
+                "name": "target",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "admin",
+                "type": "address",
+                "internalType": "address"
+            }
+        ]
+    },
     {
         "type": "error",
         "name": "NotACanceller",

package/dist/esm/abis/Registry.js

@@ -151,6 +151,19 @@ const Registry = [
         "outputs": [],
         "stateMutability": "nonpayable"
     },
+    {
+        "type": "function",
+        "name": "defaultAdminAllowanceUSDCents",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint64",
+                "internalType": "uint64"
+            }
+        ],
+        "stateMutability": "view"
+    },
     {
         "type": "function",
         "name": "defaultPriceCapUSDCents",
@@ -394,6 +407,11 @@ const Registry = [
                 "name": "_defaultPriceCapUSDCents",
                 "type": "uint64",
                 "internalType": "uint64"
+            },
+            {
+                "name": "_defaultAdminAllowanceUSDCents",
+                "type": "uint64",
+                "internalType": "uint64"
             }
         ],
         "outputs": [],
@@ -749,6 +767,19 @@ const Registry = [
         "outputs": [],
         "stateMutability": "view"
     },
+    {
+        "type": "function",
+        "name": "setDefaultAdminAllowanceUSDCents",
+        "inputs": [
+            {
+                "name": "_allowance",
+                "type": "uint64",
+                "internalType": "uint64"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
     {
         "type": "function",
         "name": "setDefaultPriceCapUSDCents",
@@ -1094,6 +1125,19 @@ const Registry = [
         ],
         "anonymous": false
     },
+    {
+        "type": "event",
+        "name": "DefaultAdminAllowanceUSDCentsUpdated",
+        "inputs": [
+            {
+                "name": "_allowance",
+                "type": "uint64",
+                "indexed": false,
+                "internalType": "uint64"
+            }
+        ],
+        "anonymous": false
+    },
     {
         "type": "event",
         "name": "DefaultPriceCapUSDCentsUpdated",
@@ -1719,6 +1763,17 @@ const Registry = [
             }
         ]
     },
+    {
+        "type": "error",
+        "name": "OwnerKeyNotHeldByWallet",
+        "inputs": [
+            {
+                "name": "deviceWallet",
+                "type": "address",
+                "internalType": "address"
+            }
+        ]
+    },
     {
         "type": "error",
         "name": "OwnershipCannotBeRenounced",

package/dist/esm/abis/RegistryHelper.js

@@ -495,6 +495,19 @@ const RegistryHelper = [
         ],
         "anonymous": false
     },
+    {
+        "type": "event",
+        "name": "DefaultAdminAllowanceUSDCentsUpdated",
+        "inputs": [
+            {
+                "name": "_allowance",
+                "type": "uint64",
+                "indexed": false,
+                "internalType": "uint64"
+            }
+        ],
+        "anonymous": false
+    },
     {
         "type": "event",
         "name": "DefaultPriceCapUSDCentsUpdated",

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

@@ -12,10 +12,12 @@ import { AdminUtilsSubPackage } from "./interface/utilsClass.js";
 // Re-export the typed error surface so backend consumers can `instanceof
 // KokioError` (or a subclass) and decode reverts without reaching into internal
 // module paths - mirroring `config.ts`.
-export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, StalledBatchError, InvalidAddressError, InvalidSymbolError, TokenNotAcceptedError, NotAProtocolESIMWalletError, UnknownTransactionError, TransactionRevertedError, ReceiptNotCanonicalError, NotAnERC20TokenError, UnmatchedPaymentEventsError, PriceOutOfRangeError, ContractRevertError, decodeContractRevert, } from "../logic/errors.js";
+export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, StalledBatchError, InvalidAddressError, InvalidSymbolError, TokenNotAcceptedError, NotAProtocolESIMWalletError, UnknownTransactionError, TransactionRevertedError, ReceiptNotCanonicalError, NotAnERC20TokenError, UnmatchedPaymentEventsError, PriceOutOfRangeError, AdminAllowanceExceededError, InvalidPaymentReferenceError, CouponSplitOutOfRangeError, ContractRevertError, decodeContractRevert, } from "../logic/errors.js";
 // `getOperationState` answers with this, and comparing against it needs the enum
 // at runtime rather than only in the types.
 export { OperationState } from "../logic/admin/reads/protocolAdmin.reads.js";
+// Passed to `utils.tagPaymentReference` and returned by `utils.parsePaymentReference`.
+export { PaymentReferenceKind } from "../logic/admin/utils/paymentReference.js";
 /**
  * EOA-only entry point for the NodeJS backend.
  *

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

@@ -1,5 +1,5 @@
 import { _buyDataBundleWithToken } from "../../logic/admin/eSIMWallet.eoa.js";
-import { _eSIMWalletFactory, _eSIMUniqueIdentifier, _newRequestedOwner, _owner, _priceCapUSDCents, _deviceWallet, _transactionHistory, } from "../../logic/admin/reads/eSIMWallet.reads.js";
+import { _adminAllowanceUSDCents, _eSIMWalletFactory, _eSIMUniqueIdentifier, _newRequestedOwner, _owner, _priceCapUSDCents, _deviceWallet, _transactionHistory, } from "../../logic/admin/reads/eSIMWallet.reads.js";
 /**
  * Thin EOA wrapper around a specific `ESIMWallet` instance. The instance address
  * is bound at construction; `KokioAdmin.setESIMWalletAddress` swaps it by
@@ -31,6 +31,9 @@ export class AdminESIMWalletSubPackage {
     priceCapUSDCents() {
         return _priceCapUSDCents(this.walletClient, this.eSIMWalletAddress);
     }
+    adminAllowanceUSDCents() {
+        return _adminAllowanceUSDCents(this.walletClient, this.eSIMWalletAddress);
+    }
     deviceWallet() {
         return _deviceWallet(this.walletClient, this.eSIMWalletAddress);
     }

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

@@ -1,5 +1,5 @@
 import { _registry, _settlementToken, _assets, _resolveAsset, _quote, _usedReferences, _upgradeManager } from "../../logic/admin/reads/paymentAdapter.reads.js";
-import { _registerAsset, _updateAsset, _registerAssetCall, _updateAssetCall, _transferOwnershipCall, _upgradeCall, _acceptOwnership } from "../../logic/admin/paymentAdapter.eoa.js";
+import { _registerAsset, _updateAsset, _registerAssetCall, _updateAssetCall, _recoverTokensCall, _transferOwnershipCall, _upgradeCall, _acceptOwnership } from "../../logic/admin/paymentAdapter.eoa.js";
 export class AdminPaymentAdapterSubPackage {
     walletClient;
     constructor(walletClient) {
@@ -42,6 +42,9 @@ export class AdminPaymentAdapterSubPackage {
     registerAssetCall(symbol, asset) {
         return _registerAssetCall(this.walletClient, symbol, asset);
     }
+    recoverTokensCall(token, to, amount) {
+        return _recoverTokensCall(this.walletClient, token, to, amount);
+    }
     updateAssetCall(symbol, asset) {
         return _updateAssetCall(this.walletClient, symbol, asset);
     }

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

@@ -1,4 +1,4 @@
-import { _operationId, _operationIdBatch, _operationIdRaw, _operationIdBatchRaw, _schedule, _scheduleBatch, _scheduleRaw, _execute, _executeBatch, _executeRaw, _cancel, _unpauseInstantly, _revokeCancellersInstantly, _disableAdminInstantly, _acceptOwnershipBatch, _renounceRole, _grantRoleCall, _revokeRoleCall, _updateDelayCall, _disableAndNominateCall, _disableAdminCall, _enableAdminCall, _unpauseCall, _setDefaultPriceCapUSDCentsCall, _setPaymentAdapterCall, } from "../../logic/admin/protocolAdmin.eoa.js";
+import { _operationId, _operationIdBatch, _operationIdRaw, _operationIdBatchRaw, _schedule, _scheduleBatch, _scheduleRaw, _execute, _executeBatch, _executeRaw, _cancel, _pauseInstantly, _unpauseInstantly, _revokeCancellersInstantly, _disableAdminInstantly, _acceptOwnershipBatch, _renounceRole, _grantRoleCall, _revokeRoleCall, _updateDelayCall, _disableAndNominateCall, _disableAdminCall, _enableAdminCall, _unpauseCall, _setDefaultPriceCapUSDCentsCall, _setDefaultAdminAllowanceUSDCentsCall, _setPaymentAdapterCall, } from "../../logic/admin/protocolAdmin.eoa.js";
 import { _getMinDelay, _minDelayFloor, _getOperationState, _getTimestamp, _isOperation, _isOperationPending, _isOperationReady, _isOperationDone, _hasRole, _getRoleAdmin, _defaultAdminRole, _proposerRole, _cancellerRole, _executorRole, _guardianRole, } from "../../logic/admin/reads/protocolAdmin.reads.js";
 /** Schedules operations. Needs an EOA holding `PROPOSER_ROLE`. */
 export class ProtocolAdminProposerSubPackage {
@@ -55,6 +55,9 @@ export class ProtocolAdminGuardianSubPackage {
     constructor(walletClient) {
         this.walletClient = walletClient;
     }
+    pauseInstantly(target) {
+        return _pauseInstantly(this.walletClient, target);
+    }
     unpauseInstantly(target) {
         return _unpauseInstantly(this.walletClient, target);
     }
@@ -132,6 +135,9 @@ export class AdminProtocolAdminSubPackage {
     setDefaultPriceCapUSDCentsCall(cap, target) {
         return _setDefaultPriceCapUSDCentsCall(this.walletClient, cap, target);
     }
+    setDefaultAdminAllowanceUSDCentsCall(allowance, target) {
+        return _setDefaultAdminAllowanceUSDCentsCall(this.walletClient, allowance, target);
+    }
     setPaymentAdapterCall(paymentAdapter, target) {
         return _setPaymentAdapterCall(this.walletClient, paymentAdapter, target);
     }

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

@@ -1,5 +1,5 @@
 import { _addOrUpdateLazyWalletRegistryAddress, _updateVaultAddress, _requestAdminUpdate, _disableAdmin, _enableAdmin, _acceptAdminUpdate, _assignESIMIdentifier, _recordSettledPurchase, _pause, _unpause, _setDefaultPriceCapUSDCents, _acceptOwnership, _transferOwnershipCall, _upgradeCall, } from "../../logic/admin/registry.eoa.js";
-import { _owner, _eSIMWalletAdmin, _adminOfRecord, _adminDisabled, _newRequestedAdmin, _vault, _upgradeManager, _lazyWalletRegistry, _uniqueIdentifierToDeviceWallet, _deviceWalletToOwner, _registeredP256Keys, _isDeviceWalletValid, _isESIMWalletValid, _isESIMWalletOnStandby, _paused, _defaultPriceCapUSDCents, _paymentAdapter, _usedPaymentReferences, _isDeviceIdentifierAlreadyUsed, _isESIMIdentifierClaimed, _eSIMWalletForIdentifier, _claimedESIMIdentifiers, _requireDeviceIdentifierNotReserved, _pendingOwner, _deviceWalletFactory, _eSIMWalletFactory, _entryPoint, _requireNotPaused, _proxiableUUID, _upgradeInterfaceVersion, } from "../../logic/admin/reads/registry.reads.js";
+import { _owner, _eSIMWalletAdmin, _adminOfRecord, _adminDisabled, _newRequestedAdmin, _vault, _upgradeManager, _lazyWalletRegistry, _uniqueIdentifierToDeviceWallet, _deviceWalletToOwner, _registeredP256Keys, _isDeviceWalletValid, _isESIMWalletValid, _isESIMWalletOnStandby, _paused, _defaultPriceCapUSDCents, _defaultAdminAllowanceUSDCents, _paymentAdapter, _usedPaymentReferences, _isDeviceIdentifierAlreadyUsed, _isESIMIdentifierClaimed, _eSIMWalletForIdentifier, _claimedESIMIdentifiers, _requireDeviceIdentifierNotReserved, _pendingOwner, _deviceWalletFactory, _eSIMWalletFactory, _entryPoint, _requireNotPaused, _proxiableUUID, _upgradeInterfaceVersion, } from "../../logic/admin/reads/registry.reads.js";
 /** Thin EOA (owner) wrapper around `Registry`. */
 export class AdminRegistrySubPackage {
     walletClient;
@@ -24,8 +24,8 @@ export class AdminRegistrySubPackage {
     acceptAdminUpdate() {
         return _acceptAdminUpdate(this.walletClient);
     }
-    recordSettledPurchase(eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference) {
-        return _recordSettledPurchase(this.walletClient, eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference);
+    recordSettledPurchase(eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference, couponUSDCents) {
+        return _recordSettledPurchase(this.walletClient, eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference, couponUSDCents);
     }
     assignESIMIdentifier(eSIMWalletAddress, eSIMUniqueIdentifier) {
         return _assignESIMIdentifier(this.walletClient, eSIMWalletAddress, eSIMUniqueIdentifier);
@@ -98,6 +98,9 @@ export class AdminRegistrySubPackage {
     defaultPriceCapUSDCents() {
         return _defaultPriceCapUSDCents(this.walletClient);
     }
+    defaultAdminAllowanceUSDCents() {
+        return _defaultAdminAllowanceUSDCents(this.walletClient);
+    }
     paymentAdapter() {
         return _paymentAdapter(this.walletClient);
     }

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

@@ -1,8 +1,9 @@
 import { _verifyERC20Transfer, _verifyProtocolPayment } from "../../logic/admin/utils/tokenTransfer.js";
+import { _parsePaymentReference, _tagPaymentReference, } from "../../logic/admin/utils/paymentReference.js";
 /**
- * Checks what a mined transaction actually paid. Nothing is sent. Pass a hash
- * when it came from a user: a receipt is used as given, so it must come from
- * your own node.
+ * Checks what a mined transaction actually paid, and builds and reads payment
+ * references. Nothing is sent. Pass a hash when it came from a user: a receipt
+ * is used as given, so it must come from your own node.
  */
 export class AdminUtilsSubPackage {
     walletClient;
@@ -24,4 +25,19 @@ export class AdminUtilsSubPackage {
     verifyERC20Transfer(transaction, token, sender, destination) {
         return _verifyERC20Transfer(this.walletClient, transaction, token, sender, destination);
     }
+    /**
+     * Marks `reference` with how the purchase was paid for. Its high 20 bytes
+     * must be zero. For a split purchase, tag the same reference once as
+     * `CouponPart` and once as `Remainder`.
+     */
+    tagPaymentReference(reference, kind) {
+        return _tagPaymentReference(reference, kind);
+    }
+    /**
+     * How a purchase was paid for, and the untagged reference it was built
+     * from. Throws on a tag this SDK did not write.
+     */
+    parsePaymentReference(reference) {
+        return _parsePaymentReference(reference);
+    }
 }

package/dist/esm/interface/deviceWalletClass.js

@@ -1,4 +1,4 @@
-import { _addDeposit, _addESIMWallet, _canPullFunds, _deployAndBindESIMWallet, _deviceUniqueIdentifier, _entryPoint, _eSIMWalletFactory, _getDeposit, _getOwner, _getVaultAddress, _isValidESIMWallet, _isValidSignature, _registry, _removeESIMWallet, _sendUserOperation, _toggleAccessToFunds, _transferOwnership, _verifier, _withdrawDepositTo } from "../logic/deviceWallet.js";
+import { _addDeposit, _addESIMWallet, _canPullFunds, _deployAndBindESIMWallet, _deviceUniqueIdentifier, _entryPoint, _eSIMWalletFactory, _getDeposit, _getOwner, _getVaultAddress, _isValidESIMWallet, _isValidSignature, _registry, _removeESIMWallet, _rotationChallenge, _sendUserOperation, _toggleAccessToFunds, _transferOwnership, _verifier, _withdrawDepositTo } from "../logic/deviceWallet.js";
 export class DeviceWalletSubPackage {
     smartAccountClient;
     walletClient;
@@ -35,8 +35,8 @@ export class DeviceWalletSubPackage {
     toggleAccessToFunds(eSIMWalletAddress, hasAccessToFunds) {
         return _toggleAccessToFunds(this.smartAccountClient, this.address, eSIMWalletAddress, hasAccessToFunds);
     }
-    transferOwnership(newOwner) {
-        return _transferOwnership(this.smartAccountClient, this.address, newOwner);
+    transferOwnership(newOwner, newOwnerSignature) {
+        return _transferOwnership(this.smartAccountClient, this.address, newOwner, newOwnerSignature);
     }
     withdrawDepositTo(withdrawAddress, amount) {
         return _withdrawDepositTo(this.smartAccountClient, this.address, withdrawAddress, amount);
@@ -69,6 +69,9 @@ export class DeviceWalletSubPackage {
     registry() {
         return _registry(this.smartAccountClient, this.address);
     }
+    rotationChallenge(newOwner) {
+        return _rotationChallenge(this.smartAccountClient, this.address, newOwner);
+    }
     verifier() {
         return _verifier(this.smartAccountClient, this.address);
     }

package/dist/esm/interface/eSIMWalletClass.js

@@ -1,4 +1,4 @@
-import { _acceptAndBindESIMWallet, _acceptOwnershipTransfer, _buyDataBundleWithToken, _buyDataBundleWithTransfer, _priceCapUSDCents, _deviceWallet, _owner, _requestTransferOwnership, _sendETHToDeviceWallet, _sendTokenToDeviceWallet, _setPriceCapUSDCents, _transactionHistory } from "../logic/eSIMWallet.js";
+import { _acceptAndBindESIMWallet, _acceptOwnershipTransfer, _adminAllowanceUSDCents, _buyDataBundleWithToken, _buyDataBundleWithTransfer, _priceCapUSDCents, _deviceWallet, _owner, _requestTransferOwnership, _sendETHToDeviceWallet, _sendTokenToDeviceWallet, _setAdminAllowanceUSDCents, _setPriceCapUSDCents, _transactionHistory } from "../logic/eSIMWallet.js";
 export class ESIMWalletSubPackage {
     client;
     address;
@@ -31,6 +31,12 @@ export class ESIMWalletSubPackage {
     priceCapUSDCents() {
         return _priceCapUSDCents(this.client, this.address);
     }
+    adminAllowanceUSDCents() {
+        return _adminAllowanceUSDCents(this.client, this.address);
+    }
+    setAdminAllowanceUSDCents(allowance) {
+        return _setAdminAllowanceUSDCents(this.client, this.address, allowance);
+    }
     deviceWallet() {
         return _deviceWallet(this.client, this.address);
     }

package/dist/esm/interface/registryClass.js

@@ -1,4 +1,4 @@
-import { _bindESIMWallet, _toggleESIMWalletStandbyStatus, _isDeviceIdentifierAlreadyUsed, _paused, _requireNotPaused, _isESIMWalletValid, _isESIMWalletOnStandby, _isDeviceWalletValid, _uniqueIdentifierToDeviceWallet, _isESIMIdentifierClaimed, _eSIMWalletForIdentifier, _defaultPriceCapUSDCents, _paymentAdapter, _usedPaymentReferences, _requireLazyHistoryCopied, _requireDeviceIdentifierNotReserved } from "../logic/registry.js";
+import { _bindESIMWallet, _toggleESIMWalletStandbyStatus, _isDeviceIdentifierAlreadyUsed, _paused, _requireNotPaused, _isESIMWalletValid, _isESIMWalletOnStandby, _isDeviceWalletValid, _uniqueIdentifierToDeviceWallet, _isESIMIdentifierClaimed, _eSIMWalletForIdentifier, _defaultPriceCapUSDCents, _defaultAdminAllowanceUSDCents, _paymentAdapter, _usedPaymentReferences, _requireLazyHistoryCopied, _requireDeviceIdentifierNotReserved } from "../logic/registry.js";
 export class RegistrySubPackage {
     client;
     constructor(client) {
@@ -49,6 +49,9 @@ export class RegistrySubPackage {
     defaultPriceCapUSDCents() {
         return _defaultPriceCapUSDCents(this.client);
     }
+    defaultAdminAllowanceUSDCents() {
+        return _defaultAdminAllowanceUSDCents(this.client);
+    }
     paymentAdapter() {
         return _paymentAdapter(this.client);
     }

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

@@ -1,6 +1,7 @@
 import { _chainId, _getChainSpecificConstants } from "../constants.js";
-import { MissingEOAWalletError, writeContractOrThrow } from "../errors.js";
+import { AdminAllowanceExceededError, MissingEOAWalletError, writeContractOrThrow } from "../errors.js";
 import { ESIMWallet } from "../../abis/index.js";
+import { _adminAllowanceUSDCents } from "./reads/eSIMWallet.reads.js";
 // Admin-EOA logic targeting a specific `ESIMWallet` instance (address passed in).
 // `buyDataBundleWithToken` is `onlyDeviceWalletOrESIMWalletAdmin`, so the admin
 // EOA can call it directly.
@@ -12,6 +13,9 @@ import { ESIMWallet } from "../../abis/index.js";
  * 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.
+ *
+ * Throws `AdminAllowanceExceededError` without sending when the price is above
+ * what the wallet's owner still allows the admin to charge.
  */
 export const _buyDataBundleWithToken = async (client, eSIMWalletAddress, dataBundleDetails, asset, maxAmountIn, paymentReference) => {
     const chainID = await _chainId(client);
@@ -19,6 +23,10 @@ export const _buyDataBundleWithToken = async (client, eSIMWalletAddress, dataBun
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
+    const remaining = await _adminAllowanceUSDCents(client, eSIMWalletAddress);
+    if (dataBundleDetails.priceUSDCents > remaining) {
+        throw new AdminAllowanceExceededError(dataBundleDetails.priceUSDCents, remaining);
+    }
     return writeContractOrThrow(client, {
         address: eSIMWalletAddress,
         chain: values.chain,

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

@@ -57,6 +57,22 @@ export const _registerAssetCall = async (client, symbol, asset) => {
         args: [symbol, asset],
     };
 };
+/**
+ * Send back `amount` of `token` someone sent to the adapter by mistake. Pass the
+ * result to `schedule`. Purchases never leave tokens in the adapter, so anything
+ * it holds arrived by mistake.
+ */
+export const _recoverTokensCall = async (client, token, to, amount) => {
+    const chainID = await _chainId(client);
+    const rpcURL = client.transport.url;
+    const values = _getChainSpecificConstants(chainID, rpcURL);
+    return {
+        address: values.factoryAddresses.PAYMENT_ADAPTER,
+        abi: PaymentAdapter,
+        functionName: 'recoverTokens',
+        args: [token, to, amount],
+    };
+};
 /** Change a currency already in the table, scheduled through the timelock. Pass the result to `schedule`. */
 export const _updateAssetCall = async (client, symbol, asset) => {
     const chainID = await _chainId(client);