@x1id/resolve 0.23.0 → 0.44.0

package/dist/agentPolicy.js

@@ -0,0 +1,364 @@
+/**
+ * Agent spend policies enforced by the registry (program upgrade 6,
+ * OpenProject #8456; spec docs/specs/agent-spend-policy.md).
+ *
+ * The current authority of an `@name` (untokenized owner, or the pNFT holder)
+ * authorises an agent wallet under a policy bound to the name:
+ * `["agent_policy", handle, agent]` holds per-mint caps per rolling period
+ * (native XNT = {@link AGENT_POLICY_NATIVE_MINT}), an expiry and an optional
+ * recipient allow-list. Native XNT is spent from the policy PDA's float (its
+ * lamports above rent); SPL / Token-2022 from a grantor token account through
+ * the policy's OWN delegate `["agent_delegate", policy, createdSlot]`, which
+ * the grantor approves with a plain SPL `Approve`
+ * ({@link buildApproveAgentDelegateIx}). One delegate per policy (Sentinel
+ * run-012 A-04): an allowance approved for one agent's policy can never be
+ * spent by another agent. One delegate per CREATION (D-02): the policy's
+ * `createdSlot` is a seed, so an approval left behind by a revoked policy
+ * can never re-arm when the same `(handle, agent)` policy is created again. A token account has
+ * one delegate, so give each agent (policy) its own token account per mint.
+ *
+ * Kill switches: lock the name (`lock_handle`, lock.ts) — every spend fails
+ * at once; {@link buildRevokeAgentPolicyIx} (works during lockdown and while
+ * locked); {@link buildWithdrawAgentFloatIx}; SPL `Revoke`.
+ *
+ * Tokenized names: pass `holderTokenAccount` (the grantor's canonical pNFT ATA)
+ * to create / update / spend; it is the program's `remaining_accounts[0]`
+ * authority proof.
+ *
+ * Hand-rolled like the rest of this package: no Anchor client, no web3.js.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+export const AGENT_POLICY_SEED = "agent_policy";
+export const AGENT_DELEGATE_SEED = "agent_delegate";
+/** The "mint" a native-XNT cap is written under (all-zero pubkey). */
+export const AGENT_POLICY_NATIVE_MINT = "11111111111111111111111111111111";
+export const AGENT_MAX_CAPS = 4;
+export const AGENT_MAX_RECIPIENTS = 4;
+export const AGENT_PERIOD_MIN_SECS = 60;
+export const AGENT_PERIOD_MAX_SECS = 366 * 24 * 60 * 60;
+/** `8 + AgentPolicy::INIT_SPACE` (layout v2: `created_slot` appended). */
+export const AGENT_POLICY_ACCOUNT_LEN = 525;
+/** `AGENT_POLICY_VERSION` of the accounts this decoder reads. */
+export const AGENT_POLICY_LAYOUT_VERSION = 2;
+/** `sha256("global:<name>")[0..8]`, pinned + re-derived in the tests. */
+export const CREATE_AGENT_POLICY_DISCRIMINATOR = Uint8Array.from([68, 244, 90, 9, 10, 95, 248, 78]);
+export const UPDATE_AGENT_POLICY_DISCRIMINATOR = Uint8Array.from([55, 6, 173, 243, 185, 119, 129, 149]);
+export const FUND_AGENT_POLICY_DISCRIMINATOR = Uint8Array.from([124, 198, 77, 243, 75, 95, 114, 231]);
+export const WITHDRAW_AGENT_FLOAT_DISCRIMINATOR = Uint8Array.from([60, 8, 24, 156, 55, 183, 129, 174]);
+export const REVOKE_AGENT_POLICY_DISCRIMINATOR = Uint8Array.from([230, 27, 101, 136, 225, 188, 175, 202]);
+export const AGENT_SPEND_NATIVE_DISCRIMINATOR = Uint8Array.from([16, 112, 180, 241, 96, 128, 78, 177]);
+export const AGENT_SPEND_SPL_DISCRIMINATOR = Uint8Array.from([19, 25, 249, 214, 32, 65, 131, 201]);
+/** `sha256("account:AgentPolicy")[0..8]`. */
+export const AGENT_POLICY_ACCOUNT_DISCRIMINATOR = Uint8Array.from([148, 193, 218, 129, 21, 96, 195, 77]);
+/** Program error codes (AgentPolicyError, offset 6190). */
+export const AGENT_POLICY_ERRORS = {
+    6190: "AgentPolicyInvalidTerms",
+    6191: "AgentPolicyTooManyEntries",
+    6192: "AgentPolicyExpired",
+    6193: "AgentPolicyStale",
+    6194: "AgentPolicyNotAgent",
+    6195: "AgentPolicyMintNotAllowed",
+    6196: "AgentPolicyCapExceeded",
+    6197: "AgentPolicyRecipientNotAllowed",
+    6198: "AgentPolicyFloatInsufficient",
+    6199: "AgentPolicyNotGrantor",
+    6200: "AgentPolicyTokenAccountMismatch",
+    6201: "AgentPolicyAllowanceExhausted",
+    6202: "AgentPolicyAmountZero",
+    6203: "AgentPolicyRevokeNotAllowed",
+};
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const TE = new TextEncoder();
+const U64_MAX = 0xffffffffffffffffn;
+function b58(v, what) {
+    return encodeBase58(bytes(v, what));
+}
+function bytes(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 k(v, what, isSigner, isWritable) {
+    return { pubkey: b58(v, what), isSigner, isWritable };
+}
+function cat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function u64(v, what) {
+    if (typeof v !== "bigint" || v < 0n || v > U64_MAX)
+        throw new Error(`${what} must be a u64 bigint`);
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, v, true);
+    return out;
+}
+function i64(v, what) {
+    if (typeof v !== "bigint" || v < -(1n << 63n) || v >= 1n << 63n)
+        throw new Error(`${what} must be an i64 bigint`);
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, v, true);
+    return out;
+}
+function u32(n) {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, n, true);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+/** `["agent_policy", handle, agent]`. */
+export async function deriveAgentPolicyPda(find, programId, handle, agent) {
+    return find([TE.encode(AGENT_POLICY_SEED), bytes(handle, "handle"), bytes(agent, "agent")], b58(programId, "programId"));
+}
+/**
+ * `["agent_delegate", policy, createdSlot (u64 LE)]` — the policy's own SPL
+ * delegate, which the grantor approves on the token account that policy's
+ * agent spends from. `createdSlot` is the policy's generation: read it from
+ * the account ({@link decodeAgentPolicy}`(…).createdSlot`) after
+ * `create_agent_policy` lands. A re-created policy (same address) has a new
+ * `createdSlot`, hence a new delegate (Sentinel run-012 D-02). Since 0.41.0;
+ * 0.40 used `["agent_delegate", policy]`, 0.38–0.39 the grantor (neither on
+ * mainnet).
+ */
+export async function deriveAgentDelegatePda(find, programId, agentPolicy, createdSlot) {
+    return find([TE.encode(AGENT_DELEGATE_SEED), bytes(agentPolicy, "agentPolicy"), u64(createdSlot, "createdSlot")], b58(programId, "programId"));
+}
+/** Client-side mirror of the program's `validate_terms` (null = valid). */
+export function agentPolicyTermsProblem(t, nowSecs) {
+    const rec = t.recipients ?? [];
+    if (t.caps.length > AGENT_MAX_CAPS || rec.length > AGENT_MAX_RECIPIENTS)
+        return "at most 4 caps and 4 recipients";
+    if (t.caps.length === 0)
+        return "at least one cap is required";
+    if (t.expiresAt <= nowSecs)
+        return "expiry must be in the future";
+    if (t.periodSecs < BigInt(AGENT_PERIOD_MIN_SECS) || t.periodSecs > BigInt(AGENT_PERIOD_MAX_SECS)) {
+        return "period must be between 60 seconds and 366 days";
+    }
+    const mints = t.caps.map((c) => b58(c.mint, "cap mint"));
+    if (new Set(mints).size !== mints.length)
+        return "duplicate mint in caps";
+    if (t.caps.some((c) => c.cap <= 0n))
+        return "every cap must be > 0";
+    const rs = rec.map((r) => b58(r, "recipient"));
+    if (new Set(rs).size !== rs.length)
+        return "duplicate recipient";
+    if (rs.includes(SYSTEM_PROGRAM))
+        return "the default pubkey is not a recipient";
+    return null;
+}
+/** Borsh `AgentPolicyTerms { expires_at, period_secs, caps: Vec<{mint,cap}>, recipients: Vec<Pubkey> }`. */
+export function encodeAgentPolicyTerms(t) {
+    const rec = t.recipients ?? [];
+    return cat(i64(t.expiresAt, "expiresAt"), i64(t.periodSecs, "periodSecs"), u32(t.caps.length), ...t.caps.flatMap((c) => [bytes(c.mint, "cap mint"), u64(c.cap, "cap")]), u32(rec.length), ...rec.map((r) => bytes(r, "recipient")));
+}
+function proof(p, who) {
+    return p.holderTokenAccount === undefined ? [] : [k(p.holderTokenAccount, `${who} holderTokenAccount`, false, false)];
+}
+/** `create_agent_policy(agent, terms)`: grantor(s,w), handle, config, agent_policy(w), system [+ holder ATA]. */
+export function buildCreateAgentPolicyIx(p) {
+    const problem = agentPolicyTermsProblem(p.terms, p.nowSecs ?? BigInt(Math.floor(Date.now() / 1000)));
+    if (problem)
+        throw new Error(problem);
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.grantor, "grantor", true, true),
+            k(p.handle, "handle", false, false),
+            k(p.config, "config", false, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            k(SYSTEM_PROGRAM, "systemProgram", false, false),
+            ...proof(p, "create"),
+        ],
+        data: cat(CREATE_AGENT_POLICY_DISCRIMINATOR, bytes(p.agent, "agent"), encodeAgentPolicyTerms(p.terms)),
+    };
+}
+/** `update_agent_policy(terms)`: grantor(s), handle, config, agent_policy(w) [+ holder ATA]. */
+export function buildUpdateAgentPolicyIx(p) {
+    const problem = agentPolicyTermsProblem(p.terms, p.nowSecs ?? BigInt(Math.floor(Date.now() / 1000)));
+    if (problem)
+        throw new Error(problem);
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.grantor, "grantor", true, false),
+            k(p.handle, "handle", false, false),
+            k(p.config, "config", false, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            ...proof(p, "update"),
+        ],
+        data: cat(UPDATE_AGENT_POLICY_DISCRIMINATOR, encodeAgentPolicyTerms(p.terms)),
+    };
+}
+/** `fund_agent_policy(amount)`: grantor(s,w), config, agent_policy(w), system. */
+export function buildFundAgentPolicyIx(p) {
+    if (p.lamports <= 0n)
+        throw new Error("lamports must be > 0");
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.grantor, "grantor", true, true),
+            k(p.config, "config", false, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            k(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data: cat(FUND_AGENT_POLICY_DISCRIMINATOR, u64(p.lamports, "lamports")),
+    };
+}
+/** `withdraw_agent_float(amount)`: grantor(s,w), agent_policy(w). Always allowed. */
+export function buildWithdrawAgentFloatIx(p) {
+    if (p.lamports <= 0n)
+        throw new Error("lamports must be > 0");
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [k(p.grantor, "grantor", true, true), k(p.agentPolicy, "agentPolicy", false, true)],
+        data: cat(WITHDRAW_AGENT_FLOAT_DISCRIMINATOR, u64(p.lamports, "lamports")),
+    };
+}
+/** `revoke_agent_policy()`: signer(s), handle, agent_policy(w), grantor(w) [+ signer's pNFT ATA]. */
+export function buildRevokeAgentPolicyIx(p) {
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.signer, "signer", true, false),
+            k(p.handle, "handle", false, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            k(p.grantor, "grantor", false, true),
+            ...proof(p, "revoke"),
+        ],
+        data: REVOKE_AGENT_POLICY_DISCRIMINATOR.slice(),
+    };
+}
+/** `agent_spend_native(amount)`: agent(s), agent_policy(w), handle, config, recipient(w) [+ grantor's pNFT ATA]. */
+export function buildAgentSpendNativeIx(p) {
+    if (p.lamports <= 0n)
+        throw new Error("lamports must be > 0");
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.agent, "agent", true, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            k(p.handle, "handle", false, false),
+            k(p.config, "config", false, false),
+            k(p.recipient, "recipient", false, true),
+            ...proof(p, "spend"),
+        ],
+        data: cat(AGENT_SPEND_NATIVE_DISCRIMINATOR, u64(p.lamports, "lamports")),
+    };
+}
+/** `agent_spend_spl(amount)`: agent(s), agent_policy(w), handle, config, agent_delegate, mint, source(w), destination(w), token_program [+ grantor's pNFT ATA]. */
+export function buildAgentSpendSplIx(p) {
+    if (p.amount <= 0n)
+        throw new Error("amount must be > 0");
+    return {
+        programId: b58(p.programId, "programId"),
+        keys: [
+            k(p.agent, "agent", true, false),
+            k(p.agentPolicy, "agentPolicy", false, true),
+            k(p.handle, "handle", false, false),
+            k(p.config, "config", false, false),
+            k(p.agentDelegate, "agentDelegate", false, false),
+            k(p.mint, "mint", false, false),
+            k(p.source, "source", false, true),
+            k(p.destination, "destination", false, true),
+            k(p.tokenProgram, "tokenProgram", false, false),
+            ...proof(p, "spend"),
+        ],
+        data: cat(AGENT_SPEND_SPL_DISCRIMINATOR, u64(p.amount, "amount")),
+    };
+}
+/** SPL `Approve` (tag 4) of the agent delegate — signed by the grantor. */
+export function buildApproveAgentDelegateIx(p) {
+    return {
+        programId: b58(p.tokenProgram, "tokenProgram"),
+        keys: [k(p.source, "source", false, true), k(p.agentDelegate, "agentDelegate", false, false), k(p.grantor, "grantor", true, false)],
+        data: cat(Uint8Array.of(4), u64(p.amount, "amount")),
+    };
+}
+/**
+ * SPL `Revoke` (tag 5) — the grantor cuts the policy whose delegate is
+ * approved on that token account off it. `revoke_agent_policy` closes the
+ * policy but cannot clear the SPL approval (only the token-account owner
+ * can). The leftover approval names a delegate no policy can ever sign as
+ * again (re-creating the same `(handle, agent)` policy gets a new
+ * `createdSlot` and a new delegate), so an old approval can never re-arm;
+ * appending this still tidies the token account (it holds one delegate).
+ */
+export function buildRevokeAgentDelegateIx(p) {
+    return {
+        programId: b58(p.tokenProgram, "tokenProgram"),
+        keys: [k(p.source, "source", false, true), k(p.grantor, "grantor", true, false)],
+        data: Uint8Array.of(5),
+    };
+}
+/** Decode an `AgentPolicy` account (null when not one). */
+export function decodeAgentPolicy(data) {
+    if (data.length < AGENT_POLICY_ACCOUNT_LEN)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== AGENT_POLICY_ACCOUNT_DISCRIMINATOR[i])
+            return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const pk = (o) => encodeBase58(data.subarray(o, o + 32));
+    const capsLen = data[147];
+    const recLen = data[372];
+    if (capsLen > AGENT_MAX_CAPS || recLen > AGENT_MAX_RECIPIENTS)
+        return null;
+    const caps = [];
+    for (let i = 0; i < capsLen; i++) {
+        const o = 148 + 56 * i;
+        const mint = pk(o);
+        caps.push({ mint, native: mint === AGENT_POLICY_NATIVE_MINT, cap: dv.getBigUint64(o + 32, true), spent: dv.getBigUint64(o + 40, true), periodStart: dv.getBigInt64(o + 48, true) });
+    }
+    const recipients = [];
+    for (let i = 0; i < recLen; i++)
+        recipients.push(pk(373 + 32 * i));
+    return {
+        version: data[8],
+        bump: data[9],
+        delegateBump: data[10],
+        handle: pk(11),
+        agent: pk(43),
+        grantor: pk(75),
+        epoch: dv.getBigInt64(107, true),
+        createdAt: dv.getBigInt64(115, true),
+        updatedAt: dv.getBigInt64(123, true),
+        expiresAt: dv.getBigInt64(131, true),
+        periodSecs: dv.getBigInt64(139, true),
+        caps,
+        recipients,
+        totalSpends: dv.getBigUint64(501, true),
+        lastSpentAt: dv.getBigInt64(509, true),
+        createdSlot: dv.getBigUint64(517, true),
+    };
+}
+/**
+ * What the agent may still spend of `mint` at `nowSecs` (the program's
+ * `roll_period` applied): null when the mint has no cap. Does NOT include
+ * the float / SPL allowance bound, the lock, or the policy's liveness.
+ */
+export function agentPolicyRemaining(p, mint, nowSecs) {
+    const m = b58(mint, "mint");
+    const c = p.caps.find((x) => x.mint === m);
+    if (!c)
+        return null;
+    let start = c.periodStart;
+    let spent = c.spent;
+    if (p.periodSecs > 0n && nowSecs >= start && nowSecs - start >= p.periodSecs) {
+        start += ((nowSecs - start) / p.periodSecs) * p.periodSecs;
+        spent = 0n;
+    }
+    return { remaining: c.cap > spent ? c.cap - spent : 0n, periodEndsAt: start + p.periodSecs, expired: nowSecs >= p.expiresAt };
+}

