@x1id/resolve 0.6.0 → 0.7.0

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

@@ -44,6 +44,8 @@ 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";

package/dist/index.js

@@ -51,6 +51,8 @@ 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 { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
 import { parseName } from "./parse.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";

package/dist/pnftTransfer.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Move a handle's capability NFT — `TransferV1` for Metaplex
+ * ProgrammableNonFungibles (pNFTs), the standard `mint_handle_nft` mints.
+ *
+ * One import to move a handle NFT:
+ *
+ * ```ts
+ * import { WasmResolver, buildTransferV1Ix, deriveTransferV1Accounts } from "@x1id/resolve";
+ *
+ * const accounts = deriveTransferV1Accounts(wasm, {
+ *   mint,                 // Handle.nft_mint (parseHandleAccount(...).nftMint)
+ *   holder,               // current holder — signs
+ *   recipient,            // destination wallet
+ * });
+ * const ix = buildTransferV1Ix({ ...accounts, amount: 1n });
+ * // adapt `ix` to your runtime (see delegate.ts's module docs for the
+ * // two-line web3.js adapter) and send with the holder's signature.
+ * ```
+ *
+ * # Why a plain SPL transfer no longer works
+ *
+ * A pNFT's token accounts are permanently FROZEN by the Token Metadata
+ * program (that is how it enforces programmability): `spl_token::transfer`
+ * fails with `AccountFrozen`. The ONLY way to move one is the Token Metadata
+ * program's own `TransferV1`, which thaw-moves-refreezes under the hood and
+ * maintains one `TokenRecord` PDA per token account on both sides.
+ * READ paths are unaffected — a frozen account still reports `amount 1`, so
+ * holder resolution (`nftHolder`, `reverse()`) is identical for both
+ * standards.
+ *
+ * Handles tokenized BEFORE the pNFT cutover hold plain `NonFungible`s
+ * (unfrozen) — those still move by plain SPL transfer. Branch on the mint's
+ * metadata `token_standard` (or on the source ATA's frozen state); this
+ * module only builds the pNFT path.
+ *
+ * # Wire format (verified against mpl-token-metadata 5.1.1, the crate the
+ * # workspace Cargo.lock pins — `src/generated/instructions/transfer_v1.rs`)
+ *
+ * Data: `[49, 0]` (instruction discriminator `Transfer` = 49, then
+ * `TransferArgs::V1` = 0) ‖ `amount: u64 LE` ‖ `authorization_data:
+ * Option` (`0` — this SDK never builds `AuthorizationData`; handle rule
+ * sets carry `rule_set: None`, so none is ever needed). 11 bytes total.
+ *
+ * Accounts, in exactly this order (17): token(w) token_owner
+ * destination_token(w) destination_owner mint metadata(w) edition
+ * token_record(w) destination_token_record(w) authority(s) payer(s,w)
+ * system_program sysvar_instructions spl_token_program spl_ata_program
+ * authorization_rules_program authorization_rules. An absent OPTIONAL slot
+ * is filled with the Token Metadata program id itself, read-only — Metaplex's
+ * "explicitly None" convention (kinobi-generated builders do the same).
+ *
+ * The destination ATA and its `TokenRecord` need not exist: `TransferV1`
+ * creates both (rent from `payer`) — that is why the ATA program is in the
+ * account list. No separate create-ATA instruction is needed.
+ *
+ * PDAs are derived through the WASM module (this package's one rule: never
+ * hand-roll `find_program_address`'s on-curve check in TypeScript — see
+ * wasm.ts). The Token Metadata program id is a parameter everywhere because
+ * X1 runs its own deployment ({@link MPL_TOKEN_METADATA_PROGRAM}).
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { WasmResolver } from "./wasm.js";
+/** X1's Token Metadata deployment — the id `mint_handle_nft` CPIs into
+ *  (lib.rs `TOKEN_METADATA_PROGRAM_ID`, `…x1s` suffix). NOT the canonical
+ *  Solana-mainnet id; on another chain, pass that deployment's id instead. */
+export declare const MPL_TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
+/** `MetadataInstruction::Transfer`'s Borsh enum discriminator. */
+export declare const TRANSFER_IX_DISCRIMINATOR = 49;
+/** `TransferArgs::V1`'s Borsh enum discriminator. */
+export declare const TRANSFER_ARGS_V1 = 0;
+/** Metadata `token_standard` value for a pNFT
+ *  (`TokenStandard::ProgrammableNonFungible`, mpl 5.1.1 enum order). */
+export declare const TOKEN_STANDARD_PROGRAMMABLE_NON_FUNGIBLE = 4;
+/**
+ * Derive the `TokenRecord` PDA for `(mint, token)` — `token` is the token
+ * ACCOUNT (the ATA), not its owner. Byte-for-byte
+ * `mpl_token_metadata::accounts::TokenRecord::find_pda`; seeds
+ * `["metadata", program, mint, "token_record", token]` under `programId`.
+ */
+export declare function deriveTokenRecordPda(wasm: WasmResolver, mint: AddressLike, token: AddressLike, programId?: AddressLike): string;
+/** Every address {@link buildTransferV1Ix} needs, derived from just
+ *  `(mint, holder, recipient)`. */
+export interface TransferV1Accounts {
+    /** The holder's ATA — the account the NFT leaves. */
+    readonly token: string;
+    /** The holder. */
+    readonly tokenOwner: string;
+    /** The recipient's ATA — created by `TransferV1` itself if absent. */
+    readonly destinationToken: string;
+    readonly destinationOwner: string;
+    readonly mint: string;
+    readonly metadata: string;
+    readonly edition: string;
+    readonly tokenRecord: string;
+    readonly destinationTokenRecord: string;
+    /** The holder — pNFT self-transfers sign as owner. */
+    readonly authority: string;
+    /** Rent for the destination ATA + token record. Defaults to the holder. */
+    readonly payer: string;
+    readonly tokenMetadataProgramId: string;
+}
+/**
+ * Derive the full `TransferV1` account set for moving a handle NFT from
+ * `holder` to `recipient`. Pure derivation — nothing is fetched; whether the
+ * mint really is a pNFT is the caller's check (read the metadata
+ * `token_standard`, or the source ATA's frozen state).
+ */
+export declare function deriveTransferV1Accounts(wasm: WasmResolver, p: {
+    readonly mint: AddressLike;
+    readonly holder: AddressLike;
+    readonly recipient: AddressLike;
+    /** Pays destination-side rent. Defaults to `holder`. */
+    readonly payer?: AddressLike;
+    readonly tokenMetadataProgramId?: AddressLike;
+}): TransferV1Accounts;
+export interface TransferV1Params {
+    /** Source token account (the holder's ATA). */
+    readonly token: AddressLike;
+    readonly tokenOwner: AddressLike;
+    /** Destination token account — need not exist yet (see module docs). */
+    readonly destinationToken: AddressLike;
+    readonly destinationOwner: AddressLike;
+    readonly mint: AddressLike;
+    readonly metadata: AddressLike;
+    /** Master Edition PDA. Required for a pNFT. */
+    readonly edition: AddressLike;
+    /** `TokenRecord` PDA of the SOURCE token account. Required for a pNFT. */
+    readonly tokenRecord: AddressLike;
+    /** `TokenRecord` PDA of the DESTINATION token account. Required for a
+     *  pNFT — `TransferV1` creates the account if it does not exist. */
+    readonly destinationTokenRecord: AddressLike;
+    /** The transfer authority (holder or delegate). Signer. */
+    readonly authority: AddressLike;
+    /** Pays destination-side rent. Signer. */
+    readonly payer: AddressLike;
+    /** Defaults to 1 — handle NFTs are fixed-supply-1. */
+    readonly amount?: bigint;
+    /** OPTIONAL auth-rules pair — supply BOTH or NEITHER. Handle NFTs are
+     *  minted with `rule_set: None`, so normally neither: the slots are then
+     *  filled with the "explicitly None" placeholder (the program id). Plumbed
+     *  for completeness should a rule set ever exist. */
+    readonly authorizationRulesProgram?: AddressLike;
+    readonly authorizationRules?: AddressLike;
+    readonly tokenMetadataProgramId?: AddressLike;
+}
+/**
+ * Build `TransferV1`. See the module docs for the verified account order and
+ * data serialization. `authorization_data` is always serialized `None` —
+ * with `rule_set: None` there is nothing to authorize against.
+ */
+export declare function buildTransferV1Ix(p: TransferV1Params): BuiltInstruction;

package/dist/pnftTransfer.js

@@ -0,0 +1,183 @@
+/**
+ * Move a handle's capability NFT — `TransferV1` for Metaplex
+ * ProgrammableNonFungibles (pNFTs), the standard `mint_handle_nft` mints.
+ *
+ * One import to move a handle NFT:
+ *
+ * ```ts
+ * import { WasmResolver, buildTransferV1Ix, deriveTransferV1Accounts } from "@x1id/resolve";
+ *
+ * const accounts = deriveTransferV1Accounts(wasm, {
+ *   mint,                 // Handle.nft_mint (parseHandleAccount(...).nftMint)
+ *   holder,               // current holder — signs
+ *   recipient,            // destination wallet
+ * });
+ * const ix = buildTransferV1Ix({ ...accounts, amount: 1n });
+ * // adapt `ix` to your runtime (see delegate.ts's module docs for the
+ * // two-line web3.js adapter) and send with the holder's signature.
+ * ```
+ *
+ * # Why a plain SPL transfer no longer works
+ *
+ * A pNFT's token accounts are permanently FROZEN by the Token Metadata
+ * program (that is how it enforces programmability): `spl_token::transfer`
+ * fails with `AccountFrozen`. The ONLY way to move one is the Token Metadata
+ * program's own `TransferV1`, which thaw-moves-refreezes under the hood and
+ * maintains one `TokenRecord` PDA per token account on both sides.
+ * READ paths are unaffected — a frozen account still reports `amount 1`, so
+ * holder resolution (`nftHolder`, `reverse()`) is identical for both
+ * standards.
+ *
+ * Handles tokenized BEFORE the pNFT cutover hold plain `NonFungible`s
+ * (unfrozen) — those still move by plain SPL transfer. Branch on the mint's
+ * metadata `token_standard` (or on the source ATA's frozen state); this
+ * module only builds the pNFT path.
+ *
+ * # Wire format (verified against mpl-token-metadata 5.1.1, the crate the
+ * # workspace Cargo.lock pins — `src/generated/instructions/transfer_v1.rs`)
+ *
+ * Data: `[49, 0]` (instruction discriminator `Transfer` = 49, then
+ * `TransferArgs::V1` = 0) ‖ `amount: u64 LE` ‖ `authorization_data:
+ * Option` (`0` — this SDK never builds `AuthorizationData`; handle rule
+ * sets carry `rule_set: None`, so none is ever needed). 11 bytes total.
+ *
+ * Accounts, in exactly this order (17): token(w) token_owner
+ * destination_token(w) destination_owner mint metadata(w) edition
+ * token_record(w) destination_token_record(w) authority(s) payer(s,w)
+ * system_program sysvar_instructions spl_token_program spl_ata_program
+ * authorization_rules_program authorization_rules. An absent OPTIONAL slot
+ * is filled with the Token Metadata program id itself, read-only — Metaplex's
+ * "explicitly None" convention (kinobi-generated builders do the same).
+ *
+ * The destination ATA and its `TokenRecord` need not exist: `TransferV1`
+ * creates both (rent from `payer`) — that is why the ATA program is in the
+ * account list. No separate create-ATA instruction is needed.
+ *
+ * PDAs are derived through the WASM module (this package's one rule: never
+ * hand-roll `find_program_address`'s on-curve check in TypeScript — see
+ * wasm.ts). The Token Metadata program id is a parameter everywhere because
+ * X1 runs its own deployment ({@link MPL_TOKEN_METADATA_PROGRAM}).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** X1's Token Metadata deployment — the id `mint_handle_nft` CPIs into
+ *  (lib.rs `TOKEN_METADATA_PROGRAM_ID`, `…x1s` suffix). NOT the canonical
+ *  Solana-mainnet id; on another chain, pass that deployment's id instead. */
+export const MPL_TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
+/** `MetadataInstruction::Transfer`'s Borsh enum discriminator. */
+export const TRANSFER_IX_DISCRIMINATOR = 49;
+/** `TransferArgs::V1`'s Borsh enum discriminator. */
+export const TRANSFER_ARGS_V1 = 0;
+/** Metadata `token_standard` value for a pNFT
+ *  (`TokenStandard::ProgrammableNonFungible`, mpl 5.1.1 enum order). */
+export const TOKEN_STANDARD_PROGRAMMABLE_NON_FUNGIBLE = 4;
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const SYSVAR_INSTRUCTIONS = "Sysvar1nstructions1111111111111111111111111";
+const SPL_TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const SPL_ATA_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+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));
+}
+/**
+ * Derive the `TokenRecord` PDA for `(mint, token)` — `token` is the token
+ * ACCOUNT (the ATA), not its owner. Byte-for-byte
+ * `mpl_token_metadata::accounts::TokenRecord::find_pda`; seeds
+ * `["metadata", program, mint, "token_record", token]` under `programId`.
+ */
+export function deriveTokenRecordPda(wasm, mint, token, programId = MPL_TOKEN_METADATA_PROGRAM) {
+    const out = wasm.deriveTokenRecordAccount(toBytes32(mint, "mint"), toBytes32(token, "token"), toBytes32(programId, "programId"));
+    if (!out)
+        throw new Error("token record derivation failed");
+    return encodeBase58(out);
+}
+/**
+ * Derive the full `TransferV1` account set for moving a handle NFT from
+ * `holder` to `recipient`. Pure derivation — nothing is fetched; whether the
+ * mint really is a pNFT is the caller's check (read the metadata
+ * `token_standard`, or the source ATA's frozen state).
+ */
+export function deriveTransferV1Accounts(wasm, p) {
+    const mint = toBytes32(p.mint, "mint");
+    const holder = toBytes32(p.holder, "holder");
+    const recipient = toBytes32(p.recipient, "recipient");
+    const program = toBytes32(p.tokenMetadataProgramId ?? MPL_TOKEN_METADATA_PROGRAM, "tokenMetadataProgramId");
+    const sourceAta = wasm.deriveAssociatedTokenAccount(holder, mint);
+    const destAta = wasm.deriveAssociatedTokenAccount(recipient, mint);
+    const metadata = wasm.deriveMetadataAccount(mint, program);
+    const edition = wasm.deriveMasterEditionAccount(mint, program);
+    const sourceRecord = sourceAta && wasm.deriveTokenRecordAccount(mint, sourceAta, program);
+    const destRecord = destAta && wasm.deriveTokenRecordAccount(mint, destAta, program);
+    if (!sourceAta || !destAta || !metadata || !edition || !sourceRecord || !destRecord) {
+        throw new Error("TransferV1 account derivation failed");
+    }
+    return {
+        token: encodeBase58(sourceAta),
+        tokenOwner: encodeBase58(holder),
+        destinationToken: encodeBase58(destAta),
+        destinationOwner: encodeBase58(recipient),
+        mint: encodeBase58(mint),
+        metadata: encodeBase58(metadata),
+        edition: encodeBase58(edition),
+        tokenRecord: encodeBase58(sourceRecord),
+        destinationTokenRecord: encodeBase58(destRecord),
+        authority: encodeBase58(holder),
+        payer: encodeBase58(p.payer !== undefined ? toBytes32(p.payer, "payer") : holder),
+        tokenMetadataProgramId: encodeBase58(program),
+    };
+}
+/**
+ * Build `TransferV1`. See the module docs for the verified account order and
+ * data serialization. `authorization_data` is always serialized `None` —
+ * with `rule_set: None` there is nothing to authorize against.
+ */
+export function buildTransferV1Ix(p) {
+    const amount = p.amount ?? 1n;
+    if (amount < 0n || amount > 0xffffffffffffffffn) {
+        throw new Error("amount must fit in a u64");
+    }
+    const hasRules = p.authorizationRulesProgram !== undefined || p.authorizationRules !== undefined;
+    if (hasRules && (p.authorizationRulesProgram === undefined || p.authorizationRules === undefined)) {
+        throw new Error("authorizationRulesProgram and authorizationRules must both be supplied, or neither");
+    }
+    const programId = toBase58(p.tokenMetadataProgramId ?? MPL_TOKEN_METADATA_PROGRAM, "tokenMetadataProgramId");
+    // [49, 0] ‖ amount u64 LE ‖ Option<AuthorizationData> = None (0).
+    const data = new Uint8Array(11);
+    data[0] = TRANSFER_IX_DISCRIMINATOR;
+    data[1] = TRANSFER_ARGS_V1;
+    new DataView(data.buffer).setBigUint64(2, amount, true);
+    data[10] = 0;
+    const keys = [
+        { pubkey: toBase58(p.token, "token"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.tokenOwner, "tokenOwner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.destinationToken, "destinationToken"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.destinationOwner, "destinationOwner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.mint, "mint"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.metadata, "metadata"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.edition, "edition"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.tokenRecord, "tokenRecord"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.destinationTokenRecord, "destinationTokenRecord"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.authority, "authority"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+        { pubkey: SYSVAR_INSTRUCTIONS, isSigner: false, isWritable: false },
+        { pubkey: SPL_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: SPL_ATA_PROGRAM_ID, isSigner: false, isWritable: false },
+        hasRules
+            ? { pubkey: toBase58(p.authorizationRulesProgram, "authorizationRulesProgram"), isSigner: false, isWritable: false }
+            : { pubkey: programId, isSigner: false, isWritable: false },
+        hasRules
+            ? { pubkey: toBase58(p.authorizationRules, "authorizationRules"), isSigner: false, isWritable: false }
+            : { pubkey: programId, isSigner: false, isWritable: false },
+    ];
+    return { programId, keys, data };
+}

package/dist/wasm.d.ts

@@ -54,5 +54,29 @@ export declare class WasmResolver {
      * holds a tokenized handle's NFT.
      */
     deriveAssociatedTokenAccount(owner: Uint8Array, mint: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte Metaplex Token Metadata PDA for a 32-byte mint under a given
+     * Token Metadata program id — seeds `["metadata", program, mint]`.
+     *
+     * The program id is a parameter (staged, like `deriveHandleAccount`'s)
+     * because X1 runs its own Token Metadata deployment
+     * (`MPL_TOKEN_METADATA_PROGRAM` in pnftTransfer.ts) — the canonical
+     * Solana-mainnet id would derive addresses no X1 account lives at.
+     */
+    deriveMetadataAccount(mint: Uint8Array, programId: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte Metaplex Master Edition PDA for a 32-byte mint under a given
+     * Token Metadata program id — seeds `["metadata", program, mint,
+     * "edition"]`. Same program-id rationale as `deriveMetadataAccount`.
+     */
+    deriveMasterEditionAccount(mint: Uint8Array, programId: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte Metaplex `TokenRecord` PDA for a 32-byte mint and a 32-byte token
+     * ACCOUNT (the ATA — not its owner) under a given Token Metadata program id
+     * — seeds `["metadata", program, mint, "token_record", token]`,
+     * byte-for-byte `mpl_token_metadata::accounts::TokenRecord::find_pda`.
+     * Needed on BOTH sides of a `ProgrammableNonFungible` transfer.
+     */
+    deriveTokenRecordAccount(mint: Uint8Array, token: Uint8Array, programId: Uint8Array): Uint8Array | null;
 }
 export {};

package/dist/wasm.js

@@ -101,4 +101,49 @@ export class WasmResolver {
         const n = this.#write(joined);
         return this.#x.derive_associated_token_account(n) === 1 ? this.#read() : null;
     }
+    /**
+     * 32-byte Metaplex Token Metadata PDA for a 32-byte mint under a given
+     * Token Metadata program id — seeds `["metadata", program, mint]`.
+     *
+     * The program id is a parameter (staged, like `deriveHandleAccount`'s)
+     * because X1 runs its own Token Metadata deployment
+     * (`MPL_TOKEN_METADATA_PROGRAM` in pnftTransfer.ts) — the canonical
+     * Solana-mainnet id would derive addresses no X1 account lives at.
+     */
+    deriveMetadataAccount(mint, programId) {
+        if (mint.length !== 32 || programId.length !== 32)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const n = this.#write(mint);
+        return this.#x.derive_metadata_account(n) === 1 ? this.#read() : null;
+    }
+    /**
+     * 32-byte Metaplex Master Edition PDA for a 32-byte mint under a given
+     * Token Metadata program id — seeds `["metadata", program, mint,
+     * "edition"]`. Same program-id rationale as `deriveMetadataAccount`.
+     */
+    deriveMasterEditionAccount(mint, programId) {
+        if (mint.length !== 32 || programId.length !== 32)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const n = this.#write(mint);
+        return this.#x.derive_master_edition_account(n) === 1 ? this.#read() : null;
+    }
+    /**
+     * 32-byte Metaplex `TokenRecord` PDA for a 32-byte mint and a 32-byte token
+     * ACCOUNT (the ATA — not its owner) under a given Token Metadata program id
+     * — seeds `["metadata", program, mint, "token_record", token]`,
+     * byte-for-byte `mpl_token_metadata::accounts::TokenRecord::find_pda`.
+     * Needed on BOTH sides of a `ProgrammableNonFungible` transfer.
+     */
+    deriveTokenRecordAccount(mint, token, programId) {
+        if (mint.length !== 32 || token.length !== 32 || programId.length !== 32)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const joined = new Uint8Array(64);
+        joined.set(mint, 0);
+        joined.set(token, 32);
+        const n = this.#write(joined);
+        return this.#x.derive_token_record_account(n) === 1 ? this.#read() : null;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",