kokio-sdk 3.3.0 → 3.4.0

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

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

package/dist/esm/admin/interface/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

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

package/dist/esm/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/errors.js

@@ -228,6 +228,30 @@ export class PriceOutOfRangeError extends KokioError {
         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

@@ -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, 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/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

@@ -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/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/errors.d.ts

@@ -149,6 +149,23 @@ 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/package.json

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