@x1id/resolve 0.23.0 → 0.44.0

package/dist/credentials.d.ts

@@ -0,0 +1,466 @@
+/**
+ * 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 type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+import type { PdaFinder } from "./namespacePricing.js";
+export declare const ISSUER_SEED = "issuer";
+export declare const CRED_SCHEMA_SEED = "cred_schema";
+export declare const CREDENTIAL_SEED = "credential";
+export declare const CRED_CONFIG_SEED = "cred_config";
+export declare const RECOMMENDED_ISSUERS_SEED = "recommended_issuers";
+/** Allocated sizes (8-byte discriminator + `INIT_SPACE`). */
+export declare const ISSUER_ACCOUNT_LEN: number;
+export declare const CREDENTIAL_SCHEMA_ACCOUNT_LEN: number;
+export declare const CREDENTIAL_ACCOUNT_LEN: number;
+export declare const CRED_CONFIG_ACCOUNT_LEN: number;
+export declare const RECOMMENDED_ISSUERS_ACCOUNT_LEN: number;
+/** Registration fee while the admin never set one: 1 XNT. */
+export declare const DEFAULT_ISSUER_FEE_LAMPORTS = 1000000000n;
+/** Program caps on the admin-set fees: 100 XNT and 0.1 XNT. */
+export declare const ISSUER_FEE_MAX_LAMPORTS = 100000000000n;
+export declare const CREDENTIAL_FEE_MAX_LAMPORTS = 100000000n;
+/** No credential may be valid for more than 10 years (3653 days). */
+export declare const MAX_CREDENTIAL_VALIDITY_SECS: bigint;
+export declare const CRED_URI_MAX_LEN = 200;
+/** `assert_credential` accepts 1..=8 issuers. */
+export declare const MAX_ACCEPTED_ISSUERS = 8;
+export declare const MAX_RECOMMENDED_ISSUERS = 32;
+export declare const ISSUER_STATUS: {
+    readonly Active: 0;
+    readonly Paused: 1;
+    readonly Retired: 2;
+};
+export declare const SCHEMA_STATUS: {
+    readonly Active: 0;
+    readonly Deprecated: 1;
+};
+/** Compute-unit limits to request (measured in tests/credentials.rs, with
+ *  headroom; spec §12). */
+export declare const CREDENTIAL_CU_LIMITS: {
+    readonly registerIssuer: 60000;
+    readonly createSchema: 50000;
+    readonly issueCredential: 100000;
+    readonly renewCredential: 80000;
+    readonly revokeCredential: 50000;
+    readonly closeCredential: 50000;
+    readonly assertCredential: 80000;
+};
+export declare const REGISTER_ISSUER_DISCRIMINATOR: Uint8Array;
+export declare const UPDATE_ISSUER_DISCRIMINATOR: Uint8Array;
+export declare const LINK_ISSUER_HANDLE_DISCRIMINATOR: Uint8Array;
+export declare const UNLINK_ISSUER_HANDLE_DISCRIMINATOR: Uint8Array;
+export declare const CREATE_SCHEMA_DISCRIMINATOR: Uint8Array;
+export declare const DEPRECATE_SCHEMA_DISCRIMINATOR: Uint8Array;
+export declare const ISSUE_CREDENTIAL_DISCRIMINATOR: Uint8Array;
+export declare const RENEW_CREDENTIAL_DISCRIMINATOR: Uint8Array;
+export declare const REVOKE_CREDENTIAL_DISCRIMINATOR: Uint8Array;
+export declare const CLOSE_CREDENTIAL_DISCRIMINATOR: Uint8Array;
+export declare const ASSERT_CREDENTIAL_DISCRIMINATOR: Uint8Array;
+export declare const SET_CREDENTIAL_CONFIG_DISCRIMINATOR: Uint8Array;
+export declare const SET_RECOMMENDED_ISSUERS_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:<Name>")[..8]`. */
+export declare const ISSUER_ACCOUNT_DISCRIMINATOR: Uint8Array;
+export declare const CREDENTIAL_SCHEMA_ACCOUNT_DISCRIMINATOR: Uint8Array;
+export declare const CREDENTIAL_ACCOUNT_DISCRIMINATOR: Uint8Array;
+export declare const CRED_CONFIG_ACCOUNT_DISCRIMINATOR: Uint8Array;
+export declare const RECOMMENDED_ISSUERS_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** Byte offsets for `getProgramAccounts` `memcmp` filters. */
+export declare const ISSUER_OFFSETS: {
+    readonly authority: 9;
+    readonly status: 41;
+    readonly invalidateBefore: 42;
+    readonly name: 50;
+    readonly linkedHandle: 115;
+    readonly linkedBy: 147;
+};
+export declare const CREDENTIAL_SCHEMA_OFFSETS: {
+    readonly issuer: 9;
+    readonly schemaId: 41;
+    readonly status: 45;
+};
+export declare const CREDENTIAL_OFFSETS: {
+    readonly issuer: 9;
+    readonly handle: 41;
+    readonly schemaId: 73;
+    readonly subject: 77;
+    readonly rentPayer: 189;
+};
+/** Program error codes of the credentials block (fixed range 6158-6189;
+ *  6181-6189 are reserved placeholders). */
+export declare const CREDENTIAL_ERRORS: {
+    readonly IssuerNameInvalid: 6158;
+    readonly IssuerNameReserved: 6159;
+    readonly IssuerUriTooLong: 6160;
+    readonly IssuerNotActive: 6161;
+    readonly IssuerRetired: 6162;
+    readonly NotIssuerAuthority: 6163;
+    readonly InvalidateBeforeInvalid: 6164;
+    readonly IssuerStatusInvalid: 6165;
+    readonly SchemaNameInvalid: 6166;
+    readonly SchemaNotActive: 6167;
+    readonly SchemaIssuerMismatch: 6168;
+    readonly SchemaValidityInvalid: 6169;
+    readonly CredentialExpiryInvalid: 6170;
+    readonly CredentialExpiryRequired: 6171;
+    readonly CredentialSubjectNotAuthority: 6172;
+    readonly CredentialNotRenewable: 6173;
+    readonly CredentialStillValid: 6174;
+    readonly CredentialIssuerSetInvalid: 6175;
+    readonly CredentialGateNotSatisfied: 6176;
+    readonly CredentialFeeAboveCap: 6177;
+    readonly RecommendedListInvalid: 6178;
+    readonly IssuerHandleLinkInvalid: 6179;
+    readonly CredConfigMismatch: 6180;
+};
+/** Human message for a credentials error code, or null for another code. */
+export declare function credentialErrorMessage(code: number): string | null;
+/** 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 declare function isValidCredentialName(name: string, allowSpace?: boolean): boolean;
+/** Owner decision Q7: issuer names may not contain `x1id`, also split by
+ *  separators. */
+export declare function isReservedIssuerName(name: string): boolean;
+/** `["issuer", authority]`. */
+export declare function findIssuerPda(find: PdaFinder, programId: AddressLike, authority: AddressLike): Promise<string>;
+/** `["cred_schema", issuer, schema_id u32 LE]`. */
+export declare function findCredentialSchemaPda(find: PdaFinder, programId: AddressLike, issuer: AddressLike, schemaId: number): Promise<string>;
+/** `["credential", issuer, handle, schema_id u32 LE]`. */
+export declare function findCredentialPda(find: PdaFinder, programId: AddressLike, issuer: AddressLike, handle: AddressLike, schemaId: number): Promise<string>;
+/** `["cred_config"]`. */
+export declare function findCredConfigPda(find: PdaFinder, programId: AddressLike): Promise<string>;
+/** `["recommended_issuers"]`. */
+export declare function findRecommendedIssuersPda(find: PdaFinder, programId: AddressLike): Promise<string>;
+export interface Issuer {
+    readonly version: number;
+    readonly authority: string;
+    readonly status: "active" | "paused" | "retired";
+    readonly invalidateBefore: bigint;
+    /** Display label only. Never trust it: identity is `authority`. */
+    readonly name: string;
+    readonly uriHash: Uint8Array;
+    /** The linked X1ID `Handle` PDA, or null. Check {@link issuerLinkValid}. */
+    readonly linkedHandle: string | null;
+    readonly linkedBy: string | null;
+    readonly linkedAt: bigint;
+    readonly createdAt: bigint;
+    readonly feePaid: bigint;
+    readonly issuedCount: bigint;
+    readonly revokedCount: bigint;
+    readonly bump: number;
+    readonly uri: string;
+}
+/** Decode a raw `Issuer` (discriminator included); null if it is not one. */
+export declare function decodeIssuer(data: Uint8Array): Issuer | null;
+export interface CredentialSchema {
+    readonly version: number;
+    readonly issuer: string;
+    readonly schemaId: number;
+    readonly status: "active" | "deprecated";
+    /** 0n = credentials may be no-expiry. */
+    readonly maxValiditySecs: bigint;
+    readonly name: string;
+    readonly contentHash: Uint8Array;
+    readonly createdAt: bigint;
+    readonly bump: number;
+    readonly uri: string;
+}
+export declare function decodeCredentialSchema(data: Uint8Array): CredentialSchema | null;
+export interface Credential {
+    readonly version: number;
+    /** The `Issuer` PDA. */
+    readonly issuer: string;
+    /** The `Handle` PDA. */
+    readonly handle: string;
+    readonly schemaId: number;
+    /** The holder it was issued to (co-signed). */
+    readonly subject: string;
+    readonly evidenceHash: Uint8Array;
+    readonly claimHash: Uint8Array;
+    readonly issuedAt: bigint;
+    /** 0n = no expiry. */
+    readonly expiresAt: bigint;
+    readonly rentPayer: string;
+    readonly bump: number;
+}
+export declare function decodeCredential(data: Uint8Array): Credential | null;
+export interface CredConfig {
+    readonly issuerFeeLamports: bigint;
+    readonly credentialFeeLamports: bigint;
+    readonly updatedAt: bigint;
+}
+export declare function decodeCredConfig(data: Uint8Array): CredConfig | null;
+export interface RecommendedIssuers {
+    /** Issuer PDAs, base58. ADVISORY: the program never reads this list. */
+    readonly issuers: readonly string[];
+    readonly updatedAt: bigint;
+}
+export declare function decodeRecommendedIssuers(data: Uint8Array): RecommendedIssuers | null;
+/** What a reader knows about the handle right now. */
+export interface CredentialHandleContext {
+    /** The `Handle` PDA (base58); null/undefined if it no longer exists. */
+    readonly handle: string | null;
+    readonly registeredAt: bigint;
+    /** H5 `holder_epoch` (0n if absent). */
+    readonly holderEpoch: bigint;
+    /** The CURRENT authority: `Handle.owner` while untokenized, the pNFT
+     *  holder once tokenized. Null if unknown (the holder check then fails). */
+    readonly currentHolder: string | null;
+}
+export type CredentialInvalidReason = "released" | "expired" | "insufficient_headroom" | "issuer_retired" | "invalidated" | "epoch" | "holder_mismatch" | "holder_unknown" | "issuer_not_accepted" | "wrong_handle" | "wrong_schema";
+export interface CredentialValidity {
+    readonly valid: boolean;
+    readonly reasons: readonly CredentialInvalidReason[];
+}
+/**
+ * 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 declare function credentialValidity(cred: Credential, issuer: Pick<Issuer, "status" | "invalidateBefore">, ctx: CredentialHandleContext, nowSecs: bigint | number, terms?: {
+    readonly acceptedIssuers?: readonly string[];
+    readonly schemaId?: number;
+    readonly minRemainingSecs?: bigint | number;
+}): CredentialValidity;
+/**
+ * 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 declare function issuerLinkValid(issuer: Pick<Issuer, "linkedHandle" | "linkedBy" | "linkedAt">, ctx: CredentialHandleContext): boolean;
+/** Decode the 52-byte `set_return_data` of a passing `assert_credential`. */
+export declare function decodeAssertCredentialReturn(data: Uint8Array): {
+    readonly issuer: string;
+    readonly schemaId: number;
+    readonly issuedAt: bigint;
+    readonly expiresAt: bigint;
+} | null;
+/** Fetch raw data for several accounts in one `getMultipleAccounts` (null
+ *  for a missing account, or one not owned by `programId`). */
+export declare function fetchProgramAccountsData(rpc: RpcFn, programId: AddressLike, addresses: readonly string[], commitment?: string): Promise<(Uint8Array | null)[]>;
+/** Read the advisory recommended-issuer list (empty if never written). */
+export declare function fetchRecommendedIssuers(rpc: RpcFn, find: PdaFinder, programId: AddressLike): Promise<readonly string[]>;
+/** One credential a handle holds from one issuer for one schema, with its
+ *  issuer and validity. */
+export interface HandleCredential {
+    readonly address: string;
+    readonly credential: Credential;
+    readonly issuer: Issuer | null;
+    readonly validity: CredentialValidity;
+}
+/**
+ * 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 declare function fetchHandleCredentials(rpc: RpcFn, find: PdaFinder, programId: AddressLike, ctx: CredentialHandleContext & {
+    readonly handle: string;
+}, schemaId: number, issuers: readonly string[], nowSecs: bigint | number, minRemainingSecs?: bigint | number): Promise<HandleCredential[]>;
+interface Common {
+    readonly programId: AddressLike;
+}
+export interface RegisterIssuerParams extends Common {
+    /** Signer, writable: pays the fee + rent. */
+    readonly payer: AddressLike;
+    /** Signer: the issuer's identity key. */
+    readonly authority: AddressLike;
+    readonly config: AddressLike;
+    /** {@link findCredConfigPda} (initialized or not). */
+    readonly credConfig: AddressLike;
+    /** `Config.treasury`. */
+    readonly treasury: AddressLike;
+    /** {@link findIssuerPda}(authority). */
+    readonly issuer: AddressLike;
+    readonly name: string;
+    readonly uri: string;
+    readonly uriHash?: Uint8Array;
+}
+/** `register_issuer(name, uri, uri_hash)`. */
+export declare function buildRegisterIssuerIx(p: RegisterIssuerParams): BuiltInstruction;
+export interface UpdateIssuerParams extends Common {
+    readonly authority: AddressLike;
+    readonly issuer: AddressLike;
+    readonly uri?: string;
+    readonly uriHash?: Uint8Array;
+    /** Active <-> Paused, or Retired (TERMINAL: every credential stops counting). */
+    readonly status?: "active" | "paused" | "retired";
+    /** Mass revocation cut-off (unix seconds, never lower than stored, <= now). */
+    readonly invalidateBefore?: bigint;
+}
+/** `update_issuer(uri?, uri_hash?, status?, invalidate_before?)`. Available
+ *  during a lockdown (retiring a compromised key always works). */
+export declare function buildUpdateIssuerIx(p: UpdateIssuerParams): BuiltInstruction;
+export interface LinkIssuerHandleParams extends Common {
+    readonly authority: AddressLike;
+    /** Signer: the handle's current authority (owner, or pNFT holder). */
+    readonly handleAuthority: AddressLike;
+    readonly issuer: AddressLike;
+    readonly handle: AddressLike;
+    /** Tokenized name: `handleAuthority`'s ATA for the pNFT mint. */
+    readonly holderAta?: AddressLike;
+    /** Scoped `name.tld`: the `["namespace", label]` account. */
+    readonly namespace?: AddressLike;
+}
+/** `link_issuer_handle()`: the issuer proves it is `@name`. */
+export declare function buildLinkIssuerHandleIx(p: LinkIssuerHandleParams): BuiltInstruction;
+/** `unlink_issuer_handle()`. */
+export declare function buildUnlinkIssuerHandleIx(p: Common & {
+    readonly authority: AddressLike;
+    readonly issuer: AddressLike;
+}): BuiltInstruction;
+export interface CreateSchemaParams extends Common {
+    readonly payer: AddressLike;
+    readonly authority: AddressLike;
+    readonly config: AddressLike;
+    readonly issuer: AddressLike;
+    /** {@link findCredentialSchemaPda}(issuer, schemaId). */
+    readonly schema: AddressLike;
+    readonly schemaId: number;
+    readonly name: string;
+    readonly uri?: string;
+    readonly contentHash?: Uint8Array;
+    /** 0n = credentials may be no-expiry; at most 10 years. IMMUTABLE. */
+    readonly maxValiditySecs: bigint;
+}
+/** `create_schema(schema_id, name, uri, content_hash, max_validity_secs)`. */
+export declare function buildCreateSchemaIx(p: CreateSchemaParams): BuiltInstruction;
+/** `deprecate_schema(schema_id)`: Active -> Deprecated, one way. */
+export declare function buildDeprecateSchemaIx(p: Common & {
+    readonly authority: AddressLike;
+    readonly issuer: AddressLike;
+    readonly schema: AddressLike;
+    readonly schemaId: number;
+}): BuiltInstruction;
+export interface IssueCredentialParams extends Common {
+    /** Signer, writable: rent (+ the optional credential fee). Recorded as
+     *  `rent_payer` on first issue. */
+    readonly payer: AddressLike;
+    /** Signer: the issuer authority. */
+    readonly authority: AddressLike;
+    /** Signer: the handle's CURRENT authority (owner decision Q1). */
+    readonly subject: AddressLike;
+    readonly config: AddressLike;
+    readonly credConfig: AddressLike;
+    readonly treasury: AddressLike;
+    readonly issuer: AddressLike;
+    readonly schema: AddressLike;
+    readonly handle: AddressLike;
+    /** {@link findCredentialPda}(issuer, handle, schemaId). */
+    readonly credential: AddressLike;
+    readonly schemaId: number;
+    readonly evidenceHash: Uint8Array;
+    /** sha256(salt ‖ canonical claim); omit for none. */
+    readonly claimHash?: Uint8Array;
+    /** 0n = no expiry (only when the schema allows it). */
+    readonly expiresAt: bigint;
+    /** Tokenized name: the subject's ATA for the pNFT mint (FIRST). */
+    readonly holderAta?: AddressLike;
+    /** Scoped `name.tld`: the namespace (after the ATA). */
+    readonly namespace?: AddressLike;
+}
+/** `issue_credential(schema_id, evidence_hash, claim_hash, expires_at)` —
+ *  a three-signer transaction (payer, issuer authority, holder). */
+export declare function buildIssueCredentialIx(p: IssueCredentialParams): BuiltInstruction;
+export interface RenewCredentialParams extends Common {
+    readonly authority: AddressLike;
+    readonly config: AddressLike;
+    readonly issuer: AddressLike;
+    readonly handle: AddressLike;
+    readonly credential: AddressLike;
+    readonly schema: AddressLike;
+    readonly expiresAt: bigint;
+    readonly evidenceHash?: Uint8Array;
+    /** Tokenized name: the STORED subject's ATA. */
+    readonly holderAta?: AddressLike;
+    readonly namespace?: AddressLike;
+}
+/** `renew_credential(expires_at, evidence_hash?)` — issuer only; only while
+ *  the credential still counts for its subject. */
+export declare function buildRenewCredentialIx(p: RenewCredentialParams): BuiltInstruction;
+/** `revoke_credential()` — issuer only; rent to `rentPayer`. */
+export declare function buildRevokeCredentialIx(p: Common & {
+    readonly authority: AddressLike;
+    readonly issuer: AddressLike;
+    readonly credential: AddressLike;
+    readonly rentPayer: AddressLike;
+}): BuiltInstruction;
+/** `close_credential()` — anyone (no signer), for a credential that can never
+ *  count again; rent to `rentPayer`, never to the caller. */
+export declare function buildCloseCredentialIx(p: Common & {
+    readonly credential: AddressLike;
+    readonly rentPayer: AddressLike;
+    readonly issuer: AddressLike;
+    readonly handle: AddressLike;
+}): BuiltInstruction;
+export interface AssertCredentialParams extends Common {
+    /** Signer: must be the handle's current authority and the credential's subject. */
+    readonly caller: AddressLike;
+    readonly handle: AddressLike;
+    readonly credential: AddressLike;
+    readonly issuer: AddressLike;
+    readonly schemaId: number;
+    /** 1-8 Issuer PDAs. YOUR constant set: never the end user's input. */
+    readonly acceptedIssuers: readonly AddressLike[];
+    readonly minRemainingSecs?: bigint;
+    readonly holderAta?: AddressLike;
+    readonly namespace?: AddressLike;
+}
+/** `assert_credential(schema_id, accepted_issuers, min_remaining_secs)` —
+ *  the side-effect-free gate; compose it before your gated instruction. */
+export declare function buildAssertCredentialIx(p: AssertCredentialParams): BuiltInstruction;
+/** `set_credential_config(issuer_fee, credential_fee)` — `Config.admin`. */
+export declare function buildSetCredentialConfigIx(p: Common & {
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    readonly credConfig: AddressLike;
+    readonly issuerFeeLamports: bigint;
+    readonly credentialFeeLamports: bigint;
+}): BuiltInstruction;
+/** `set_recommended_issuers(issuers)` — `Config.admin`; each listed Issuer
+ *  account rides along read-only, in list order. */
+export declare function buildSetRecommendedIssuersIx(p: Common & {
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    readonly recommended: AddressLike;
+    readonly issuers: readonly AddressLike[];
+}): BuiltInstruction;
+export {};