@x1id/resolve 0.3.0 → 0.7.0

package/dist/recordWrite.js

@@ -0,0 +1,228 @@
+/**
+ * Write builders for the address `Record` family: `create_record` and the
+ * three `verify_record_*` proof-of-control instructions (ETH/secp256k1,
+ * SVM/ed25519, BTC/BIP-137). `records.ts` was read-only until now — every
+ * other record family (text records, attestations, vouchers, subnames...)
+ * already had write builders; this was the one gap (WP #8142).
+ *
+ * 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 `["record", handlePda, coinTypeLE(4)]`
+ * with your runtime's canonical `findProgramAddress`.
+ *
+ * # What this SDK does and does not do for you
+ *
+ * This does NOT sign anything, derive an address from a signature, or
+ * verify a signature client-side — that's the on-chain program's job
+ * (`verify_record_eth`/`svm`/`btc` recover the signer's address from the
+ * signature itself and compare it to the record's claimed value; a client
+ * proving nothing false cannot fabricate a match). What this module DOES do:
+ *
+ * 1. {@link buildRecordChallenge} — build the exact bytes a wallet must
+ *    sign, byte-identical to `handle-normalize`'s Rust `challenge()`
+ *    (verified: `crates/handle-normalize/src/challenge.rs`). Unlike the
+ *    off-chain control-proof flow (`control.ts`), this challenge's nonce
+ *    does NOT need to be server-issued — the on-chain transaction landing
+ *    IS the single-use event, so any ASCII-alphanumeric nonce (1..=64
+ *    chars) the caller picks is fine.
+ * 2. {@link splitEthSignature} / {@link splitBtcSignature} — repackage what
+ *    a wallet's `personal_sign` (ETH) or `signmessage` (BTC) actually
+ *    returns into the exact args each verify instruction expects.
+ * 3. The four instruction builders themselves.
+ *
+ * # ETH: EIP-191 `personal_sign`, not EIP-712
+ *
+ * `verify_record_eth` (lib.rs) hashes the challenge with EIP-191's
+ * `"\x19Ethereum Signed Message:\n" + len + message` framing — the exact
+ * framing every wallet's `personal_sign` / `eth_sign` RPC method produces.
+ * There is no EIP-712 typed-data variant on-chain to build a client for.
+ *
+ * # BTC: mainnet-only, compressed P2PKH or bech32/P2WPKH only
+ *
+ * `verify_record_btc` derives the address FROM the recovered pubkey (never
+ * trusts a client-supplied address) and only accepts the header-byte ranges
+ * for compressed P2PKH (31-34) and bech32/P2WPKH (39-42) — see `btc.rs`'s
+ * module doc for exactly why uncompressed P2PKH and P2SH-segwit are refused
+ * rather than guessed. {@link splitBtcSignature} passes the header byte
+ * through unchanged; it is the wallet's job to produce one of the two
+ * supported ranges (most current wallets do).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { recordDelegateNonePlaceholder, recordDelegateSomeSlot } from "./delegate.js";
+import { normalizeHandle } from "./parse.js";
+import { ResolveError } from "./types.js";
+/** Matches `control.ts`'s identically-named private helper: STRICT
+ *  canonical-form check (reject, never silently transform), mirroring the
+ *  Rust `is_canonical` the challenge builder must match exactly —
+ *  `normalizeHandle` alone would accept `"@Alice"` by transforming it,
+ *  which `handle_normalize::challenge` (Rust) does NOT: it demands
+ *  already-canonical input and rejects anything else outright. */
+function isCanonicalHandle(handle) {
+    try {
+        return normalizeHandle(handle) === handle;
+    }
+    catch {
+        return false;
+    }
+}
+export const CREATE_RECORD_DISCRIMINATOR = Uint8Array.from([
+    116, 124, 63, 58, 126, 204, 178, 10,
+]);
+export const VERIFY_RECORD_ETH_DISCRIMINATOR = Uint8Array.from([
+    57, 157, 98, 0, 160, 210, 94, 234,
+]);
+export const VERIFY_RECORD_SVM_DISCRIMINATOR = Uint8Array.from([
+    234, 151, 82, 212, 185, 112, 234, 212,
+]);
+export const VERIFY_RECORD_BTC_DISCRIMINATOR = Uint8Array.from([
+    54, 50, 183, 232, 122, 200, 194, 64,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const NONCE_RE = /^[0-9A-Za-z]{1,64}$/;
+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 encVec(bytes) {
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function encString(s) {
+    return encVec(new TextEncoder().encode(s));
+}
+function pushAuthorityTail(keys, programId, p) {
+    if (p.recordDelegate !== undefined) {
+        keys.push(recordDelegateSomeSlot(p.recordDelegate));
+    }
+    else if (p.holderTokenAccount !== undefined) {
+        keys.push(recordDelegateNonePlaceholder(programId));
+    }
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+}
+// ---------------------------------------------------------------------------
+// Challenge
+// ---------------------------------------------------------------------------
+/**
+ * `x1-handles:v1:<handle>:<coinType>:<registeredAt>:<nonce>` — byte-identical
+ * to `handle_normalize::challenge` (Rust). `handle` must already be
+ * canonical (pass it through {@link import("./parse.js").normalizeHandle}
+ * first if it might have a leading `@` or mixed case).
+ */
+export function buildRecordChallenge(handle, coinType, registeredAt, nonce) {
+    if (!isCanonicalHandle(handle)) {
+        throw new ResolveError("invalid-handle", `"${handle}" is not a canonical handle`, handle);
+    }
+    if (!NONCE_RE.test(nonce)) {
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    }
+    return `x1-handles:v1:${handle}:${coinType}:${registeredAt}:${nonce}`;
+}
+/** Split a 65-byte ETH `personal_sign` output (`r(32) || s(32) || v(1)`)
+ *  into `verify_record_eth`'s `{signature: [u8;64], recoveryId: u8}`,
+ *  normalizing `v`'s two common conventions (27/28, matching most wallets'
+ *  raw RPC output, or already 0/1). */
+export function splitEthSignature(sig65) {
+    if (sig65.length !== 65)
+        throw new Error("ETH signature must be exactly 65 bytes (r || s || v)");
+    const v = sig65[64];
+    const recoveryId = v >= 27 ? v - 27 : v;
+    if (recoveryId !== 0 && recoveryId !== 1) {
+        throw new Error(`unrecognized recovery id byte: ${v}`);
+    }
+    return { signature: sig65.slice(0, 64), recoveryId };
+}
+/** Split a 65-byte BTC BIP-137 `signmessage` output (`header(1) || r(32) ||
+ *  s(32)`) into `verify_record_btc`'s `{header, signature: [u8;64]}`. The
+ *  header byte is passed through unchanged — see the module docs for which
+ *  ranges `verify_record_btc` accepts. */
+export function splitBtcSignature(sig65) {
+    if (sig65.length !== 65)
+        throw new Error("BTC signature must be exactly 65 bytes (header || r || s)");
+    return { header: sig65[0], signature: sig65.slice(1) };
+}
+export function buildCreateRecordIx(p) {
+    if (p.value.length === 0 || p.value.length > 64) {
+        throw new Error("value must be 1..=64 bytes");
+    }
+    const coinTypeBytes = new Uint8Array(4);
+    new DataView(coinTypeBytes.buffer).setUint32(0, p.coinType, true);
+    const data = new Uint8Array(8 + 4 + 4 + p.value.length);
+    data.set(CREATE_RECORD_DISCRIMINATOR, 0);
+    data.set(coinTypeBytes, 8);
+    data.set(encVec(p.value), 12);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+export function buildVerifyRecordEthIx(p) {
+    if (p.signature.length !== 64)
+        throw new Error("signature must be exactly 64 bytes (r || s)");
+    if (p.recoveryId !== 0 && p.recoveryId !== 1)
+        throw new Error("recoveryId must be 0 or 1");
+    if (!NONCE_RE.test(p.nonce))
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    const nonceEnc = encString(p.nonce);
+    const data = new Uint8Array(8 + nonceEnc.length + 64 + 1);
+    data.set(VERIFY_RECORD_ETH_DISCRIMINATOR, 0);
+    data.set(nonceEnc, 8);
+    data.set(p.signature, 8 + nonceEnc.length);
+    data[8 + nonceEnc.length + 64] = p.recoveryId;
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+export function buildVerifyRecordSvmIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.claimed, "claimed"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data: VERIFY_RECORD_SVM_DISCRIMINATOR.slice() };
+}
+export function buildVerifyRecordBtcIx(p) {
+    if (p.signature.length !== 64)
+        throw new Error("signature must be exactly 64 bytes (r || s)");
+    if (!Number.isInteger(p.header) || p.header < 0 || p.header > 255) {
+        throw new Error("header must be a single byte (0-255)");
+    }
+    if (!NONCE_RE.test(p.nonce))
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    const nonceEnc = encString(p.nonce);
+    const data = new Uint8Array(8 + nonceEnc.length + 65);
+    data.set(VERIFY_RECORD_BTC_DISCRIMINATOR, 0);
+    data.set(nonceEnc, 8);
+    data[8 + nonceEnc.length] = p.header;
+    data.set(p.signature, 8 + nonceEnc.length + 1);
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/records.d.ts

@@ -19,6 +19,15 @@
  * There is deliberately no way to decode or fetch a record through this
  * module without the handle's `registered_at` in hand, mirroring
  * app/src/lib/x1/records.ts. See docs/record-trust.md for the full argument.
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer. The same functions therefore also demand the handle's
+ * `recordsClearedAt` (0 if never cleared, from `ParsedHandle`) and a record
+ * is `stale` when EITHER `updated_at < registeredAt` OR
+ * `updated_at < recordsClearedAt` — see `Handle::read_records_cleared_at`'s
+ * doc comment in state.rs.
  */
 import { type Chain } from "./types.js";
 import type { RpcFn } from "./accounts.js";
@@ -75,7 +84,10 @@ export interface HandleRecord {
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale` (and so `verified`).
- * There is intentionally no overload without it.
+ * `recordsClearedAt` is the same Handle's `recordsClearedAt` (0 if never
+ * cleared, #8139) — a SECOND, independent staleness anchor, checked
+ * alongside (not instead of) `registeredAt`. There is intentionally no
+ * overload without either.
  *
  * Returns null for anything that is not a Record: wrong length, wrong
  * discriminator, or a `value` length that does not fit. The Listing / Offer /
@@ -83,7 +95,7 @@ export interface HandleRecord {
  * so a handle-only memcmp scan DOES return them — they are rejected here by
  * tag and size, not by luck.
  */
-export declare function decodeRecord(raw: Uint8Array, account: string, registeredAt: bigint): HandleRecord | null;
+export declare function decodeRecord(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint): HandleRecord | null;
 /** The records the CURRENT owner actually has — `stale` ones excluded. This
  *  is the list to resolve against, display to a visitor, and count. */
 export declare function liveRecords(records: readonly HandleRecord[]): HandleRecord[];
@@ -105,9 +117,14 @@ export declare function valueToAddress(chain: Chain | null, value: Uint8Array):
  *
  * `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 record is returned,
- * stale ones flagged (`verified` already forced false), so an owner surface
- * can show what a previous owner left behind; anything that resolves,
- * displays to a visitor, or counts takes `liveRecords(...)`.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it, not a
+ * literal 0, unless the records being fetched genuinely hang off a DIFFERENT
+ * account than the one `clear_records` could ever touch (e.g. a subname's
+ * own records, keyed by the subname's `createdAt` instead — see
+ * `subname.ts`). Every record is returned, stale ones flagged (`verified`
+ * already forced false), so an owner surface can show what a previous owner
+ * left behind; anything that resolves, displays to a visitor, or counts
+ * takes `liveRecords(...)`.
  */
-export declare function fetchRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint): Promise<HandleRecord[]>;
+export declare function fetchRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint): Promise<HandleRecord[]>;

package/dist/records.js

@@ -19,6 +19,15 @@
  * There is deliberately no way to decode or fetch a record through this
  * module without the handle's `registered_at` in hand, mirroring
  * app/src/lib/x1/records.ts. See docs/record-trust.md for the full argument.
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer. The same functions therefore also demand the handle's
+ * `recordsClearedAt` (0 if never cleared, from `ParsedHandle`) and a record
+ * is `stale` when EITHER `updated_at < registeredAt` OR
+ * `updated_at < recordsClearedAt` — see `Handle::read_records_cleared_at`'s
+ * doc comment in state.rs.
  */
 import { encodeBase58 } from "./base58.js";
 import { CHAIN_COIN_TYPE } from "./types.js";
@@ -52,7 +61,10 @@ export function chainForCoinType(coinType) {
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale` (and so `verified`).
- * There is intentionally no overload without it.
+ * `recordsClearedAt` is the same Handle's `recordsClearedAt` (0 if never
+ * cleared, #8139) — a SECOND, independent staleness anchor, checked
+ * alongside (not instead of) `registeredAt`. There is intentionally no
+ * overload without either.
  *
  * Returns null for anything that is not a Record: wrong length, wrong
  * discriminator, or a `value` length that does not fit. The Listing / Offer /
@@ -60,7 +72,7 @@ export function chainForCoinType(coinType) {
  * so a handle-only memcmp scan DOES return them — they are rejected here by
  * tag and size, not by luck.
  */
-export function decodeRecord(raw, account, registeredAt) {
+export function decodeRecord(raw, account, registeredAt, recordsClearedAt) {
     if (raw.length !== RECORD_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -83,7 +95,7 @@ export function decodeRecord(raw, account, registeredAt) {
     const verified = raw[o] === 1;
     o += 1;
     const updatedAt = dv.getBigInt64(o, true);
-    const stale = updatedAt < registeredAt;
+    const stale = updatedAt < registeredAt || updatedAt < recordsClearedAt;
     const chain = chainForCoinType(coinType);
     return {
         account,
@@ -142,12 +154,17 @@ function hexToBytes(hex) {
  *
  * `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 record is returned,
- * stale ones flagged (`verified` already forced false), so an owner surface
- * can show what a previous owner left behind; anything that resolves,
- * displays to a visitor, or counts takes `liveRecords(...)`.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it, not a
+ * literal 0, unless the records being fetched genuinely hang off a DIFFERENT
+ * account than the one `clear_records` could ever touch (e.g. a subname's
+ * own records, keyed by the subname's `createdAt` instead — see
+ * `subname.ts`). Every record is returned, stale ones flagged (`verified`
+ * already forced false), so an owner surface can show what a previous owner
+ * left behind; anything that resolves, displays to a visitor, or counts
+ * takes `liveRecords(...)`.
  */
-export async function fetchRecords(rpc, programId, handleAccount, registeredAt) {
+export async function fetchRecords(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -166,7 +183,7 @@ export async function fetchRecords(rpc, programId, handleAccount, registeredAt)
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const r = decodeRecord(raw, a.pubkey, registeredAt);
+        const r = decodeRecord(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 record to
         // this handle. A malformed account is skipped, not fatal to the list.

package/dist/register.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `register` — the core write instruction: pay the current ramp price and
+ * claim an unregistered `["handle", name]` PDA. Every other write path in
+ * this SDK (voucher, subname, lock, delegate, attestation, text record,
+ * integrator) already has a builder; this was the one gap.
+ *
+ * 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 `["config"]` / `["handle", name]` with your
+ * runtime's canonical `findProgramAddress`.
+ *
+ * `register`'s price is computed ON-CHAIN at execution time (time + volume
+ * ramp over `Config.tier_lamports`) — there is no client-supplied price or
+ * slippage parameter; the payer simply pays whatever the program charges as
+ * of the landing slot. {@link fetchConfigTreasury} reads the one `Config`
+ * field this builder needs (the treasury address every registration pays).
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+import type { HandleTypeValue } from "./voucher.js";
+/** Anchor instruction discriminator: `sha256("global:register")[0..8]`. */
+export declare const REGISTER_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:register_with_forti")[0..8]`. */
+export declare const REGISTER_WITH_FORTI_DISCRIMINATOR: Uint8Array;
+/**
+ * Read `Config.treasury` — the account every `register` call pays — given
+ * the `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ * shaped like a `Config` (too short to hold `treasury`).
+ */
+export declare function fetchConfigTreasury(rpc: RpcFn, configAccount: string): Promise<string | null>;
+export interface RegisterParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the registration fee and the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — a handle can be registered on
+     *  someone else's behalf (gifting, merchant onboarding). */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — read it fresh via {@link fetchConfigTreasury}
+     *  (it's admin-rotatable, so don't cache it across a session). */
+    readonly treasury: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist. */
+    readonly handle: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** OPTIONAL revenue-share pair (#7397) — supply BOTH or NEITHER; supplying
+     *  exactly one fails on-chain (`IntegratorNotAllowed`). */
+    readonly integrator?: AddressLike;
+    /** The `["integrator", integrator]` allowlist PDA. */
+    readonly integratorAllowlist?: AddressLike;
+}
+/**
+ * Build `register`. Price is computed on-chain (see the module docs) — this
+ * builder does not know or assert it; simulate first if you need to show the
+ * payer a price before they sign.
+ */
+export declare function buildRegisterIx(p: RegisterParams): BuiltInstruction;
+/** The `Config` fields `register_with_forti` needs beyond what
+ *  {@link fetchConfigTreasury} already reads. `fortiRatePerLamport === 0n`
+ *  means FORTI payment is not enabled on this deployment — the same
+ *  `ZeroFortiRate` gate the program itself enforces; callers should refuse
+ *  to build the instruction rather than let it fail on-chain. */
+export interface ConfigForti {
+    readonly fortiMint: string;
+    readonly fortiTreasuryAta: string;
+    readonly veFortiProgram: string;
+    readonly fortiBuybackRecipient: string;
+    readonly fortiRatePerLamport: bigint;
+}
+/** Read the `Config` fields a `register_with_forti` build needs, given the
+ *  `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ *  shaped like a post-#8136 `Config` (too short to hold these fields —
+ *  e.g. a `Config` that hasn't run `migrate_config_v4` yet). */
+export declare function fetchConfigForti(rpc: RpcFn, configAccount: string): Promise<ConfigForti | null>;
+export interface RegisterWithFortiParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the FORTI amount and the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — same as {@link RegisterParams.owner}. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.forti_mint` — {@link fetchConfigForti}. */
+    readonly fortiMint: AddressLike;
+    /** The PAYER's associated token account for `fortiMint` — derive with your
+     *  runtime's canonical ATA derivation (Token-2022; the real testnet FORTI
+     *  mint is Token-2022, not classic SPL Token). */
+    readonly payerFortiAccount: AddressLike;
+    /** `Config.forti_treasury_ata` — {@link fetchConfigForti}. */
+    readonly fortiTreasuryAta: AddressLike;
+    /** `Config.forti_buyback_recipient` — {@link fetchConfigForti}. */
+    readonly fortiBuybackRecipient: AddressLike;
+    /** The payer's veFORTI lock PDA (`["lock", payer]` under
+     *  `Config.veforti_program`) — may not exist (payer never locked), in
+     *  which case the program treats voting power as zero. Derive with your
+     *  runtime's canonical `findProgramAddress` against
+     *  `fetchConfigForti(...).veFortiProgram`. */
+    readonly veFortiLock: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist. */
+    readonly handle: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** The token program that owns `fortiMint` — Token-2022 on testnet today;
+     *  pass whichever `fortiMint`'s own `owner` field names, never hardcode. */
+    readonly tokenProgram: AddressLike;
+}
+/**
+ * Build `register_with_forti` (#8136) — a SIBLING payment path to
+ * `register`, not a replacement. Price is computed on-chain the same way
+ * `register`'s is (see that builder's docs) — this builder does not know or
+ * assert it; use `/quote/:name?pay_with=forti[&payer=...]` (tools/api) or
+ * simulate first if you need to show the payer a price before they sign.
+ */
+export declare function buildRegisterWithFortiIx(p: RegisterWithFortiParams): BuiltInstruction;

package/dist/register.js

@@ -0,0 +1,183 @@
+/**
+ * `register` — the core write instruction: pay the current ramp price and
+ * claim an unregistered `["handle", name]` PDA. Every other write path in
+ * this SDK (voucher, subname, lock, delegate, attestation, text record,
+ * integrator) already has a builder; this was the one gap.
+ *
+ * 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 `["config"]` / `["handle", name]` with your
+ * runtime's canonical `findProgramAddress`.
+ *
+ * `register`'s price is computed ON-CHAIN at execution time (time + volume
+ * ramp over `Config.tier_lamports`) — there is no client-supplied price or
+ * slippage parameter; the payer simply pays whatever the program charges as
+ * of the landing slot. {@link fetchConfigTreasury} reads the one `Config`
+ * field this builder needs (the treasury address every registration pays).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Anchor instruction discriminator: `sha256("global:register")[0..8]`. */
+export const REGISTER_DISCRIMINATOR = Uint8Array.from([
+    211, 124, 67, 15, 211, 194, 178, 240,
+]);
+/** Anchor instruction discriminator: `sha256("global:register_with_forti")[0..8]`. */
+export const REGISTER_WITH_FORTI_DISCRIMINATOR = Uint8Array.from([
+    48, 73, 211, 175, 49, 236, 133, 82,
+]);
+/** Byte offset of `treasury` within a `Config` account (after the 8-byte
+ *  discriminator: `admin: Pubkey(32)` then `treasury: Pubkey(32)` at 40). */
+const CONFIG_TREASURY_OFFSET = 40;
+const PUBKEY_LEN = 32;
+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));
+}
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+/**
+ * Read `Config.treasury` — the account every `register` call pays — given
+ * the `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ * shaped like a `Config` (too short to hold `treasury`).
+ */
+export async function fetchConfigTreasury(rpc, configAccount) {
+    const res = (await rpc("getAccountInfo", [
+        configAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data = res?.value?.data?.[0];
+    if (!data)
+        return null;
+    const bin = atob(data);
+    if (bin.length < CONFIG_TREASURY_OFFSET + PUBKEY_LEN)
+        return null;
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    return encodeBase58(raw.slice(CONFIG_TREASURY_OFFSET, CONFIG_TREASURY_OFFSET + PUBKEY_LEN));
+}
+/**
+ * Build `register`. Price is computed on-chain (see the module docs) — this
+ * builder does not know or assert it; simulate first if you need to show the
+ * payer a price before they sign.
+ */
+export function buildRegisterIx(p) {
+    if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+    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);
+    data.set(REGISTER_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nameBytes.length, true);
+    data.set(nameBytes, 12);
+    data[12 + nameBytes.length] = p.handleType;
+    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: 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 };
+}
+// ============================= register_with_forti (#8136, WP #8200) =============================
+/** Byte offsets of the `Config` fields `register_with_forti` needs, verbatim
+ *  from state.rs's field order (confirmed against `migrate_config_v4`'s own
+ *  write order in lib.rs) — lying after `treasury` (40) this module's own
+ *  {@link fetchConfigTreasury} already reads:
+ *    ...recovery_timelock_secs(i64)@256 lease_rate_divisor(u64)@264
+ *    lease_grace_period_secs(i64)@272 forti_mint(32)@280
+ *    forti_treasury_ata(32)@312 veforti_program(32)@344
+ *    forti_buyback_recipient(32)@376 forti_rate_per_lamport(u64)@408
+ *    veforti_bonus_bps(u16)@416 forti_buyback_share_bps(u16)@418 */
+const CONFIG_FORTI_MINT_OFFSET = 280;
+const CONFIG_FORTI_TREASURY_ATA_OFFSET = 312;
+const CONFIG_VEFORTI_PROGRAM_OFFSET = 344;
+const CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET = 376;
+const CONFIG_FORTI_RATE_OFFSET = 408;
+const CONFIG_FORTI_MIN_LEN = CONFIG_FORTI_RATE_OFFSET + 8;
+/** Read the `Config` fields a `register_with_forti` build needs, given the
+ *  `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ *  shaped like a post-#8136 `Config` (too short to hold these fields —
+ *  e.g. a `Config` that hasn't run `migrate_config_v4` yet). */
+export async function fetchConfigForti(rpc, configAccount) {
+    const res = (await rpc("getAccountInfo", [
+        configAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data = res?.value?.data?.[0];
+    if (!data)
+        return null;
+    const bin = atob(data);
+    if (bin.length < CONFIG_FORTI_MIN_LEN)
+        return null;
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        fortiMint: encodeBase58(raw.slice(CONFIG_FORTI_MINT_OFFSET, CONFIG_FORTI_MINT_OFFSET + PUBKEY_LEN)),
+        fortiTreasuryAta: encodeBase58(raw.slice(CONFIG_FORTI_TREASURY_ATA_OFFSET, CONFIG_FORTI_TREASURY_ATA_OFFSET + PUBKEY_LEN)),
+        veFortiProgram: encodeBase58(raw.slice(CONFIG_VEFORTI_PROGRAM_OFFSET, CONFIG_VEFORTI_PROGRAM_OFFSET + PUBKEY_LEN)),
+        fortiBuybackRecipient: encodeBase58(raw.slice(CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET, CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET + PUBKEY_LEN)),
+        fortiRatePerLamport: dv.getBigUint64(CONFIG_FORTI_RATE_OFFSET, true),
+    };
+}
+/**
+ * Build `register_with_forti` (#8136) — a SIBLING payment path to
+ * `register`, not a replacement. Price is computed on-chain the same way
+ * `register`'s is (see that builder's docs) — this builder does not know or
+ * assert it; use `/quote/:name?pay_with=forti[&payer=...]` (tools/api) or
+ * simulate first if you need to show the payer a price before they sign.
+ */
+export function buildRegisterWithFortiIx(p) {
+    if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+    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);
+    data.set(REGISTER_WITH_FORTI_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nameBytes.length, true);
+    data.set(nameBytes, 12);
+    data[12 + nameBytes.length] = p.handleType;
+    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.fortiMint, "fortiMint"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.payerFortiAccount, "payerFortiAccount"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.fortiTreasuryAta, "fortiTreasuryAta"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.fortiBuybackRecipient, "fortiBuybackRecipient"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.veFortiLock, "veFortiLock"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.tokenProgram, "tokenProgram"), isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}