package/dist/attestation.d.ts

@@ -120,6 +120,8 @@ export declare const SET_ATTESTOR_DISCRIMINATOR: Uint8Array;
 export declare const CREATE_ATTESTATION_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator: `sha256("global:close_attestation")[0..8]`. */
 export declare const CLOSE_ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:remove_own_attestation")[0..8]`. */
+export declare const REMOVE_OWN_ATTESTATION_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator: `sha256("global:attest_validator")[0..8]` — the co-sign path. */
 export declare const ATTEST_VALIDATOR_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator: `sha256("global:attest_validator_signed")[0..8]` — the detached path. */
@@ -356,6 +358,29 @@ export interface CloseAttestationParams {
  * a rotated-away key's output).
  */
 export declare function buildCloseAttestationIx(p: CloseAttestationParams): BuiltInstruction;
+export interface RemoveOwnAttestationParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's current authority (any kind), or — for a validator link
+     *  only — the withdraw authority that proved it. Signer. */
+    readonly signer: AddressLike;
+    /** The handle PDA the attestation belongs to. */
+    readonly handle: AddressLike;
+    /** The `["attestation", handle, [kind]]` account being removed. */
+    readonly attestation: AddressLike;
+    /** Rent refund, pinned on chain: the attestation's stored `attestor` for an
+     *  attestor-minted kind (0–5), the `signer` for a validator link (6). */
+    readonly recipient: AddressLike;
+    /** ONLY for a tokenized handle signed by its holder: the holder's ATA for
+     *  the handle's NFT mint (the `require_current_authority` proof). */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `remove_own_attestation` — self-service removal of one of the
+ * handle's own attestations (unlink a validator, drop a social/DNS
+ * verification). Removing can only take a badge away, never forge one.
+ */
+export declare function buildRemoveOwnAttestationIx(p: RemoveOwnAttestationParams): BuiltInstruction;
 export interface AttestValidatorParams {
     /** The registry program id. */
     readonly programId: AddressLike;

package/dist/attestation.js

@@ -129,6 +129,10 @@ export const CREATE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
 export const CLOSE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
     249, 84, 133, 23, 48, 175, 252, 221,
 ]);
