kokio-sdk 3.2.0 → 3.3.0

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

@@ -8,10 +8,11 @@ import { AdminDeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
 import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { AdminPaymentAdapterSubPackage } from "./interface/paymentAdapterClass.js";
 import { AdminCallsSubPackage } from "./interface/callsClass.js";
+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, 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, 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";
@@ -45,6 +46,8 @@ export class KokioAdmin {
     paymentAdapter;
     /** Calls for the app to sign as a user operation, built here so the backend holds the purchase logic. */
     calls;
+    /** Checks what a mined transaction paid, before the backend acts on it. */
+    utils;
     // Instance-scoped surfaces - undefined until their address is known.
     deviceWallet;
     eSIMWallet;
@@ -60,6 +63,7 @@ export class KokioAdmin {
         this.protocolAdmin = new AdminProtocolAdminSubPackage(walletClient);
         this.paymentAdapter = new AdminPaymentAdapterSubPackage(walletClient);
         this.calls = new AdminCallsSubPackage(walletClient);
+        this.utils = new AdminUtilsSubPackage(walletClient);
         this.deviceWallet = deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, deviceWalletAddress) : undefined;
         this.eSIMWallet = eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, eSIMWalletAddress) : undefined;
     }
@@ -111,6 +115,7 @@ export class KokioAdmin {
         this.protocolAdmin = new AdminProtocolAdminSubPackage(walletClient);
         this.paymentAdapter = new AdminPaymentAdapterSubPackage(walletClient);
         this.calls = new AdminCallsSubPackage(walletClient);
+        this.utils = new AdminUtilsSubPackage(walletClient);
         this.deviceWallet = this.deviceWalletAddress ? new AdminDeviceWalletSubPackage(walletClient, this.deviceWalletAddress) : undefined;
         this.eSIMWallet = this.eSIMWalletAddress ? new AdminESIMWalletSubPackage(walletClient, this.eSIMWalletAddress) : undefined;
         return this;

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

@@ -0,0 +1,27 @@
+import { _verifyERC20Transfer, _verifyProtocolPayment } from "../../logic/admin/utils/tokenTransfer.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.
+ */
+export class AdminUtilsSubPackage {
+    walletClient;
+    constructor(walletClient) {
+        this.walletClient = walletClient;
+    }
+    /**
+     * The purchases `eSIMWallet` paid for through the protocol in `symbol`
+     * ("USDC", "USDCt"), with each one's `paymentReference` and price in cents.
+     * Throws if the symbol is not an onchain currency on the payment adapter.
+     */
+    verifyProtocolPayment(transaction, symbol, eSIMWallet) {
+        return _verifyProtocolPayment(this.walletClient, transaction, symbol, eSIMWallet);
+    }
+    /**
+     * What `sender` sent `destination` directly in any ERC-20. The cents count
+     * one token as one dollar, so they mean nothing for a token that is not.
+     */
+    verifyERC20Transfer(transaction, token, sender, destination) {
+        return _verifyERC20Transfer(this.walletClient, transaction, token, sender, destination);
+    }
+}

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

@@ -2,7 +2,7 @@ import { BaseError, ContractFunctionRevertedError, isAddressEqual, parseEventLog
 import { _chainId, _getChainSpecificConstants } from "../constants.js";
 import { BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, MissingEOAWalletError, StalledBatchError, writeContractOrThrow, } from "../errors.js";
 import { LazyWalletRegistry, Registry } from "../../abis/index.js";
-import { _eSIMWalletsDeployed, _lazyDeployedESIMWallet } from "./reads/lazyWalletRegistry.reads.js";
+import { _eSIMIdentifiersAssociatedWithDeviceIdentifier, _eSIMWalletsDeployed, _lazyDeployedESIMWallet, } from "./reads/lazyWalletRegistry.reads.js";
 // Admin-EOA logic for `LazyWalletRegistry`. Every function here is
 // `onlyESIMWalletAdmin` on chain, so they can only succeed from the admin EOA -
 // a device-wallet userOp (whose sender is the smart account) always reverts.
@@ -199,6 +199,7 @@ export const _deployLazyWalletAllBatches = async (client, deviceOwnerPublicKey,
     }
     const alreadyDeployed = await _eSIMWalletsDeployed(client, deviceUniqueIdentifier);
     const batches = [];
+    let earlier = { eSIMWallets: [], eSIMIdentifiers: [] };
     let deviceWallet;
     let outstanding;
     if (alreadyDeployed === 0n) {
@@ -216,6 +217,9 @@ export const _deployLazyWalletAllBatches = async (client, deviceOwnerPublicKey,
     else {
         if (depositAmount !== 0n)
             throw new DepositOnResumeError(deviceUniqueIdentifier, depositAmount);
+        // Wallets an earlier call deployed. Without them a resume would report only its
+        // own batches, and a caller walking the result would skip the rest of the device.
+        earlier = await _readDeployedESIMWallets(client, deviceUniqueIdentifier, alreadyDeployed);
         deviceWallet = await publicClient.readContract({
             address: values.factoryAddresses.REGISTRY,
             abi: Registry,
@@ -230,7 +234,7 @@ export const _deployLazyWalletAllBatches = async (client, deviceOwnerPublicKey,
             account: client.account,
         }, "AllESIMWalletsDeployed");
         if (finished) {
-            return { deviceWallet, eSIMWallets: [], eSIMIdentifiers: [], batches: [], alreadyComplete: true };
+            return { deviceWallet, ...earlier, batches: [], alreadyComplete: true };
         }
         outstanding = true;
     }
@@ -249,12 +253,22 @@ export const _deployLazyWalletAllBatches = async (client, deviceOwnerPublicKey,
     }
     return {
         deviceWallet,
-        eSIMWallets: batches.flatMap((batch) => [...batch.eSIMWallets]),
-        eSIMIdentifiers: batches.flatMap((batch) => [...batch.eSIMIdentifiers]),
+        eSIMWallets: [...earlier.eSIMWallets, ...batches.flatMap((batch) => [...batch.eSIMWallets])],
+        eSIMIdentifiers: [...earlier.eSIMIdentifiers, ...batches.flatMap((batch) => [...batch.eSIMIdentifiers])],
         batches,
         alreadyComplete: false,
     };
 };
+/**
+ * The first `count` eSIM wallets deployed for a device, in deploy order. The
+ * deploy walks the device's identifier list from the start, so the first
+ * `count` identifiers are exactly the ones with wallets.
+ */
+const _readDeployedESIMWallets = async (client, deviceUniqueIdentifier, count) => {
+    const eSIMIdentifiers = await Promise.all(Array.from({ length: Number(count) }, (_, i) => _eSIMIdentifiersAssociatedWithDeviceIdentifier(client, deviceUniqueIdentifier, BigInt(i))));
+    const eSIMWallets = await Promise.all(eSIMIdentifiers.map((id) => _lazyDeployedESIMWallet(client, id)));
+    return { eSIMWallets, eSIMIdentifiers };
+};
 /**
  * Copy an eSIM's whole stored purchase history onto its wallet, over as many
  * transactions as that takes. `onlyESIMWalletAdmin`.

package/dist/esm/logic/admin/utils/tokenTransfer.js

@@ -0,0 +1,157 @@
+import { BaseError, ContractFunctionRevertedError, ContractFunctionZeroDataError, AbiDecodingDataSizeTooSmallError, AbiDecodingZeroDataError, TransactionReceiptNotFoundError, erc20Abi, isAddress, isAddressEqual, isHash, parseEventLogs, publicActions, stringToHex, zeroAddress, } from "viem";
+import { _chainId, _getChainSpecificConstants } from "../../constants.js";
+import { ESIMWallet, PaymentAdapter, Registry } from "../../../abis/index.js";
+import { InvalidAddressError, InvalidSymbolError, NotAProtocolESIMWalletError, NotAnERC20TokenError, PriceOutOfRangeError, ReceiptNotCanonicalError, TokenNotAcceptedError, TransactionRevertedError, UnknownTransactionError, UnmatchedPaymentEventsError, } from "../../errors.js";
+// The contracts price everything in uint64 cents.
+const MAX_UINT64 = 2n ** 64n - 1n;
+const _checkAddress = (what, value) => {
+    if (!isAddress(value))
+        throw new InvalidAddressError(what, value, "is not a valid address");
+    if (isAddressEqual(value, zeroAddress))
+        throw new InvalidAddressError(what, value, "is the zero address");
+    return value;
+};
+// Same bytes as Solidity's `bytes32("USDC")`: the text on the left, zeros after.
+const _symbolToBytes32 = (symbol) => {
+    if (!symbol)
+        throw new InvalidSymbolError(symbol);
+    try {
+        return stringToHex(symbol, { size: 32 });
+    }
+    catch {
+        throw new InvalidSymbolError(symbol);
+    }
+};
+const _checkTransaction = (transaction) => {
+    if (typeof transaction === "string" && !isHash(transaction))
+        throw new UnknownTransactionError(transaction);
+};
+// A receipt passed in is used as given, so it must come from the caller's own node.
+const _receipt = async (client, transaction) => {
+    let receipt = transaction;
+    if (typeof transaction === "string") {
+        try {
+            receipt = await client.extend(publicActions).getTransactionReceipt({ hash: transaction });
+        }
+        catch (err) {
+            if (err instanceof TransactionReceiptNotFoundError)
+                throw new UnknownTransactionError(transaction);
+            throw err;
+        }
+    }
+    if (receipt.status !== "success")
+        throw new TransactionRevertedError(receipt.transactionHash);
+    return receipt;
+};
+// The receipt plus how far its block has settled, read alongside it. A receipt passed in
+// is also checked against the chain's block at its height, since it may be from a block
+// since reorged out. One fetched by hash comes from the chain as it is now.
+const _receiptWithFinality = async (client, transaction) => {
+    const publicClient = client.extend(publicActions);
+    const given = typeof transaction === "string" ? undefined : transaction;
+    const [receipt, safe, finalized, canonical] = await Promise.all([
+        _receipt(client, transaction),
+        publicClient.getBlock({ blockTag: "safe" }),
+        publicClient.getBlock({ blockTag: "finalized" }),
+        given && publicClient.getBlock({ blockNumber: given.blockNumber }),
+    ]);
+    if (canonical && canonical.hash !== receipt.blockHash) {
+        throw new ReceiptNotCanonicalError(receipt.transactionHash, receipt.blockHash);
+    }
+    const finality = receipt.blockNumber <= finalized.number ? "finalized"
+        : receipt.blockNumber <= safe.number ? "safe"
+            : "latest";
+    return { receipt, landed: { finality, blockNumber: receipt.blockNumber, blockHash: receipt.blockHash } };
+};
+/**
+ * Every purchase `eSIMWallet` paid for in `symbol` within one transaction, read
+ * from the payment adapter's `PaymentSettled` and the eSIM wallet's
+ * `DataBundleBoughtWithToken`. Cents and references are the contracts' own.
+ */
+export const _verifyProtocolPayment = async (client, transaction, symbol, eSIMWallet) => {
+    const wallet = _checkAddress("eSIM wallet", eSIMWallet);
+    const asset = _symbolToBytes32(symbol);
+    _checkTransaction(transaction);
+    const publicClient = client.extend(publicActions);
+    const reads = async () => {
+        const F = _getChainSpecificConstants(await _chainId(client), client.transport.url).factoryAddresses;
+        const [deviceWallet, entry] = await Promise.all([
+            publicClient.readContract({ address: F.REGISTRY, abi: Registry, functionName: "isESIMWalletValid", args: [wallet] }),
+            publicClient.readContract({ address: F.PAYMENT_ADAPTER, abi: PaymentAdapter, functionName: "assets", args: [asset] }),
+        ]);
+        return { adapter: F.PAYMENT_ADAPTER, deviceWallet, entry };
+    };
+    const [{ receipt, landed }, { adapter, deviceWallet, entry: [, , decimals, token] }] = await Promise.all([
+        _receiptWithFinality(client, transaction),
+        reads(),
+    ]);
+    if (deviceWallet === zeroAddress)
+        throw new NotAProtocolESIMWalletError(wallet);
+    // A registered symbol always has non-zero decimals, even once withdrawn.
+    if (decimals === 0)
+        throw new TokenNotAcceptedError(symbol, "NOT_REGISTERED");
+    if (token === zeroAddress)
+        throw new TokenNotAcceptedError(symbol, "NOT_ONCHAIN");
+    // Filtered on the emitting address, so a look-alike event from any other contract is ignored.
+    const settled = parseEventLogs({ abi: PaymentAdapter, eventName: "PaymentSettled", logs: receipt.logs })
+        .filter((log) => isAddressEqual(log.address, adapter) && log.args._symbol === asset && isAddressEqual(log.args._eSIMWallet, wallet));
+    const bought = parseEventLogs({ abi: ESIMWallet, eventName: "DataBundleBoughtWithToken", logs: receipt.logs })
+        .filter((log) => isAddressEqual(log.address, wallet) && log.args._asset === asset);
+    // The adapter settles first and the wallet emits after, once per purchase.
+    if (settled.length !== bought.length)
+        throw new UnmatchedPaymentEventsError(receipt.transactionHash);
+    const payments = settled.map((s, i) => {
+        const b = bought[i];
+        if (s.logIndex > b.logIndex || s.args._priceUSDCents !== b.args._priceUSDCents || s.args._spent !== b.args._amountSpent) {
+            throw new UnmatchedPaymentEventsError(receipt.transactionHash);
+        }
+        return {
+            paymentReference: b.args._paymentReference,
+            dataBundleId: b.args._dataBundleID,
+            priceUSDCents: b.args._priceUSDCents,
+            amountSpent: b.args._amountSpent,
+            vault: s.args._vault,
+        };
+    });
+    return { priceUSDCents: payments.reduce((sum, p) => sum + p.priceUSDCents, 0n), payments, ...landed };
+};
+// A revert or an empty answer means the address is not an ERC-20. Anything else, like a
+// network failure, is passed on as-is.
+const _erc20Read = (read, token) => read.catch((err) => {
+    const notAToken = err instanceof BaseError && err.walk((e) => e instanceof ContractFunctionRevertedError ||
+        e instanceof ContractFunctionZeroDataError ||
+        e instanceof AbiDecodingZeroDataError ||
+        e instanceof AbiDecodingDataSizeTooSmallError);
+    throw notAToken ? new NotAnERC20TokenError(token) : err;
+});
+/**
+ * What `sender` sent `destination` directly in `token` within one transaction.
+ * Cents treat one token as one dollar, the way the payment adapter prices a
+ * dollar currency, so they mean nothing for a token that is not.
+ */
+export const _verifyERC20Transfer = async (client, transaction, token, sender, destination) => {
+    const tokenAddress = _checkAddress("Token", token);
+    const from = _checkAddress("Sender", sender);
+    const to = _checkAddress("Destination", destination);
+    if (isAddressEqual(from, to))
+        throw new InvalidAddressError("Destination", to, "is the same as the sender");
+    _checkTransaction(transaction);
+    const publicClient = client.extend(publicActions);
+    // decimals() is what an ERC-721 lacks, and an address with no code answers neither.
+    const [{ receipt, landed }, decimals] = await Promise.all([
+        _receiptWithFinality(client, transaction),
+        _erc20Read(publicClient.readContract({ address: tokenAddress, abi: erc20Abi, functionName: "decimals" }), tokenAddress),
+        _erc20Read(publicClient.readContract({ address: tokenAddress, abi: erc20Abi, functionName: "totalSupply" }), tokenAddress),
+    ]);
+    // Strict parsing skips an ERC-721 Transfer, whose third topic is the token id.
+    const amount = parseEventLogs({ abi: erc20Abi, eventName: "Transfer", logs: receipt.logs })
+        .filter((log) => isAddressEqual(log.address, tokenAddress) && isAddressEqual(log.args.from, from) && isAddressEqual(log.args.to, to))
+        .reduce((sum, log) => sum + log.args.value, 0n);
+    // amount * 100 / 10^decimals, without the large intermediate.
+    const priceUSDCents = decimals >= 2
+        ? amount / 10n ** BigInt(decimals - 2)
+        : amount * 10n ** BigInt(2 - decimals);
+    if (priceUSDCents > MAX_UINT64)
+        throw new PriceOutOfRangeError(priceUSDCents);
+    return { priceUSDCents, amount, ...landed };
+};

package/dist/esm/logic/errors.js

@@ -132,6 +132,102 @@ export class StalledBatchError extends KokioError {
         this.remaining = remaining;
     }
 }
+/** An address argument is malformed, zero, or the same as the other side of the transfer. */
+export class InvalidAddressError extends KokioError {
+    value;
+    constructor(what, value, reason) {
+        super("INVALID_ADDRESS", `${what} ${value} ${reason}.`);
+        this.value = value;
+    }
+}
+/** A currency symbol is empty or does not fit the contracts' 32-byte symbol. */
+export class InvalidSymbolError extends KokioError {
+    symbol;
+    constructor(symbol) {
+        super("INVALID_SYMBOL", `Symbol "${symbol}" must be 1 to 32 bytes long.`);
+        this.symbol = symbol;
+    }
+}
+/**
+ * The payment adapter cannot have taken this symbol as an onchain payment:
+ * `NOT_REGISTERED` if it was never added, `NOT_ONCHAIN` for fiat and non-EVM
+ * entries, which have no token address.
+ */
+export class TokenNotAcceptedError extends KokioError {
+    symbol;
+    reason;
+    constructor(symbol, reason) {
+        super("TOKEN_NOT_ACCEPTED", reason === "NOT_REGISTERED"
+            ? `Symbol "${symbol}" is not registered on the payment adapter.`
+            : `Symbol "${symbol}" has no token address on the payment adapter, so it cannot be paid onchain.`);
+        this.symbol = symbol;
+        this.reason = reason;
+    }
+}
+/** The registry has no record of this address as an eSIM wallet. */
+export class NotAProtocolESIMWalletError extends KokioError {
+    address;
+    constructor(address) {
+        super("NOT_A_PROTOCOL_ESIM_WALLET", `${address} is not an eSIM wallet the registry knows.`);
+        this.address = address;
+    }
+}
+/** No mined transaction with this hash on the client's chain. */
+export class UnknownTransactionError extends KokioError {
+    hash;
+    constructor(hash) {
+        super("UNKNOWN_TRANSACTION", `No mined transaction ${hash} on this chain.`);
+        this.hash = hash;
+    }
+}
+/** The transaction was mined but reverted, so nothing in it moved. */
+export class TransactionRevertedError extends KokioError {
+    hash;
+    constructor(hash) {
+        super("TRANSACTION_REVERTED", `Transaction ${hash} reverted.`);
+        this.hash = hash;
+    }
+}
+/**
+ * A receipt passed in is from a block the chain no longer has at that height,
+ * so it was reorged out. The payment may have landed again elsewhere.
+ */
+export class ReceiptNotCanonicalError extends KokioError {
+    hash;
+    blockHash;
+    constructor(hash, blockHash) {
+        super("RECEIPT_NOT_CANONICAL", `The receipt for ${hash} is from block ${blockHash}, which is no longer on the chain. Check again by hash.`);
+        this.hash = hash;
+        this.blockHash = blockHash;
+    }
+}
+/** The address does not answer `decimals()` and `totalSupply()` like an ERC-20. */
+export class NotAnERC20TokenError extends KokioError {
+    token;
+    constructor(token) {
+        super("NOT_AN_ERC20_TOKEN", `${token} is not an ERC-20 token on this chain.`);
+        this.token = token;
+    }
+}
+/**
+ * A purchase's adapter event and eSIM wallet event disagree or do not pair up.
+ * The current contracts always emit them together, so this means they changed.
+ */
+export class UnmatchedPaymentEventsError extends KokioError {
+    hash;
+    constructor(hash) {
+        super("UNMATCHED_PAYMENT_EVENTS", `Transaction ${hash} has payment events that do not pair up.`);
+        this.hash = hash;
+    }
+}
+/** A cent figure too large for the uint64 the contracts price in. */
+export class PriceOutOfRangeError extends KokioError {
+    priceUSDCents;
+    constructor(priceUSDCents) {
+        super("PRICE_OUT_OF_RANGE", `${priceUSDCents} cents does not fit the contracts' uint64 price.`);
+        this.priceUSDCents = priceUSDCents;
+    }
+}
 // Every ABI that can surface a custom error from an on-chain revert. viem's
 // `decodeErrorResult` walks each ABI's `error` fragments to match the 4-byte
 // selector in the revert data.

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

@@ -9,7 +9,8 @@ import { AdminDeviceWalletSubPackage } from "./interface/deviceWalletClass.js";
 import { AdminESIMWalletSubPackage } from "./interface/eSIMWalletClass.js";
 import { AdminPaymentAdapterSubPackage } from "./interface/paymentAdapterClass.js";
 import { AdminCallsSubPackage } from "./interface/callsClass.js";
-export { KokioError, NullOrUndefinedValueError, MissingSmartWalletError, MissingEOAWalletError, InvalidClientError, UnsupportedChainError, UnconfiguredChainError, CounterfactualMismatchError, BatchSizeOutOfRangeError, DepositOnResumeError, ESIMWalletNotLazyDeployedError, MissingBatchEventError, StalledBatchError, ContractRevertError, decodeContractRevert, } from "../logic/errors.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 type { DecodedRevert } from "../logic/errors.js";
 export { OperationState } from "../logic/admin/reads/protocolAdmin.reads.js";
 /**
@@ -41,6 +42,8 @@ export declare class KokioAdmin {
     paymentAdapter: AdminPaymentAdapterSubPackage;
     /** Calls for the app to sign as a user operation, built here so the backend holds the purchase logic. */
     calls: AdminCallsSubPackage;
+    /** Checks what a mined transaction paid, before the backend acts on it. */
+    utils: AdminUtilsSubPackage;
     deviceWallet?: AdminDeviceWalletSubPackage;
     eSIMWallet?: AdminESIMWalletSubPackage;
     constructor(walletClient: WalletClient, deviceWalletAddress?: Address, eSIMWalletAddress?: Address);

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

@@ -0,0 +1,21 @@
+import { Address, Hash, TransactionReceipt, WalletClient } from "viem";
+/**
+ * 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.
+ */
+export declare class AdminUtilsSubPackage {
+    walletClient: WalletClient;
+    constructor(walletClient: WalletClient);
+    /**
+     * The purchases `eSIMWallet` paid for through the protocol in `symbol`
+     * ("USDC", "USDCt"), with each one's `paymentReference` and price in cents.
+     * Throws if the symbol is not an onchain currency on the payment adapter.
+     */
+    verifyProtocolPayment(transaction: Hash | TransactionReceipt, symbol: string, eSIMWallet: Address): Promise<import("../../types.js").ProtocolPaymentCheck>;
+    /**
+     * What `sender` sent `destination` directly in any ERC-20. The cents count
+     * 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>;
+}

package/dist/types/logic/admin/utils/tokenTransfer.d.ts

@@ -0,0 +1,14 @@
+import { Address, Hash, TransactionReceipt, WalletClient } from "viem";
+import { ERC20TransferCheck, ProtocolPaymentCheck } from "../../../types.js";
+/**
+ * Every purchase `eSIMWallet` paid for in `symbol` within one transaction, read
+ * from the payment adapter's `PaymentSettled` and the eSIM wallet's
+ * `DataBundleBoughtWithToken`. Cents and references are the contracts' own.
+ */
+export declare const _verifyProtocolPayment: (client: WalletClient, transaction: Hash | TransactionReceipt, symbol: string, eSIMWallet: Address) => Promise<ProtocolPaymentCheck>;
+/**
+ * What `sender` sent `destination` directly in `token` within one transaction.
+ * Cents treat one token as one dollar, the way the payment adapter prices a
+ * dollar currency, so they mean nothing for a token that is not.
+ */
+export declare const _verifyERC20Transfer: (client: WalletClient, transaction: Hash | TransactionReceipt, token: Address, sender: Address, destination: Address) => Promise<ERC20TransferCheck>;

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

@@ -87,6 +87,68 @@ export declare class StalledBatchError extends KokioError {
     readonly remaining: bigint;
     constructor(hash: Hex, remaining: bigint);
 }
+/** An address argument is malformed, zero, or the same as the other side of the transfer. */
+export declare class InvalidAddressError extends KokioError {
+    readonly value: string;
+    constructor(what: string, value: string, reason: string);
+}
+/** A currency symbol is empty or does not fit the contracts' 32-byte symbol. */
+export declare class InvalidSymbolError extends KokioError {
+    readonly symbol: string;
+    constructor(symbol: string);
+}
+/**
+ * The payment adapter cannot have taken this symbol as an onchain payment:
+ * `NOT_REGISTERED` if it was never added, `NOT_ONCHAIN` for fiat and non-EVM
+ * entries, which have no token address.
+ */
+export declare class TokenNotAcceptedError extends KokioError {
+    readonly symbol: string;
+    readonly reason: "NOT_REGISTERED" | "NOT_ONCHAIN";
+    constructor(symbol: string, reason: "NOT_REGISTERED" | "NOT_ONCHAIN");
+}
+/** The registry has no record of this address as an eSIM wallet. */
+export declare class NotAProtocolESIMWalletError extends KokioError {
+    readonly address: string;
+    constructor(address: string);
+}
+/** No mined transaction with this hash on the client's chain. */
+export declare class UnknownTransactionError extends KokioError {
+    readonly hash: Hex;
+    constructor(hash: Hex);
+}
+/** The transaction was mined but reverted, so nothing in it moved. */
+export declare class TransactionRevertedError extends KokioError {
+    readonly hash: Hex;
+    constructor(hash: Hex);
+}
+/**
+ * A receipt passed in is from a block the chain no longer has at that height,
+ * so it was reorged out. The payment may have landed again elsewhere.
+ */
+export declare class ReceiptNotCanonicalError extends KokioError {
+    readonly hash: Hex;
+    readonly blockHash: Hex;
+    constructor(hash: Hex, blockHash: Hex);
+}
+/** The address does not answer `decimals()` and `totalSupply()` like an ERC-20. */
+export declare class NotAnERC20TokenError extends KokioError {
+    readonly token: string;
+    constructor(token: string);
+}
+/**
+ * A purchase's adapter event and eSIM wallet event disagree or do not pair up.
+ * The current contracts always emit them together, so this means they changed.
+ */
+export declare class UnmatchedPaymentEventsError extends KokioError {
+    readonly hash: Hex;
+    constructor(hash: Hex);
+}
+/** A cent figure too large for the uint64 the contracts price in. */
+export declare class PriceOutOfRangeError extends KokioError {
+    readonly priceUSDCents: bigint;
+    constructor(priceUSDCents: bigint);
+}
 export interface DecodedRevert {
     errorName: string;
     args: readonly unknown[];

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

@@ -1,3 +1,3 @@
-export type { P256Key, Call, WebAuthnSignature, P256Credential, DataBundleDetails, Asset, SignedRequest, KokioSmartAccount, KokioSmartAccountClient, OwnerCall, OperationOptions, ScheduledOperation, ScheduledBatchOperation, LazyDeploymentBatch, LazyDeployment, LazyHistoryBatch, LazyHistoryCopy } from './types.js';
+export type { P256Key, Call, WebAuthnSignature, P256Credential, DataBundleDetails, Asset, SignedRequest, KokioSmartAccount, KokioSmartAccountClient, OwnerCall, OperationOptions, ScheduledOperation, ScheduledBatchOperation, LazyDeploymentBatch, LazyDeployment, LazyHistoryBatch, LazyHistoryCopy, Finality, TransactionFinality, ProtocolPayment, ProtocolPaymentCheck, ERC20TransferCheck } from './types.js';
 export type { KokioConstants } from './interface/constantsClass.js';
 export { Settlement } from './types.js';

package/dist/types/types.d.ts

@@ -127,8 +127,8 @@ export type LazyDeploymentBatch = {
 };
 /**
  * What a fully paginated lazy deployment did. `eSIMWallets` and `eSIMIdentifiers`
- * cover only the batches this call ran, so a resume reports what it finished
- * rather than the device's whole set.
+ * cover the device's whole set, including wallets an earlier call deployed, so a
+ * resume can be walked like a fresh deploy. `batches` holds only what this call sent.
  */
 export type LazyDeployment = {
     deviceWallet: Address;
@@ -154,6 +154,41 @@ export type LazyHistoryCopy = {
     /** The history was already fully copied, so nothing was sent. */
     alreadyComplete: boolean;
 };
+/** One data bundle an eSIM wallet paid for through the protocol. */
+export type ProtocolPayment = {
+    /** The offchain order id the purchase spent. */
+    paymentReference: Hex;
+    dataBundleId: Hex;
+    /** 123456n is $1234.56. */
+    priceUSDCents: bigint;
+    /** What reached the vault, in the token's smallest unit. */
+    amountSpent: bigint;
+    vault: Address;
+};
+/**
+ * How far a block has settled. `latest` can still be reorged out, `safe` only by
+ * an L1 reorg, and `finalized` not at all.
+ */
+export type Finality = "latest" | "safe" | "finalized";
+/** Where a checked transaction landed, to store and check again later. */
+export type TransactionFinality = {
+    finality: Finality;
+    blockNumber: bigint;
+    blockHash: Hex;
+};
+/** Every protocol purchase one eSIM wallet made in one transaction and currency. */
+export type ProtocolPaymentCheck = TransactionFinality & {
+    /** Total across `payments`, 0n if there were none. */
+    priceUSDCents: bigint;
+    payments: readonly ProtocolPayment[];
+};
+/** What one address sent another directly in one ERC-20, in one transaction. */
+export type ERC20TransferCheck = TransactionFinality & {
+    /** `amount` as cents, counting one token as one dollar and rounding down. */
+    priceUSDCents: bigint;
+    /** In the token's smallest unit, 0n if nothing was sent. */
+    amount: bigint;
+};
 export type SignedRequest = {
     body: string;
     stamp: {

package/package.json

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