@x1id/resolve 0.2.0 → 0.3.0

package/dist/recordCount.js

@@ -0,0 +1,114 @@
+/**
+ * The record_count Handle extension (#7384): decode helper for the on-chain
+ * live-record counter, plus the instruction builder for the admin-only
+ * `backfill_record_count` migration path.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). The builder returns
+ * the same transport-neutral {@link BuiltInstruction} `delegate.ts` uses.
+ *
+ * # The extension, mirrored from state.rs's EXTENSION OFFSET REGISTRY
+ *
+ * A `Handle` account's struct is frozen at 157 bytes (`8 + INIT_SPACE`);
+ * features append fixed-offset raw regions past it:
+ *
+ *   offset  size  region
+ *   157     33    NFT capability extension (presence tag + mint pubkey)
+ *   190      1    RESERVED lock byte (#7377, unbuilt)
+ *   191      5    record_count: presence tag + u32 LE live-record count
+ *   196      —    next free offset
+ *
+ * `create_record` increments the count (initializing the extension and
+ * growing the account on first use — which is why the record-editing
+ * create/close instructions pass the HANDLE account WRITABLE as of this
+ * feature; the account LIST is unchanged), `close_record` decrements it
+ * (saturating, only when initialized), and `release_handle` refuses while an
+ * initialized count is nonzero (`HandleHasRecords`, code 6044).
+ *
+ * # Uninitialized is NOT zero
+ *
+ * {@link readRecordCount} returns `null` for a handle whose extension is
+ * uninitialized — an account too short (a pre-#7384 handle) or a presence
+ * byte still zero (grown for the NFT extension, never counted). Such a
+ * handle keeps the OLD unguarded release behaviour until the admin stamps it
+ * via `backfill_record_count` or a post-upgrade `create_record` initializes
+ * it. A `0` return, by contrast, is an initialized, trustworthy
+ * "provably no live records". Never conflate the two: rendering `null` as
+ * "0 records" would tell an owner their release is safe when the program
+ * cannot actually vouch for that.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** `8 + Handle::INIT_SPACE` — the frozen base struct size, and the first
+ *  extension offset. */
+export const HANDLE_BASE_LEN = 157;
+/** Byte offset of the record_count extension: base(157) + NFT ext(33) +
+ *  reserved lock byte(1). */
+export const RECORD_COUNT_EXT_OFFSET = 191;
+/** presence tag(1) + u32 LE count(4). */
+export const RECORD_COUNT_EXT_LEN = 5;
+/** One past the last known extension region (must match the program's
+ *  `Handle::KNOWN_EXT_END`) — the size a fully-grown Handle account has under
+ *  this program version. Layout: base(157) + NFT(33) + reserved(1) +
+ *  record_count(5) + lock(9) = 205. Was 196 (pre-lock); the #7377 lock extension
+ *  (see LOCK_EXT_OFFSET=196 / LOCK_EXT_LEN=9 in lock.ts) pushed it to 205, so any
+ *  consumer allocating/resizing to this constant must use the current value. */
+export const HANDLE_KNOWN_EXT_END = 205;
+/** Anchor instruction discriminator:
+ *  `sha256("global:backfill_record_count")[0..8]`. Pinned (this SDK is
+ *  zero-dependency and cannot assume WebCrypto SHA-256 everywhere it runs);
+ *  asserted against a re-derivation in the test suite so a typo can never
+ *  silently pass. */
+export const BACKFILL_RECORD_COUNT_DISCRIMINATOR = Uint8Array.from([
+    151, 122, 233, 167, 188, 54, 32, 110,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBase58(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return encodeBase58(b);
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return encodeBase58(v);
+}
+/**
+ * Read the live-record count from a `Handle` account's raw data (exactly
+ * what an RPC `getAccountInfo` returns for the `["handle", name]` PDA).
+ *
+ * Returns the count when the extension is INITIALIZED, and `null` when it is
+ * not — see the module docs for why `null` and `0` mean different things and
+ * must be rendered differently. Mirrors the program's
+ * `Handle::read_record_count` tolerance exactly: a short account and a
+ * zeroed region are both `null`, never an error.
+ */
+export function readRecordCount(data) {
+    if (data.length < RECORD_COUNT_EXT_OFFSET + RECORD_COUNT_EXT_LEN)
+        return null;
+    if (data[RECORD_COUNT_EXT_OFFSET] === 0)
+        return null;
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(RECORD_COUNT_EXT_OFFSET + 1, true);
+}
+/**
+ * Build `backfill_record_count` — admin-only: stamp a pre-#7384 handle's
+ * record_count extension with the off-chain-computed truth, moving it
+ * permanently out of the unguarded-release window. Mainnet never needs it
+ * (the mainnet registry starts fresh at cutover, counted from the first
+ * record); this is testnet migration + permanent correction tooling.
+ */
+export function buildBackfillRecordCountIx(p) {
+    if (!Number.isInteger(p.count) || p.count < 0 || p.count > 0xffffffff) {
+        throw new Error("count must be a u32");
+    }
+    const data = new Uint8Array(8 + 4);
+    data.set(BACKFILL_RECORD_COUNT_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, p.count, true);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/records.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+import { type Chain } from "./types.js";
+import type { RpcFn } from "./accounts.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 declare 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 declare const RECORD_DISC = "fee975fc4ca6928b";
+/** 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 declare function chainForCoinType(coinType: number): Chain | null;
+/** A decoded per-chain payment record, staleness already judged. */
+export interface HandleRecord {
+    /** The Record account's address, base58. */
+    readonly account: string;
+    /** The Handle account this record hangs off, base58. */
+    readonly handle: string;
+    readonly coinType: number;
+    /** Which chain `coinType` maps to, or null for an unknown coin type. */
+    readonly chain: Chain | null;
+    /** Raw bytes as stored on-chain. */
+    readonly value: Uint8Array;
+    /** Human-readable address string — see `valueToAddress`. */
+    readonly address: string;
+    /**
+     * `Record.verified` AS STORED, gated by the staleness rule: `false`
+     * whenever the record is `stale`, whatever the account says. A stale
+     * `true` is a proof a PREVIOUS owner made; it is never surfaced as a
+     * verification of the current owner's address.
+     */
+    readonly verified: boolean;
+    /** `Record.updated_at`, unix seconds. */
+    readonly updatedAt: bigint;
+    /**
+     * The rule docs/record-trust.md mandates: this record is only the current
+     * owner's if `updated_at >= handle.registered_at`. A stale record belongs
+     * to a previous, unrelated owner of the same name: it must never be
+     * resolved as this name's address, never counted, and only ever offered
+     * to the CURRENT owner as something to remove.
+     */
+    readonly stale: boolean;
+}
+/**
+ * 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`).
+ * There is intentionally no overload without it.
+ *
+ * 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 declare function decodeRecord(raw: Uint8Array, account: string, registeredAt: 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[];
+/**
+ * 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 declare function valueToAddress(chain: Chain | null, value: Uint8Array): string;
+/**
+ * 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. 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[]>;

package/dist/records.js

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+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`).
+ * There is intentionally no overload without it.
+ *
+ * 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) {
+    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;
+    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. 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) {
+    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);
+        // 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;
+}