kokio-sdk 3.3.0 → 3.5.0

package/dist/types/abis/ProtocolAdmin.d.ts

@@ -443,6 +443,16 @@ declare const ProtocolAdmin: readonly [{
         readonly internalType: "bytes4";
     }];
     readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "pauseInstantly";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "function";
     readonly name: "renounceRole";
@@ -740,6 +750,21 @@ declare const ProtocolAdmin: readonly [{
         readonly internalType: "address";
     }];
     readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "PauseRaised";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }, {
+        readonly name: "guardian";
+        readonly type: "address";
+        readonly indexed: true;
+        readonly internalType: "address";
+    }];
+    readonly anonymous: false;
 }, {
     readonly type: "event";
     readonly name: "PauseReleased";
@@ -855,6 +880,18 @@ declare const ProtocolAdmin: readonly [{
     readonly type: "error";
     readonly name: "NoProposers";
     readonly inputs: readonly [];
+}, {
+    readonly type: "error";
+    readonly name: "NomineeIsTheIncumbent";
+    readonly inputs: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+        readonly internalType: "address";
+    }, {
+        readonly name: "admin";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
 }, {
     readonly type: "error";
     readonly name: "NotACanceller";

package/dist/types/abis/Registry.d.ts

@@ -114,6 +114,16 @@ declare const Registry: readonly [{
     }];
     readonly outputs: readonly [];
     readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "defaultAdminAllowanceUSDCents";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }];
+    readonly stateMutability: "view";
 }, {
     readonly type: "function";
     readonly name: "defaultPriceCapUSDCents";
@@ -303,6 +313,10 @@ declare const Registry: readonly [{
         readonly name: "_defaultPriceCapUSDCents";
         readonly type: "uint64";
         readonly internalType: "uint64";
+    }, {
+        readonly name: "_defaultAdminAllowanceUSDCents";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
     }];
     readonly outputs: readonly [];
     readonly stateMutability: "nonpayable";
@@ -574,6 +588,16 @@ declare const Registry: readonly [{
     readonly inputs: readonly [];
     readonly outputs: readonly [];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "setDefaultAdminAllowanceUSDCents";
+    readonly inputs: readonly [{
+        readonly name: "_allowance";
+        readonly type: "uint64";
+        readonly internalType: "uint64";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
 }, {
     readonly type: "function";
     readonly name: "setDefaultPriceCapUSDCents";
@@ -843,6 +867,16 @@ declare const Registry: readonly [{
         readonly internalType: "bytes32";
     }];
     readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "DefaultAdminAllowanceUSDCentsUpdated";
+    readonly inputs: readonly [{
+        readonly name: "_allowance";
+        readonly type: "uint64";
+        readonly indexed: false;
+        readonly internalType: "uint64";
+    }];
+    readonly anonymous: false;
 }, {
     readonly type: "event";
     readonly name: "DefaultPriceCapUSDCentsUpdated";
@@ -1326,6 +1360,14 @@ declare const Registry: readonly [{
         readonly type: "bytes32";
         readonly internalType: "bytes32";
     }];
+}, {
+    readonly type: "error";
+    readonly name: "OwnerKeyNotHeldByWallet";
+    readonly inputs: readonly [{
+        readonly name: "deviceWallet";
+        readonly type: "address";
+        readonly internalType: "address";
+    }];
 }, {
     readonly type: "error";
     readonly name: "OwnershipCannotBeRenounced";

package/dist/types/abis/RegistryHelper.d.ts

@@ -378,6 +378,16 @@ declare const RegistryHelper: readonly [{
         readonly internalType: "bytes32";
     }];
     readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "DefaultAdminAllowanceUSDCentsUpdated";
+    readonly inputs: readonly [{
+        readonly name: "_allowance";
+        readonly type: "uint64";
+        readonly indexed: false;
+        readonly internalType: "uint64";
+    }];
+    readonly anonymous: false;
 }, {
     readonly type: "event";
     readonly name: "DefaultPriceCapUSDCentsUpdated";

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

@@ -10,9 +10,10 @@ import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { AdminPaymentAdapterSubPackage } from "./interface/paymentAdapterClass.js";
 import { AdminCallsSubPackage } from "./interface/callsClass.js";
 import { AdminUtilsSubPackage } from "./interface/utilsClass.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, 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";
 export type { DecodedRevert } from "../logic/errors.js";
 export { OperationState } from "../logic/admin/reads/protocolAdmin.reads.js";
+export { PaymentReferenceKind } from "../logic/admin/utils/paymentReference.js";
 /**
  * EOA-only entry point for the NodeJS backend.
  *

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

@@ -15,6 +15,7 @@ export declare class AdminESIMWalletSubPackage {
     newRequestedOwner(): Promise<`0x${string}`>;
     owner(): Promise<`0x${string}`>;
     priceCapUSDCents(): Promise<bigint>;
+    adminAllowanceUSDCents(): Promise<bigint>;
     deviceWallet(): Promise<`0x${string}`>;
     transactionHistory(index: bigint): Promise<DataBundleDetails>;
 }

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

@@ -14,6 +14,7 @@ export declare class AdminPaymentAdapterSubPackage {
     updateAsset(symbol: Hex, asset: Asset): Promise<`0x${string}`>;
     acceptOwnership(): Promise<`0x${string}`>;
     registerAssetCall(symbol: Hex, asset: Asset): Promise<import("../../types.js").OwnerCall>;
+    recoverTokensCall(token: Address, to: Address, amount: bigint): Promise<import("../../types.js").OwnerCall>;
     updateAssetCall(symbol: Hex, asset: Asset): Promise<import("../../types.js").OwnerCall>;
     transferOwnershipCall(newOwner: Address): Promise<import("../../types.js").OwnerCall>;
     upgradeCall(newImplementation: Address, data?: Hex): Promise<import("../../types.js").OwnerCall>;

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

@@ -33,6 +33,7 @@ export declare class ProtocolAdminCancellerSubPackage {
 export declare class ProtocolAdminGuardianSubPackage {
     walletClient: WalletClient;
     constructor(walletClient: WalletClient);
+    pauseInstantly(target: Address): Promise<`0x${string}`>;
     unpauseInstantly(target: Address): Promise<`0x${string}`>;
     revokeCancellersInstantly(accounts: readonly Address[]): Promise<`0x${string}`>;
     disableAdminInstantly(target?: Address): Promise<`0x${string}`>;
@@ -73,6 +74,7 @@ export declare class AdminProtocolAdminSubPackage {
     enableAdminCall(target?: Address): Promise<OwnerCall>;
     unpauseCall(target?: Address): Promise<OwnerCall>;
     setDefaultPriceCapUSDCentsCall(cap: bigint, target?: Address): Promise<OwnerCall>;
+    setDefaultAdminAllowanceUSDCentsCall(allowance: bigint, target?: Address): Promise<OwnerCall>;
     setPaymentAdapterCall(paymentAdapter: Address, target?: Address): Promise<OwnerCall>;
     operationId(call: OwnerCall, opts?: OperationOptions): Promise<`0x${string}`>;
     operationIdBatch(calls: readonly OwnerCall[], opts?: OperationOptions): Promise<`0x${string}`>;

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

@@ -10,7 +10,19 @@ export declare class AdminRegistrySubPackage {
     disableAdmin(): Promise<`0x${string}`>;
     enableAdmin(): Promise<`0x${string}`>;
     acceptAdminUpdate(): Promise<`0x${string}`>;
-    recordSettledPurchase(eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReference: Hex): Promise<`0x${string}`>;
+    /**
+     * Records a purchase paid for by card or an external wallet, or one line of
+     * a coupon purchase. One transaction.
+     */
+    recordSettledPurchase(eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReference: Hex): Promise<Hex>;
+    /**
+     * Records a purchase split between a coupon and a card or external wallet
+     * payment, as two lines. `dataBundleDetail` carries the full price and how
+     * the remainder was paid; `asset` and `tokenAmount` are what the user paid
+     * for the remainder. Lines already recorded are skipped. Returns the hash
+     * of the last transaction sent; any earlier one is already mined.
+     */
+    recordSettledPurchase(eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReferences: readonly [couponRef: Hex, remainderRef: Hex], couponUSDCents: bigint): Promise<Hex>;
     assignESIMIdentifier(eSIMWalletAddress: Address, eSIMUniqueIdentifier: string): Promise<`0x${string}`>;
     pause(): Promise<`0x${string}`>;
     unpause(): Promise<`0x${string}`>;
@@ -34,6 +46,7 @@ export declare class AdminRegistrySubPackage {
     isESIMWalletOnStandby(eSIMWallet: Address): Promise<boolean>;
     paused(): Promise<boolean>;
     defaultPriceCapUSDCents(): Promise<bigint>;
+    defaultAdminAllowanceUSDCents(): Promise<bigint>;
     paymentAdapter(): Promise<`0x${string}`>;
     usedPaymentReferences(scopedReference: Hex): Promise<boolean>;
     isDeviceIdentifierAlreadyUsed(deviceUniqueIdentifier: string): Promise<boolean>;

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

@@ -1,8 +1,9 @@
-import { Address, Hash, TransactionReceipt, WalletClient } from "viem";
+import { Address, Hash, Hex, TransactionReceipt, WalletClient } from "viem";
+import { PaymentReferenceKind } 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 declare class AdminUtilsSubPackage {
     walletClient: WalletClient;
@@ -18,4 +19,18 @@ export declare class AdminUtilsSubPackage {
      * one token as one dollar, so they mean nothing for a token that is not.
      */
     verifyERC20Transfer(transaction: Hash | TransactionReceipt, token: Address, sender: Address, destination: Address): Promise<import("../../types.js").ERC20TransferCheck>;
+    /**
+     * 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: Hex, kind: PaymentReferenceKind): `0x${string}`;
+    /**
+     * 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: Hex): {
+        kind: PaymentReferenceKind;
+        reference: Hex;
+    };
 }

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

@@ -23,7 +23,7 @@ export declare class DeviceWalletSubPackage {
     getVaultAddress(): Promise<`0x${string}`>;
     removeESIMWallet(eSIMWalletAddress: Address, callBackETH: boolean): Promise<`0x${string}`>;
     toggleAccessToFunds(eSIMWalletAddress: Address, hasAccessToFunds: boolean): Promise<`0x${string}`>;
-    transferOwnership(newOwner: P256Key): Promise<`0x${string}`>;
+    transferOwnership(newOwner: P256Key, newOwnerSignature: Hex): Promise<`0x${string}`>;
     withdrawDepositTo(withdrawAddress: Address, amount: bigint): Promise<`0x${string}`>;
     canPullFunds(eSIMWalletAddress: Address): Promise<boolean>;
     deviceUniqueIdentifier(): Promise<string>;
@@ -34,5 +34,6 @@ export declare class DeviceWalletSubPackage {
     isValidESIMWallet(eSIMWalletAddress: Address): Promise<boolean>;
     isValidSignature(messageHash: Hex, signature: Hex): Promise<`0x${string}`>;
     registry(): Promise<`0x${string}`>;
+    rotationChallenge(newOwner: P256Key): Promise<`0x${string}`>;
     verifier(): Promise<`0x${string}`>;
 }

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

@@ -22,6 +22,8 @@ export declare class ESIMWalletSubPackage {
      */
     buyDataBundleWithTransfer(dataBundleDetails: DataBundleDetails, asset: Hex, maxAmountIn: bigint, paymentReference: Hex): Promise<`0x${string}`>;
     priceCapUSDCents(): Promise<bigint>;
+    adminAllowanceUSDCents(): Promise<bigint>;
+    setAdminAllowanceUSDCents(allowance: bigint): Promise<`0x${string}`>;
     deviceWallet(): Promise<`0x${string}`>;
     owner(): Promise<`0x${string}`>;
     requestTransferOwnership(newOwner: Address): Promise<`0x${string}`>;

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

@@ -23,6 +23,7 @@ export declare class RegistrySubPackage {
     isESIMIdentifierClaimed(eSIMUniqueIdentifier: string): Promise<boolean>;
     eSIMWalletForIdentifier(eSIMUniqueIdentifier: string): Promise<`0x${string}`>;
     defaultPriceCapUSDCents(): Promise<bigint>;
+    defaultAdminAllowanceUSDCents(): Promise<bigint>;
     paymentAdapter(): Promise<`0x${string}`>;
     usedPaymentReferences(scopedReference: Hex): Promise<boolean>;
     requireLazyHistoryCopied(eSIMWallet: Address): Promise<void>;

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

@@ -8,5 +8,8 @@ import { DataBundleDetails } from "../../types.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 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

@@ -6,6 +6,12 @@ export declare const _registerAsset: (client: WalletClient, symbol: Hex, asset:
 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>;
+/**
+ * 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 declare const _recoverTokensCall: (client: WalletClient, token: Address, to: Address, amount: bigint) => 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>;
 /**

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

@@ -57,6 +57,13 @@ export declare const _executeRaw: (client: WalletClient, target: Address, value:
  * proposer also holds.
  */
 export declare const _cancel: (client: WalletClient, id: Hex) => Promise<`0x${string}`>;
+/**
+ * Pause a protocol contract straight away. `GUARDIAN_ROLE`.
+ *
+ * Only stops the contract, which the admin key could already do, and a guardian
+ * can release it at once with `_unpauseInstantly`.
+ */
+export declare const _pauseInstantly: (client: WalletClient, target: Address) => Promise<`0x${string}`>;
 /**
  * Release a pause on a protocol contract straight away. `GUARDIAN_ROLE`.
  *
@@ -138,6 +145,13 @@ export declare const _unpauseCall: (client: WalletClient, target?: Address) => P
  * `target` defaults to the registry.
  */
 export declare const _setDefaultPriceCapUSDCentsCall: (client: WalletClient, cap: bigint, target?: Address) => Promise<OwnerCall>;
+/**
+ * Set what the admin key may charge each newly created eSIM wallet, in USD
+ * cents. Pass the result to `schedule`. Existing wallets keep their own figure.
+ *
+ * `target` defaults to the registry.
+ */
+export declare const _setDefaultAdminAllowanceUSDCentsCall: (client: WalletClient, allowance: bigint, target?: Address) => Promise<OwnerCall>;
 /**
  * Point the registry at a new payment adapter. Pass the result to `schedule`.
  *

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

@@ -11,6 +11,11 @@ export declare const _eSIMUniqueIdentifier: (client: WalletClient, eSIMWalletAdd
  * `buyDataBundleWithToken`, since a price over the ceiling reverts.
  */
 export declare const _priceCapUSDCents: (client: WalletClient, eSIMWalletAddress: Address) => Promise<bigint>;
+/**
+ * What the admin key may still charge this eSIM wallet, in USD cents. Only the
+ * owner can raise it, so a purchase above it needs the user first.
+ */
+export declare const _adminAllowanceUSDCents: (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. */

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

@@ -27,6 +27,8 @@ export declare const _paused: (client: WalletClient) => Promise<boolean>;
  * cap of its own. Never zero.
  */
 export declare const _defaultPriceCapUSDCents: (client: WalletClient) => Promise<bigint>;
+/** What the admin key may charge a newly created eSIM wallet in total, in USD cents. */
+export declare const _defaultAdminAllowanceUSDCents: (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). */

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

@@ -1,5 +1,5 @@
 import { Address, Hex, WalletClient } from "viem";
-import type { DataBundleDetails, OwnerCall } from "../../types.js";
+import { type DataBundleDetails, type 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`. */
@@ -72,8 +72,29 @@ export declare const _assignESIMIdentifier: (client: WalletClient, eSIMWalletAdd
  * 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.
+ *
+ * Given `[couponRef, remainderRef]` and `couponUSDCents`, records a purchase
+ * split between a coupon and another payment as two lines, see
+ * {@link _couponSplitLines}. Lines already recorded are skipped, so a retry
+ * after a partial failure sends only what is missing. Returns the last hash
+ * sent; any earlier one is already mined.
+ */
+export declare const _recordSettledPurchase: (client: WalletClient, eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReference: Hex | readonly [Hex, Hex], couponUSDCents?: bigint) => Promise<Hex>;
+/** One `recordSettledPurchase` call's worth of arguments, past the eSIM wallet. */
+export interface SettledLine {
+    dataBundleDetail: DataBundleDetails;
+    asset: Hex;
+    tokenAmount: bigint;
+    paymentReference: Hex;
+}
+/**
+ * Splits one purchase into its remainder line and its coupon line, in that
+ * order. `dataBundleDetail` carries the full price and how the remainder was
+ * paid; `asset` and `tokenAmount` are what the user paid for the remainder.
+ * The coupon line is always `Fiat` in `USD`, with the coupon's cents as its
+ * token amount.
  */
-export declare const _recordSettledPurchase: (client: WalletClient, eSIMWalletAddress: Address, dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, paymentReference: Hex) => Promise<`0x${string}`>;
+export declare const _couponSplitLines: (dataBundleDetail: DataBundleDetails, asset: Hex, tokenAmount: bigint, [couponRef, remainderRef]: readonly [Hex, Hex], couponUSDCents: bigint | undefined) => [remainder: SettledLine, coupon: SettledLine];
 /**
  * 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/admin/utils/paymentReference.d.ts

@@ -0,0 +1,26 @@
+import { Hex } from "viem";
+/** How a purchase was paid for, as written into its payment reference. */
+export declare enum PaymentReferenceKind {
+    /** Paid in full without a coupon. Carries no tag. */
+    Standard = "Standard",
+    /** Paid in full by a coupon. */
+    Coupon = "Coupon",
+    /** The coupon's share of a purchase split between a coupon and another payment. */
+    CouponPart = "CouponPart",
+    /** What the user paid on top of the coupon in a split purchase. */
+    Remainder = "Remainder"
+}
+/**
+ * Writes `kind`'s tag into the high 20 bytes of `reference`, which must be zero
+ * there. Tag both halves of a split purchase from the same reference, so each
+ * spends once onchain and both still point at the same order.
+ */
+export declare const _tagPaymentReference: (reference: Hex, kind: PaymentReferenceKind) => Hex;
+/**
+ * Reads back how a purchase was paid for, and the untagged reference it was
+ * built from. Throws on a tag this SDK did not write.
+ */
+export declare const _parsePaymentReference: (reference: Hex) => {
+    kind: PaymentReferenceKind;
+    reference: Hex;
+};

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

@@ -44,12 +44,12 @@ export declare const _removeESIMWallet: (client: KokioSmartAccountClient, addres
  * Rotate the P256 key that owns this wallet. The registry is told in the same
  * call, so its record of the owner cannot drift from the wallet's.
  *
- * A key that cannot produce a verifiable signature bricks the wallet: this is
- * reachable only through a signed userOp, so there is no rotating back and no
- * reaching the balance afterwards. The contract rejects a key it can tell is
- * unusable, but check the new key can sign before calling.
+ * `newOwnerSignature` is the new passkey's WebAuthn assertion over
+ * `rotationChallenge(newOwner)`, ABI-encoded as a `WebAuthnSignature` with no
+ * version or validUntil header. Without it the contract reverts with
+ * `NewOwnerKeyCannotSign`, so a wallet can only move to a key that can sign.
  */
-export declare const _transferOwnership: (client: KokioSmartAccountClient, address: Address, newOwner: P256Key) => Promise<`0x${string}`>;
+export declare const _transferOwnership: (client: KokioSmartAccountClient, address: Address, newOwner: P256Key, newOwnerSignature: Hex) => Promise<`0x${string}`>;
 /**
  * Top up the gas deposit the EntryPoint holds for this wallet, from the wallet's
  * own balance. Anyone may pay into any account's deposit, so an EOA can do this
@@ -81,6 +81,12 @@ export declare const _canPullFunds: (client: KokioSmartAccountClient, address: A
  * the same owner key's wallet at a different salt.
  */
 export declare const _isValidSignature: (client: KokioSmartAccountClient, address: Address, messageHash: Hex, signature: Hex) => Promise<Hex>;
+/**
+ * The bytes the new passkey must sign before `transferOwnership` accepts it.
+ * Bound to this wallet, this chain and `newOwner`, so it cannot be reused for
+ * another rotation.
+ */
+export declare const _rotationChallenge: (client: KokioSmartAccountClient, address: Address, newOwner: P256Key) => Promise<Hex>;
 /** The registry this wallet reports its ownership changes to. */
 export declare const _registry: (client: KokioSmartAccountClient, address: Address) => Promise<Address>;
 /** The factory that deploys this wallet's eSIM wallets. */

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

@@ -11,6 +11,14 @@ import { KokioSmartAccountClient } from "../types.js";
  * owner has to set it again.
  */
 export declare const _setPriceCapUSDCents: (client: KokioSmartAccountClient, address: Address, cap: bigint) => Promise<`0x${string}`>;
+/**
+ * Set the total the admin key may charge this eSIM wallet, in USD cents. It
+ * replaces what is left rather than adding to it, and zero stops admin charges.
+ *
+ * `onlyDeviceWallet`, so only the user can raise what the admin may spend. A
+ * handover resets it to the registry default.
+ */
+export declare const _setAdminAllowanceUSDCents: (client: KokioSmartAccountClient, address: Address, allowance: bigint) => Promise<`0x${string}`>;
 /**
  * Buy a data bundle in `asset`, an ERC-20 the payment adapter accepts.
  *
@@ -53,6 +61,12 @@ export declare const _owner: (client: KokioSmartAccountClient, address: Address)
  * state is reachable.
  */
 export declare const _priceCapUSDCents: (client: KokioSmartAccountClient, address: Address) => Promise<bigint>;
+/**
+ * What the admin key may still charge this eSIM wallet, in USD cents. Each admin
+ * purchase lowers it and nothing refills it, so the owner tops it up with
+ * `setAdminAllowanceUSDCents`. The owner's own purchases do not touch it.
+ */
+export declare const _adminAllowanceUSDCents: (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.

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

@@ -149,6 +149,33 @@ export declare class PriceOutOfRangeError extends KokioError {
     readonly priceUSDCents: bigint;
     constructor(priceUSDCents: bigint);
 }
+/**
+ * An admin purchase priced above what the eSIM wallet's owner still allows the
+ * admin key to charge. Thrown before sending, since the contract would revert
+ * with `AdminAllowanceExceeded`. The owner raises it with `setAdminAllowanceUSDCents`.
+ */
+export declare class AdminAllowanceExceededError extends KokioError {
+    readonly priceUSDCents: bigint;
+    readonly remainingUSDCents: bigint;
+    constructor(priceUSDCents: bigint, remainingUSDCents: bigint);
+}
+/**
+ * A payment reference that is not 32 bytes, has an empty order part, or
+ * carries a tag this SDK cannot write over or read back.
+ */
+export declare class InvalidPaymentReferenceError extends KokioError {
+    readonly reference: string;
+    constructor(reference: string, reason: string);
+}
+/**
+ * A coupon that covers none or all of the price. Neither is a split: a coupon
+ * covering the whole price is a full-coupon order with a single reference.
+ */
+export declare class CouponSplitOutOfRangeError extends KokioError {
+    readonly couponUSDCents?: bigint;
+    readonly priceUSDCents: bigint;
+    constructor(couponUSDCents: bigint | undefined, priceUSDCents: bigint);
+}
 export interface DecodedRevert {
     errorName: string;
     args: readonly unknown[];

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

@@ -70,6 +70,8 @@ export declare const _isESIMIdentifierClaimed: (client: KokioSmartAccountClient,
 export declare const _eSIMWalletForIdentifier: (client: KokioSmartAccountClient, eSIMUniqueIdentifier: string) => Promise<Address>;
 /** The fallback price ceiling in USD cents for a wallet holding no cap of its own. */
 export declare const _defaultPriceCapUSDCents: (client: KokioSmartAccountClient) => Promise<bigint>;
+/** What the admin key may charge a newly created eSIM wallet in total, in USD cents. */
+export declare const _defaultAdminAllowanceUSDCents: (client: KokioSmartAccountClient) => Promise<bigint>;
 /** The payment adapter this registry currently points at. */
 export declare const _paymentAdapter: (client: KokioSmartAccountClient) => Promise<Address>;
 /**

package/package.json

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