@x1id/resolve 0.2.1 → 0.6.0

package/dist/records.js

@@ -0,0 +1,195 @@
+/**
+ * Per-chain payment records (`Record` accounts) — read WITH the universal
+ * staleness rule from docs/record-trust.md structurally enforced.
+ *
+ * # Why every function here demands `registeredAt`
+ *
+ * A `Handle`'s address is `["handle", name]` — a pure function of the name.
+ * Release + re-register lands the new registration at the SAME pubkey, and
+ * `Record` PDAs (`["record", handle_pubkey, coin_type]`) hang off that pubkey,
+ * so a record a PREVIOUS owner created (possibly `verified: true` for THEIR
+ * address) is physically attached to the new owner's name with no action by
+ * anyone. The program cannot prevent this (state.rs, `Handle` doc comment);
+ * the mandatory read-side rule is:
+ *
+ *     record.updated_at >= handle.registered_at
+ *
+ * A record that fails it belongs to a previous, unrelated owner and must be
+ * treated as unset/unverified — for PAYMENT resolution, not just badges.
+ * 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";
+/** `8 + Record::INIT_SPACE` — the program allocates the full 64-byte `value`
+ *  capacity, so every Record account is exactly this long:
+ *  8 + 32 + 4 + (4 + 64) + 1 + 8 + 1. */
+export const RECORD_LEN = 122;
+/** `sha256("account:Record")[..8]`, hex — the tag every Record account's
+ *  data starts with. Pinned (this SDK is zero-dependency and cannot assume
+ *  WebCrypto SHA-256 everywhere it runs); the value is asserted against a
+ *  re-derivation in the test suite so a typo can never silently pass. */
+export const RECORD_DISC = "fee975fc4ca6928b";
+/** Byte offset of `handle` within a Record account: the 8-byte discriminator. */
+const RECORD_HANDLE_OFFSET = 8;
+/** Reverse of CHAIN_COIN_TYPE — which chain a stored coin_type belongs to, or
+ *  null for a coin_type this SDK does not know how to render. */
+export function chainForCoinType(coinType) {
+    for (const c of Object.keys(CHAIN_COIN_TYPE)) {
+        if (CHAIN_COIN_TYPE[c] === coinType)
+            return c;
+    }
+    return null;
+}
+/**
+ * Decode one Record account.
+ *
+ * Record account layout, after the 8-byte Anchor discriminator:
+ *
+ *   handle: Pubkey(32)  coin_type: u32(4)  value: Vec<u8> (u32 len + bytes, max 64)
+ *   verified: bool(1)  updated_at: i64(8)  bump: u8(1)
+ *
+ * `registeredAt` is the owning Handle's `registered_at`, decoded by the
+ * caller from the Handle account — it decides `stale` (and so `verified`).
+ * `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 /
+ * Auction PDAs of the same handle also carry the handle pubkey at offset 8,
+ * 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, recordsClearedAt) {
+    if (raw.length !== RECORD_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (raw[i] !== parseInt(RECORD_DISC.slice(i * 2, i * 2 + 2), 16))
+            return null;
+    }
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    let o = 8;
+    const handle = encodeBase58(raw.slice(o, o + 32));
+    o += 32;
+    const coinType = dv.getUint32(o, true);
+    o += 4;
+    const len = dv.getUint32(o, true);
+    o += 4;
+    // `#[max_len(64)]` — and the fixed fields after `value` must still fit.
+    if (len > 64 || o + len + 1 + 8 + 1 > raw.length)
+        return null;
+    const value = raw.slice(o, o + len);
+    o += len;
+    const verified = raw[o] === 1;
+    o += 1;
+    const updatedAt = dv.getBigInt64(o, true);
+    const stale = updatedAt < registeredAt || updatedAt < recordsClearedAt;
+    const chain = chainForCoinType(coinType);
+    return {
+        account,
+        handle,
+        coinType,
+        chain,
+        value,
+        address: valueToAddress(chain, value),
+        verified: verified && !stale,
+        updatedAt,
+        stale,
+    };
+}
+/** The records the CURRENT owner actually has — `stale` ones excluded. This
+ *  is the list to resolve against, display to a visitor, and count. */
+export function liveRecords(records) {
+    return records.filter((r) => !r.stale);
+}
+/**
+ * Render stored record bytes for display / payment, per the conventions
+ * app/src/lib/x1/records.ts writes them with: X1/SOL are 32-byte pubkeys
+ * (base58), ETH is 20 raw bytes (0x-hex), BTC is the UTF-8 bytes of the
+ * canonical address string. Unknown coin types render as hex so a value is
+ * never silently hidden.
+ */
+export function valueToAddress(chain, value) {
+    const hex = () => `0x${Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+    if (chain === "X1" || chain === "SOL") {
+        return value.length === 32 ? encodeBase58(value) : hex();
+    }
+    if (chain === "ETH")
+        return hex();
+    if (chain === "BTC") {
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(value);
+        }
+        catch {
+            return hex();
+        }
+    }
+    return hex();
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/**
+ * Fetch every Record account of a handle — one `getProgramAccounts` call,
+ * filtered by the RPC on size (122), the Record discriminator at offset 0
+ * and the handle pubkey at offset 8, then every byte re-checked locally
+ * (the node's filters are an optimisation, never the guarantee). Scoping the
+ * scan to the registry program id also IS the ownership check: a foreign
+ * account cannot appear in it.
+ *
+ * `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. `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, recordsClearedAt) {
+    const res = (await rpc("getProgramAccounts", [
+        programId,
+        {
+            encoding: "base64",
+            commitment: "confirmed",
+            filters: [
+                { dataSize: RECORD_LEN },
+                { memcmp: { offset: 0, bytes: encodeBase58(hexToBytes(RECORD_DISC)) } },
+                { memcmp: { offset: RECORD_HANDLE_OFFSET, bytes: handleAccount } },
+            ],
+        },
+    ]));
+    const out = [];
+    for (const a of res ?? []) {
+        const bin = atob(a.account.data[0]);
+        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, 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.
+        if (r && r.handle === handleAccount)
+            out.push(r);
+    }
+    out.sort((x, y) => (x.chain ?? "").localeCompare(y.chain ?? "") || x.coinType - y.coinType);
+    return out;
+}

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 };
+}