+/** Anchor instruction discriminator: `sha256("global:remove_own_attestation")[0..8]`. */
+export const REMOVE_OWN_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
+    211, 214, 29, 219, 165, 179, 35, 209,
+]);
 /** Anchor instruction discriminator: `sha256("global:attest_validator")[0..8]` — the co-sign path. */
 export const ATTEST_VALIDATOR_DISCRIMINATOR = Uint8Array.from([
     170, 159, 195, 248, 59, 130, 28, 168,
@@ -452,6 +456,27 @@ export function buildCloseAttestationIx(p) {
         data: CLOSE_ATTESTATION_DISCRIMINATOR.slice(),
     };
 }
+/**
+ * Build `remove_own_attestation` — self-service removal of one of the
+ * handle's own attestations (unlink a validator, drop a social/DNS
+ * verification). Removing can only take a badge away, never forge one.
+ */
+export function buildRemoveOwnAttestationIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.signer, "signer"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestation, "attestation"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: REMOVE_OWN_ATTESTATION_DISCRIMINATOR.slice(),
+    };
+}
 /**
  * Build `attest_validator` (co-sign path). Two signers — `owner` (authorizes
  * the link) and `withdrawAuthority` (the proof) — which MAY be the same key. No

package/dist/checkout.d.ts

@@ -0,0 +1,216 @@
+/**
+ * X1ID Pay checkout widget ([Pay 7], docs/x1id-pay-checkout.md): the
+ * postMessage protocol between a merchant page and the X1 Pay invoice page (app.x1pay.me),
+ * plus the merchant-side controller that opens the checkout popup.
+ *
+ * The widget only PAYS an invoice that already exists on chain. The merchant
+ * creates the invoice (itself, or with a merchant-delegate key on its server),
+ * opens checkout for it, and then verifies payment SERVER-SIDE by reading the
+ * Invoice account ({@link verifyInvoicePaid} in pay.ts). What this protocol
+ * reports back to the merchant's browser is a UX hint only: a browser result
+ * can be forged by anyone who controls the merchant's page, so it must never
+ * release goods by itself.
+ *
+ * Flow (all messages are plain JSON-able objects, see {@link CheckoutMessage}):
+ *
+ *   merchant page (origin M)              popup: X1 Pay app (origin A)
+ *   ───────────────────────               ──────────────────────────
+ *   window.open(A/invoice?address=…&embed=1&origin=M&sid=S)
+ *                                    ◀──  ready  {sid, invoice}   (targetOrigin M)
+ *   ack {sid}  (targetOrigin A)       ──▶
+ *                                    ◀──  result {sid, invoice, status, signature}
+ *   popup closed without a result → status "closed" (detected locally)
+ *
+ * Origin checks on BOTH sides:
+ * - the popup posts only to `window.opener` with `targetOrigin` = the
+ *   merchant origin it was opened for, so the browser drops the message if the
+ *   opener is anything else; it trusts an `ack` only when `event.source` is
+ *   its opener and `event.origin` is exactly that origin;
+ * - the merchant accepts a message only when `event.source` is the popup it
+ *   opened, `event.origin` is exactly the X1 Pay app origin, and the session id
+ *   (`sid`, 128 random bits per checkout) and invoice match.
+ *
+ * No iframe mode: the X1 Pay app keeps `frame-ancestors 'none'` /
+ * `X-Frame-Options: DENY` (clickjacking), and wallet extensions work in a
+ * top-level window.
+ *
+ * Dependency-free on purpose (no SDK imports), so the browser widget bundle
+ * stays tiny.
+ */
+/** Protocol tag on every message. */
+export declare const CHECKOUT_PROTOCOL = "x1id-checkout";
+/** Protocol version on every message. */
+export declare const CHECKOUT_VERSION = 1;
+/** Where the hosted checkout lives. */
+export declare const DEFAULT_CHECKOUT_APP_ORIGIN = "https://app.x1pay.me";
+/**
+ * - `paid`: the invoice page read the Invoice account back as Paid.
+ * - `cancelled`: the payer returned to the merchant without paying.
+ * - `closed`: the popup was closed without a result (merchant side only, never
+ *   sent over the wire).
+ */
+export type CheckoutStatus = "paid" | "cancelled" | "closed";
+/** What the merchant page learns. A HINT: verify on your server. */
+export interface CheckoutResult {
+    /** The invoice address (base58) this checkout was opened for. */
+    readonly invoice: string;
+    /** The payment transaction, when known (only with `paid`). */
+    readonly signature: string | null;
+    readonly status: CheckoutStatus;
+}
+export interface CheckoutReadyMessage {
+    readonly protocol: typeof CHECKOUT_PROTOCOL;
+    readonly version: typeof CHECKOUT_VERSION;
+    readonly type: "ready";
+    readonly sid: string;
+    readonly invoice: string;
+}
+export interface CheckoutAckMessage {
+    readonly protocol: typeof CHECKOUT_PROTOCOL;
+    readonly version: typeof CHECKOUT_VERSION;
+    readonly type: "ack";
+    readonly sid: string;
+}
+export interface CheckoutResultMessage {
+    readonly protocol: typeof CHECKOUT_PROTOCOL;
+    readonly version: typeof CHECKOUT_VERSION;
+    readonly type: "result";
+    readonly sid: string;
+    readonly invoice: string;
+    /** Only the two statuses the popup can report. */
+    readonly status: "paid" | "cancelled";
+    readonly signature: string | null;
+}
+export type CheckoutMessage = CheckoutReadyMessage | CheckoutAckMessage | CheckoutResultMessage;
+/** Shape check for a base58 account address (32-44 chars). */
+export declare function isCheckoutAddress(s: unknown): s is string;
+/** Shape check for a base58 transaction signature (64-88 chars). */
+export declare function isCheckoutSignature(s: unknown): s is string;
+/** A checkout session id: 32 lowercase hex chars (128 bits). */
+export declare function isCheckoutSid(s: unknown): s is string;
+/** 128 fresh random bits as a checkout session id (CSPRNG). */
+export declare function newCheckoutSid(): string;
+/**
+ * A web origin the protocol will talk to, or null. It must be exactly an
+ * origin (`scheme://host[:port]`, no path, query, fragment or credentials),
+ * `https:`, or `http:` on a loopback host for local development. `"null"`
+ * (sandboxed / `file:` pages) is refused: messages could not be pinned to it.
+ */
+export declare function normalizeCheckoutOrigin(raw: unknown): string | null;
+/**
+ * Parse an incoming `event.data` as a protocol message, or null. Strict:
+ * right protocol tag and version, a known `type`, only the fields that type
+ * carries, each well-formed. Says nothing about WHO sent it: check
+ * `event.origin` and `event.source` too (see {@link acceptCheckoutResult} and
+ * {@link acceptCheckoutAck}).
+ */
+export declare function parseCheckoutMessage(data: unknown): CheckoutMessage | null;
+export declare function checkoutReadyMessage(sid: string, invoice: string): CheckoutReadyMessage;
+export declare function checkoutAckMessage(sid: string): CheckoutAckMessage;
+export declare function checkoutResultMessage(p: {
+    readonly sid: string;
+    readonly invoice: string;
+    readonly status: "paid" | "cancelled";
+    readonly signature: string | null;
+}): CheckoutResultMessage;
+/** The parts of a `MessageEvent` the checks read. */
+export interface CheckoutEventLike {
+    readonly origin: string;
+    readonly source: unknown;
+    readonly data: unknown;
+}
+/**
+ * Merchant side: the result carried by `ev`, or null unless it comes from
+ * exactly `expect.source` (the popup window this page opened) at exactly
+ * `expect.appOrigin`, for this checkout's `sid` and `invoice`.
+ */
+export declare function acceptCheckoutResult(ev: CheckoutEventLike, expect: {
+    readonly appOrigin: string;
+    readonly source: unknown;
+    readonly sid: string;
+    readonly invoice: string;
+}): CheckoutResult | null;
+/**
+ * Popup side: true when `ev` is this checkout's `ack`, sent by the window that
+ * opened the popup (`expect.opener`) from exactly `expect.origin`.
+ */
+export declare function acceptCheckoutAck(ev: CheckoutEventLike, expect: {
+    readonly origin: string;
+    readonly opener: unknown;
+    readonly sid: string;
+}): boolean;
+/** The hosted checkout URL for an invoice. */
+export declare function buildCheckoutUrl(p: {
+    readonly invoice: string;
+    /** The merchant page's own origin (`location.origin`). */
+    readonly origin: string;
+    readonly sid: string;
+    readonly appOrigin?: string;
+}): string;
+/** Popup side: the checkout parameters of an invoice page URL, or null when it
+ *  is not an embedded checkout (or any parameter is malformed). */
+export declare function parseCheckoutParams(get: (name: string) => string | null): {
+    readonly origin: string;
+    readonly sid: string;
+} | null;
+/** The popup window, as far as the controller uses it. */
+export interface CheckoutPopupLike {
+    readonly closed: boolean;
+    postMessage(message: unknown, targetOrigin: string): void;
+    close(): void;
+    focus?(): void;
+}
+/** The merchant window, as far as the controller uses it (`window` in a
+ *  browser; a fake in tests). */
+export interface CheckoutHostLike {
+    readonly location: {
+        readonly origin: string;
+    };
+    open(url: string, target: string, features: string): CheckoutPopupLike | null;
+    addEventListener(type: "message", listener: (ev: CheckoutEventLike) => void): void;
+    removeEventListener(type: "message", listener: (ev: CheckoutEventLike) => void): void;
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+    readonly screenX?: number;
+    readonly screenY?: number;
+    readonly outerWidth?: number;
+    readonly outerHeight?: number;
+}
+export interface OpenCheckoutOptions {
+    /** The invoice address (base58) the merchant created on chain. */
+    readonly invoice: string;
+    /** Override the hosted checkout origin (e.g. a testnet deployment). */
+    readonly appOrigin?: string;
+    /** Called once the popup has proved it is the X1 Pay app for this checkout. */
+    readonly onReady?: () => void;
+    /** Popup size. */
+    readonly width?: number;
+    readonly height?: number;
+    /** How often to check whether the popup was closed (ms). */
+    readonly pollMs?: number;
+    /** Injected for tests; defaults to {@link newCheckoutSid}. */
+    readonly sid?: string;
+}
+export interface CheckoutSession {
+    readonly sid: string;
+    /** Settles once: the popup's result, or `closed`. Rejects only on
+     *  {@link CheckoutSession.abort}. */
+    readonly result: Promise<CheckoutResult>;
+    /** Stop listening, close the popup, reject `result`. */
+    abort(): void;
+}
+/** Thrown by {@link openCheckout} when the browser blocked the popup (call it
+ *  straight from a click handler). */
+export declare class CheckoutPopupBlockedError extends Error {
+    constructor();
+}
+/**
+ * Open the hosted checkout for `opts.invoice` in a popup and listen for its
+ * result. Call it synchronously from a user gesture (a click), or the browser
+ * blocks the popup ({@link CheckoutPopupBlockedError}).
+ *
+ * The result is a HINT for your UI. Before you ship anything, have your server
+ * call `verifyInvoicePaid` with the invoice address and terms YOU stored when
+ * you created the invoice.
+ */
+export declare function openCheckout(host: CheckoutHostLike, opts: OpenCheckoutOptions): CheckoutSession;