@x1id/resolve 0.3.0 → 0.7.0

package/dist/attestation.js

@@ -50,6 +50,15 @@
  * documented blind spot is shared with `Handle.owner`/`Primary`/
  * `RecordDelegate`: a bearer-NFT marketplace trade bumps no epoch, so the
  * attestation keeps reading live until the attestor re-reviews or revokes.)
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer — its own doc comment (lib.rs) names attestations
+ * explicitly alongside records/text-records as sharing this epoch rule. The
+ * same functions therefore also demand the handle's `recordsClearedAt` (0 if
+ * never cleared, from `ParsedHandle`), and an attestation is `stale` when
+ * EITHER `attested_at < registeredAt` OR `attested_at < recordsClearedAt`.
  */
 import { encodeBase58 } from "./base58.js";
 import { decodeBase58_32 } from "./base58.js";
@@ -123,13 +132,15 @@ export function attestationKindName(kind) {
  * Decode one Attestation account.
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
- * caller from the Handle account — it decides `stale`. There is
- * intentionally no overload without it (see the module docs).
+ * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
+ * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
+ * SECOND independent staleness anchor. There is intentionally no overload
+ * without either (see the module docs).
  *
  * Returns null for anything that is not an Attestation: wrong length or
  * wrong discriminator.
  */
-export function decodeAttestation(raw, account, registeredAt) {
+export function decodeAttestation(raw, account, registeredAt, recordsClearedAt) {
     if (raw.length !== ATTESTATION_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -155,7 +166,7 @@ export function decodeAttestation(raw, account, registeredAt) {
         evidenceHash,
         attestedAt,
         attestor,
-        stale: attestedAt < registeredAt,
+        stale: attestedAt < registeredAt || attestedAt < recordsClearedAt,
     };
 }
 /** The attestations that vouch for the CURRENT owner — `stale` ones
@@ -181,12 +192,13 @@ export function isHandleVerified(attestations) {
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every attestation is returned,
- * stale ones flagged, so an owner surface can show what a previous
- * registration left behind; anything that renders a verified badge takes
- * {@link isHandleVerified} / {@link liveAttestations}.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Every attestation is returned, stale ones flagged, so an owner surface can
+ * show what a previous registration left behind; anything that renders a
+ * verified badge takes {@link isHandleVerified} / {@link liveAttestations}.
  */
-export async function fetchAttestations(rpc, programId, handleAccount, registeredAt) {
+export async function fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -205,7 +217,7 @@ export async function fetchAttestations(rpc, programId, handleAccount, registere
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const decoded = decodeAttestation(raw, a.pubkey, registeredAt);
+        const decoded = decodeAttestation(raw, a.pubkey, registeredAt, recordsClearedAt);
         // Defence in depth: the memcmp filter should guarantee the handle
         // match, but a wrong offset would silently attribute someone else's
         // attestation to this handle. A malformed account is skipped, not fatal.

package/dist/clearRecords.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `clear_records` (#8139): bulk-invalidate every record/text-record/
+ * attestation on a handle RIGHT NOW, without a transfer, by bumping
+ * `Handle.records_cleared_at` to the current time. The accounts
+ * (`accounts.ts` `ParsedHandle.recordsClearedAt`) and read-side staleness
+ * rule (every decoder in `records.ts` / `textRecords.ts` / `attestation.ts`:
+ * `updated_at < recordsClearedAt` is stale, alongside the `registeredAt`
+ * epoch rule) have existed since #8139 shipped; this module is the one
+ * missing piece — the instruction builder to actually trigger a clear
+ * (WP #8212).
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). The builder returns
+ * the same transport-neutral {@link BuiltInstruction} `delegate.ts` uses.
+ *
+ * # Authority: STRICT current-authority, no delegate
+ *
+ * `clear_records` is gated by `require_current_authority` in lib.rs — the
+ * SAME strict check `lock_handle`/`initiate_unlock`/`complete_unlock` use
+ * (see `lock.ts`'s module docs), not the record-editing delegate model
+ * (`require_record_edit_authority`, `recordWrite.ts`'s
+ * `RecordEditAuthorityParams`). A handle's active `RecordDelegate` can add,
+ * edit, and verify individual records, but CANNOT bulk-invalidate all of
+ * them — that stays an owner/NFT-holder-only action, on purpose: nuking
+ * every record is a much bigger blast radius than editing one. There is
+ * deliberately no `recordDelegate` param here.
+ *
+ * A TOKENIZED handle's current holder appends their ATA for the handle's
+ * NFT mint as the sole remaining account (`holderTokenAccount`), exactly
+ * like `lock.ts`'s `LockParams`/`UnlockParams`; omit it for an untokenized
+ * handle.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Anchor instruction discriminator: `sha256("global:clear_records")[0..8]`.
+ *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
+ *  everywhere it runs); asserted against a re-derivation in the test suite
+ *  so a typo can never silently pass. */
+export declare const CLEAR_RECORDS_DISCRIMINATOR: Uint8Array;
+export interface ClearRecordsParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's CURRENT authority (untokenized owner, or NFT holder).
+     *  Signer, writable — also pays the one-time account grow through
+     *  `records_cleared_at`'s extension region on a handle that has never
+     *  been grown that far. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** TOKENIZED handles only: the holder's associated token account for the
+     *  handle's NFT mint, appended as the strict check's remaining-account
+     *  proof. Omit for an untokenized handle. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `clear_records` — bump `Handle.records_cleared_at` to now, so every
+ * record/text-record/attestation with an `updated_at` before this instant
+ * reads as stale everywhere in this SDK, without touching any of those
+ * accounts individually. Idempotent (re-clearing just re-stamps the clock).
+ */
+export declare function buildClearRecordsIx(p: ClearRecordsParams): BuiltInstruction;

package/dist/clearRecords.js

@@ -0,0 +1,69 @@
+/**
+ * `clear_records` (#8139): bulk-invalidate every record/text-record/
+ * attestation on a handle RIGHT NOW, without a transfer, by bumping
+ * `Handle.records_cleared_at` to the current time. The accounts
+ * (`accounts.ts` `ParsedHandle.recordsClearedAt`) and read-side staleness
+ * rule (every decoder in `records.ts` / `textRecords.ts` / `attestation.ts`:
+ * `updated_at < recordsClearedAt` is stale, alongside the `registeredAt`
+ * epoch rule) have existed since #8139 shipped; this module is the one
+ * missing piece — the instruction builder to actually trigger a clear
+ * (WP #8212).
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). The builder returns
+ * the same transport-neutral {@link BuiltInstruction} `delegate.ts` uses.
+ *
+ * # Authority: STRICT current-authority, no delegate
+ *
+ * `clear_records` is gated by `require_current_authority` in lib.rs — the
+ * SAME strict check `lock_handle`/`initiate_unlock`/`complete_unlock` use
+ * (see `lock.ts`'s module docs), not the record-editing delegate model
+ * (`require_record_edit_authority`, `recordWrite.ts`'s
+ * `RecordEditAuthorityParams`). A handle's active `RecordDelegate` can add,
+ * edit, and verify individual records, but CANNOT bulk-invalidate all of
+ * them — that stays an owner/NFT-holder-only action, on purpose: nuking
+ * every record is a much bigger blast radius than editing one. There is
+ * deliberately no `recordDelegate` param here.
+ *
+ * A TOKENIZED handle's current holder appends their ATA for the handle's
+ * NFT mint as the sole remaining account (`holderTokenAccount`), exactly
+ * like `lock.ts`'s `LockParams`/`UnlockParams`; omit it for an untokenized
+ * handle.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Anchor instruction discriminator: `sha256("global:clear_records")[0..8]`.
+ *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
+ *  everywhere it runs); asserted against a re-derivation in the test suite
+ *  so a typo can never silently pass. */
+export const CLEAR_RECORDS_DISCRIMINATOR = Uint8Array.from([
+    150, 232, 238, 45, 8, 105, 50, 153,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBase58(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return encodeBase58(b);
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return encodeBase58(v);
+}
+/**
+ * Build `clear_records` — bump `Handle.records_cleared_at` to now, so every
+ * record/text-record/attestation with an `updated_at` before this instant
+ * reads as stale everywhere in this SDK, without touching any of those
+ * accounts individually. Idempotent (re-clearing just re-stamps the clock).
+ */
+export function buildClearRecordsIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: CLEAR_RECORDS_DISCRIMINATOR.slice() };
+}

package/dist/commitReveal.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Commit-reveal registration (#8134 / #8199): instruction builders and
+ * account decoding for `commit` / `register_revealed` / `cancel_commitment`
+ * — the anti-front-running path. `register` (register.ts) stays the plain
+ * single-step sibling; this module adds the two-step flow: stake out a
+ * hash, wait `Config.min_commitment_age_secs`, then reveal.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. PDAs are NOT derived here (see delegate.ts's
+ * module docs for why) — derive `["commitment", hash]` (seed constant:
+ * {@link COMMITMENT_SEED}) with your runtime's canonical
+ * `findProgramAddress`, e.g. web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(COMMITMENT_SEED), Buffer.from(hash)],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The commitment hash
+ *
+ * `sha256(name_bytes ‖ owner_pubkey ‖ handle_type_byte ‖ secret[32] ‖
+ * program_id_bytes)` — the exact preimage order of the program's own
+ * `commitment_hash` (lib.rs), byte-verified against the deployed program by
+ * the E2E reveal phase (tools/scripts/e2e/journey-audit.ts). sha256, NOT
+ * keccak, for the same documented reason as `text_key_hash`: off-chain
+ * derivation is plain WebCrypto with no extra dependency — so
+ * {@link commitmentHash} is async, mirroring textRecords.ts's
+ * `hashTextKey`. The program id in the preimage is the SVM analog of
+ * ENS/ArcNS's `chainid + controller` domain separation: a commitment cannot
+ * replay against a different deployment.
+ *
+ * # Lifecycle (mirror of lib.rs)
+ *
+ * - `commit(commitment_hash)` `init`s `["commitment", hash]`, recording only
+ *   `payer` + `committed_at` — the name is never on chain until reveal.
+ *   Anyone may pay (the security is the secret preimage, not who pays).
+ * - `register_revealed(name, handle_type, secret)` recomputes the hash
+ *   on-chain from the now-public fields; the supplied `commitment` account
+ *   must sit at exactly the PDA that hash derives (`CommitmentMismatch`,
+ *   6077, otherwise). Valid only inside the window: at least
+ *   `min_commitment_age_secs` after `committed_at` (`CommitmentTooNew`,
+ *   6074) and strictly before `max_commitment_age_secs` (`CommitmentTooOld`,
+ *   6075). Consuming closes the commitment — rent back. Pricing, integrator
+ *   split and the `Handle` write are identical to `register` (both call the
+ *   program's `register_core`); the result is a PERMANENT registration.
+ * - `cancel_commitment()` closes an unconsumed commitment, payer-only
+ *   (`NotCommitmentPayer`, 6080), allowed at ANY age — the escape hatch for
+ *   a lost secret or an abandoned flow, so rent is never stranded.
+ *
+ * A SECRET THAT IS LOST STRANDS THE COMMITMENT: without it the hash cannot
+ * be recomputed, so the commitment can only ever be `cancel_commitment`ed
+ * (which at least needs its address, discoverable via
+ * `getProgramAccounts` on the payer). Persist the secret client-side the
+ * moment it is generated, before `commit` is even sent.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+import type { HandleTypeValue } from "./voucher.js";
+/** Seed prefix of the commitment PDA: `["commitment", commitmentHash]`. */
+export declare const COMMITMENT_SEED = "commitment";
+/** Anchor instruction discriminator: `sha256("global:commit")[0..8]`. */
+export declare const COMMIT_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:register_revealed")[0..8]`. */
+export declare const REGISTER_REVEALED_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:cancel_commitment")[0..8]`. */
+export declare const CANCEL_COMMITMENT_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator: `sha256("account:Commitment")[0..8]`. */
+export declare const COMMITMENT_DISCRIMINATOR: Uint8Array;
+/** `Commitment` account size: disc(8) payer(32) committed_at(8) bump(1). */
+export declare const COMMITMENT_LEN = 49;
+export interface CommitmentHashParams {
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    /** The owner the reveal will register the handle to — must be the SAME
+     *  key later passed as `register_revealed`'s `owner`, or the reveal fails
+     *  closed (`CommitmentMismatch`). */
+    readonly owner: AddressLike;
+    readonly handleType: HandleTypeValue;
+    /** 32 bytes of fresh CSPRNG output (`crypto.getRandomValues(new
+     *  Uint8Array(32))`). Persist it — see the module docs. */
+    readonly secret: Uint8Array;
+    /** The registry program id — part of the preimage (domain separation). */
+    readonly programId: AddressLike;
+}
+/**
+ * The 32-byte commitment hash — `sha256(name ‖ owner ‖ handle_type ‖ secret
+ * ‖ program_id)`, the program's own preimage order (see the module docs).
+ * WebCrypto (`crypto.subtle`), so it is async — mirrors `hashTextKey`.
+ */
+export declare function commitmentHash(p: CommitmentHashParams): Promise<Uint8Array>;
+export interface CommitParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the commitment's rent; recorded as the only key allowed to
+     *  `cancel_commitment`. Signer. */
+    readonly payer: AddressLike;
+    /** The `["commitment", commitmentHash]` PDA — derive it with your
+     *  runtime's canonical `findProgramAddress` (see the module docs). */
+    readonly commitment: AddressLike;
+    /** The 32-byte hash from {@link commitmentHash}. */
+    readonly commitmentHash: Uint8Array;
+}
+/**
+ * Build `commit` — stake out the hash. Only the hash goes on chain; the
+ * name stays private until reveal. Account order matches `Commit<'info>`
+ * (lib.rs) exactly: payer, commitment, system_program.
+ */
+export declare function buildCommitIx(p: CommitParams): BuiltInstruction;
+export interface RegisterRevealedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the registration fee and the `Handle` account's rent. Signer.
+     *  Need NOT be the commitment's payer — the binding is the hash preimage,
+     *  and the consumed commitment's rent refunds to this payer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign, but MUST be the key the commitment
+     *  hashed (see {@link CommitmentHashParams.owner}). */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — read it fresh via `fetchConfigTreasury`
+     *  (register.ts); it's admin-rotatable. */
+    readonly treasury: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist. */
+    readonly handle: AddressLike;
+    /** The `["commitment", commitmentHash]` PDA the matching `commit`
+     *  created. */
+    readonly commitment: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** The exact 32-byte secret the commitment hashed. */
+    readonly secret: Uint8Array;
+    /** OPTIONAL revenue-share pair — same contract as `register`'s (#7397):
+     *  supply BOTH or NEITHER. */
+    readonly integrator?: AddressLike;
+    /** The `["integrator", integrator]` allowlist PDA. */
+    readonly integratorAllowlist?: AddressLike;
+}
+/**
+ * Build `register_revealed` — the reveal step. Price is computed on-chain
+ * exactly like `register`'s (see register.ts's module docs); simulate first
+ * to show the payer a price. Account order matches
+ * `RegisterRevealed<'info>` (lib.rs) exactly: payer, owner, config,
+ * treasury, handle, commitment, system_program [, integrator,
+ * integrator_allowlist].
+ */
+export declare function buildRegisterRevealedIx(p: RegisterRevealedParams): BuiltInstruction;
+export interface CancelCommitmentParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** MUST be the commitment's recorded payer (`NotCommitmentPayer`, 6080,
+     *  otherwise). Signer; receives the rent. */
+    readonly payer: AddressLike;
+    /** The commitment account to close. No name/secret needed — half the
+     *  point of canceling is that the preimage may be lost. */
+    readonly commitment: AddressLike;
+}
+/**
+ * Build `cancel_commitment` — reclaim an unconsumed commitment's rent,
+ * payer-only, allowed at any age. Account order matches
+ * `CancelCommitment<'info>` (lib.rs) exactly: payer, commitment.
+ */
+export declare function buildCancelCommitmentIx(p: CancelCommitmentParams): BuiltInstruction;
+/** Decoded `Commitment` account. The hash itself is never stored — the
+ *  account's ADDRESS is the hash's proof (it is the PDA seed). */
+export interface Commitment {
+    /** Who paid `commit`'s rent — the only key allowed to cancel (base58). */
+    readonly payer: string;
+    /** Unix seconds when `commit` created this account — what the
+     *  min/max-age window is checked against. */
+    readonly committedAt: bigint;
+    readonly bump: number;
+}
+/**
+ * Decode a `Commitment` account's raw data, or null if not one (wrong
+ * discriminator or too short).
+ */
+export declare function decodeCommitment(data: Uint8Array): Commitment | null;
+/**
+ * Fetch + decode one `Commitment` account, or null when it doesn't exist
+ * (never committed, already consumed by a reveal, or canceled — all leave
+ * no account) or isn't shaped like a `Commitment`.
+ */
+export declare function fetchCommitment(rpc: RpcFn, commitmentAccount: string): Promise<Commitment | null>;

package/dist/commitReveal.js

@@ -0,0 +1,245 @@
+/**
+ * Commit-reveal registration (#8134 / #8199): instruction builders and
+ * account decoding for `commit` / `register_revealed` / `cancel_commitment`
+ * — the anti-front-running path. `register` (register.ts) stays the plain
+ * single-step sibling; this module adds the two-step flow: stake out a
+ * hash, wait `Config.min_commitment_age_secs`, then reveal.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. PDAs are NOT derived here (see delegate.ts's
+ * module docs for why) — derive `["commitment", hash]` (seed constant:
+ * {@link COMMITMENT_SEED}) with your runtime's canonical
+ * `findProgramAddress`, e.g. web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(COMMITMENT_SEED), Buffer.from(hash)],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The commitment hash
+ *
+ * `sha256(name_bytes ‖ owner_pubkey ‖ handle_type_byte ‖ secret[32] ‖
+ * program_id_bytes)` — the exact preimage order of the program's own
+ * `commitment_hash` (lib.rs), byte-verified against the deployed program by
+ * the E2E reveal phase (tools/scripts/e2e/journey-audit.ts). sha256, NOT
+ * keccak, for the same documented reason as `text_key_hash`: off-chain
+ * derivation is plain WebCrypto with no extra dependency — so
+ * {@link commitmentHash} is async, mirroring textRecords.ts's
+ * `hashTextKey`. The program id in the preimage is the SVM analog of
+ * ENS/ArcNS's `chainid + controller` domain separation: a commitment cannot
+ * replay against a different deployment.
+ *
+ * # Lifecycle (mirror of lib.rs)
+ *
+ * - `commit(commitment_hash)` `init`s `["commitment", hash]`, recording only
+ *   `payer` + `committed_at` — the name is never on chain until reveal.
+ *   Anyone may pay (the security is the secret preimage, not who pays).
+ * - `register_revealed(name, handle_type, secret)` recomputes the hash
+ *   on-chain from the now-public fields; the supplied `commitment` account
+ *   must sit at exactly the PDA that hash derives (`CommitmentMismatch`,
+ *   6077, otherwise). Valid only inside the window: at least
+ *   `min_commitment_age_secs` after `committed_at` (`CommitmentTooNew`,
+ *   6074) and strictly before `max_commitment_age_secs` (`CommitmentTooOld`,
+ *   6075). Consuming closes the commitment — rent back. Pricing, integrator
+ *   split and the `Handle` write are identical to `register` (both call the
+ *   program's `register_core`); the result is a PERMANENT registration.
+ * - `cancel_commitment()` closes an unconsumed commitment, payer-only
+ *   (`NotCommitmentPayer`, 6080), allowed at ANY age — the escape hatch for
+ *   a lost secret or an abandoned flow, so rent is never stranded.
+ *
+ * A SECRET THAT IS LOST STRANDS THE COMMITMENT: without it the hash cannot
+ * be recomputed, so the commitment can only ever be `cancel_commitment`ed
+ * (which at least needs its address, discoverable via
+ * `getProgramAccounts` on the payer). Persist the secret client-side the
+ * moment it is generated, before `commit` is even sent.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the commitment PDA: `["commitment", commitmentHash]`. */
+export const COMMITMENT_SEED = "commitment";
+/** Anchor instruction discriminator: `sha256("global:commit")[0..8]`. */
+export const COMMIT_DISCRIMINATOR = Uint8Array.from([
+    223, 140, 142, 165, 229, 208, 156, 74,
+]);
+/** Anchor instruction discriminator: `sha256("global:register_revealed")[0..8]`. */
+export const REGISTER_REVEALED_DISCRIMINATOR = Uint8Array.from([
+    175, 112, 193, 148, 139, 78, 15, 86,
+]);
+/** Anchor instruction discriminator: `sha256("global:cancel_commitment")[0..8]`. */
+export const CANCEL_COMMITMENT_DISCRIMINATOR = Uint8Array.from([
+    36, 39, 70, 137, 71, 179, 88, 232,
+]);
+/** Anchor account discriminator: `sha256("account:Commitment")[0..8]`. */
+export const COMMITMENT_DISCRIMINATOR = Uint8Array.from([
+    61, 112, 129, 128, 24, 147, 77, 87,
+]);
+/** `Commitment` account size: disc(8) payer(32) committed_at(8) bump(1). */
+export const COMMITMENT_LEN = 49;
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+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 checkHandleType(handleType) {
+    if (!Number.isInteger(handleType) || handleType < 0 || handleType > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+}
+function checkSecret(secret) {
+    if (secret.length !== 32)
+        throw new Error("secret must be exactly 32 bytes");
+}
+/**
+ * The 32-byte commitment hash — `sha256(name ‖ owner ‖ handle_type ‖ secret
+ * ‖ program_id)`, the program's own preimage order (see the module docs).
+ * WebCrypto (`crypto.subtle`), so it is async — mirrors `hashTextKey`.
+ */
+export async function commitmentHash(p) {
+    checkHandleType(p.handleType);
+    checkSecret(p.secret);
+    const nameBytes = new TextEncoder().encode(p.name);
+    if (nameBytes.length < 1 || nameBytes.length > 32) {
+        throw new Error("name must be 1..=32 bytes (UTF-8)");
+    }
+    const owner = toBytes32(p.owner, "owner");
+    const program = toBytes32(p.programId, "programId");
+    const preimage = new Uint8Array(nameBytes.length + 32 + 1 + 32 + 32);
+    let o = 0;
+    preimage.set(nameBytes, o);
+    o += nameBytes.length;
+    preimage.set(owner, o);
+    o += 32;
+    preimage[o] = p.handleType;
+    o += 1;
+    preimage.set(p.secret, o);
+    o += 32;
+    preimage.set(program, o);
+    const digest = await crypto.subtle.digest("SHA-256", preimage);
+    return new Uint8Array(digest);
+}
+/**
+ * Build `commit` — stake out the hash. Only the hash goes on chain; the
+ * name stays private until reveal. Account order matches `Commit<'info>`
+ * (lib.rs) exactly: payer, commitment, system_program.
+ */
+export function buildCommitIx(p) {
+    if (p.commitmentHash.length !== 32) {
+        throw new Error("commitmentHash must be exactly 32 bytes (a sha256 digest)");
+    }
+    const data = new Uint8Array(8 + 32);
+    data.set(COMMIT_DISCRIMINATOR, 0);
+    data.set(p.commitmentHash, 8);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.commitment, "commitment"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `register_revealed` — the reveal step. Price is computed on-chain
+ * exactly like `register`'s (see register.ts's module docs); simulate first
+ * to show the payer a price. Account order matches
+ * `RegisterRevealed<'info>` (lib.rs) exactly: payer, owner, config,
+ * treasury, handle, commitment, system_program [, integrator,
+ * integrator_allowlist].
+ */
+export function buildRegisterRevealedIx(p) {
+    checkHandleType(p.handleType);
+    checkSecret(p.secret);
+    const nameBytes = new TextEncoder().encode(p.name);
+    if (nameBytes.length < 1 || nameBytes.length > 32) {
+        throw new Error("name must be 1..=32 bytes (UTF-8)");
+    }
+    const data = new Uint8Array(8 + 4 + nameBytes.length + 1 + 32);
+    data.set(REGISTER_REVEALED_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nameBytes.length, true);
+    data.set(nameBytes, 12);
+    data[12 + nameBytes.length] = p.handleType;
+    data.set(p.secret, 12 + nameBytes.length + 1);
+    const hasIntegrator = p.integrator !== undefined || p.integratorAllowlist !== undefined;
+    if (hasIntegrator && (p.integrator === undefined || p.integratorAllowlist === undefined)) {
+        throw new Error("integrator and integratorAllowlist must both be supplied, or neither");
+    }
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.commitment, "commitment"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (hasIntegrator) {
+        keys.push({ pubkey: toBase58(p.integrator, "integrator"), isSigner: false, isWritable: true }, {
+            pubkey: toBase58(p.integratorAllowlist, "integratorAllowlist"),
+            isSigner: false,
+            isWritable: false,
+        });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `cancel_commitment` — reclaim an unconsumed commitment's rent,
+ * payer-only, allowed at any age. Account order matches
+ * `CancelCommitment<'info>` (lib.rs) exactly: payer, commitment.
+ */
+export function buildCancelCommitmentIx(p) {
+    const data = new Uint8Array(8);
+    data.set(CANCEL_COMMITMENT_DISCRIMINATOR, 0);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+            { pubkey: toBase58(p.commitment, "commitment"), isSigner: false, isWritable: true },
+        ],
+        data,
+    };
+}
+/**
+ * Decode a `Commitment` account's raw data, or null if not one (wrong
+ * discriminator or too short).
+ */
+export function decodeCommitment(data) {
+    if (data.length < COMMITMENT_LEN)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== COMMITMENT_DISCRIMINATOR[i])
+            return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return {
+        payer: encodeBase58(data.slice(8, 40)),
+        committedAt: view.getBigInt64(40, true),
+        bump: data[48],
+    };
+}
+/**
+ * Fetch + decode one `Commitment` account, or null when it doesn't exist
+ * (never committed, already consumed by a reveal, or canceled — all leave
+ * no account) or isn't shaped like a `Commitment`.
+ */
+export async function fetchCommitment(rpc, commitmentAccount) {
+    const res = (await rpc("getAccountInfo", [
+        commitmentAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data = res?.value?.data?.[0];
+    if (!data)
+        return null;
+    const bin = atob(data);
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    return decodeCommitment(raw);
+}

package/dist/index.d.ts

@@ -38,6 +38,14 @@ export * from "./textRecords.js";
 export * from "./lock.js";
 export * from "./integrator.js";
 export * from "./voucher.js";
+export * from "./agent.js";
+export * from "./register.js";
+export * from "./accounts.js";
+export * from "./x402.js";
+export * from "./recordWrite.js";
+export * from "./clearRecords.js";
+export * from "./commitReveal.js";
+export * from "./pnftTransfer.js";
 import { type Chain, type Resolved } from "./types.js";
 import { WasmResolver } from "./wasm.js";
 import { type HandleRecord } from "./records.js";