kokio-sdk 3.2.1 → 3.4.0

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

@@ -8,13 +8,16 @@ 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, 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.
  *
@@ -45,6 +48,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 +65,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 +117,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/registryClass.js

@@ -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);

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

@@ -0,0 +1,43 @@
+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, 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;
+    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);
+    }
+    /**
+     * 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/logic/admin/registry.eoa.js

@@ -1,6 +1,9 @@
+import { encodeAbiParameters, keccak256, publicActions, stringToHex } from "viem";
 import { _chainId, _getChainSpecificConstants } from "../constants.js";
-import { MissingEOAWalletError, writeContractOrThrow } from "../errors.js";
+import { CouponSplitOutOfRangeError, InvalidPaymentReferenceError, MissingEOAWalletError, TransactionRevertedError, writeContractOrThrow, } from "../errors.js";
 import { Registry } from "../../abis/index.js";
+import { Settlement } from "../../types.js";
+import { PaymentReferenceKind, _parsePaymentReference } from "./utils/paymentReference.js";
 // Admin-EOA logic for `Registry`. Most of this is `onlyOwner`, so the `client`
 // must carry the owner EOA. `_acceptAdminUpdate` is the nominee's own call and
 // `_assignESIMIdentifier` is `onlyESIMWalletAdmin`.
@@ -207,21 +210,92 @@ export const _assignESIMIdentifier = async (client, eSIMWalletAddress, eSIMUniqu
  * 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 const _recordSettledPurchase = async (client, eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference) => {
+export const _recordSettledPurchase = async (client, eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference, couponUSDCents) => {
     const chainID = await _chainId(client);
     const rpcURL = client.transport.url;
     const values = _getChainSpecificConstants(chainID, rpcURL);
     if (!client.account)
         throw new MissingEOAWalletError();
-    return writeContractOrThrow(client, {
+    const account = client.account;
+    const record = (line) => writeContractOrThrow(client, {
         address: values.factoryAddresses.REGISTRY,
         chain: values.chain,
-        account: client.account,
+        account,
         abi: Registry,
         functionName: 'recordSettledPurchase',
-        args: [eSIMWalletAddress, dataBundleDetail, asset, tokenAmount, paymentReference]
+        args: [eSIMWalletAddress, line.dataBundleDetail, line.asset, line.tokenAmount, line.paymentReference]
     });
+    if (typeof paymentReference === "string") {
+        return record({ dataBundleDetail, asset, tokenAmount, paymentReference });
+    }
+    const lines = _couponSplitLines(dataBundleDetail, asset, tokenAmount, paymentReference, couponUSDCents);
+    const publicClient = client.extend(publicActions);
+    const spent = await Promise.all(lines.map((line) => publicClient.readContract({
+        address: values.factoryAddresses.REGISTRY,
+        abi: Registry,
+        functionName: "usedPaymentReferences",
+        args: [keccak256(encodeAbiParameters([{ type: "address" }, { type: "bytes32" }], [eSIMWalletAddress, line.paymentReference]))]
+    })));
+    const missing = lines.filter((_, i) => !spent[i]);
+    // With both lines recorded, the remainder is sent anyway so the contract refuses it with
+    // `PaymentReferenceAlreadyUsed`, the same answer a retried single reference gets.
+    let hash;
+    for (const line of missing.length > 0 ? missing : [lines[0]]) {
+        if (hash) {
+            const receipt = await publicClient.waitForTransactionReceipt({ hash });
+            if (receipt.status !== "success")
+                throw new TransactionRevertedError(hash);
+        }
+        hash = await record(line);
+    }
+    return hash;
+};
+// Coupons are recorded as card payments in USD, whose smallest unit is a cent.
+const COUPON_ASSET = stringToHex("USD", { size: 32 });
+/**
+ * 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 const _couponSplitLines = (dataBundleDetail, asset, tokenAmount, [couponRef, remainderRef], couponUSDCents) => {
+    const coupon = _parsePaymentReference(couponRef);
+    const remainder = _parsePaymentReference(remainderRef);
+    if (coupon.kind !== PaymentReferenceKind.CouponPart) {
+        throw new InvalidPaymentReferenceError(couponRef, "is not tagged as a coupon part");
+    }
+    if (remainder.kind !== PaymentReferenceKind.Remainder) {
+        throw new InvalidPaymentReferenceError(remainderRef, "is not tagged as a remainder");
+    }
+    if (coupon.reference !== remainder.reference) {
+        throw new InvalidPaymentReferenceError(remainderRef, `belongs to a different order than ${couponRef}`);
+    }
+    const price = dataBundleDetail.priceUSDCents;
+    if (couponUSDCents === undefined || couponUSDCents <= 0n || couponUSDCents >= price) {
+        throw new CouponSplitOutOfRangeError(couponUSDCents, price);
+    }
+    return [
+        {
+            dataBundleDetail: { ...dataBundleDetail, priceUSDCents: price - couponUSDCents },
+            asset,
+            tokenAmount,
+            paymentReference: remainderRef,
+        },
+        {
+            dataBundleDetail: { id: dataBundleDetail.id, priceUSDCents: couponUSDCents, settlement: Settlement.Fiat },
+            asset: COUPON_ASSET,
+            tokenAmount: couponUSDCents,
+            paymentReference: couponRef,
+        },
+    ];
 };
 /**
  * Step 2 of the 2-step admin handover: the nominee accepts. The chain requires

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

@@ -0,0 +1,58 @@
+import { concat, isHex, pad, size, slice } from "viem";
+import { InvalidPaymentReferenceError } from "../../errors.js";
+/** How a purchase was paid for, as written into its payment reference. */
+export var PaymentReferenceKind;
+(function (PaymentReferenceKind) {
+    /** Paid in full without a coupon. Carries no tag. */
+    PaymentReferenceKind["Standard"] = "Standard";
+    /** Paid in full by a coupon. */
+    PaymentReferenceKind["Coupon"] = "Coupon";
+    /** The coupon's share of a purchase split between a coupon and another payment. */
+    PaymentReferenceKind["CouponPart"] = "CouponPart";
+    /** What the user paid on top of the coupon in a split purchase. */
+    PaymentReferenceKind["Remainder"] = "Remainder";
+})(PaymentReferenceKind || (PaymentReferenceKind = {}));
+// The backend puts the order id in the low 12 bytes, leaving the high 20 free for a tag.
+// Every coupon tag starts with 0xfee0ff ("fee off") so it stands out on an explorer.
+const TAG_SIZE = 20;
+const TAGS = {
+    [PaymentReferenceKind.Standard]: pad("0x", { size: TAG_SIZE }),
+    [PaymentReferenceKind.Coupon]: pad("0xfee0ff", { size: TAG_SIZE, dir: "right" }),
+    [PaymentReferenceKind.CouponPart]: pad("0xfee0ffc0de", { size: TAG_SIZE, dir: "right" }),
+    [PaymentReferenceKind.Remainder]: pad("0xfee0ffba1a5ce0", { size: TAG_SIZE, dir: "right" }),
+};
+// Lowercased so a checksum-style or uppercase input compares equal to the tags above.
+const _splitReference = (reference) => {
+    if (!isHex(reference, { strict: true }) || size(reference) !== 32) {
+        throw new InvalidPaymentReferenceError(reference, "is not 32 bytes of hex");
+    }
+    const lower = reference.toLowerCase();
+    const order = slice(lower, TAG_SIZE);
+    // The contracts refuse a zero reference, and a tag would hide an empty order id from that check.
+    if (BigInt(order) === 0n)
+        throw new InvalidPaymentReferenceError(reference, "has an empty order part");
+    return { tag: slice(lower, 0, TAG_SIZE), order };
+};
+/**
+ * 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 const _tagPaymentReference = (reference, kind) => {
+    const { tag, order } = _splitReference(reference);
+    if (tag !== TAGS[PaymentReferenceKind.Standard]) {
+        throw new InvalidPaymentReferenceError(reference, "is already tagged");
+    }
+    return concat([TAGS[kind], order]);
+};
+/**
+ * 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 const _parsePaymentReference = (reference) => {
+    const { tag, order } = _splitReference(reference);
+    const kind = Object.keys(TAGS).find((k) => TAGS[k] === tag);
+    if (!kind)
+        throw new InvalidPaymentReferenceError(reference, "has an unknown tag");
+    return { kind, reference: pad(order, { size: 32 }) };
+};

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,126 @@ 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;
+    }
+}
+/**
+ * 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 class InvalidPaymentReferenceError extends KokioError {
+    reference;
+    constructor(reference, reason) {
+        super("INVALID_PAYMENT_REFERENCE", `Payment reference "${reference}" ${reason}.`);
+        this.reference = reference;
+    }
+}
+/**
+ * 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 class CouponSplitOutOfRangeError extends KokioError {
+    couponUSDCents;
+    priceUSDCents;
+    constructor(couponUSDCents, priceUSDCents) {
+        super("COUPON_SPLIT_OUT_OF_RANGE", `A coupon of ${couponUSDCents} cents does not split a price of ${priceUSDCents} cents.`);
+        this.couponUSDCents = couponUSDCents;
+        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,9 +9,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";
-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, 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.
  *
@@ -41,6 +43,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/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}`>;

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

@@ -0,0 +1,36 @@
+import { Address, Hash, Hex, TransactionReceipt, WalletClient } from "viem";
+import { PaymentReferenceKind } from "../../logic/admin/utils/paymentReference.js";
+/**
+ * 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;
+    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>;
+    /**
+     * 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/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/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,85 @@ 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);
+}
+/**
+ * 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/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

@@ -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.1",
+  "version": "3.4.0",
   "description": "",
   "type": "module",
   "main": "./dist/esm/config.js",