@x1id/resolve 0.23.0 → 0.43.0

package/dist/credentials.js

@@ -0,0 +1,669 @@
+/**
+ * X1ID Verify: third-party credentials (docs/specs/x1id-credentials.md,
+ * program upgrade 6). Instruction builders, account decoders, PDA finders and
+ * the off-chain validity rule for issuer-signed credentials on `@names`.
+ *
+ * # The model
+ *
+ * - Anyone registers an **issuer** (`["issuer", authority]`) for a small fee
+ *   paid to the X1ID treasury. The authority KEY is the issuer's identity; the
+ *   display name is a label and must never be trusted. An issuer can prove it
+ *   is `@acme` with {@link buildLinkIssuerHandleIx} (the name's holder
+ *   co-signs); {@link issuerLinkValid} checks the link is still current.
+ * - Issuers define immutable **schemas** (`["cred_schema", issuer, id]`).
+ * - A **credential** (`["credential", issuer, handle, id]`) is issued with the
+ *   name's CURRENT holder co-signing, may expire, and is revoked only by its
+ *   issuer. Anyone may garbage-collect a dead one (rent goes back to whoever
+ *   paid it).
+ * - A credential counts for the current holder only while it is unexpired,
+ *   its issuer is not Retired and has not invalidated it, it was issued in
+ *   the name's current ownership epoch, and its `subject` IS the current
+ *   holder ({@link credentialValidity}).
+ *
+ * # Never a blue tick
+ *
+ * Third-party credentials NEVER satisfy the X1ID blue tick: `isHandleVerified`,
+ * `"any-verified"` and `{ kind }` gates read only X1ID `Attestation` accounts.
+ * Gate on a credential with an explicit `{ credential: { schema, issuers } }`
+ * clause (gate.ts).
+ *
+ * # Integrators: the issuer set is YOURS
+ *
+ * **When you call `assert_credential` on-chain (CPI or sibling instruction),
+ * the accepted issuer set must be a constant of your program or config,
+ * never taken from the end user's input.** Otherwise a user registers an
+ * issuer, issues a credential to themselves, and names it.
+ *
+ * Routed through the program's `fallback` (`extra_ix`): `sha256("global:<name>")
+ * [..8]` + raw Borsh, accounts exactly in the order of the program's
+ * `Accounts` structs (programs/x1-handles/src/credentials.rs). Hand-rolled,
+ * no web3.js.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+// ---------------------------------------------------------------------------
+// constants (mirror programs/x1-handles/src/credentials.rs)
+// ---------------------------------------------------------------------------
+export const ISSUER_SEED = "issuer";
+export const CRED_SCHEMA_SEED = "cred_schema";
+export const CREDENTIAL_SEED = "credential";
+export const CRED_CONFIG_SEED = "cred_config";
+export const RECOMMENDED_ISSUERS_SEED = "recommended_issuers";
+/** Allocated sizes (8-byte discriminator + `INIT_SPACE`). */
+export const ISSUER_ACCOUNT_LEN = 8 + 416;
+export const CREDENTIAL_SCHEMA_ACCOUNT_LEN = 8 + 324;
+export const CREDENTIAL_ACCOUNT_LEN = 8 + 214;
+export const CRED_CONFIG_ACCOUNT_LEN = 8 + 26;
+export const RECOMMENDED_ISSUERS_ACCOUNT_LEN = 8 + 1038;
+/** Registration fee while the admin never set one: 1 XNT. */
+export const DEFAULT_ISSUER_FEE_LAMPORTS = 1000000000n;
+/** Program caps on the admin-set fees: 100 XNT and 0.1 XNT. */
+export const ISSUER_FEE_MAX_LAMPORTS = 100000000000n;
+export const CREDENTIAL_FEE_MAX_LAMPORTS = 100000000n;
+/** No credential may be valid for more than 10 years (3653 days). */
+export const MAX_CREDENTIAL_VALIDITY_SECS = 3653n * 86400n;
+export const CRED_URI_MAX_LEN = 200;
+/** `assert_credential` accepts 1..=8 issuers. */
+export const MAX_ACCEPTED_ISSUERS = 8;
+export const MAX_RECOMMENDED_ISSUERS = 32;
+export const ISSUER_STATUS = { Active: 0, Paused: 1, Retired: 2 };
+export const SCHEMA_STATUS = { Active: 0, Deprecated: 1 };
+/** Compute-unit limits to request (measured in tests/credentials.rs, with
+ *  headroom; spec §12). */
+export const CREDENTIAL_CU_LIMITS = {
+    registerIssuer: 60_000,
+    createSchema: 50_000,
+    issueCredential: 100_000,
+    renewCredential: 80_000,
+    revokeCredential: 50_000,
+    closeCredential: 50_000,
+    assertCredential: 80_000,
+};
+const d8 = (...b) => Uint8Array.from(b);
+export const REGISTER_ISSUER_DISCRIMINATOR = d8(145, 117, 52, 59, 189, 27, 127, 18);
+export const UPDATE_ISSUER_DISCRIMINATOR = d8(9, 100, 234, 30, 84, 43, 30, 29);
+export const LINK_ISSUER_HANDLE_DISCRIMINATOR = d8(23, 23, 31, 237, 147, 43, 237, 96);
+export const UNLINK_ISSUER_HANDLE_DISCRIMINATOR = d8(5, 206, 46, 125, 153, 25, 244, 141);
+export const CREATE_SCHEMA_DISCRIMINATOR = d8(105, 171, 40, 140, 30, 91, 30, 134);
+export const DEPRECATE_SCHEMA_DISCRIMINATOR = d8(17, 211, 95, 93, 93, 28, 134, 203);
+export const ISSUE_CREDENTIAL_DISCRIMINATOR = d8(255, 193, 171, 224, 68, 171, 194, 87);
+export const RENEW_CREDENTIAL_DISCRIMINATOR = d8(181, 54, 171, 106, 20, 185, 136, 131);
+export const REVOKE_CREDENTIAL_DISCRIMINATOR = d8(38, 123, 95, 95, 223, 158, 169, 87);
+export const CLOSE_CREDENTIAL_DISCRIMINATOR = d8(213, 210, 242, 210, 169, 79, 220, 112);
+export const ASSERT_CREDENTIAL_DISCRIMINATOR = d8(8, 158, 83, 118, 209, 229, 25, 215);
+export const SET_CREDENTIAL_CONFIG_DISCRIMINATOR = d8(35, 210, 7, 175, 5, 130, 150, 109);
+export const SET_RECOMMENDED_ISSUERS_DISCRIMINATOR = d8(163, 195, 233, 222, 182, 84, 219, 150);
+/** `sha256("account:<Name>")[..8]`. */
+export const ISSUER_ACCOUNT_DISCRIMINATOR = d8(216, 19, 83, 230, 108, 53, 80, 14);
+export const CREDENTIAL_SCHEMA_ACCOUNT_DISCRIMINATOR = d8(175, 122, 25, 51, 201, 54, 253, 222);
+export const CREDENTIAL_ACCOUNT_DISCRIMINATOR = d8(145, 44, 68, 220, 67, 46, 100, 135);
+export const CRED_CONFIG_ACCOUNT_DISCRIMINATOR = d8(120, 101, 56, 66, 129, 114, 34, 87);
+export const RECOMMENDED_ISSUERS_ACCOUNT_DISCRIMINATOR = d8(146, 35, 166, 67, 212, 149, 13, 177);
+/** Byte offsets for `getProgramAccounts` `memcmp` filters. */
+export const ISSUER_OFFSETS = { authority: 9, status: 41, invalidateBefore: 42, name: 50, linkedHandle: 115, linkedBy: 147 };
+export const CREDENTIAL_SCHEMA_OFFSETS = { issuer: 9, schemaId: 41, status: 45 };
+export const CREDENTIAL_OFFSETS = { issuer: 9, handle: 41, schemaId: 73, subject: 77, rentPayer: 189 };
+/** Program error codes of the credentials block (fixed range 6158-6189;
+ *  6181-6189 are reserved placeholders). */
+export const CREDENTIAL_ERRORS = {
+    IssuerNameInvalid: 6158,
+    IssuerNameReserved: 6159,
+    IssuerUriTooLong: 6160,
+    IssuerNotActive: 6161,
+    IssuerRetired: 6162,
+    NotIssuerAuthority: 6163,
+    InvalidateBeforeInvalid: 6164,
+    IssuerStatusInvalid: 6165,
+    SchemaNameInvalid: 6166,
+    SchemaNotActive: 6167,
+    SchemaIssuerMismatch: 6168,
+    SchemaValidityInvalid: 6169,
+    CredentialExpiryInvalid: 6170,
+    CredentialExpiryRequired: 6171,
+    CredentialSubjectNotAuthority: 6172,
+    CredentialNotRenewable: 6173,
+    CredentialStillValid: 6174,
+    CredentialIssuerSetInvalid: 6175,
+    CredentialGateNotSatisfied: 6176,
+    CredentialFeeAboveCap: 6177,
+    RecommendedListInvalid: 6178,
+    IssuerHandleLinkInvalid: 6179,
+    CredConfigMismatch: 6180,
+};
+const CREDENTIAL_ERROR_MESSAGES = {
+    6158: "issuer name must be 3-32 characters of a-z, 0-9, space, '.', '_' or '-'",
+    6159: "issuer names may not contain 'x1id'",
+    6160: "uri is longer than 200 bytes",
+    6161: "issuer is not active",
+    6162: "issuer is retired",
+    6163: "signer is not this issuer's authority",
+    6164: "invalidate_before must not decrease and must not be in the future",
+    6165: "invalid issuer status",
+    6166: "schema name must be 3-32 characters of a-z, 0-9, '.', '_' or '-'",
+    6167: "credential schema is not active",
+    6168: "credential schema does not belong to this issuer",
+    6169: "schema max validity must be between 0 and 10 years",
+    6170: "credential expiry is invalid",
+    6171: "this schema requires credentials to expire",
+    6172: "credential subject is not the name's current authority",
+    6173: "credential is not valid and cannot be renewed",
+    6174: "credential may still be valid; only its issuer can revoke it",
+    6175: "accepted issuer set must have 1 to 8 entries",
+    6176: "credential gate not satisfied",
+    6177: "credential fee is above the program cap",
+    6178: "recommended issuer list is invalid",
+    6179: "handle link is invalid: the name's current authority must co-sign",
+    6180: "cred_config account mismatch",
+};
+/** Human message for a credentials error code, or null for another code. */
+export function credentialErrorMessage(code) {
+    return CREDENTIAL_ERROR_MESSAGES[code] ?? null;
+}
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const TE = new TextEncoder();
+const TD = new TextDecoder();
+const U32_MAX = 0xffff_ffff;
+const U64_MAX = 0xffffffffffffffffn;
+const I64_MIN = -(1n << 63n);
+const I64_MAX = (1n << 63n) - 1n;
+// ---------------------------------------------------------------------------
+// encoding helpers
+// ---------------------------------------------------------------------------
+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 key(pubkey, what, isSigner, isWritable) {
+    return { pubkey: toBase58(pubkey, what), isSigner, isWritable };
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((a, p) => a + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function u32le(v, what) {
+    if (!Number.isInteger(v) || v < 0 || v > U32_MAX)
+        throw new Error(`${what} must be a u32`);
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, v, true);
+    return out;
+}
+function u64le(v, what) {
+    if (typeof v !== "bigint" || v < 0n || v > U64_MAX)
+        throw new Error(`${what} must be a u64 bigint`);
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, v, true);
+    return out;
+}
+function i64le(v, what) {
+    if (typeof v !== "bigint" || v < I64_MIN || v > I64_MAX)
+        throw new Error(`${what} must be an i64 bigint`);
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, v, true);
+    return out;
+}
+function encString(s) {
+    const bytes = TE.encode(s);
+    return concat(u32le(bytes.length, "string length"), bytes);
+}
+function hash32(v, what) {
+    if (v === undefined)
+        return new Uint8Array(32);
+    if (v.length !== 32)
+        throw new Error(`${what} must be 32 bytes`);
+    return v;
+}
+function opt(v) {
+    return v === undefined ? Uint8Array.of(0) : concat(Uint8Array.of(1), v);
+}
+function tailKeys(p) {
+    const out = [];
+    if (p.holderAta !== undefined)
+        out.push(key(p.holderAta, "holderAta", false, false));
+    if (p.namespace !== undefined)
+        out.push(key(p.namespace, "namespace", false, false));
+    return out;
+}
+function ix(programId, keys, data) {
+    return { programId: toBase58(programId, "programId"), keys, data };
+}
+// ---------------------------------------------------------------------------
+// name rules (mirror the program; the program is the authority)
+// ---------------------------------------------------------------------------
+/** The display-name rule: 3-32 bytes of `[a-z0-9._-]` (plus single inner
+ *  spaces for issuers), starting and ending with `[a-z0-9]`. */
+export function isValidCredentialName(name, allowSpace = true) {
+    if (!/^[a-z0-9][a-z0-9 ._-]{1,30}[a-z0-9]$/.test(name))
+        return false;
+    if (!allowSpace && name.includes(" "))
+        return false;
+    return !name.includes("  ");
+}
+/** Owner decision Q7: issuer names may not contain `x1id`, also split by
+ *  separators. */
+export function isReservedIssuerName(name) {
+    return name.replace(/[^a-z0-9]/gi, "").toLowerCase().includes("x1id");
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+function idSeed(schemaId) {
+    return u32le(schemaId, "schemaId");
+}
+/** `["issuer", authority]`. */
+export async function findIssuerPda(find, programId, authority) {
+    return find([TE.encode(ISSUER_SEED), toBytes32(authority, "authority")], toBase58(programId, "programId"));
+}
+/** `["cred_schema", issuer, schema_id u32 LE]`. */
+export async function findCredentialSchemaPda(find, programId, issuer, schemaId) {
+    return find([TE.encode(CRED_SCHEMA_SEED), toBytes32(issuer, "issuer"), idSeed(schemaId)], toBase58(programId, "programId"));
+}
+/** `["credential", issuer, handle, schema_id u32 LE]`. */
+export async function findCredentialPda(find, programId, issuer, handle, schemaId) {
+    return find([TE.encode(CREDENTIAL_SEED), toBytes32(issuer, "issuer"), toBytes32(handle, "handle"), idSeed(schemaId)], toBase58(programId, "programId"));
+}
+/** `["cred_config"]`. */
+export async function findCredConfigPda(find, programId) {
+    return find([TE.encode(CRED_CONFIG_SEED)], toBase58(programId, "programId"));
+}
+/** `["recommended_issuers"]`. */
+export async function findRecommendedIssuersPda(find, programId) {
+    return find([TE.encode(RECOMMENDED_ISSUERS_SEED)], toBase58(programId, "programId"));
+}
+// ---------------------------------------------------------------------------
+// decoders
+// ---------------------------------------------------------------------------
+function hasDisc(data, disc) {
+    if (data.length < 8)
+        return false;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== disc[i])
+            return false;
+    return true;
+}
+function view(data) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+}
+const b58 = (d, o) => encodeBase58(d.slice(o, o + 32));
+const ZERO_KEY = encodeBase58(new Uint8Array(32));
+/** Decode a raw `Issuer` (discriminator included); null if it is not one. */
+export function decodeIssuer(data) {
+    if (data.length < 8 + 220 + 4 || !hasDisc(data, ISSUER_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const v = view(data);
+    const status = data[41];
+    if (status > 2)
+        return null;
+    const nameLen = data[82];
+    if (nameLen > 32)
+        return null;
+    const uriLen = v.getUint32(220, true);
+    if (uriLen > CRED_URI_MAX_LEN || data.length < 224 + uriLen)
+        return null;
+    const linked = b58(data, 115);
+    return {
+        version: data[8],
+        authority: b58(data, 9),
+        status: ["active", "paused", "retired"][status],
+        invalidateBefore: v.getBigInt64(42, true),
+        name: TD.decode(data.slice(50, 50 + nameLen)),
+        uriHash: data.slice(83, 115),
+        linkedHandle: linked === ZERO_KEY ? null : linked,
+        linkedBy: linked === ZERO_KEY ? null : b58(data, 147),
+        linkedAt: v.getBigInt64(179, true),
+        createdAt: v.getBigInt64(187, true),
+        feePaid: v.getBigUint64(195, true),
+        issuedCount: v.getBigUint64(203, true),
+        revokedCount: v.getBigUint64(211, true),
+        bump: data[219],
+        uri: TD.decode(data.slice(224, 224 + uriLen)),
+    };
+}
+export function decodeCredentialSchema(data) {
+    if (data.length < 8 + 128 + 4 || !hasDisc(data, CREDENTIAL_SCHEMA_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const v = view(data);
+    const status = data[45];
+    if (status > 1)
+        return null;
+    const nameLen = data[86];
+    if (nameLen > 32)
+        return null;
+    const uriLen = v.getUint32(128, true);
+    if (uriLen > CRED_URI_MAX_LEN || data.length < 132 + uriLen)
+        return null;
+    return {
+        version: data[8],
+        issuer: b58(data, 9),
+        schemaId: v.getUint32(41, true),
+        status: status === 0 ? "active" : "deprecated",
+        maxValiditySecs: v.getBigInt64(46, true),
+        name: TD.decode(data.slice(54, 54 + nameLen)),
+        contentHash: data.slice(87, 119),
+        createdAt: v.getBigInt64(119, true),
+        bump: data[127],
+        uri: TD.decode(data.slice(132, 132 + uriLen)),
+    };
+}
+export function decodeCredential(data) {
+    if (data.length < CREDENTIAL_ACCOUNT_LEN || !hasDisc(data, CREDENTIAL_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const v = view(data);
+    return {
+        version: data[8],
+        issuer: b58(data, 9),
+        handle: b58(data, 41),
+        schemaId: v.getUint32(73, true),
+        subject: b58(data, 77),
+        evidenceHash: data.slice(109, 141),
+        claimHash: data.slice(141, 173),
+        issuedAt: v.getBigInt64(173, true),
+        expiresAt: v.getBigInt64(181, true),
+        rentPayer: b58(data, 189),
+        bump: data[221],
+    };
+}
+export function decodeCredConfig(data) {
+    if (data.length < CRED_CONFIG_ACCOUNT_LEN || !hasDisc(data, CRED_CONFIG_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const v = view(data);
+    return {
+        issuerFeeLamports: v.getBigUint64(9, true),
+        credentialFeeLamports: v.getBigUint64(17, true),
+        updatedAt: v.getBigInt64(25, true),
+    };
+}
+export function decodeRecommendedIssuers(data) {
+    if (data.length < 8 + 1 + 4 || !hasDisc(data, RECOMMENDED_ISSUERS_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const v = view(data);
+    const n = v.getUint32(9, true);
+    if (n > MAX_RECOMMENDED_ISSUERS || data.length < 13 + 32 * n + 8)
+        return null;
+    const issuers = [];
+    for (let i = 0; i < n; i++)
+        issuers.push(b58(data, 13 + 32 * i));
+    return { issuers, updatedAt: v.getBigInt64(13 + 32 * n, true) };
+}
+/**
+ * Whether `cred` counts for the handle's CURRENT holder at `nowSecs` — the
+ * same checks `assert_credential` makes. `records_cleared_at` deliberately
+ * plays no part (owner decision Q6). Pass `acceptedIssuers` / `schemaId` /
+ * `minRemainingSecs` to apply a gate's terms as well.
+ */
+export function credentialValidity(cred, issuer, ctx, nowSecs, terms = {}) {
+    const now = BigInt(nowSecs);
+    const reasons = [];
+    if (ctx.handle === null)
+        reasons.push("released");
+    else if (ctx.handle !== cred.handle)
+        reasons.push("wrong_handle");
+    if (terms.schemaId !== undefined && terms.schemaId !== cred.schemaId)
+        reasons.push("wrong_schema");
+    if (terms.acceptedIssuers !== undefined && !terms.acceptedIssuers.includes(cred.issuer))
+        reasons.push("issuer_not_accepted");
+    const min = BigInt(terms.minRemainingSecs ?? 0);
+    if (cred.expiresAt !== 0n) {
+        if (now >= cred.expiresAt)
+            reasons.push("expired");
+        else if (min < 0n || now + min >= cred.expiresAt)
+            reasons.push("insufficient_headroom");
+    }
+    else if (min < 0n)
+        reasons.push("insufficient_headroom");
+    if (issuer.status === "retired")
+        reasons.push("issuer_retired");
+    if (cred.issuedAt < issuer.invalidateBefore)
+        reasons.push("invalidated");
+    if (ctx.handle !== null && !(cred.issuedAt >= ctx.registeredAt && (ctx.holderEpoch === 0n || cred.issuedAt > ctx.holderEpoch))) {
+        reasons.push("epoch");
+    }
+    if (ctx.currentHolder === null)
+        reasons.push("holder_unknown");
+    else if (ctx.currentHolder !== cred.subject)
+        reasons.push("holder_mismatch");
+    return { valid: reasons.length === 0, reasons };
+}
+/**
+ * Whether an issuer's `linkedHandle` still proves "this issuer is @name":
+ * the link was made in the handle's current ownership epoch and the wallet
+ * that co-signed it is still the handle's current authority.
+ */
+export function issuerLinkValid(issuer, ctx) {
+    if (!issuer.linkedHandle || ctx.handle !== issuer.linkedHandle)
+        return false;
+    if (!(issuer.linkedAt >= ctx.registeredAt && (ctx.holderEpoch === 0n || issuer.linkedAt > ctx.holderEpoch)))
+        return false;
+    return ctx.currentHolder !== null && ctx.currentHolder === issuer.linkedBy;
+}
+/** Decode the 52-byte `set_return_data` of a passing `assert_credential`. */
+export function decodeAssertCredentialReturn(data) {
+    if (data.length !== 52)
+        return null;
+    const v = view(data);
+    return { issuer: b58(data, 0), schemaId: v.getUint32(32, true), issuedAt: v.getBigInt64(36, true), expiresAt: v.getBigInt64(44, true) };
+}
+// ---------------------------------------------------------------------------
+// chain reads
+// ---------------------------------------------------------------------------
+function b64ToBytes(s) {
+    const bin = atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Fetch raw data for several accounts in one `getMultipleAccounts` (null
+ *  for a missing account, or one not owned by `programId`). */
+export async function fetchProgramAccountsData(rpc, programId, addresses, commitment = "confirmed") {
+    if (addresses.length === 0)
+        return [];
+    const owner = toBase58(programId, "programId");
+    const out = [];
+    for (let i = 0; i < addresses.length; i += 100) {
+        const chunk = addresses.slice(i, i + 100);
+        const res = (await rpc("getMultipleAccounts", [chunk, { encoding: "base64", commitment }]));
+        const vals = res?.value ?? [];
+        for (let j = 0; j < chunk.length; j++) {
+            const v = vals[j];
+            out.push(v && v.owner === owner ? b64ToBytes(v.data[0]) : null);
+        }
+    }
+    return out;
+}
+/** Read the advisory recommended-issuer list (empty if never written). */
+export async function fetchRecommendedIssuers(rpc, find, programId) {
+    const addr = await findRecommendedIssuersPda(find, programId);
+    const [raw] = await fetchProgramAccountsData(rpc, programId, [addr]);
+    return raw ? (decodeRecommendedIssuers(raw)?.issuers ?? []) : [];
+}
+/**
+ * Fetch the credentials `handle` holds for `schemaId` from each of `issuers`
+ * (PDAs derived, one `getMultipleAccounts`), with each one's validity for
+ * `ctx` at `nowSecs`. Missing credentials are omitted.
+ */
+export async function fetchHandleCredentials(rpc, find, programId, ctx, schemaId, issuers, nowSecs, minRemainingSecs = 0) {
+    const credAddrs = await Promise.all(issuers.map((i) => findCredentialPda(find, programId, i, ctx.handle, schemaId)));
+    const raws = await fetchProgramAccountsData(rpc, programId, [...credAddrs, ...issuers]);
+    const out = [];
+    for (let i = 0; i < issuers.length; i++) {
+        const raw = raws[i];
+        const credential = raw ? decodeCredential(raw) : null;
+        if (!credential)
+            continue;
+        const iraw = raws[issuers.length + i];
+        const issuer = iraw ? decodeIssuer(iraw) : null;
+        const validity = issuer
+            ? credentialValidity(credential, issuer, ctx, nowSecs, { acceptedIssuers: issuers, schemaId, minRemainingSecs })
+            : { valid: false, reasons: ["issuer_not_accepted"] };
+        out.push({ address: credAddrs[i], credential, issuer, validity });
+    }
+    return out;
+}
+/** `register_issuer(name, uri, uri_hash)`. */
+export function buildRegisterIssuerIx(p) {
+    if (!isValidCredentialName(p.name, true))
+        throw new Error("invalid issuer name");
+    if (isReservedIssuerName(p.name))
+        throw new Error("issuer names may not contain 'x1id'");
+    if (TE.encode(p.uri).length > CRED_URI_MAX_LEN)
+        throw new Error("uri is longer than 200 bytes");
+    return ix(p.programId, [
+        key(p.payer, "payer", true, true),
+        key(p.authority, "authority", true, false),
+        key(p.config, "config", false, false),
+        key(p.credConfig, "credConfig", false, false),
+        key(p.treasury, "treasury", false, true),
+        key(p.issuer, "issuer", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ], concat(REGISTER_ISSUER_DISCRIMINATOR, encString(p.name), encString(p.uri), hash32(p.uriHash, "uriHash")));
+}
+/** `update_issuer(uri?, uri_hash?, status?, invalidate_before?)`. Available
+ *  during a lockdown (retiring a compromised key always works). */
+export function buildUpdateIssuerIx(p) {
+    if (p.uri !== undefined && TE.encode(p.uri).length > CRED_URI_MAX_LEN)
+        throw new Error("uri is longer than 200 bytes");
+    const status = p.status === undefined ? undefined : Uint8Array.of(ISSUER_STATUS[p.status === "active" ? "Active" : p.status === "paused" ? "Paused" : "Retired"]);
+    return ix(p.programId, [key(p.authority, "authority", true, false), key(p.issuer, "issuer", false, true)], concat(UPDATE_ISSUER_DISCRIMINATOR, opt(p.uri === undefined ? undefined : encString(p.uri)), opt(p.uriHash === undefined ? undefined : hash32(p.uriHash, "uriHash")), opt(status), opt(p.invalidateBefore === undefined ? undefined : i64le(p.invalidateBefore, "invalidateBefore"))));
+}
+/** `link_issuer_handle()`: the issuer proves it is `@name`. */
+export function buildLinkIssuerHandleIx(p) {
+    return ix(p.programId, [
+        key(p.authority, "authority", true, false),
+        key(p.handleAuthority, "handleAuthority", true, false),
+        key(p.issuer, "issuer", false, true),
+        key(p.handle, "handle", false, false),
+        ...tailKeys(p),
+    ], LINK_ISSUER_HANDLE_DISCRIMINATOR.slice());
+}
+/** `unlink_issuer_handle()`. */
+export function buildUnlinkIssuerHandleIx(p) {
+    return ix(p.programId, [key(p.authority, "authority", true, false), key(p.issuer, "issuer", false, true)], UNLINK_ISSUER_HANDLE_DISCRIMINATOR.slice());
+}
+/** `create_schema(schema_id, name, uri, content_hash, max_validity_secs)`. */
+export function buildCreateSchemaIx(p) {
+    if (!isValidCredentialName(p.name, false))
+        throw new Error("invalid schema name");
+    const uri = p.uri ?? "";
+    if (TE.encode(uri).length > CRED_URI_MAX_LEN)
+        throw new Error("uri is longer than 200 bytes");
+    if (p.maxValiditySecs < 0n || p.maxValiditySecs > MAX_CREDENTIAL_VALIDITY_SECS)
+        throw new Error("maxValiditySecs must be 0..10 years");
+    return ix(p.programId, [
+        key(p.payer, "payer", true, true),
+        key(p.authority, "authority", true, false),
+        key(p.config, "config", false, false),
+        key(p.issuer, "issuer", false, false),
+        key(p.schema, "schema", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ], concat(CREATE_SCHEMA_DISCRIMINATOR, u32le(p.schemaId, "schemaId"), encString(p.name), encString(uri), hash32(p.contentHash, "contentHash"), i64le(p.maxValiditySecs, "maxValiditySecs")));
+}
+/** `deprecate_schema(schema_id)`: Active -> Deprecated, one way. */
+export function buildDeprecateSchemaIx(p) {
+    return ix(p.programId, [key(p.authority, "authority", true, false), key(p.issuer, "issuer", false, false), key(p.schema, "schema", false, true)], concat(DEPRECATE_SCHEMA_DISCRIMINATOR, u32le(p.schemaId, "schemaId")));
+}
+/** `issue_credential(schema_id, evidence_hash, claim_hash, expires_at)` —
+ *  a three-signer transaction (payer, issuer authority, holder). */
+export function buildIssueCredentialIx(p) {
+    return ix(p.programId, [
+        key(p.payer, "payer", true, true),
+        key(p.authority, "authority", true, false),
+        key(p.subject, "subject", true, false),
+        key(p.config, "config", false, false),
+        key(p.credConfig, "credConfig", false, false),
+        key(p.treasury, "treasury", false, true),
+        key(p.issuer, "issuer", false, true),
+        key(p.schema, "schema", false, false),
+        key(p.handle, "handle", false, false),
+        key(p.credential, "credential", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ...tailKeys(p),
+    ], concat(ISSUE_CREDENTIAL_DISCRIMINATOR, u32le(p.schemaId, "schemaId"), hash32(p.evidenceHash, "evidenceHash"), hash32(p.claimHash, "claimHash"), i64le(p.expiresAt, "expiresAt")));
+}
+/** `renew_credential(expires_at, evidence_hash?)` — issuer only; only while
+ *  the credential still counts for its subject. */
+export function buildRenewCredentialIx(p) {
+    return ix(p.programId, [
+        key(p.authority, "authority", true, false),
+        key(p.config, "config", false, false),
+        key(p.issuer, "issuer", false, false),
+        key(p.handle, "handle", false, false),
+        key(p.credential, "credential", false, true),
+        key(p.schema, "schema", false, false),
+        ...tailKeys(p),
+    ], concat(RENEW_CREDENTIAL_DISCRIMINATOR, i64le(p.expiresAt, "expiresAt"), opt(p.evidenceHash === undefined ? undefined : hash32(p.evidenceHash, "evidenceHash"))));
+}
+/** `revoke_credential()` — issuer only; rent to `rentPayer`. */
+export function buildRevokeCredentialIx(p) {
+    return ix(p.programId, [
+        key(p.authority, "authority", true, false),
+        key(p.issuer, "issuer", false, true),
+        key(p.credential, "credential", false, true),
+        key(p.rentPayer, "rentPayer", false, true),
+    ], REVOKE_CREDENTIAL_DISCRIMINATOR.slice());
+}
+/** `close_credential()` — anyone (no signer), for a credential that can never
+ *  count again; rent to `rentPayer`, never to the caller. */
+export function buildCloseCredentialIx(p) {
+    return ix(p.programId, [
+        key(p.credential, "credential", false, true),
+        key(p.rentPayer, "rentPayer", false, true),
+        key(p.issuer, "issuer", false, false),
+        key(p.handle, "handle", false, false),
+    ], CLOSE_CREDENTIAL_DISCRIMINATOR.slice());
+}
+/** `assert_credential(schema_id, accepted_issuers, min_remaining_secs)` —
+ *  the side-effect-free gate; compose it before your gated instruction. */
+export function buildAssertCredentialIx(p) {
+    if (p.acceptedIssuers.length < 1 || p.acceptedIssuers.length > MAX_ACCEPTED_ISSUERS) {
+        throw new Error("acceptedIssuers must have 1 to 8 entries");
+    }
+    const min = p.minRemainingSecs ?? 0n;
+    if (min < 0n)
+        throw new Error("minRemainingSecs must be >= 0");
+    return ix(p.programId, [
+        key(p.caller, "caller", true, false),
+        key(p.handle, "handle", false, false),
+        key(p.credential, "credential", false, false),
+        key(p.issuer, "issuer", false, false),
+        ...tailKeys(p),
+    ], concat(ASSERT_CREDENTIAL_DISCRIMINATOR, u32le(p.schemaId, "schemaId"), u32le(p.acceptedIssuers.length, "acceptedIssuers length"), ...p.acceptedIssuers.map((a, i) => toBytes32(a, `acceptedIssuers[${i}]`)), i64le(min, "minRemainingSecs")));
+}
+/** `set_credential_config(issuer_fee, credential_fee)` — `Config.admin`. */
+export function buildSetCredentialConfigIx(p) {
+    if (p.issuerFeeLamports > ISSUER_FEE_MAX_LAMPORTS || p.credentialFeeLamports > CREDENTIAL_FEE_MAX_LAMPORTS) {
+        throw new Error("fee above the program cap");
+    }
+    return ix(p.programId, [
+        key(p.admin, "admin", true, true),
+        key(p.config, "config", false, false),
+        key(p.credConfig, "credConfig", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ], concat(SET_CREDENTIAL_CONFIG_DISCRIMINATOR, u64le(p.issuerFeeLamports, "issuerFee"), u64le(p.credentialFeeLamports, "credentialFee")));
+}
+/** `set_recommended_issuers(issuers)` — `Config.admin`; each listed Issuer
+ *  account rides along read-only, in list order. */
+export function buildSetRecommendedIssuersIx(p) {
+    if (p.issuers.length > MAX_RECOMMENDED_ISSUERS)
+        throw new Error("at most 32 recommended issuers");
+    return ix(p.programId, [
+        key(p.admin, "admin", true, true),
+        key(p.config, "config", false, false),
+        key(p.recommended, "recommended", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ...p.issuers.map((a, i) => key(a, `issuers[${i}]`, false, false)),
+    ], concat(SET_RECOMMENDED_ISSUERS_DISCRIMINATOR, u32le(p.issuers.length, "issuers length"), ...p.issuers.map((a, i) => toBytes32(a, `issuers[${i}]`))));
+}