@x1id/resolve 0.23.0 → 0.44.0

package/dist/subscription.js

@@ -0,0 +1,642 @@
+/**
+ * X1ID Pay, phase 2: SPL pull subscriptions (docs/specs/x1id-pay-onchain.md
+ * §3/§4).
+ *
+ * - `Subscription` at `["sub", payer, payee, id]`: created and paid for by
+ *   the PAYER, its terms (mint, decimals, amount, period, max charges, the
+ *   optional `@name` binding) fixed for life. Any change = a new id.
+ * - The payer's delegate PDA `["sub_delegate", payer]` is the SPL delegate on
+ *   the payer's canonical ATA. ONE per payer (an SPL account has a single
+ *   delegate), so the SPL approval is shared by every subscription of that
+ *   payer in a mint. The program tracks each subscription's own share in
+ *   `allowanceLeft` (layout v2, Sentinel run-011): a charge needs and spends
+ *   `amount` of it, so no subscription can spend another's share.
+ * - The payer's `SubLedger` at `["sub_ledger", payer, mint]` (Sentinel S-01)
+ *   holds the running total of the Active shares in that mint. It is created
+ *   on first use by `create_subscription` (payer-funded, 82 bytes) and is
+ *   passed to every subscription instruction except close.
+ * - `create_subscription` records `amount × min(charges left, 12)` as the new
+ *   subscription's `allowanceLeft`, adds it to the ledger and SETS the SPL
+ *   approval to the new ledger total (not "current + window"), so an outside
+ *   revoke / approve or a re-created ATA can never leave a share unbacked
+ *   while another subscription spends it. An unlimited (or > 12-charge)
+ *   subscription needs a top-up after 12 charges:
+ *   {@link buildTopUpSubscriptionIx} (raises the share and the ledger, then
+ *   re-approves the ledger total; a plain SPL `Approve` alone does not extend
+ *   a subscription).
+ * - Any cancel (payer or payee) removes the subscription's `allowanceLeft`
+ *   from the ledger. A payer cancel with `giveBack` also re-approves
+ *   `min(current approval, remaining ledger total)` (Revoke at 0).
+ * - `charge_subscription` is a permissionless crank with NO arguments: it
+ *   pulls exactly `amount` once `now >= next_due_at` (fee to the treasury as
+ *   `pay_invoice`), then moves `next_due_at` to the next slot of the
+ *   creation-anchored schedule after `now` ({@link subNextDueAt}).
+ * - SPL Token and Token-2022 only; native XNT is not pullable (use invoices).
+ *   Token-2022 mints must carry only {@link SUB_ALLOWED_MINT_EXTENSIONS}.
+ *
+ * Routed through the program's `fallback` (`extra_ix`) like the rest of Pay:
+ * `sha256("global:<name>")[..8]` + raw Borsh, accounts in exactly the order of
+ * the program's `Accounts` structs. Hand-rolled, no web3.js.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+// ---------------------------------------------------------------------------
+// constants (mirror programs/x1-handles/src/{lib,state}.rs)
+// ---------------------------------------------------------------------------
+export const SUBSCRIPTION_SEED = "sub";
+export const SUB_DELEGATE_SEED = "sub_delegate";
+/** The payer's per-mint ledger: `["sub_ledger", payer, mint]`. */
+export const SUB_LEDGER_SEED = "sub_ledger";
+/** Allocated size of a `SubLedger` (8-byte discriminator + 74). */
+export const SUB_LEDGER_ACCOUNT_LEN = 8 + 74;
+/** Current `SubLedger.version`. */
+export const SUB_LEDGER_VERSION = 1;
+/** Length of a subscription id (`[u8; 16]`). */
+export const SUBSCRIPTION_ID_LEN = 16;
+/** Allocated size of a `Subscription` (8-byte discriminator + `INIT_SPACE`;
+ *  238 since layout v2 added `allowance_left`). */
+export const SUBSCRIPTION_ACCOUNT_LEN = 8 + 238;
+/** Current `Subscription.version`: 2 added `allowance_left`; 3 (same bytes)
+ *  marks a subscription counted in its payer's `SubLedger`. A v2 account is
+ *  refused by `charge_subscription` until a payer top-up adopts it. */
+export const SUBSCRIPTION_VERSION = 3;
+/** Shortest / longest billing period, seconds (1 hour / 5 × 366 days). */
+export const SUB_PERIOD_MIN_SECS = 3600n;
+export const SUB_PERIOD_MAX_SECS = 5n * 366n * 86400n;
+/** Charges' worth of allowance `create_subscription` approves (and records
+ *  as the subscription's `allowanceLeft`) at most. */
+export const SUB_APPROVE_WINDOW_CHARGES = 12n;
+/** Token-2022 mint extension types a subscription mint may carry. */
+export const SUB_ALLOWED_MINT_EXTENSIONS = [3, 6, 12, 18, 19, 20, 21, 22, 23, 26];
+/** Byte offsets inside a raw `Subscription`, for `getProgramAccounts`
+ *  `memcmp` filters. Fields before the variable-width `handle` are fixed. */
+export const SUBSCRIPTION_OFFSETS = {
+    version: 8,
+    payer: 9,
+    payee: 41,
+    id: 73,
+    mint: 89,
+    decimals: 121,
+    amount: 122,
+    periodSecs: 130,
+    nextDueAt: 138,
+    maxCharges: 146,
+    chargesMade: 150,
+    status: 154,
+    createdAt: 155,
+    lastChargedAt: 163,
+    handle: 171,
+};
+const d8 = (...b) => Uint8Array.from(b);
+/** `sha256("global:create_subscription")[..8]`. */
+export const CREATE_SUBSCRIPTION_DISCRIMINATOR = d8(65, 71, 10, 60, 249, 82, 197, 12);
+/** `sha256("global:charge_subscription")[..8]`. */
+export const CHARGE_SUBSCRIPTION_DISCRIMINATOR = d8(121, 52, 210, 23, 3, 68, 86, 194);
+/** `sha256("global:cancel_subscription")[..8]`. */
+export const CANCEL_SUBSCRIPTION_DISCRIMINATOR = d8(60, 139, 189, 242, 191, 208, 143, 18);
+/** `sha256("global:close_subscription")[..8]`. */
+export const CLOSE_SUBSCRIPTION_DISCRIMINATOR = d8(33, 214, 169, 135, 35, 127, 78, 7);
+/** `sha256("global:top_up_subscription")[..8]`. */
+export const TOP_UP_SUBSCRIPTION_DISCRIMINATOR = d8(145, 113, 117, 42, 174, 139, 53, 61);
+/** `sha256("account:Subscription")[..8]`. */
+export const SUBSCRIPTION_ACCOUNT_DISCRIMINATOR = d8(64, 7, 26, 135, 102, 132, 98, 33);
+/** `sha256("account:SubLedger")[..8]`. */
+export const SUB_LEDGER_ACCOUNT_DISCRIMINATOR = d8(18, 52, 119, 178, 113, 160, 89, 255);
+/** Byte offsets inside a raw `SubLedger` (fixed layout). */
+export const SUB_LEDGER_OFFSETS = { version: 8, payer: 9, mint: 41, total: 73, bump: 81 };
+/** Program error codes added by Pay phase 2 (`RegistryError`, 6138-6150),
+ *  plus the upgrade-5 Sentinel block at 6230-6235 (run-011 and the S-01
+ *  ledger; 6158-6229 belong to upgrade 6). Subscriptions also reuse the Pay
+ *  phase 1 codes for the fee config (6122), the `@name` binding (6126-6128)
+ *  and the mint/payee/treasury accounts (6131-6133); see `PAY_ERRORS`. */
+export const SUBSCRIPTION_ERRORS = {
+    SubscriptionAmountZero: 6138,
+    SubscriptionPeriodOutOfRange: 6139,
+    SubscriptionStartOutOfRange: 6140,
+    SubscriptionMintNotSupported: 6141,
+    SubscriptionPayerIsPayee: 6142,
+    SubscriptionDelegateInUse: 6143,
+    SubscriptionNotActive: 6144,
+    SubscriptionNotDue: 6145,
+    SubscriptionFinished: 6146,
+    SubscriptionAllowanceExhausted: 6147,
+    SubscriptionTokenAccountMismatch: 6148,
+    NotSubscriptionParty: 6149,
+    SubscriptionStillActive: 6150,
+    /** `payee` = the payer's own `["sub_delegate", payer]` PDA. */
+    SubscriptionPayeeIsDelegate: 6230,
+    /** `top_up_subscription` above `amount × charges left`. */
+    SubscriptionTopUpTooLarge: 6233,
+    /** Cancel without the `SubLedger` (a ledger-counted subscription or a
+     *  give-back), or a charge of a legacy v2 subscription not yet adopted. */
+    SubscriptionLedgerRequired: 6234,
+    /** The ledger total would overflow u64 (or fall below a share). */
+    SubscriptionLedgerOutOfRange: 6235,
+};
+/** `Subscription.status` as stored (Borsh enum index). */
+export const SUBSCRIPTION_STATUS = { Active: 0, Cancelled: 1 };
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const TOKEN_2022_PROGRAM = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+const TE = new TextEncoder();
+const U32_MAX = 0xffff_ffff;
+const U64_MAX = 0xffffffffffffffffn;
+const I64_MAX = 0x7fffffffffffffffn;
+// ---------------------------------------------------------------------------
+// encoding helpers
+// ---------------------------------------------------------------------------
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function key(pubkey, what, isSigner, isWritable) {
+    return { pubkey: toBase58(pubkey, what), isSigner, isWritable };
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((a, p) => a + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function u32le(n) {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, n, true);
+    return out;
+}
+function u64le(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, n, true);
+    return out;
+}
+function i64le(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, n, true);
+    return out;
+}
+function hasPrefix(data, disc) {
+    if (data.length < disc.length)
+        return false;
+    for (let i = 0; i < disc.length; i++)
+        if (data[i] !== disc[i])
+            return false;
+    return true;
+}
+function checkId(id) {
+    if (!(id instanceof Uint8Array) || id.length !== SUBSCRIPTION_ID_LEN) {
+        throw new Error(`subscription id must be exactly ${SUBSCRIPTION_ID_LEN} bytes`);
+    }
+    return id;
+}
+function toSecs(n) {
+    return typeof n === "bigint" ? n : BigInt(Math.floor(n));
+}
+// ---------------------------------------------------------------------------
+// pure helpers (mirror the program's)
+// ---------------------------------------------------------------------------
+/** The next due time after a charge at `now >= nextDueAt`: the first slot of
+ *  the creation-anchored schedule strictly after `now` (the program's
+ *  `sub_next_due_at`). One charge per period; missed periods are forfeited. */
+export function subNextDueAt(nextDueAt, periodSecs, now) {
+    const n = toSecs(now);
+    if (periodSecs <= 0n)
+        throw new Error("periodSecs must be positive");
+    if (n < nextDueAt)
+        throw new Error("not due yet");
+    const missed = (n - nextDueAt) / periodSecs;
+    return nextDueAt + periodSecs * (missed + 1n);
+}
+/** `amount × min(charges left, 12)` (unlimited = the full window),
+ *  saturating at u64::MAX: what `create_subscription` adds to the shared
+ *  approval and sets as the subscription's `allowanceLeft`. (A payer-signed
+ *  `cancel_subscription` gives back the stored `allowanceLeft`, not this.) */
+export function subWindowAllowance(amount, maxCharges, chargesMade = 0) {
+    let left = SUB_APPROVE_WINDOW_CHARGES;
+    if (maxCharges !== 0) {
+        const remaining = BigInt(Math.max(0, maxCharges - chargesMade));
+        if (remaining < left)
+            left = remaining;
+    }
+    const v = amount * left;
+    return v > U64_MAX ? U64_MAX : v;
+}
+/** Whether a raw mint account (owned by `owner`) may back a subscription:
+ *  any classic SPL mint; a Token-2022 mint only with extensions in
+ *  {@link SUB_ALLOWED_MINT_EXTENSIONS} (the program's
+ *  `sub_mint_extensions_allowed`). */
+export function isSubscriptionMintSupported(data, owner) {
+    if (owner !== TOKEN_2022_PROGRAM || data.length <= 82)
+        return true;
+    if (data.length <= 165 || data[165] !== 1)
+        return false;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let o = 166;
+    while (o + 4 <= data.length) {
+        const t = dv.getUint16(o, true);
+        const len = dv.getUint16(o + 2, true);
+        if (t === 0)
+            break;
+        if (o + 4 + len > data.length || !SUB_ALLOWED_MINT_EXTENSIONS.includes(t))
+            return false;
+        o += 4 + len;
+    }
+    return true;
+}
+/** 16 fresh random bytes for a new subscription id (CSPRNG). */
+export function newSubscriptionId() {
+    const c = globalThis.crypto;
+    if (!c?.getRandomValues)
+        throw new Error("No CSPRNG available (globalThis.crypto.getRandomValues)");
+    return c.getRandomValues(new Uint8Array(SUBSCRIPTION_ID_LEN));
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+/** A subscription: `["sub", payer, payee, id]`. */
+export async function findSubscriptionPda(find, programId, payer, payee, id) {
+    return find([TE.encode(SUBSCRIPTION_SEED), toBytes32(payer, "payer"), toBytes32(payee, "payee"), checkId(id)], toBase58(programId, "programId"));
+}
+/** The payer's SPL delegate for every subscription: `["sub_delegate", payer]`. */
+export async function findSubDelegatePda(find, programId, payer) {
+    return find([TE.encode(SUB_DELEGATE_SEED), toBytes32(payer, "payer")], toBase58(programId, "programId"));
+}
+/** The payer's ledger of Active subscription shares in one mint:
+ *  `["sub_ledger", payer, mint]`. */
+export async function findSubLedgerPda(find, programId, payer, mint) {
+    return find([TE.encode(SUB_LEDGER_SEED), toBytes32(payer, "payer"), toBytes32(mint, "mint")], toBase58(programId, "programId"));
+}
+const STATUS_NAMES = ["active", "cancelled"];
+/**
+ * Decode a raw `Subscription` (discriminator included) in the Borsh order of
+ * state.rs: version u8 | payer | payee | id [u8;16] | mint | decimals u8 |
+ * amount u64 | period_secs i64 | next_due_at i64 | max_charges u32 |
+ * charges_made u32 | status u8 | created_at i64 | last_charged_at i64 |
+ * handle Option<Pubkey> | memo_hash [u8;32] | bump u8 | delegate_bump u8 |
+ * allowance_left u64 (version 2; a version-1 account decodes with
+ * `allowanceLeft = 0n`). Null when the bytes are not a `Subscription`.
+ */
+export function decodeSubscription(data) {
+    const O = SUBSCRIPTION_OFFSETS;
+    if (!hasPrefix(data, SUBSCRIPTION_ACCOUNT_DISCRIMINATOR) || data.length < O.handle + 1)
+        return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const pk = (o) => encodeBase58(data.slice(o, o + 32));
+    const status = STATUS_NAMES[data[O.status]];
+    if (status === undefined)
+        return null;
+    const tag = data[O.handle];
+    if (tag > 1)
+        return null;
+    let o = O.handle + 1;
+    let handle = null;
+    if (tag === 1) {
+        if (data.length < o + 32)
+            return null;
+        handle = pk(o);
+        o += 32;
+    }
+    if (data.length < o + 32 + 2)
+        return null;
+    const version = data[O.version];
+    let allowanceLeft = 0n;
+    if (version >= 2) {
+        if (data.length < o + 34 + 8)
+            return null;
+        allowanceLeft = dv.getBigUint64(o + 34, true);
+    }
+    return {
+        version,
+        payer: pk(O.payer),
+        payee: pk(O.payee),
+        id: data.slice(O.id, O.id + SUBSCRIPTION_ID_LEN),
+        mint: pk(O.mint),
+        decimals: data[O.decimals],
+        amount: dv.getBigUint64(O.amount, true),
+        periodSecs: dv.getBigInt64(O.periodSecs, true),
+        nextDueAt: dv.getBigInt64(O.nextDueAt, true),
+        maxCharges: dv.getUint32(O.maxCharges, true),
+        chargesMade: dv.getUint32(O.chargesMade, true),
+        status,
+        createdAt: dv.getBigInt64(O.createdAt, true),
+        lastChargedAt: dv.getBigInt64(O.lastChargedAt, true),
+        handle,
+        memoHash: data.slice(o, o + 32),
+        bump: data[o + 32],
+        delegateBump: data[o + 33],
+        allowanceLeft,
+    };
+}
+/** Borsh-encode a {@link Subscription} exactly as the program stores it (the
+ *  inverse of {@link decodeSubscription}, zero-padded to the allocation). */
+export function encodeSubscription(s) {
+    const status = STATUS_NAMES.indexOf(s.status);
+    if (status < 0)
+        throw new Error("bad status");
+    if (s.memoHash.length !== 32)
+        throw new Error("memoHash must be exactly 32 bytes");
+    const body = concat(SUBSCRIPTION_ACCOUNT_DISCRIMINATOR, Uint8Array.of(s.version), toBytes32(s.payer, "payer"), toBytes32(s.payee, "payee"), checkId(s.id), toBytes32(s.mint, "mint"), Uint8Array.of(s.decimals), u64le(s.amount), i64le(s.periodSecs), i64le(s.nextDueAt), u32le(s.maxCharges), u32le(s.chargesMade), Uint8Array.of(status), i64le(s.createdAt), i64le(s.lastChargedAt), s.handle === null ? Uint8Array.of(0) : concat(Uint8Array.of(1), toBytes32(s.handle, "handle")), s.memoHash, Uint8Array.of(s.bump, s.delegateBump), s.version >= 2 ? u64le(s.allowanceLeft) : new Uint8Array(0));
+    const out = new Uint8Array(Math.max(SUBSCRIPTION_ACCOUNT_LEN, body.length));
+    out.set(body);
+    return out;
+}
+/** Decode a raw `SubLedger` (discriminator included): version u8 | payer |
+ *  mint | total u64 | bump u8. Null when the bytes are not a `SubLedger`. */
+export function decodeSubLedger(data) {
+    const O = SUB_LEDGER_OFFSETS;
+    if (!hasPrefix(data, SUB_LEDGER_ACCOUNT_DISCRIMINATOR) || data.length < SUB_LEDGER_ACCOUNT_LEN)
+        return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return {
+        version: data[O.version],
+        payer: encodeBase58(data.slice(O.payer, O.payer + 32)),
+        mint: encodeBase58(data.slice(O.mint, O.mint + 32)),
+        total: dv.getBigUint64(O.total, true),
+        bump: data[O.bump],
+    };
+}
+/** Borsh-encode a {@link SubLedger} exactly as the program stores it. */
+export function encodeSubLedger(l) {
+    if (typeof l.total !== "bigint" || l.total < 0n || l.total > U64_MAX)
+        throw new Error("total must be a u64 bigint");
+    return concat(SUB_LEDGER_ACCOUNT_DISCRIMINATOR, Uint8Array.of(l.version), toBytes32(l.payer, "payer"), toBytes32(l.mint, "mint"), u64le(l.total), Uint8Array.of(l.bump));
+}
+/** Read and decode a payer's `SubLedger`. Null when it does not exist yet
+ *  (no subscription in that mint so far); throws when it exists but is not
+ *  one (or, with `programId`, is not owned by it). */
+export async function fetchSubLedger(rpc, address, opts = {}) {
+    const addr = toBase58(address, "address");
+    const res = (await rpc("getAccountInfo", [addr, { encoding: "base64", commitment: opts.commitment ?? "confirmed" }]));
+    const v = res?.value;
+    if (!v)
+        return null;
+    if (opts.programId !== undefined && v.owner !== toBase58(opts.programId, "programId")) {
+        throw new Error("account is not owned by the registry program");
+    }
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    const ledger = decodeSubLedger(data);
+    if (!ledger)
+        throw new Error("account is not an X1ID subscription ledger");
+    return { address: addr, ledger, lamports: BigInt(v.lamports) };
+}
+/** Whether every allowed charge has been made (`maxCharges > 0`). */
+export function isSubscriptionFinished(s) {
+    return s.maxCharges !== 0 && s.chargesMade >= s.maxCharges;
+}
+/** Whether `charge_subscription` would pass its status/schedule checks at
+ *  `nowSecs` (Active, charges left, `now >= nextDueAt`). The allowance,
+ *  balance, binding and lockdown are checked on chain. */
+export function isSubscriptionDue(s, nowSecs) {
+    return s.status === "active" && !isSubscriptionFinished(s) && toSecs(nowSecs) >= s.nextDueAt;
+}
+/** Read and decode a Subscription. Null when it does not exist; throws when
+ *  it exists but is not one (or, with `programId`, is not owned by it). */
+export async function fetchSubscription(rpc, address, opts = {}) {
+    const addr = toBase58(address, "address");
+    const res = (await rpc("getAccountInfo", [addr, { encoding: "base64", commitment: opts.commitment ?? "confirmed" }]));
+    const v = res?.value;
+    if (!v)
+        return null;
+    if (opts.programId !== undefined && v.owner !== toBase58(opts.programId, "programId")) {
+        throw new Error("account is not owned by the registry program");
+    }
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    const subscription = decodeSubscription(data);
+    if (!subscription)
+        throw new Error("account is not an X1ID subscription");
+    return { address: addr, subscription, lamports: BigInt(v.lamports) };
+}
+// ---------------------------------------------------------------------------
+// instruction builders
+// ---------------------------------------------------------------------------
+function bindingKeys(b) {
+    const out = [key(b.handle, "handle", false, false), key(b.payeeRecord, "payeeRecord", false, false)];
+    if (b.pnftTokenAccount !== undefined)
+        out.push(key(b.pnftTokenAccount, "pnftTokenAccount", false, false));
+    if (b.namespace !== undefined)
+        out.push(key(b.namespace, "namespace", false, false));
+    return out;
+}
+/** The Borsh arguments of `create_subscription` (after the discriminator). */
+export function encodeCreateSubscriptionArgs(a) {
+    if (typeof a.amount !== "bigint" || a.amount <= 0n || a.amount > U64_MAX) {
+        throw new Error("amount must be a u64 bigint greater than zero");
+    }
+    if (typeof a.periodSecs !== "bigint" || a.periodSecs < SUB_PERIOD_MIN_SECS || a.periodSecs > SUB_PERIOD_MAX_SECS) {
+        throw new Error(`periodSecs must be between ${SUB_PERIOD_MIN_SECS} and ${SUB_PERIOD_MAX_SECS} seconds`);
+    }
+    if (typeof a.firstDueAt !== "bigint" || a.firstDueAt < 0n || a.firstDueAt > I64_MAX) {
+        throw new Error("firstDueAt must be a non-negative i64 bigint (0n = now)");
+    }
+    if (!Number.isInteger(a.maxCharges) || a.maxCharges < 0 || a.maxCharges > U32_MAX) {
+        throw new Error("maxCharges must be a u32 (0 = unlimited)");
+    }
+    if (a.memoHash.length !== 32)
+        throw new Error("memoHash must be exactly 32 bytes");
+    return concat(checkId(a.id), toBytes32(a.mint, "mint"), u64le(a.amount), i64le(a.periodSecs), i64le(a.firstDueAt), u32le(a.maxCharges), a.memoHash, Uint8Array.of(a.bindHandle ? 1 : 0));
+}
+/**
+ * `create_subscription(id, mint, amount, period_secs, first_due_at,
+ * max_charges, memo_hash, bind_handle)`. Accounts (`CreateSubscription`):
+ * payer(s,w), payee, config, subscription(w), sub_delegate, sub_ledger(w),
+ * mint, payer_token_account(w), token_program, system_program, then the
+ * optional handle, payee_record and the binding's remaining accounts.
+ *
+ * The program records {@link subWindowAllowance} as the subscription's own
+ * `allowanceLeft`, adds it to the payer's ledger and approves `subDelegate`
+ * on `payerTokenAccount` for EXACTLY the new ledger total (the sum of every
+ * Active share in the mint), so the wallet shows that delegate approval.
+ * Fails with `SubscriptionDelegateInUse` (6143) if the ATA has another app's
+ * delegate; prepend an SPL `Revoke` if the payer agrees. Refuses `payee` =
+ * `subDelegate` (6230: funds sent there could never move).
+ */
+export function buildCreateSubscriptionIx(p) {
+    const payer = toBase58(p.payer, "payer");
+    const payee = toBase58(p.payee, "payee");
+    if (payer === payee)
+        throw new Error("payer and payee must differ");
+    if (payee === toBase58(p.subDelegate, "subDelegate")) {
+        throw new Error("payee cannot be the payer's subscription delegate PDA (SubscriptionPayeeIsDelegate)");
+    }
+    const keys = [
+        key(payer, "payer", true, true),
+        key(payee, "payee", false, false),
+        key(p.config, "config", false, false),
+        key(p.subscription, "subscription", false, true),
+        key(p.subDelegate, "subDelegate", false, false),
+        key(p.subLedger, "subLedger", false, true),
+        key(p.mint, "mint", false, false),
+        key(p.payerTokenAccount, "payerTokenAccount", false, true),
+        key(p.tokenProgram, "tokenProgram", false, false),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ];
+    if (p.bindHandle !== undefined)
+        keys.push(...bindingKeys(p.bindHandle));
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: concat(CREATE_SUBSCRIPTION_DISCRIMINATOR, encodeCreateSubscriptionArgs({
+            id: p.id,
+            mint: p.mint,
+            amount: p.amount,
+            periodSecs: p.periodSecs,
+            firstDueAt: p.firstDueAt ?? 0n,
+            maxCharges: p.maxCharges ?? 0,
+            memoHash: p.memoHash ?? new Uint8Array(32),
+            bindHandle: p.bindHandle !== undefined,
+        })),
+    };
+}
+/**
+ * `charge_subscription()`: no arguments; the program reads every term from
+ * the Subscription. Accounts (`ChargeSubscription`): cranker(s,w),
+ * subscription(w), config, treasury, pay_config, sub_delegate,
+ * sub_ledger(w), mint, payer_token_account(w), payee_token_account(w),
+ * treasury_token_account(w), token_program, associated_token_program,
+ * system_program, then the optional handle, payee_record and the binding's
+ * remaining accounts. After an outside revoke of the payer's approval every
+ * charge fails with 6147 until the payer's next create / top-up.
+ */
+export function buildChargeSubscriptionIx(p) {
+    const keys = [
+        key(p.cranker, "cranker", true, true),
+        key(p.subscription, "subscription", false, true),
+        key(p.config, "config", false, false),
+        key(p.treasury, "treasury", false, false),
+        key(p.payConfig, "payConfig", false, false),
+        key(p.subDelegate, "subDelegate", false, false),
+        key(p.subLedger, "subLedger", false, true),
+        key(p.mint, "mint", false, false),
+        key(p.payerTokenAccount, "payerTokenAccount", false, true),
+        key(p.payeeTokenAccount, "payeeTokenAccount", false, true),
+        key(p.treasuryTokenAccount, "treasuryTokenAccount", false, true),
+        key(p.tokenProgram, "tokenProgram", false, false),
+        key(ASSOCIATED_TOKEN_PROGRAM, "associatedTokenProgram", false, false),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ];
+    if (p.binding !== undefined)
+        keys.push(...bindingKeys(p.binding));
+    return { programId: toBase58(p.programId, "programId"), keys, data: CHARGE_SUBSCRIPTION_DISCRIMINATOR.slice() };
+}
+/** `cancel_subscription()`. Accounts (`CancelSubscription`): signer(s),
+ *  subscription(w), sub_ledger(w) (the program id as "None" when `null`),
+ *  then the optional payer_token_account(w), sub_delegate, token_program
+ *  (used only when the payer signs). */
+export function buildCancelSubscriptionIx(p) {
+    if (p.subLedger === undefined)
+        throw new Error("subLedger is required (null only for a legacy v2 subscription)");
+    if (p.subLedger === null && p.giveBack !== undefined)
+        throw new Error("giveBack needs the subLedger");
+    const programId = toBase58(p.programId, "programId");
+    const keys = [
+        key(p.signer, "signer", true, false),
+        key(p.subscription, "subscription", false, true),
+        p.subLedger === null ? key(programId, "subLedger", false, false) : key(p.subLedger, "subLedger", false, true),
+    ];
+    if (p.giveBack !== undefined) {
+        keys.push(key(p.giveBack.payerTokenAccount, "payerTokenAccount", false, true), key(p.giveBack.subDelegate, "subDelegate", false, false), key(p.giveBack.tokenProgram, "tokenProgram", false, false));
+    }
+    return { programId, keys, data: CANCEL_SUBSCRIPTION_DISCRIMINATOR.slice() };
+}
+/** `close_subscription()`. Accounts (`CloseSubscription`): signer(s),
+ *  subscription(w), payer(w). Only once Cancelled or finished. */
+export function buildCloseSubscriptionIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.signer, "signer", true, false),
+            key(p.subscription, "subscription", false, true),
+            key(p.payer, "payer", false, true),
+        ],
+        data: CLOSE_SUBSCRIPTION_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * `top_up_subscription(amount)`: raise ONE subscription's `allowanceLeft`
+ * and the payer's ledger total by `amount`, then approve the payer's
+ * delegate PDA for EXACTLY the new ledger total (also restoring the pool
+ * after an outside revoke). Accounts (`TopUpSubscription`): payer(s,w),
+ * subscription(w), config, sub_delegate, sub_ledger(w),
+ * payer_token_account(w), token_program, system_program. Payer only; Active
+ * and not finished; refused during lockdown and when the ATA has another
+ * app's delegate (6143).
+ */
+export function buildTopUpSubscriptionIx(p) {
+    if (typeof p.amount !== "bigint" || p.amount <= 0n || p.amount > U64_MAX) {
+        throw new Error("amount must be a u64 bigint greater than zero");
+    }
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.payer, "payer", true, true),
+            key(p.subscription, "subscription", false, true),
+            key(p.config, "config", false, false),
+            key(p.subDelegate, "subDelegate", false, false),
+            key(p.subLedger, "subLedger", false, true),
+            key(p.payerTokenAccount, "payerTokenAccount", false, true),
+            key(p.tokenProgram, "tokenProgram", false, false),
+            key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data: concat(TOP_UP_SUBSCRIPTION_DISCRIMINATOR, u64le(p.amount)),
+    };
+}
+/** A plain SPL `Approve` (instruction 4, same bytes under both token
+ *  programs) of the payer's delegate PDA: a precise re-approve, e.g. to cut
+ *  the surplus a payee-cancelled subscription left back to the ledger total.
+ *  It does NOT extend a subscription (each charge also needs the
+ *  subscription's own `allowanceLeft`); use {@link buildTopUpSubscriptionIx}
+ *  for that (it also re-approves the ledger total). */
+export function buildSubscriptionAllowanceIx(p) {
+    if (typeof p.allowance !== "bigint" || p.allowance < 0n || p.allowance > U64_MAX) {
+        throw new Error("allowance must be a u64 bigint");
+    }
+    return {
+        programId: toBase58(p.tokenProgram, "tokenProgram"),
+        keys: [
+            key(p.payerTokenAccount, "payerTokenAccount", false, true),
+            key(p.subDelegate, "subDelegate", false, false),
+            key(p.payer, "payer", true, false),
+        ],
+        data: concat(Uint8Array.of(4), u64le(p.allowance)),
+    };
+}
+/** Plain-language sentence for a subscription error code (6138-6150,
+ *  6230, 6233-6235), or null (see `payErrorMessage` for the shared Pay codes). */
+export function subscriptionErrorMessage(code) {
+    switch (code) {
+        case 6138: return "A subscription amount must be greater than zero.";
+        case 6139: return "The billing period must be between 1 hour and 5 years.";
+        case 6140: return "The first charge must be now or a future date within 5 years.";
+        case 6141: return "This token can't be used for subscriptions (its extensions could change what a charge pays).";
+        case 6142: return "You can't subscribe to yourself.";
+        case 6143: return "Your token account already has another app's spending approval. Revoke it first.";
+        case 6144: return "This subscription is cancelled.";
+        case 6145: return "The next charge isn't due yet.";
+        case 6146: return "This subscription has made all its charges.";
+        case 6147: return "This subscription's spending approval is used up or revoked. Top it up to continue.";
+        case 6148: return "The payer's token account doesn't match this subscription.";
+        case 6149: return "Only the subscriber or the merchant can do this.";
+        case 6150: return "This subscription is still active. Cancel it first.";
+        case 6230: return "A subscription can't pay to your own subscription delegate address.";
+        case 6233: return "That top-up is more than the remaining charges can use.";
+        case 6234: return "This subscription needs its subscription ledger. If it is an older subscription, top it up once to continue.";
+        case 6235: return "The total of your subscriptions in this token is out of range.";
+        default: return null;
+    }
+}